重置管理员密钥

v2 Beta：保持原数据与安装状态

先按 备份与恢复 停机备份 Manager（usage.sqlite、WAL/SHM、data.key、usage-archives/，存在时）及 Embedded Runtime/secret。重置仅替换 Manager 的管理员凭证，不会恢复 data.key、轮换 CPA Management Key/Client Key、重新认领安装或完成升级。首次安装应使用 Host initialize 与 Handoff，不要用重置命令代替向导。

在同一发布 Compose 目录/项目下（保留三镜像 Digest 配对）：

docker compose -f docker-compose.v2-embedded.yml stop
docker compose -f docker-compose.v2-embedded.yml run --rm --no-deps \
  cpamp-manager reset-admin-key --db-path /data/usage.sqlite

保存终端仅显示一次的新 Admin Key；命令成功后才执行 docker compose -f docker-compose.v2-embedded.yml up -d，通过原公开入口下安装时设置的控制台地址（默认 /console，例如 http://<host>:18317/console）登录。v2 不提供 /management.html。不要删除数据卷、锁文件或安装记录；失败时保持停止，核对真实数据路径。不要让输出进入公开日志。

linux/amd64 Native 在停止完整 launcher/systemd 服务、完成备份后，从包根目录执行：

sudo ./bin/cpa-manager-plus reset-admin-key --db-path "$PWD/data/usage.sqlite"

如果显式指定新密钥，使用 --admin-key-file 及私有文件；Docker 还需把该文件只读挂到一次性容器并使用容器内路径。成功后恢复原服务，验证管理员登录和 CPA 连接，不要重复运行安装器。升级中的拒绝仍按 升级手册 处理（源基线 v1.14.10、CPA 最低 v8.0.55）。

1.x Stable：原部署恢复步骤

忘记 CPAMP 管理员密钥时，用这页重置完整 Docker / 原生 Manager Server 模式的登录密钥。它不会重置 CPA Management Key，也不能恢复丢失的 data.key。

重置命令会直接修改本地 SQLite 数据库。执行前请先停止 Manager Server，避免服务运行中继续写入 SQLite。

最短恢复流程

1. 停止 Manager Server 并备份数据目录。
2. 在对应 Docker 或原生包环境中运行 reset-admin-key。
3. 只记录终端输出的新 CPAMP 管理员密钥，不要把它提交到仓库或发到聊天中。
4. 重启 Manager Server。
5. 1.x Stable 打开 :18317/management.html；v2 Beta 打开安装时设置的控制台地址（默认 /console），用新密钥登录并确认 CPA 连接正常。

下面的命令按部署方式分类。只执行与你当前部署匹配的一组。

高级：命令内部行为

命令作用

cpa-manager-plus reset-admin-key 会替换 Manager Server SQLite 中的 settings.admin_credential_v1，写入新的盐和 HMAC 摘要。

• 不指定密钥时，会生成一个 cpamp_... 管理员密钥。
• 指定密钥时，只保存摘要，命令不会把指定密钥回显到输出。
• 命令不会启动 HTTP 服务、采集器或后台任务。
• 命令不需要 CPA Management Key，也不需要 data.key。

也可以使用别名 reset-admin-password。

执行前检查

1. 停止 Manager Server。
2. 备份完整数据目录，包含 usage.sqlite、usage.sqlite-wal、usage.sqlite-shm 和 data.key。
3. 确认命令指向真实的 Manager Server 数据库：
   • Docker 默认：/data/usage.sqlite
   • 原生包默认：二进制旁边的 data/usage.sqlite
   • 自定义部署：USAGE_DB_PATH 的值

Docker Compose

docker compose -f docker-compose.manager.yml stop cpa-manager-plus
docker compose -f docker-compose.manager.yml run --rm cpa-manager-plus reset-admin-key
docker compose -f docker-compose.manager.yml up -d cpa-manager-plus

命令会输出一次新生成的密钥：

CPA Manager Plus admin key reset.
New admin key: cpamp_...
Save this value now. It will not be shown again.

一键安装脚本创建的 Docker 部署

如果 Docker 部署由 install-cpamp.sh 创建，优先让安装器完成停止、重置、重启和登录验证：

curl -fsSLO https://raw.githubusercontent.com/seakee/CPA-Manager-Plus/main/bin/install-cpamp.sh
CPAMP_OPERATION=repair \
CPAMP_INSTALL_DIR="$HOME/cpa-manager-plus" \
bash install-cpamp.sh

修复流程会把 SQLite 中的管理员凭证同步为安装目录中的 secrets/cpamp-admin-key，因此文件中的密钥和实际登录密钥会保持一致。它不会删除 Docker 数据卷、CPA Management Key 或请求历史。

非交互环境需要明确确认：

curl -fsSLO https://raw.githubusercontent.com/seakee/CPA-Manager-Plus/main/bin/install-cpamp.sh
CPAMP_OPERATION=repair \
CPAMP_INSTALL_DIR="$HOME/cpa-manager-plus" \
CPAMP_NON_INTERACTIVE=1 \
CPAMP_CONFIRM=1 \
bash install-cpamp.sh

Docker Named Volume

docker stop cpa-manager-plus
docker run --rm \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest \
  reset-admin-key
docker start cpa-manager-plus

如果使用 GitHub Container Registry 镜像，把 seakee/cpa-manager-plus:latest 替换为 ghcr.io/seakee/cpa-manager-plus:latest。

指定管理员密钥

推荐使用 --admin-key-file，避免密钥进入 shell history：

printf '%s\n' 'replace-with-a-long-random-admin-key' > /srv/new-cpamp-admin-key.txt
docker stop cpa-manager-plus
docker run --rm \
  -v cpa-manager-plus-data:/data \
  -v /srv/new-cpamp-admin-key.txt:/run/secrets/new_admin_key:ro \
  seakee/cpa-manager-plus:latest \
  reset-admin-key --admin-key-file /run/secrets/new_admin_key
docker start cpa-manager-plus

原生包

macOS / Linux：

./cpa-manager-plus reset-admin-key

Windows PowerShell：

.\cpa-manager-plus.exe reset-admin-key

如果 SQLite 数据库不在默认数据目录，显式指定路径：

./cpa-manager-plus reset-admin-key --db-path /path/to/usage.sqlite

排障

• SQLite database not found：当前命令没有运行在真实配置环境中。请传入 --db-path，或挂载正确的 Docker volume / 宿主机目录。
• is empty / does not look like a CPA Manager Plus Manager Server database：路径指向了错误文件或新建的空文件。
• database is locked：Manager Server 或其他进程仍在使用 SQLite。停止相关进程后重试。
• 重置后仍无法登录：确认面板访问的是同一个 Manager Server。
• 生成的新密钥没有保存：在 Manager Server 停止状态下重新执行命令，会生成另一个随机密钥。