按 现象 → 可能原因 → 处理 排列。
网站打不开 / 502 Bad Gateway
| 可能原因 | 处理 |
|---|
| Open WebUI 容器未运行 | docker ps；cd /root/openwebui && docker compose up -d |
| 端口不是 3002 | docker port openwebui；修正 Nginx proxy_pass |
| Nginx 配置错误 | sudo nginx -t |
能打开页面，但所有模型报错
| 可能原因 | 处理 |
|---|
| LiteLLM 未运行 | docker ps | grep litellm；bash /root/litellm/operation.sh |
| Open WebUI Connections 未配或 Key 错误 | 核对 Base URL、LITELLM_MASTER_KEY |
| 厂商 Key 失效/欠费 | docker logs litellm；用 curl 单独测 /v1/chat/completions；欠费则用 bucssatech@gmail.com 登录厂商充值，见 API 充值 |
流式输出卡顿、整段跳出
| 可能原因 | 处理 |
|---|
| Nginx 缓冲开启 | 确认 proxy_buffering off |
| 超时过短 | 增大 proxy_read_timeout |
| 模型侧限流 | 换模型或稍后重试 |
LiteLLM 启动后立刻退出
| 可能原因 | 处理 |
|---|
config.yaml 语法错误 | docker logs litellm；本地 YAML 校验 |
| 缺少 env | 确认 api_keys.env 存在且挂载 |
| 端口占用 | ss -lntp | grep 4001 |
改 config 不生效
| 可能原因 | 处理 |
|---|
| 只 restart 未 recreate | 运行 bash /root/litellm/operation.sh |
| Open WebUI 缓存模型列表 | 管理后台刷新 Models |
备份失败邮件
| 可能原因 | 处理 |
|---|
| rclone 认证过期 | rclone ls remote:bucket |
| 磁盘满 | df -h；检查 retention_local |
| Docker 卷名变更 | 核对 OPENWEBUI_VOLUME |
曾出现的 Neon 常驻连接
若 LiteLLM 配置了 database_url / DATABASE_URL，会连接云 Postgres。当前架构 应删除 这两项，仅保留 master_key。详见 Introduction。