# 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. **设备列表管理**：可查看在线设备并强制下线