zhou
CPA用量统计插件部署指南
zoe.X Lv3
  2026-07-09 10:30:00   2026-07-08 16:50:58    

CPA 用量统计插件

这是一个给 CLIProxyAPI/CPA v7 使用的用量统计插件，项目地址：

https://github.com/zduu/cpa-usage-plugin

插件的作用很直接：CPA 处理请求时，顺手把请求数量、成功失败、延迟、首 token 时间、输入输出 token、缓存 token、reasoning token 等数据记录下来，然后在管理面板里提供一个“用量统计”页面。

如果你用 CPA 转发多个模型或多个上游接口，这类统计会很实用：可以看到哪个模型调用最多、哪个上游失败率偏高、最近 7 天服务是否稳定、当前 token 大概花了多少钱，也能按条件导出请求事件做后续分析。

项目特点

  • 请求统计：记录总请求数、成功/失败、平均延迟、TTFT 和 RPM。
  • Token 统计：区分 input、output、reasoning、cache 和 total token。
  • 多维聚合：按上游接口、模型、来源、CPA 凭证、调用 CPA 的客户端 API key 汇总。
  • 健康网格：用 15 分钟粒度展示最近 7 天服务状态。
  • 趋势图：支持查看每日成本、请求量、token 和平均 RPM。
  • 模型价格表：支持手动配置模型价格，也可以启用 models.dev 默认价格源。
  • 事件明细：按时间范围、模型、来源、凭证和客户端 API key 查询。
  • 导入导出：支持 JSON、CSV、JSONL 和 gzip，大导出可走后台任务。
  • 持久化：可选开启 JSONL 存储，重启 CPA 后恢复保留窗口内的数据。
  • 健康检查：/health 返回持久化队列、缓存命中率、导出压力和告警信息。

当前项目版本为 2.2.7，已经支持 CPA 插件商店所需的 zip 资产和 checksums.txt。

安装方式

方式一：插件商店安装

CPA v7 支持插件商店，这是目前最省心的方式。先在 config.yaml 中添加插件商店源：

1
2
3
4
5
6
7
8
9
10
11
12
plugins:
  enabled: true
  dir: plugins
  store-sources:
    - "https://raw.githubusercontent.com/zduu/cpa-usage-plugin/main/registry.json"
  configs:
    usage-statistics:
      enabled: true
      store:
        version: "2.2.7"
        release-tag: "v2.2.7"
        repository: "https://github.com/zduu/cpa-usage-plugin"

重启 CPA 后，进入管理面板的插件商店，就能看到“用量统计”，点击安装即可。以后有新版本时，也可以直接在管理面板里点更新。

方式二：手动下载插件

如果不使用插件商店，可以从 GitHub Releases 下载对应平台的插件文件：

  • Linux x86_64 / amd64：usage-statistics-linux-amd64.so
  • Linux arm64 / aarch64：usage-statistics-linux-arm64.so
  • macOS Intel：usage-statistics-darwin-amd64.dylib
  • macOS Apple Silicon：usage-statistics-darwin-arm64.dylib
  • Windows x86_64 / amd64：usage-statistics-windows-amd64.dll

Docker 部署时，一般把 Linux 版本放到宿主机挂载的 plugins 目录：

1
2
3
4
5
6
mkdir -p ~/docker/CLIProxyAPI/plugins
cp usage-statistics-linux-amd64.so ~/docker/CLIProxyAPI/plugins/usage-statistics.so
chmod 755 ~/docker/CLIProxyAPI/plugins/usage-statistics.so

cd ~/docker/CLIProxyAPI
docker compose restart cli-proxy-api

macOS 直跑 CPA 时，文件扩展名应使用 .dylib：

1
2
3
4
5
6
mkdir -p CLIProxyAPI/plugins
cp usage-statistics-darwin-arm64.dylib CLIProxyAPI/plugins/usage-statistics.dylib
chmod 755 CLIProxyAPI/plugins/usage-statistics.dylib

cd CLIProxyAPI
./cli-proxy-api

必要配置

除了插件自身开关，CPA 的远程管理配置也要打开。否则管理页面和 /v0/management/* 接口无法访问。

下面是一份比较完整的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
host: ""
port: 8317

remote-management:
  allow-remote: true
  secret-key: "请替换成你自己的管理密钥"
  disable-control-panel: false

plugins:
  enabled: true
  dir: plugins
  store-sources:
    - "https://raw.githubusercontent.com/zduu/cpa-usage-plugin/main/registry.json"
  configs:
    usage-statistics:
      enabled: true
      store:
        version: "2.2.7"
        release-tag: "v2.2.7"
        repository: "https://github.com/zduu/cpa-usage-plugin"

      max_details_per_model: 5000
      retention_days: 30
      dedup_window_minutes: 1440

      storage_enabled: true
      storage_path: data/usage-statistics.jsonl
      storage_flush_interval_seconds: 5
      storage_snapshot_interval_seconds: 300
      storage_snapshot_record_interval: 1000

      export_max_records: 100000

      price_storage_path: usage-statistics-prices.json
      models_dev_prices_enabled: false
      models_dev_prices_url: https://models.dev/api.json
      models_dev_prices_refresh_interval_seconds: 43200

这里有几个容易漏掉的点：

  • remote-management.secret-key 必须设置，否则管理 API 会被 CPA 禁用。
  • plugins.enabled: true 是全局插件开关。
  • plugins.configs.usage-statistics.enabled: true 是本插件开关。
  • 如果通过公网、局域网或反向代理访问管理面板，通常需要 allow-remote: true。
  • 如果希望重启后保留统计数据，建议开启 storage_enabled，并把 storage_path 放到已经挂载的数据目录。

查看统计页面

确认 CPA 已经处理过真实请求后，打开管理面板：

1
http://127.0.0.1:8317/management.html

登录后，在左侧菜单里打开“用量统计”。页面里主要有这些信息：

  • 顶部统计卡片：总请求、成功率、失败数、token、RPM、估算花费。
  • 服务健康网格：最近 7 天，每 15 分钟一个格子，适合快速查看异常时间段。
  • 上游接口统计：对比不同 provider 或上游 API 的请求量、失败率和延迟。
  • 模型统计：查看模型请求量、token 消耗、缓存命中率和估算成本。
  • 来源与客户端 API 统计：区分不同调用方或不同 CPA key 的消耗。
  • 请求事件明细：按模型、来源、凭证、时间范围筛选。
  • 导入导出：把统计数据备份出来，或迁移到另一个实例。

看板首屏使用 /dashboard-summary，不会把所有明细一次性传到浏览器；事件明细则通过 /dashboard-events 分页加载。所以即使记录量比较大，首页也不会因为明细过多而明显变慢。

常用管理接口

管理接口都需要带上 x-management-key 请求头，值就是 remote-management.secret-key。

获取轻量摘要

1
2
curl http://127.0.0.1:8317/v0/management/plugins/usage-statistics/dashboard-summary \
  -H 'x-management-key: <你的管理密钥>'

查询事件明细

1
2
curl "http://127.0.0.1:8317/v0/management/plugins/usage-statistics/dashboard-events?limit=20&offset=0&range=24h&model=gpt-4" \
  -H 'x-management-key: <你的管理密钥>'

导出最近 24 小时事件

1
2
3
curl "http://127.0.0.1:8317/v0/management/plugins/usage-statistics/dashboard-events-export?range=24h&format=csv" \
  -H 'x-management-key: <你的管理密钥>' \
  -o usage-events.csv

后台导出大文件

1
2
curl -X POST "http://127.0.0.1:8317/v0/management/plugins/usage-statistics/dashboard-events-export-jobs?range=7d&format=jsonl&gzip=1&limit=50000" \
  -H 'x-management-key: <你的管理密钥>'

任务创建后会返回 id，再用下面的接口查询和下载：

1
2
3
4
5
6
curl "http://127.0.0.1:8317/v0/management/plugins/usage-statistics/dashboard-events-export-jobs?id=<job_id>" \
  -H 'x-management-key: <你的管理密钥>'

curl "http://127.0.0.1:8317/v0/management/plugins/usage-statistics/dashboard-events-export-download?id=<job_id>" \
  -H 'x-management-key: <你的管理密钥>' \
  -o usage-events.jsonl.gz

健康检查

1
2
curl http://127.0.0.1:8317/v0/management/plugins/usage-statistics/health \
  -H 'x-management-key: <你的管理密钥>'

/health 里会返回 status 和 alerts，也会展示持久化 writer 队列、写入耗时、summary/events 查询耗时、ETag 条件请求命中率、导出是否被截断等信息。如果想把插件状态接入外部监控，这个接口比较合适。

数据持久化建议

插件默认只把统计放在内存里，CPA 重启后数据会清空。生产环境建议开启 JSONL 持久化：

1
2
3
4
5
6
7
8
9
plugins:
  configs:
    usage-statistics:
      enabled: true
      storage_enabled: true
      storage_path: data/usage-statistics.jsonl
      storage_flush_interval_seconds: 5
      storage_snapshot_interval_seconds: 300
      storage_snapshot_record_interval: 1000

开启后，新请求会进入后台写入队列，按日期分片写入 data/usage-statistics/usage-YYYY-MM-DD.jsonl。插件启动时会加载 snapshot，再 replay 保留窗口内的增量分片。

如果已经跑了一段时间但之前没开启持久化，可以先从页面导出统计数据；开启持久化并重启 CPA 后，再把导出的 JSON 导入一次。

更新插件

插件商店安装的情况下，直接在 CPA 管理面板里更新即可。

手动部署时，可以使用项目里的脚本：

1
2
3
4
5
6
curl -fsSL https://raw.githubusercontent.com/zduu/cpa-usage-plugin/main/scripts/update-latest-release.sh \
  -o CLIProxyAPI/update-latest-release.sh
chmod +x CLIProxyAPI/update-latest-release.sh

cd CLIProxyAPI
bash update-latest-release.sh --restart

注意：插件文件被 CPA 进程加载后，单纯覆盖文件不会立即生效，需要重启 CPA 才会加载新版本。

常见问题

Q: 管理页面看不到“用量统计”？

A: 先检查 plugins.enabled 和 plugins.configs.usage-statistics.enabled 是否都为 true，再看 CPA 日志里有没有 plugin loaded 和 plugin registered。

Q: 页面打开了，但是没有数据？

A: 插件只会统计 CPA 实际处理过的请求。先确认已经通过 CPA 调用过模型接口，再刷新看板。

Q: 远程访问管理页面失败？

A: 检查 remote-management.allow-remote 是否为 true，secret-key 是否已设置，反向代理是否正确转发到 CPA 端口。

Q: 重启后统计清零？

A: 默认内存模式就是这个行为。需要保留数据时开启 storage_enabled，并把 storage_path 放到持久化目录。

Q: 成本估算不准？

A: 需要在模型价格表里配置对应模型的 input/output/cache 单价，或者启用 models.dev 默认价格源。手动配置的价格优先级更高。

总结

这个插件适合长期运行 CPA 的场景。它不只是看总请求数，还能把上游接口、模型、来源、客户端 API key、成本和健康状态串起来看。对多模型、多上游、多人共用的 CPA 实例来说，开启用量统计和持久化基本属于刚需配置。

 评论
评论插件加载失败
正在加载评论插件
  1. CPA 用量统计插件
    1. 项目特点
    2. 安装方式
      1. 方式一：插件商店安装
      2. 方式二：手动下载插件
    3. 必要配置
    4. 查看统计页面
    5. 常用管理接口
      1. 获取轻量摘要
      2. 查询事件明细
      3. 导出最近 24 小时事件
      4. 后台导出大文件
      5. 健康检查
    6. 数据持久化建议
    7. 更新插件
    8. 常见问题
    9. 总结
© 2025 - 2026    zoe.X
由 Hexo 驱动 & 主题 Keep
访客数 访问量
  1. CPA 用量统计插件
    1. 项目特点
    2. 安装方式
      1. 方式一：插件商店安装
      2. 方式二：手动下载插件
    3. 必要配置
    4. 查看统计页面
    5. 常用管理接口
      1. 获取轻量摘要
      2. 查询事件明细
      3. 导出最近 24 小时事件
      4. 后台导出大文件
      5. 健康检查
    6. 数据持久化建议
    7. 更新插件
    8. 常见问题
    9. 总结