第二十一章. 第三方授权：JustAuth 集成与 Gitee 实战

本章学习路径

我们将按照“理念 -> 配置 -> 实战”的路径，分步攻克第三方登录集成：

21.1. 核心理念：RVP 的“绑定式”授权

在开始配置之前，我们必须首先理解 RVP 框架在第三方登录功能上的核心设计思想。

21.1.1. 什么是第三方登录？

第三方登录（Third-party Login），是一种授权机制，允许用户利用他们在第三方平台（如微信、QQ、Gitee、GitHub）上已有的账户，来快速完成我们自己应用的登录或注册。

它的核心价值 在于简化了用户的操作流程。用户无需在我们自己的系统中再次填写繁琐的注册表单、记忆新的账号密码，从而提高了用户体验和转化率。

21.1.2. [重点] RVP 的模式：“先绑定，后快捷登录”

RVP 框架采用的第三方登录模型，与常见的“一键注册”模型 有所不同。

• 常见模型 (一键注册)：用户在登录页点击“微信登录”，授权后，系统自动为其创建一个新账号并登录。
• RVP 模型 (先绑定)：RVP 的第三方登录 不用于“注册”，而是作为一种“辅助认证”手段。

RVP 的流程被严格地分为两步：

1. 流程一：账号绑定（在“个人中心”）
   • 用户 必须 首先通过常规的“用户名 + 密码”方式登录系统。
   • 登录后，在“个人中心” -> “第三方应用”界面。
   • 用户点击“绑定 Gitee”，跳转到 Gitee 授权页，同意授权。
   • 授权成功后，系统将该 Gitee 账号的唯一标识 (UUID) 与当前 已登录 的 RVP 账号（如 admin）建立关联。
2. 流程二：快捷登录（在“登录页”）
   • 只有完成绑定后，用户才能在“登录页”使用第三方快捷登录。
   • 用户点击“Gitee”图标，跳转 Gitee 授权。
   • 授权成功后，RVP 后端根据 Gitee 返回的 UUID，在数据库中找到了已绑定的 admin 账号，于是自动为 admin 账号创建会话，实现登录。

21.1.3. 技术基石：JustAuth 框架

RVP 框架之所以能支持 Gitee、GitHub 等众多平台，其底层依赖的是一个强大的开源组件—— JustAuth。

JustAuth 是一个“小而全”的第三方登录集成库。它将 Gitee、GitHub、钉钉、企业微信、QQ、微博等几十种平台的 OAuth 2.0 授权流程，封装成了统一的、简洁的 Java API 接口。

RVP 框架集成了 JustAuth，这意味着：凡是 JustAuth 支持的平台，RVP 均可支持。 我们需要做的，只是按照规范，在 application.yml 中添加对应平台的配置即可。

21.2. 准备工作（一）：在 Gitee 创建应用

在 RVP 中配置 Gitee 登录之前，我们必须先去 Gitee 平台，注册一个“第三方应用”，并获取到关键的凭证。

21.2.1. 申请第三方应用

1. 登录 Gitee (码云) 官网 跳转至 帐号管理 - Gitee.com
2. 点击右上角头像，进入“设置”。
3. 在左侧菜单栏找到并点击“第三方应用”。
4. 点击“创建应用”按钮。

此时，我们需要填写应用的“基本信息”：

• 应用名称：用于向用户展示，例如 RuoYi-Vue-Plus 演示。
• 应用主页：你的网站首页地址，例如 https://www.ruoyi.vip (可先随意填写一个有效的 HTTPS 网址)。
• 应用图标：上传一个 Logo。

21.2.2. [核心] 理解并配置“应用回调地址”

这是 最核心 的配置项。

什么是回调地址？
它告诉 Gitee：当用户在 Gitee 页面上点击“同意授权”后，Gitee 应该“重定向” (Redirect) 到你应用的哪个 URL 地址，并附上授权凭证。

如果这里配置的地址与 RVP 后端请求 Gitee 时携带的 redirect_uri 参数 不一致，Gitee 将拒绝授权，并报错“无效的登录回调地址”(invalid_redirect_uri)。
RVP 框架 justauth 模块定义的统一回调地址格式为：
{后端服务地址}/auth/callback?source={平台名称}

对于 Gitee，我们需要在 Gitee 应用配置中填写：
http://localhost:81/social-callback?source=giteee

21.2.3. 获取 Client ID 与 Client Secret

完成所有信息填写（包括权限，选择“访问用户的个人信息”等）并创建应用后，Gitee 会跳转到应用详情页。

在此页面，我们可以获取到两个关键凭证：

• Client ID：应用的唯一标识符（客户端 ID）。
• Client Secret：应用的密钥（客户端 Secret）。

请妥善保管这两个值，它们是 RVP 后端与 Gitee 通信的“账号和密码”。

21.3. 准备工作（二）：配置 RVP 后端

在上一节中，我们已经从 Gitee 平台获取了 Client ID 和 Client Secret。现在，我们需要将这两个凭证配置到 RVP 的后端项目中。

21.3.1. [核心] application-dev.yml 中的 justauth 配置

首先，在 IDEA 中打开 RVP 后端项目。

文件路径：ruoyi-admin/src/main/resources/application-dev.yml

打开 ruoyi-admin 模块（主启动模块）的 开发环境 配置文件 application-dev.yml。在文件中找到 justauth 相关的配置块。

1
2
3
4
5
6
7
8
9
10
11
12

# JustAuth第三方登录配置
justauth:
  # RVP 后端服务的回调地址前缀
  # 注意：这里的地址必须与 Gitee 应用中配置的回调地址 {RVP后端地址} 部分完全一致
  address: http://localhost:81
  # Gitee 平台配置
  type:
    gitee:
      client-id: xxxx
      client-secret: xxxx
      redirect-uri: ${justauth.address}/social-callback?source=gitee
      # ... 其他平台，如 github, wechat_open ...

21.3.2. 填充 Gitee 的 Client ID 与 Secret

我们需要修改 type.gitee 节点下的配置：

1. 将 client-id: test 替换为我们在 21.2.3 中从 Gitee 获取的 Client ID。
2. 将 client-secret: test 替换为我们在 21.2.3 中获取的 Client Secret。

配置示例：

1
2
3
4
5
6
7
8
9
10

# ... (省略上方配置) ...
justauth:
  address: http://localhost:81
  type:
    gitee:
      # [修改这里] 替换为你自己的 Client ID
      client-id: 9a8b7c6d5e...
      # [修改这里] 替换为你自己的 Client Secret
      client-secret: 1f2e3d4c5b...
# ... (省略下方配置) ...

21.3.3. 重启后端服务

21.4. [重点] 解决开发环境“回调地址无效”

在 21.3 节我们重启服务后，满怀期待地去“个人中心”点击“Gitee 绑定”，此时你 极有可能 会授权失败，并看到 Gitee 页面提示“存在错误：无效的登录回调地址 (invalid_redirect_uri)”。

这是开发环境中 90% 的人都会遇到的问题。

21.4.1. 为什么 Gitee 不认识 localhost？

这个问题的根源在于“回调地址”的校验机制。

1. Gitee 侧：我们在 Gitee 应用上配置的回调地址是 http://localhost:8080/auth/callback?source=gitee。
2. RVP 侧：RVP 后端（justauth.address）告诉 Gitee，请你回调 http://localhost:8080。

当 Gitee 收到 RVP 的请求时，它会对比这两个字符串。但有时，浏览器或本地网络环境可能会将 localhost 自动解析或重定向为 127.0.0.1。

此时，RVP 实际请求的回调地址变成了 http://127.0.0.1:8080/...，而 Gitee 平台上只注册了 http://localhost:8080/...，Gitee 认为这两个字符串 不匹配，于是拒绝了请求。

21.4.2. [实战] 修改 hosts 文件（Windows）

要解决这个 localhost 和 127.0.0.1 之间的“身份不一致”问题，最彻底的办法是修改本地的 hosts 文件，强制建立一个明确的 IP 与域名（localhost）的映射关系。

hosts 文件路径：
C:\Windows\System32\drivers\etc\hosts

修改步骤：

1. 由于该文件是系统文件，没有管理员权限无法直接保存。
2. 将 hosts 文件 复制 到桌面。
3. 使用“记事本”打开桌面上这个 hosts 副本。
4. 在文件末尾，添加以下两行（如果已存在则无需重复添加）：

   1 2 3 4

   # 强制将 127.0.0.1 映射到 localhost 127.0.0.1 localhost # （可选，但推荐）反向映射 localhost 127.0.0.1

5. 保存并关闭记事本。
6. 将桌面上修改后的 hosts 副本，复制粘贴 回 C:\Windows\System32\drivers\etc\ 目录。
7. 系统会提示“你需要提供管理员权限”，点击“继续”将其覆盖。

21.4.3. 验证 hosts 文件生效

hosts 文件修改并覆盖后，无需重启电脑。但为了确保配置被正确加载，我们应该：

1. 重启你的 IDEA（以及 DromaraApplication 服务）。
2. （可选）清空浏览器缓存，或使用“无痕模式”访问。

完成 hosts 修改并重启服务后，localhost 和 127.0.0.1 之间的解析将变得一致，Gitee 的回调校验就能成功通过了。

21.5. [实战] 用户操作全流程

在完成了 Gitee 应用创建、后端 YML 配置、hosts 文件修复并重启服务后，我们的准备工作已全部完成。现在，我们来完整体验 RVP 的“绑定式”授权流程。

21.5.1. 流程一：绑定账号（个人中心）

这是实现第三方登录的 第一步，也是 必须的 一步。

1. 使用 用户名和密码（例如 admin / admin123）登录 RVP 系统。
2. 点击右上角头像，进入“个人中心”。
3. 在左侧菜单中选择“第三方应用”。
4. 点击 Gitee (码云) 图标按钮。
5. 页面跳转到 Gitee 授权页（此时应能看到你在 21.2.1 中创建的应用名称和 Logo）。
6. 勾选所需权限（如“访问个人信息”），点击“同意授权”。
7. Gitee 将回调 RVP 后端，后端处理成功后，页面跳回“第三方应用”界面，提示“操作成功”。

此时，我们就成功地将 Gitee 账号与 admin 这个 RVP 账号绑定在了一起。

21.5.2. 流程二：快捷登录（登录页）

只有在完成“绑定”后，这个流程才能成功。

1. 在 RVP 系统中，点击右上角“退出登录”。
2. 返回到 RVP 登录页面。
3. 点击登录框下方的 Gitee (码云) 图标。
4. 页面跳转到 Gitee 授权页（如果浏览器已有 Gitee 登录状态，可能 不会 再次要求授权，而是直接回调）。
5. Gitee 回调 RVP 后端，RVP 后端根据 Gitee 返回的用户信息，在数据库中找到了已绑定的 admin 账号。
6. 系统自动为 admin 账号创建会话，页面提示“操作成功”并跳转到系统主页。

失败场景：如果你在 绑定前，直接在登录页点击 Gitee 图标，授权回调后系统会提示：“你还没有绑定三方应用，请先登录后绑定”。

21.5.3. 流程三：解除绑定

如果不再希望使用 Gitee 快捷登录，可以随时解绑。

1. 使用任意方式登录 RVP 系统（用户名密码 或 Gitee 快捷登录 均可）。
2. 进入“个人中心” -> “第三方应用”。
3. 在已绑定的 Gitee 账号信息旁，点击“解绑”按钮。
4. 确认后，该 Gitee 账号与 RVP 账号的关联被解除。

解绑后，你将无法再通过 Gitee 快捷登录，必须使用用户名和密码，直到你重新进行“绑定”操作。