1
用户授权 → GitHub 302 重定向到 http://localhost:8080/api/auth/github/callback?code=xxx&state=xxx
2
  → AuthController.githubCallback() 接收
3
  → AuthService.login() 处理
4
  → ThirdPartyAuthServiceImpl.getUserByAuthCode()
5
    1. validateState() 校验 state
6
    2. getTokenResponse() 用 code 换 access_token
7
       POST https://github.com/login/oauth/access_token
8
       Header: Authorization: Basic base64(clientId:clientSecret)
9
       Body: grant_type=authorization_code&code=xxx&redirect_uri=xxx
10
    3. GithubUserInfoStrategy.getUserInfo() 获取用户信息
11
       GET https://api.github.com/user
12
       Header: Authorization: Bearer {access_token}
13
       返回: { id: 883782250, login: "WuuMing", avatar_url: "..." }
14
    4. processLoginOrRegister() 登录或注册
15
       提取 thirdPartyId = "883782250"
16
       查询 sys_user 表 where third_party_type='github' and third_party_id='883782250'
17
       不存在则自动注册，userName = "github_883782250"
18
    5. 生成 JWT Token，写入 Cookie，302 重定向到前端

1
# zsk-auth-dev.yml (开发环境)
2
auth:
3
  github:
4
    client-id: Ov23liNgSavJA5vHz36r
5
    client-secret: your-client-secret
6
    redirect-uri: http://localhost:8080/api/auth/github/callback
7

8
# zsk-auth-prod.yml (生产环境)
9
auth:
10
  github:
11
    client-id: your-prod-client-id
12
    client-secret: your-prod-client-secret
13
    redirect-uri: https://your-domain.com/api/auth/github/callback
14

15
# zsk-gateway-dev.yml (Gateway 白名单 - 生产同理)
16
security:
17
  ignore:
18
    whites:
19
      - /api/auth/github/callback

1
用户扫码 → 微信 302 重定向到 http://your-domain.com/api/auth/wechat/callback?code=xxx&state=xxx
2
  → AuthController.wechatCallback() 接收
3
  → AuthService.login() 处理
4
  → ThirdPartyAuthServiceImpl.getUserByAuthCode()
5
    1. validateState() 校验 state
6
    2. getTokenResponse() 用 code 换 access_token
7
       GET https://api.weixin.qq.com/sns/oauth2/access_token
8
         ?appid=xxx&secret=xxx&code=xxx&grant_type=authorization_code
9
       返回: { access_token: "xxx", openid: "xxx", ... }
10
    3. WeChatUserInfoStrategy.getUserInfo() 获取用户信息
11
       GET https://api.weixin.qq.com/sns/userinfo
12
         ?access_token=xxx&openid=xxx&lang=zh_CN
13
       返回: { openid: "xxx", nickname: "微信昵称", headimgurl: "..." }
14
    4. processLoginOrRegister() 登录或注册
15
       userName = "wechat_{openid}"
16
    5. 生成 JWT Token，写入 Cookie，302 重定向到前端

1
# zsk-auth-dev.yml (开发环境)
2
auth:
3
  wechat:
4
    app-id: wx1234567890abcdef
5
    app-secret: your-app-secret
6
    redirect-uri: http://dev.your-domain.com:8080/api/auth/wechat/callback
7

8
third-party:
9
  redirect-url: http://dev.your-domain.com:3000
10

11
# zsk-auth-prod.yml (生产环境)
12
auth:
13
  wechat:
14
    app-id: your-prod-app-id
15
    app-secret: your-prod-app-secret
16
    redirect-uri: https://your-domain.com/api/auth/wechat/callback
17

18
third-party:
19
  redirect-url: https://your-domain.com
20

21
# zsk-gateway-dev.yml (Gateway 白名单 - 生产同理)
22
security:
23
  ignore:
24
    whites:
25
      - /api/auth/wechat/callback

1
用户授权 → QQ 302 重定向到 http://localhost:8080/api/auth/qq/callback?code=xxx&state=xxx
2
  → AuthController.qqCallback() 接收
3
  → AuthService.login() 处理
4
  → ThirdPartyAuthServiceImpl.getUserByAuthCode()
5
    1. validateState() 校验 state
6
    2. getTokenResponse() 用 code 换 access_token
7
       POST https://graph.qq.com/oauth2.0/token?fmt=json
8
         ?grant_type=authorization_code&code=xxx&client_id=xxx&client_secret=xxx&redirect_uri=xxx
9
       返回: { access_token: "xxx", ... }
10
    3. QQUserInfoStrategy.getUserInfo() 获取用户信息（两步）
11
       步骤 1: 调用 me 接口获取 OpenID
12
         GET https://graph.qq.com/oauth2.0/me?access_token=xxx
13
         返回: callback( {"client_id":"xxx","openid":"xxx"} );
14
         解析 JSONP 格式提取 openid
15
       步骤 2: 调用 get_user_info 接口获取用户详情
16
         GET https://graph.qq.com/user/get_user_info
17
           ?access_token=xxx&oauth_consumer_key=xxx&openid=xxx&fmt=json
18
         返回: { ret: 0, nickname: "QQ昵称", figureurl_qq_2: "头像URL", ... }
19
    4. processLoginOrRegister() 登录或注册
20
       userName = "qq_{openid}"
21
       nickName = attributes.get("nickname")
22
       avatar = attributes.get("figureurl_qq_2") (100x100 高清)
23
    5. 生成 JWT Token，写入 Cookie，302 重定向到前端

1
# zsk-auth-dev.yml (开发环境)
2
auth:
3
  qq:
4
    app-id: 100000000
5
    app-secret: your-app-secret
6
    redirect-uri: http://localhost:8080/api/auth/qq/callback
7

8
# zsk-auth-prod.yml (生产环境)
9
auth:
10
  qq:
11
    app-id: your-prod-app-id
12
    app-secret: your-prod-app-secret
13
    redirect-uri: https://your-domain.com/api/auth/qq/callback
14

15
# zsk-gateway-dev.yml (Gateway 白名单 - 生产同理)
16
security:
17
  ignore:
18
    whites:
19
      - /api/auth/qq/callback

1
# ============ 开发环境：zsk-auth-dev.yml ============
2
auth:
3
  github:
4
    client-id: Ov23liNgSavJA5vHz36r
5
    client-secret: dev-github-secret
6
    redirect-uri: http://localhost:8080/api/auth/github/callback
7
  wechat:
8
    app-id: wx1234567890abcdef
9
    app-secret: dev-wechat-secret
10
    redirect-uri: http://dev.your-domain.com:8080/api/auth/wechat/callback
11
  qq:
12
    app-id: 100000000
13
    app-secret: dev-qq-secret
14
    redirect-uri: http://localhost:8080/api/auth/qq/callback
15

16
third-party:
17
  redirect-url: http://localhost:3000
18

19
# ============ 生产环境：zsk-auth-prod.yml ============
20
auth:
21
  github:
22
    client-id: prod-github-client-id
23
    client-secret: ${GITHUB_CLIENT_SECRET}
24
    redirect-uri: https://your-domain.com/api/auth/github/callback
25
  wechat:
26
    app-id: prod-wechat-app-id
27
    app-secret: ${WECHAT_APP_SECRET}
28
    redirect-uri: https://your-domain.com/api/auth/wechat/callback
29
  qq:
30
    app-id: prod-qq-app-id
31
    app-secret: ${QQ_APP_SECRET}
32
    redirect-uri: https://your-domain.com/api/auth/qq/callback
33

34
third-party:
35
  redirect-url: https://your-domain.com

1
# ============ zsk-gateway-dev.yml 或 zsk-gateway-prod.yml ============
2
security:
3
  ignore:
4
    whites:
5
      # 第三方登录回调（免鉴权）
6
      - /api/auth/github/callback
7
      - /api/auth/wechat/callback
8
      - /api/auth/qq/callback
9
      - /api/auth/third-party/**
10
      # 其他白名单
11
      - /api/auth/login
12
      - /api/auth/register
13
      - /api/auth/captcha
14
      - /api/auth/captcha/check
15
      - /api/auth/public-key
16
      - /api/auth/email/code/**
17
      - /api/auth/magic-link/**

1
□ GitHub
2
  □ 在 GitHub Settings → Developer settings → OAuth Apps 中配置生产回调地址
3
  □ 使用生产环境的 Client ID 和 Client Secret
4
  □ Nacos prod 配置中的 redirect-uri 改为 HTTPS 域名地址
5

6
□ 微信
7
  □ 在微信开放平台配置生产授权回调域（只需域名）
8
  □ 使用生产环境的 AppID 和 AppSecret
9
  □ Nacos prod 配置中的 redirect-uri 改为 HTTPS 域名地址
10
  □ 确认域名已完成 ICP 备案
11

12
□ QQ
13
  □ 在 QQ 互联配置生产网站回调域
14
  □ 使用生产环境的 AppID 和 AppKey
15
  □ Nacos prod 配置中的 redirect-uri 改为 HTTPS 域名地址
16

17
□ Gateway
18
  □ 确认 zsk-gateway-prod.yml 中回调路由在白名单中
19
  □ 确认 Nginx 已配置 HTTPS 证书
20

21
□ 安全
22
  □ 生产环境 Secret 使用环境变量/密钥管理服务，不写死在配置中
23
  □ 生产环境全部使用 HTTPS
24
  □ 确认 Cookie 的 Secure 标志已设置（代码中已设置 cookie.setSecure(true)）
25

26
□ 前端
27
  □ 确认 third-party.redirect-url 配置为生产环境前端地址
28
  □ 前端已处理 Cookie 中的 token，能正确跳转

1
// 用户授权后，第三方平台 302 重定向到后端回调地址
2
// 后端处理完成后，302 重定向到前端首页，并设置 Cookie
3

4
// 前端页面加载时检查 Cookie
5
function getTokenFromCookie() {
6
  const match = document.cookie.match(/access_token=([^;]+)/)
7
  return match ? match[1] : null
8
}
9

10
const token = getTokenFromCookie()
11
if (token) {
12
  // 存入 localStorage
13
  localStorage.setItem('accessToken', token)
14
  // 跳转首页
15
  router.push('/dashboard')
16
}