跳转至

00. 约定与鉴权

1. 基础信息

  • HTTP 前缀：/api
  • WebSocket 地址：/ws
  • 数据格式：application/json（文件上传除外）
  • 时间格式：2006-01-02 15:04:05（如 2026-04-05 16:30:00）
  • UDP DraARLv1 固定头部始终为 90 字节；如设备需要上报 MAC，只能追加在心跳 DATA 扩展区，不能写入 header。

2. 鉴权方式

2.1 Access Token

受保护接口需要：

Authorization: Bearer <access_token>
  • Access Token 默认有效期：3 小时。
  • 登录成功后会返回：token、refresh_token。
  • Cookie 名：refresh_token
  • Path：/api/auth
  • HttpOnly：true
  • 过期：14 天

刷新接口：POST /api/auth/refresh

  • 优先读取 Cookie。
  • 也可 body 传 refresh_token（桌面/移动端）。
  • 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 次
  • /api/public/client-resources/manifest 与 /api/public/client-resources/artifacts/:artifact_id/download：共享 IP 每分钟 30 次
  • /api/groups/:id/messages 与 /api/groups/:id/messages/:message_id：使用 MessageAPI 的账号/IP 窗口和并发查询槽；默认每页 50、最大每页 100、账号每分钟 120 次、IP 每分钟 300 次、 并发 32。超限返回 429，并发槽耗尽返回 503 message_api_busy。

7. 安全限制

  • 任何 token 类 query 参数（token/access_token/refresh_token/jwt/...）会被网关直接拒绝，local 存储的受控上传 PUT /api/storage/put 与短期下载 GET /api/storage/get 是例外：
{ "code": 400, "message": "token_query_not_allowed" }

/healthz 不检查数据库、Redis 或对象存储，只表示 HTTP 进程已监听；依赖状态请使用 管理员指标接口和部署侧健康检查。