当前位置：首页 > news >正文

从CPA-Manager迁移到Plus：历史数据保留与配置无缝过渡

news 2026/7/31 21:02:31

从CPA-Manager迁移到Plus：历史数据保留与配置无缝过渡

【免费下载链接】CPA-Manager-PlusA self-hosted CPA / CLIProxyAPI management panel and AI gateway observability dashboard for requests, usage, cost, quota, failures, and account health.项目地址: https://gitcode.com/gh_mirrors/cp/CPA-Manager-Plus

CPA-Manager-Plus是一款自托管的CPA/CLIProxyAPI管理面板和AI网关可观测性仪表板，专为请求、使用量、成本、配额、故障和账户健康状况设计。本指南将帮助您从旧版CPA-Manager平滑迁移到Plus版本，确保历史数据和配置的无缝过渡。

迁移前的关键准备工作

在开始迁移之前，做好充分的准备工作至关重要。首先，确认您的CPA本体版本是否符合要求 - 推荐使用v7.1.0及以上版本，HTTP用量队列至少需要v6.10.8+。其次，确定旧Manager Server的数据位置，这取决于您的部署方式：

Docker卷通常命名为cpa-manager-data
宿主机目录挂载通常映射到容器的/data目录
原生包默认数据存储在程序目录下的data/usage.sqlite

最重要的一步是停止旧容器或进程，并备份整个数据目录，包括usage.sqlite、usage.sqlite-wal和usage.sqlite-shm文件。不要只备份单个数据库文件，完整的备份可以在迁移过程中出现问题时提供安全保障。

不同部署方式的迁移步骤

Docker卷迁移

如果您使用Docker卷部署旧版CPA-Manager，迁移过程相对简单。旧的compose文件结构通常如下：

services: cpa-manager: image: seakee/cpa-manager:latest volumes: - cpa-manager-data:/data volumes: cpa-manager-data:

迁移时，只需让Plus直接挂载旧卷：

services: cpa-manager-plus: image: seakee/cpa-manager-plus:latest 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" volumes: - cpa-manager-data:/data volumes: cpa-manager-data: external: true

⚠️ 注意：Plus版本的示例compose文件默认会创建新的cpa-manager-plus-data卷。如果直接使用默认配置，您将获得一个全新的安装，不会包含任何旧数据。

宿主机目录迁移

如果您的旧容器使用宿主机目录挂载，迁移命令如下：

docker stop cpa-manager cp -a /srv/cpa-manager-data /srv/cpa-manager-data.backup docker run -d \ --name cpa-manager-plus \ --restart unless-stopped \ -p 18317:18317 \ -v /srv/cpa-manager-data:/data \ -e CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key' \ seakee/cpa-manager-plus:latest

启动后，您可以通过http://<host>:18317/management.html使用管理员密钥登录新的Plus面板。

原生包迁移

对于原生包部署，迁移步骤如下：

停止旧的cpa-manager进程
备份旧程序目录，尤其是data/usage.sqlite*文件
解压新的cpa-manager-plus_<version>_<os>_<arch>包
将旧的data目录复制到新包目录，或设置环境变量指向旧数据目录
首次启动时设置管理员密钥：

CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key' ./cpa-manager-plus

如果未设置管理员密钥，服务会生成一个cpamp_...格式的密钥，并只在首次启动日志中输出一次，请注意保存。

迁移后的验证与检查

成功启动Plus版本后，您需要进行一系列验证以确保迁移成功：

查看启动日志，确认没有出现decrypt secret、open sqlite或bootstrap manager server等错误信息
访问管理面板，检查已绑定的CPA地址、请求监控开关、采集模式和轮询间隔等配置
打开仪表盘或监控页面，确认历史数据是否正常显示

请求/status端点，检查collector状态、lastConsumedAt、lastInsertedAt和lastError等指标
备份迁移后的/data目录，此时应包含新生成的data.key文件

数据安全与备份策略

Plus版本引入了新的数据加密机制，将CPA Management Key加密存储在SQLite数据库中。默认的数据密钥位于/data/data.key，请务必了解以下安全规则：

仅泄露usage.sqlite文件时，攻击者无法直接获取CPA Management Key
同时泄露usage.sqlite和data.key时，CPA Management Key可能被解密
丢失data.key时，已加密的CPA Management Key无法恢复，只能重新配置

因此，进行灾备时，务必同时备份SQLite文件和data.key；而在共享排查材料时，不要上传data.key文件。

常见问题与解决方案

迁移过程中可能会遇到一些常见问题，以下是解决方案：

迁移后没有旧数据：通常是因为挂载了新的cpa-manager-plus-data空卷，而不是旧的cpa-manager-data卷
登录一直401：请记住，Manager Server接口需要管理员密钥，而CPA Management Key仅用于登录CPA控制面板
监控页面为空：确认CPA用量发布已开启，USAGE_COLLECTOR_MODE与网络路径匹配，并且同一个CPA实例只有一个Manager Server消费用量队列
解密失败：检查是否在迁移后丢失或替换了/data/data.key文件

如果您遇到管理员密钥丢失的情况，可以参考重置Manager Server管理员密钥文档进行处理。