Web 开发常见 HTTP 错误码解决方案：502/503/504/400/401/403

根本成因

• 代理卡死：代理线程/进程死锁或资源耗尽，无法处理新的连接。
• 不支持隧道：代理根本没实现 CONNECT 隧道功能，直接丢弃或关闭连接。

排查与解决

• 若在 CONNECT proxy:port HTTP/1.1 后就重置，说明代理不支持隧道。

1. 检查代理进程状态
   • 用 ps aux、top 观察 CPU/内存、线程数。
   • 查看是否达到最大连接数限制（如 Nginx 的 worker_connections、Squid 的 max_filedescriptors）。
2. 替换或升级代理软件
   • 使用支持隧道的版本，或切换到成熟方案（如 TinyProxy、HAProxy）。
3. 网络与防火墙
   • 确保代理服务器对外端口开放，无防火墙规则丢包。
   • 检查客户端与代理之间的网络链路。

测试代理隧道能力

curl -v -x http://proxy:port https://example.com

504 Gateway Timeout

问题表现

前端或客户端收到：

HTTP/1.1 504 Gateway Timeout

通常表示代理等待上游响应超过设定阈值。

根本成因

• 上游响应慢：后端接口处理耗时超出代理超时设置。
• 网络抖动：中间网络链路不稳定，导致延迟飙升。

排查与解决

1. 调整代理超时
   • 根据业务需求适当延长超时时间。
2. 优化后端性能
   • 数据库索引、缓存（Redis/Memcached）、异步队列。
   • 分析慢查询、CPU 瓶颈、垃圾回收等。
3. 异步或批处理
   • 对于超时敏感操作，可采用异步处理，前端快速返回，再由后台通知。
4. 多活与降级
   • 在高延迟场景下，用本地缓存或降级逻辑保证用户体验。

HAProxy 示例：

timeout connect 10s
timeout server 30s
timeout client 30s

Nginx 示例：

proxy_connect_timeout 10s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;

400 Bad Request

问题表现

代理返回 HTTP/1.1 400 Bad Request，并提示：

'代理根本不认你的 CONNECT 请求。'

根本成因

• 请求格式错误：CONNECT 方法格式不符合 HTTP/1.1 规范。
• 代理不支持 CONNECT：仅允许 GET/POST 等'简单'方法。

排查与解决

1. 确认请求格式
   • 确保符合 HTTP/1.1 标准。
2. 检查代理白名单
   • 确认允许的端口和方法。
3. 升级或更换代理
   • 如老版本 Squid 可能不完全支持 TLS 隧道。
4. 使用 HTTPS 直连
   • 若业务允许，可绕过代理直连后端，或使用更现代的 HTTP/2 直连方案。

Squid 中需在配置里加：

acl SSL_ports port 443
http_access allow CONNECT SSL_ports

正确的 CONNECT 用法：

CONNECT api.example.com:443 HTTP/1.1
Host: api.example.com:443
Proxy-Authorization: Basic XXXXX

401 Unauthorized

问题表现

客户端或浏览器收到：

HTTP/1.1 401 Unauthorized

或响应头中带有 WWW-Authenticate。

根本成因

• 认证凭证缺失或无效：请求未包含或包含错误的 Authorization 头。
• Token 过期或签名错误：JWT、OAuth2 Token 已过期或无效。
• 跨域预检失败：CORS 预检请求未携带合法认证信息。

排查与解决

1. 检查 Authorization 头
   • 确认格式为：Authorization: Bearer <token> 或 Basic <credentials>。
2. 验证 Token 有效性
   • 解码 JWT，检查 exp、nbf 等字段。
   • 与认证服务同步时间，确保无时差。
3. 查看认证服务日志
   • 检查认证服务器（如 Keycloak、Auth0）返回的错误详情。
4. 配置 CORS
   • 允许跨域请求头。
5. 重试或刷新凭证
   • 对于过期 Token，可设计自动刷新机制。

在代理或应用中允许跨域 Authorization 头：

add_header Access-Control-Allow-Headers "Authorization,Content-Type";

403 Forbidden

问题表现

客户端收到：

HTTP/1.1 403 Forbidden

无论请求格式和认证凭证是否正确，仍提示权限不足。

根本成因

• 访问权限不足：用户或客户端没有访问该资源的权限。
• ACL 配置错误：代理或应用层的访问控制列表设置不当。
• CSRF 验证失败：请求未带或带错 CSRF Token。

排查与解决

1. 检查用户角色与权限
   • 后端或 IAM 系统查看用户是否在允许访问列表。
2. 验证访问控制配置
   • 检查 Nginx/Apache 等配置。
3. 检查 CSRF 配置
   • 确保表单或 AJAX 请求携带合法的 CSRF Token。
4. 文件/目录权限
   • 对静态资源，检查文件系统权限（Linux 下 chmod/chown）。
5. 日志与审计
   • 在代理和应用层启用审计日志，定位拒绝原因。

Nginx 示例：

location /admin {
  allow 192.168.1.0/24;
  deny all;
}

最佳实践与监控建议

1. 完善日志与告警
   • 在代理层与应用层分别配置日志，并接入 ELK／Prometheus＋Grafana。
2. 健康检查与自动化重试
   • 针对常见超时和网络抖动，自动重试或流量切换。
3. 容量规划与限流
   • 根据业务增长定期评估代理与后端承载能力。
4. 文档与规范
   • 团队内统一请求格式、代理使用规范，并做好培训。

通过以上完善的错误码排查与解决方案，基本涵盖了代理相关的常见 4xx/5xx 问题。从日志入手，找到根因，结合代理和后端配置，才能在复杂网络环境和高并发场景下保障服务稳定运行。