532 lines
21 KiB
Markdown
532 lines
21 KiB
Markdown
# 8.6 Token 使用说明
|
||
|
||
:::tip 概述
|
||
系统采用 JWT 双令牌认证，access_token 用于接口认证（2小时），refresh_token 用于刷新令牌（7天）。所有需认证的接口必须在请求头中携带 access_token。
|
||
:::
|
||
|
||
## Token 完整生命周期
|
||
|
||
### 登录获取 Token
|
||
|
||
```text
|
||
用户输入账号密码
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：POST /api/login │
|
||
│ { username, password, code, key } │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 后端：LoginController → LoginLogic → JwtService │
|
||
│ │
|
||
│ 1. CaptchaService::check() 验证码校验 │
|
||
│ 2. User::where('username') 查询用户 │
|
||
│ 3. PasswordService::verify() 密码校验 │
|
||
│ 4. Jwt::createAccessToken() 签发 access_token（2小时） │
|
||
│ Jwt::createRefreshToken() 签发 refresh_token（7天） │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 响应： │
|
||
│ { │
|
||
│ "accessToken": "eyJ...", ← 用于接口认证 │
|
||
│ "refreshToken": "eyJ...", ← 用于刷新令牌 │
|
||
│ "tokenType": "Bearer", │
|
||
│ "expiresIn": 7200, ← 2小时 = 7200秒 │
|
||
│ "user": { "id":1, "username":"admin" } │
|
||
│ } │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：存储 Token │
|
||
│ │
|
||
│ localStorage.setItem('access_token', accessToken) │
|
||
│ localStorage.setItem('refresh_token', refreshToken) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 使用 Token 请求 API
|
||
|
||
```text
|
||
用户操作（如点击"用户列表"）
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：请求拦截器 │
|
||
│ │
|
||
│ const token = localStorage.getItem('access_token') │
|
||
│ config.headers['Authorization'] = `Bearer ${token}` │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ GET /api/user/page?pageNo=1&pageSize=10 │
|
||
│ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 后端：AuthMiddleware │
|
||
│ │
|
||
│ 1. Jwt::getTokenFromHeader() 从请求头提取 Token │
|
||
│ │ 空 → 返回 401 "未提供认证令牌" │
|
||
│ ▼ │
|
||
│ 2. Jwt::decode($token) 解码并校验签名+有效期 │
|
||
│ │ 过期 → 返回 401 "token已过期" │
|
||
│ │ 签名无效 → 返回 401 "token签名无效" │
|
||
│ ▼ │
|
||
│ 3. $decoded->type === 'access' 校验 Token 类型 │
|
||
│ │ 非 access → 返回 401 "无效的认证令牌" │
|
||
│ ▼ │
|
||
│ 4. $request->userInfo = $decoded 注入用户信息 │
|
||
│ ▼ │
|
||
│ 5. checkPermission() 权限校验 │
|
||
│ │ 无权限 → 返回 403 "无访问权限" │
|
||
│ ▼ │
|
||
│ 6. 放行 → Controller → Logic → Model → 响应 │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：响应拦截器 │
|
||
│ │
|
||
│ code === 0 → 返回 data（成功） │
|
||
│ code === 401 → Token 过期，尝试刷新 │
|
||
│ code === 403 → 提示"无访问权限" │
|
||
│ 其他 → 提示 msg │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Token 过期自动刷新
|
||
|
||
```text
|
||
前端请求 API → 后端返回 code=401 "token已过期"
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：响应拦截器检测到 401 │
|
||
│ │
|
||
│ if (code === 401 && !config._retry) { │
|
||
│ // 尝试用 refresh_token 刷新 │
|
||
│ } │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：POST /api/oauth2/token │
|
||
│ { grant_type: "refresh_token", refresh_token: "eyJ..." } │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 后端：JwtService::refreshToken() │
|
||
│ │
|
||
│ 1. Jwt::decode(refreshToken) 解码 refresh_token │
|
||
│ │ 无效/过期 → 返回错误 │
|
||
│ ▼ │
|
||
│ 2. $decoded->type === 'refresh' 校验必须为 refresh 类型 │
|
||
│ │ 非 refresh → 返回错误 │
|
||
│ ▼ │
|
||
│ 3. User::find($decoded->uid) 校验用户仍存在且状态正常 │
|
||
│ │ 不存在/禁用 → 返回错误 │
|
||
│ ▼ │
|
||
│ 4. 签发新 access_token + 新 refresh_token │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：更新存储 + 重试原请求 │
|
||
│ │
|
||
│ localStorage.setItem('access_token', newAccessToken) │
|
||
│ localStorage.setItem('refresh_token', newRefreshToken) │
|
||
│ │
|
||
│ // 用新 Token 重试原失败请求 │
|
||
│ config.headers['Authorization'] = `Bearer ${newAccessToken}`│
|
||
│ return axios(config) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Token 刷新失败（重新登录）
|
||
|
||
```text
|
||
前端请求 API → 后端返回 code=401
|
||
│
|
||
▼
|
||
尝试用 refresh_token 刷新
|
||
│
|
||
▼
|
||
刷新失败（refresh_token 也过期/无效）
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端：清除登录态，跳转登录页 │
|
||
│ │
|
||
│ localStorage.removeItem('access_token') │
|
||
│ localStorage.removeItem('refresh_token') │
|
||
│ window.location.href = '/login' │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 两种 Token 的区别
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ access_token │
|
||
│ │
|
||
│ 用途：接口认证（每个 API 请求携带） │
|
||
│ 有效期：2 小时（7200 秒） │
|
||
│ payload.type：access │
|
||
│ 传递方式：Authorization: Bearer <token> │
|
||
│ 校验方：AuthMiddleware │
|
||
│ 特点：短期有效，泄露影响范围有限 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ refresh_token │
|
||
│ │
|
||
│ 用途：刷新令牌（仅在 access_token 过期时使用） │
|
||
│ 有效期：7 天（604800 秒） │
|
||
│ payload.type：refresh │
|
||
│ 传递方式：POST /api/oauth2/token 请求体 │
|
||
│ 校验方：JwtService::refreshToken() │
|
||
│ 特点：长期有效，仅用于换取新令牌，不用于接口认证 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 请求头格式
|
||
|
||
```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_name` | `Authorization` | 请求头名称 |
|
||
| `jwt.header_prefix` | `Bearer ` | 请求头前缀（注意有空格） |
|
||
|
||
## 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": {
|
||
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||
"refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||
"tokenType": "Bearer",
|
||
"expiresIn": 7200,
|
||
"user": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"realname": "管理员",
|
||
"avatar": "/uploads/user/avatar/avatar.jpg"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### OAuth2 密码模式获取
|
||
|
||
```bash
|
||
POST /api/oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
grant_type=password&username=admin&password=123456
|
||
```
|
||
|
||
### 响应字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `accessToken` | string | 访问令牌（用于接口认证） |
|
||
| `refreshToken` | string | 刷新令牌（用于换取新令牌） |
|
||
| `tokenType` | string | 令牌类型（固定 `Bearer`） |
|
||
| `expiresIn` | number | access_token 有效期（秒，默认 7200） |
|
||
| `user` | object | 用户基础信息（id、username、realname、avatar） |
|
||
|
||
## Token 刷新
|
||
|
||
access_token 过期后（响应 code=401），使用 refresh_token 换取新令牌对：
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| URL | `POST /api/oauth2/token` |
|
||
| Content-Type | `application/json` 或 `application/x-www-form-urlencoded` |
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
# JSON 格式
|
||
POST /api/oauth2/token
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"grant_type": "refresh_token",
|
||
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
|
||
}
|
||
|
||
# 表单格式
|
||
POST /api/oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
grant_type=refresh_token&refresh_token=eyJ0eXAiOi...
|
||
```
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"ok": true,
|
||
"msg": "success",
|
||
"data": {
|
||
"accessToken": "eyJ...(新access_token)",
|
||
"refreshToken": "eyJ...(新refresh_token)",
|
||
"tokenType": "Bearer",
|
||
"expiresIn": 7200
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败响应
|
||
|
||
| 场景 | code | msg |
|
||
|------|------|-----|
|
||
| 缺少 refresh_token | 1 | 缺少refresh_token参数 |
|
||
| 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": "token已过期"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Token 吊销
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| URL | `DELETE /api/oauth2/remove/{token}` |
|
||
|
||
```bash
|
||
DELETE /api/oauth2/remove/eyJ0eXAiOi...
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
:::warning 简化实现
|
||
当前 Token 吊销为简化实现（直接返回 true），JWT 本身无状态，服务端无法直接使其失效。生产环境建议结合 Redis 黑名单机制实现真正的吊销。
|
||
:::
|
||
|
||
## URL 参数传递（SSO 场景）
|
||
|
||
路由守卫支持通过 URL 参数传递 Token，适用于 SSO 单点登录场景：
|
||
|
||
```html
|
||
http://localhost:8001/?token=<access_token>
|
||
```
|
||
|
||
**前端处理逻辑：**
|
||
|
||
```text
|
||
1. 路由守卫检测 URL 中的 token 参数
|
||
2. 将 token 存入 localStorage
|
||
3. 清除 URL 中的 token 参数（防止泄露）
|
||
4. 后续请求自动携带该 token
|
||
```
|
||
|
||
## 前端存储与使用
|
||
|
||
### 存储
|
||
|
||
```typescript
|
||
// 登录后存储
|
||
localStorage.setItem('access_token', data.accessToken);
|
||
localStorage.setItem('refresh_token', data.refreshToken);
|
||
|
||
// 登出时清除
|
||
localStorage.removeItem('access_token');
|
||
localStorage.removeItem('refresh_token');
|
||
```
|
||
|
||
### 请求拦截器（自动携带）
|
||
|
||
```typescript
|
||
// src/utils/http/axios/index.ts
|
||
axios.interceptors.request.use(config => {
|
||
const token = localStorage.getItem('access_token');
|
||
if (token) {
|
||
config.headers['Authorization'] = `Bearer ${token}`;
|
||
}
|
||
return config;
|
||
});
|
||
```
|
||
|
||
### 响应拦截器（自动刷新）
|
||
|
||
```typescript
|
||
axios.interceptors.response.use(
|
||
response => response,
|
||
async error => {
|
||
const { config, response } = error;
|
||
|
||
if (response?.status === 401 && !config._retry) {
|
||
config._retry = true;
|
||
|
||
const refreshToken = localStorage.getItem('refresh_token');
|
||
if (refreshToken) {
|
||
try {
|
||
// 尝试刷新 Token
|
||
const res = await refreshTokenApi(refreshToken);
|
||
localStorage.setItem('access_token', res.data.accessToken);
|
||
localStorage.setItem('refresh_token', res.data.refreshToken);
|
||
|
||
// 用新 Token 重试原请求
|
||
config.headers['Authorization'] = `Bearer ${res.data.accessToken}`;
|
||
return axios(config);
|
||
} catch (e) {
|
||
// 刷新失败，跳转登录
|
||
localStorage.clear();
|
||
window.location.href = '/login';
|
||
}
|
||
}
|
||
}
|
||
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
```
|
||
|
||
## Token Payload 结构
|
||
|
||
### access_token
|
||
|
||
```json
|
||
{
|
||
"uid": 1,
|
||
"username": "admin",
|
||
"type": "access",
|
||
"iss": "rxthinkcmf",
|
||
"iat": 1727000000,
|
||
"exp": 1727007200
|
||
}
|
||
```
|
||
|
||
### refresh_token
|
||
|
||
```json
|
||
{
|
||
"uid": 1,
|
||
"username": "admin",
|
||
"type": "refresh",
|
||
"iss": "rxthinkcmf",
|
||
"iat": 1727000000,
|
||
"exp": 1727604800
|
||
}
|
||
```
|
||
|
||
## 错误响应汇总
|
||
|
||
| 场景 | HTTP 状态 | code | msg |
|
||
|------|----------|------|-----|
|
||
| 未提供 Token | 200 | 401 | 未提供认证令牌 |
|
||
| Token 过期 | 200 | 401 | token已过期 |
|
||
| Token 签名无效 | 200 | 401 | token签名无效 |
|
||
| Token 类型错误 | 200 | 401 | 无效的认证令牌 |
|
||
| 无权限 | 200 | 403 | 无访问权限 |
|
||
|
||
## 配置项
|
||
|
||
| 配置键 | 环境变量 | 默认值 | 说明 |
|
||
|--------|---------|--------|------|
|
||
| `jwt.secret` | `JWT.SECRET` | 内置默认密钥 | JWT 签名密钥，**生产环境务必修改** |
|
||
| `jwt.access_ttl` | `JWT.ACCESS_TTL` | `7200` | access_token 有效期（秒） |
|
||
| `jwt.refresh_ttl` | `JWT.REFRESH_TTL` | `604800` | refresh_token 有效期（秒） |
|
||
| `jwt.issuer` | — | `rxthinkcmf` | 签发者标识 |
|
||
| `jwt.header_name` | — | `Authorization` | 请求头名称 |
|
||
| `jwt.header_prefix` | — | `Bearer ` | 请求头前缀 |
|
||
|
||
:::warning 生产环境安全
|
||
生产环境务必通过 `.env` 设置 `JWT.SECRET` 为强随机密钥：
|
||
```bash
|
||
php -r "echo bin2hex(random_bytes(32));"
|
||
```
|
||
:::
|