重启 Docker 中的 Dify 服务后无法访问 Web UI，可能原因有哪些？

Question

重启 Docker 中的 Dify 服务后无法访问 Web UI，常见原因包括：① 容器未真正启动（`docker ps` 查无运行中容器，可能因配置错误或健康检查失败导致自动退出）；② 端口映射失效（如 `docker run -p 3000:3000` 遗漏或宿主机端口被占用）；③ 依赖服务未就绪（PostgreSQL、Redis 启动慢或连接失败，Dify 初始化阻塞）；④ 环境变量缺失或错误（如 `DATABASE_URL`、`REDIS_URL` 配置不匹配，或 `WEB_API_URL` 指向错误地址）；⑤ 构建镜像版本不一致（本地缓存旧镜像，缺少最新前端构建产物）；⑥ 反向代理（Nginx/Caddy）未重载配置或上游地址未更新。建议按序执行 `docker logs dify-web` 查启动日志、`docker inspect dify-web` 核对网络与端口、`docker exec -it dify-web curl -v http://localhost:3000/health` 验证内部可访问性，快速定位根因。

Answer 1

```html

一、现象层：Web UI 无法访问的直观表现

用户执行 docker restart dify-web 后，浏览器访问 http://localhost:3000（或反向代理域名）返回 Connection refused、502 Bad Gateway 或空白页。此时最基础的连通性已中断，需排除「服务是否存活」这一前提。切忌直接跳入前端调试——Dify 是典型的前后端分离+多依赖服务架构，UI 不可达 ≠ 前端代码故障。

二、容器层：确认容器生命周期状态

• 执行 docker ps -a | grep dify-web，观察 STATUS 是否为 Up X seconds 或瞬时出现后变为 Exited (1)；
• 若容器未运行，立即执行 docker logs --tail 100 dify-web —— 关键线索常在首 5 行（如 Database connection failed、Redis connection timeout、FATAL: password authentication failed）；
• 注意健康检查失败导致的自动退出：docker inspect dify-web | jq '.[0].State.Health' 可验证健康探针结果。

三、网络层：端口映射与通信路径验证

检查项	命令示例	预期输出
宿主机端口占用	lsof -i :3000 或 netstat -tuln | grep :3000	无输出或仅显示 dify-web 进程
容器端口绑定	docker inspect dify-web | jq '.[0].NetworkSettings.Ports'	{"3000/tcp": [{"HostIp": "0.0.0.0", "HostPort": "3000"}]}

四、依赖层：PostgreSQL 与 Redis 就绪性深度诊断

Dify 启动时执行同步初始化（migration + cache warm-up），若依赖不可达将阻塞并退出。需交叉验证：

• docker exec -it dify-db psql -U dify -d dify -c "SELECT now();" —— 验证 DB 连通性与时钟同步；
• docker exec -it dify-redis redis-cli -a "$REDIS_PASSWORD" ping —— 注意密码需与 REDIS_URL 中一致；
• 关键陷阱：PostgreSQL 容器启动快但数据库初始化耗时（尤其首次），建议在 docker-compose.yml 中为 dify-web 添加 depends_on + condition: service_healthy 并配置健康检查。

五、配置层：环境变量语义一致性校验

常见致命错误示例：

DATABASE_URL=postgresql://dify:password@localhost:5432/dify  ❌（localhost 指向容器自身，非宿主机或 Docker 网络）
DATABASE_URL=postgresql://dify:password@dify-db:5432/dify  ✅（使用 Docker 内部服务名）
WEB_API_URL=http://localhost:5001  ❌（前端容器内访问应为 http://dify-api:5001）
WEB_API_URL=http://dify-api:5001  ✅（Docker Compose 网络内服务发现）

务必通过 docker exec dify-web env | grep -E "(DATABASE|REDIS|WEB_API)" 确认运行时实际加载值。

六、镜像层：构建一致性与缓存污染治理

本地开发中易忽略：docker build 默认复用旧 layer，若 frontend/ 目录未触发 rebuild，将导致 HTML/JS 仍为旧版（如缺失新路由或 API 调用逻辑）。解决方案：

• 强制重建： docker build --no-cache --pull -t dify-web:latest .；
• 验证镜像时间戳：docker images | grep dify-web，比对 CREATED 时间与 git commit 时间；
• 进入容器检查前端资源：docker exec dify-web ls -la /app/web/build/ | head -5。

七、代理层：反向代理配置的动态收敛

graph LR
  A[Client] --> B[Nginx/Caddy]
  B --> C{Upstream Health Check}
  C -->|OK| D[dify-web:3000]
  C -->|Failed| E[Return 502]
  subgraph Proxy Configuration Drift
  B -.-> F[nginx.conf upstream ip/port]
  F --> G[是否指向 docker network IP？]
  G -->|否| H[手动 reload 失效]
  end

典型误操作：修改 docker-compose.yml 中 ports 后未更新 Nginx 的 proxy_pass http://127.0.0.1:3000 为 proxy_pass http://dify-web:3000（Docker 网络模式下不应走 localhost）；执行 nginx -t && nginx -s reload 后，还需验证 curl -H "Host: your-domain.com" http://localhost 模拟真实请求头。

八、诊断流水线：标准化排障命令序列

1. docker ps -a | grep dify —— 容器存活态
2. docker logs --since 5m dify-web —— 启动期错误
3. docker inspect dify-web | jq '.[0].NetworkSettings.Ports' —— 端口映射
4. docker exec -it dify-web curl -v http://localhost:3000/health —— 内部 HTTP 健康
5. docker exec -it dify-web curl -v http://dify-api:5001/health —— 后端连通性
6. docker exec -it dify-web env | grep URL —— 运行时配置
7. docker exec -it dify-db psql -U dify -d dify -c "SELECT count(*) FROM migrations;" —— DB 初始化完成度

九、高阶防御：生产环境可观测性加固建议

面向 5+ 年经验工程师，推荐在 docker-compose.prod.yml 中嵌入以下实践：

• 为所有服务添加 healthcheck（含 timeout/retries/start_period）；
• 使用 docker compose up --wait 替代简单 restart，确保依赖就绪再启动应用；
• 在 dify-web 入口脚本中注入 pre-start 检查：循环调用 pg_isready 和 redis-cli ping；
• 部署 Prometheus + cAdvisor + Grafana，监控容器 restart_count、network RX/TX、HTTP 5xx rate。

十、根因归类矩阵：六类问题的交叉验证表

现象特征	最可能根因	验证命令	修复动作
容器秒退，logs 显示 "connect ECONNREFUSED 127.0.0.1:6379"	④ 环境变量错误	docker exec dify-web env | grep REDIS_URL	修正为 redis://dify-redis:6379/0
容器持续运行，但 curl localhost:3000 超时	② 端口映射失效	docker port dify-web	补加 -p 3000:3000 并重启

```