CPA Usage Keeper：给 CLIProxyAPI 的用量留痕与成本账本
具有 SQLite 持久性和内置仪表板的独立 CliProxyAPI 使用情况跟踪器。
秒懂
- 它是什么？
- CPA Usage Keeper 是一个独立的 SQLite 持久化与仪表盘工具，专门记录 CLIProxyAPI 的用量、成本与健康状态。它的价值在于把 CPA 本身不保留的历史数据变成可查询、可导出的记录，但前提是 CPA 必须开启 usage-statistics-enabled。
- 适合谁用？
- CPA Usage Keeper 适合那些已经运行 CLIProxyAPI、并且需要长期保留用量历史、做成本归因或监控请求健康的团队。它的前提是 CPA 必须开启 usage-statistics-enabled: true，否则数据源为空，整个工具失去意义。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 Go（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
CPA 不留痕，Keeper 来补账
CLIProxyAPI（CPA）是一个代理网关，转发请求时会产生大量用量数据，但它本身不长期保存这些数据。CPA Usage Keeper 就是为这个缺口设计的：它把 CPA 的用量记录持久化到 SQLite，并提供仪表盘查看。目标用户很明确，运行 CPA 的人，尤其是多人共用、需要分摊成本或排查请求失败的团队。文档里强调了一个硬性前提：CPA 必须设置 usage-statistics-enabled: true，否则 Keeper 拿不到数据。这不是可选项，是数据源开关。另一个约束是，如果有多个用量收集器共用一个 CPA 实例，它们都必须用 subscription 模式，否则收集会停止或变得不完整。这个条件容易被忽略，但直接决定工具是否可用。
从 CPA 拉数据，在 SQLite 里算账
Keeper 的架构在 README 的项目结构里写得很清楚：internal/poller 负责同步 CPA 的用量和元数据，internal/repository 做 SQLite 持久化和聚合，internal/api 提供 HTTP 路由，internal/service 处理用量、定价和身份逻辑。数据流大概是：poller 定期从 CPA 拉取请求记录、Auth Files、API Keys 和 AI Providers，写入 SQLite，然后仪表盘通过 API 查询聚合结果。它不只是存请求日志，还维护模型定价，用于估算成本。这意味着即使 CPA 不报告成本，Keeper 也能根据 token 数和模型单价算出费用。这个设计让成本分析不依赖上游的计价能力，但也意味着定价表需要维护，如果模型价格变了，你得手动更新。
仪表盘看什么：用量、成本、健康与配额
仪表盘提供的视图覆盖了运维关心的几个面。请求层面，可以按时间范围、模型、API Key、来源和结果筛选，看请求数、token 数、成本、缓存命中、成功率、RPM/TPM 和延迟。分析层面，有趋势、成本构成、模型/API Key/AI Provider 混合、每小时热力图和延迟诊断。还有专门的 Auth Files 和 AI Providers 监控，带健康检查和配额刷新。文档里提到一个只读视图，可以按单个 CPA API Key 限定范围，这适合给不同用户看自己的用量，而不暴露全局数据。排名功能是社区性的，可以选择按总分、token、请求数、缓存率、平均 TTFT/延迟或峰值 TPM/RPM 参与，这更像是一个可选的社交功能，不是核心。
部署：Docker Compose 是主路，但别忘密码
README 推荐的部署方式是 Docker Compose，分两种场景：新部署 CPA 和 Keeper 一起用全栈，已有 CPA 则用 Keeper-only 栈。也支持 Docker CLI、Homebrew（macOS）、Linux 二进制、Windows 二进制和 systemd。架构覆盖 linux/amd64、linux/arm64，macOS 和 Windows 也有对应版本。本地开发需要 Go 1.26+ 和 Node.js 24+，先复制 .env.example 到 .env，设置 CPA_BASE_URL 和 CPA_MANAGEMENT_KEY，然后 go run ./cmd/server/main.go 启动后端，再用 npm --prefix ./web ci 和 npm run dev 启动前端。登录保护默认开启，必须配置 LOGIN_PASSWORD，或者只有在环境隔离可靠时才显式设 AUTH_ENABLED=false。这个安全默认值是合理的，因为仪表盘暴露的是敏感用量数据。
局限：依赖 CPA 的统计开关，且多收集器有坑
这个工具最大的局限是它完全依赖 CPA 的用量统计功能。如果 CPA 没开 usage-statistics-enabled，或者版本不支持，Keeper 就是一个空壳。文档还警告，多个收集器共用一个 CPA 实例时，必须都用 subscription 模式，否则收集会停止或不完整。这意味着在多人或分布式部署场景下，配置错误是静默的，你可能以为在记录，实际数据是断的。另一个限制是，Keeper 只记录 CPA 报告的数据，不拦截或修改请求，所以它无法捕捉 CPA 本身丢失的事件。如果你需要的是实时拦截或流式处理，这个工具不合适。
替代方案：CPA 自带接口 vs. 通用日志分析
如果你不想部署额外服务，CPA 自带的管理接口可能提供即时的用量视图，但问题是它不持久化历史，重启或时间窗口过后数据就没了。另一个替代是通用的日志收集工具，比如 Prometheus 加 Grafana，你可以让 CPA 输出日志，用 exporter 抓取指标。区别在于，Prometheus 是拉取型时序数据库，适合监控趋势和告警，但存储成本和查询灵活性不如 SQLite 适合做细粒度的请求级审计。Keeper 的优势是它专门为 CPA 的数据模型设计，直接理解 Auth Files、AI Providers 和模型定价，省去你写转换逻辑。通用方案则更灵活，但你需要自己定义指标和维度。
维护与许可：MIT 协议，升级节奏快
项目使用 MIT 许可证，可以自由使用和修改，没有 copyleft 约束。最近的发布记录显示 v1.14.9、v1.14.8、v1.14.7 在几天内连续发布，说明维护活跃，但也意味着升级频率可能较高。你需要关注 release notes 来确认是否有破坏性变更，尤其是数据库 schema 或配置项变化。README 提到可选定时备份，这意味着 SQLite 文件需要纳入备份策略，否则数据丢失风险由你自己承担。整体维护成本不算高，但如果你要长期使用，得跟上版本节奏。
编辑结论
CPA Usage Keeper 适合那些已经运行 CLIProxyAPI、并且需要长期保留用量历史、做成本归因或监控请求健康的团队。它的前提是 CPA 必须开启 usage-statistics-enabled: true，否则数据源为空，整个工具失去意义。如果你只需要临时看一眼当前用量，CPA 自带的管理接口可能就够用，不需要多部署一个服务。采用前先确认 CPA 版本支持 usage statistics，并且所有用量收集器都使用 subscription 模式，否则文档明确警告收集可能停止或不完整。部署时记得设置 LOGIN_PASSWORD，因为登录保护默认开启，空密码会带来暴露风险。这个工具解决的是 CPA 不留痕的问题，它本身不改变 CPA 的转发行为，只是一个旁路记录器。
社区笔记