Skip to main content
Version: Current

Debugging Guide

分层排查顺序​

  1. Nginx / TLS — 公网是否到达本机
  2. Open WebUI — 容器健康、卷是否挂载
  3. LiteLLM — 代理是否在线、模型列表是否返回
  4. 厂商 API — Key、配额、模型 ID 是否正确

常用命令​

# 容器与健康
docker ps -a
docker inspect openwebui --format '{{.State.Health.Status}}'
docker logs openwebui --tail 50
docker logs litellm --tail 50

# 端口
ss -lntp | grep -E '3002|4001'

# LiteLLM（替换为真实 master key）
export LITELLM_MASTER_KEY='...'
curl -sS -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  http://127.0.0.1:4001/v1/models

curl -sS -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5-mini","messages":[{"role":"user","content":"hi"}]}' \
  http://127.0.0.1:4001/v1/chat/completions

# Open WebUI 本机
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3002/

# Nginx
sudo nginx -t
curl -sSI https://ai.bucssa.org/

网络：容器间互通​

docker network inspect openwebui_default
docker exec openwebui wget -qO- http://litellm:4000/ 2>/dev/null | head

若从 Open WebUI 容器访问 litellm:4000 失败，检查 LiteLLM 是否在 openwebui_default 网络（operation.sh 已指定）。

配置 diff​

# 确认 LiteLLM 无 DATABASE_URL
docker inspect litellm --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -i database

# 卷
docker volume inspect openwebui_openwebui-data

日志级别​

LiteLLM 上游支持通过环境变量提高日志详细度（见官方文档）。临时调试可在 operation.sh 的 docker run 中追加 -e LITELLM_LOG=DEBUG，勿长期开启（可能打印请求片段）。

收集信息发给维护者​

  • 出错时间（时区）
  • 模型名
  • docker ps 输出
  • docker logs litellm --tail 100（打码 Key）
  • 是否仅生产域名失败、本机 3002 是否正常