使用 Codex 修改后端接口时，经常会遇到一种很典型的问题：
本地调试完全正常，一部署到服务器就开始出现 502 或 504。
常见表现包括：
localhost访问接口正常；- 服务日志看起来也已经启动；
- 通过正式域名请求却返回
502 Bad Gateway； - 有些接口立即502，有些接口等几十秒后变成504；
- Codex改过端口、Docker配置或启动方式后突然出现；
- 重启Nginx也没有解决。
这类问题很多时候不是业务代码写错了。
真正需要排查的是：
请求从代理到后端服务这一段链路到底断在哪里。
一、先区分502和504
虽然都经常出现在Nginx、Gateway这一层，但含义并不完全一样。
502 Bad Gateway
更像是：
代理想连接后端，但没有拿到正常响应。
常见原因包括：
- 后端没启动；
- 端口写错；
- Upstream配置错误；
- 服务监听地址不对；
- 容器端口没有正确暴露。
504 Gateway Timeout
更像是：
代理已经在等后端，但后端迟迟没有返回结果。
常见原因包括：
- 接口执行太慢；
- 数据库查询卡住；
- 第三方接口超时；
- Proxy Timeout设置过短。
所以先分清错误类型，排查方向会快很多。
二、第一步确认后端服务真的活着
不要只看：
服务启动成功。
应该直接在服务器上请求真实后端地址。
例如：
curl http://127.0.0.1:3000/api/health
如果这里都请求失败，就说明问题还没到Nginx。
应该先检查：
- 服务进程是否存在；
- 有没有启动报错；
- 真实监听端口是多少；
- 服务有没有启动后又退出。
如果服务器本机直连接口正常，再继续往代理层查。
三、Codex改过端口后，要检查Nginx的Upstream
例如原来后端监听：
3000
Codex后来改成：
4000
但Nginx仍然配置：
127.0.0.1:3000
这时候后端本身完全正常，正式域名仍然会502。
所以要同时确认三处：
应用实际监听端口
Nginx Upstream端口
部署配置里的端口
三者必须对应。
四、监听127.0.0.1和0.0.0.0也会影响结果
有些服务本地启动时默认监听：
127.0.0.1
在单机环境可能没有问题。
但进入Docker或某些网络环境后，其他容器可能无法访问。
如果需要从容器外或其他服务访问，通常还要确认应用是否监听：
0.0.0.0
尤其是出现：
容器内部curl正常，Nginx访问却失败
这种情况，就要重点检查监听地址和容器网络。
五、Docker里最容易把“容器端口”和“宿主机端口”搞混
例如应用在容器内部监听：
3000
Docker映射：
8080:3000
那么：
- 容器内部端口是3000；
- 宿主机访问端口可能是8080。
如果Nginx运行在宿主机，可能应该连接：
127.0.0.1:8080
如果Nginx也在同一个Docker网络中，则可能直接使用：
service-name:3000
所以不能只看：
应用代码里写的是3000。
还要确认请求从哪一层发出。
六、为什么有时不是502，而是等很久才504？
如果接口可以连上，但执行时间太长，代理就可能一直等待。
例如：
后端需要：
- 执行复杂SQL；
- 调用外部API；
- 生成大型文件；
- 等待其他服务。
接口本地直接请求可能40秒后成功。
但Nginx只允许等待30秒。
于是最终就变成：
504 Gateway Timeout。
这种情况下继续改端口没有意义。
应该检查：
接口真实耗时 + Proxy Timeout。
七、不要只想着把Timeout调大
看到504以后，最简单的办法是：
把代理超时时间从30秒改成120秒。
有时候确实有用。
但如果接口本身因为：
- 慢SQL；
- 死锁；
- 第三方接口卡死；
- 无限重试；
才一直不返回，单纯延长Timeout只是让用户多等一会。
所以更稳的顺序是：
先测接口真实耗时，再决定是优化接口，还是调整代理超时。
八、Nginx日志通常比页面报错更有用
浏览器只告诉你：
502
或者：
504
信息太少。
应该继续查看Nginx错误日志。
常见信息可能直接提示：
- connection refused；
- upstream timed out；
- no live upstreams；
- connection reset。
例如：
connection refused
通常更像端口、进程或监听问题。
而：
upstream timed out
则更偏后端执行过慢。
这比反复修改接口代码有效得多。
九、可以按这个顺序排查
Codex改完接口后，本地正常、部署502/504，可以依次确认：
第一步：服务器本机直连后端。
确认服务本身能不能访问。
第二步：确认进程和监听端口。
检查应用实际监听在哪里。
第三步：检查Nginx Upstream。
域名最终转发到了哪个地址和端口。
第四步：如果使用Docker，确认端口映射和容器网络。
不要混淆宿主机端口和容器端口。
第五步：看Nginx错误日志。
判断是连接失败还是等待超时。
第六步：测试接口真实耗时。
如果是504，再继续排查慢SQL、第三方接口和Timeout。
十、可以直接这样让Codex排查
以后遇到这类问题，可以直接告诉Codex：
请不要继续修改业务逻辑，先排查部署后的502/504。确认后端进程是否存活、实际监听地址和端口、服务器本机能否curl成功、Nginx Upstream是否与当前端口一致。如果使用Docker，检查端口映射和容器网络。再根据Nginx错误日志区分connection refused和upstream timeout，最后判断是连接问题还是接口执行过慢。
这样比直接说：
帮我修一下502。
更容易快速定位真正故障点。
最后
Codex改完接口以后，本地正常但部署后一直502/504，很多时候真正的问题不是：
接口代码不能运行。
而是：
代理和后端之间没有正确连接，或者后端没有在代理允许的时间内返回。
最有效的排查链路应该是：
服务进程 → 监听地址 → 端口 → Docker网络 → Nginx Upstream → 接口耗时 → Proxy Timeout。
先确认请求到底在哪一层断掉，再决定下一步怎么修。
这样通常比不断重写业务代码快得多。
持续更新 Codex、大模型开发与 AI 编程实战内容，更多技术内容和稳定订阅渠道欢迎搜索关注「仙逆GPT」。