开发排障笔记

深浅主题

反向代理 502/504 ​

问题现象 ​

代理返回 502 Bad Gateway 或 504 Gateway Timeout，但后端进程看似正常；不同代理的错误映射可能不同。

适用环境 ​

Caddy 2 或 Nginx、Docker 内网、HTTP 后端。

本文是可复用的排障示例，不代表某次个人生产事故。命令中的名称、账号和数据均为示例，执行前请替换为已确认的目标。

复现或诊断步骤 ​

  1. 记录故障时间、请求 ID 和代理日志中的具体错误，区分拒绝连接、DNS 失败、TLS 失败和读取超时。
  2. 从代理所在容器或网络内直连后端健康路径，而不只从宿主机测试。
  3. 查看后端监听地址、端口、容器网络、线程池与慢请求日志，分段比较延迟。

原因分析 ​

502 通常指代理无法获得有效上游响应，504 通常指等待上游超时，具体以日志为准。容器内 localhost 指该容器本身；后端只绑定 127.0.0.1 时其他容器无法连接。长查询、连接池等待也会表现为代理超时。

修复示例 ​

caddyfile
app.example.com {
  reverse_proxy backend:8080 {
    transport http {
      dial_timeout 3s
      response_header_timeout 30s
    }
  }
}
# backend 必须与代理共享可解析服务名的网络

按错误修复地址、服务名、监听或下游瓶颈。超时应由端到端预算决定，长导出更适合异步任务。修改前备份配置并 validate，再热加载；失败恢复原配置 reload。不要为调试而将数据库或内部后端直接发布公网。

验证方法 ​

检查健康路径与真实业务请求，模拟后端停机和慢响应，确认返回错误可区分、日志可关联。恢复后检查连接池及队列，不只检查代理是否返回 200。

常见误区 ​

增加超时不能解决连接拒绝。把 upstream 改成宿主机公网 IP 可能引入额外暴露和回环链路；curl 首页成功也不证明所有接口健康。

官方参考链接 ​

相关分类：部署与运维 · 全部笔记