feat: migrate account usage to CLIProxyAPI

docs/README.md

@@ -8,7 +8,7 @@
 | --- | --- |
 | 修改启动、路由、中间件、健康检查或后台任务 | [`backend/runtime-and-api.md`](backend/runtime-and-api.md) |
 | 修改初始化、登录、session、请求来源或秘密 | [`backend/authentication-and-security.md`](backend/authentication-and-security.md) |
-| 修改 Codex 登录、账号进程、同步、套餐或用量解析 | [`backend/codex-integration-and-usage.md`](backend/codex-integration-and-usage.md) |
+| 修改 CLIProxyAPI 绑定、账号同步、套餐或用量解析 | [`backend/codex-integration-and-usage.md`](backend/codex-integration-and-usage.md) |
 | 修改 SQLite、提醒、Telegram、SMTP、清理或备份 | [`backend/data-notifications-and-backup.md`](backend/data-notifications-and-backup.md) |
 | 修改 React 路由、总览、设置、状态或 API 调用 | [`frontend/application.md`](frontend/application.md) |
 | 开发、构建、测试或检查格式 | [`guides/development-and-validation.md`](guides/development-and-validation.md) |

docs/backend/authentication-and-security.md

@@ -2,7 +2,7 @@
 
 ## 初始化与管理员
 
-新数据库始终创建账号表中的默认 Codex 账号，但只有 `settings.initialized` 存在才视为完成安装。`POST /api/v1/setup` 在事务中创建唯一 `admin(id=1)`、通用设置和安装标记；用户名至少 3 位、密码至少 10 位。首次初始化没有额外安装令牌，因此初始化完成前不得把实例直接暴露到不可信网络。
+新数据库不预建 Codex 账号；管理员初始化后通过 CPA `authIndex` 添加绑定。只有 `settings.initialized` 存在才视为完成安装。`POST /api/v1/setup` 在事务中创建唯一 `admin(id=1)`、通用设置和安装标记；用户名至少 3 位、密码至少 10 位。首次初始化没有额外安装令牌，因此初始化完成前不得把实例直接暴露到不可信网络。
 
 管理员密码使用 argon2id（3 次、64 MiB、2 lanes、32 字节结果和随机 salt）保存。当前没有改密或找回接口；不要通过新增旁路直接写入明文或弱摘要。
 
@@ -18,10 +18,10 @@
 
 `security.OpenVault` 首次启动创建权限 `0600` 的 `/data/secret.key`。SMTP 密码和 Telegram Bot Token 使用该 32 字节密钥经 AES-GCM 加密，密文写入 SQLite；GET 和保存响应不得返回秘密明文，空密码/Token 表示保留旧值。
 
-Codex OAuth 凭据由 app-server 写入各账号隔离的 `CODEX_HOME`，不经过浏览器或 SQLite。`secret.key`、数据库、Codex 目录和日志都可能包含敏感运行信息，不得提交 Git、加入镜像层或复制到前端。
+Codex OAuth 凭据由外部 CLIProxyAPI 保存和刷新，不进入 Codex Helper。每条本地账号记录只保存非秘密的 CPA `authIndex`；`CLIPROXY_API_MANAGEMENT_KEY` 只从服务端环境变量读取，不写入 SQLite、日志、前端状态或响应。`secret.key`、数据库、部署 `.env`、CPA management key 和 CPA 凭据目录都属于敏感运行信息，不得提交 Git、加入镜像层或复制到前端。
 
 ## HTTP 边界
 
-初始化完成后，标记为公开的账号列表和 Dashboard 以匿名只读方式开放，供公开总览加载；未标记账号对匿名请求不可见。匿名响应不返回邮箱、Codex 认证方式、账号配置校验字段或内部错误。新增账号、设备码登录、同步、删除、公开状态修改、提醒和所有设置接口仍必须经过 `require` 的 session 与来源校验。
+初始化完成后，标记为公开的账号列表和 Dashboard 以匿名只读方式开放，供公开总览加载；未标记账号对匿名请求不可见。匿名响应不返回邮箱、CPA authIndex、Codex 认证方式、账号配置校验字段或内部错误。新增或修改 CPA 绑定、同步、删除、公开状态修改、提醒和所有设置接口仍必须经过 `require` 的 session 与来源校验。
 
-JSON 解码限制为 1 MiB 并拒绝未知字段。统一安全头包括限制性 CSP、`nosniff`、禁止 iframe 和 same-origin referrer。前端路由、按钮禁用和邮箱掩码均不是服务端授权边界；所有新敏感端点必须在后端经过 `require`，改变 API 方法时还要核对来源头逻辑。
+JSON 解码限制为 1 MiB 并拒绝未知字段。统一安全头包括限制性 CSP、`nosniff`、禁止 iframe 和 same-origin referrer。前端路由、按钮禁用和邮箱掩码均不是服务端授权边界；所有新敏感端点必须在后端经过 `require`，改变 API 方法时还要核对来源头逻辑。公开账号响应必须清空 `authIndex`，避免把 CPA 内部凭据标识暴露给匿名访问者。

docs/backend/codex-integration-and-usage.md

@@ -1,39 +1,53 @@
-# Codex 集成与用量同步
+# CLIProxyAPI 与 Codex 用量同步
 
-## 账号隔离与进程生命周期
+## 外部依赖与凭据边界
 
-每个 `accounts` 记录对应一个 `accountRuntime` 和独立 `codex app-server` 子进程。账号 1 为升级兼容固定使用 `/data/codex`；其他账号使用 `/data/accounts/<id>/codex`。该目录通过子进程 `CODEX_HOME` 注入，保存并刷新 ChatGPT 登录凭据。
+Codex Helper 不再启动 `codex app-server`，也不保存 Codex OAuth token。所有 Codex 登录、凭据持久化和刷新均由外部 CLIProxyAPI（CPA）负责；本项目只通过环境变量读取：
 
-`ensureReady` 用 lifecycle mutex 串行冷启动：创建目录、启动子进程、在 20 秒内调用 `initialize`，成功后才标记 ready。仅子进程存活不代表协议已初始化；失败进程必须关闭后重试。`syncing` mutex 串行同账号同步并保护 Dashboard，`stateMu` 保护 ready/stopped。删除账号先从应用 map 移除并停止进程，再删除数据库和精确凭据目录。
+- `CLIPROXY_API_BASE_URL`：CPA Management API 根地址。
+- `CLIPROXY_API_MANAGEMENT_KEY`：CPA management key，只进入服务端请求头，不写入 SQLite、日志或前端响应。
 
-## JSONL 协议与登录
+每条 `accounts` 记录保存一个唯一的非空 `auth_index`。添加或修改绑定时，后端先调用 CPA `GET /v0/management/auth-files?auth_index=...`，确认索引唯一匹配、provider/type 为 `codex`，且凭据未 disabled。CPA 的临时 `unavailable`/error 状态可能正是额度耗尽导致，不能据此拒绝读取，否则仪表盘无法显示 100% 用量和重置时间。账号邮箱、套餐和 ChatGPT account ID 来自该认证条目的安全元数据与 ID token claims；原始 token 不会进入 Codex Helper。
 
-客户端以 stdio 启动 `codex app-server`，每行一个 JSON 消息。递增 ID 将响应关联到 buffered channel；请求受调用 context 或 20 秒 timeout 控制。旧进程晚退出时不能把替代进程标记为断开。
+旧数据库迁移会为已有账号增加空 `auth_index`。这些账号会保持未连接，直到管理员在设置页绑定 CPA authIndex。新数据库不再自动创建无凭据的默认账号。
 
-设备码登录调用：
+## Management API 代请求
 
-```text
-account/login/start {type:"chatgptDeviceCode"}
-```
+后端通过 CPA `POST /v0/management/api-call` 发起上游请求，请求体使用 `auth_index` 选择凭据，并在 Authorization 中传递 `Bearer $TOKEN$` 占位符，由 CPA 注入和刷新真实 access token。关键上游请求是：
 
-前端展示 `verificationUrl` 与 `userCode`。收到 `account/login/completed`、`account/updated` 或 `account/rateLimits/updated` 后异步重拉数据；登录完成最多以 0、1、3 秒退避等待套餐分类可用。官方流程和字段见 [Codex App Server 文档](https://learn.chatgpt.com/docs/app-server)。Dockerfile 固定的 CLI 版本及项目测试仍是实际兼容基线。
+- `GET https://chatgpt.com/backend-api/wham/usage`：套餐、普通限额、代码审查限额、`additional_rate_limits` 和可用重置卡摘要。
+- `GET https://chatgpt.com/backend-api/wham/profiles/me`：Token 活动摘要与每日 bucket。
+- `GET https://chatgpt.com/backend-api/wham/rate-limit-reset-credits`：可选的重置卡详情及到期时间。
 
-## 同步数据流
+CPA HTTP 层和包装的上游状态分别校验。错误只包含安全的阶段、HTTP 状态和上游错误类型，不包含 management key、OAuth token、原始响应正文或 CPA 凭据内容。请求均有超时和响应体大小限制。
 
-一次同步依次读取 `account/read`、`account/rateLimits/read` 和 `account/usage/read`：
+这些 `/wham/*` 路径属于 ChatGPT/Codex 内部接口，并非稳定公开 API；CLIProxyAPI 版本、当前解析代码和测试是本项目的实际兼容基线。
 
-- `account/read` 决定连接、邮箱、认证模式和套餐；读取失败会使整次同步失败。
-- 限额读取兼容 `rateLimitsByLimitId` 多 bucket 和旧 `rateLimits` 单 bucket，再把 primary/secondary 展平；同时读取 `rateLimitResetCredits`，只在有可用卡时保留数量和到期时间。失败时保留空限额而不令整次同步失败。
-- 套餐未知时，可从所有可分类且一致的限额 bucket 回填；冲突或未知时必须保持 unknown。
-- 用量读取保存 summary 和每日 Token bucket；接口失败时使用空摘要和空历史，不令整次同步失败。同步成功后，以当前仍有效的最长限额窗口作为当前重置周期，按每日 bucket 汇总周期起点至当前日期的 Token，写入 Dashboard 的 `currentCycle`；周期外和未来日期不会计入。
-- 每次限额同步写入快照、检测用量百分比显著回落，并更新账号元数据及内存 Dashboard。
+## 限额归一化
 
-`account/usage/read` 的 optional 指标和 daily buckets 可能暂未提供。仅 API Key 或 Bedrock 登录不能保证读取 ChatGPT 用量；不得在缺失数据时合成调用次数、输入/输出 Token、价格或账单日期。
+一次成功同步会把 `/wham/usage` 转换为现有 `Dashboard.Limits`：
 
-重置卡来自 `account/rateLimits/read` 的 `rateLimitResetCredits`。该信息只保存在内存 Dashboard 中，下一次同步会重新读取；没有可用卡时不返回到 Dashboard。当前项目只展示数量和到期时间，不执行消耗操作。
+- 顶层 `rate_limit` 使用稳定 `limitId=codex`。
+- `code_review_rate_limit` 使用稳定 `limitId=code_review`。
+- `additional_rate_limits[]` 优先使用 `metered_feature` 作为 limit ID，`limit_name` 作为显示名称；例如 Spark 的 `codex_bengalfox`。
+- `primary_window` 和 `secondary_window` 分别保留为 `windowType=primary|secondary`，前端依据窗口时长识别小时和周额度，不假定字段顺序。
+- `limit_window_seconds` 向上取整转换为分钟。
+- `used_percent` 限制在 0–100，但保留小数。
+- 重置时间优先使用 Unix 秒 `reset_at`；缺失时以本次响应时间加 `reset_after_seconds` 推算。
+- `plan_type` 未知时按原值保留，并由现有套餐分类逻辑安全显示为 unknown。
 
-`currentCycle` 的周期长度和重置时间来自 `account/rateLimits/read`，不硬编码为七天；通常会选择 secondary 周窗口。由于 daily bucket 只有日期没有每次请求时间，周期边界所在日期按整日汇总，因此该值是当前周期的日级统计，不是 Credits 或美元估值。
+可用重置卡数量优先以详情接口的 `available_count` 为准，详情接口失败时可退回 `/wham/usage` 的 `rate_limit_reset_credits.available_count`。只有状态为 available 且能解析 RFC3339 `expires_at` 的记录才进入到期时间列表；详情失败不影响主同步。
 
-## 套餐类型
+## Token 活动与当前周期
 
-用户期望类型仅为连接后的校验提示：`any`、`personal`、`team`。当前 personal 包括 free/go/plus/pro/prolite；team 包括 team/business 及两种 self-serve business 标识。未知新套餐必须显示 unknown，不能静默当作某一类型。相同邮箱和相同已知实际类型的多个账号标记 `possibleDuplicate`，但不会自动合并或删除。
+`/wham/profiles/me` 的 `stats` 提供 lifetime、单日峰值、最长任务、连续天数以及 `daily_usage_buckets`。每日 bucket 继续写入按 `account_id` 隔离的 `daily_usage`；optional、`null`、未来新增字段和暂缺 bucket 必须安全降级，不能合成调用次数、输入/输出 Token、价格或账单日期。
+
+同步成功后，以当前仍有效的最长限额窗口作为当前重置周期，按每日 bucket 汇总周期起点至当前日期的 Token，写入 `Dashboard.currentCycle`。周期边界只有日期粒度，因此边界日按整日汇总。额度和 Profile Token 活动来自不同上游聚合链路，数据新鲜度可能不同。
+
+## 调度、并发与失败
+
+应用启动后异步同步全部已绑定账号，之后固定每五分钟同步；手动同步和 Telegram 立即刷新使用同一链路。每个账号的 `syncing` mutex 串行同步并保护内存 Dashboard，不同账号仍保持数据库、历史和提醒隔离。
+
+`auth_index` 缺失、CPA 未配置、认证条目不可用或核心 `/wham/usage` 失败会使本次同步失败：已有 Dashboard 保留并标记 `stale=true`，内部错误仅对已登录管理员可见。`/wham/profiles/me` 的 Token 活动和重置卡详情都是可选数据；Profile 失败时同一进程内保留上次成功的摘要和每日历史，没有旧值时降级为空，重置卡详情失败时退回用量接口的可用数量。两者都不会隐藏已成功读取的额度窗口。成功同步会清除 stale/error、写入限额快照、检测百分比回落并更新账号元数据。
+
+删除账号只删除 Codex Helper 中的绑定、数据库历史和内存 Dashboard，不调用 CPA 删除认证文件。CPA OAuth 凭据的删除和恢复必须在 CLIProxyAPI 中单独执行。

docs/backend/data-notifications-and-backup.md

@@ -6,18 +6,18 @@
 
 - `settings` 保存通用、SMTP、Telegram、绑定码及安装标记；秘密单独以密文 key 保存。
 - `admin` 与 `sessions` 保存唯一管理员和登录会话。
-- `accounts` 保存 Codex 连接元数据、期望套餐类型和 `public_visible`；该字段默认 `0`，旧账号迁移后保持私有，只有管理员明确开启后才进入匿名总览。
+- `accounts` 保存唯一 CPA `auth_index`、Codex 连接元数据、期望套餐类型和 `public_visible`；公开响应会隐藏 `auth_index`。旧账号迁移后索引为空且保持私有，只有管理员绑定 CPA 凭据并明确开启后才进入匿名总览。
 - `daily_usage` 和 `limit_snapshots` 按 `account_id` 保存历史，删除账号时级联删除。
 - `notifications` 保存稳定去重键、调度时间、结构化消息、状态、次数和错误。
 - `telegram_updates` 保存 Bot API offset。
 
-启动迁移必须幂等并兼容早期单账号库：创建默认账号 1，把旧用量和限额数据迁入该账号，补 `expected_kind` 和通知 body。schema 变化应增加覆盖旧结构且保留已有行的测试。
+启动迁移必须幂等并兼容早期单账号库：已有默认账号 1 及其旧用量、限额数据继续保留，账号行补空 `auth_index`、`expected_kind` 和通知 body；新数据库不再主动创建默认账号。schema 变化应增加覆盖旧结构且保留已有行的测试。
 
 ## 清理与备份
 
 每分钟调度器根据 `retentionDays` 清理旧限额、通知和每日用量；允许范围为 30–365 天。`maintenance/backup` 使用 SQLite `VACUUM INTO` 创建独立一致性快照，包含已提交 WAL 数据且不中断写入。
 
-数据库快照不包含 `/data/secret.key`、`/data/codex` 或 `/data/accounts/*/codex`，因此不能单独恢复通知凭据和 Codex 登录。完整灾难恢复必须停止容器并备份、恢复整个 `/data`，同时保持 UID `10001` 可读。不得把 `docker compose down -v` 写成普通升级步骤。
+数据库快照不包含 `/data/secret.key`，因此不能单独恢复通知凭据。Codex OAuth 凭据位于外部 CLIProxyAPI，不属于 Codex Helper 备份；两套服务必须分别备份。恢复 Codex Helper 必须停止容器并备份、恢复整个 `/data`，同时保持 UID `10001` 可读。不得把 `docker compose down -v` 写成普通升级步骤。
 
 ## 提醒生成与重试
 

docs/backend/runtime-and-api.md

@@ -1,26 +1,30 @@
-# 后端运行与 API
+# 后端运行时与 API
 
 ## 启动与关闭
 
-入口为 `backend/cmd/server/main.go`。普通启动调用 `app.New`：打开 `/data/codex-helper.db` 并执行兼容迁移、打开或创建 `/data/secret.key`、为数据库中的每个账号创建运行时对象，再组装 HTTP server。`Run` 启动 app-server 保活、后台调度器和 Telegram long polling；SIGINT/SIGTERM 触发五秒 HTTP 优雅关闭、停止所有账号进程并关闭数据库。
+入口为 `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/v1/` 分派、初始化、会话、账号和用量同步。
+- `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/codex/client.go`：与 `codex app-server` 的 JSONL 请求/响应关联。
+- `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) 为准。
 
 ## 后台任务
 
-- `keepCodex` 每秒检查未就绪的账号，串行完成进程启动与协议初始化，成功后立即同步。
-- `scheduler` 每五分钟固定触发全账号同步；每分钟清理过期历史并异步处理提醒。通用设置中的 `syncMinutes` 仅为旧客户端兼容字段，不改变固定调度周期。
+- 应用启动后异步同步全部已绑定 CPA authIndex，避免外部服务暂时不可用阻止 HTTP 启动。
+- 独立同步调度器每五分钟固定触发全账号同步，最多并发同步四个账号；通用设置中的 `syncMinutes` 仅为旧客户端兼容字段，不改变固定周期。
+- 独立维护调度器每分钟清理过期历史并异步处理提醒，CPA 同步变慢不得阻塞该分钟任务。
 - `telegramLoop` 使用 Bot API long polling；仅已配置 Token 才请求更新。
-- app-server 的登录、账号和限额通知会触发带短退避的同步；多次失败将内存 Dashboard 标为 stale 并记录 `lastError`。
 
-这些 goroutine 都以应用 context 为退出边界。修改调度时必须避免无限阻塞、重复启动、停止后重启和同一账号并发同步。
+这些 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` 表达。

docs/frontend/application.md

@@ -18,9 +18,9 @@ API 类型精确区分后端 `null` 与 optional，并为秘密设置拆分读
 
 ## 总览与设置
 
-总览显示账户连接、套餐、每个限额窗口的剩余百分比和重置时间、当前重置周期 Token 合计、本周期单日峰值、其他摘要及每日 Token 图；账号有可用重置卡时，详情额外显示卡片数量和到期时间，公开账号的匿名总览也会显示。当前周期 Token 与本周期单日峰值都由后端按 app-server 的有效最长限额窗口和每日 bucket 汇总，不包含周期外或未来日期；详情会显示周期起止时间和“按每日数据汇总”提示。`usedPercent` 展示前限制到 0–100，但原始数据语义不得在 API 类型层改写。缺失摘要显示“暂无”，缺失限额显示明确空状态。匿名公开 Dashboard 仍隐藏邮箱、认证方式和内部错误。
+总览显示账户连接、套餐、每个限额窗口的剩余百分比和重置时间、当前重置周期 Token 合计、本周期单日峰值、其他摘要及每日 Token 图；账号有可用重置卡时，详情额外显示卡片数量和到期时间，公开账号的匿名总览也会显示。当前周期 Token 与本周期单日峰值都由后端按 CPA 返回的有效最长限额窗口和 `/wham/profiles/me` 每日 bucket 汇总，不包含周期外或未来日期；详情会显示周期起止时间和“按每日数据汇总”提示。`usedPercent` 展示前限制到 0–100，但原始数据语义不得在 API 类型层改写。缺失摘要显示“暂无”，缺失限额显示明确空状态。匿名公开 Dashboard 仍隐藏邮箱、认证方式和内部错误。
 
-设置页四个 tab 全部保持挂载，以保留未提交表单状态；非活动 panel 使用 `aria-hidden` 和 `inert` 隔离。tab 支持方向键、Home 和 End，程序化切换不得改变页面滚动和布局。账号删除必须保留不可撤销确认，并清理正在显示的设备码和本地账号选择。
+设置页四个 tab 全部保持挂载，以保留未提交表单状态；非活动 panel 使用 `aria-hidden` 和 `inert` 隔离。tab 支持方向键、Home 和 End，程序化切换不得改变页面滚动和布局。Codex 设置通过 CPA `authIndex` 添加和修改本地绑定，不再提供设备码登录或退出按钮。账号删除必须明确说明只删除本地绑定与历史、不会删除 CLIProxyAPI 凭据，并清理本地账号选择。
 
 ## 验证重点
 

docs/guides/deployment.md

@@ -4,7 +4,7 @@
 
 ## 镜像结构
 
-`Dockerfile` 有四个阶段：Node 24.19.0 构建 React 静态资源；Go 1.26.0 以 `CGO_ENABLED=0` 构建后端；Node 阶段安装固定 `@openai/codex`；最终 Debian bookworm 镜像只包含 CA、时区、后端、Node runtime 和 Codex 包。`APP_VERSION` 构建参数通过 Go linker 注入状态 API，未指定时默认为 `0.3.0`，前端在品牌区域显示该版本。
+`Dockerfile` 有三个阶段：Node 24.19.0 构建 React 静态资源；Go 1.26.0 以 `CGO_ENABLED=0` 构建后端；最终 Debian bookworm 镜像只包含 CA、时区和后端二进制，不再包含 Node runtime 或 Codex CLI。`APP_VERSION` 构建参数通过 Go linker 注入状态 API，未指定时默认为 `0.3.0`，前端在品牌区域显示该版本。
 
 前端产物复制到 `backend/internal/web/dist` 后嵌入二进制。运行层使用 UID `10001` 的 system 用户 `helper`，默认 `DATA_DIR=/data`、`LISTEN_ADDR=:8080`，并暴露 `/data` volume 和 8080。健康检查调用二进制自身的 `healthcheck` 子命令。
 
@@ -22,7 +22,7 @@ bash push-image.sh 0.3.0
 
 ## Compose 与持久化
 
-`docker-compose.yml` 本地构建 `codex-helper:latest`，将宿主机 8180 映射到容器 8080，并把命名卷 `codex-helper-data` 挂载到 `/data`。全部数据库、密钥、Codex 配置和多账号凭据都依赖这个卷。
+`docker-compose.yml` 本地构建 `codex-helper:latest`，将宿主机 8180 映射到容器 8080，并把命名卷 `codex-helper-data` 挂载到 `/data`。该卷保存数据库和通知解密密钥；Codex OAuth 凭据由外部 CLIProxyAPI 保存。Compose 通过 `CLIPROXY_API_BASE_URL` 和 `CLIPROXY_API_MANAGEMENT_KEY` 注入 CPA Management API 配置，并为宿主机 CPA 提供 `host.docker.internal` 映射。
 
 升级应使用：
 
@@ -35,10 +35,10 @@ docker compose up -d --build
 
 ## 网络与安全
 
-应用自身监听 HTTP。公网部署应放在 HTTPS 反向代理后，初始化前限制访问来源，并保证到 OpenAI 登录/Codex 服务、Telegram Bot API 和所选 SMTP 服务的出站连接。当前只有 `LISTEN_ADDR` 是 Compose 显式环境变量；运行配置由前端保存到数据库。
+应用自身监听 HTTP。公网部署应放在 HTTPS 反向代理后，初始化前限制访问来源，并保证到 CLIProxyAPI、Telegram Bot API 和所选 SMTP 服务的出站连接。CPA 自身负责访问 ChatGPT Codex 服务。通用和通知配置由前端保存到数据库；CPA 根地址和 management key 只通过环境变量提供。
 
-设备码登录不需要 OpenAI API Key。Codex app-server 为每个 `CODEX_HOME` 管理 ChatGPT token；不要把这些目录暴露为静态文件或外部共享目录。
+`CLIPROXY_API_MANAGEMENT_KEY` 不得写入镜像、Compose 明文仓库配置、日志或前端。Codex Helper 从独立容器访问 CPA 时，CPA 必须启用带 secret key 的 Management API，并允许来自该容器网络的远程管理请求。只开放必要网络路径，不应把 CPA Management API 直接暴露到公网。
 
 ## 备份与恢复
 
-维护接口下载的 SQLite 快照适合查看或数据库级备份，但不包含解密密钥和 Codex 凭据。完整恢复步骤是：停止容器、备份或恢复整个 `/data`、确认 UID `10001` 可读写、再启动并检查 `/health/live`、`/health/ready`、管理员登录和各账号连接。恢复过程不得只替换数据库而遗失对应 `secret.key`。
+维护接口下载的 SQLite 快照适合查看或数据库级备份，但不包含解密密钥，也不包含外部 CPA 的 Codex 凭据。Codex Helper 恢复步骤是：停止容器、备份或恢复整个 `/data`、确认 UID `10001` 可读写、恢复正确的 CPA 环境变量，再启动并检查 `/health/live`、`/health/ready`、管理员登录和各账号连接。CLIProxyAPI 需要按其自身机制单独备份和恢复。恢复过程不得只替换数据库而遗失对应 `secret.key`。

docs/guides/development-and-validation.md

@@ -64,7 +64,7 @@ docker build -t codex-helper:test .
 | --- | --- |
 | 后端普通逻辑 | 相关 Go test、gofmt 检查、build、vet |
 | SQLite schema、迁移、备份 | 新旧 schema 测试、WAL 快照测试、完整后端门禁 |
-| app-server 生命周期或同步 | codex/app runtime 单测、并发和失败重试路径 |
+| CLIProxyAPI 客户端或同步 | Management API `httptest`、账号绑定、并发、失败与不泄密路径 |
 | 鉴权、session 或秘密 | security 与 app 测试、成功和拒绝路径 |
 | 通知 | reminder 渲染、去重、计划与异常重置测试 |
 | 前端 | 相关 Vitest、生产 build |

docs/reference/code-review-rules.md

@@ -25,9 +25,10 @@ findings 优先，按 `P0` 至 `P3` 排序。每条必须包含严重级别和
 - 匿名端点是否意外扩大；session、过期检查和非只读来源头是否在所有路径生效；cookie 改动是否适配 HTTPS 反代。
 - setup 是否事务化且不能覆盖管理员；登录限流是否存在竞态、无限内存或错误信任代理头。
 - SQLite migration 是否可从旧 schema 启动且保留数据；查询是否带正确 `account_id`；rows、transaction 和临时文件是否关闭。
-- 删除账号是否精确停止 runtime、级联历史并删除正确目录，尤其是账号 1 的旧路径。
-- app-server 生命周期是否可能双启动、停止后重启、死锁或由旧进程回调污染新进程；pending 请求在所有结束路径是否释放。
-- app-server optional/null、多 bucket、未知套餐和部分接口失败是否降级，而非生成错误数据或清除有效凭据。
+- 删除账号是否只删除精确的本地 runtime 和级联历史，且不会调用 CPA 删除凭据或误导用户。
+- CPA authIndex 是否在创建/修改前验证唯一、provider、状态和本地重复；失败是否可能留下半绑定账号。
+- CPA Management API 是否有 timeout、响应体大小限制、包装状态与上游状态双重校验；错误或日志是否泄露 management key、OAuth token 或原始正文。
+- `/wham/*` optional/null、多 bucket、未知套餐和部分接口失败是否按契约降级，而非生成错误数据或清除有效绑定。
 - 提醒是否稳定去重、限定六小时重试、正确区分 before/after/detected reset；多渠道部分失败是否按既定语义重试。
 - SMTP、Telegram 错误是否有 timeout、TLS 和 HTML 转义；设置接口、日志和错误是否泄露秘密。
 - 备份是否包含 committed WAL 且不阻塞写入；文案是否误称数据库快照为完整恢复包。
@@ -35,15 +36,15 @@ findings 优先，按 `P0` 至 `P3` 排序。每条必须包含严重级别和
 ## 前端专项
 
 - 初始化、未登录、登录态路由是否无闪烁或循环；401 后是否进入可恢复状态。
-- 切换或删除账号时，旧 Dashboard、设备码和 localStorage 是否清理；异步旧响应是否覆盖新账号。
+- 切换或删除账号时，旧 Dashboard 和 localStorage 是否清理；异步旧响应是否覆盖新账号。
 - API 类型是否准确表达 `null`、optional、unknown 和空列表；错误响应是否可能被当作成功。
 - 邮箱是否在所有可见位置掩码；服务端文本和外部 URL 是否以安全方式渲染。
-- effect、30 秒 polling、设备码 polling、timer 和 event handler 是否在卸载时清理。
+- effect、30 秒 polling、timer 和 event handler 是否在卸载时清理。
 - 设置 tab 是否保持键盘操作、`inert` 隔离、表单状态、滚动位置和窄屏无溢出。
 
 ## 部署与验证专项
 
-- 固定 Go、Node、Codex CLI 和 Playwright 版本是否同步 Dockerfile、lockfile 与文档；架构和静态构建是否匹配运行层。
+- 固定 Go、Node 和 Playwright 版本是否同步 Dockerfile、lockfile 与文档；架构和静态构建是否匹配运行层。
 - 静态前端是否在 Go build 前正确复制；`.dockerignore` 是否会丢失必须资源或带入运行数据。
 - 最终镜像是否继续非 root，`/data` 权限是否兼容 UID `10001`；Compose 升级是否复用原卷。
 - 新环境变量是否同步代码、Compose、README 和部署文档；秘密是否可能进入 build arg、镜像层或日志。

docs/reference/engineering-invariants.md

@@ -12,17 +12,19 @@
 ## 数据与账号
 
 - `internal/store/store.go` 是 SQLite schema 和兼容迁移的事实来源。启动迁移必须幂等、保留旧数据并启用 foreign keys。
-- 旧单账号数据迁到账号 1；账号 1 的凭据路径永久为 `/data/codex`，不能统一搬到 `accounts/1`。
-- 删除账号必须先停止并移除精确 runtime，再删除该账号数据库行和精确凭据目录；不得使用未校验路径、glob 或宽泛递归删除。
+- 旧单账号数据及账号 1 历史必须保留；迁移只为旧账号补空 `auth_index`，不得因切换 CPA 删除旧快照。新数据库不再预建空账号。
+- 每个非空 CPA `auth_index` 最多绑定一个本地账号。添加或修改绑定前必须验证索引唯一指向未禁用的 Codex auth，失败不得留下半创建或半更新记录；CPA 的 transient unavailable/error 可能表示额度耗尽，不能阻止额度读取。修改到不同 authIndex 时必须原子清除该本地账号的旧用量、限额和提醒历史，禁止串身份。
+- 删除账号只删除本地 runtime、数据库行及其级联历史，绝不能调用 CPA 删除凭据或误导用户认为 CPA auth 已删除。
 - `daily_usage` 与 `limit_snapshots` 以 `account_id` 隔离。任何查询、更新、提醒 key 或清理不得串账号。
 - `expectedKind` 只是校验期望；未知套餐保持 unknown。相同邮箱提示重复不能成为自动合并依据。
 
-## Codex 运行时
+## CLIProxyAPI 运行时
 
-- 每账号一套 app-server 和 `CODEX_HOME`。进程存活与协议 ready 是不同状态，初始化失败必须关闭旧进程。
-- lifecycle mutex 串行启动/停止，syncing mutex 串行同步和 Dashboard 访问，state mutex 保护 ready/stopped；不得以无锁读写替换。
-- 旧子进程晚退出不能断开新子进程或失败新请求。请求取消和 20 秒 timeout 必须清除 pending channel。
-- `account/read` 是同步的硬依赖；rate limits 与 usage 是可缺失数据。optional、`null`、多 bucket 和未知字段必须安全降级。
+- Codex Helper 不保存、返回或记录 CPA management key、OAuth access token、refresh token 或原始认证文件。公开账号响应必须清空 `authIndex`。
+- CPA base URL 和 management key 只从服务端环境读取。未配置不得阻止 setup/login，但所有账号同步必须明确失败并保留旧 Dashboard 为 stale。
+- 每账号 `syncing` mutex 继续串行同步和 Dashboard 访问；不得以无锁读写替换。
+- auth-files 验证、`api-call` 包装状态和上游状态必须分别检查。请求必须保留超时和响应体大小限制，错误不得包含原始上游正文。
+- `/wham/usage` 是额度同步的硬依赖；`/wham/profiles/me` Token 活动和重置卡详情是可缺失数据。optional、`null`、多 bucket、未知套餐和畸形附加限额必须安全降级或产生不泄密的同步错误，Profile 失败不得隐藏有效限额。
 
 ## 通知、外部输入与秘密
 
@@ -33,7 +35,7 @@
 
 ## 前端与部署
 
-- Web 界面中的所有可见账号邮箱继续掩码；Telegram `/account` 当前会向已绑定会话显示完整邮箱。账号切换清空旧 Dashboard；删除账号清除设备码和 localStorage 选择。
+- Web 界面中的所有可见账号邮箱继续掩码；Telegram `/account` 当前会向已绑定会话显示完整邮箱。账号切换清空旧 Dashboard；删除账号清除 localStorage 选择。公开账号响应不得暴露 CPA authIndex。
 - 非活动设置 panel 保持 `inert`，tab 键盘和布局稳定性是现有可访问性契约。
 - 前端生产资源嵌入 Go 二进制；Docker build stage 的复制顺序变化必须验证实际嵌入的是新产物。
 - `/data` 是唯一完整恢复单元。数据库快照不含 `secret.key` 和 Codex 凭据；任何文档不得暗示其可完整灾难恢复。