格姗导航接入第三方登录 - QQ 图文教程！

原创

格姗知识圈

发布于 2026-08-18 23:22:54

280

文章被收录于专栏：格姗知识圈格姗知识圈

格姗导航 - 第三方登录 QQ 接入说明

1. 申请应用

1.登录QQ互联平台

https://connect.qq.com/

2.申请开发者

进入“应用管理”页面：https://connect.qq.com/manage.html#/ 如果是第一次使用，并且未进行过开发者认证，需要提交一下个人资料，待认证通过后方可创建应用。

3. 添加应用

依次点击：应用管理 -> 网站应用 -> 创建应用，应用信息提交后，等待审核通过即可

应用审核通过后如下：

copy以下三个信息：App ID、App Key和网站回调域。

重要提示
“应用密钥”可保护你应用程序的安全，因此请确保其不会泄露！也不要与任何人共享你的“应用密钥”！！！

2. 网站配置

申请通过后，登录后台管理，进入系统导航配置-登录配置，编辑 QQ，填写对应的值即可。这时就能通过 QQ 进行登录。

3. 项目依赖

如果不用了解技术，下面内容可以直接跳过。

本项目使用 JustAuth 作为第三方登录统一解决方案。

3.1 根 POM 依赖声明

文件位置：pom.xml

<!-- JustAuth 版本定义 -->
<just.auth.version>1.16.5</just.auth.version>

<!-- JustAuth 第三方登录模块 -->
<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
    <version>${just.auth.version}</version>
</dependency>

3.2 application 模块引入依赖

文件位置：geshanzsq-nav-admin/geshanzsq-nav-admin-application/pom.xml

<!-- JustAuth 第三方登录模块 -->
<dependency>
    <groupId>me.zhyd.oauth</groupId>
    <artifactId>JustAuth</artifactId>
</dependency>

4. 数据库配置

4.1 第三方登录配置表

表名：sys_third_login_config，用于存储各平台（QQ、Gitee、GitHub 等）的登录配置信息。

CREATE TABLE `sys_third_login_config` (
  `id`          bigint(20)   NOT NULL COMMENT '配置 id',
  `login_icon`  varchar(30)  DEFAULT NULL COMMENT '登录图标',
  `source`      varchar(255) DEFAULT ''  COMMENT '登录来源',
  `client_id`   varchar(255) DEFAULT ''  COMMENT '登录 id（App ID）',
  `client_secret` varchar(255) DEFAULT ''  COMMENT '登录密钥（App Key）',
  `sort`        int(11)      DEFAULT NULL COMMENT '排序',
  `status`      int(11)      DEFAULT NULL COMMENT '状态（1 正常，2 停用）',
  `fk_create_user_id` bigint(20) DEFAULT NULL COMMENT '创建人用户 id',
  `gmt_create`  datetime     DEFAULT NULL COMMENT '创建时间',
  `fk_modify_user_id` bigint(20) DEFAULT NULL COMMENT '修改人用户 id',
  `gmt_modify`  datetime     DEFAULT NULL COMMENT '修改时间',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统三方登录配置';

4.2 第三方用户表

表名：sys_third_user，用于存储第三方登录用户的关联信息。

CREATE TABLE `sys_third_user` (
  `id`          bigint(20)   NOT NULL COMMENT '系统第三方用户 id',
  `fk_user_id`  bigint(20)   DEFAULT NULL COMMENT '用户 id',
  `uuid`        varchar(255) DEFAULT NULL COMMENT '平台 uuid',
  `gmt_create`  datetime     DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `source`      varchar(20)  DEFAULT NULL COMMENT '来源',
  `username`    varchar(255) DEFAULT NULL COMMENT '第三方用户名',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='系统第三方用户';

4.3 插入 QQ 登录配置

数据已内置 QQ 配置，只需管理后台填写对应的 QQ 信息即可。如没有，可将申请到的 App ID 和 App Key 填入以下 SQL：

INSERT INTO `sys_third_login_config`
(`id`, `login_icon`, `source`, `client_id`, `client_secret`, `sort`, `status`, `fk_create_user_id`, `gmt_create`, `fk_modify_user_id`, `gmt_modify`)
VALUES
(78259887838068736, 'qq', 'QQ', '你的App ID', '你的App Key', 1, 1, 1, NOW(), 1, NOW());

说明：source 字段填写 QQ（对应枚举 SysThirdLoginConfigSource.QQ.code = "qq"） login_icon 填写 qq，对应前端 SVG 图标 status 设为 1 表示启用

5. 后端配置

5.1 通用配置

文件位置：geshanzsq-nav-admin/geshanzsq-nav-admin-application/src/main/resources/application.yml

# 第三方登录
third-login:
  # 错误地址（登录失败跳转页面）
  error-url: /500
  # 登录页面地址（携带 ticket 参数，前端凭 ticket 换取 token）
  login-url: /login?ticket=

5.2 开发环境配置

文件位置：application-dev.yml

third-login:
  # 前端网站地址
  site-url: http://localhost:8023
  # 登录回调地址（会拼接 source 参数，如 /geshanzsq-nav-api/auth/third/login/callback/qq）
  callback-url: /geshanzsq-nav-api/auth/third/login/callback/

5.3 生产环境配置

文件位置：application-prod.yml

third-login:
  site-url: https://gesdh.cn
  callback-url: /geshanzsq-nav-api/auth/third/login/callback/

5.4 安全放行配置

在 application.yml 中，需将第三方登录接口加入免登录放行列表：

security:
  not-login-urls:
    - /auth/third/login/**
    - /system/third/login/list

6. 后端核心代码说明

6.1 枚举：登录来源

文件：SysThirdLoginConfigSource.java

public enum SysThirdLoginConfigSource {
    QQ("qq"),
    GITEE("gitee"),
    GITHUB("github"),
    WE_CHAT("weChat");

    public final String code;

    SysThirdLoginConfigSource(String code) {
        this.code = code;
    }
}

6.2 配置属性类

文件：ThirdLoginProperty.java

@Data
@Configuration
@ConfigurationProperties(prefix = "third-login")
public class ThirdLoginProperty {
    private String siteUrl;      // 网站地址
    private String callbackUrl;  // 登录回调地址
    private String errorUrl;     // 错误地址
    private String loginUrl;     // 登录页面地址
}

6.3 第三方登录控制器

文件：ThirdLoginController.java

@RestController
@RequestMapping("/auth/third/login")
public class ThirdLoginController extends BaseController {

    // 获取第三方登录授权地址
    @GetMapping("/getLoginUrl/{source}")
    public ResponseResult<LoginUrlVO> getLoginUrl(@PathVariable String source) {
        LoginUrlVO loginUrlVO = authService.getLoginUrl(source);
        return ResponseResult.success(loginUrlVO);
    }

    // 第三方登录回调
    @GetMapping("/callback/{source}")
    public void callback(@PathVariable String source,
                         AuthCallback authCallback,
                         HttpServletResponse response) throws IOException {
        authService.callback(source, authCallback, response);
    }
}

6.4 QQ 登录请求构建（核心）

文件：ThirdLoginServiceImpl.java

QQ 登录的核心逻辑：

// 构建 QQ 登录请求
if (SysThirdLoginConfigSource.QQ.code.equals(source)) {
    authRequest = new AuthQqRequest(AuthConfig.builder()
            .clientId(clientId)          // App ID
            .clientSecret(clientSecret)  // App Key
            .redirectUri(callbackUrl)    // 回调地址
            .build());
}

完整回调处理流程：

// 1. 生成授权 URL（前端调用）
public LoginUrlVO getLoginUrl(String source) {
    String callbackUrl = thirdLoginProperty.getSiteUrl()
                       + thirdLoginProperty.getCallbackUrl()
                       + source.toLowerCase();
    AuthRequest authRequest = getAuthRequest(source, callbackUrl);
    String authorizeUrl = authRequest.authorize(AuthStateUtils.createState());
    return new LoginUrlVO(authorizeUrl);
}

// 2. 回调处理（QQ 重定向后调用）
public void callback(String source, AuthCallback authCallback,
                     HttpServletResponse response) throws IOException {
    AuthRequest authRequest = getAuthRequest(source, callbackUrl);
    AuthResponse authResponse = authRequest.login(authCallback);

    // 判断是否成功（JustAuth 成功码为 2000）
    if (authResponse.getCode() != 2000) {
        response.sendRedirect(siteUrl + errorUrl);
        return;
    }

    // 解析用户信息
    TicketAuth ticketAuth = JSONObject.parseObject(
            JSONObject.toJSONString(authResponse.getData()), TicketAuth.class);

    // 生成临时票据（Redis 缓存 60 秒）
    String ticket = ticketAuthService.createTicket(ticketAuth);

    // 重定向到前端登录页，携带 ticket
    String redirectUrl = StrUtils.format("{}{}{}",
            siteUrl, loginUrl, ticket);
    response.sendRedirect(redirectUrl);
}

6.5 票据服务（TicketAuth）

文件：TicketAuthServiceImpl.java

// 创建票据，存入 Redis，有效期 60 秒
public String createTicket(TicketAuth ticketAuth) {
    String ticket = IdUtils.simpleUUID();
    redisService.set(getTicketCacheKey(ticket), ticketAuth, 60, TimeUnit.SECONDS);
    return ticket;
}

7. 前端代码说明

7.1 API 接口

文件：vue-geshanzsq-nav/src/api/auth/login.js

// 获取登录授权地址
export function getLoginUrl(source) {
  return request({
    url: `/auth/third/login/getLoginUrl/${source}`,
    method: 'get'
  })
}

// 票据登录（前端凭 ticket 换取正式 token）
export function ticketLogin(data) {
  return request({
    url: '/ticket/login',
    method: 'post',
    data
  })
}

文件：vue-geshanzsq-nav/src/api/system/third/login.js

// 获取可用的第三方登录配置列表（公开接口）
export function list() {
  return request({
    url: '/system/third/login/list',
    method: 'get'
  })
}

7.2 后台登录页面

文件：vue-geshanzsq-nav/src/views/login/index.vue

页面加载时调用 list() 接口获取已启用的第三方登录配置
展示「第三方账号登录」区域，遍历 loginConfigList 显示各平台图标
点击 QQ 图标调用 handleTypeLogin('QQ')：

async function handleTypeLogin(source) {
  if (redirect.value) {
    setLoginRedirectPath(redirect.value)
  }
  const { data: { url } } = await getLoginUrl(source)
  window.location.href = url  // 跳转到 QQ 授权页面
}

用户授权后 QQ 回调到后端，后端重定向到 /login?ticket=xxx
前端检测到 ticket 参数后自动调用 ticketLogin({ ticket }) 换取 token

function init() {
  const ticket = router.currentRoute.value.query.ticket
  if (ticket) {
    doTicketLogin(ticket)
    return
  }
  initNotLogin()
}

async function doTicketLogin(ticket) {
  const { data } = await ticketLogin({ ticket })
  setToken(data.token)
  store.dispatch('user/setToken', data.token)
  router.push(getLoginRedirectPath() || redirect.value || '/me')
  removeLoginRedirectPath()
}

7.3 前台客户端登录弹窗

文件：vue-geshanzsq-nav/src/layout/client/components/Login/index.vue

前台页面同样支持第三方登录，流程与后台登录一致。

8. 完整登录流程图

┌─────────┐   ①点击QQ登录     ┌──────────┐   ②GET /auth/third/login/getLoginUrl/QQ   ┌──────────┐
│  前端    │ ────────────────→ │  前端    │ ──────────────────────────────────────────→ │  后端    │
│ (登录页) │                   │ (跳转)   │                                            │ (Java)   │
└─────────┘                   └──────────┘                                            └──────────┘
                                    │                                                      │
                                    │ ③window.location.href = authorizeUrl                 │ ④构建 AuthQqRequest
                                    ↓                                                      │ 返回 QQ 授权 URL
                              ┌───────────┐                                               │
                              │  QQ授权页  │                                               │
                              └───────────┘                                               │
                                    │                                                      │
                                    │ ⑤用户同意授权                                        │
                                    ↓                                                      │
                              ┌──────────┐   ⑥GET /auth/third/login/callback/QQ            │
                              │  后端    │ ←── QQ 回调携带 code ─────────────────────────── │
                              │ (回调)   │                                                 │
                              └──────────┘                                                 │
                                    │                                                      │
                                    │ ⑦ authRequest.login(callback) 获取用户信息           │
                                    │ ⑧ 生成 ticket 存入 Redis（60s）                      │
                                    │ ⑨ response.sendRedirect(/login?ticket=xxx)           │
                                    ↓                                                      │
                              ┌──────────┐   ⑩ POST /ticket/login { ticket }               │
                              │  前端    │ ──────────────────────────────────────────────→ │
                              │ (登录页) │ ←── 返回 token ─────────────────────────────── │
                              └──────────┘                                                 │
                                    │                                                      │
                                    │ ⑪ setToken + 跳转到目标页                            │
                                    ↓                                                      │
                              ┌──────────┐
                              │  目标页面  │
                              └──────────┘

9. QQ 互联平台回调域配置

在 QQ 互联应用管理后台，回调域需配置为：

开发环境：

http://localhost:8023/geshanzsq-nav-api/auth/third/login/callback/qq

生产环境：

https://gesdh.cn/geshanzsq-nav-api/auth/third/login/callback/qq

注意：回调地址格式为 {siteUrl}{callbackUrl}{source}，其中：siteUrl：网站地址（如 http://localhost:8023） callbackUrl：配置的回调路径（如 /geshanzsq-nav-api/auth/third/login/callback/） source：登录来源（QQ 为 qq，注意小写）

10. 常见问题

10.1 回调地址不匹配

确保 QQ 互联后台配置的回调域与项目中的回调地址完全一致，包括协议（http/https）、域名和路径。

10.2 clientId 或 clientSecret 配置错误

请确认数据库中 sys_third_login_config 表的 client_id 和 client_secret 与 QQ 互联申请的 App ID 和 App Key 一致。

10.3 状态未启用

确保 sys_third_login_config 表中 status 字段值为 1（正常），否则后端会返回「当前登录方式不支持」。

10.4 ticket 过期

票据（ticket）有效期为 60 秒，如果用户从 QQ 回调后长时间未跳转到登录页，ticket 可能已过期，需重新发起登录。

10.5 前端回调后未自动登录

检查浏览器地址栏是否包含 ?ticket= 参数，前端 init() 方法会自动检测并调用票据登录接口。确保 /ticket/login 接口在安全放行列表中。

11. 管理后台操作

登录系统后台后，进入 系统管理 → 第三方登录配置 页面，可以进行以下操作：

新增配置：添加 QQ 或其他平台的登录配置
编辑配置：修改 App ID、App Key 等信息
停用/启用：控制该登录方式是否对外展示
排序：调整各登录方式的展示顺序

12. 参考文档

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

oauth2.0

单点登录

spring boot