2.3 开台体检：环境排障清单
2.3 开台体检：环境排障清单
排障铁律：先看容器状态，再看目标容器日志，再测网络连通——这个次序能避免 90% 的瞎猜。本节把开台阶段最高发的四类故障做成"症状、诊断、处方"三段式的清单，每条都配真实可复现的命令与输出。
开台三步的最后一步。前两节装了平台、挂了模型，本节假定"哪里不对劲"：这不是乌鸦嘴，而是自部署系统的日常。学会体检，环境才真正属于你。
先背下三步诊断次序
无论症状多古怪，诊断动作永远从同三步开始：
# 第一步：容器全家是否都活着、有没有在重启环里打转 docker compose ps # 盯两列：STATUS 应为 Up；若出现 Restarting 或 Exited，记下是哪个容器 # 第二步：看可疑容器的最近日志，错误通常就写在最后几十行 docker compose logs --tail 50 api # 换成可疑容器的名字 # 关注：端口占用 bind 报错、连不上数据库、密钥无效、权限拒绝 # 第三步：测目标容器的网络连通（比如模型供应商出网） docker compose exec api curl -s -o /dev/null -w "%{http_code}" https://api.openai.com # 返回 000 说明出网不通（代理/DNS 问题）；401/403 说明网络通但鉴权问题
这三步的价值在于把问题钉死在哪一层：容器层、配置层还是网络层。钉死之后，下面的四类高频故障就能对号入座。
故障一：网关起不来，端口被占
症状：docker compose ps 里 nginx 容器 Exited，日志里有 bind: address already in use。浏览器访问端口直接拒连。
诊断：宿主机上已有服务占了同一端口——老项目的前端、另一个 Nginx、或上一次没停干净的 Dify。
处方：要么换端口（改 EXPOSE_NGINX_PORT 后 docker compose up -d），要么找到占用者处理：
# Linux 下查端口占用（8088 换成你的端口） ss -lntp | grep 8088 # 输出示例：LISTEN 0 4096 0.0.0.0:8088 users:(("nginx",pid=1731,fd=6)) # 是上次没停干净的进程就停掉；是别的业务就换端口，别硬抢
故障二：容器反复重启（重启环）
症状：某容器 STATUS 一栏 Restarting (1) 5 seconds ago，计数不断增长。控制台时好时坏。
诊断：容器内进程启动即崩，九成是依赖项没就绪或配置非法。最常见两种：数据库容器还没就绪，API 容器抢先启动连库失败；.env 被改出语法错误（少了引号、值里有空格没加引号）。
处方：先看日志把崩因钉死。若是启动顺序问题，docker compose restart api 单独重启即可恢复；若是 .env 语法问题，修完后必须 docker compose up -d 重建容器（restart 不会重新注入环境变量——这是本节最容易踩的认知坑）：
docker compose logs --tail 30 api # 典型输出：sqlalchemy 错误 connection refused → 等库就绪后重启 api # 典型输出：ENV 值解析失败 → 修 .env，然后 up -d 重建
故障三：模型接入"成功"但对话报错
症状：供应商密钥填了、模型也选中了，调试面板一发消息就报错，常见文案是鉴权失败、模型不存在或超时。
诊断：三类来源要对号。鉴权失败——密钥复制时带了空格，或密钥没给对应模型的权限；模型不存在——模型名拼写与供应商控制台不一致，或该区域账号没有此模型；超时——容器出网不通（代理环境最常见），或供应商限流。
处方：用第三步的 curl 命令把网络先验通，再核对密钥与模型名。代理环境给 Docker 守护进程配置代理，或在 .env 里给平台设置出网代理变量后重建。服务商偶发限流导致的零星失败，属于外部现象：重试即可，别急着动自己的配置。
故障四：控制台能登，发布出去的页面白屏
症状：控制台一切正常，点"发布"拿到的链接或嵌入代码打开是空白页。
诊断：多半不是故障，是 2.1 节那四个 URL 没配——发布出去的页面脚本仍指向容器内部地址或示例值，浏览器根本找不到服务。
处方：回 .env 把 CONSOLE_API_URL、SERVICE_API_URL、APP_WEB_URL 改成用户真实可访问的地址（团队内网部署就填内网 IP），docker compose up -d 重建后重试。浏览器强刷一次避免旧缓存误导判断。
一张可以贴墙上的体检表
把上述内容收敛成开台验收清单，全部打勾才算环境就绪，直接进入第 3 章：
开台体检表 v1 [ ] docker compose ps 全部 Up，无 Restarting [ ] 控制台可登录，管理员密码非默认且已记录 [ ] SECRET_KEY 已替换为随机值（2.1） [ ] 系统模型三件套已设置：推理 / 嵌入 /（可选）重排 [ ] 调试面板一句话对话成功，流式输出正常 [ ] .env 四个 URL 与真实访问地址一致，发布页不白屏 [ ] 供应商控制台已为密钥设消费上限 [ ] 数据库卷做过一次备份演练（哪怕只是手动导出一次）
最后一条最容易被略过，但它把第 7 章的备份话题提前变成了肌肉记忆——第一次备份永远应该在"什么都没发生"的时候做。
💡 关键直觉：排障能力的核心不是记住多少报错，而是永远先定位层次再动手。三步诊断次序（容器→日志→连通）就是"定位层次"的机械化版本，它把玄学变成流程。
本节要点回顾
- 三步次序：容器状态→目标容器日志→网络连通，任何故障都从这里起步；
- 四类高频故障：端口占用、重启环、模型不通、发布白屏，各有固定处方；
- restart 不重注环境变量：改过
.env必须 up -d 重建，这是重启环处理中最隐蔽的坑； - 白屏先查 URL 配置：四地址与真实访问地址一致是发布可用的前提；
- 体检表文化：环境验收用清单而非感觉，备份演练从第一天开始。
环境全绿，模型出话。下一章进入工作室，把小艺从空白画布搭成能发布的产品。