codex-helper/docs/backend/runtime-and-api.md

后端运行时与 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 为准。

后台任务

• 应用启动后异步同步全部已绑定 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 表达。