HT1072公开知识系统
返回列表总览 ↗
决决策档案2026-05-31 · 决策记录
2026-05-31 · DECISION TRACE

CPA-Manager-Plus 8318 正式替换 CPA-Manager 8316

保留方案、指标、验证、复盘和治理判断，让结论能够追溯。

2026-05-31记录日期
决策记录记录类型
14章节数

CPA-Manager-Plus 8318 正式替换 CPA-Manager 8316

  • HTML: https://decision.ht1072.top/2026-05-31-cpa-manager-plus-8318-formal-cutover.html
  • Local HTML: [已移除本地路径]
  • Generated: 2026-05-31T15:01:38+08:00

title: CPA-Manager-Plus 8318 正式替换 CPA-Manager 8316 created: 2026-05-31 updated: 2026-05-31 type: summary status: active tags: [hermes-ops, cliproxyapi, cpa-manager, upgrade, sidecar, systemd, cutover] sources: - [已移除本地路径] - [已移除本地路径] confidence: high

CPA-Manager-Plus 8318 正式替换 CPA-Manager 8316

一句话结论

2026-05-31 已按“方案 A”完成控制面替换：旧 CPA-Manager v1.5.3 从 8316 退场，CPA-Manager-Plus v0.7.0-beta 正式托管在 127.0.0.1:8318；CLIProxyAPI 主服务继续保持 127.0.0.1:8317，切换后 collector 正常、历史数据迁移成功、deadLetters=0。

最终拓扑

组件 当前端口 状态 说明
CLIProxyAPI 127.0.0.1:8317 active 主 CPA 服务未变更
CPA-Manager-Plus 127.0.0.1:8318 enabled + active/running 新控制面，正式接管 usage 管理
旧 CPA-Manager 8316 disabled + inactive/dead 已无监听，保留文件和回滚路径

为什么选 8318，而不是复用 8316

选择 8318 是为了让替换边界清楚：Plus 引入了新的 admin key、data key、设置项和数据迁移行为。如果直接复用 8316，容易被误判为一次普通小版本升级；而独立端口能明确表达“这是新控制面”，也便于观察期内保留旧服务回滚入口。

执行过程

  1. 确认 8318 空闲，8316 旧 Manager 和 8317 CPA 主服务正常。
  2. 停止旧 systemctl --user stop cpa-manager.service。
  3. 确认 8316 释放，8317 仍可访问。
  4. 备份旧 live data、旧 unit、旧二进制目录。
  5. 准备 Plus 正式二进制和数据目录。
  6. 写入 ~/.config/systemd/user/cpa-manager-plus.service，绑定 127.0.0.1:8318。
  7. systemctl --user disable cpa-manager.service，避免旧 collector 与 Plus 双消费。
  8. systemctl --user enable --now cpa-manager-plus.service。
  9. 验证 Plus health/info/status/usage/model-prices 与 SQLite 状态。
  10. 落盘切换结果和回滚命令。

关键路径

用途 路径
Plus service [已移除本地路径]
Plus binary [已移除本地路径]
Plus data [已移除本地路径]
Plus admin key file [已移除本地路径]
Plus data key file [已移除本地路径]
切换备份 [已移除本地路径]
切换结果 [已移除本地路径]
预演记录 [已移除本地路径]

验证结果

运行态

cpa-manager-plus.service: enabled + active/running
cpa-manager.service: disabled + inactive/dead
8317: CLIProxyAPI 正常监听
8318: CPA-Manager-Plus 正常监听
8316: 无监听

Plus 基础接口

GET /health -> 200, service=cpa-manager-plus
GET /usage-service/info -> configured=true, adminReady=true, migrationStatus=migrated, dataKeyReady=true, hasHistoricalData=true
GET /management.html -> 3037638 bytes

Collector

collector: running
upstream: http://127.0.0.1:8317
mode: auto
transport: subscribe
queue: usage
totalInserted: 2
deadLetters: 0

数据接口

GET /usage-service/config -> 200
GET /v0/management/model-prices -> 200
GET /v0/management/usage -> 200

SQLite 观察：

usage_events: 28936
dead_letter_events: 0
model_prices: 2
settings: 4
settings keys: admin_credential_v1, bootstrap_state_v1, manager_config_v1, setup

重要边界

  • 8318 是当前正式控制面，不再把 8316 当 live 入口。
  • 旧 cpa-manager.service 只是 disabled/inactive，不删除，便于回滚。
  • admin key 与 data key 属于敏感凭证，只记录文件路径和脱敏校验，不把明文写入 wiki 或 HTML。
  • Plus 会独占消费 8317 的 usage queue；不能让旧 Manager 与 Plus 长期双跑。
  • 备份必须包含 SQLite 数据、旧 unit、旧二进制，以及 Plus 的 data.key / admin key 文件。

回滚命令

仅回滚服务入口：

systemctl --user stop cpa-manager-plus.service
systemctl --user disable cpa-manager-plus.service
systemctl --user enable cpa-manager.service
systemctl --user start cpa-manager.service
curl -fsS http://127.0.0.1:8316/health
ss -tlnp | grep -E ':(8316|8318)\b' || true

如需把旧数据也恢复到切换前快照：

systemctl --user stop cpa-manager-plus.service || true
systemctl --user stop cpa-manager.service || true
rm -rf [已移除本地路径]
cp -a [已移除本地路径] [已移除本地路径]
systemctl --user start cpa-manager.service

后续观察

  • usage_events 是否持续增长。
  • /status 中 collector.lastConsumedAt 与 lastInsertedAt 是否持续刷新。
  • deadLetters 是否保持 0。
  • 旧 8316 是否还有外部依赖访问；若观察期无依赖，可继续保持 disabled，不急删目录。
  • Plus 的 admin key / data key 需要进入本机 secrets 备份策略。

关联页面

  • [[cliproxyapi]]
  • [[cliproxyapi-v7-upgrade-and-cpa-manager-convergence-2026-05-13]]
  • [[cpa-usage-keeper-sidecar-integration-2026-05-12]]
  • [[backup-and-restore]]
  • [[runtime-effect-check]]