# auth: refreshToken 滑动续期 + 双 token 机制(admin + 小程序 user)

> **服务**: hl-user-service (8081) + hl-mp-service (8085) + hl-gateway (8080)
> **PR**: #2312 (已合 dev,测试服待 Deploy Panel 部署)
> **Issue**: #2309
> **日期**: 2026-05-15
> **影响范围**: 管理后台 hl-ui + 微信小程序两端的登录态 / 401 拦截器

---

## ⚠️ 关键变化(对前一版 #2285 的演进)

| 维度 | 上一版 PR #2285 (2026-05-14) | 本版 PR #2312 (2026-05-15) |
|------|--------------------------------|------------------------------|
| 适用端 | 仅 admin | **admin + 小程序 user 双端** |
| accessToken TTL | admin 2h | **admin 30 分钟 / user 30 分钟** |
| refreshToken TTL | admin 7d | **admin 7d / user 90d** |
| 续期模式 | refresh 字符串**轮转**(每次换新串,旧立即失效) | **滑动续期** — refresh 字符串**不换**,只刷 Redis 中 jti 的 TTL |
| 灰度策略 | 直接切 | **网关新 key 优先 + 旧 key fallback**(2026-05-22 删 fallback) |
| 字段名 | data.token = access (兼容) + refreshToken | **同上,新增 data.accessToken 显式字段,data.token 仍保留** |

**核心新原则**:**refreshToken 字符串后端不换,前端无需更新本地存的 refresh,只更新 access**。这是与 #2285 最大的行为差异 —— 上一版前端必须每次 refresh 后立即覆盖本地 refresh,这一版**不需要**(覆盖也无害)。

---

## 一、背景

PR #2285 上线后用户中途反馈:**rotation 模式遇到弱网/重复请求/双标签页时,新 refresh 还没收到旧 refresh 已被废,触发误踢登录**。本版改为滑动续期:refresh 字符串保持稳定 7d/90d 内不变,只刷 Redis TTL,既解决误踢又保留"长期不活跃自动失效"语义。同时把小程序 user 端也接入(此前 user 端是无 refresh 机制 90 天硬到期)。

TTL 配置(线上确认值):

| 端 | accessToken | refreshToken | nacos key |
|----|-------------|--------------|-----------|
| admin | 30 分钟 (1800s) | 7 天 (604800s) | `auth.jwt.admin-access-ttl-seconds` / `auth.jwt.admin-refresh-ttl-seconds` |
| 小程序 user | 30 分钟 (1800s) | 90 天 (7776000s) | `auth.jwt.user-access-ttl-seconds` / `auth.jwt.user-refresh-ttl-seconds` |

灰度期: **2026-05-15 ~ 2026-05-22**,7 天后后端会清掉网关里的旧 key fallback 块。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | admin 刷新令牌 | POST | `/admin/auth/refresh` | 行为变化 | 从字符串轮转改滑动续期,refresh 不换串 |
| 2 | 小程序刷新令牌 | POST | `/mp/user/refresh` | **新增** | 小程序端首次有 refresh 能力 |
| 3 | user-service 刷新令牌(内部) | POST | `/user/refresh` | **新增** | hl-mp-service Feign 调用入口 |
| 4 | user-service 刷新令牌(MP 内部) | POST | `/internal/mp/user/refresh` | **新增** | mp-service → user-service Feign |
| 5 | admin 所有签发 token 接口 | - | login/2fa/switch-role/wechat-qr/check 等 | 响应字段微调 | data 内仍是 token+refreshToken+accessTokenExpiresIn+refreshTokenExpiresIn,**额外多 accessToken 字段** |
| 6 | 小程序 user login + login-by-sms | POST | `/mp/user/login` 等 | 响应新增 | data 多 refreshToken+双 expiresIn+accessToken 字段 |

---

## 三、登录响应字段(灰度期前端可零改动)

```json
{
  "code": 200,
  "data": {
    "token": "eyJ...ACCESS",                  // 向后兼容字段, = accessToken
    "accessToken": "eyJ...ACCESS",            // 新字段, 同 token
    "refreshToken": "eyJ...REFRESH",          // 新字段, 长效 7d/90d
    "accessTokenExpiresIn": 1800,             // 秒
    "refreshTokenExpiresIn": 604800,          // 秒, admin=604800/user=7776000
    "...其它现有字段保持不变"
  }
}
```

**灰度期内前端不改任何代码,继续读 `data.token` 即可正常登录使用,只是 30 分钟后会被踢**(因为没用 refresh)。要做无感续期才需要新增 refresh 拦截器。

---

## 四、新接口详情

### 1. POST /admin/auth/refresh (管理端)

```json
// Request
{ "refreshToken": "eyJ...REFRESH" }

// Response 200
{
  "code": 200,
  "data": {
    "token": "...新 access...",
    "accessToken": "...新 access...",
    "refreshToken": "...原 refresh,字符串不变...",
    "accessTokenExpiresIn": 1800,
    "refreshTokenExpiresIn": 604800
  }
}

// Response 401 — refresh 已过期 / 已被 logout 作废 / 篡改 / tokenKind 错
{ "code": 401, "msg": "刷新令牌无效或已过期,请重新登录" }
```

- **不需要 Authorization 头**(网关 SKIP_URLS 已加白名单)
- **refresh JWT 字符串保持不变**,仅刷新 Redis 中 jti 的 TTL
- 错误码: `200209 REFRESH_TOKEN_INVALID` / `200210 REFRESH_TOKEN_REPLAY` / `200211 TOKEN_KIND_MISMATCH`

### 2. POST /mp/user/refresh (小程序端,新接口)

请求 / 响应结构同上,`refreshTokenExpiresIn = 7776000` (90 天)。

- **不需要 Authorization 头**
- 链路: 小程序 → hl-mp-service `MpUserController` → `MpUserAggregationService` → `MpUserFeignClient.refreshToken()` → hl-user-service `InternalMpUserController` `POST /internal/mp/user/refresh`

### 3. logout 行为(无契约变化,但行为补强)

`POST /admin/auth/logout` / `POST /mp/user/logout` 后端同时清:
- access 白名单 key (新+旧两套)
- refresh 白名单 key

logout 后立即调 refresh 会 401。

---

## 五、自动 refresh 拦截器实现要点 (@mmg)

### admin 端 (axios)

```js
// 单飞锁防并发 401 一起触发多次 refresh
let refreshing = null;

async function onResponseError(err) {
  // 本项目 HTTP 总是 200,401 在 body.code,也要拦
  const code = err.response?.data?.code;
  if ((code === 401 || err.response?.status === 401) && !err.config._retried) {
    if (!refreshing) {
      refreshing = (async () => {
        const r = await axios.post('/admin/auth/refresh', {
          refreshToken: localStorage.getItem('admin_refresh')
        });
        if (r.data?.code !== 200) throw new Error('refresh failed');
        // 关键: refreshToken 字符串和原来一样,但 accessToken 变了
        localStorage.setItem('admin_access', r.data.data.accessToken); // 或 .token
        // refreshToken 不需要更新(后端不换串),但更新一下也无害
        localStorage.setItem('admin_refresh', r.data.data.refreshToken);
      })().finally(() => { refreshing = null; });
    }
    try {
      await refreshing;
      err.config._retried = true;
      err.config.headers.Authorization = `Bearer ${localStorage.getItem('admin_access')}`;
      return axios.request(err.config);
    } catch (refreshErr) {
      localStorage.removeItem('admin_access');
      localStorage.removeItem('admin_refresh');
      router.push('/login');
    }
  }
  throw err;
}
```

### 小程序端

同样的 401 拦截思路,把 `axios` 换成 `wx.request` 包装,storage 用 `wx.setStorageSync('user_refresh', ...)`,refresh 端点 `/mp/user/refresh`。

⚠️ **复用同一 refreshToken 字符串** — 后端不换串,你前端**无需**更新 refreshToken,只需更新 accessToken / token 字段。这与 PR #2285 的行为不同。

---

## 六、安全注意

1. **refreshToken 不要带在业务请求里**,只在调 `/admin/auth/refresh` 或 `/mp/user/refresh` 时用
2. **refreshToken 不要传给 Authorization 头** — 网关会显式拒绝(`tokenKind=REFRESH 不能用于业务接口`,401)
3. logout 时要把 storage 里的 token + refreshToken 都清掉
4. accessToken 30 分钟 TTL,即使被泄露窗口期短;refreshToken 7d/90d TTL 长,泄露后果严重 — 优先存 secure storage(小程序 `wx.setStorage` 即可,管理后台用 httpOnly cookie 不现实就用 localStorage,**禁止打印到 console / 上传到第三方 SDK**)
5. switchRole / changePassword / 改密 / 删 admin / 锁定账号 等场景后端会主动清 refresh,前端调 refresh 收到 401 时直接跳登录即可

---

## 七、灰度兼容期具体行为(2026-05-15 ~ 2026-05-22)

| 场景 | 行为 |
|------|------|
| 旧前端 (只读 data.token,不调 refresh) | ✓ 正常工作 |
| 旧前端 access 30 分钟后过期 | ⚠️ 30 分钟后 401,被迫重登(因为没用 refresh) |
| 新前端 (调 refresh) | ✓ 滑动续期,7d/90d 内活跃永不重登 |
| 灰度期内旧 admin_token / user_token Redis key | ✓ 网关 fallback 仍认 |
| 2026-05-22 后旧 key 失效 | ❌ 仍读旧 key 的代码会全失败 — **mmg 务必在 5-22 前完成切换** |

---

## 八、不影响范围

- 现有所有业务接口契约(参/返)零变化
- 登录端点 path 不变
- /admin/auth/info / /mp/user/profile 等读接口不变
- 已签发的旧 access token 在 Redis 还有原 TTL,部署后**不会立即失效**(灰度 fallback)
- 接口字段名 `data.token` 保留,**不做 breaking 改名**

---

## 九、配置项

| 配置 key | 默认 | 备注 |
|----------|------|------|
| `auth.jwt.admin-access-ttl-seconds` | 1800 (30 分钟) | nacos 可覆盖 |
| `auth.jwt.admin-refresh-ttl-seconds` | 604800 (7 天) | nacos 可覆盖 |
| `auth.jwt.user-access-ttl-seconds` | 1800 (30 分钟) | nacos 可覆盖 |
| `auth.jwt.user-refresh-ttl-seconds` | 7776000 (90 天) | nacos 可覆盖 |

代码层有 fallback,nacos 不配也能跑。

---

## 十、相关历史 PR

| PR | Issue | 说明 | 是否仍有效 |
|----|-------|------|------------|
| #2285 (2026-05-14) | #2283 | 首版双 token,admin only,字符串轮转 | ❌ 已被本 PR 演进替代(除合规清理逻辑外行为差异) |
| #2287 hotfix | - | user-service TokenInterceptor 白名单 | ✅ 仍有效 |
| #2294 hotfix | - | deleteAdmin/resetPassword/账号锁定 cleanup | ✅ 仍有效,本 PR 兼容 |
| **本 PR #2312** | **#2309** | 滑动续期 + 双端覆盖 + 灰度兼容 | ✅ **最新** |

---

## 十一、联调端点

- 测试服: `https://api.test.1814.love/`(待 Deploy Panel 部署 PR #2312 后生效)
- 测试 admin: `admin / Admin@123456`
- 测试小程序 user: 用现有微信测试号登录即可

---

## 十二、相关文档

- 关联 Issue: [wx/HL#2309](https://git.1814.love:8443/wx/HL/issues/2309)
- 关联 PR: [wx/HL#2312](https://git.1814.love:8443/wx/HL/pulls/2312)
- 上一版 changelog: `2026-05/14_feat_admin_auth_refresh_token.md`