添加 IM 系统鉴权与 Token 安全规范文档

2026-01-30 21:37:11 +08:00
parent 3841c41bc2
commit a7848bac9b
1 changed files with 115 additions and 0 deletions
@@ -0,0 +1,115 @@
+# IM 系统鉴权与 Token 安全规范文档
+
+## 1. 概述
+
+本规范用于确保系统用户身份验证、消息安全和多端同步安全。
+ 鉴权体系采用 **Token（JWT 或自定义） + HTTPS/WebSocket** 方式。
+
+------
+
+## 2. 鉴权方式选择
+
+| 方法                                   |
+| -------------------------------------- |
+| JWT（JSON Web Token）+ Redis黑名单机制 |
+
+------
+
+## 3. Token 生成规则
+
+### 3.1 Token 内容结构（JWT 示例）
+
+```
+{
+  "userId": 1001,            // 用户ID
+  "iat": 1700000000,         // 签发时间（Unix时间戳）
+  "exp": 1700003600,         // 过期时间
+  "deviceId": "uuid-xxxx",   // 设备ID，用于多端区分
+  "role": "user"             // 角色
+}
+```
+
+- **签名算法**：HMAC-SHA256 或 RSA
+- **签名秘钥**：服务端统一管理，不暴露给客户端
+
+------
+
+### 3.2 Token 生成流程
+
+1. 用户登录（用户名/密码）
+2. 验证用户名与密码正确
+3. 生成 Token，写入 Redis（可选）
+4. 返回 Token 给客户端
+
+**响应示例**：
+
+```
+{
+  "code": 0,
+  "message": "登录成功",
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+------
+
+## 4. Token 使用
+
+### 4.1 HTTP 接口鉴权
+
+- 客户端请求带上 Header：
+
+```
+Authorization: Bearer <token>
+```
+
+- 后端解析 Token：
+  1. 校验签名
+  2. 校验 exp 是否过期
+  3. 校验 Redis 黑名单（可选）
+- 不通过返回 401 / code 1006
+
+------
+
+### 4.2 WebSocket 鉴权
+
+- 建立连接时通过 Query 或 Header 传 Token：
+
+```
+ws://example.com/ws?token=xxxx&deviceId=uuid-001
+```
+
+- 握手阶段：
+  1. 服务器验证 Token
+  2. 成功返回 AUTH_SUCCESS
+  3. 失败返回 AUTH_FAIL 并关闭连接
+
+------
+
+## 5. Token 过期策略
+
+| 类型               | 建议值                 | 说明                                     |
+| ------------------ | ---------------------- | ---------------------------------------- |
+| 短期 Token         | 30 分钟 ~ 1 小时       | 防止长时间泄露                           |
+| 长期 Refresh Token | 7 ~ 30 天              | 用于获取新 Token，安全性高               |
+| WebSocket 长连接   | Token 与短期有效期一致 | 客户端定期刷新 Token（心跳或重连时验证） |
+
+### 5.1 Token 刷新流程
+
+1. 客户端 Token 快过期时，调用刷新接口
+2. 服务端验证 Refresh Token
+3. 返回新 Token，更新 Redis / 黑名单
+
+------
+
+## 6. 多端登录处理
+
+- **每个设备对应一个 deviceId**
+- Token 中绑定 deviceId
+- 多端策略：
+  1. **允许多端同时登录**：每端单独维护 Token
+  2. **限制单端登录**：新登录覆盖旧设备 Token
+  3. **设备列表管理**：可查看在线设备并强制下线
+