跳转到内容

API 总览

所有接口经网关暴露,基址为:

http://localhost:8080/api/v1 # 本地默认
https://<你的域名>/api/v1 # 线上

网关先校验凭据(用户 JWT,或 bot 的静态 ofb_ token),再按路由表校验权限,最后转发给内部服务。

两条路径例外:GET /api/v1/health 由网关自身应答;GET /api/v1/files/... 在网关 NoRoute 中特判(只解析 JWT)。

方式 请求头 说明
用户 JWT Authorization: Bearer <jwt> 登录后获得,默认 24 小时
Bot 静态 token Authorization: Bearer ofb_<64位十六进制> 无过期,重置即失效(见 Bot 开发指南)

失败响应:

情况 响应
未带 Authorization 401 {"error":"missing authorization token"}
JWT 无效/过期 401
bot token 失效、被重置、bot 被封禁 401 {"error":"invalid bot token"}
缺权限 403 {"error":"permission denied","permission":"<键>"}
账号被封禁(JWT) 403 {"error":"account is banned","banned":true}

封禁的 bot 在 token 解析阶段就被拒,返回 401 而非 403。客户端统一按 401 处理“凭据失效”。

级别 含义
authPublic 公开。带有效 token 时仍会解析身份,用于返回个性化字段(is_following、my_role、自身点赞/收藏状态)
authRequired 必须认证,不检查具体权限键
authPermission 必须认证 + 持有该路由的权限键
authTicket 仅 GET /ws:网关删除客户端身份头,凭一次性票据兑换

除文件上传外,POST/PUT 一律 Content-Type: application/json。上传为 multipart/form-data。

接口类型 成功形态
单对象创建(发帖、评论、消息) 201 + 对象本身
列表 200 {"<复数名>":[…], "page":1} 或 {"messages":[…]}
删除、标记已读 204 No Content
错误 {"error":"…"},部分附带附加字段(如 permission、banned、limit)

页码分页(帖子、评论、用户帖子):

GET /posts?page=1&limit=20
GET /posts?q=关键词&author=alice&tag=news&author_id=7&from=2026-01-01&to=2026-02-01

响应里的 page 是当前页;没有 total、没有 has_more——请求到空数组即为末尾。

游标分页(消息,只能往前翻):

GET /conversations/:id/messages?limit=50&before=12345
  • limit 默认 50,合法区间 1..100,越界会被重置为 50;
  • before=<消息 id> 取更旧的消息;不传取最新一页;
  • 返回时间正序(旧 → 新),最新一条在 messages[-1];
  • 没有 after:取新消息只能轮询最新页按 id 去重,或改用 WebSocket。
  • 时间戳为 RFC3339(2026-10-10T15:20:12Z);info 类字段偶用 Unix 秒。
  • 金额一律整数分(cents,BIGINT),客户端自行 /100 展示。红包与打赏接口的 amount 以“币”为单位(10.5),注意区分。
限制 值 作用域
网关令牌桶 120 请求/分钟,突发 240 按真实 TCP 对端 IP;超限先等待令牌,持续超限才 429
举报 20 条/小时 按用户
登录 / 支付 PIN 试错 内部预算(pkg/ratelimit) 按用户,仅统计错误次数

网关限流不区分 bot 与普通用户,也不按 token 计数——同一出口 IP 后所有请求共用一个桶。

分组 文档
认证与会话(OIDC、密码、刷新、多账号、扫码) 认证与会话
用户与档案(资料、头像、关注、隐私、名称样式、存储桶、注销) 用户与档案
钱包、转账、支付 PIN、红包 钱包与支付
帖子、评论、互动、打赏、营地 帖子与营地
会话、消息、群管理、E2EE、搜索 聊天
语音/视频通话 通话
附件与对象存储 附件与存储
任务、经验等级、会员 任务与会员
举报与处罚 审核与处罚
公告、插件、能力探测、健康检查、实时推送 系统接口
  • 公开路由也会个性化:GET /posts、GET /camps、GET /users/:id 等在带上有效 token 时返回结果会不同(自身点赞状态、my_role、is_following)。不带 token 只能拿到公共视图。
  • 未匹配路由返回 404,后端故障返回 503——两者可区分,便于定位是客户端路径写错还是服务挂了。
  • 浏览器跨域:需要网关的 server.allowed_origins 放行;localhost/127.0.0.1 来源默认总是允许。
  • Host 白名单:配置 server.allowed_hosts 后,Host 不匹配的请求会被直接拒绝。

上游 docs/punishments.md 提到 POST /auth/logout 在封禁状态下仍可达,但网关路由表中没有注册 /auth/logout。当前会话失效请使用 DELETE /auth/sessions/:id(见认证与会话)。