agentdock/docs/MAINTENANCE.md

升级和备份

升级 CLI

默认版本是 latest。升级时重新构建镜像：

cd /opt/ai-toolbox
docker compose build --pull --no-cache
docker compose up -d
docker compose exec ai-tools ai-tools-check

为了避免上游突然更新造成故障，首次部署成功后建议记录版本：

docker compose exec ai-tools npm list -g --depth=0

然后把 .env 中的 latest 改成确定的版本号，再重新构建。例如：

CODEX_VERSION=具体版本号
CLAUDE_VERSION=具体版本号

DeepSeek Harness 目前是 developer preview，尤其建议锁定版本。

CC Switch 与 Multica 使用固定原生二进制版本和 SHA256 校验。升级时同时修改 Dockerfile 中的版本号和对应架构校验值，不要只修改 .env 版本而保留旧校验值。

备份账号和会话

所有 CLI 的用户配置位于 .env 的 AI_HOME_PATH。默认示例为：

/opt/ai-toolbox/data

这个目录也包含 ~/.cc-switch、~/.multica、各 CLI 登录信息以及 Multica Runtime 身份，必须整体备份。

创建备份：

mkdir -p "$HOME/ai-toolbox-backups"
docker run --rm \
  -v /opt/ai-toolbox/data:/source:ro \
  -v "$HOME/ai-toolbox-backups:/backup" \
  ubuntu:24.04 \
  tar -C /source -czf /backup/ai-toolbox-home.tar.gz .

备份中包含登录凭证，应当像密码一样保护。

网页控制台还需要备份：

/vol1/1000/docker/ai-toools/console-data
/vol1/1000/docker/ai-toools/.env

.env 内的 CONFIG_ENCRYPTION_KEY 必须与 console-data 成对保存，否则无法解密 网页中保存的 API Key。备份中还包含管理员密码，也应按密码文件保护。

不要执行的命令

停止使用：

docker compose down

docker compose down 不会删除 AI_HOME_PATH 中的配置。不要手动删除该目录，除非明确要清除全部登录状态和会话。