Manager Server 指南

Manager Server 是完整 CPAMP 体验的后端。它托管 management.html，保存本地 SQLite，用采集器消费 CPA 用量队列，并用 CPAMP 管理员密钥保护管理能力。

当你打开下面入口时，使用的是 Manager Server 模式：

http://<host>:18317/management.html

当 CPA 自己托管下面入口时，属于 CPA Panel 模式：

http://<cpa-host>:8317/management.html

CPA Panel 模式不会读取 Manager Server SQLite，也没有完整的历史请求监控、模型价格、API 密钥别名、导入导出和服务端巡检历史。

Manager Server 负责什么

• 托管内置管理面板。
• 执行首次 setup 并保存绑定的 CPA 连接。
• 使用 cmp_admin_... 管理员密钥做登录认证。
• 使用 data.key 加密保存 CPA Management Key。
• setup 后代理 CPA Management API。
• 消费 CPA 用量事件。
• 将用量事件持久化到 SQLite。
• 提供仪表盘、请求监控、用量分析、模型价格、API 密钥别名、用量导入导出和服务端 Codex 账号巡检 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
      -> 采集器 -> CPA 用量队列
      -> /data/usage.sqlite

CPA 仍然需要单独运行，CPAMP 不包含 CPA 本体。

首次 setup 与登录

首次启动时，CPAMP 需要管理员密钥。可以显式提供：

CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key'

如果不提供，Manager Server 会生成：

cmp_admin_...

并只在启动日志中输出一次。

首次 setup 需要填写：

管理员密钥
CPA URL
CPA Management Key
请求监控
采集模式
轮询间隔

setup 后：

• 浏览器登录使用 CPAMP 管理员密钥。
• CPA Management Key 会在服务端加密保存。
• Manager Server 使用保存的 CPA Management Key 访问 CPA。
• 新浏览器不再需要 CPA Management Key。

CPA 前置条件

请求监控依赖 CPA 用量发布和 CPA 用量队列。

最低要求：

CPA v6.10.8+ 支持 HTTP 用量队列

推荐：

CPA v7.1.39+

CPA Management API 必须启用：

remote-management:
  secret-key: "your CPA Management Key"
  allow-remote: true

用量发布可以由 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 用量队列 -> RESP pop fallback

模式	适用场景
auto	推荐默认值。
subscribe	强制 RESP Pub/Sub，适合能直连 CPA API 端口的低延迟采集。
http	强制 HTTP 用量队列，适合普通 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 用量数据。
• 模型价格。
• API 密钥别名。
• 服务端巡检历史。

仍由 CPA 管理：

• usage-statistics-enabled
• redis-usage-queue-retention-seconds
• remote-management
• proxy / routing 配置
• logging 配置
• 认证文件
• 提供商配置
• CPA config.yaml

保存 CPAMP 配置不会重写完整 CPA config.yaml。

常用环境变量

变量	默认值	说明
CPA_MANAGER_CONFIG	空	可选配置文件路径；原生包默认使用二进制旁边的 config.json。
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	空	可选管理员密钥。
CPA_MANAGER_ADMIN_KEY_FILE	/run/secrets/cpa_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_RESP_QUEUE	usage	RESP key 参数，通常保持默认。
USAGE_RESP_POP_SIDE	right	right 使用 RPOP；left 使用 LPOP。
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 校验。
USAGE_QUOTA_COOLDOWN_ENABLED	false	启用 Codex usage-limit cooldown worker。
USAGE_ACCOUNT_ACTIONS_ENABLED	false	启用账号处理队列，用于记录需要人工处理的认证问题。
USAGE_ACCOUNT_ACTIONS_AUTO_DISABLE	false	启用认证问题自动禁用；只有账号处理队列启用时才会生效。
PANEL_PATH	空	使用自定义 management.html。

启动优先级：

environment variables > config.json > defaults

如果 USAGE_QUOTA_COOLDOWN_ENABLED、USAGE_ACCOUNT_ACTIONS_ENABLED 或 USAGE_ACCOUNT_ACTIONS_AUTO_DISABLE 由环境变量设置，面板中的对应开关会显示为环境变量来源并被锁定。要改成面板可编辑，需要移除环境变量并重启 Manager Server。

运行时接口

Endpoint	用途
GET /health	健康检查。
GET /status	采集器、SQLite、事件计数和错误。
GET /usage-service/info	Manager Server 模式探测。
GET /usage-service/config	读取 CPAMP Manager Server 配置。
PUT /usage-service/config	保存 CPAMP 配置，必要时重启采集器。
GET /usage-service/account-processing-policy	读取配额冷却、账号处理队列和自动禁用策略。
PATCH /usage-service/account-processing-policy	更新账号处理策略；被环境变量锁定的字段不能通过接口修改。
GET /usage-service/quota-cooldowns	读取当前活跃的配额冷却，用于认证文件页面展示恢复提示。
POST /setup	首次 setup。
GET /v0/management/usage	兼容 usage data。
GET /v0/management/usage/export	导出 JSONL usage events。
POST /v0/management/usage/import	导入 JSONL 或兼容旧快照。
GET /v0/management/model-prices	模型价格。
PUT /v0/management/model-prices	替换保存的模型价格。
POST /v0/management/model-prices/sync	价格同步。
GET /v0/management/api-key-aliases	API 密钥别名。
GET /v0/management/account-action-candidates	认证问题处理队列。
POST /v0/management/account-action-candidates/{id}/ignore	忽略账号处理候选项。
POST /v0/management/account-action-candidates/{id}/resolve	标记账号处理候选项已处理。
POST /v0/management/account-action-candidates/{id}/enable	重新启用候选项关联的认证文件。
DELETE /v0/management/account-action-candidates/{id}/auth-file	删除候选项关联的认证文件。
GET /v0/management/dashboard/*	仪表盘数据。
GET /v0/management/monitoring/*	请求监控数据。
GET /v0/management/codex-inspection/*	服务端 Codex 巡检。
GET /models, GET /v1/models	setup 后代理 model-list 请求到 CPA。
/v0/management/*	CPAMP 未处理的路径代理到 CPA。

setup 后，Manager Server 管理接口需要：

Authorization: Bearer <CPAMP_ADMIN_KEY>

数据和安全

必须备份：

usage.sqlite
usage.sqlite-wal
usage.sqlite-shm
data.key

安全边界：

• 管理员密钥不会明文保存；SQLite 中只保存 salt 和 HMAC 摘要。
• CPA Management Key 保存前会加密。
• 只有 usage.sqlite 泄露时，保存的 CPA Management Key 不能直接读取。
• usage.sqlite 和 data.key 同时泄露时，CPA Management Key 可以被解密。
• data.key 丢失后，保存的 CPA Management Key 无法恢复。
• 请求元数据可能包含模型名、端点、账号标签、项目快照、Token 用量、延迟和失败摘要。
• 原始失败 body 只保存在本地 SQLite；普通 API 和 JSONL 导出只暴露脱敏摘要。

导入和导出

Manager Server 可以导出 JSONL / NDJSON usage events。

可以导入：

• Manager Server 导出的 JSONL / NDJSON。
• 带 request-level details 的旧 usage snapshot。

只有聚合数据的旧文件不能重建请求级 monitoring。对准确性有要求时，先在备份或 staging 数据库上测试导入。