原生包部署

不想使用 Docker 时，可以直接运行 CPAMP 原生包。它适合已有进程管理、systemd、launchd 或 Windows 服务托管习惯的环境。

原生包模式仍然是 Manager Server 模式：二进制会托管 /management.html，本地保存 SQLite 数据，并使用 CPAMP 管理员密钥登录。它不是旧 CPA-Manager 的“给 CPA Panel 外接 Usage Service”工作流。

前置要求

运行前先准备：

• CPA / CLI Proxy API 单独运行。
• CPA Management API 已启用。
• CPA Management Key。
• CPAMP 数据目录持久化并纳入备份。
• 同一个 CPA 用量队列只由一个 CPAMP Manager Server 消费。

推荐 CPA 版本：

v7.1.39+

HTTP 用量队列最低要求：

v6.10.8+

下载

从 GitHub Releases 下载对应平台包。

常见包名：

cpa-manager-plus_<version>_linux_amd64.tar.gz
cpa-manager-plus_<version>_linux_arm64.tar.gz
cpa-manager-plus_<version>_darwin_amd64.tar.gz
cpa-manager-plus_<version>_darwin_arm64.tar.gz
cpa-manager-plus_<version>_windows_amd64.zip
cpa-manager-plus_<version>_windows_arm64.zip

Linux 查看架构：

uname -m

映射：

x86_64  -> linux_amd64
aarch64 -> linux_arm64
arm64   -> linux_arm64

手动运行

macOS / Linux：

tar -xzf cpa-manager-plus_vX.Y.Z_linux_amd64.tar.gz
cd cpa-manager-plus_vX.Y.Z_linux_amd64
./cpa-manager-plus

Windows PowerShell：

Expand-Archive .\cpa-manager-plus_vX.Y.Z_windows_amd64.zip -DestinationPath .
cd .\cpa-manager-plus_vX.Y.Z_windows_amd64
.\cpa-manager-plus.exe

打开：

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

如果没有配置管理员密钥，进程会在日志中输出一次生成的 cmp_admin_...。请立即保存。

也可以显式设置：

macOS / Linux：

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

Windows PowerShell：

$env:CPA_MANAGER_ADMIN_KEY = 'replace-with-a-long-random-admin-key'
.\cpa-manager-plus.exe

数据位置

默认情况下，原生包会在二进制旁边创建：

config.json
data/usage.sqlite
data/data.key

可通过环境变量覆盖：

USAGE_DATA_DIR=/var/lib/cpa-manager-plus ./cpa-manager-plus

或：

USAGE_DB_PATH=/var/lib/cpa-manager-plus/usage.sqlite ./cpa-manager-plus

需要备份：

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

data.key 用来解密已保存的 CPA Management Key。丢失后只能重新保存 CPA 连接。

Linux systemd 示例

安装到固定目录：

sudo mkdir -p /opt/cpa-manager-plus /var/lib/cpa-manager-plus
sudo cp -a cpa-manager-plus_vX.Y.Z_linux_amd64/* /opt/cpa-manager-plus/
sudo useradd --system --no-create-home --shell /usr/sbin/nologin cpa-manager-plus
sudo chown -R cpa-manager-plus:cpa-manager-plus /opt/cpa-manager-plus /var/lib/cpa-manager-plus

创建 /etc/systemd/system/cpa-manager-plus.service：

[Unit]
Description=CPA Manager Plus Manager Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=cpa-manager-plus
Group=cpa-manager-plus
WorkingDirectory=/opt/cpa-manager-plus
ExecStart=/opt/cpa-manager-plus/cpa-manager-plus
Restart=on-failure
RestartSec=3

Environment=HTTP_ADDR=0.0.0.0:18317
Environment=USAGE_DATA_DIR=/var/lib/cpa-manager-plus
# 推荐用环境文件或 secret manager 提供稳定密钥。
# Environment=CPA_MANAGER_ADMIN_KEY=replace-with-a-long-random-admin-key

[Install]
WantedBy=multi-user.target

启动：

sudo systemctl daemon-reload
sudo systemctl enable --now cpa-manager-plus
sudo systemctl status cpa-manager-plus

查看日志：

journalctl -u cpa-manager-plus -f

首次 setup

打开：

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

填写：

管理员密钥:         日志中的 cmp_admin_... 或你配置的管理员密钥
CPA URL:            http://127.0.0.1:8317、http://<cpa-host>:8317 或你的 CPA 地址
CPA Management Key: CPA remote-management.secret-key

setup 后：

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

后台运行

生产环境建议使用 systemd、launchd、Windows 服务管理器或进程管理工具托管进程。无论使用哪种方式，都要保证数据目录持久化并纳入备份。

升级

1. 停止原生进程。
2. 备份数据目录，包括 data.key。
3. 解压新包。
4. 复制 config.json 和 data/，或继续使用 USAGE_DATA_DIR / USAGE_DB_PATH。
5. 启动新二进制。

systemd 示例：

sudo systemctl stop cpa-manager-plus
sudo cp -a /var/lib/cpa-manager-plus /var/lib/cpa-manager-plus.backup.$(date +%Y%m%d%H%M%S)
sudo cp -a cpa-manager-plus_vX.Y.Z_linux_amd64/* /opt/cpa-manager-plus/
sudo systemctl start cpa-manager-plus

升级不会要求手动迁移 SQLite。程序启动时会自动执行兼容迁移。

验证

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

检查 configured、collector.lastError、lastConsumedAt、lastInsertedAt 和 eventCount。

如果监控页面为空，继续按 请求监控排障 检查。