-
Notifications
You must be signed in to change notification settings - Fork 77
Manager Server 使用指南
seakee edited this page Jun 5, 2026
·
1 revision
CPA Manager Plus Manager Server 是完整 CPAMP 体验所需的长驻后端,取代旧 CPA-Manager 的 Usage Service 模型。
当你打开下面入口时,会使用 Manager Server:
http://<host>:18317/management.html
当 CPA 自己托管下面入口时,不会使用 Manager Server:
http://<cpa-host>:8317/management.html
CPA panel mode 在 Plus 中是纯 CPA 面板,不会调用单独的 Manager Server。
Manager Server 会:
- 托管内置管理面板
- 执行首次 setup 并保存绑定的 CPA 连接
- 使用 CPAMP Admin Key 做登录认证
- 使用
data.key加密保存 CPA Management Key - setup 后代理 CPA Management API
- 消费 CPA usage events
- 将 usage events 持久化到 SQLite
- 提供 dashboard、monitoring、model pricing、API key alias、usage import/export、server inspection API
Browser
-> Manager Server :18317
-> /management.html
-> /usage-service/info
-> /usage-service/config
-> /v0/management/usage 从 SQLite 读取
-> /v0/management/model-prices 从 SQLite 读取
-> /v0/management/api-key-aliases 从 SQLite 读取
-> /v0/management/dashboard/* 从 SQLite 读取
-> /v0/management/monitoring/* 从 SQLite 读取
-> /v0/management/codex-inspection/* 从 SQLite/后台任务读取
-> 其他 /v0/management/* 代理到 CPA
-> collector -> CPA usage queue
-> /data/usage.sqlite
CPA 仍然需要单独运行,CPAMP 不包含 CPA 本体。
首次启动时,CPAMP 需要 Admin Key。
可以显式提供:
CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key'如果不提供,Manager Server 会生成:
cmp_admin_...
并只在首次启动日志输出一次。
首次 setup 需要填写:
Admin Key
CPA URL
CPA Management Key
Request Monitoring
Collection Mode
Poll Interval
setup 后:
- 浏览器登录使用 CPAMP Admin Key
- CPA Management Key 会在服务端加密保存
- Manager Server 使用保存的 CPA Management Key 访问 CPA
- 新浏览器不再需要 CPA Management Key
请求监控依赖 CPA usage publishing 和 CPA usage queue。
最低要求:
CPA v6.10.8+ 支持 HTTP usage queue
推荐:
CPA v7.1.39+
CPA Management API 必须启用:
remote-management: secret-key: "你的 CPA Management Key" allow-remote: true
usage publishing 可以由 CPAMP 在 setup / config save 时启用,也可以直接在 CPA 中设置:
usage-statistics-enabled: true
队列保留时间由 CPA 控制:
redis-usage-queue-retention-seconds: 60
默认 60 秒,最大 3600 秒。Manager Server 需要持续运行。
默认:
auto
行为:
auto -> RESP Pub/Sub -> HTTP usage queue -> RESP pop fallback
模式说明:
| 模式 | 适用场景 |
|---|---|
auto |
推荐默认值 |
subscribe |
强制 RESP Pub/Sub,适合能直连 CPA API 端口的低延迟采集 |
http |
强制 HTTP usage queue,适合普通 HTTP 反代 |
resp |
强制旧 RESP pop,必须直连 CPA API 端口 |
RESP 传输不能穿过普通 HTTP 反代。如果看到 unsupported RESP prefix 'H',通常是 RESP 客户端连到了 HTTP 地址。
Manager Server 管理:
- 绑定的 CPA URL
- 加密后的 CPA Management Key
- 请求监控开关
- 采集模式
- 轮询间隔
- Batch size
- Query limit
- SQLite usage data
- 模型价格
- API Key 别名
- 服务端巡检历史
仍由 CPA 管理:
usage-statistics-enabledredis-usage-queue-retention-secondsremote-management- proxy / routing 配置
- logging 配置
- auth files
- provider 配置
- CPA
config.yaml
保存 CPAMP 配置不会重写完整 CPA config.yaml。
| 变量 | 默认值 | 说明 |
|---|---|---|
HTTP_ADDR |
0.0.0.0:18317 |
Manager Server 监听地址 |
USAGE_DATA_DIR |
Docker: /data; native: ./data
|
数据目录 |
USAGE_DB_PATH |
Docker: /data/usage.sqlite; native: ./data/usage.sqlite
|
SQLite 路径 |
CPA_MANAGER_ADMIN_KEY |
空 | 可选 Admin Key |
CPA_MANAGER_ADMIN_KEY_FILE |
/run/secrets/cpa_admin_key |
可选 Admin Key 文件 |
CPA_MANAGER_DATA_KEY |
空 | 可选数据加密 key |
CPA_MANAGER_DATA_KEY_FILE |
/run/secrets/cpa_data_key |
可选数据加密 key 文件 |
CPA_MANAGER_DATA_KEY_PATH |
Docker: /data/data.key; native: ./data/data.key
|
自动生成的数据 key 路径 |
CPA_UPSTREAM_URL |
空 | 可选环境变量管理的 CPA URL |
CPA_MANAGEMENT_KEY |
空 | 可选环境变量管理的 CPA Management Key |
CPA_MANAGEMENT_KEY_FILE |
/run/secrets/cpa_management_key |
可选 CPA Management Key 文件 |
USAGE_COLLECTOR_MODE |
auto |
auto、subscribe、http、resp
|
USAGE_BATCH_SIZE |
100 |
单批最大记录数 |
USAGE_POLL_INTERVAL_MS |
500 |
空闲轮询间隔 |
USAGE_QUERY_LIMIT |
50000 |
最近 usage events 返回上限 |
USAGE_CORS_ORIGINS |
* |
兼容接口 CORS origin |
USAGE_RESP_TLS_SKIP_VERIFY |
false |
RESP 跳过 TLS 校验 |
PANEL_PATH |
空 | 使用自定义 management.html
|
启动优先级:
环境变量 > config.json > 默认值
| 接口 | 用途 |
|---|---|
GET /health |
健康检查 |
GET /status |
collector、SQLite、事件数和错误 |
GET /usage-service/info |
Manager Server 模式探测 |
GET /usage-service/config |
读取 CPAMP 配置 |
PUT /usage-service/config |
保存 CPAMP 配置并按需重启 collector |
POST /setup |
首次 setup |
GET /v0/management/usage |
兼容 usage 数据 |
GET /v0/management/usage/export |
导出 JSONL usage events |
POST /v0/management/usage/import |
导入 JSONL 或兼容旧快照 |
GET /v0/management/model-prices |
模型价格 |
POST /v0/management/model-prices/sync |
价格同步 |
GET /v0/management/api-key-aliases |
API Key 别名 |
GET /v0/management/dashboard/* |
Dashboard 数据 |
GET /v0/management/monitoring/* |
Monitoring 数据 |
GET /v0/management/codex-inspection/* |
服务端 Codex 巡检 |
/v0/management/* |
未由 CPAMP 处理的路径代理到 CPA |
setup 后,Manager Server 管理接口需要:
Authorization: Bearer <CPAMP_ADMIN_KEY>
需要备份:
usage.sqlite
usage.sqlite-wal
usage.sqlite-shm
data.key
安全说明:
- Admin Key 不明文保存,只保存 salted HMAC credential。
- CPA Management Key 加密后保存到 SQLite。
- 只泄露
usage.sqlite时,保存的 CPA Management Key 不能被直接读取。 - 同时泄露
usage.sqlite和data.key时,保存的 CPA Management Key 可以被解密。 - 如果
data.key丢失,保存的 CPA Management Key 无法恢复。 - 请求元数据可能包含模型名、endpoint、账号标签、project snapshot、token usage、latency 和失败摘要。
Manager Server 导出 JSONL / NDJSON usage events。
可导入:
- Manager Server 导出的 JSONL / NDJSON
- 有 request-level details 的旧 usage snapshot
只有聚合总量的旧文件不能重建请求级监控。重要迁移前建议先在备份或测试库验证。