【免费下载链接】cpa-usage-keeper
Standalone CliProxyAPI usage tracker with SQLite persistence and built-in dashboard.
CPA Usage Keeper 是一个独立的 CLIProxyAPI（CPA）用量追踪工具，用 SQLite 持久化保存每一次模型请求的用量、成本、延迟和配额数据，并自带可视化 Dashboard。本文以 Docker Compose 为核心，带你用 3 个步骤完成 CPA + Keeper 联合部署：一次启动两个容器，即可拥有完整的用量监控面板。
CPA Usage Keeper 能做什么？
部署完成后，你会得到一个开箱即用的监控面板，核心能力包括：
- 保留历史：所有 CPA 用量记录持久化到 SQLite，并支持定时自动备份
- 看懂成本：按模型、API Key、服务商分析用量、缓存命中和估算成本
- 排查请求：查看请求明细与成功率、首 Token 时间（TTFT）、总延迟，支持导出
- 追踪配额：监控凭证健康度与剩余额度，刷新配额、编辑优先级、查看 Codex 配额历史
- 共享视图：为单个 CPA API Key 提供只读的用量查看入口
面板默认开启登录保护，首次访问需要输入你设置的LOGIN_PASSWORD。
部署前准备：确认 3 个前提
Docker 方式部署不需要安装 Go、Node.js 或编译源码，只要满足以下条件即可：
- 服务器已安装 Docker 和 Docker Compose（支持
linux/amd64、linux/arm64） - CPA 已开启用量统计：v8 配置中
observability.usage.usage-statistics-enabled设为true（旧版配置使用顶层usage-statistics-enabled） - 同一 CPA 接入多个用量采集服务时，全部使用订阅模式，否则可能导致收数中断
⚠️ 这是最容易踩的坑：如果 CPA 没有开启用量统计，Keeper 启动后页面会一片空白。
准备好以下 3 个关键值，配置阶段会反复用到：
| 值 | 说明 |
|---|---|
| CPA 管理密钥 | 写在 CPA 配置的management.secret-key，Keeper 靠它读取管理接口 |
| Keeper 登录密码 | 访问 Dashboard 的密码，务必设置为私有密码 |
| 客户端 API Key | CPA 的access.api-keys，供客户端调用模型使用（与管理密钥、登录密码完全独立） |
步骤 1：搭建部署目录并准备 Compose 模板
推荐先把项目克隆到服务器，方便直接取用官方部署模板：
git clone https://gitcode.com/gh_mirrors/cp/cpa-usage-keeper cd cpa-usage-keeper在部署目录中创建所需的子目录（CPA 与 Keeper 的数据将分开存放）：
mkdir -p cpa/auths cpa/logs keeper然后将联合部署模板 docker-compose.full.example.yml 复制为docker-compose.yml，并从 CPA 官方仓库取一份配置示例保存为cpa/config.yaml。最终目录结构如下：
./ ├── cpa/ │ ├── config.yaml # CPA 配置文件 │ ├── auths/ # CPA 凭证目录 │ └── logs/ ├── keeper/ # Keeper 数据目录 └── docker-compose.yml模板中的两个容器会通过独立的cpa-network桥接网络通信，depends_on保证 CPA 先于 Keeper 启动，无需额外网络配置。
步骤 2：配置 CPA 与 Keeper 的关键参数
这一步只需编辑两个文件。
① 编辑cpa/config.yaml（v8 配置结构，保留原有 YAML 层级与缩进）：
| 配置项 | 设置说明 |
|---|---|
management.allow-remote | 改为true，允许 Keeper 从另一个容器访问 CPA 管理功能 |
management.secret-key | 设置私有管理密钥，稍后在 Compose 文件中填写同一个值 |
observability.usage.usage-statistics-enabled | 改为true，开启用量统计 |
access.api-keys | 将示例密钥替换为你自己的客户端 API Key |
同时保留server.host为空、server.port为8317、oauth.auth-dir为"~/.cli-proxy-api"，这些值与模板中的容器网络和目录挂载一一对应。
② 编辑docker-compose.yml，在cpa-usage-keeper服务的environment中填写两项：
| 变量 | 填写内容 |
|---|---|
CPA_BASE_URL | 模板已设为http://cli-proxy-api:8317，无需改动 |
CPA_MANAGEMENT_KEY | 与 CPA 中相同的原始管理密钥 |
LOGIN_PASSWORD | 将空字符串""替换为你的 Keeper 登录密码 |
REDIS_QUEUE_ADDR | 模板已设为cli-proxy-api:8317，无需改动 |
如果更习惯用环境变量文件，也可以把配置写入./keeper/.env（模板通过可选的env_file读取）。参考完整变量说明可查阅 .env.example，其中每个变量都带有中文注释。
📌 登录保护默认启用：
LOGIN_PASSWORD为空时 Keeper 会拒绝启动，这正是它保护你的方式。
步骤 3：一条命令启动并验证访问
在部署目录执行：
docker compose up -d等待两个容器启动后，浏览器打开http://服务器地址:8080（本机部署用http://127.0.0.1:8080），用刚设置的 Keeper 密码登录即可。
首次部署后，请在 CPA 中添加模型凭证并实际调用一次模型——只有产生真实的模型请求，Keeper 才会开始落盘用量数据。数据就绪后，Overview 页面会显示如下概览：
常用维护命令：
# 查看 Keeper 运行日志 docker compose logs --tail=100 -f cpa-usage-keeper # 停止整个服务栈 docker compose down # 升级 Keeper 到最新版本（配置与数据目录不受影响） docker compose pull cpa-usage-keeper docker compose up -d cpa-usage-keeper部署完成后：面板各模块速览
登录后可以按页面逐一体验各个模块。
用量分析：按模型、时间维度拆解用量、缓存与估算成本，适合回答"这个月到底花了多少"：
凭证与配额：集中查看各凭证的健康状态与剩余额度，支持手动刷新、定时刷新和优先级调整：
配额历史：完整追踪 Codex 等服务商的配额变化曲线，方便复盘周期重置与异常消耗：
请求事件：逐条查看请求明细，包括成功率、TTFT 与总延迟，并可导出用于排查。
附加场景：已有 CPA，只想部署 Keeper
如果 CPA 已在运行，不需要完整模板，使用 Keeper-only 的 docker-compose.example.yml 即可。在新目录下载模板后，编辑.env填入连接信息：
CPA_BASE_URL=http://host.docker.internal:8317 CPA_MANAGEMENT_KEY=replace-with-your-management-key AUTH_ENABLED=true LOGIN_PASSWORD=你的私有密码两点注意：
- CPA 必须允许远程管理（v8 配置
management.allow-remote: true），且监听地址要能被 Keeper 容器访问——只绑定127.0.0.1时容器无法连接 - 其他网络布局下，把
CPA_BASE_URL改为容器可实际访问的 CPA 地址即可
常见问题与数据说明
启动后没有数据？按顺序排查这 3 项：
- CPA 用量统计开关是否为
true（对照上文前提 2） - Keeper 能否连通
CPA_BASE_URL，且CPA_MANAGEMENT_KEY与 CPA 管理密钥一致 - CPA 是否确实收到了新的模型请求；仍无数据时用
docker compose logs -f cpa-usage-keeper查看连接或鉴权报错
数据存在哪里？CPA 数据在./cpa，Keeper 数据（SQLite 数据库、日志、备份）在./keeper，迁移时带上这两个目录即可。数据库默认每 24 小时自动备份一次、保留 7 天，相关策略均可通过 .env.example 中的变量调整。
升级与日志：升级只需pull后重新up -d；错误日志单独落盘，默认保留最近 30 天，便于事后排障。
想深入了解各模块的内部实现，可以查看 internal/poller/（CPA 用量同步）、internal/quota/（配额刷新与巡检）、internal/repository/（SQLite 持久化与聚合），完整中文说明见 README.zh.md。
掌握以上 3 步，你就可以在十几分钟内为 CPA 配上一个带完整历史、成本分析和配额追踪的专属监控面板。
【免费下载链接】cpa-usage-keeper
Standalone CliProxyAPI usage tracker with SQLite persistence and built-in dashboard.
相关推荐
gpt-researcher Docker 快速部署指南：docker-compose 与 Docker CLI 完整实战
gpt researcher Docker 快速部署指南：docker compose 与 Docker CLI 完整实战 本文围绕 gpt researche
人工智能AI 应用深度研究AI Agent自主智能体RAG多智能体后端3步快速上手：Docker容器化部署Node.js应用完整指南
3步快速上手：Docker容器化部署Node.js应用完整指南 想要在开发环境中快速部署和测试Node.js应用吗？Docker容器化技术让这一切变得简单高效。
虚拟化操作系统固件5步快速部署：Windows Hyper-V运行macOS完整指南
5步快速部署：Windows Hyper V运行macOS完整指南 想要在Windows电脑上体验macOS系统吗？OSX Hyper V项目让这一切变得简单。
虚拟化操作系统固件
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
