09-troubleshooting

09. 常见问题与排错 §

工具速查 §

docker logs --tail 50 cli-proxy-api
docker logs --tail 50 mihomo
docker exec cli-proxy-api ./CLIProxyAPI --help
docker exec cli-proxy-api ls /root/.cli-proxy-api/

排错原则：先看日志，再分层定位（客户端 → CPA → mihomo → 上游）。

---

部署/启动类 §

Q：docker compose up -d 报 unknown shorthand flag: 'd' §

原 Docker 没装 compose v2 插件。

# Ubuntu/Debian
apt install -y docker-compose-plugin
# CentOS/Rocky/OpenCloudOS
dnf install -y docker-compose-plugin

或直接用 docker run 单行命令。

Q：粘贴 docker run 多行命令报 unknown flag / command not found §

shell 把 \ 后面的换行处理掉了，或者粘贴时被 shell 加了缩进。合并成一行执行最稳。

Q：写 heredoc (cat > file <<'EOF' ... EOF) 时多了引号/缩进 §

不少终端会自动给粘贴内容加缩进。改用 vi 直接编辑或者一次写完不要粘贴。

Q：mihomo 容器启动崩溃，日志说 address already in use 0.0.0.0:53 §

DNS 监听端口和 systemd-resolved 冲突。改 config.yaml：

dns:
  listen: '0.0.0.0:1053'

Q：auth file changed 但 0 clients 不变 §

凭据文件格式错或被改坏了。删掉重新登录：

rm /root/CLIProxyAPI/auths/有问题的.json
docker exec -it cli-proxy-api ./CLIProxyAPI --codex-login --no-browser

---

网络/代理类 §

Q：curl https://api.openai.com 不通 §

确认走代理：

curl -x http://127.0.0.1:7890 -I https://api.openai.com

通的话说明 mihomo OK，CPA 没走代理 → config.yaml 的 proxy-url 没设或 IP 错了。

Q：CPA 容器里测代理用 127.0.0.1:7890 不通 §

CPA 容器自己的 127.0.0.1 不是宿主。要用 bridge 网关 IP：

docker network inspect cliproxyapi_default --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'
# 比如 172.18.0.1，写到 proxy-url

或者把 CPA 也改成 --network host，再用 127.0.0.1:7890。

Q：ChatGPT 登录页报”该地区不可用 / not available in your country” §

出口在不支持的地区（HK/CN/RU/IR 等）。切美/日/新节点：

curl -X PUT http://127.0.0.1:9090/proxies/🔰Proxy \
  -H "Content-Type: application/json" \
  -d '{"name":"US Pro 12 | 倍率 2x"}'

注意：有些机场把 OpenAI 单独路由到其它组，不一定是 🔰Proxy。列出所有 selector：

curl -s http://127.0.0.1:9090/proxies | python3 -c "import json,sys;d=json.load(sys.stdin)['proxies'];[print(n,'->',p.get('now')) for n,p in d.items() if p['type']=='Selector']"

Q：登录到一半浏览器卡在 localhost:1455 转圈 §

SSH 隧道没起或断了。回到本地终端：

ssh -L 1455:127.0.0.1:1455 root@服务器IP

保持开着，刷新浏览器。

Q：日志里 failed to fetch latest management release information error=unexpected release status 403: ... API rate limit exceeded for 174.x.x.x §

GitHub API 按 IP 限流，共享代理出口被刷爆。两条路：

1. 切到使用人少的 US 节点，等 1 小时左右
2. 手动下载 management.html 复制进容器（06-management-panel.md §3）

Q：failed to download management asset error=... EOF §

GitHub Release 下载到一半中断，常见于不稳定的代理链路。同上：换节点 + 手动复制。

Q：/management.html 404 但配置看起来都对 §

可能命中以下一种：

1. disable-control-panel 没改成 false：grep 确认
2. secret-key 还是空：CPA 必须有 secret-key 才会注册 /v0/management/* 路由
3. 静态文件缺失：docker exec cli-proxy-api ls /CLIProxyAPI/static/ 看有没有 management.html

---

调用类 §

Q：curl /v1/models 返回 401 §

没带 API key 或 key 不在 api-keys 列表里：

curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer 你的api-key"

Q：curl /v1/chat/completions 返回 404 §

CPA 有些路径需要登录了至少一个对应类型的凭据才会注册。例如没登录 Claude 时，/v1/messages 会 404。

docker exec cli-proxy-api ls /root/.cli-proxy-api/
# 看有没有对应 provider 的凭据文件

Q：model not supported / model_not_supported §

模型名拼错或被 excluded-models 排掉了。先看可用列表：

curl -s http://127.0.0.1:8317/v1/models -H "Authorization: Bearer 你的api-key" | python3 -m json.tool

Q：返回的内容很短就被截断 / 报上游错误 §

• 检查上游账号是否过期（见日志 refresh failed）
• 配额耗尽？看管理面板 Usage 标签
• 上游拒绝特定模型/用法 → 切其它凭据或换模型

Q：客户端访问 http://服务器IP:8317 504/连接被重置 §

云厂商安全组没开。给 8317 入站加规则，来源限你公网 IP。

---

性能 / 维护 §

Q：日志爆磁盘 §

容器默认 stdout 日志由 Docker 收集，长期跑会大。两个办法：

1. 给 docker run 加日志限额：

   --log-opt max-size=50m --log-opt max-file=5
   

2. 在 config.yaml 启用文件日志 + 总量限制：

   logging-to-file: true
   logs-max-total-size-mb: 500

Q：升级 CPA §

docker pull eceasy/cli-proxy-api:latest
docker stop cli-proxy-api && docker rm cli-proxy-api
# 重新跑 docker run（用回原参数）

config.yaml 和 auths/ 都在宿主上挂载，不会丢。

Q：升级 mihomo §

docker pull metacubex/mihomo:latest
docker stop mihomo && docker rm mihomo
docker run -d --name mihomo --restart unless-stopped --network host \
  -v /root/mihomo/config.yaml:/root/.config/mihomo/config.yaml \
  metacubex/mihomo:latest

下一步：10-security.md 安全加固。