502 Bad Gateway 错误说明 Nginx 与上游服务通信失败，需聚焦 proxy_pass 连通性、协议合规性及响应有效性：直连验证后端监听与响应、核对 proxy_pass 地址/斜杠/Host 头/SSL 配置、调整超时与缓冲区参数，并依据 error.log 报错关键词精准定位。
502 Bad Gateway 错误出现在使用 proxy_pass 时，说明 Nginx 成功接收到客户端请求，但在把请求转给后端时失败了——不是 Nginx 自己挂了，而是它和上游“沟通失败”。排查要聚焦在 proxy_pass 这一跳的连通性、协议合规性、响应有效性上。
确认后端真实可连、可响应
别只看进程是否运行，要看它是否真在监听且能返回合法 HTTP 响应：
- 用
curl -v http://127.0.0.1:端口/health直连后端地址（注意：必须和proxy_pass后写的地址完全一致），检查是否返回200和完整响应头 - 执行
ss -tuln | grep :端口，确认监听的是0.0.0.0:端口或127.0.0.1:端口，而非::1:端口（IPv6 回环）或特定 IP（如192.168.1.100:端口） - 查后端日志（如 Node.js 的 stdout、PHP-FPM 的
error.log），看是否有连接被拒绝、超时中断或响应截断记录 - 若用 Docker，确认容器已启动且端口映射正确：
docker ps看 STATUS，docker logs 容器名看启动输出
检查 proxy\_pass 地址与路径转发逻辑
proxy_pass 写错一个斜杠、少一个协议、漏一个域名，都可能让后端收不到预期请求：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 确保地址含协议：HTTP 后端写
http://backend，HTTPS 后端必须写https://backend，不能省略 - 注意尾部斜杠规则：
location /api/ { proxy_pass http://backend; }会把/api/user转为/api/user；而proxy_pass http://backend/;会把/api/user剪成/user - 如果后端依赖 Host 头做路由（如多租户 SaaS），不要用
$host，应写死：proxy_set_header Host api.example.com; - 反代 HTTPS 后端时，必须加：
proxy_ssl_server_name on;，否则 TLS 握手失败直接 502
验证超时与缓冲区是否匹配后端行为
后端处理慢、返回头大、响应体长，Nginx 默认值很容易撑不住：
- 设
proxy_connect_timeout 60s;防止后端启动慢或网络抖动导致连接失败 - 设
proxy_read_timeout 120s;（普通 API）或更高（如86400用于 WebSocket），确保大于后端最长处理时间 - 若后端返回头超过 4KB（比如带大量 Cookie 或自定义 header），调大
proxy_buffer_size 16k; - 若响应体较大（如文件下载、JSON 列表），增加缓冲：
proxy_buffers 8 16k;和proxy_busy_buffers_size 32k;
从 Nginx 错误日志定位具体失败环节
打开 /var/log/nginx/error.log，重点关注带关键词的报错行：
-
connect() failed (111: Connection refused)→ 后端没监听该地址端口 -
upstream timed out (110: Connection timed out)→ 连接建立成功但读响应超时，优先调proxy_read_timeout -
SSL_do_handshake() failed→ HTTPS 反代缺proxy_ssl_server_name on;或证书不匹配 -
upstream sent too big header→ 缓冲区不足，需调大proxy_buffer_size -
no live upstreams→upstream块里所有 server 都被标记为 down，检查健康检查或 backup 配置
