Docker 部署 CPA Manager Plus

Docker 部署 CPA Manager Plus

本文介绍如何用 Docker 部署 CPA Manager Plus。镜像包含 CPAMP Manager Server 和内置 management.html 面板，但不包含 CPA / CLI Proxy API 本体。

新部署建议使用 Manager Server 托管面板：

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

不要照搬旧 CPA-Manager 的「CPA 面板 + External Usage Service URL」模式。Plus 中的 CPA panel mode 是纯 CPA 面板，不使用 Manager Server 的监控和 SQLite 统计能力。

---

前置要求

你需要：

• 已运行的 CPA / CLI Proxy API
• 已启用 CPA Management API
• CPA Management Key
• 挂载持久化 /data
• 同一个 CPA usage queue 只由一个 CPAMP Manager Server 消费

推荐 CPA 版本：

v7.1.39+

HTTP usage queue 最低版本：

v6.10.8+

CPA 需要允许 Manager Server 访问 Management API：

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

---

快速启动

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

打开：

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

首次 setup 填写：

Admin Key:          启动日志中的 cmp_admin_...
CPA URL:            http://host.docker.internal:8317、http://cli-proxy-api:8317 或你的 CPA 地址
CPA Management Key: CPA remote-management.secret-key

如果没有设置 CPA_MANAGER_ADMIN_KEY，CPAMP 会生成管理员密钥并只在首次启动日志输出一次：

docker logs cpa-manager-plus

setup 完成后，新浏览器登录只需要 CPAMP Admin Key。CPA Management Key 会在服务端加密保存。

---

Docker Compose

services:
  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    container_name: cpa-manager-plus
    restart: unless-stopped
    ports:
      - "18317:18317"
    environment:
      HTTP_ADDR: "0.0.0.0:18317"
      USAGE_DB_PATH: "/data/usage.sqlite"
      CPA_MANAGER_DATA_KEY_PATH: "/data/data.key"
      # 托管部署建议显式设置：
      # CPA_MANAGER_ADMIN_KEY: "replace-with-a-long-random-admin-key"
      USAGE_COLLECTOR_MODE: "auto"
      USAGE_BATCH_SIZE: "100"
      USAGE_POLL_INTERVAL_MS: "500"
      USAGE_QUERY_LIMIT: "50000"
    volumes:
      - cpa-manager-plus-data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:18317/health"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  cpa-manager-plus-data:

启动：

docker compose up -d

也可以使用 GHCR 镜像：

ghcr.io/seakee/cpa-manager-plus:latest

---

CPA URL 怎么填

场景	CPAMP setup 中填写的 CPA URL
CPA 和 CPAMP 在同一个 Compose network	http://cli-proxy-api:8317
CPA 跑在 Docker Desktop 宿主机	http://host.docker.internal:8317
CPA 跑在 Linux 宿主机，CPAMP 跑在 Docker	http://host.docker.internal:8317，并加 --add-host=host.docker.internal:host-gateway
CPA 是远程服务且支持 HTTP queue	https://your-cpa.example.com

Linux 宿主机 CPA 示例：

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  --add-host=host.docker.internal:host-gateway \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

然后填写：

http://host.docker.internal:8317

不要在容器里用 127.0.0.1 访问宿主机 CPA。

---

数据持久化和备份

必须挂载 /data。

Docker 默认数据：

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

备份必须包含 SQLite 文件和 data.key：

docker run --rm \
  -v cpa-manager-plus-data:/data \
  -v "$PWD":/backup \
  alpine \
  tar czf /backup/cpa-manager-plus-data-backup.tar.gz -C /data .

data.key 很重要：

• usage.sqlite 保存用量数据和加密后的 CPAMP 配置
• data.key 用来解密已保存的 CPA Management Key
• 如果 data.key 丢失，已保存的 CPA Management Key 无法恢复，只能重新保存 CPA 连接

---

升级

升级前先备份 /data。

docker pull seakee/cpa-manager-plus:latest
docker stop cpa-manager-plus
docker rm cpa-manager-plus
docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

Compose：

docker compose pull
docker compose up -d

---

验证

curl http://127.0.0.1:18317/health
curl http://127.0.0.1:18317/usage-service/info

setup 后：

curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
  http://127.0.0.1:18317/status

重点检查：

configured
collector.lastError
lastConsumedAt
lastInsertedAt
eventCount

---

相比旧 CPA-Manager 的变化

旧 CPA-Manager Docker 文档使用 seakee/cpa-manager，并描述了 CPA 面板外接 Usage Service。CPA Manager Plus 中：

• 镜像变为 seakee/cpa-manager-plus
• 容器通常命名为 cpa-manager-plus
• Full mode 登录使用 CPAMP Admin Key，不使用 CPA Management Key
• CPA Management Key 使用 /data/data.key 加密保存
• CPA panel mode 是纯 CPA 面板，不配置外部 Manager Server 统计