31 lines
2.6 KiB
Markdown
31 lines
2.6 KiB
Markdown
# 后端运行时与 API
|
||
|
||
## 启动与关闭
|
||
|
||
入口为 `backend/cmd/server/main.go`。普通启动调用 `app.New`：打开 `/data/codex-helper.db` 并执行兼容迁移、打开或创建 `/data/secret.key`、创建 CLIProxyAPI 客户端、为数据库中的每个账号创建内存 Dashboard 运行时，再组装 HTTP server。`Run` 启动首次账号同步、后台调度器和 Telegram long polling；SIGINT/SIGTERM 触发五秒 HTTP 优雅关闭并关闭数据库。
|
||
|
||
`codex-helper healthcheck` 将 `${LISTEN_ADDR:-:8080}` 的通配地址转换为 `127.0.0.1` 并请求 `/health/live`，供 Docker `HEALTHCHECK` 使用。
|
||
|
||
## 组件职责
|
||
|
||
- `internal/app/app.go`：应用生命周期、账号内存运行时、调度和 HTTP 路由。
|
||
- `internal/app/api.go`：认证后的业务 API、CPA 账号绑定与 Dashboard 同步。
|
||
- `internal/app/notify.go`：SMTP、Telegram、提醒生成和发送。
|
||
- `internal/store/store.go`：SQLite schema、兼容迁移和数据方法。
|
||
- `internal/cliproxy/`：CLIProxyAPI Management API、`api-call` 包装及 `/wham/*` 响应解析。
|
||
|
||
所有路由由 `http.ServeMux` 承载。API 先处理 status、setup、login 和初始化后的账号/Dashboard 匿名只读入口，再统一调用 `require`；前端资源从 Go `embed.FS` 提供，未知浏览器路径回退到 `index.html`。完整端点以 [`backend/CONTRACT.md`](../../backend/CONTRACT.md) 为准。
|
||
|
||
## 后台任务
|
||
|
||
- 应用启动后异步同步全部已绑定 CPA authIndex，避免外部服务暂时不可用阻止 HTTP 启动。
|
||
- 独立同步调度器每五分钟固定触发全账号同步，最多并发同步四个账号；通用设置中的 `syncMinutes` 仅为旧客户端兼容字段，不改变固定周期。
|
||
- 独立维护调度器每分钟清理过期历史并异步处理提醒，CPA 同步变慢不得阻塞该分钟任务。
|
||
- `telegramLoop` 使用 Bot API long polling；仅已配置 Token 才请求更新。
|
||
|
||
这些 goroutine 都以应用 context 为退出边界。每账号 `syncing` mutex 串行手动同步、定时同步和 Dashboard 读取；修改调度时必须避免无限阻塞、重复启动和同一账号并发同步。CPA 同步失败会保留旧 Dashboard 并标记 stale，不得清空仍有效的历史快照。
|
||
|
||
## 状态语义
|
||
|
||
`/health/live` 只表示 HTTP 进程存活；`/health/ready` 还检查 SQLite，并返回 `cpa` 布尔值。`/api/v1/system/status` 也返回同一 `cpa` 配置状态。该字段只表示 CPA base URL 和 management key 均已配置，不代表每个 authIndex 或上游 `/wham/*` 当前可用；具体账号状态由账号列表和 Dashboard 的 `connected`、`stale`、`lastError` 表达。
|