# billing

当前项目的本质是对 `CLIProxyAPI` 的核心扩展，功能边界会非常收敛

- 更好的统计、展示
- 初期优先保证codex的正常使用
- 能最简单的管理多用户key

## 参考

- `CLIProxyAPI` 原始项目
- `cpa-plugin-key-billing` CLIProxyAPI 下游 API Key 计费与订阅额度插件
- `cpa-usage-keeper` 用量持久化与分析面板

## 上游依赖与参考仓库边界

`.externals/CLIProxyAPI/` 是锁定官方基线的 Git submodule，用于宿主构建、契约核对和集成测试。宿主修复仍以根仓库 `patch/` 中的补丁维护，不直接提交到官方 submodule。

`.externals/cpa-plugin-key-billing/`、`.externals/cpa-usage-keeper/` 不是本项目的实际开发仓库，只用于测试、契约核对和实现对比。

- 默认不检查两个参考插件目录的 Git 状态、提交历史、分支、远端或工作区改动。
- 不为这两个参考插件仓库修复问题，不修改或提交其中的代码，也不处理其 Git 状态。
- 上述限制不影响运行时测试：可直接加载已经构建好的参考插件；测试 CPA 插件组合时，按需启用 `cpa-key-billing` 作为对照插件，但不得因此进入其仓库做源码或 Git 操作。
- 只有在 billing 的兼容性验证、测试或实现判断确有必要时，才按最小范围只读查看相关文件。
- CPA submodule 只允许按 `patch/README.md` 应用、验证或重新生成本项目维护的宿主补丁；除此以外的 CPA 修改，以及两个参考插件的修改、构建、提交或维护，必须由用户明确提出。
- 项目的实现、提交和工作区清洁度只以 billing 根仓库为准。

## DO

- 阅读 `docs/dev.md` 了解开发前置知识
- 阅读 `TODOS.md` 了解计划

## 本地与远端发布约定

- 本地 CPA 在 WSL 中运行，项目运行目录统一使用 `cpa-plugin/.runtime`；Windows 客户端经 `127.0.0.1` 访问 WSL 时，localhost 转发层可能不会立即向 CPA 传递客户端断开，取消链路测试优先在 WSL 内直连执行。
- 从 PowerShell 跨 WSL 或 SSH 执行包含 Bash 变量、命令替换或多层引号的逻辑时，优先在 `.runtime/tmp/` 创建临时脚本后传入目标环境执行，不拼接复杂的单行 shell；临时脚本不提交。
- CLIProxyAPI 宿主补丁保存在 `patch/`，当前已验证基线为 `v7.2.139` / `0a14eb70`，必须按 `usage-context`、`usage-identity`、`request-lifecycle-cancel` 的顺序应用；升级 CPA 后按 `docs/operations.md` 核对补丁和已知上游测试例外。
- 构建本项目 patched CPA 时必须按上游 release workflow 使用 `-ldflags` 注入 `main.Version`、`main.Commit` 和 `main.BuildDate`。`Version` 固定使用“当前上游最新 tag + `-dev`”格式（例如 `v7.2.139-dev`），用于明确区分官方 Release 与本项目补丁构建；不得发布只显示 `dev`、`none` 或 `unknown` 的产物。上传前先在本地执行二进制并核对完整版本输出。
- CPA Linux 可执行文件解压后约 60 MiB，`gzip -9` 后约 20 MiB。上传远端时使用 gzip/tar.gz 或 `scp -C`，不要直接传输未压缩二进制；部署后的运行文件仍需解压为原始可执行文件。
- 实际服务器为 `root@akko.pchuan.top`，CPA 根目录为 `/root/cpa`。只维护本项目的 `billing` 和已要求启用的 `keeper`，不启用或部署其他参考插件。
- 远端替换 CPA 或 billing 前，先停止 `/root/cpa/cpa.sh` 管理的进程，并把旧二进制、插件和 `data/cpa-ext.db*` 备份到 `/root/cpa/backups/<timestamp>/`；新版本启动失败时恢复旧二进制和插件。
- 功能、协议、计费、取消链路与真实模型请求验收全部在本地 CPA 完成；至少核对：无 Key 被拒绝、有效 billing Key 请求成功、请求明细只有一条且包含 Request ID 和 Token、额度发生一次扣减、`active_requests` 回到 0。
- 本地验收通过后可直接发布远端。远端只允许执行压缩包校验、旧文件与数据库备份、二进制和插件替换、进程启动、健康检查及插件注册状态检查；禁止为验收向远端模型端点发送请求，包括任何 `/v1/responses`、`/v1/chat/completions` 或 compact 请求。
- 管理密钥和下游 Key 从远端 secret 文件或管理 API 在脚本内部读取，禁止在终端输出、提交或写入普通日志；验证结果只输出 Key 名称、状态、额度配置和布尔结论。