CLIProxyAPI 部署配置手册

本文记录 CLIProxyAPI 在 Ubuntu 服务器上的标准部署流程，重点说明如何通过宿主机目录持久化配置文件、认证信息、证书和日志，避免容器重启或升级后数据丢失。

如果你的环境已经安装的是 Docker Compose Plugin，推荐优先使用 docker compose 命令；如果你安装的是旧版独立二进制，则对应命令为 docker-compose。本文示例统一写成 docker compose，两者含义一致。

1. 环境准备

1.1 更新系统

在开始部署前，先更新系统软件包：

sudo apt update
sudo apt upgrade -y

1.2 安装 Docker 与 Docker Compose

推荐直接安装 Docker 和官方 Compose Plugin：

sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

安装完成后验证版本：

docker --version
docker compose version

如果你的环境必须使用旧版独立 docker-compose，也可以手动安装：

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

2. 克隆 CLIProxyAPI 项目

从 GitHub 拉取项目代码并进入目录：

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI

3. 规划持久化目录

为了保证容器升级、重启后配置和认证数据不丢失，建议将以下内容挂载到宿主机目录：

• config.yaml：主配置文件，必须持久化
• auths/：认证凭据目录，必须持久化
• certs/：HTTPS/TLS 证书目录，推荐持久化
• logs/：日志目录，可按需持久化

3.1 创建持久化目录

这里统一放到 /srv/cli-proxy-api/：

sudo mkdir -p /srv/cli-proxy-api/auths
sudo mkdir -p /srv/cli-proxy-api/certs
sudo mkdir -p /srv/cli-proxy-api/logs
sudo touch /srv/cli-proxy-api/config.yaml

如果后续需要让当前用户直接编辑配置文件，可以额外调整权限：

sudo chown -R $USER:$USER /srv/cli-proxy-api

3.2 修改 config.yaml

创建完配置文件后，建议先编辑宿主机上的配置文件：

vim /srv/cli-proxy-api/config.yaml

其中下面这两个字段需要按实际环境修改：

remote-management:
  allow-remote: false
  secret-key: "换成你自己的管理密钥"

说明如下：

• allow-remote：是否允许远程访问管理接口；如果不希望管理接口暴露给外部，保持 false
• secret-key：管理接口访问密钥，必须改成你自己的强随机字符串，不能直接使用示例值

如果你后续需要启用远程管理，再结合公网访问策略、防火墙或反向代理统一评估是否把 allow-remote 改为 true。

4. 配置 Docker Compose

在项目根目录创建或修改 docker-compose.yml，将容器内的重要目录映射到宿主机：

services:
  cli-proxy-api:
    image: router-for-me/cli-proxy-api:latest
    container_name: cli-proxy-api
    ports:
      - "8317:8317"
      - "8085:8085"
      - "1455:1455"
      - "54545:54545"
      - "51121:51121"
      - "11451:11451"
    volumes:
      - /srv/cli-proxy-api/config.yaml:/CLIProxyAPI/config.yaml
      - /srv/cli-proxy-api/auths:/root/.cli-proxy-api
      - /srv/cli-proxy-api/certs:/CLIProxyAPI/certs
      - /srv/cli-proxy-api/logs:/CLIProxyAPI/logs
    restart: always

各挂载项说明如下：

宿主机路径	容器路径	说明
/srv/cli-proxy-api/config.yaml	/CLIProxyAPI/config.yaml	主配置文件
/srv/cli-proxy-api/auths	/root/.cli-proxy-api	认证目录
/srv/cli-proxy-api/certs	/CLIProxyAPI/certs	TLS 证书目录
/srv/cli-proxy-api/logs	/CLIProxyAPI/logs	日志目录

4.1 端口说明

上面的 ports 配置中，8317 是主服务端口，其余端口主要用于不同平台的 OAuth 登录回调：

端口	用途说明
8317	CLIProxyAPI 主服务端口，用于 API 服务和管理界面访问
8085	Gemini OAuth 登录回调端口
1455	OpenAI Codex OAuth 登录回调端口
54545	Claude OAuth 登录回调端口
51121	Antigravity OAuth 登录回调端口
11451	iFlow OAuth 登录回调端口

可以按下面的原则理解这些端口：

• 8317 一般需要长期保留，用于日常访问和服务转发
• 其余端口主要在对应平台登录授权时使用
• 如果你明确不会使用某个提供方，可以在后续评估后移除对应端口映射
• 如果服务器暴露在公网，建议通过防火墙或安全组限制这些登录回调端口的访问范围

5. 启动服务

5.1 启动容器

在项目根目录执行：

sudo docker compose up -d

如果你使用的是旧版命令，则改为：

sudo docker-compose up -d

5.2 查看运行状态

检查容器是否已经正常启动：

sudo docker ps
sudo docker logs -f cli-proxy-api

6. 升级 CLIProxyAPI

后续升级时，建议按以下流程执行：

6.1 停止并删除旧容器

sudo docker compose down

6.2 拉取最新镜像并重新启动

sudo docker compose pull
sudo docker compose up -d

如果使用旧版命令，则对应替换成 docker-compose 即可。

由于配置文件、认证信息、证书和日志都已经挂载到宿主机目录中，因此升级过程中这些数据不会丢失。

7. 需要持久化的文件与目录

内容	默认位置	是否需要持久化
config.yaml	程序目录	强制
auths/	~/.cli-proxy-api	强制
TLS 证书	自定义路径	推荐
日志	容器内部	可选

8. 常见注意事项

8.1 先创建配置文件再启动容器

如果宿主机上的 config.yaml 不存在，部分环境下文件挂载可能异常，因此建议提前执行：

sudo touch /srv/cli-proxy-api/config.yaml

8.2 关注端口与防火墙

当前示例暴露的是 8317 端口，如果服务器启用了防火墙或安全组，需要同步放行该端口。

8.3 认证目录必须保留

auths/ 目录用于保存认证凭据。如果不做持久化，重新部署后可能需要重新授权或重新登录。

8.4 启用 HTTPS 时同步持久化证书

如果你启用了 HTTPS/TLS，证书目录也必须映射到宿主机，否则容器重建后证书文件会丢失。

9. 总结

CLIProxyAPI 的部署重点不在于容器启动本身，而在于持久化策略是否完整。建议至少持久化以下内容：

• config.yaml
• auths/
• certs/（如果启用 HTTPS/TLS）
• logs/（如果需要保留运行日志）

采用以上方式后，CLIProxyAPI 在后续升级、迁移或重启时都能尽量避免配置和认证数据丢失，维护成本也会更低。