# 8.6 Token 使用说明

:::tip 概述
系统采用 JWT 双令牌认证，access_token 用于接口认证（2 小时），refresh_token 用于刷新令牌（7 天）。refresh_token 存储于 Redis（jti 有状态），支持**一次性刷新、登出吊销、踢下线**。所有需认证的接口必须在请求头中携带 access_token。
:::

## Token 完整生命周期

### 登录获取 Token

```text
用户输入账号密码
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 前端：POST /api/login                                       │
│ { username, password, code, key }                           │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ 后端：AuthController → JwtService                           │
│                                                             │
│ 1. LoginRequest            参数格式校验                      │
│ 2. CaptchaService::verify() 验证码校验（key/code）            │
│ 3. User::where('username') 查询用户                          │
│ 4. PasswordService::verify() 密码校验（双重加盐）             │
│ 5. createTokenPair()       签发双令牌 + refresh 存 Redis      │
│    （同一 jti，Redis 键 refresh:{uid}:{jti}，TTL 7 天）        │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ 响应（登录/刷新接口 raw 返回，保持 snake_case）：             │
│ {                                                           │
│   "access_token": "eyJ...",      ← 用于接口认证             │
│   "refresh_token": "eyJ...",     ← 用于刷新令牌             │
│   "token_type": "Bearer",                                   │
│   "expires_in": 7200,            ← 2小时 = 7200秒           │
│   "user": { "id":1, "username":"admin", ... }                │
│ }                                                           │
│ （AuthController 调用 success(..., true) 跳过驼峰转换，      │
│   与前端 store 的 data.access_token 读取方式保持一致）        │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ 前端：存储 Token（仅存 access_token）                        │
│                                                             │
│ storage.set('ACCESS-TOKEN', data.access_token)              │
└─────────────────────────────────────────────────────────────┘
```

### 使用 Token 请求 API

```text
用户操作（如点击"用户列表"）
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 前端：请求拦截器                                            │
│ const token = storage.get('ACCESS-TOKEN')                   │
│ config.headers['Authorization'] = `Bearer ${token}`         │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ GET /api/user/page?pageNo=1&pageSize=10                     │
│ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ 后端：Authenticate 中间件（auth.jwt）                        │
│                                                             │
│ 1. 提取 Authorization 头（带 Bearer 前缀则剥离，裸 token 亦可）│
│    │ 头缺失 → HTTP 200 "未提供认证令牌"                        │
│ 2. JwtService::parseToken()（校验签名+有效期+type=access）    │
│    │ 过期/签名错/类型错 → HTTP 200                           │
│ 3. 注入 attributes['userInfo']                              │
│ 4. 反射 #[Permission] → checkPermission()                   │
│    │ 无权限 → HTTP 403 "无访问权限：{权限码}"                 │
│ 5. 放行 → Controller → Service → Model → 响应               │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│ 前端：响应拦截器                                            │
│ code === 0   → 返回 data（成功）                            │
│ code/status 401 → 弹窗"登录身份已失效" → 清存储 → 跳登录页    │
│ code/status 403 → 提示"无访问权限"                           │
│ 其他         → 提示 msg                                     │
└─────────────────────────────────────────────────────────────┘
```

### Token 刷新（后端能力）

access_token 过期后，客户端可用 refresh_token 换取新令牌对：

```text
POST /api/refresh
{ "refresh_token": "eyJ..." }          ← 主入口（公开接口）
   （或 POST /api/oauth2/token，grant_type=refresh_token）
    │
    ▼
JwtService::refreshToken()
    │ 1. 解析 refresh_token → 失败 → "无效的refresh_token"
    │ 2. type 必须为 refresh
    │ 3. Lua 原子校验并删除 Redis refresh:{uid}:{jti}（一次性）
    │    已用过/已吊销 → "refresh_token已失效"
    │ 4. 用户状态校验 → "用户不存在或已被禁用"
    │ 5. createTokenPair() → 新 jti 签发新令牌对
    ▼
返回新令牌对（access_token / refresh_token 均为新值）
```

:::warning 一次性刷新（防重放）
旧 refresh_token 刷新后立即从 Redis 删除——**必须保存返回的新 refresh_token**，重放旧令牌会得到 `refresh_token已失效`。
:::

:::info 管理后台前端的现状
`ui/` 管理后台当前**未内置自动续签**：access_token 过期（401）时直接弹窗提示重新登录（见下文「响应拦截器」）。`POST /api/refresh` 面向第三方接入客户端与后续前端升级使用。
:::

### Token 失效（重新登录）

```text
access_token 过期 / refresh_token 刷新失败（过期/已吊销/网络异常）
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 前端：清除登录态，跳转登录页                                 │
│ storage.clear()                                             │
│ window.location.href = '/login'                             │
└─────────────────────────────────────────────────────────────┘
```

### 两种 Token 的区别

```text
┌─────────────────────────────────────────────────────────────┐
│                    access_token                             │
│  用途：接口认证（每个 API 请求携带）                         │
│  有效期：2 小时（JWT_ACCESS_TTL=7200 秒）                    │
│  payload：type=access，含 jti                               │
│  传递方式：Authorization: Bearer <token>                    │
│  校验方：Authenticate 中间件                                 │
│  特点：短期有效、无状态，泄露影响范围有限                    │
├─────────────────────────────────────────────────────────────┤
│                    refresh_token                             │
│  用途：刷新令牌（仅在 access_token 过期时使用）              │
│  有效期：7 天（JWT_REFRESH_TTL=604800 秒）                   │
│  payload：type=refresh，含与 access 相同的 jti               │
│  传递方式：POST /api/refresh 请求体                          │
│  校验方：JwtService::refreshToken()（Redis jti 一次性校验）  │
│  特点：有状态（Redis）、可吊销、支持踢下线                   │
└─────────────────────────────────────────────────────────────┘
```

## 请求头格式

```text
Authorization: Bearer <access_token>
```

### 示例

```bash
# curl
curl http://localhost:8000/api/user/page \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

# curl（带分页参数）
curl "http://localhost:8000/api/user/page?pageNo=1&pageSize=10" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
```

### 请求头配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `jwt.header_prefix` | `Bearer ` | 请求头前缀（注意有尾部空格，`config/jwt.php`） |

## Token 获取

### 登录获取（主入口）

```bash
POST /api/login
Content-Type: application/json

{
    "username": "admin",
    "password": "123456",
    "code": "a3Bx",
    "key": "captcha_key_xxx"
}
```

**成功响应：**

```json
{
    "code": 0,
    "ok": true,
    "msg": "登录成功",
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "token_type": "Bearer",
        "expires_in": 7200,
        "user": {
            "id": 1,
            "username": "admin",
            "realname": "管理员",
            "avatar": "user/avatar/20260923/100429_e8FAKf9r.png"
        }
    }
}
```

### OAuth2 密码模式获取

```bash
POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin&password=123456
```

### 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `access_token` | string | 访问令牌（用于接口认证） |
| `refresh_token` | string | 刷新令牌（用于换取新令牌） |
| `token_type` | string | 令牌类型（固定 `Bearer`） |
| `expires_in` | number | access_token 有效期（秒，默认 7200） |
| `user` | object | 用户基础信息（id、username、realname、avatar） |

:::tip 登录/刷新接口为 snake_case 特例
一般接口响应经驼峰自动转换（`create_time` → `createTime`）；登录、刷新等令牌接口由 `AuthController` 以 `success(..., true)` raw 返回，键名保持 snake_case，与前端 `data.access_token` 读取方式一致。
:::

## Token 刷新

access_token 过期后（code=401），使用 refresh_token 换取新令牌对：

### 接口信息

| 项目 | 说明 |
|------|------|
| URL（主入口） | `POST /api/refresh`（公开接口） |
| URL（OAuth2 兼容） | `POST /api/oauth2/token`（grant_type=refresh_token） |
| Content-Type | `application/json` 或 `application/x-www-form-urlencoded` |

### 请求示例

```bash
# 推荐：/api/refresh（JSON）
POST /api/refresh
Content-Type: application/json

{ "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }

# OAuth2 兼容（表单）
POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=eyJ0eXAiOi...
```

### 成功响应

```json
{
    "code": 0,
    "ok": true,
    "msg": "刷新成功",
    "data": {
        "access_token": "eyJ...（新access_token）",
        "refresh_token": "eyJ...（新refresh_token）",
        "token_type": "Bearer",
        "expires_in": 7200
    }
}
```

### 失败响应

| 场景 | code | msg |
|------|------|-----|
| 缺少 refresh_token | 1 | 缺少refresh_token |
| refresh_token 无效/类型错 | 1 | 无效的refresh_token |
| 旧令牌已用过（重放）/ 已吊销 | 1 | refresh_token已失效 |
| 用户不存在/禁用 | 1 | 用户不存在或已被禁用 |

## Token 有效性检查

### 接口信息

| 项目 | 说明 |
|------|------|
| URL | `GET /api/oauth2/check/token` |
| 权限 | 无需认证（公开接口） |

### 请求示例

```bash
# 通过请求头传递
GET /api/oauth2/check/token
Authorization: Bearer <access_token>

# 通过 URL 参数传递
GET /api/oauth2/check/token?token=<access_token>
```

### 成功响应（有效）

```json
{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": {
        "valid": true,
        "uid": 1,
        "exp": 1727007200
    }
}
```

### 失败响应（无效）

```json
{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": {
        "valid": false,
        "msg": "Expired token"
    }
}
```

## Token 吊销

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/logout` | POST | 认证组 | 登出：吊销当前 refresh_token（`revokeToken` 删除 Redis jti） |
| `/api/oauth2/remove/{token}` | DELETE | 认证组 | 吊销指定令牌 |

```bash
# 登出（携带 access_token）
POST /api/logout
Authorization: Bearer <access_token>
```

:::tip 真实吊销（Redis 有状态）
本项目 refresh_token 以 `refresh:{uid}:{jti}` 存于 Redis——登出即删除该键，旧 access_token 到期后**无法续签**；`JwtService::revokeAllTokens($userId)` 可一次性吊销用户全部令牌（踢下线、改密全端失效场景）。
:::

## URL 参数传递（SSO 场景）

前端路由守卫支持通过 URL 参数传递 Token，适用于 SSO 单点登录场景：

```text
http://localhost:8001/?token=<access_token>
```

**前端处理逻辑：**

```text
1. 路由守卫检测 URL 中的 token 参数
2. 将 token 存入 localStorage
3. 清除 URL 中的 token 参数（防止泄露）
4. 后续请求自动携带该 token
```

## 前端存储与使用

### 存储（摘自 `ui/src/store/modules/user.ts` 实际代码）

```typescript
// 登录成功后存储（仅 access_token）
const ex = 7 * 24 * 60 * 60 * 1000;
storage.set(ACCESS_TOKEN, data.access_token, ex);   // 键名 'ACCESS-TOKEN'

// 登出时清除（userStore.logout）
storage.remove(ACCESS_TOKEN);
storage.remove(CURRENT_USER);
storage.clear();
```

### 请求拦截器（自动携带，摘自 `ui/src/utils/http/axios/index.ts`）

```typescript
const token = storage.get('ACCESS-TOKEN', '');
config.headers['Authorization'] = `Bearer ${token}`;
```

### 响应拦截器（401 处理，摘自 `ui/src/utils/http/axios/index.ts`）

```typescript
// code === 401（ResultEnum.TIMEOUT）
case ResultEnum.TIMEOUT:
  if (router.currentRoute.value?.name === PageEnum.BASE_LOGIN_NAME) return;
  ElMessageBox.confirm('登录身份已失效，请重新登录!', '提示', {
    type: 'warning',
  })
    .then(() => {
      storage.clear();
      window.location.href = PageEnum.BASE_LOGIN;   // '/login'
    })
    .catch(() => {});
  break;
```

### SSO 场景（URL 参数传递 Token）

路由守卫检测 `?token=` 参数并写入存储（摘自 `ui/src/router/router-guards.ts` 实际代码）：

```typescript
if (to.query && 'token' in to.query) {
  const tokenVal = String(to.query.token);
  storage.set(ACCESS_TOKEN, tokenVal);
  userStore.setToken(tokenVal);
}
```

## Token Payload 结构

### access_token

```json
{
    "uid": 1,
    "username": "admin",
    "type": "access",
    "jti": "550e8400-e29b-41d4-a716-446655440000",
    "iss": "rxthinkcmf",
    "iat": 1727000000,
    "exp": 1727007200
}
```

### refresh_token

```json
{
    "uid": 1,
    "username": "admin",
    "type": "refresh",
    "jti": "550e8400-e29b-41d4-a716-446655440000",
    "iss": "rxthinkcmf",
    "iat": 1727000000,
    "exp": 1727604800
}
```

（同一登录的两个令牌共享 `jti`，Redis 键 `refresh:{uid}:{jti}`。）

## 错误响应汇总

| 场景 | HTTP 状态 | code | msg |
|------|----------|------|-----|
| 未提供 Token | 200 | 401 | 未提供认证令牌 |
| Token 过期 | 200 | 401 | Expired token |
| Token 签名无效 | 200 | 401 | Signature verification failed |
| Token 类型错误（refresh 当 access 用） | 200 | 401 | 无效的access_token |
| 无权限 | **403** | 403 | 无访问权限：{权限码} |
| refresh_token 无效/类型错 | 200 | 1 | 无效的refresh_token |
| refresh_token 已用/已吊销 | 200 | 1 | refresh_token已失效 |

## 配置项

| 配置键（`config/jwt.php`） | 环境变量 | 默认值 | 说明 |
|--------|---------|--------|------|
| `jwt.secret` | `JWT_SECRET` | （必填） | JWT 签名密钥，**必须 ≥ 32 字符，否则拒绝启动** |
| `jwt.access_ttl` | `JWT_ACCESS_TTL` | `7200` | access_token 有效期（秒） |
| `jwt.refresh_ttl` | `JWT_REFRESH_TTL` | `604800` | refresh_token 有效期（秒） |
| `jwt.perms_ttl` | `JWT_PERMS_TTL` | `7200` | 权限缓存 TTL（秒） |
| `jwt.issuer` | `JWT_ISSUER` | `rxthinkcmf` | 签发者标识 |
| `jwt.header_prefix` | — | `Bearer ` | 请求头前缀 |

:::warning 生产环境安全
生产环境务必通过 `.env` 设置 `JWT_SECRET` 为 ≥32 字符的强随机密钥（**不满足应用拒绝启动**）：

```bash
openssl rand -base64 32
# 或
php -r "echo bin2hex(random_bytes(32));"
```
:::