第十六章. 认证中心：客户端管理（多端 Token 策略的核心）

第十六章. 认证中心：客户端管理（多端 Token 策略的核心）

摘要：本章我们将深入 RVP 5.x 的一个 核心认证模块——客户端管理。在 4.x 中，Token 的超时时间在 yml 中全局写死；而 5.x 引入了 Client（客户端）概念，允许我们为 PC 端、小程序、APP 端 设置 完全不同 的 Token 超时策略，这是多端应用架构的基石。

本章学习路径

我们将从“为什么需要它”这一核心痛点出发，深入理解其设计原理与应用价值：

16.1. [核心] 客户端管理的价值：对比 4.x yml 配置

在开始探索这个模块之前，我们必须先理解 RVP 5.x 为什么要“大费周章”地新增一个“客户端管理”？

16.1.1. 4.x 的局限：yml 中的“一刀切”

在 RVP 4.x 的老版本中，Token（用户令牌）的超时时间，是 全局配置 在 application.yml 文件中的。比如，我们这样设置：

1
2
3
# RuoYi 4.x (示例)
token:
  expireTime: 1800 # 30分钟

这种“一刀切”的设计有一个 致命缺陷：它无法区分“客户端”类型。

16.1.2. 5.x 的进化：“多端多策略”的 Token 管理

在现代项目中，一个后端系统往往要同时支持多个前端：

  1. PC 管理后台：安全性要求高，30 分钟不操作就该退出。
  2. APP（iOS/Android）：安全性中等，可以保持 7 天登录。
  3. 小程序（MiniProgram）：信任度最高（已通过微信认证），我们希望用户“永远在线”，至少 15 天内都不要重新登录。

如果使用 4.x 的“一刀切”配置，就会陷入两难：

  • 如果设置为 30 分钟，小程序用户会“骂娘”，因为他们每半小时就要重新授权一次。
  • 如果设置为 15 天，PC 管理后台的安全性又形同虚设。

“客户端管理”（sys_client 表）就是 RVP 5.x 提供的完美解决方案。它将 Token 策略从 yml 的“静态全局配置”中解放出来，变成了“动态可配置的策略中心”。

它允许我们为 PC、APP、MiniProgram 分别创建 三条 不同的客户端配置，匹配三套 完全不同 的超时策略。

16.2. [重点] 核心字段解析：clientId、grantType 与“双超时”

我们点击 系统管理 -> 客户端管理，打开一条配置（如 PC 端）进行“修改”。

image-20251112103313641

16.2.1. clientId / clientKey / clientSecret（客户端凭证）

我们观察上方截图，可以明白我们有以下三个核心字段

  • clientId：客户端的 唯一 ID（如 15cd...）。这是前端发起请求时必须携带的“身份标识”。
  • clientKey：客户端的“用户名”（如 PC）。
  • clientSecret：客户端的“密码”。

这套 Key/Secret 组合，是 OAuth 2.0 认证体系中的标准概念，用于 认证“前端应用”本身的合法性。

16.2.2. “授权类型”与“设备类型”

  • 授权类型：定义了本客户端“允许”使用哪种方式登录。例如，PC 端我们勾选了 password（密码验证）和 third_part（三方登录）。
  • 设备类型：一个标记，用于区分 PC、Android、iOS 等。

[核心] 字典驱动：
这两个字段的设计非常精妙，它们的数据源 并非 写死在代码中，而是 关联了“字典管理”（我们在第十二章所学）。

  • sys_grant_type (授权类型字典)
  • sys_device_type (设备类型字典)

这意味着什么？如果未来我们想增加一种“HarmonyOS (鸿蒙)”设备，我们 不需要修改任何后端 Java 代码。我们只需要去“字典管理”中，为 sys_device_type 添加一个 HarmonyOS 的字典数据，这里就能立刻选择它。

16.2.3. [核心] “双超时”机制详解

这是本模块 最核心 的两个配置，必须彻底理解。

16.2.3.1. tokenActiveTimeout（活跃超时时间）：滑动窗口

  • 含义：指定时间内 无操作 则过期（默认 1800 秒，即 30 分钟）。
  • 机制：这是一个“滑动窗口”或“续期”机制。
  • 类比：它就像一个 30 分钟的“屏保”。
    • 你 10:00 登录，Token 10:30 过期。
    • 你在 10:20 进行了操作（点击了菜单，发起 API 请求）。
    • RVP 后端发现你的 Token 还在有效期，于是 自动 将你的过期时间“续期”到 10:50（从 10:20 往后再推 30 分钟）。
  • 应用：这是 PC 管理后台的标准配置，保证了“只要你在操作，你就不会掉线”。

16.2.3.2. tokenTimeout（固定超时时间）：绝对有效期

  • 含义：指定时间 必定 过期（默认 604800 秒，即 7 天）。
  • 机制：这是一个“绝对有效期”或“硬期限”机制。
  • 类比：它就像一张“7 天体验卡”。
  • 场景：你是一个非常活跃的用户，连续 7 天都在操作，你的“活跃超时”被无限次地“续期”了。
  • 结果：到了第 7 天的 10:00（你最初登录的时间），RVP 发现 Token 已达到“固定超时时间”，立刻判定 Token 失效，不再为你续期。
  • 应用：这是出于 安全 考虑。它强制用户（即使是活跃用户）最长 也只能 7 天免密登录，7 天后必须 重新认证 一次，防止 Token 泄露后被永久盗用。

16.3. [原理] 客户端 clientId 的传递与验证

我们已经配置好了策略，那么 RVP 后端是如何“知道”当前用户应该应用哪条策略的呢？

16.3.1. 前端（UI）：在请求头中携带 clientId

答案在前端。前端（浏览器）在发起 每一次 API 请求时，都必须在 Request Header（请求标头） 中，携带它自己的“身份标识”——clientId。

我们可以打开浏览器的“开发者工具”（F12），切换到“网络(Network)”标签页，刷新页面。随便点开一个（如 getInfo）请求，在“请求标头”中，你会清晰地看到：

clientId: e5cdxxxxxxxxxxxxx

这个 e5cd... 正是我们在“客户端管理”中看到的 PC 端的那条记录的 ID。

image-20251112103730438

16.3.2. 后端（API）：根据 clientId 查询并应用 Token 策略

RVP 的后端（网关或认证中心）在收到请求后，会执行以下自动化流程：

  1. 从 Request Header 中 读取 clientId。
  2. 查询 sys_client 表，找到 clientId 对应的 策略行。
  3. 获取 该策略的“活跃超时”（1800 秒）和“固定超时”（7 天）。
  4. 根据这套策略，去 验证 请求中携带的 Token 是否有效、是否需要“续期”。

16.3.3. [注意] 正在使用的 Client 禁止停用

理解了这个机制，我们就明白了一个 至关重要的安全警告：

永远不要“停用”或“删除”你前端正在使用的那条 clientId 配置！

如果你（admin）在后台“停用”了 e5cd... 这条 PC 端配置，会发生什么？

  1. 你刷新页面，前端发起 getInfo 请求，依然携带 clientId:e5cd...。
  2. RVP 后端读取 clientId，去 sys_client 表查询。
  3. 后端发现这条配置 已被停用（status = 1）。
  4. 后端 立刻拒绝 了此次请求，返回“客户端已被禁用”的错误。
  5. 结果：你的前端页面 瞬间崩溃，所有 API 401，你（admin）也 被踢出了系统，并且 再也无法登录（因为登录请求也需要 clientId）。

16.4. 如何为“小程序”配置长效 Token

最后，我们把所有知识串联起来，解决那个最初的痛点：如何为小程序配置一个 15 天的“长效 Token”？

（这是一个“讲解型”的流程，我们关注的是“思路”而非“操作”）

思路一：扩展“字典”
如果我们想在“设备类型”中选择“小程序”，但字典里没有。我们应先去“字典管理”，为 sys_device_type 字典新增一个条目（例如：标签 = 小程序, 键值 = miniProgram）。

思路二：新增“客户端”
回到“客户端管理”，点击“新增”：

  • 客户端 Key：mini-program（方便识别）
  • 客户端密钥：自动生成或自定义一个（例如 miniprogram_secret）
  • 授权类型：勾选 miniProgram_login（小程序验证，假设字典里已配好）
  • 设备类型：选择我们刚添加的 小程序
  • 活跃超时：1296000 (15 天，15 * 24 * 60 * 60)
  • 固定超时：2592000 (30 天)
  • 点击“确定”保存。

思路三：小程序端“应用”
最后，也是最关键的一步：在“小程序”的 前端代码 中，在发起所有请求（包括登录请求）时，其全局 Request Header 中携带的 clientId 必须是 我们刚刚新增的那条记录的 clientId（例如 88ab...）。

最终效果：

  • PC 端（clientId: 15cd...）登录，获得 30 分钟的 Token。
  • 小程序端（clientId: 88ab...）登录，获得 15 天的 Token。

同一个用户，在不同设备上，获得了完全不同的 Token 策略。这就是 RVP 5.x 客户端管理的真正威力。

16.5 第十六章总结

本章我们深入了 RVP 5.x 认证体系的基石——客户端管理。它解决了 4.x yml 配置“一刀切”的痛点。

  • 核心价值：实现了“多端多策略”的 Token 管理。允许 PC、APP、小程序使用 各自独立 的超时配置。
  • 核心机制：前端在 请求头（Header） 中携带 clientId，后端根据 clientId 查询 sys_client 表，获取对应的 Token 策略。
  • “双超时”：
    • 活跃超时（activeTimeout）：滑动窗口，操作即“续期”（如 30 分钟）。
    • 固定超时（timeout）：绝对寿命，到期必“强退”（如 7 天）。
  • 扩展性：“授权类型”和“设备类型”均由“字典管理”驱动，可自由扩展（如新增 HarmonyOS）而无需修改后端代码。
  • 安全红线：严禁 停用或删除前端正在使用的 clientId，否则将导致全站崩溃。