Keeper

English ｜ 简体中文

CPA Usage Keeper

万千流转，皆有迹可循。

最新版本 CI 状态 GHCR Docker 镜像 支持 Homebrew 支持 Linux 支持 macOS 支持 Windows MIT License

CPA Usage Keeper 是面向 [CLIProxyAPI（CPA）](https://github.com/router-for-me/CLIProxyAPI) 的独立用量持久化与分析面板。它将 CPA 用量保存到 SQLite，自动拉取 CPA 配置和凭证数据，并提供用量、成本、请求健康、限额及模型/API 统计。 ## 界面预览

CPA Usage Keeper 总览 CPA Usage Keeper 分析

CPA Usage Keeper Auth Files CPA Usage Keeper AI Provider

CPA Usage Keeper 排名 CPA Usage Keeper 登录页

## 功能特性 - 将 CPA 用量持久保存到 SQLite，并支持可选的定时备份 - 统计请求量、Token、成本、缓存、成功率、RPM/TPM 和延迟，并可按时间、模型、API Key、来源及结果筛选 - 查看和导出请求级事件，并自定义表格列 - 分析用量趋势、成本构成、模型/API Key/AI Provider 占比、时段热力图和延迟诊断 - 监控 Auth Files 与 AI Providers 的用量、健康状态和限额，支持健康巡检与限额刷新 - 可选择加入社区排名，按综合得分、Token、请求量、缓存率、平均 TTFT/延迟或峰值 TPM/RPM 对比表现 - 为单个 CPA API Key 提供独立的只读用量视图 - 自动同步 CPA Auth Files、API Keys 和 AI Providers，并维护模型价格用于成本估算 - 支持 Docker/Docker Compose、Homebrew、二进制和 systemd 部署，并可启用密码保护 - 通过 CPA 插件将 Keeper Dashboard 嵌入 CPAMC ## 赞助与特别感谢 - 感谢 [CLIProxyAPI（CPA）](https://github.com/router-for-me/CLIProxyAPI) 提供本项目所依赖的上游 CPA 基础与数据来源。 - 感谢 [@YouShouldBetOnMe](https://github.com/YouShouldBetOnMe) 对 CPA Usage Keeper 的支持。 - 感谢 CPA 讨论组（QQ群组）的讨论与反馈。 ## 快速开始 > 使用前请确认 CPA 配置已开启 usage 统计：`usage-statistics-enabled: true`。 Docker Compose 是推荐部署方式：首次部署可同时运行 CPA + Keeper，已有 CPA 时则使用 Keeper-only Compose。 | 场景 | 推荐方式 | 架构 | | --- | --- | --- | | 首次部署 CPA + Keeper | [Docker Compose：CPA + Keeper](#docker-compose推荐) | `linux/amd64`、`linux/arm64` | | 已有 CPA | [Docker Compose：仅 Keeper](#docker-compose推荐) | `linux/amd64`、`linux/arm64` | | 已有 CPA，偏好 Docker CLI | [Docker](#dockercpa-已在宿主机运行) | `linux/amd64`、`linux/arm64` | | macOS | [Homebrew](#macos-homebrew) | `amd64`、`arm64` | | Linux 不使用容器 | [Linux 二进制](#linux-二进制) | `amd64`、`arm64` | | Windows | [Windows Binary](#windows-binary) | `amd64`、`arm64` | 公网部署建议启用 `AUTH_ENABLED=true`，并配置 `LOGIN_PASSWORD` 保护数据。 ## 项目结构 ```text cmd/server/ 应用入口 internal/api/ HTTP 路由与处理器 internal/app/ 应用装配与启动 internal/auth/ Session 与访问控制 internal/poller/ CPA 用量与配置同步 internal/repository/ SQLite 持久化与聚合 internal/service/ 用量、定价与身份服务 internal/quota/ Provider 限额刷新与巡检 internal/ranking/ 社区排名聚合与同步 deploy/linux/ systemd 服务模板 web/ React + TypeScript 前端 ``` ## 本地开发 ### 前置依赖 - Go 1.26+ - Node.js 22+ - npm - 一个可用的 [CLIProxyAPI（CPA）](https://github.com/router-for-me/CLIProxyAPI) 实例 ### 本地运行 1. 将 `.env.example` 复制为 `.env`，至少设置 `CPA_BASE_URL` 和 `CPA_MANAGEMENT_KEY`。 ```bash cp .env.example .env vim .env ``` 2. 启动后端。 ```bash go run ./cmd/server/main.go ``` 3. 在另一个终端安装前端依赖并启动开发服务器。 ```bash npm --prefix ./web ci npm --prefix ./web run dev -- --host 127.0.0.1 ``` 打开 `http://127.0.0.1:5173`。前端默认将 `/api` 代理到 `http://127.0.0.1:8080`；后端使用其它端口时可通过 `VITE_API_PROXY_TARGET` 覆盖。 ### 测试 运行完整验证： ```bash make verify ``` 也可以分别运行： ```bash go test ./cmd/... ./internal/... npm --prefix ./web run test npm --prefix ./web run lint npm --prefix ./web run typecheck npm --prefix ./web run build ``` ## 部署方式 ### Docker Compose（推荐） Docker Compose 同时推荐用于 CPA + Keeper 联合部署和 Keeper 单独部署。 #### CPA + Keeper 将下面内容保存为 `docker-compose.yml`，并替换管理密钥和登录密码： ```yaml services: cli-proxy-api: image: eceasy/cli-proxy-api:latest container_name: cli-proxy-api restart: unless-stopped ports: - "8317:8317" - "1455:1455" volumes: - ./cpa/config.yaml:/CLIProxyAPI/config.yaml - ./cpa/auths:/root/.cli-proxy-api - ./cpa/logs:/CLIProxyAPI/logs networks: - cpa-network cpa-usage-keeper: image: ghcr.io/willxup/cpa-usage-keeper:latest container_name: cpa-usage-keeper restart: unless-stopped depends_on: - cli-proxy-api ports: - "8080:8080" environment: TZ: Asia/Shanghai # 设置容器时区，日志时间会按该时区显示。 CPA_BASE_URL: http://cli-proxy-api:8317 CPA_MANAGEMENT_KEY: replace-with-your-management-key REDIS_QUEUE_ADDR: cli-proxy-api:8317 AUTH_ENABLED: true LOGIN_PASSWORD: replace-with-your-login-password volumes: - ./keeper:/data networks: - cpa-network networks: cpa-network: driver: bridge ``` 运行 `docker compose up -d` 启动，使用 `docker compose down` 停止。 CPA 数据保存在 `./cpa`，Keeper 数据保存在 `./keeper`。 #### Keeper Only CPA 已经部署好时，直接使用仓库中的 Keeper-only Compose 模板： ```bash cp docker-compose.example.yml docker-compose.yml cp .env.example .env vim .env ``` CPA 运行在 Docker 宿主机上时，可从以下配置开始： ```env CPA_BASE_URL=http://host.docker.internal:8317 CPA_MANAGEMENT_KEY=replace-with-your-management-key AUTH_ENABLED=true LOGIN_PASSWORD=replace-with-your-login-password ``` 其它网络环境请将 `CPA_BASE_URL` 改为容器可访问的 CPA 地址。CPA 使用非默认 Redis/RESP 地址时，再设置 `REDIS_QUEUE_ADDR`。 运行 `docker compose up -d` 启动 Keeper，使用 `docker compose down` 停止。 模板默认将 Keeper 数据保存在 `./data`。 ### Docker（CPA 已在宿主机运行） 偏好使用 `docker run` 时，复用上面 Keeper-only Compose 的 `.env` 配置： ```bash docker run -d \ --name cpa-usage-keeper \ --add-host=host.docker.internal:host-gateway \ -p 8080:8080 \ -v "$(pwd)/keeper:/data" \ --env-file .env \ ghcr.io/willxup/cpa-usage-keeper:latest ``` ### macOS Homebrew Homebrew 是 macOS 推荐安装方式： ```bash brew tap Willxup/cpa-usage-keeper brew install cpa-usage-keeper ``` 至少设置 `CPA_BASE_URL` 和 `CPA_MANAGEMENT_KEY`，然后启动服务： ```bash vim "$(brew --prefix)/etc/cpa-usage-keeper.env" brew services start cpa-usage-keeper ``` 升级和服务管理命令： ```bash brew services list brew services restart cpa-usage-keeper brew update brew upgrade cpa-usage-keeper ``` 数据保存在 `$(brew --prefix)/var/cpa-usage-keeper`，日志写入 `$(brew --prefix)/var/log/`。 ### Linux 二进制 从 [Releases](https://github.com/Willxup/cpa-usage-keeper/releases/latest) 下载 `linux_amd64` 或 `linux_arm64` 压缩包，然后解压并运行： ```bash mkdir -p cpa-usage-keeper tar -xzf ./cpa-usage-keeper_*_linux_*.tar.gz -C cpa-usage-keeper --strip-components=1 cd cpa-usage-keeper cp .env.example .env vim .env ./cpa-usage-keeper ``` #### systemd Linux 压缩包内置 service 模板。请在解压后的目录中运行： ```bash sudo cp cpa-usage-keeper.service /etc/systemd/system/cpa-usage-keeper.service sudo sed -i "s|__CPA_USAGE_KEEPER_DIR__|$(pwd)|g" /etc/systemd/system/cpa-usage-keeper.service sudo systemctl daemon-reload sudo systemctl enable --now cpa-usage-keeper ``` ```bash sudo systemctl status cpa-usage-keeper sudo journalctl -u cpa-usage-keeper -f sudo systemctl restart cpa-usage-keeper ``` ### 命令行参数 二进制支持以下可选启动参数： ```bash cpa-usage-keeper --host 127.0.0.1 # 仅为当前进程覆盖 APP_HOST。 cpa-usage-keeper -v # 输出构建版本并退出；也支持 --version。 ``` ### Windows Binary 从 [Releases](https://github.com/Willxup/cpa-usage-keeper/releases/latest) 下载 `windows_amd64` 或 `windows_arm64` ZIP 并解压。在 PowerShell 中进入解压目录后运行： ```powershell Copy-Item .env.example .env notepad .env .\cpa-usage-keeper.exe ``` 启动前至少设置 `CPA_BASE_URL` 和 `CPA_MANAGEMENT_KEY`。公网部署还应设置 `AUTH_ENABLED=true` 和 `LOGIN_PASSWORD`。 ## 配置 复制配置模板： ```bash cp .env.example .env ``` 新手部署时优先看“最小必填”和“Web 访问与反代”两组，其它配置保持默认即可。 ### 最小必填 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `CPA_BASE_URL` | 是 | - | Keeper 服务端访问 CPA 的地址。Docker Compose 内通常是 `http://cli-proxy-api:8317`，可以是内网地址或容器服务名 | | `CPA_MANAGEMENT_KEY` | 是 | - | CPA management key，用于读取 CPA 管理接口数据 | ### Web 访问与反代 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `APP_HOST` | 否 | 所有接口 | Keeper HTTP 监听主机；原生部署仅允许本机访问时可设为 `127.0.0.1` | | `APP_PORT` | 否 | `8080` | Keeper HTTP 监听端口 | | `APP_BASE_PATH` | 否 | 根路径 | Keeper 子路径部署前缀，例如 `/keeper`；留空表示部署在 `/` | | `CPA_PUBLIC_URL` | 否 | 当前浏览器同源根路径 | 浏览器访问 CPA 的公开地址，用于“返回 CPA”跳转和 CPAMC frame 信任来源 | - 启动参数 `--host` 的优先级高于 `APP_HOST`。两者都未设置时，Keeper 保持现有行为，监听所有可用网络接口。 - Docker/Compose 请保持 `APP_HOST` 为空；如需仅允许 Docker 宿主机访问，请将端口发布为 `127.0.0.1:8080:8080`。 - `APP_BASE_PATH` 必须为空或以 `/` 开头；`/cpa/` 会规范为 `/cpa`。 - `CPA_BASE_URL` 是服务端访问 CPA 的地址，可以使用内网地址或 Docker 服务名。 - `CPA_PUBLIC_URL` 控制浏览器跳转和跨域 CPAMC frame 信任。同源且 CPA 位于 `/management.html` 时可留空；域名、端口或路径不同时应设置公开 CPA 地址。 跨域嵌入 CPAMC 时，`CPA_PUBLIC_URL` 必须是带 host 的完整 `http://` 或 `https://` URL；相对路径只影响浏览器跳转。 ### 登录保护 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `AUTH_ENABLED` | 否 | `false` | 是否启用登录保护 | | `LOGIN_PASSWORD` | 鉴权启用时必填 | - | 登录密码 | | `AUTH_SESSION_TTL` | 否 | `168h` | 登录 session 有效时长 | ### 时区与请求行为 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `TZ` | 否 | `Asia/Shanghai` | 统计和展示使用的时区；Today、按天统计、页面时间、日志时间和每日清理时间都会按这个时区计算 | | `REQUEST_TIMEOUT` | 否 | `30s` | 请求 CPA HTTP 接口和 Redis 队列的超时时间 | | `TLS_SKIP_VERIFY` | 否 | `false` | 跳过 CPA HTTPS 和 Redis 队列 TLS 的证书验证；仅在使用自签名证书时启用 | ### Auth Files 限额刷新 Auth Files 定时限额刷新在 Auth Files 巡检弹窗的小齿轮中配置。设置保存在本地 SQLite，不依赖页面保持打开。 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `QUOTA_REFRESH_WORKER_LIMIT` | 否 | `10` | 手动刷新和定时刷新共用的 Auth Files 限额刷新队列最大并发数，最大 `100` | ### Redis 队列高级配置 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `REDIS_QUEUE_ADDR` | 否 | `CPA_BASE_URL` 主机名 + `8317` | CPA Redis/RESP TCP 地址；一般保持空即可。非默认端口或单独暴露 Redis stream 时填写 `host:port` | | `REDIS_QUEUE_TLS` | 否 | `false` | 是否使用 TLS 连接 Redis 队列；显式设置 `REDIS_QUEUE_ADDR` 且需要 TLS 时设为 `true` | | `REDIS_QUEUE_BATCH_SIZE` | 否 | `10000` | 每次最多拉取的队列记录数 | | `REDIS_QUEUE_IDLE_INTERVAL` | 否 | `1s` | 队列为空时的检查间隔 | ### 存储、日志与备份 | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `WORK_DIR` | 否 | `./data` | 应用工作目录；数据库、日志和备份默认分别写入 `app.db`、`logs/`、`backups/` | | `LOG_LEVEL` | 否 | `info` | 日志级别 | | `LOG_FILE_ENABLED` | 否 | `true` | 是否写入持久化日志文件 | | `LOG_RETENTION_DAYS` | 否 | `7` | 综合日志保留历史天数，并额外保留当天；`0` 表示不自动清理。仅错误日志固定保留历史 30 天及当天 | | `BACKUP_ENABLED` | 否 | `true` | 是否启用 SQLite 数据库备份 | | `BACKUP_INTERVAL` | 否 | `24h` | 数据库备份间隔 | | `BACKUP_RETENTION_DAYS` | 否 | `7` | 备份保留天数 | Keeper 会在每天 04:30 的维护窗口中，把早于 90 个本地自然日的原始 `usage_events` 自动移动到永久保留的 `usage_events_archive` 冷表。该冷表用于未来 schema migration 重建增量数据，正常仪表盘 API 不查询 archive。 启用文件日志后，`cpa-usage-keeper-YYYY-MM-DD.log` 会记录所有已输出级别；error、fatal 和 panic 级别还会同时写入 `cpa-usage-keeper-error-YYYY-MM-DD.log`，该文件固定保留历史 30 个本地自然日及当天。 ### 内置 HTTPS | 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `TLS_ENABLED` | 否 | `false` | 是否让 Keeper 自己启用 HTTPS/TLS | | `TLS_CERT_FILE` | 启用 TLS 时必填 | - | HTTPS 证书文件路径 | | `TLS_KEY_FILE` | 启用 TLS 时必填 | - | HTTPS 私钥文件路径 | 通常建议在 nginx、Caddy 等反向代理层处理 HTTPS。只有需要 Keeper 进程直接提供 HTTPS 时，才设置 `TLS_ENABLED=true`，并填写 `TLS_CERT_FILE` 和 `TLS_KEY_FILE`；相对路径会按 `.env` 所在目录解析。 安全与数据说明： - 浏览器 API 会脱敏 key 类字段，但 SQLite 数据库及其未加密备份仍包含原始数据。 - 公网部署建议启用 `AUTH_ENABLED=true`，并在反向代理层启用 HTTPS。 - 登录 session hash 会保存在 SQLite 中，直到用户退出或超过 `AUTH_SESSION_TTL`。 - CPAMC 使用独立的 embed session：优先使用 `HttpOnly` Cookie，不可用时回退到保存在浏览器 session storage 中的单标签页请求头 token。 - 同源嵌入默认可用；跨域嵌入时，将 `CPA_PUBLIC_URL` 设置为用于 `frame-ancestors` 的公开 CPA/CPAMC 来源。 - Redis inbox 消息成功后保留到当天结束，失败后保留 7 天。 ## Nginx 反向代理 部署到 `/cpa` 时设置 `APP_BASE_PATH=/cpa`，并在反向代理中保留该前缀： ```nginx location /cpa/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } ``` CPA 与 Keeper 浏览器同源时，可以不设置 `CPA_PUBLIC_URL`，“返回 CPA”默认使用 `/management.html`。CPA 位于其它域名、端口或路径时，设置公开地址： ```env CPA_PUBLIC_URL=https://cpa.example.com ``` ## License 本项目基于 [MIT License](./LICENSE) 开源。