03-deploy-cpa

03. 部署 CLIProxyAPI §

1) 准备初始 config.yaml §

CPA 镜像里自带一份 config.example.yaml，最简单的做法是先起一次容器、把它拷出来当模板。

docker run --rm --entrypoint cat eceasy/cli-proxy-api:latest /CLIProxyAPI/config.example.yaml \
  > /root/CLIProxyAPI/config.yaml

或者直接写个最小可用配置：

# /root/CLIProxyAPI/config.yaml
host: ""
port: 8317
 
remote-management:
  allow-remote: false             # 先不允许远程管理，登录完面板后再开
  secret-key: "请改成你自己的明文" # 启动时会自动 bcrypt 哈希
  disable-control-panel: false
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"
 
auth-dir: "~/.cli-proxy-api"
 
api-keys:
  - "sk-自己定一个长一点的-key"
 
debug: false
proxy-url: ""                     # 后面填 mihomo 地址
 
routing:
  strategy: "round-robin"

关键字段含义见 08-config-reference.md。

2) 起容器（docker run 单行版） §

docker run -d \
  --name cli-proxy-api \
  --restart unless-stopped \
  -p 8317:8317 \
  -p 1455:1455 \
  -p 8085:8085 \
  -p 11451:11451 \
  -p 51121:51121 \
  -p 54545:54545 \
  -e TZ=Asia/Shanghai \
  -v /root/CLIProxyAPI/config.yaml:/CLIProxyAPI/config.yaml \
  -v /root/CLIProxyAPI/auths:/root/.cli-proxy-api \
  -v /root/CLIProxyAPI/logs:/CLIProxyAPI/logs \
  eceasy/cli-proxy-api:latest

如果你的 shell 不接受多行 \，把上面合并成一行执行即可。

端口里 1455 / 8085 / 51121 / 54545 / 11451 都是 OAuth 回调端口，只有登录的瞬间才会用到，平时也可以不暴露——登录的时候用 docker exec + SSH 隧道更安全（05-oauth-login.md）。

3) docker compose 版（可选） §

# /root/CLIProxyAPI/docker-compose.yml
services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    ports:
      - "8317:8317"
      - "1455:1455"
      - "8085:8085"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs

cd /root/CLIProxyAPI
docker compose up -d

4) 验证启动 §

docker ps | grep cli-proxy-api
docker logs --tail 20 cli-proxy-api

正常应该能看到：

CLIProxyAPI Version: vX.Y.Z, Commit: ..., BuiltAt: ...
management routes registered after secret key configuration
API server started successfully on: :8317
file watcher started for config and auth directory changes
core auth auto-refresh started (interval=15m0s)

curl -s http://127.0.0.1:8317/
# {"endpoints":["POST /v1/chat/completions",...],"message":"CLI Proxy API Server"}

5) 配置上游代理（境内 VPS 必做） §

CPA 默认走直连，境内 VPS 直连 OpenAI/Google/Anthropic 大概率失败或被风控。先按 04-mihomo-proxy.md 把 mihomo 搭起来，然后改 config.yaml：

proxy-url: "http://172.18.0.1:7890"

要点：

• 这里的 IP 不是 127.0.0.1，因为 CPA 在容器里。
• 如果 mihomo 用 network_mode: host，CPA 要从自己的 bridge 网络访问宿主，要用该 bridge 的网关 IP。查询：

  docker network inspect cliproxyapi_default --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'

  默认 bridge 一般是 172.17.0.1，custom bridge（如 compose 默认网络）通常是 172.18.0.1 / 172.19.0.1 这类。
• 也支持 socks5://、https://，Per-key 还能写 direct 强制直连。

改完重启：

docker restart cli-proxy-api
docker logs --tail 10 cli-proxy-api

日志里能正常拉 antigravity_version、models.json 就说明代理生效。

6) 关于 host 网络模式 §

如果觉得 bridge 网络的网关 IP 太麻烦，也可以让 CPA 也走 --network host：

docker run -d --name cli-proxy-api --network host ... \
  -e HTTPS_PROXY=http://127.0.0.1:7890 \
  -e HTTP_PROXY=http://127.0.0.1:7890 \
  -e NO_PROXY=localhost,127.0.0.1 \
  eceasy/cli-proxy-api:latest

此时端口不需要再 -p 映射（host 模式下端口直接暴露在宿主上）。

7) 常见问题速查 §

现象	原因	解法
容器一直 restarting	config.yaml 语法错或挂载路径错	docker logs cli-proxy-api 看红字
failed to fetch ... 403 rate limit	GitHub API 限流（共享出口 IP 被刷爆）	切代理节点 / 等几小时
failed to download management asset ... EOF	出口到 GitHub releases 不稳	手动下载，详见 06
日志里 0 clients	还没登录任何 OAuth 账号 / 没配 API key	进 05-oauth-login.md

下一步：04-mihomo-proxy.md 配置上游代理。