MeBox Mobile API 接入与部署说明

更新日期：2026-10-17
适用版本：后端 feature/android-mobile-api 分支；App 0.1.0（versionCode 1）。

1. 路径与版本

安卓契约挂载在 /api/v1，与既有 /api、Emby/Jellyfin 入口并行。
健康检查：GET /api/health。
实例身份：GET /api/v1/server-info（匿名，Cache-Control: no-store）。
契约字段与错误码见同目录 openapi.yaml。

server-info.capabilities 必须反映真实运行能力。当前分支只有 device_sessions=true；播放会话、阅读 v1 进度、批量正文与移动端转码仍为 false，App 不得据此进入对应流程。

2. 连接与传输安全

公网必须使用 HTTPS；App 默认使用系统信任链，不提供全局跳过证书校验。
局域网 HTTP 需要用户在 App 内明确确认风险；App 只对当前配置的服务器来源使用明文，不会把 MeBox Authorization 发往其它主机。
首版只支持根路径部署。https://host/mebox 这类子路径会被 App 明确拒绝，不会静默截断为根路径。
反代需要保留 X-Request-ID（可选）；服务端会回传同值或新生成值，用于日志对账。

3. 反向代理检查项

以下项用于媒体阶段（M3/M4）回归，当前登录闭环不依赖它们，但仍建议提前配置：

项目	要求
Range / 206	透传客户端 `Range`，不要缓存完整响应后改写状态码
流式响应	关闭代理缓冲（如 nginx `proxy_buffering off`）
HLS	`.m3u8` 与分片路径不要被改写或强制压缩
WebSocket	升级头透传，读超时大于心跳间隔
超时	登录/普通 API 30 秒内完成；转码起播超时单独配置

目前只验证了普通 JSON 端点；上表其余项尚未在本分支验收。

4. 认证与会话

POST /api/v1/auth/login 创建 auth_sessions 记录，访问令牌 JWT 增加 sid。
旧 /api 中间件同样校验 sid：设备被踢出或退出后，未过期的 JWT 也会立即返回 401，不能借旧入口绕过。
没有 sid 的历史令牌继续按原逻辑访问旧 API；v1 认证端点拒绝这类令牌， App 需要重新登录。
POST /api/v1/auth/logout 幂等；会话撤销会同时撤销其名下刷新令牌。
设备管理中的踢出操作会同步撤销该设备认证会话。

刷新轮换边界

同一个刷新令牌的并发请求共享一次轮换；60 秒宽限期内重复提交返回同一结果。
轮换结果仍保存在进程内。若新令牌已签发、旧令牌已撤销，但客户端没收到响应且服务器随后重启，旧令牌可能无法恢复；此时 App 应要求重新登录。首版接受该边界，未实现持久化幂等轮换。
会话被撤销时，刷新返回 401 SESSION_REVOKED，优先于宽限期复用。

5. 错误契约

统一响应：

{
  "code": "SESSION_REVOKED",
  "message": "auth session revoked or expired",
  "request_id": "8a3bade4-cbb3-485b-8e34-2471e4940fc3",
  "retryable": false
}

401 由 code 区分 TOKEN_EXPIRED、SESSION_REVOKED、INVALID_CREDENTIALS。
403 表示权限或账号状态，不触发刷新。
429 带 Retry-After，客户端必须等待。
5xx / SERVICE_UNAVAILABLE / retryable=true 表示可安全重试。

6. 数据迁移与回滚

新表 auth_sessions 与 refresh_tokens.auth_session_id 由现有 AutoMigrate 创建，属于增量变更，不清库。
SQLite 已验证；PostgreSQL 迁移需要在有实例的环境中单独执行 go test ./internal/database ./internal/repository -count=1 后才能宣称通过。
回滚到旧版本不会删除新表；旧程序忽略新增字段。回滚前应先确认不需要再依赖 sid 即时撤销能力。

7. 已知限制

单实例部署；未实现多副本共享会话。
外部播放令牌尚未继承 sid（属于 M3 播放会话范围），当前不能按设备即时撤销。
反代子路径、自签名证书信任、多服务器配置均未支持。
App 目前只开放连接、登录、会话恢复与退出；媒体与阅读入口未实现。

4.1 KiB Raw Permalink Blame History Unescape Escape