8ef45f53f1
- 注册时Zulip账号创建改为异步，不阻塞注册流程 - 新增带3次重试和递增延迟的createZulipAccountWithRetry方法 - Zulip失败只记录日志，不影响用户注册成功 - 更新API文档，补充80+接口覆盖聊天/通知/位置等模块 - 添加.claude/和test-*.ps1到.gitignore Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
41 KiB
Whale Town 像素游戏服务器 API 文档
版本: 2.0.0
更新时间: 2026-01-20
<EFBFBD> 目录
概述
Whale Town 像素游戏服务器提供完整的 RESTful API 和 WebSocket 实时通信接口，支持：
- 用户认证与授权（JWT）
- 实时聊天和位置广播
- 管理员后台管理
- Zulip 第三方集成
- 通知推送系统
基础URL: https://whaletownend.xinghangee.icu
WebSocket URL: wss://whaletownend.xinghangee.icu/game
认证机制
JWT Token 认证
大部分接口需要在请求头中携带 JWT Token：
Authorization: Bearer <your_jwt_token>
Token 获取方式
- 用户登录：
POST /auth/login - 用户注册：
POST /auth/register - GitHub OAuth：
POST /auth/github - 验证码登录：
POST /auth/verification-code-login
Token 刷新
使用刷新令牌获取新的访问令牌：POST /auth/refresh-token
通用响应格式
成功响应
{
"success": true,
"data": { ... },
"message": "操作成功"
}
错误响应
{
"success": false,
"message": "错误描述",
"error_code": "ERROR_CODE"
}
错误代码说明
| 错误代码 | HTTP状态码 | 说明 |
|---|---|---|
| LOGIN_FAILED | 401 | 登录失败（用户名或密码错误） |
| REGISTER_FAILED | 400/409 | 注册失败（参数错误或用户已存在） |
| TOKEN_REFRESH_FAILED | 401 | Token刷新失败 |
| VERIFICATION_CODE_LOGIN_FAILED | 401 | 验证码登录失败 |
| SEND_CODE_FAILED | 400/404 | 验证码发送失败 |
| RESET_PASSWORD_FAILED | 400 | 密码重置失败 |
| CHANGE_PASSWORD_FAILED | 400/401 | 密码修改失败 |
| TEST_MODE_ONLY | 206 | 测试模式（验证码未真实发送） |
| ADMIN_LOGIN_FAILED | 401/403 | 管理员登录失败 |
| USER_NOT_FOUND | 404 | 用户不存在 |
| TOO_MANY_REQUESTS | 429 | 请求过于频繁 |
API接口列表
应用状态
获取应用状态
接口: GET /
描述: 获取应用的基本运行状态信息，用于健康检查和服务监控
认证: 不需要
响应示例:
{
"service": "Pixel Game Server",
"version": "2.0.0",
"status": "running",
"timestamp": "2026-01-20T10:00:00.000Z",
"uptime": 86400,
"environment": "production",
"storage_mode": "database"
}
用户认证
1. 用户登录
接口: POST /auth/login
描述: 支持用户名、邮箱或手机号登录
请求体:
{
"identifier": "testuser",
"password": "password123"
}
成功响应 (200):
{
"success": true,
"data": {
"user": {
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com",
"phone": null,
"avatar_url": null,
"role": 1,
"created_at": "2026-01-20T10:00:00.000Z"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"is_new_user": false,
"message": "登录成功"
},
"message": "登录成功"
}
错误响应:
401: 用户名或密码错误403: 账户被禁用或锁定429: 登录尝试过于频繁
2. 用户注册
接口: POST /auth/register
描述: 创建新用户账户，支持邮箱验证
请求体（基础注册）:
{
"username": "newuser",
"password": "password123",
"nickname": "新用户"
}
请求体（带邮箱验证）:
{
"username": "newuser",
"password": "password123",
"nickname": "新用户",
"email": "newuser@example.com",
"email_verification_code": "123456"
}
成功响应 (201):
{
"success": true,
"data": {
"user": {
"id": "2",
"username": "newuser",
"nickname": "新用户",
"email": "newuser@example.com",
"phone": null,
"avatar_url": null,
"role": 1,
"created_at": "2026-01-20T10:00:00.000Z"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"is_new_user": true,
"message": "注册成功"
},
"message": "注册成功"
}
错误响应:
400: 验证码错误或参数错误409: 用户名或邮箱已存在429: 注册请求过于频繁
3. GitHub OAuth 登录
接口: POST /auth/github
描述: 使用 GitHub 账户登录或注册
请求体:
{
"github_id": "12345678",
"username": "octocat",
"nickname": "The Octocat",
"email": "octocat@github.com",
"avatar_url": "https://github.com/images/error/octocat_happy.gif"
}
成功响应 (200):
{
"success": true,
"data": {
"user": {
"id": "3",
"username": "octocat",
"nickname": "The Octocat",
"email": "octocat@github.com",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"role": 1,
"created_at": "2026-01-20T10:00:00.000Z"
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"is_new_user": false,
"message": "GitHub登录成功"
},
"message": "GitHub登录成功"
}
4. 验证码登录
接口: POST /auth/verification-code-login
描述: 使用邮箱或手机号和验证码进行登录，无需密码
请求体:
{
"identifier": "test@example.com",
"verification_code": "123456"
}
成功响应 (200):
{
"success": true,
"data": {
"user": { ... },
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"is_new_user": false,
"message": "验证码登录成功"
},
"message": "验证码登录成功"
}
错误响应:
401: 验证码错误或已过期404: 用户不存在
5. 发送登录验证码
接口: POST /auth/send-login-verification-code
描述: 向用户邮箱或手机发送登录验证码
请求体:
{
"identifier": "test@example.com"
}
成功响应 (200) - 生产环境:
{
"success": true,
"data": {
"is_test_mode": false
},
"message": "验证码已发送，请查收"
}
测试模式响应 (206) - 开发环境:
{
"success": false,
"data": {
"verification_code": "654321",
"is_test_mode": true
},
"message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码。",
"error_code": "TEST_MODE_ONLY"
}
错误响应:
404: 用户不存在429: 发送频率过高
6. 发送邮箱验证码
接口: POST /auth/send-email-verification
描述: 向指定邮箱发送验证码（用于注册）
请求体:
{
"email": "test@example.com"
}
成功响应 (200):
{
"success": true,
"data": {
"is_test_mode": false
},
"message": "验证码已发送，请查收邮件"
}
错误响应:
409: 邮箱已被注册429: 验证码发送过于频繁
7. 验证邮箱验证码
接口: POST /auth/verify-email
描述: 使用验证码验证邮箱
请求体:
{
"email": "test@example.com",
"verification_code": "123456"
}
成功响应 (200):
{
"success": true,
"message": "邮箱验证成功"
}
错误响应:
400: 验证码错误或已过期
8. 重新发送邮箱验证码
接口: POST /auth/resend-email-verification
描述: 重新向指定邮箱发送验证码
请求体:
{
"email": "test@example.com"
}
成功响应 (200):
{
"success": true,
"data": {
"is_test_mode": false
},
"message": "验证码已重新发送，请查收邮件"
}
错误响应:
400: 邮箱已验证，无需重复验证429: 发送频率过高
9. 发送密码重置验证码
接口: POST /auth/forgot-password
描述: 向用户邮箱或手机发送密码重置验证码
请求体:
{
"identifier": "test@example.com"
}
成功响应 (200):
{
"success": true,
"data": {
"is_test_mode": false
},
"message": "验证码已发送，请查收"
}
错误响应:
404: 用户不存在429: 发送频率过高
10. 重置密码
接口: POST /auth/reset-password
描述: 使用验证码重置用户密码
请求体:
{
"identifier": "test@example.com",
"verification_code": "789012",
"new_password": "newpassword123"
}
成功响应 (200):
{
"success": true,
"message": "密码重置成功"
}
错误响应:
400: 验证码错误或参数无效404: 用户不存在429: 重置请求过于频繁
11. 修改密码
接口: PUT /auth/change-password
描述: 用户修改自己的密码（需要提供旧密码）
请求体:
{
"user_id": "1",
"old_password": "oldpassword123",
"new_password": "newpassword123"
}
成功响应 (200):
{
"success": true,
"message": "密码修改成功"
}
错误响应:
400: 请求参数错误401: 旧密码不正确404: 用户不存在
12. 刷新访问令牌
接口: POST /auth/refresh-token
描述: 使用有效的刷新令牌生成新的访问令牌
请求体:
{
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
成功响应 (200):
{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600
},
"message": "令牌刷新成功"
}
错误响应:
401: 刷新令牌无效或已过期404: 用户不存在或已被禁用429: 刷新请求过于频繁
管理员接口
1. 管理员登录
接口: POST /admin/auth/login
描述: 管理员身份认证，仅允许 role=9 的账户登录
请求体:
{
"identifier": "admin",
"password": "Admin123456"
}
成功响应 (200):
{
"success": true,
"data": {
"admin": {
"id": "1",
"username": "admin",
"nickname": "管理员",
"role": 9
},
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 28800,
"message": "管理员登录成功"
},
"message": "管理员登录成功"
}
错误响应:
401: 用户名或密码错误403: 权限不足，需要管理员权限429: 登录尝试过于频繁
2. 获取用户列表
接口: GET /admin/users
描述: 分页获取系统中的用户列表
认证: 需要管理员 Token
查询参数:
limit(可选): 返回数量，默认100offset(可选): 偏移量，默认0
成功响应 (200):
{
"success": true,
"data": {
"users": [
{
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com",
"phone": null,
"role": 1,
"status": "active",
"email_verified": true,
"created_at": "2026-01-20T10:00:00.000Z",
"updated_at": "2026-01-20T10:00:00.000Z"
}
],
"pagination": {
"limit": 100,
"offset": 0,
"total": 1
}
},
"message": "用户列表获取成功"
}
3. 获取用户详情
接口: GET /admin/users/:id
描述: 根据用户ID获取指定用户的详细信息
认证: 需要管理员 Token
路径参数:
id: 用户ID
成功响应 (200):
{
"success": true,
"data": {
"user": {
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com",
"phone": null,
"role": 1,
"status": "active",
"email_verified": true,
"github_id": null,
"avatar_url": null,
"created_at": "2026-01-20T10:00:00.000Z",
"updated_at": "2026-01-20T10:00:00.000Z"
}
},
"message": "用户详情获取成功"
}
错误响应:
404: 用户不存在
4. 重置用户密码
接口: POST /admin/users/:id/reset-password
描述: 管理员直接为指定用户设置新密码
认证: 需要管理员 Token
路径参数:
id: 用户ID
请求体:
{
"newPassword": "newpassword123"
}
成功响应 (200):
{
"success": true,
"message": "用户密码重置成功"
}
错误响应:
400: 密码不符合强度规则404: 用户不存在429: 操作过于频繁
5. 获取运行时日志
接口: GET /admin/logs/runtime
描述: 从 logs/ 目录读取最近的日志行
认证: 需要管理员 Token
查询参数:
lines(可选): 返回行数，默认200，最大2000
成功响应 (200):
{
"success": true,
"data": {
"logs": [
"[2026-01-20 18:27:35] LOG [NestApplication] Nest application successfully started",
"[2026-01-20 18:27:35] LOG [RouterExplorer] Mapped {/, GET} route"
],
"total_lines": 2,
"timestamp": "2026-01-20T10:27:44.352Z"
},
"message": "运行时日志获取成功"
}
6. 下载全部运行日志
接口: GET /admin/logs/archive
描述: 将 logs/ 目录打包为 tar.gz 并下载
认证: 需要管理员 Token
响应: 二进制流（application/gzip）
用户管理
1. 修改用户状态
接口: PUT /admin/users/:id/status
描述: 管理员修改指定用户的账户状态
认证: 需要管理员 Token
路径参数:
id: 用户ID
请求体:
{
"status": "locked",
"reason": "违规操作"
}
支持的状态值:
active: 激活inactive: 未激活locked: 锁定banned: 禁用deleted: 已删除pending: 待审核
成功响应 (200):
{
"success": true,
"data": {
"user": {
"id": "1",
"username": "testuser",
"status": "locked",
"updated_at": "2026-01-20T10:00:00.000Z"
}
},
"message": "用户状态修改成功"
}
错误响应:
400: 状态值无效403: 权限不足404: 用户不存在429: 操作过于频繁
2. 批量修改用户状态
接口: POST /admin/users/batch-status
描述: 管理员批量修改多个用户的账户状态
认证: 需要管理员 Token
请求体:
{
"userIds": ["1", "2", "3"],
"status": "active",
"reason": "批量激活"
}
成功响应 (200):
{
"success": true,
"data": {
"updated_count": 3,
"failed_count": 0,
"results": [
{
"user_id": "1",
"success": true,
"new_status": "active"
},
{
"user_id": "2",
"success": true,
"new_status": "active"
},
{
"user_id": "3",
"success": true,
"new_status": "active"
}
]
},
"message": "批量状态修改完成"
}
3. 获取用户状态统计
接口: GET /admin/users/status-stats
描述: 获取各种用户状态的数量统计信息
认证: 需要管理员 Token
成功响应 (200):
{
"success": true,
"data": {
"stats": {
"active": 15,
"inactive": 3,
"locked": 2,
"banned": 1,
"deleted": 0,
"pending": 5
},
"total": 26
},
"message": "用户状态统计获取成功"
}
聊天系统
1. 获取聊天历史记录
接口: GET /chat/history
描述: 获取指定地图的聊天历史记录
认证: 需要 JWT Token
查询参数:
mapId(可选): 地图IDlimit(可选): 消息数量限制offset(可选): 偏移量
成功响应 (200):
{
"success": true,
"data": {
"messages": [
{
"id": "msg_123",
"userId": "1",
"username": "testuser",
"nickname": "测试用户",
"content": "Hello World",
"mapId": "map_001",
"timestamp": "2026-01-20T10:00:00.000Z"
}
],
"total": 100,
"limit": 50,
"offset": 0
}
}
2. 获取聊天系统状态
接口: GET /chat/status
描述: 获取聊天系统的运行状态和统计信息
认证: 不需要
成功响应 (200):
{
"websocket": {
"totalConnections": 150,
"authenticatedConnections": 120,
"activeSessions": 120,
"mapPlayerCounts": {
"map_001": 45,
"map_002": 38,
"map_003": 37
}
},
"zulip": {
"serverConnected": true,
"serverVersion": "11.4",
"botAccountActive": true,
"availableStreams": 12,
"gameStreams": ["Whale Port", "Pumpkin Valley", "Novice Village"],
"recentMessageCount": 156
},
"uptime": 86400,
"memory": {
"used": "128.5 MB",
"total": "256.0 MB",
"percentage": 50.2
}
}
3. 获取 WebSocket 连接信息
接口: GET /chat/websocket/info
描述: 获取 WebSocket 连接配置信息
认证: 不需要
成功响应 (200):
{
"websocketUrl": "wss://whaletownend.xinghangee.icu/game",
"protocol": "native-websocket",
"path": "/game",
"supportedEvents": ["login", "chat", "position"],
"supportedResponses": [
"connected",
"login_success",
"login_error",
"chat_sent",
"chat_error",
"chat_render",
"error"
],
"authRequired": true,
"tokenType": "JWT"
}
位置广播
1. 创建新会话
接口: POST /location-broadcast/sessions
描述: 创建一个新的游戏会话，用于多人位置广播
认证: 需要 JWT Token
请求体:
{
"sessionId": "session_12345",
"name": "测试会话",
"description": "这是一个测试会话",
"maxUsers": 50,
"allowObservers": true,
"password": "optional_password",
"allowedMaps": ["map_001", "map_002"],
"broadcastRange": 100,
"metadata": {
"custom_field": "value"
}
}
成功响应 (201):
{
"success": true,
"data": {
"sessionId": "session_12345",
"createdAt": 1641024000000,
"config": {
"maxUsers": 50,
"allowObservers": true,
"broadcastRange": 100
},
"metadata": {
"custom_field": "value"
}
},
"message": "会话创建成功"
}
错误响应:
400: 请求参数错误409: 会话ID已存在
2. 查询会话列表
接口: GET /location-broadcast/sessions
描述: 根据条件查询游戏会话列表
认证: 需要 JWT Token
查询参数:
status(可选): 会话状态minUsers(可选): 最小用户数maxUsers(可选): 最大用户数publicOnly(可选): 只显示公开会话offset(可选): 分页偏移limit(可选): 分页大小
成功响应 (200):
{
"success": true,
"data": {
"sessions": [
{
"sessionId": "session_12345",
"name": "测试会话",
"status": "active",
"currentUsers": 15,
"maxUsers": 50,
"createdAt": 1641024000000
}
],
"total": 10,
"page": 1,
"pageSize": 10
}
}
3. 获取会话详情
接口: GET /location-broadcast/sessions/:sessionId
描述: 获取指定会话的详细信息，包括用户列表和位置信息
认证: 需要 JWT Token
路径参数:
sessionId: 会话ID
成功响应 (200):
{
"success": true,
"data": {
"session": {
"sessionId": "session_12345",
"name": "测试会话",
"status": "active",
"currentUsers": 15,
"maxUsers": 50
},
"users": [
{
"userId": "1",
"username": "testuser",
"joinedAt": 1641024000000
}
],
"onlineCount": 15,
"activeMaps": ["map_001", "map_002"]
}
}
错误响应:
404: 会话不存在
4. 更新会话配置
接口: PUT /location-broadcast/sessions/:sessionId/config
描述: 更新指定会话的配置参数（需要管理员权限）
认证: 需要 JWT Token
路径参数:
sessionId: 会话ID
请求体:
{
"maxUsers": 100,
"allowObservers": false,
"broadcastRange": 150
}
成功响应 (200):
{
"success": true,
"data": {
"sessionId": "session_12345",
"config": {
"maxUsers": 100,
"allowObservers": false,
"broadcastRange": 150
}
},
"message": "会话配置更新成功"
}
错误响应:
403: 权限不足404: 会话不存在
5. 结束会话
接口: DELETE /location-broadcast/sessions/:sessionId
描述: 结束指定的游戏会话（需要管理员权限）
认证: 需要 JWT Token
路径参数:
sessionId: 会话ID
成功响应 (200):
{
"success": true,
"message": "会话结束成功"
}
错误响应:
403: 权限不足404: 会话不存在
6. 查询位置信息
接口: GET /location-broadcast/positions
描述: 根据条件查询用户位置信息
认证: 需要 JWT Token
查询参数:
userIds(可选): 用户ID列表（逗号分隔）mapId(可选): 地图IDsessionId(可选): 会话IDcenterX(可选): 范围查询中心X坐标centerY(可选): 范围查询中心Y坐标radius(可选): 范围查询半径offset(可选): 分页偏移limit(可选): 分页大小
成功响应 (200):
{
"success": true,
"data": {
"positions": [
{
"userId": "1",
"username": "testuser",
"mapId": "map_001",
"x": 100,
"y": 200,
"timestamp": 1641024000000
}
],
"total": 20,
"timestamp": 1641024000000
}
}
7. 获取位置统计信息
接口: GET /location-broadcast/positions/stats
描述: 获取位置数据的统计信息，包括用户分布、活跃地图等
认证: 需要 JWT Token
查询参数:
mapId(可选): 地图IDsessionId(可选): 会话ID
成功响应 (200):
{
"success": true,
"data": {
"totalUsers": 100,
"onlineUsers": 85,
"activeMaps": 5,
"mapDistribution": {
"map_001": 35,
"map_002": 28,
"map_003": 22
},
"updateFrequency": 2.5,
"timestamp": 1641024000000
}
}
8. 获取用户位置历史
接口: GET /location-broadcast/users/:userId/position-history
描述: 获取指定用户的位置历史记录
认证: 需要 JWT Token
路径参数:
userId: 用户ID
查询参数:
mapId(可选): 地图ID过滤limit(可选): 最大记录数
成功响应 (200):
{
"success": true,
"data": [
{
"userId": "1",
"mapId": "map_001",
"x": 100,
"y": 200,
"timestamp": 1641024000000
}
]
}
错误响应:
403: 权限不足（只能查看自己的历史记录）
9. 清理用户数据
接口: DELETE /location-broadcast/users/:userId/data
描述: 清理指定用户的位置广播相关数据（需要管理员权限）
认证: 需要 JWT Token
路径参数:
userId: 用户ID
成功响应 (200):
{
"success": true,
"message": "用户数据清理成功"
}
错误响应:
403: 权限不足
通知系统
1. 创建通知
接口: POST /api/notices
描述: 创建新的通知消息
认证: 需要 JWT Token
请求体:
{
"title": "系统通知",
"content": "这是一条系统通知消息",
"userId": 1,
"type": "system"
}
成功响应 (201):
{
"id": 1,
"title": "系统通知",
"content": "这是一条系统通知消息",
"userId": 1,
"type": "system",
"isRead": false,
"createdAt": "2026-01-20T10:00:00.000Z"
}
2. 获取通知列表
接口: GET /api/notices
描述: 获取当前用户的通知列表
认证: 需要 JWT Token
查询参数:
all(可选): 管理员可设置为true获取所有通知
成功响应 (200):
[
{
"id": 1,
"title": "系统通知",
"content": "这是一条系统通知消息",
"userId": 1,
"type": "system",
"isRead": false,
"createdAt": "2026-01-20T10:00:00.000Z"
}
]
3. 获取未读通知数量
接口: GET /api/notices/unread-count
描述: 获取当前用户的未读通知数量
认证: 需要 JWT Token
成功响应 (200):
{
"count": 5
}
4. 获取通知详情
接口: GET /api/notices/:id
描述: 获取指定通知的详细信息
认证: 需要 JWT Token
路径参数:
id: 通知ID
成功响应 (200):
{
"id": 1,
"title": "系统通知",
"content": "这是一条系统通知消息",
"userId": 1,
"type": "system",
"isRead": false,
"createdAt": "2026-01-20T10:00:00.000Z"
}
5. 标记通知为已读
接口: PATCH /api/notices/:id/read
描述: 将指定通知标记为已读
认证: 需要 JWT Token
路径参数:
id: 通知ID
成功响应 (200):
{
"id": 1,
"title": "系统通知",
"content": "这是一条系统通知消息",
"userId": 1,
"type": "system",
"isRead": true,
"createdAt": "2026-01-20T10:00:00.000Z"
}
6. 发送系统通知
接口: POST /api/notices/system
描述: 发送系统通知给指定用户或所有用户
认证: 需要 JWT Token（管理员）
请求体:
{
"title": "系统维护通知",
"content": "系统将于今晚22:00进行维护",
"userId": 1
}
成功响应 (201):
{
"id": 2,
"title": "系统维护通知",
"content": "系统将于今晚22:00进行维护",
"userId": 1,
"type": "system",
"isRead": false,
"createdAt": "2026-01-20T10:00:00.000Z"
}
7. 发送广播通知
接口: POST /api/notices/broadcast
描述: 向所有用户发送广播通知
认证: 需要 JWT Token（管理员）
请求体:
{
"title": "重要公告",
"content": "新版本即将上线，敬请期待！"
}
成功响应 (201):
{
"id": 3,
"title": "重要公告",
"content": "新版本即将上线，敬请期待！",
"type": "broadcast",
"isRead": false,
"createdAt": "2026-01-20T10:00:00.000Z"
}
Zulip集成
1. 创建Zulip账号关联
接口: POST /zulip-accounts
描述: 为游戏用户创建与Zulip账号的关联关系
认证: 需要 JWT Token
请求体:
{
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active"
}
成功响应 (201):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active",
"createdAt": "2026-01-20T10:00:00.000Z",
"updatedAt": "2026-01-20T10:00:00.000Z"
}
错误响应:
400: 请求参数错误409: 关联已存在
2. 查询Zulip账号关联列表
接口: GET /zulip-accounts
描述: 根据条件查询Zulip账号关联列表
认证: 需要 JWT Token
查询参数:
gameUserId(可选): 游戏用户IDzulipUserId(可选): Zulip用户IDzulipEmail(可选): Zulip邮箱地址status(可选): 账号状态limit(可选): 返回数量offset(可选): 偏移量
成功响应 (200):
{
"data": [
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active",
"createdAt": "2026-01-20T10:00:00.000Z"
}
],
"total": 1,
"limit": 10,
"offset": 0
}
3. 根据ID获取Zulip账号关联
接口: GET /zulip-accounts/:id
描述: 根据关联ID获取Zulip账号关联详情
认证: 需要 JWT Token
路径参数:
id: 关联ID
成功响应 (200):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active",
"createdAt": "2026-01-20T10:00:00.000Z",
"updatedAt": "2026-01-20T10:00:00.000Z"
}
错误响应:
404: 关联不存在
4. 根据游戏用户ID获取关联
接口: GET /zulip-accounts/game-user/:gameUserId
描述: 根据游戏用户ID获取Zulip账号关联
认证: 需要 JWT Token
路径参数:
gameUserId: 游戏用户ID
成功响应 (200):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active"
}
5. 根据Zulip用户ID获取关联
接口: GET /zulip-accounts/zulip-user/:zulipUserId
描述: 根据Zulip用户ID获取账号关联
认证: 需要 JWT Token
路径参数:
zulipUserId: Zulip用户ID
成功响应 (200):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active"
}
6. 根据Zulip邮箱获取关联
接口: GET /zulip-accounts/zulip-email/:zulipEmail
描述: 根据Zulip邮箱获取账号关联
认证: 需要 JWT Token
路径参数:
zulipEmail: Zulip邮箱地址
成功响应 (200):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Test User",
"status": "active"
}
7. 更新Zulip账号关联
接口: PUT /zulip-accounts/:id
描述: 更新指定的Zulip账号关联信息
认证: 需要 JWT Token
路径参数:
id: 关联ID
请求体:
{
"zulipFullName": "Updated Name",
"status": "inactive"
}
成功响应 (200):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Updated Name",
"status": "inactive",
"updatedAt": "2026-01-20T10:00:00.000Z"
}
8. 根据游戏用户ID更新关联
接口: PUT /zulip-accounts/game-user/:gameUserId
描述: 根据游戏用户ID更新Zulip账号关联
认证: 需要 JWT Token
路径参数:
gameUserId: 游戏用户ID
请求体:
{
"zulipFullName": "Updated Name",
"status": "active"
}
成功响应 (200):
{
"id": 1,
"gameUserId": "12345",
"zulipUserId": 67890,
"zulipEmail": "user@example.com",
"zulipFullName": "Updated Name",
"status": "active",
"updatedAt": "2026-01-20T10:00:00.000Z"
}
9. 删除Zulip账号关联
接口: DELETE /zulip-accounts/:id
描述: 删除指定的Zulip账号关联
认证: 需要 JWT Token
路径参数:
id: 关联ID
成功响应 (200):
{
"success": true,
"message": "Zulip账号关联删除成功"
}
10. 根据游戏用户ID删除关联
接口: DELETE /zulip-accounts/game-user/:gameUserId
描述: 根据游戏用户ID删除Zulip账号关联
认证: 需要 JWT Token
路径参数:
gameUserId: 游戏用户ID
成功响应 (200):
{
"success": true,
"message": "Zulip账号关联删除成功"
}
11. 获取需要验证的账号列表
接口: GET /zulip-accounts/management/verification-needed
描述: 获取需要验证的Zulip账号列表
认证: 需要 JWT Token
成功响应 (200):
{
"data": [
{
"id": 1,
"gameUserId": "12345",
"zulipEmail": "user@example.com",
"status": "pending_verification"
}
],
"total": 1
}
12. 获取错误状态的账号列表
接口: GET /zulip-accounts/management/error-accounts
描述: 获取处于错误状态的Zulip账号列表
认证: 需要 JWT Token
成功响应 (200):
{
"data": [
{
"id": 2,
"gameUserId": "67890",
"zulipEmail": "error@example.com",
"status": "error",
"errorMessage": "连接失败"
}
],
"total": 1
}
13. 批量更新账号状态
接口: PUT /zulip-accounts/management/batch-status
描述: 批量更新Zulip账号的状态
认证: 需要 JWT Token
请求体:
{
"accountIds": [1, 2, 3],
"status": "active"
}
成功响应 (200):
{
"success": true,
"updated": 3,
"message": "批量更新成功"
}
14. 获取账号状态统计
接口: GET /zulip-accounts/management/statistics
描述: 获取Zulip账号的状态统计信息
认证: 需要 JWT Token
成功响应 (200):
{
"total": 100,
"active": 85,
"inactive": 10,
"pending_verification": 3,
"error": 2
}
15. 验证账号有效性
接口: POST /zulip-accounts/management/verify
描述: 验证Zulip账号的有效性
认证: 需要 JWT Token
请求体:
{
"accountId": 1
}
成功响应 (200):
{
"success": true,
"valid": true,
"message": "账号验证成功"
}
16. 检查邮箱是否已存在
接口: GET /zulip-accounts/validation/email-exists/:email
描述: 检查指定邮箱是否已在Zulip中存在
认证: 需要 JWT Token
路径参数:
email: 邮箱地址
成功响应 (200):
{
"exists": true,
"accountId": 1
}
17. 检查Zulip用户ID是否已存在
接口: GET /zulip-accounts/validation/zulip-user-exists/:zulipUserId
描述: 检查指定Zulip用户ID是否已关联
认证: 需要 JWT Token
路径参数:
zulipUserId: Zulip用户ID
成功响应 (200):
{
"exists": true,
"accountId": 1
}
数据库管理
1. 获取用户列表
接口: GET /admin/database/users
描述: 分页获取用户列表（管理员专用）
认证: 需要管理员 Token
查询参数:
limit(可选): 返回数量，默认20，最大100offset(可选): 偏移量，默认0
成功响应 (200):
{
"success": true,
"data": [
{
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com",
"role": 1,
"status": "active",
"created_at": "2026-01-20T10:00:00.000Z"
}
],
"total": 100,
"limit": 20,
"offset": 0
}
2. 获取用户详情
接口: GET /admin/database/users/:id
描述: 根据用户ID获取详细的用户信息
认证: 需要管理员 Token
路径参数:
id: 用户ID
成功响应 (200):
{
"success": true,
"data": {
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com",
"phone": null,
"role": 1,
"status": "active",
"email_verified": true,
"created_at": "2026-01-20T10:00:00.000Z",
"updated_at": "2026-01-20T10:00:00.000Z"
}
}
3. 搜索用户
接口: GET /admin/database/users/search
描述: 根据关键词搜索用户，支持用户名、邮箱、昵称模糊匹配
认证: 需要管理员 Token
查询参数:
keyword: 搜索关键词limit(可选): 返回数量，默认20，最大50
成功响应 (200):
{
"success": true,
"data": [
{
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com"
}
],
"total": 5
}
4. 创建用户
接口: POST /admin/database/users
描述: 创建新用户（管理员专用）
认证: 需要管理员 Token
请求体:
{
"username": "newuser",
"password": "password123",
"nickname": "新用户",
"email": "newuser@example.com",
"role": 1
}
成功响应 (201):
{
"success": true,
"data": {
"id": "2",
"username": "newuser",
"nickname": "新用户",
"email": "newuser@example.com",
"role": 1,
"created_at": "2026-01-20T10:00:00.000Z"
},
"message": "用户创建成功"
}
错误响应:
400: 请求参数错误409: 用户名或邮箱已存在
5. 更新用户
接口: PUT /admin/database/users/:id
描述: 根据用户ID更新用户信息
认证: 需要管理员 Token
路径参数:
id: 用户ID
请求体:
{
"nickname": "更新后的昵称",
"email": "newemail@example.com",
"status": "active"
}
成功响应 (200):
{
"success": true,
"data": {
"id": "1",
"username": "testuser",
"nickname": "更新后的昵称",
"email": "newemail@example.com",
"status": "active",
"updated_at": "2026-01-20T10:00:00.000Z"
},
"message": "用户更新成功"
}
错误响应:
404: 用户不存在
6. 删除用户
接口: DELETE /admin/database/users/:id
描述: 根据用户ID删除用户（软删除）
认证: 需要管理员 Token
路径参数:
id: 用户ID
成功响应 (200):
{
"success": true,
"message": "用户删除成功"
}
错误响应:
404: 用户不存在
操作日志
1. 获取操作日志列表
接口: GET /admin/operation-logs
描述: 分页获取管理员操作日志，支持多种过滤条件
认证: 需要管理员 Token
查询参数:
limit(可选): 返回数量，默认50，最大200offset(可选): 偏移量，默认0adminUserId(可选): 管理员用户ID过滤operationType(可选): 操作类型过滤（CREATE, UPDATE, DELETE, QUERY）targetType(可选): 目标类型过滤（users, admin_logs等）operationResult(可选): 操作结果过滤（SUCCESS, FAILURE）startDate(可选): 开始日期（ISO格式）endDate(可选): 结束日期（ISO格式）isSensitive(可选): 是否敏感操作
成功响应 (200):
{
"success": true,
"data": [
{
"id": "log_123",
"adminUserId": "1",
"operationType": "CREATE",
"targetType": "users",
"targetId": "2",
"operationResult": "SUCCESS",
"description": "创建用户",
"isSensitive": true,
"createdAt": "2026-01-20T10:00:00.000Z"
}
],
"total": 100,
"limit": 50,
"offset": 0
}
2. 获取操作日志详情
接口: GET /admin/operation-logs/:id
描述: 根据日志ID获取操作日志的详细信息
认证: 需要管理员 Token
路径参数:
id: 日志ID
成功响应 (200):
{
"success": true,
"data": {
"id": "log_123",
"adminUserId": "1",
"operationType": "CREATE",
"targetType": "users",
"targetId": "2",
"operationResult": "SUCCESS",
"description": "创建用户",
"isSensitive": true,
"metadata": {
"username": "newuser",
"email": "newuser@example.com"
},
"createdAt": "2026-01-20T10:00:00.000Z"
}
}
错误响应:
404: 日志不存在
📊 版本更新记录
v2.0.0 (2026-01-20)
- 架构升级: 完整的四层架构实现（Gateway、Business、Core、Database）
- 新增功能: 位置广播系统、通知系统、Zulip集成
- 数据库管理: 完整的管理员数据库管理接口
- 操作日志: 管理员操作审计日志系统
- Token刷新: 支持刷新令牌机制
- WebSocket: 完整的实时通信支持
v1.1.2 (2025-12-25)
- 验证码冷却优化: 注册、密码重置、验证码登录成功后自动清除验证码冷却时间
- 用户体验提升: 成功操作后可立即发送新的验证码
v1.1.1 (2025-12-25)
- 邮箱冲突检测优化: 发送邮箱验证码前检查邮箱是否已被注册
- 错误处理改进: 返回409 Conflict状态码和明确错误信息
v1.1.0 (2025-12-25)
- 新增验证码登录功能: 支持邮箱验证码登录
- HTTP状态码修复: 所有接口返回正确的业务状态码
- 完善错误处理: 统一错误响应格式和错误代码
🔗 相关资源
📝 注意事项
- 认证机制: 大部分接口需要 JWT Token 认证
- 频率限制: 已实现 API 频率限制，请注意请求频率
- 测试模式: 开发环境下邮件服务返回206状态码，验证码在响应中返回
- WebSocket: 实时功能（聊天、位置广播）推荐使用 WebSocket 接口
- 管理员权限: 管理员接口需要 role=9 的账户权限
- 数据格式: 所有日期时间使用 ISO 8601 格式
- 错误处理: 根据 HTTP 状态码和 error_code 进行错误处理
文档维护: 本文档根据后端代码自动生成，如有疑问请参考源代码或联系开发团队。