docs: align maintainer guidance with implementation
This commit is contained in:
zhoujun0601
@@ -40,7 +40,7 @@ docker compose logs -f codex-helper
|
||||
容器健康后访问：
|
||||
|
||||
```text
|
||||
http://服务器地址:8080
|
||||
http://服务器地址:8180
|
||||
```
|
||||
|
||||
首次打开页面时创建管理员账号，并设置所在时区。用户名至少 3 位，密码至少 10 位。
|
||||
@@ -91,7 +91,7 @@ http://服务器地址:8080
|
||||
|
||||
7. 收到“绑定成功”后，返回页面点击“发送测试”。
|
||||
|
||||
绑定码十分钟内有效，一个实例只绑定一个 Telegram 会话。即使关闭查询菜单，仍可完成绑定并接收提醒；开启菜单后可使用以下按钮或命令：
|
||||
绑定码十分钟内有效，一个实例只绑定一个 Telegram 会话。即使关闭查询菜单，仍可完成绑定并接收提醒；开启菜单后可使用以下按钮或命令。`/account` 会向已绑定会话显示账号的完整邮箱，因此只应绑定受信任的私有会话。
|
||||
|
||||
- 当前用量（包含所有已添加连接）
|
||||
- 重置时间 / `/reset`
|
||||
@@ -138,8 +138,8 @@ docker compose logs --tail=200 codex-helper
|
||||
健康检查：
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/health/live
|
||||
curl http://localhost:8080/health/ready
|
||||
curl http://localhost:8180/health/live
|
||||
curl http://localhost:8180/health/ready
|
||||
```
|
||||
|
||||
## 数据、备份与恢复
|
||||
@@ -153,7 +153,7 @@ curl http://localhost:8080/health/ready
|
||||
登录管理页面后，可直接在浏览器访问以下地址下载一致性 SQLite 快照：
|
||||
|
||||
```text
|
||||
http://服务器地址:8080/api/v1/maintenance/backup
|
||||
http://服务器地址:8180/api/v1/maintenance/backup
|
||||
```
|
||||
|
||||
SQLite 快照不包含 `secret.key` 和 `codex/`。完整灾难恢复必须同时备份整个 `/data` 数据卷；恢复时先停止容器，再恢复全部内容，并确保文件所有者仍可被容器中的 UID `10001` 读取。
|
||||
|
||||
+8
-8
@@ -8,7 +8,7 @@
|
||||
- `GET /health/live` 始终返回 `200 {"status":"ok"}`；`GET /health/ready` 在 SQLite 可用时返回 `200 {"status":"ok","appServer":bool}`，数据库不可用时返回 `503 {"error":string}`。`appServer` 表示至少一个账号的 app-server 已完成初始化。
|
||||
- JSON 请求体最多读取 1 MiB，拒绝未知字段；业务错误统一为 `{"error":string}`。未匹配 API 返回 `404 {"error":"接口不存在"}`。
|
||||
- 所有响应带 `X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY`、`Referrer-Policy: same-origin` 和同源 CSP。
|
||||
- `GET /api/v1/system/status`、`POST /api/v1/setup`、`POST /api/v1/auth/login` 匿名可用。status 的其他方法返回 405；其余 API 要求有效 `session` cookie，非 `GET`/`HEAD` 请求还要求 `X-Requested-With: codex-helper`，否则分别返回 401 或 403。
|
||||
- `GET /api/v1/system/status`、`POST /api/v1/setup`、`POST /api/v1/auth/login` 匿名可用。status 的其他方法返回 405；其余 API 要求有效 `session` cookie，非 `GET`/`HEAD` 请求还要求 `X-Requested-With: codex-helper`，否则分别返回 401 或 403。当前 dispatcher 只对部分路由显式限制 HTTP method；下文使用“任意方法”或“非 `GET`”的地方是对实际兼容行为的记录。
|
||||
- session 有效期七天，cookie 为 `HttpOnly`、`SameSite=Strict`、`Path=/`；数据库只保存 token 摘要。登录失败按 `RemoteAddr` 在进程内限制为 15 分钟最多 10 次，超限返回 429。
|
||||
- 未命中静态文件的非 API GET 路径返回嵌入的 `index.html`，供前端路由回退。
|
||||
|
||||
@@ -46,7 +46,7 @@
|
||||
| `GET /api/v1/system/status` | 匿名 | `200 {initialized,version,appServer}`。当前版本字段为 `0.2.0`。 |
|
||||
| `POST /api/v1/setup` | 匿名、仅未初始化 | body `{username,password,timezone}`；用户名至少 3 位、密码至少 10 位，否则 400；时区有效时写入，否则使用默认 UTC。事务创建唯一管理员和通用设置，设置 session，返回 `201 {ok:true}`；已初始化返回 409。 |
|
||||
| `POST /api/v1/auth/login` | 匿名 | body `{username,password}`；未初始化返回 409，错误凭据返回 401，成功设置 session 并返回 `200 {ok:true}`，限流返回 429。 |
|
||||
| `GET /api/v1/auth/me` | session | `200 {username}`。 |
|
||||
| `任意方法 /api/v1/auth/me` | session；非 `GET`/`HEAD` 还需来源头 | `200 {username}`。前端使用 `GET`。 |
|
||||
| `POST /api/v1/auth/logout` | session + 来源头 | 删除当前 session、清除 cookie，返回 `200 {ok:true}`。 |
|
||||
|
||||
兼容文案包括：`系统已初始化`、`用户名至少3位，密码至少10位`、`请先初始化`、`用户名或密码错误`、`尝试次数过多，请稍后再试`、`未登录`、`请求来源校验失败`。
|
||||
@@ -62,7 +62,7 @@
|
||||
| `POST /api/v1/accounts/{id}/login/device` | 启动并初始化 app-server，调用 `account/login/start` 的 `chatgptDeviceCode` 流程；返回含 `verificationUrl`、`userCode` 和 `loginId` 的结果。 |
|
||||
| `POST /api/v1/accounts/{id}/logout` | 调用 `account/logout` 并将连接状态置为 false；返回 `200 {ok:true}`。 |
|
||||
| `POST /api/v1/accounts/{id}/sync` | 同步指定账号；成功 `200 {ok:true}`，上游失败 502。 |
|
||||
| `GET /api/v1/dashboard?accountId={id}` | 返回内存中的 `Dashboard`；省略或无效的零值 ID 使用账号 1。 |
|
||||
| `任意方法 /api/v1/dashboard?accountId={id}` | 返回内存中的 `Dashboard`；非 `GET`/`HEAD` 还需来源头。省略或无效的零值 ID 使用账号 1，前端使用 `GET`。 |
|
||||
| `POST /api/v1/sync?accountId={id}` | 旧兼容入口，同步指定账号；省略或零值 ID 使用账号 1。 |
|
||||
|
||||
账号不存在返回 404 `账号不存在`；非法路径 ID 返回 400 `账号 ID 无效`；无效 `expectedKind` 返回 400 `连接类型无效`。未知账号套餐不得猜测为个人或团队。
|
||||
@@ -77,19 +77,19 @@
|
||||
{timezone,theme,syncMinutes,retentionDays,beforeMinutes,notifyBefore,notifyAfter}
|
||||
```
|
||||
|
||||
`PUT /api/v1/settings/general` 接受完整对象。`syncMinutes` 为 1–60，`retentionDays` 为 30–365，`beforeMinutes` 为 1–1440，时区必须能由 Go 加载；非法值返回 400。成功返回保存后的对象。
|
||||
任意非 `GET` 方法都按更新处理，前端使用 `PUT`；请求接受完整对象。`syncMinutes` 为 1–60，`retentionDays` 为 30–365，`beforeMinutes` 为 1–1440，时区必须能由 Go 加载；非法值返回 400。成功返回保存后的对象。
|
||||
|
||||
### SMTP
|
||||
|
||||
- `GET /api/v1/settings/smtp` 返回 `{host,port,username,from,fromName,to,security,enabled,configured}`；`password` 为空或省略，默认端口 587、默认 `security=starttls`。
|
||||
- `PUT /api/v1/settings/smtp` 接受完整设置；`password` 留空时保留旧秘密。host、合法端口、from、to 必填；成功响应不返回密码。
|
||||
- 任意非 `GET` 方法都按更新处理，前端使用 `PUT`；接受完整设置，`password` 留空时保留旧秘密。host、合法端口、from、to 必填；成功响应不返回密码。
|
||||
- `POST /api/v1/settings/smtp/test` 使用已保存配置发送测试邮件；成功 `200 {ok:true}`，发送失败 502。
|
||||
- `security` 的当前运行值为 `starttls`、`tls` 或 `none`。
|
||||
- 前端为 `security` 提供 `starttls`、`tls` 和 `none`；后端当前不对该字段做白名单校验，其他值会落入无 TLS 分支。
|
||||
|
||||
### Telegram
|
||||
|
||||
- `GET /api/v1/settings/telegram` 返回 `{chatId,enabled,menuEnabled,configured,botName?}`，不返回 Token 明文。
|
||||
- `PUT /api/v1/settings/telegram` 接受 `{token,chatId,enabled,menuEnabled}`；Token 留空时保留旧值，保存前调用 Bot API `getMe` 验证。失败返回 400 或 502。
|
||||
- 任意非 `GET` 方法都按更新处理，前端使用 `PUT`；接受 `{token,chatId,enabled,menuEnabled}`，Token 留空时保留旧值，保存前调用 Bot API `getMe` 验证。失败返回 400 或 502。
|
||||
- `POST /api/v1/settings/telegram/bind` 返回六位 `{code}`，绑定码有效十分钟。
|
||||
- `POST /api/v1/settings/telegram/test` 向已绑定会话发送测试消息；未绑定或发送失败返回 502。
|
||||
|
||||
@@ -98,7 +98,7 @@
|
||||
| 方法与路径 | 行为 |
|
||||
| --- | --- |
|
||||
| `POST /api/v1/maintenance/cleanup` | 按当前保留天数删除旧限额快照、通知和每日用量，返回 `200 {deleted}`。 |
|
||||
| `GET /api/v1/maintenance/backup` | 使用 SQLite `VACUUM INTO` 生成包含已提交 WAL 数据的一致性快照，并以 `codex-helper.db` 下载。快照不含 `/data/secret.key` 或 Codex 凭据目录。 |
|
||||
| `任意方法 /api/v1/maintenance/backup` | 使用 SQLite `VACUUM INTO` 生成包含已提交 WAL 数据的一致性快照，并以 `codex-helper.db` 下载；非 `GET`/`HEAD` 还需来源头，前端使用 `GET`。快照不含 `/data/secret.key` 或 Codex 凭据目录。 |
|
||||
|
||||
## 7. 外部协议边界
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
所有请求使用相对 `/api/v1/`、`credentials: same-origin`、JSON content type 和 `X-Requested-With: codex-helper`。非 2xx 响应优先显示 `{error}`，否则退化为 HTTP 状态。新增下载或非 JSON 响应不能直接套用当前 `api` helper。
|
||||
|
||||
后端的 optional、`null`、空数组及 unknown 套餐必须在 TypeScript 中准确表达。邮箱在账号选择器、总览和设置中统一经过 `maskEmail`；不得把未掩码邮箱添加到新的可见位置。
|
||||
当前 `main.tsx` 的 API 类型将部分后端 `null` 值建模为 optional，渲染层通过 truthy 检查同时兼容 `undefined` 和 `null`；空数组及 unknown 套餐按后端返回值处理。邮箱在 Web 界面的账号选择器、总览和设置中统一经过 `maskEmail`；不得把未掩码邮箱添加到新的 Web 可见位置。Telegram `/account` 是独立的已绑定会话输出，当前显示完整邮箱。
|
||||
|
||||
## 总览与设置
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@
|
||||
|
||||
## 前端与部署
|
||||
|
||||
- 所有可见邮箱继续掩码。账号切换清空旧 Dashboard；删除账号清除设备码和 localStorage 选择。
|
||||
- Web 界面中的所有可见账号邮箱继续掩码；Telegram `/account` 当前会向已绑定会话显示完整邮箱。账号切换清空旧 Dashboard；删除账号清除设备码和 localStorage 选择。
|
||||
- 非活动设置 panel 保持 `inert`，tab 键盘和布局稳定性是现有可访问性契约。
|
||||
- 前端生产资源嵌入 Go 二进制；Docker build stage 的复制顺序变化必须验证实际嵌入的是新产物。
|
||||
- `/data` 是唯一完整恢复单元。数据库快照不含 `secret.key` 和 Codex 凭据；任何文档不得暗示其可完整灾难恢复。
|
||||
|
||||
Reference in New Issue
Block a user