CLIProxyAPI 安装与升级指南

bash /path/to/manager-script.sh

curl -I http://[IP REDACTED]:8317
# 预期：HTTP/1.1 200（根路径返回 200 是正常的）

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
cp .env.example .env
# 编辑 config.yaml，至少配置 secret-key
vim config.yaml
docker compose up -d

docker pull eceasy/cli-proxy-api:latest
mkdir -p /root/cli-proxy-api/data

# 提取默认配置模板
docker run --rm --entrypoint cat 
  eceasy/cli-proxy-api:latest /CLIProxyAPI/config.example.yaml 
  > /root/cli-proxy-api/data/config.yaml

vim /root/cli-proxy-api/data/config.yaml

docker run -d 
  --name cli-proxy-api 
  --restart always 
  --network host 
  -v /root/cli-proxy-api/data/config.yaml:/CLIProxyAPI/config.yaml 
  -v /root/cli-proxy-api/data:/CLIProxyAPI/data 
  -v /root/cli-proxy-api/auth:/root/.cli-proxy-api 
  eceasy/cli-proxy-api:latest

# 绑定地址："" = 所有网卡，"[IP REDACTED]" = 仅本机（禁止 IP 直连）
host: ""
port: 8317
debug: false

tls:
  enable: false       # true 时启用 HTTPS
  cert: "/path/to/cert"
  key: "/path/to/key"

remote-management:
  allow-remote: true   # true = 允许远程访问管理面板
  *** "your-key-here"
  # ⚠️ ***限制：
  #   - 最大 72 字节（bcrypt 限制）
  #   - 避免 $ ! 等特殊字符（YAML 解析失败）
  #   - 建议大小写字母+数字组合
  disable-control-panel: false
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"

auth-dir: "~/.cli-proxy-api"

***
  - "***
  - "***

request-retry: 3
max-retry-credentials: 0
max-retry-interval: 30
quota-exceeded:
  switch-project: true
  switch-preview-model: true
  antigravity-credits: true
routing:
  strategy: "round-robin"
  session-affinity-ttl: "1h"

logging-to-file: false        # true = 写入文件
logs-max-total-size-mb: 500   # 日志上限（MB）
error-logs-max-files: 10
commercial-mode: false        # true = 禁用详细日志
usage-statistics-enabled: false

proxy-url: ""   # socks5://user:pass@host:port/

gemini-api-key: []
codex-api-key: []
claude-api-key: []
vertex-api-key: []
openai-compatibility: []

oauth-model-alias:
  gemini-cli:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"
      fork: true

oauth-excluded-models:
  gemini-cli:
    - "gemini-2.5-flash-lite"
    - "*-preview"

payload:
  default:
    - models:
        - name: "gemini-*"
          protocol: "gemini"
      params:
        "generationConfig.thinkingConfig.thinkingBudget": 32768
  override:
    - models:
        - name: "gpt-*"
          protocol: "codex"
      params:
        "reasoning.effort": "high"
  filter:
    - models:
        - name: "gemini-2.5-pro"
      params:
        - "generationConfig.thinkingConfig.thinkingBudget"

plugins:
  enabled: false
  dir: "plugins"
  configs:
    example:
      enabled: true
      priority: 1

pprof:
  enable: false
  addr: "[IP REDACTED]:8316"

http://<IP>:8317/management.html

curl http://localhost:8317/v1/models 
  -H "Authorization: Bearer ***

curl http://localhost:8317/v1/chat/completions 
  -H "Authorization: Bearer *** 
  -H "Content-Type: application/json" 
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

curl http://localhost:8317/v1/chat/completions 
  -H "Authorization: Bearer *** 
  -H "Content-Type: application/json" 
  -d '{
    "model": "gemini-2.5-pro",
    "stream": true,
    "messages": [{"role": "user", "content": "Tell me a story"}]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="***
    base_url="http://your-server:8317/v1"
)
response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

const response = await fetch("http://your-server:8317/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ***
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-2.5-pro",
    messages: [{ role: "user", content: "Hello!" }]
  })
});

curl -s http://your-server:8317/v1/chat/completions 
  -H "Authorization: Bearer *** 
  -H "Content-Type: application/json" 
  -d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"Hello"}]}' 
  | jq -r '.choices[0].message.content'

***
  - "***

gemini-api-key:
  - "AIzaSy..."           # 你的 Gemini API Key

claude-api-key:
  - "***          # 你的 Claude API Key

codex-api-key:
  - "codex-..."           # 你的 Codex API Key

oauth-model-alias:
  gemini-cli:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"

oauth-excluded-models:
  gemini-cli:
    - "gemini-2.5-flash-lite"
    - "*-preview"
    - "*flash*"     # 通配符匹配

claude-api-key:
  # 官方 Claude API（无需 base-url）
  - api-key: "***
    models:
      - name: "claude-sonnet-4-5-20250929"
      - name: "claude-opus-4-5-20251101"

  # 第三方 Claude 代理（通过 anyrouter 等）（需 base-url）
  - api-key: "***
    base-url: "https://anyrouter.top"
    models:
      - name: "claude-haiku-4-5-20251001"

openai-compatibility:
  # 最简配置
  - name: "sensenova"
    base-url: "https://token.sensenova.cn/v1"
    api-key-entries:
      - api-key: "***
    models:
      - name: "deepseek-v4-flash"
      - name: "sensenova-6.7-flash-lite"

  # 含模型别名 + 优先级
  - name: "cline.bot"
    base-url: "https://api.cline.bot/api/v1"
    api-key-entries:
      - api-key: "sk_d7ba31d765a1abee96e8609a3e383f89a74063564d6b11394cc4d13c755c9d16"
    models:
      - name: "mimo-v2.5"
      - name: "minimax-m3"
    priority: 500

gemini-api-key:
  - api-key: "AIzaSy..."
    models:
      - name: "gemini-2.5-pro"
      - name: "gemini-2.5-flash"

curl http://[IP REDACTED]:8317/v1/models 
  -H "Authorization: Bearer your-api-key"

{
  "data": [
    {"id": "claude-haiku-4-5-20251001", "owned_by": "anthropic"},
    {"id": "deepseek-v4-flash", "owned_by": "sensenova"},
    {"id": "stepfun/step-3.7-flash-free", "owned_by": "zenmux.ai"}
  ]
}

配额超限 → cooldown（默认 60 秒）
         → 到期后自动恢复
         → 可配置 save-cooldown-status 持久化冷却状态

# 全局代理
proxy-url: "socks5://user:pass@[IP REDACTED]:1080/"

# 每提供者单独设置（管理面板中配置）
# 设为 "direct" 或 "none" 可绕过全局代理

plugins:
  enabled: true
  dir: "plugins"
  store-sources:
    - "https://example.com/registry.json"

PGSTORE_DSN=postgresql://user:pass@localhost:5432/cliproxy

GITSTORE_GIT_URL=https://github.com/your-org/cli-proxy-config.git

OBJECTSTORE_ENDPOINT=https://s3.your-cloud.com
OBJECTSTORE_BUCKET=cli-proxy-config

logging-to-file: true         # 写入文件
logs-max-total-size-mb: 500   # 日志上限
error-logs-max-files: 10      # 错误日志保留数
commercial-mode: false        # 禁用详细日志

docker logs cli-proxy-api -f        # 实时
docker logs cli-proxy-api --tail 50 # 最近 50 行

# Docker daemon 配置（/etc/docker/daemon.json）
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

# config.yaml
host: "[IP REDACTED]"

docker restart cli-proxy-api

iptables -A INPUT -p tcp --dport 8317 ! -s [IP REDACTED] -j DROP

upstream cliproxy_backend {
    server [IP REDACTED]:8317;
    keepalive 64;
}

# HTTP → HTTPS 跳转
server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/nginx/certs/api.example.com.pem;
    ssl_certificate_key /etc/nginx/certs/api.example.com.key;

    # WebSocket 支持（流式必需）
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    # 限流（可选）
    limit_req_zone $binary_remote_addr zone=api:10m rate=30r/s;
    limit_req zone=api burst=50 nodelay;

    location / {
        proxy_pass http://cliproxy_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;     # 长连接
        proxy_send_timeout 86400s;
    }

    client_max_body_size 1000m;
}

/etc/nginx/
├── conf.d/
│   ├── default.conf        # 默认返回 444
│   ├── api.example.com.conf
│   └── map.conf            # 连接升级映射
├── certs/                  # SSL 证书
├── nginx.conf
└── stream.d/

curl https://get.acme.sh | sh
~/.acme.sh/acme.sh --issue -d api.example.com --nginx
~/.acme.sh/acme.sh --install-cert -d api.example.com 
  --key-file /etc/nginx/certs/api.key 
  --fullchain-file /etc/nginx/certs/api.crt 
  --reloadcmd "nginx -s reload"

# 安装 cloudflared
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -O /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# 登录
cloudflared tunnel login

# 创建隧道
cloudflared tunnel create cliproxy

# 配置隧道（~/.cloudflared/config.yml）
tunnel: cliproxy
credentials-file: /root/.cloudflared/cliproxy.json
ingress:
  - hostname: api.example.com
    service: http://localhost:8317
  - service: http_status:404

# 配置 DNS
cloudflared tunnel route dns cliproxy api.example.com

# 启动
cloudflared tunnel run cliproxy

host: "[IP REDACTED]"
# 或 iptables / 云防火墙封锁 8317 端口

# 仅允许本地访问管理面板，通过 SSH 隧道使用
remote-management:
  allow-remote: false

limit_req_zone $binary_remote_addr zone=api:10m rate=30r/s;
limit_req zone=api burst=50 nodelay;

geo $allow_access {
    default 0;
    你的家庭IP/32 1;
    公司VPN网段/24 1;
}
server {
    if ($allow_access = 0) {
        return 403;
    }
}

# /etc/fail2ban/jail.local
[cliproxy-api]
enabled = true
port = 8317
filter = cliproxy-api
logpath = /root/cli-proxy-api/data/logs/*.log
maxretry = 5
bantime = 3600

# config.yaml 仅 root 可读
chmod 600 /root/cli-proxy-api/data/config.yaml

# /etc/sysctl.conf
fs.file-max = 1000000
net.ipv4.tcp_tw_reuse = 1
net.core.somaxconn = 65535

# /etc/security/limits.conf
* soft nofile 1000000
* hard nofile 1000000

# 限制容器内存和 CPU
docker run -d 
  --memory="1g" 
  --cpus="1" 
  --restart always 
  ...

cd /home/docker/CLIProxyAPI
cp config.yaml config.yaml.bak.$(date +%Y%m%d)
git pull
docker compose pull
docker compose up -d
docker logs cli-proxy-api --tail 10

# 1. 备份
cp /root/cli-proxy-api/data/config.yaml /root/config.yaml.bak.$(date +%Y%m%d)

# 2. 拉取新镜像
docker pull eceasy/cli-proxy-api:latest

# 3. 删除旧容器
docker rm -f cli-proxy-api

# 4. 启动新容器
docker run -d --name cli-proxy-api --restart always --network host 
  -v /root/cli-proxy-api/data/config.yaml:/CLIProxyAPI/config.yaml 
  -v /root/cli-proxy-api/data:/CLIProxyAPI/data 
  -v /root/cli-proxy-api/auth:/root/.cli-proxy-api 
  eceasy/cli-proxy-api:latest

# 5. 验证
docker logs cli-proxy-api --tail 10 | grep "started successfully"

BACKUP_DIR=/root/backups/cli-proxy-$(date +%Y%m%d-%H%M)
mkdir -p $BACKUP_DIR
cp -r /root/cli-proxy-api/data $BACKUP_DIR/
du -sh $BACKUP_DIR/
# 验证备份有实际内容（应 >12KB）
find $BACKUP_DIR/ -type f

# crontab -e，每天凌晨 3 点，保留 7 天
0 3 * * * BACKUP_DIR=/root/backups/cli-proxy-$(date +%Y%m%d); mkdir -p $BACKUP_DIR; cp -r /root/cli-proxy-api/data $BACKUP_DIR/; find /root/backups/ -type d -mtime +7 -exec rm -rf {} + 2>/dev/null; echo "Backup done: $BACKUP_DIR"

docker stop cli-proxy-api
rm -rf /root/cli-proxy-api/data
cp -r /path/to/backup/data /root/cli-proxy-api/data
# 确保 config.yaml 是文件不是目录
ls -la /root/cli-proxy-api/data/config.yaml
docker start cli-proxy-api
docker logs cli-proxy-api --tail 10
curl -I http://[IP REDACTED]:8317

# 创建备份目录（带时间戳）
BACKUP_DIR=/root/cli-proxy-full-backup-$(date +%Y%m%d-%H%M)
mkdir -p $BACKUP_DIR

# 备份全部数据
cp -r /root/cli-proxy-api/data $BACKUP_DIR/data
cp -r /root/cli-proxy-api/auth $BACKUP_DIR/auth

# 校验
du -sh $BACKUP_DIR/
echo "文件数：$(find $BACKUP_DIR -type f | wc -l)"
echo "备份完成：$BACKUP_DIR"

# 1. 停止并删除容器
docker rm -f cli-proxy-api

# 2. 恢复数据目录
rm -rf /root/cli-proxy-api/data /root/cli-proxy-api/auth
cp -r /path/to/backup/data /root/cli-proxy-api/data
cp -r /path/to/backup/auth /root/cli-proxy-api/auth

# 3. 确认 config.yaml 是文件不是目录
ls -la /root/cli-proxy-api/data/config.yaml

# 4. 启动新容器（挂载全部三个目录）
docker pull eceasy/cli-proxy-api:latest

docker run -d 
  --name cli-proxy-api 
  --restart always 
  --network host 
  -v /root/cli-proxy-api/data/config.yaml:/CLIProxyAPI/config.yaml 
  -v /root/cli-proxy-api/data:/CLIProxyAPI/data 
  -v /root/cli-proxy-api/auth:/root/.cli-proxy-api 
  eceasy/cli-proxy-api:latest

# 5. 验证
sleep 2
docker logs cli-proxy-api --tail 10
curl -I http://[IP REDACTED]:8317

# 添加到 crontab，每天凌晨 3 点自动备份，保留最近 7 天
0 3 * * * BACKUP_DIR=/root/backups/cli-proxy-full-$(date +%Y%m%d); mkdir -p $BACKUP_DIR; cp -r /root/cli-proxy-api/data $BACKUP_DIR/data; cp -r /root/cli-proxy-api/auth $BACKUP_DIR/auth; find /root/backups/ -type d -mtime +7 -exec rm -rf {} + 2>/dev/null; echo "Backup done: $BACKUP_DIR ($(du -sh $BACKUP_DIR | cut -f1))"

# 如果备份目录只有 12KB 左右（只有空的目录结构），说明备份时数据已丢失
du -sh /path/to/backup/
find /path/to/backup/ -type f

docker rm -f cli-proxy-api
rm -rf /root/cli-proxy-api/data/config.yaml

# 从镜像提取默认配置
docker run --rm --entrypoint cat 
  eceasy/cli-proxy-api:latest /CLIProxyAPI/config.example.yaml 
  > /root/cli-proxy-api/data/config.yaml

vim /root/cli-proxy-api/data/config.yaml

docker run -d --name cli-proxy-api --restart always --network host 
  -v /root/cli-proxy-api/data/config.yaml:/CLIProxyAPI/config.yaml 
  -v /root/cli-proxy-api/data:/CLIProxyAPI/data 
  -v /root/cli-proxy-api/auth:/root/.cli-proxy-api 
  eceasy/cli-proxy-api:latest

# 步骤 1：检查 secret-key 是否为空
grep -A2 'secret-key' /root/cli-proxy-api/data/config.yaml

# 步骤 2：检查是否含特殊字符
grep 'secret-key' /root/cli-proxy-api/data/config.yaml | grep -E '[$!]'

# 步骤 3：检查***长度
grep 'secret-key' /root/cli-proxy-api/data/config.yaml | awk -F'"' '{print length($2)}'

# 步骤 4：检查容器是否正常运行
docker ps -a | grep cli-proxy-api
docker logs cli-proxy-api --tail 10 | grep -E "management|secret|error"

# 步骤 5：修改***后重启
docker restart cli-proxy-api

systemctl restart docker
docker start cli-proxy-api

docker logs cli-proxy-api --tail 50 | grep -i error

# 常见原因对照：
# "is a directory" → 见 25.1
# "password length exceeds 72" → secret-key 超长
# "unsafe example API key" → 删掉 your-api-key-*
# "failed to hash" → secret-key 格式问题
# 端口占用 → ss -tunlp | grep 8317
# 磁盘满 → df -h

sed -i '/your-api-key/d' /root/cli-proxy-api/data/config.yaml
docker restart cli-proxy-api

# 1. 本地测试
curl -I http://[IP REDACTED]:8317

# 2. 检查监听
ss -tunlp | grep 8317

# 3. 检查防火墙
iptables -L -n | grep 8317

# 4. 云服务器安全组
# 登录云控制台检查防火墙规则

# 5. 如果 host="[IP REDACTED]"
# 这是正常的——服务只在本地监听，需通过 Nginx 反向代理访问

#!/bin/bash
echo "=== 1. 容器状态 ==="
docker ps -a | grep cli-proxy-api

echo -e "n=== 2. 最近日志 ==="
docker logs cli-proxy-api --tail 20

echo -e "n=== 3. 端口监听 ==="
ss -tunlp | grep 8317

echo -e "n=== 4. 本地测试 ==="
curl -I http://[IP REDACTED]:8317

echo -e "n=== 5. 配置*** ==="
grep -E 'secret-key|host:|port:' /root/cli-proxy-api/data/config.yaml

echo -e "n=== 6. 磁盘 ==="
df -h / | tail -1

echo -e "n=== 7. Docker 服务 ==="
systemctl is-active docker

echo -e "n=== 8. 数据文件 ==="
ls -la /root/cli-proxy-api/data/

# 1. 停止容器
docker rm -f cli-proxy-api

# 2. 删除镜像
docker rmi eceasy/cli-proxy-api:latest

# 3. 删除数据（⚠️ 先确认已备份）
rm -rf /root/cli-proxy-api

# 4. 删除项目目录（Compose 安装）
rm -rf /home/docker/CLIProxyAPI

# 5. 清理 Docker
docker system prune -f

# 容器
docker ps -a | grep cli-proxy-api     # 状态
docker logs cli-proxy-api -f           # 实时日志
docker logs cli-proxy-api --tail 50    # 最近日志
docker restart cli-proxy-api           # 重启
docker stop cli-proxy-api              # 停止
docker start cli-proxy-api             # 启动
docker rm -f cli-proxy-api             # 删除

# 镜像
docker pull eceasy/cli-proxy-api:latest

# 配置
vim /root/cli-proxy-api/data/config.yaml
grep secret-key /root/cli-proxy-api/data/config.yaml

# 诊断
curl -I http://[IP REDACTED]:8317
curl http://[IP REDACTED]:8317/v1/models -H "Authorization: Bearer ***
ss -tunlp | grep 8317

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

# 简单健康检查
curl -I http://[IP REDACTED]:8317
# 或外部
curl -I https://api.example.com

# 系统调优
sysctl -w fs.file-max=1000000
sysctl -w net.core.somaxconn=65535

# Docker 限制
docker run --memory="1g" --cpus="2" ...

# 商用模式
commercial-mode: true   # 禁用详细日志，减少内存开销