部署完 Dify兴致勃勃配好 Nginx 想用域名访问结果打开浏览器直接给你一个 502 Bad Gateway。这个场景我见过太多次了社区群里几乎每天都有人贴出同样的问题IP 加端口访问明明好好的套了一层 Nginx 反代就白屏docker compose ps 看容器也都活着但 curl 域名就是 502。更头疼的是 Dify 这类项目本身自带一层 Nginx很多人又在外面套一层自己的 Nginx两层反代叠在一起出问题的时候连到底是哪一层断了都说不清楚。先说个结论502 不是Dify 挂了的同义词它只是最外层 Nginx 告诉你我连不上后面的服务。所以排查的关键不是盯着 502 三个数字发呆而是从最外层开始一层层往里剥直到找到真正断掉的那一环。这篇文章我会按我自己排障时走的顺序把容器层、Nginx 配置、网络视角、隐藏坑挨个过一遍手把手带你定位问题并修复。1. 搞清楚 502 到底从哪里冒出来的1.1 502 的本质Nginx 只是个传话的中间人你可以把 Nginx 理解成一个前台接待员。客户浏览器说我要找技术部前台就拿起电话打给技术部后端服务结果电话打不通或者通了没人接或者刚说两句对面就挂了。这时候客户问前台事情办得怎么样前台只能回答一句我联系不上技术部。这句话翻译成 HTTP 状态码就是 502 Bad Gateway。在 Nginx 的实现里当它根据location匹配到某个请求要走proxy_pass反向代理时它会作为客户端向上游服务发起一个新的 HTTP 请求。如果这一步 TCP 连接建立失败、连接超时、或者上游返回了非正常响应Nginx 就返回 502。换句话说502 只说明从 Nginx 到它配置的上游服务这一段出了问题。这个认知很重要因为很多人一看到 502 就去重启 Dify 容器折腾半天发现没用。方向错了做得再多也是白费。1.2 Dify 默认的访问链路可能不止一层 Nginx这里要先说清楚 Dify 自带的那层 Nginx因为这是最容易让人懵的地方。用 Docker Compose 方式部署 Dify 时docker-compose.yaml里会有一个名为nginx的服务它对外映射宿主机的 80 和 443 端口对内则负责把请求分发给前端web服务容器内端口 3000和后端api服务容器内端口 5001。也就是说当你用http://服务器IP:80访问 Dify 时实际上已经走了一层 NginxDify 自带的。你现在要加域名、上 HTTPS通常的方案是在这台服务器上再装一个 Nginx做一层外层反向代理把请求转发给 Dify 自带的 Nginx。完整链路就是这样浏览器 - 外层Nginx你的配置 - Dify自带Nginx宿主机:80 - Dify的web/api容器这两层 Nginx 叠加的时候最常见的问题就是端口冲突。外层 Nginx 默认也想监听 80Dify 自带 Nginx 也监听 80结果其中一个起不来于是所有从外层转发过去的请求全部失败表现为 502。1.3 动手改配置之前先收集三样东西排查问题最忌一上来就改配置。你先按下面三步把现场信息收集齐很多时候答案已经藏在这些输出里了。先看 Nginx 的错误日志。在 Debian/Ubuntu 上默认是/var/log/nginx/error.logCentOS/RHEL 默认在/var/log/nginx/error.log或/var/log/nginx/error.log。执行sudo tail -n 100 /var/log/nginx/error.log日志里会直接告诉你connect() failed (111: Connection refused) while connecting to upstream或者upstream timed out (110: Connection timed out)。前者说明后端端口根本没有服务在监听或有防火墙拦截后者说明能连通但响应太慢超时了。再看 Dify 容器状态cd dify-docker docker compose ps注意每个服务的状态列是不是Up有没有Restarting的。如果某个容器反复重启日志会刷屏。最后做一个最基本的连通性测试直接绕过外层 Nginx 去访问 Dify 自带 Nginxcurl -I http://127.0.0.1:80这一步通了说明内层 Nginx 和 Dify 服务都没问题问题100%出在你外层 Nginx 到宿主机 80 端口之间这一步都不通那就要往容器层继续挖。2. 容器层排查Dify 到底是活着还是假死2.1 docker compose ps 与 docker logs 的正确打开方式很多人看到docker compose ps里服务状态是Up就放心了但这个Up只代表进程在运行不代表服务真的能处理请求。比如我遇到过一次Dify 自带的 Nginx 容器状态是Up 2 minutes但打开页面一直 502。后来看容器日志才发现这个容器启动后立刻检测到 80 端口被宿主机上另一个 Nginx 占了它反复尝试绑定失败一直在崩溃重启——docker compose ps显示的是最近一次重启后的运行状态它Up 2 minutes不代表它稳定跑了2分钟而是2分钟前刚被 Nginx 的自动重启策略拉起来。查看单个容器日志要这样docker compose logs -f --tail100 nginx重点看有没有Address already in use、bind() to 0.0.0.0:80 failed这类端口占用错误。Dify 容器组里和 502 最相关的几个服务nginx入口、web前端、api后端、worker异步任务。其中api挂掉是外显 502 的高频原因记得重点看它的日志docker compose logs -f --tail200 api2.2 端口映射和监听关系核对确认容器没崩溃之后接着查端口映射。执行docker compose ps看PORTS一列确认 Dify 自带 Nginx 的80/tcp正确映射到了宿主机端口。如果映射语句里写的是127.0.0.1:80:80那么只有服务器本机访问 127.0.0.1:80 才能进 Dify外部访问服务器公网IP的80端口是进不来的——很多云服务器用户在这里踩坑。再用几个命令交叉验证端口状态# 查看宿主机端口监听情况 ss -lntp | grep -E :80|:443 # 测试端口通不通 curl -I http://127.0.0.1:80如果ss能看到0.0.0.0:80 LISTEN但curl还是不通那就要查防火墙。云服务器用户记得顺带确认安全组规则是否放行了 80 端口的入方向流量。这一步经常被忽略外面 Nginx 转发请求到 Dify 所在服务器的 80 端口结果安全组没放行 80连接直接被拦在云平台层。C 端用户在本地测试一切正常一绑线上域名就 502十有八九是这类问题。2.3 用健康检查接口验证 api 容器Dify 的api服务提供了一个比较友好的健康检查接口。如果端口映射没问题但访问页面仍然报错可以单独请求这个接口curl -i http://127.0.0.1:5001/health正常情况下会返回一段 JSON 和 200 状态码。如果这里失败说明问题出在 Dify 后端容器自身而不是 Nginx 配置层后面谈的 Nginx 配置就不用看了回到容器日志和.env配置去排查。3. Nginx 反代配置逐项过这里才是大多数人的翻车点3.1 proxy_pass 到底应该指向谁部署形态决定写法我把常见的外层 Nginx 部署形态分成三种每一种的proxy_pass指向都不一样写错了就是 502。先看这张对照表部署形态场景说明proxy_pass 推荐写法外层 Nginx 和 Dify 在同一个宿主机上直接通过宿主端口转发http://127.0.0.1:80;外层 Nginx 是宿主机上的独立进程同样走宿主网络回环http://127.0.0.1:80;外层 Nginx 在另一个 Docker 容器里容器不在同一网络栈http://宿主机IP:80;或http://Dify所在宿主机内网IP:80;很多人的错误在于想当然了。明明外层 Nginx 跑在 Docker 容器里却写proxy_pass http://127.0.0.1:80;——这个 127.0.0.1 是外层 Nginx 容器自己的回环地址而这个容器里根本没有服务监听 80 端口一转发就必然 502日志里会出现connect() failed (111: Connection refused) while connecting to upstream。反过来外层 Nginx 是宿主机直接装的二进制进程proxy_pass http://127.0.0.1:80;才是完全正确且推荐的做法因为它直接走宿主机的回环网络不经过物理网卡效率更高。如果你不想保留 Dify 自带的那层 Nginx直接用外层 Nginx 反代到web容器3000和api容器5001也不是不行但这需要你对 Dify 的路径转发规则非常熟悉/、/api、/console/api、/files这些 location 都要单独写用错一个路径就白屏或接口报错。我的建议是路由转发这活就留给 Dify 自带 Nginx 干你外层只管把流量导到它的 80 端口省心得多。3.2 与流式输出强相关的 SSE 配置不关 buffer 就等着卡死Dify 聊天应用的消息输出是典型的 SSEServer-Sent Events流式响应。但 Nginx 默认会开启proxy_buffering把上游响应先攒到缓冲区里攒满或等连接结束再一股脑发给浏览器。这在普通页面请求上问题不大但 Dify 聊天界面需要实时看到 AI 一个个字往外蹦缓冲区一开前端就会一直等表现就是转圈半天没输出最后超时断开或者一次性吐出一大段。所以反代 Dify 时必须关掉缓冲proxy_buffering off; proxy_cache off;如果 Dify 版本里启用了 WebSocket 相关能力还得把 WebSocket 升级头也写上proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;3.3 超时参数大模型推理很慢别用默认 60 秒Nginx 的proxy_read_timeout默认是 60 秒意思是 Nginx 两次从上游读取数据之间最多等 60 秒。请求大模型接口时模型光思考可能就要几十秒甚至更长如果你的上游是这类慢接口默认超时时间根本不够——Nginx 会主动断开连接返回 502 或 504。我一般会这样设proxy_connect_timeout 10s; proxy_send_timeout 600s; proxy_read_timeout 600s;connect_timeout保持短一些因为连接不上这件事应该快速暴露而不是让用户挂在那里等但读写超时给足给大模型推理留出时间。把上面这些凑一起一份能用的反代 Dify 的最小配置大概长这样server { listen 80; server_name dify.example.com; location / { proxy_pass http://127.0.0.1:80; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_buffering off; proxy_cache off; proxy_connect_timeout 10s; proxy_send_timeout 600s; proxy_read_timeout 600s; } # 如果需要可以加 /api 的独立 upstream 配置 }这里留了一个小坑给你如果 Dify 自带 Nginx 使用的是127.0.0.1:80:80这种绑定方式外面用公网 IP 直接访问 80 是进不去的但你外层 Nginx 反代的是http://127.0.0.1:80走的是本机回环完全没问题。这也是我认为最安全的组合内部服务不直接暴露到公网所有流量都从外层 Nginx 进来。4. 127.0.0.1 在同一台机器上其实有好几个世界4.1 localhost 的视角问题容器内外不是一个世界很多 502 的根因是对127.0.0.1的理解出了偏差。你在一台机器上装了 Docker这台机器其实有多个空间宿主机空间、每个容器空间。每个空间里都有自己的127.0.0.1但它们是彼此隔离的。你可以这样理解每个独立空间都像一栋楼里的一间房每间房里都有编号001的床位。宿主机的001和容器里的001完全不是同一个床位。所以我在排查时一定会先确认一个问题这个配置里写的 127.0.0.1是在谁的世界里如果外层 Nginx 是宿主机上的进程配置里写127.0.0.1:80那它连接的是宿主机的 80 端口这是对的。如果外层 Nginx 在 Docker 容器里配置里写127.0.0.1:80它连接的是 Nginx 容器自己的 80 端口而那里什么都没有这个错误防不胜防。4.2 用命令验证哪个世界里的 127.0.0.1当你怀疑是这种视角问题时最好的办法是进入对应的世界去验证。先在宿主机上测试curl -I http://127.0.0.1:80再进入外层 Nginx 容器内部测试docker exec -it 你的外层nginx容器名 bash curl -I http://127.0.0.1:80第一次能通、第二次失败问题就定位到了外层 Nginx 容器里根本没有 80 端口服务。两种解决办法一是把proxy_pass改成宿主机在 Docker 网络中的地址。一般可以用docker network inspect bridge查看宿主机在 Docker 网关的 IP常见是172.17.0.1然后写成proxy_pass http://172.17.0.1:80;二是让外层 Nginx 直接用宿主机网络模式运行network_mode: host这样它里面的127.0.0.1和宿主机是同一个世界配置就不用改。但 host 网络模式在端口管理上不够灵活生产环境要谨慎。还有个更直接的办法用docker inspect查出 Dify 自带 Nginx 容器的实际 IPdocker inspect --format{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}} dify-nginx-1把它填到proxy_pass里。缺点是这个 IP 在 Docker 网络重建后可能变化万一容器重建要记得同步更新。4.3 延伸Dify 内部 API 报 502 的127.0.0.1歧义排查 Nginx 反向代理时经常有人顺手把 Dify 应用内部报的错也一起贴出来。比如下面这类报错unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses在 Windows 上用 VSCode 的 REST Client 调试时还可能看到{error: urlopen error [winerror 10061] 由于目标计算机积极拒绝无法连接。}这两个报错看起来像 Nginx 问题但很多时候根本不是外层 Nginx 造成的而是 Dify 内部的某个服务或插件在尝试连接127.0.0.1:15721这个端口时失败了。15721 这类端口往往对应 Dify 内部的插件网关或本地代理组件。出现这种报错时要按容器视角去查而不是在宿主机上敲curl 127.0.0.1:15721因为你真正该验证的是 Dify 某个容器内部能否访问这个端口。排查动作是# 进入发起请求的容器 docker exec -it dify-api-1 bash apt-get update apt-get install -y curl # 如果容器里没 curl curl -v http://127.0.0.1:15721/v1/responses如果容器内访问不了再去查对应的插件容器是否存活、版本是否和 Dify 主程序匹配。Dify 大版本更新比如 1.17.x 这一代插件架构调整很大后插件容器没跟着升级或者插件 daemon 监听端口变了就会出现这种看起来是反代问题、其实是组件失联的 502。排查思路始终是一样的先问自己这个请求是从哪里发出来的它连的 127.0.0.1 属于哪个世界。5. 隐性原因资源瓶颈和版本升级这两个大坑5.1 Docker 容器反复重启导致的间接 502有一类 502 藏得很深Nginx 配置全对、网络也没问题但 Dify 后端容器因为内存不足被内核杀掉或者因为健康检查失败在反复重启导致 Nginx 连上游时正好赶上服务不可用的空窗期。排查时要看两个地方。一个是容器重启次数docker ps -a --format table {{.Names}}\t{{.Status}}另一个是内核日志里的 OOM 记录dmesg | grep -i -E oom|killed | tail -n 50如果你用的是 1C2G 这种小内存 VPS 跑 Dify 全家桶内存超卖是家常便饭。api容器一被 OOM killer 干掉外层 Nginx 立刻 502。这时改 Nginx 配置没有意义真正要做的是给服务器加内存或者关掉用不上的组件、调低worker并发数、给 Docker 设置内存限制等。5.2 Dify 版本升级、离线部署带来的配置漂移还有一类 502 是昨天还好好的升级完就跪了。Dify 的.env配置里包含端口映射、服务名、健康检查路径等信息大版本升级时有些配置是可以正常沿用但插件架构或默认端口可能会变。升级后如果没重新执行docker compose up -d来重建受影响的容器就会出现新旧服务端口不一致进而 502。类似的坑也出现在离线部署场景。比如你在内网环境如银河麒麟或 CentOS 离线环境编译安装 Nginx依赖没装齐导致编译出来的 Nginx 行为异常或者 Nginx 以 root 之外的用户运行但没权限绑定 80 端口这些间接因素都可能让反代不工作。遇到这类情况先跑一下nginx -t看配置是否正常再用ps aux | grep nginx看 master 和 worker 进程是否都在。如果 worker 进程起不来日志会写在 error.log 里别蒙头改配置。5.3 加了 HTTPS 后回调地址异常导致的假 502有些 502 严格来说不是 502但使用者看到的也是网关错误。当你在外层 Nginx 终结 HTTPS把请求转发给 Dify 自带 Nginx 时如果没把原始协议头透传过去Dify 生成的页面内回调链接会依然使用http://导致浏览器去访问一个无法到达的 HTTP 地址表现和打不开网关错误很相似。反代配置里务必带上proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;X-Forwarded-Proto是告诉 Dify 的 Nginx 用户原始请求是 https这样生成的重定向和静态资源引用才不会退回 http。6. 修复之后验证步骤和维护建议6.1 配置改完别直接 reload先测再切每次改完 Nginx 配置我会养成一个习惯先用nginx -t做语法检查。这一步能拦截掉 90% 以上手误比如少了分号、大括号不匹配、proxy_pass地址格式错误。sudo nginx -t sudo nginx -s reloadnginx -s reload是平滑重载不会中断现有的连接所以在生产上改配置是安全的。但我要强调一点不要一边改一边频繁 reload。改配置前先确认你的修改是对的否则每次 reload 都会让 Nginx 重新加载一次调试过程中更容易把自己绕晕。6.2 从浏览器开发者工具验证故障层配置生效后我通常会用浏览器开发者工具做一次完整的链路验证而不是只看页面能不能打开。打开 Network 面板刷新页面看所有请求的列表。重点观察两类请求一类是document类型的页面请求另一类是 XHR/Fetch 类型的 API 请求。如果页面能开但 API 请求有 502说明外层 Nginx 的流量转发没问题问题出在内层 Nginx 到 api 容器的转发或者 api 容器自身异常。如果页面本身都是 502那大概率还是外层 Nginx 到 Dify 自带 Nginx 这一段不通。用这个办法能快速区分是整条链路断还是部分路由断排障效率会高很多。6.3 我自己的维护习惯三件套轮询脚本最后分享一个让我少踩很多坑的维护习惯。因为 Dify 这类服务在重装、升级后非常容易因为端口变化或容器没启动而出问题我现在会在服务器上放一个小脚本每次部署完或者定期跑一次检查三件套#!/bin/bash echo 1. 容器状态 docker compose -f /path/to/dify/docker/docker-compose.yaml ps --format table {{.Name}}\t{{.Status}} echo 2. 端口监听 ss -lntp | grep -E :80|:443|:5001 || true echo 3. 健康探测 curl -s -o /dev/null -w dify_http_80 %{http_code}\n http://127.0.0.1:80 curl -s -o /dev/null -w api_health_5001 %{http_code}\n http://127.0.0.1:5001/health一眼就能看出当前服务的健康水位。遇到 502 的时候先跑这个脚本确认第三项输出的是200还是502排障的起点就清晰了。Nginx 反代 Dify 的排障说到底就是一层一层地确认浏览器到外层 Nginx、外层 Nginx 到 Dify 自带 Nginx、Dify 自带 Nginx 到 web/api 容器。每层用curl打一下就能看到断点在哪。你按这个思路走一遍绝大多数 502 都能在十分钟内定位。以后如果遇到 Dify 容器没起、端口被占、安全组不放行这类问题也别忘了回来看一眼这篇大概率能在对应小节里找到答案。