CPA Update（v2.2.1）

目标

在不丢配置、不丢认证、可快速回滚的前提下，完成 CLI Proxy API 更新或配置迁移。

官方资源

• Docker Hub: eceasy/cli-proxy-api
• GitHub: router-for-me/Cli-Proxy-API
• 最新版本查询: docker pull eceasy/cli-proxy-api:latest 或查看 Docker Hub tags

强制安全规则

1. 任何修改前先确认用户同意（尤其是重启/替换生产容器）。
2. 任何修改前先备份（镜像 + 配置 + auth 目录）。
3. 先测试再切生产。
4. 保留可执行回滚路径。

0) 先做现网发现（禁止硬编码）

不要假设固定容器名、镜像名、版本号、端口。

# 找 CPA 容器
docker ps --format 'table {{.Names}}t{{.Image}}t{{.Status}}'

# 查看当前版本信息（注意：某些版本会输出版本后返回非0）
docker exec <CONTAINER_NAME> ./CLIProxyAPI --version || true

# 假设配置路径为 /opt/cliproxyapi/config.yaml，读取关键项
sed -n '1,220p' /opt/cliproxyapi/config.yaml

# 快速定位当前启用的 provider 段
grep -n -- "-api-key:" /opt/cliproxyapi/config.yaml

# 检查官方最新版本
docker pull eceasy/cli-proxy-api:latest

记录以下基线（用于变更对比）：

• 容器名、镜像名、映射端口
• 当前版本号（通过 ./CLIProxyAPI --version 获取）
• auth-dir
• remote-management.allow-remote
• 当前使用的 provider 段（如 gemini-api-key、claude-api-key、codex-api-key、xai-api-key 等）

1) 备份（必须）

mkdir -p /opt/cliproxyapi/backup /opt/cliproxyapi/backups
TS=$(date +%Y%m%d-%H%M%S)

# 备份镜像（将 <IMAGE> 替换为当前生产镜像）
docker save <IMAGE> > /opt/cliproxyapi/backup/cliproxyapi-image-${TS}.tar

# 备份配置
cp /opt/cliproxyapi/config.yaml /opt/cliproxyapi/backup/config-${TS}.yaml

# 备份认证目录
cp -a /opt/cliproxyapi/auth /opt/cliproxyapi/backup/auth-${TS}

# 保存现网基线信息
HOST_PORT=$(docker inspect <CONTAINER_NAME> --format '{{(index (index .NetworkSettings.Ports "8317/tcp") 0).HostPort}}' 2>/dev/null || echo "unknown")
VERSION_RAW=$(docker exec <CONTAINER_NAME> ./CLIProxyAPI --version 2>&1 || true)
VERSION_LINE=$(printf '%sn' "$VERSION_RAW" | grep -m1 'CLIProxyAPI Version' || echo "$VERSION_RAW")
cat > /opt/cliproxyapi/backups/baseline-${TS}.md << EOF
# Baseline ${TS}
Container: <CONTAINER_NAME>
Image: <IMAGE>
Version: ${VERSION_LINE}
Port: ${HOST_PORT}
Auth Dir: /opt/cliproxyapi/auth
Config: /opt/cliproxyapi/config.yaml
EOF

2) 判断更新类型

A. 仅配置变更（推荐优先）

适用于：新增/修改 provider、模型路由、管理参数、重试策略等。

流程：

1. 编辑 config.yaml
2. 校验 YAML 格式（建议）
3. 重启容器并验证

# 2A-1 重启
docker restart <CONTAINER_NAME>

# 2A-2 健康检查
curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer <API_KEY>" | head

B. 镜像升级（涉及容器替换）

适用于：官方发布新版本或需要修复基础镜像问题。

官方镜像地址: eceasy/cli-proxy-api:latest

**兼容修复要点：**确保容器内存在 auth 目录并可写（常见问题是 /root/.cli-proxy-api 权限/挂载冲突）。

直接使用官方镜像（推荐）:

# 拉取最新官方镜像
docker pull eceasy/cli-proxy-api:latest

# 测试容器（使用测试端口 8318）
docker run -d --name cliproxyapi-test 
  -p 8318:8317 
  -v /opt/cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml 
  -v /opt/cliproxyapi/auth:/root/.cli-proxy-api 
  --restart unless-stopped 
  eceasy/cli-proxy-api:latest

# 等待启动（约 5-10 秒）
sleep 10

# 健康检查
curl -s http://127.0.0.1:8318/v1/models -H "Authorization: Bearer <API_KEY>" | head

# 检查日志
docker logs --tail 50 cliproxyapi-test

# 验证成功后停止测试容器
docker stop cliproxyapi-test && docker rm cliproxyapi-test

自定义镜像构建（如需特殊配置）:

FROM eceasy/cli-proxy-api:latest
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
RUN mkdir -p /root/.cli-proxy-api && chmod 755 /root/.cli-proxy-api
WORKDIR /CLIProxyAPI
EXPOSE 8317
CMD ["./CLIProxyAPI"]

3) 生产发布（需用户确认）

# 停止并删除当前容器
docker stop <CONTAINER_NAME>
docker rm <CONTAINER_NAME>

# 使用官方最新镜像启动生产容器
docker run -d 
  --name <CONTAINER_NAME> 
  -p 8317:8317 
  -v /opt/cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml 
  -v /opt/cliproxyapi/auth:/root/.cli-proxy-api 
  --restart unless-stopped 
  eceasy/cli-proxy-api:latest

4) 发布后验收清单

1. /v1/models 可返回完整模型列表
2. 随机抽测至少 1 个关键模型（如 gpt/claude/gemini/xai）
3. 日志无持续报错（auth、401、timeout、panic）
4. 管理接口（若启用）可访问且权限正确
5. 版本信息确认：docker exec <CONTAINER_NAME> ./CLIProxyAPI --version

5) 回滚（必须可用）

# 停新容器
docker stop <CONTAINER_NAME> && docker rm <CONTAINER_NAME>

# 恢复旧镜像
docker load < /opt/cliproxyapi/backup/cliproxyapi-image-<TS>.tar

# 用旧镜像重启
docker run -d 
  --name <CONTAINER_NAME> 
  -p 8317:8317 
  -v /opt/cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml 
  -v /opt/cliproxyapi/auth:/root/.cli-proxy-api 
  --restart unless-stopped 
  <OLD_IMAGE>

6) 更新成功后归档与清理（需用户确认）

目标：保持 /opt/cliproxyapi 干净可读；不删除在线配置与认证目录；保留回滚能力。

默认原则（推荐）

1. 永远保留在线目录：
   • /opt/cliproxyapi/config.yaml
   • /opt/cliproxyapi/auth/
2. 每次升级成功后，把历史备份移动到时间戳归档目录：
   • /opt/cliproxyapi/archive/<YYYYmmdd-HHMM>/
3. 保留策略：
   • archive/ 保留最近 2 次升级归档
   • backup/ 仅保留“当前升级批次”产物（可为空）
   • 至少保留 1 份可用回滚镜像（tar 或已打 tag 的本地镜像）
4. 仅归档/删除“历史备份”，不动生产容器和在线挂载。

归档命令模板（先归档，不直接删除）

set -euo pipefail
TS=$(date +%Y%m%d-%H%M)
ARCHIVE_DIR="/opt/cliproxyapi/archive/${TS}"
mkdir -p "$ARCHIVE_DIR"

# 记录归档前快照
find /opt/cliproxyapi -maxdepth 2 -mindepth 1 | sort > "$ARCHIVE_DIR/PRE_ARCHIVE_SNAPSHOT.txt"

# 移动历史备份（仅示例，可按实际目录调整）
shopt -s nullglob
for f in 
  /opt/cliproxyapi/backup/auth-* 
  /opt/cliproxyapi/backup/config-*.yaml 
  /opt/cliproxyapi/backup/*.tar 
  /opt/cliproxyapi/config.yaml.backup.*
 do
  [ -e "$f" ] && mv "$f" "$ARCHIVE_DIR/"
 done

# 写归档说明
cat > "$ARCHIVE_DIR/README.md" <<EOF
# CPA Archive ${TS}

归档时间：$(date '+%Y-%m-%d %H:%M:%S %Z')

在线目录（未修改）：
- /opt/cliproxyapi/config.yaml
- /opt/cliproxyapi/auth/

本次归档用于保留历史备份，便于审计与回滚追溯。
EOF

可选清理（确认后执行）

# 仅清理 dangling 镜像层（安全）
docker image prune -f

# 如需删除旧测试容器（示例）
docker rm -f cliproxyapi-test || true

归档后复检（必须）

docker ps --format 'table {{.Names}}t{{.Status}}t{{.Ports}}'
curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer <API_KEY>" | head

常见故障排查

• 容器循环重启：优先看 auth 目录挂载与权限。
• 模型列表缺失：检查 provider 段和 API key 是否生效。
• 请求 401/403：检查调用 key 与 upstream key 是否混淆。
• 管理接口异常：检查 remote-management.secret-key 与 allow-remote。
• 版本升级后功能异常：检查新版本是否有 breaking changes，参考官方 changelog。

维护建议

• 定期检查更新：每月检查一次官方镜像是否有新版本
• 基线文档化：把“现网基线”单独保存为 /opt/cliproxyapi/backups/baseline-<date>.md
• 测试先行：任何变更都先在测试端口验证
• 版本记录：在配置文件注释中记录当前使用的镜像版本和更新日期

版本升级最佳实践

1. 小步快跑：不要跳过多版本升级，逐版本验证
2. 关注 changelog：升级前查看官方 release notes
3. 备份验证：确保备份文件可以正常恢复
4. 监控告警：升级后密切监控日志和错误率