feat(login, zulip): 引入 JWT 验证并重构 API 密钥管理
### 详细变更描述 * **修复 JWT 签名冲突**：重构 `LoginService.generateTokenPair()`，移除载荷（Payload）中的 `iss` (issuer) 与 `aud` (audience) 字段，解决签名校验失败的问题。 * **统一验证逻辑**：更新 `ZulipService` 以调用 `LoginService.verifyToken()`，消除重复的 JWT 校验代码，确保逻辑单一职责化（Single Responsibility）。 * **修复硬编码 API 密钥问题**：消息发送功能不再依赖静态配置，改为从 Redis 动态读取用户真实的 API 密钥。 * **解耦依赖注入**：在 `ZulipModule` 中注入 `AuthModule` 依赖，以支持标准的 Token 验证流程。 * **完善技术文档**：补充了关于 JWT 验证流程及 API 密钥管理逻辑的详细文档。 * **新增测试工具**：添加 `test-get-messages.js` 脚本，用于验证通过 WebSocket 接收消息的功能。 * **更新自动化脚本**：同步更新了 API 密钥验证及用户注册校验的快速测试脚本。 * **端到端功能验证**：确保消息发送逻辑能够正确映射并调用用户真实的 Zulip API 密钥。
This commit is contained in:
angjustinl
@@ -68,4 +68,149 @@ C. 接收消息 (Downstream: Zulip -> Node -> Godot)
|
||||
- Zulip API Key 永不下发: 用户的 Zulip 凭证永远只保存在服务器端。如果客户端直接拿 Key，黑客可以通过解包 Godot 拿到 Key 然后去 Zulip 乱发消息。
|
||||
- 位置欺诈完全消除: 因为 Stream 的选择权在 Node 手里，玩家无法做到“人在新手村，却往高等级区域频道发消息”。
|
||||
3. 协议统一:
|
||||
- 不再需要处理 HTTP (Zulip) 和 WebSocket (Game) 两种并发逻辑。网络层代码减少一半。
|
||||
- 不再需要处理 HTTP (Zulip) 和 WebSocket (Game) 两种并发逻辑。网络层代码减少一半。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3. JWT Token 验证和 API Key 管理 (v1.1.0 更新)
|
||||
|
||||
### 3.1 用户注册和 API Key 生成流程
|
||||
|
||||
当用户注册游戏账号时，系统会自动创建对应的 Zulip 账号并获取 API Key：
|
||||
|
||||
```
|
||||
用户注册 (POST /auth/register)
|
||||
↓
|
||||
1. 创建游戏账号 (LoginService.register)
|
||||
↓
|
||||
2. 初始化 Zulip 管理员客户端
|
||||
↓
|
||||
3. 创建 Zulip 账号 (ZulipAccountService.createZulipAccount)
|
||||
- 使用相同的邮箱和密码
|
||||
- 调用 Zulip API: POST /api/v1/users
|
||||
↓
|
||||
4. 获取 API Key (ZulipAccountService.generateApiKeyForUser)
|
||||
- 使用 fetch_api_key 端点（固定的、基于密码的 Key）
|
||||
- 注意：不使用 regenerate_api_key（会生成新 Key）
|
||||
↓
|
||||
5. 加密存储 API Key (ApiKeySecurityService.storeApiKey)
|
||||
- 使用 AES-256-GCM 加密
|
||||
- 存储到 Redis: zulip:api_key:{userId}
|
||||
↓
|
||||
6. 创建账号关联记录 (ZulipAccountsRepository)
|
||||
- 存储 gameUserId ↔ zulipUserId 映射
|
||||
↓
|
||||
7. 生成 JWT Token (LoginService.generateTokenPair)
|
||||
- 包含用户信息：sub, username, email, role
|
||||
- 返回 access_token 和 refresh_token
|
||||
```
|
||||
|
||||
### 3.2 JWT Token 验证流程
|
||||
|
||||
当用户通过 WebSocket 登录游戏时，系统会验证 JWT Token 并获取 API Key：
|
||||
|
||||
```
|
||||
WebSocket 登录 (login 消息)
|
||||
↓
|
||||
1. ZulipService.validateGameToken(token)
|
||||
↓
|
||||
2. 调用 LoginService.verifyToken(token, 'access')
|
||||
- 验证签名、过期时间、载荷
|
||||
- 提取用户信息：userId, username, email
|
||||
↓
|
||||
3. 从 Redis 获取 API Key (ApiKeySecurityService.getApiKey)
|
||||
- 解密存储的 API Key
|
||||
- 更新访问计数和时间
|
||||
↓
|
||||
4. 创建 Zulip 客户端 (ZulipClientPoolService.createUserClient)
|
||||
- 使用真实的用户 API Key
|
||||
- 注册事件队列
|
||||
↓
|
||||
5. 创建游戏会话 (SessionManagerService.createSession)
|
||||
- 绑定 socketId ↔ zulipQueueId
|
||||
- 记录用户位置信息
|
||||
↓
|
||||
6. 返回登录成功
|
||||
```
|
||||
|
||||
### 3.3 消息发送流程（使用正确的 API Key）
|
||||
|
||||
```
|
||||
发送聊天消息 (chat 消息)
|
||||
↓
|
||||
1. ZulipService.sendChatMessage()
|
||||
↓
|
||||
2. 获取会话信息 (SessionManagerService.getSession)
|
||||
- 获取 userId 和当前位置
|
||||
↓
|
||||
3. 上下文注入 (SessionManagerService.injectContext)
|
||||
- 根据位置确定目标 Stream/Topic
|
||||
↓
|
||||
4. 消息验证 (MessageFilterService.validateMessage)
|
||||
- 内容过滤、频率限制
|
||||
↓
|
||||
5. 发送到 Zulip (ZulipClientPoolService.sendMessage)
|
||||
- 使用用户的真实 API Key
|
||||
- 调用 Zulip API: POST /api/v1/messages
|
||||
↓
|
||||
6. 返回发送结果
|
||||
```
|
||||
|
||||
### 3.4 关键修复说明
|
||||
|
||||
**问题 1: JWT Token 签名冲突**
|
||||
- **原因**: payload 中包含 `iss` 和 `aud`，但 `jwtService.signAsync()` 也通过 options 传递这些值
|
||||
- **修复**: 从 payload 中移除 `iss` 和 `aud`，只通过 options 传递
|
||||
- **文件**: `src/business/auth/services/login.service.ts`
|
||||
|
||||
**问题 2: 使用硬编码的旧 API Key**
|
||||
- **原因**: `ZulipService.validateGameToken()` 使用硬编码的测试 API Key
|
||||
- **修复**: 从 Redis 读取用户注册时存储的真实 API Key
|
||||
- **文件**: `src/business/zulip/zulip.service.ts`
|
||||
|
||||
**问题 3: 重复实现 JWT 验证逻辑**
|
||||
- **原因**: `ZulipService` 自己实现了 JWT 解析
|
||||
- **修复**: 复用 `LoginService.verifyToken()` 方法
|
||||
- **文件**: `src/business/zulip/zulip.service.ts`, `src/business/zulip/zulip.module.ts`
|
||||
|
||||
### 3.5 API Key 安全机制
|
||||
|
||||
**加密存储**:
|
||||
- 使用 AES-256-GCM 算法加密
|
||||
- 加密密钥从环境变量 `ZULIP_API_KEY_ENCRYPTION_KEY` 读取
|
||||
- 存储格式：`{encryptedKey, iv, authTag, createdAt, updatedAt, accessCount}`
|
||||
|
||||
**访问控制**:
|
||||
- 频率限制：每分钟最多 60 次访问
|
||||
- 访问日志：记录每次访问的时间和次数
|
||||
- 安全事件：记录所有关键操作（存储、访问、更新、删除）
|
||||
|
||||
**环境变量配置**:
|
||||
```bash
|
||||
# 生成 64 字符的十六进制密钥（32 字节 = 256 位）
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
|
||||
# 在 .env 文件中配置
|
||||
ZULIP_API_KEY_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
|
||||
```
|
||||
|
||||
### 3.6 测试验证
|
||||
|
||||
使用测试脚本验证功能：
|
||||
|
||||
```bash
|
||||
# 测试注册用户的 Zulip 集成
|
||||
node docs/systems/zulip/quick_tests/test-registered-user.js
|
||||
|
||||
# 验证 API Key 一致性
|
||||
node docs/systems/zulip/quick_tests/verify-api-key.js
|
||||
```
|
||||
|
||||
**预期结果**:
|
||||
- ✅ WebSocket 连接成功
|
||||
- ✅ JWT Token 验证通过
|
||||
- ✅ 从 Redis 获取正确的 API Key
|
||||
- ✅ 消息成功发送到 Zulip
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user