常见问题与排查

先确认故障发生在哪一段：浏览器到控制面 → 节点到 Manager → 模型部署 → 发布路由 → 应用到推理网关 → 网关到上游。查看对应服务的健康状态与日志，避免只凭页面上的一个错误提示判断原因。

表现	首先检查
控制台从外部打不开	WEBSERVER_PORT、HOST_IP、主机防火墙、云安全组及反向代理；本机先访问控制面 /health
节点引导失败或上线后离线	从节点机访问 Manager 控制面；核对 LLMPOD_NODE_MANAGER_IP、/ws/node 转发、引导令牌与 Node 日志
节点在线但无 GPU	宿主驱动、设备可见性、NVIDIA Container Toolkit / Ascend 运行时与容器设备映射
模型部署失败	部署详情阶段进度、模型下载或本机挂载、引擎兼容性、镜像拉取与剩余显存
模型市场有模型但 API 返回 404	model 是否为对外模型名，发布是否完成，是否用了正确的协议路径
API 返回 401	请求是否打到 PROXY_PORT，Key 是否有效、禁用或过期，请求头是否正确
API 返回 402 / 403 / 429	租户余额、模型封禁、Key 授权和用量限额；429 也可能来自上游
API 返回 502 / 504	端点地址、协议和上游模型名；从网关容器检查上游可达性与超时

在安装目录（默认 /opt/llmpod）查看服务状态和日志：

cd /opt/llmpod
docker compose --env-file .env ps
docker compose --env-file .env logs --tail=200 webserver proxyserver

推理请求在准入阶段被拒绝时，不会写调用日志；Anthropic Token Count 和当前 Embeddings 适配器也不写调用日志。排查这类请求应同时看 HTTP 响应、网关日志与指标。日志分享前请移除 API Key、密码、令牌和请求中的敏感内容。更细的接口状态见API 参考，指标入口见监控与调用日志。