feat: migrate account usage to CLIProxyAPI

README.md

@@ -1,6 +1,6 @@
 # Codex Helper
 
-一个单容器运行的 Codex 账户用量仪表盘。通过 Codex app-server 读取当前 ChatGPT/Codex 账户、套餐、限额窗口、重置时间和每日 Token 历史，并支持 Telegram 与 SMTP 重置提醒。
+一个单容器运行的 Codex 账户用量仪表盘。通过 CLIProxyAPI（CPA）Management API 读取已托管 Codex 凭据对应的 ChatGPT 账户、套餐、限额窗口、重置时间和每日 Token 历史，并支持 Telegram 与 SMTP 重置提醒。
 
 ## 功能
 
@@ -13,25 +13,37 @@
 - 通过 Telegram 菜单查询当前用量、重置时间、历史概览和账户信息
 - 初始化后无需登录即可查看公开只读账号总览；只有登录管理员后才能添加账号、同步用量和修改运行期配置
 - 前端适配 320px 起的手机浏览器，支持移动底部导航、iOS 安全区与深浅主题
-- React 前端、Go 后端、Codex CLI 和 SQLite 运行在同一个容器中
+- React 前端、Go 后端和 SQLite 运行在同一个容器中；Codex OAuth 凭据统一由外部 CLIProxyAPI 管理
 
 ## 运行要求
 
 - Docker Engine
 - Docker Compose v2（使用 `docker compose` 命令）
-- 一台能够访问 GitHub、OpenAI 登录页面及 Codex 服务的主机
-- 一个可使用 Codex 的 ChatGPT 账户
+- 已运行并启用 Management API 的 CLIProxyAPI 实例
+- CLIProxyAPI 中至少一个可用的 Codex OAuth 凭据及其 `auth_index`
+- Codex Helper 容器能够访问 CLIProxyAPI；CLIProxyAPI 能够访问 ChatGPT Codex 服务
 
-项目不需要单独准备 OpenAI API Key。当前界面使用 ChatGPT 设备码登录，并由容器内的 Codex app-server 保存和刷新登录凭据。OpenAI 官方的设备码流程说明见 [Codex App Server 文档](https://learn.chatgpt.com/docs/app-server#3b-log-in-with-chatgpt-device-code-flow)。
+项目不需要单独准备 OpenAI API Key，也不在本地执行 Codex 登录。Codex OAuth 登录、Token 保存和刷新全部由 CLIProxyAPI 负责；Codex Helper 只保存 CPA `authIndex`，并通过受 management key 保护的服务端请求读取数据。
 
 ## 安装
 
 ```bash
 git clone git@github.com:zhoujun0601/codex-helper.git
 cd codex-helper
+cp .env.example .env
+# 编辑 .env，填写 CLIProxyAPI Management API 地址和 management key
 docker compose up -d --build
 ```
 
+`.env` 至少包含：
+
+```dotenv
+CLIPROXY_API_BASE_URL=http://host.docker.internal:8317
+CLIPROXY_API_MANAGEMENT_KEY=replace-with-management-key
+```
+
+如果 CLIProxyAPI 位于另一个容器网络，请把两个服务加入同一网络，并将 `CLIPROXY_API_BASE_URL` 改为对应服务名。Codex Helper 从另一个容器访问 CPA Management API 时，CPA 的 `remote-management.allow-remote` 必须允许该来源，且 `remote-management.secret-key` 必须已配置。
+
 查看运行状态：
 
 ```bash
@@ -53,20 +65,16 @@ http://服务器地址:8180
 
 ## 连接 Codex 账户
 
-1. 使用管理员账号登录 Codex Helper。
-2. 打开“设置中心” → “Codex”。
-3. 点击“生成设备码”。
-4. 点击页面显示的 OpenAI 验证地址，或在另一台设备的浏览器中打开该地址。
-5. 登录需要监控的 ChatGPT/Codex 账户。
-6. 输入页面显示的一次性设备码并确认授权。
-7. 返回 Codex Helper，服务器会在后台自动同步账号用量；首次同步通常会在数秒内完成，之后固定每 5 分钟同步一次。
-8. 页面显示账户邮箱、套餐和限额窗口后，即表示连接成功。
+1. 先在 CLIProxyAPI 中完成 Codex OAuth 登录，确认凭据状态可用。
+2. 从 CPA `GET /v0/management/auth-files` 或其管理面板取得该凭据的 `auth_index`。
+3. 使用管理员账号登录 Codex Helper。
+4. 打开“设置中心” → “Codex”。
+5. 输入 CPA `authIndex`，选择预期的个人订阅或 Team / Business 类型，并点击“添加账号”。
+6. Codex Helper 会先验证该索引唯一指向未禁用的 Codex 凭据，再读取账号信息和用量；成功后立即显示，之后固定每 5 分钟同步一次。
 
-设备码授权在浏览器中完成，适用于 Docker、NAS 和远程服务器。默认连接的登录凭据保存在 `/data/codex`，新增连接保存在 `/data/accounts/<账号 ID>/codex`，不会写入浏览器或项目源码。
+每条本地账号记录只保存一个 CPA `authIndex` 及显示配置，不保存 access token、refresh token 或 CPA management key。删除账号只删除 Codex Helper 中的绑定、历史快照和提醒记录，**不会删除 CLIProxyAPI 中的凭据**。
 
-如需添加其他账号，或同一邮箱下的个人订阅与 Team 工作区，请在“设置中心” → “Codex”中分别创建连接并完成设备码登录。每个连接使用隔离的登录凭据，可自定义名称；总览页会同时展示所有连接，点击账号卡片即可查看完整详情。删除连接会同时删除对应凭据和历史数据。
-
-创建连接时可选择预期的“个人订阅”或“Team / Business 工作区”。授权完成后，Codex Helper 会使用 app-server 返回的真实套餐进行校验；`team` 和当前 Business 系列套餐均识别为团队工作区。设备码接口本身不能指定工作区 ID，因此同一邮箱包含多个空间时，需要在授权页面进入目标空间；如果页面提示类型不匹配，请退出该连接后重新授权。
+同一邮箱下的个人订阅与 Team 工作区应在 CPA 中保留为不同凭据，并分别使用各自的 `auth_index` 添加。Codex Helper 使用 CPA 返回的 ID token claims 和 `/wham/usage` 的真实套餐进行校验；未知新套餐会安全显示为 unknown，不会自动猜测类型。
 
 ## 通用设置与提醒时间
 
@@ -78,7 +86,7 @@ http://服务器地址:8180
 - 提前提醒时间：重置前 1–1440 分钟
 - 是否发送重置前提醒和重置后确认；重置后确认也会通过额度百分比回落识别并提醒官方活动、临时补发等提前重置
 
-提醒只会针对 Codex app-server 返回的限额窗口发送。发送失败的提醒会在计划时间后的六小时内自动重试。
+提醒只会针对通过 CLIProxyAPI 读取到的 Codex 限额窗口发送。发送失败的提醒会在计划时间后的六小时内自动重试。
 
 ## 配置 Telegram
 
@@ -154,7 +162,8 @@ curl http://localhost:8180/health/ready
 
 - `codex-helper.db`：管理员、设置、历史用量和通知记录
 - `secret.key`：用于解密 SMTP 密码和 Telegram Token
-- `codex/`：Codex 登录凭据及配置
+
+Codex OAuth 凭据不在该数据卷中，而是保存在 CLIProxyAPI 自己的凭据存储中。
 
 登录管理页面后，可直接在浏览器访问以下地址下载一致性 SQLite 快照：
 
@@ -162,40 +171,40 @@ curl http://localhost:8180/health/ready
 http://服务器地址:8180/api/v1/maintenance/backup
 ```
 
-SQLite 快照不包含 `secret.key` 和 `codex/`。完整灾难恢复必须同时备份整个 `/data` 数据卷；恢复时先停止容器，再恢复全部内容，并确保文件所有者仍可被容器中的 UID `10001` 读取。
+SQLite 快照不包含 `secret.key`。恢复 Codex Helper 本身必须同时备份整个 `/data` 数据卷；CLIProxyAPI 的配置与 OAuth 凭据需要按照 CPA 自身的备份方式单独保护。恢复时先停止容器，再恢复全部内容，并确保文件所有者仍可被容器中的 UID `10001` 读取。
 
 不要使用 `docker compose down -v`，该命令会删除持久数据卷。
 
 ## 数据边界
 
-Codex Helper 展示的是 Codex app-server 实际返回的数据。当前接口提供：
+Codex Helper 通过 CLIProxyAPI 代请求 ChatGPT 的内部 Codex 接口。当前使用的数据源包括 `/wham/usage`、`/wham/profiles/me` 和可选的 `/wham/rate-limit-reset-credits`，提供：
 
 - ChatGPT/Codex 账户和套餐类型
 - 限额窗口使用百分比、窗口长度和重置时间
 - 当前重置周期 Token 合计、本周期单日峰值等摘要
 - 每日总 Token 桶
 
-当前总览的 Token 合计按 app-server 返回的当前有效最长限额窗口汇总每日 Token bucket，通常对应 secondary 周窗口；周期边界所在日期按整日统计。系统不根据 Token 推算 Credits、美元价值或订阅价格。部分摘要或每日数据也可能因账户或服务端暂未返回而显示为“暂无”。根据 OpenAI 官方文档，`account/usage/read` 需要 Codex 服务支持的身份认证；仅 API Key 或 Bedrock 登录不能读取这些 ChatGPT 用量数据。
+当前总览的 Token 合计按最长有效限额窗口汇总 `/wham/profiles/me` 返回的每日 Token bucket，通常对应周窗口；周期边界所在日期按整日统计。系统不根据 Token 推算 Credits、美元价值或订阅价格。额度与 Profile Token 活动来自不同的上游聚合链路，刷新时间可能不一致；缺失数据会显示为“暂无”。这些 `/wham/*` 路径属于 ChatGPT/Codex 内部接口，上游可能调整字段或访问规则。
 
 ## 常见问题
 
-### 页面显示“app-server 未连接”
+### 页面显示“CLIProxyAPI 未配置或不可用”
 
-先查看日志并重启服务：
+先核对 `.env` 中的 `CLIPROXY_API_BASE_URL` 和 `CLIPROXY_API_MANAGEMENT_KEY`，然后查看日志：
 
 ```bash
 docker compose logs --tail=200 codex-helper
 docker compose restart codex-helper
 ```
 
-确认主机时间准确、DNS 和 HTTPS 出站访问正常。应用会自动重启并重新初始化异常的 app-server 进程。
+确认 CPA Management API 已启用、management key 匹配、远程访问策略允许 Codex Helper 容器，并检查两个容器之间的网络连通性。日志和 API 错误不会输出 management key 或 OAuth Token。
 
-### 完成设备码授权后仍显示“尚未连接”
+### 添加 authIndex 后仍显示“尚未连接”
 
-- 等待首次后台同步完成；之后服务器每 5 分钟自动同步一次。若持续未连接，请检查 app-server 和网络日志。
-- 确认授权的是需要监控的 ChatGPT 账户。
-- 重新进入 Codex 设置，退出账户后再次生成设备码。
-- 检查 `docker compose logs -f codex-helper` 中是否存在网络或认证错误。
+- 确认该索引来自当前配置的 CLIProxyAPI 实例。
+- 确认对应凭据的 provider/type 是 `codex` 且未 disabled；额度耗尽时 CPA 可能暂时标记 unavailable，这不会阻止 Codex Helper 尝试读取重置时间。
+- 在 CPA 中检查 OAuth Token 刷新是否成功。
+- 点击账号的“立即同步”，并检查 `docker compose logs -f codex-helper` 中的非敏感错误信息。
 
 ### Telegram 无法绑定
 
@@ -232,7 +241,9 @@ npm run dev
 ```bash
 cd backend
 export DATA_DIR=/tmp/codex-helper-data
+export CLIPROXY_API_BASE_URL=http://127.0.0.1:8317
+export CLIPROXY_API_MANAGEMENT_KEY=replace-with-management-key
 go run ./cmd/server
 ```
 
-本地开发需要 Go、Node.js、npm，并确保 `codex` 命令在 `PATH` 中。Vite 默认将 `/api` 和 `/health` 代理到 `http://localhost:8080`。
+本地开发需要 Go、Node.js 和 npm，并需要一个可访问的 CLIProxyAPI 实例。Vite 默认将 `/api` 和 `/health` 代理到 `http://localhost:8080`。