mirror of
https://github.com/truewhile/MeBox.git
synced 2026-11-14 12:04:23 +08:00
truewhile
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# 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. 错误契约
|
||
|
||
统一响应：
|
||
|
||
```json
|
||
{
|
||
"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 目前只开放连接、登录、会话恢复与退出；媒体与阅读入口未实现。
|