00. 约定与鉴权¶
1. 基础信息¶
- HTTP 前缀：
/api - WebSocket 地址：
/ws - 数据格式：
application/json（文件上传除外） - 时间格式：
2006-01-02 15:04:05（如2026-04-05 16:30:00）
2. 鉴权方式¶
2.1 Access Token¶
受保护接口需要：
Authorization: Bearer <access_token>
- Access Token 默认有效期：3 小时。
- 登录成功后会返回：
token、refresh_token。
2.2 Refresh Token（推荐 Cookie 模式）¶
- Cookie 名：
refresh_token - Path：
/api/auth - HttpOnly：
true - 过期：14 天
刷新接口：POST /api/auth/refresh
- 优先读取 Cookie。
- 也可 body 传 refresh_token（桌面/移动端）。
2.3 WebSocket 鉴权 Cookie¶
- Cookie 名：
ws_token - Path：
/ - HttpOnly：
true - 由登录/刷新或
POST /api/auth/ws-token/sync同步。
/ws 只从 Cookie 读取 token，不从 URL/query 读取。
3. 统一响应结构¶
大部分接口：
{
"code": 200,
"message": "成功",
"data": {}
}
常见错误：
{ "code": 400, "message": "请求参数错误" }
{ "code": 401, "message": "未授权" }
{ "code": 403, "message": "需要管理员权限" }
{ "code": 404, "message": "资源不存在" }
{ "code": 429, "message": "请求过于频繁，请稍后重试", "data": { "retry_after": 9 } }
{ "code": 500, "message": "服务器内部错误" }
4. 分页约定¶
常见请求参数：
- page（默认 1）
- page_size 或 limit（默认 20）
常见返回：
{
"total": 123,
"items": [],
"page": 1,
"page_size": 20
}
5. 权限分层¶
- 公开：无需登录
JWT：登录后可访问JWT + Approved：账号需审核通过（或管理员绕过）Admin：管理员Admin/GroupOwner：管理员或群组创建者
6. 限流（代码内置）¶
/api/device/pre-check：IP 每秒 1 次；MAC 每分钟 5 次/api/device/request-code：IP 每 10 秒 1 次；MAC 每分钟 1 次/api/device/confirm-bind：MAC 每 5 秒 1 次/api/device/bind：用户每分钟 5 次/api/device/submit-config：用户每分钟 10 次/api/public/relays：IP 每分钟 10 次
7. 安全限制¶
- 任何 token 类 query 参数（
token/access_token/refresh_token/jwt/...）会被网关直接拒绝：
{ "code": 400, "message": "token_query_not_allowed" }