07-troubleshooting

07. 常见问题与排错 §

工具速查 §

docker ps | grep new-api
docker logs --tail 50 new-api
docker exec new-api wget -qO- http://localhost:3000/ | head -3
curl -sI http://127.0.0.1:3000/
ss -tlnp | grep 3000

排错原则：先确认 New API 容器本身，再确认公网访问，再确认 New API 到 CPA，再确认上游模型。

---

部署/启动类 §

Q：docker run 多行粘贴后报 invalid reference format §

多行反斜杠或缩进被终端处理坏了。直接用单行命令：

docker run -d --name new-api --restart unless-stopped -p 3000:3000 -e TZ=Asia/Shanghai -v /root/new-api/data:/data calciumion/new-api:latest

Q：启动时报 Docker iptables 错误 §

报错类似：

iptables: No chain/target/match by that name

处理：

docker rm new-api
systemctl restart docker
docker run -d --name new-api --restart unless-stopped -p 3000:3000 -e TZ=Asia/Shanghai -v /root/new-api/data:/data calciumion/new-api:latest

Q：日志里 REDIS_CONN_STRING not set §

SQLite 单机部署不用 Redis，这是提示不是错误。

Q：日志里 system is not initialized and no root user exists §

正常。第一次访问网页会进入初始化流程，创建管理员账号即可。

---

网络访问类 §

Q：服务器本地能访问，浏览器打不开 §

服务器上先确认：

curl -sI http://127.0.0.1:3000/
ss -tlnp | grep 3000

如果本地返回 200，说明容器和宿主机都没问题，重点查：

• 腾讯云安全组是否放行 TCP:3000
• 安全组是否绑定到了这台实例
• 来源是否填了本机公网 IP，而不是服务器内网 IP
• 系统防火墙是否拦截

Q：安全组来源 IP 怎么填 §

在本机 Mac 上：

curl -4 ifconfig.me

返回 x.x.x.x，安全组来源填：

x.x.x.x/32

Q：浏览器显示 502 §

分层测：

docker exec new-api wget -qO- http://localhost:3000/ | head -3
curl -sI http://127.0.0.1:3000/

如果这两条都正常，502 不是 New API 崩了，多半是公网链路、安全组、反代或云安全产品。

---

渠道/CPA 类 §

Q：渠道 Base URL 填 127.0.0.1:8317 不通 §

New API 在容器里，容器内 127.0.0.1 是容器自己。

本次部署填：

http://172.17.0.1:8317

Q：渠道测试 401 §

CPA 的 API key 填错，或者没带 Bearer。先在服务器测：

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

Q：渠道测试 timeout / refused §

从 New API 容器里测：

docker exec new-api wget -qO- http://172.17.0.1:8317/v1/models \
  --header="Authorization: Bearer 你的CPA_API_KEY"

如果这里不通，说明 New API 容器到 CPA 的网络路径有问题。

Q：模型不存在 §

先看 CPA 实际模型列表：

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

New API 渠道里模型名必须填上游真实支持的模型。

---

计费/配置类 §

Q：Model gpt-5.4 price not configured §

这是价格配置问题，不是网络问题。

两种解决方式：

1. 系统设置 -> 运营设置 开启自用模式。
2. 系统设置 -> 分组与模型定价设置 为该模型配置价格。

Q：用户 token 调用时报额度不足 §

检查：

• 用户是否有额度。
• 用户所在分组是否有对应模型价格。
• 渠道是否支持该分组。
• 是否开启了自用模式但用的是普通用户流程。

维护命令 §

重启 New API：

docker restart new-api

查看日志：

docker logs --tail 100 new-api

删除并重建容器但保留数据：

docker stop new-api
docker rm new-api
docker run -d --name new-api --restart unless-stopped -p 3000:3000 -e TZ=Asia/Shanghai -v /root/new-api/data:/data calciumion/new-api:latest