Nginx日志是排查Hyperf部署异常的首要依据，可直接反映请求抵达情况、拒绝原因、超时位置及转发失败细节；重点分析error.log中的连接拒绝、超时、重置等错误，并结合access.log与Hyperf日志通过统一request_id实现端到端追踪。
单机 Nginx 日志是排查 Hyperf 部署访问异常的第一道“门”。它不经过 PHP 层，能直接反映请求是否抵达服务器、被拒绝原因、超时位置或转发失败细节——尤其当 Hyperf 本身没打日志、页面空白或 502/504 时，Nginx 日志往往藏着关键线索。
Nginx 错误日志定位真实拦截点
Nginx 错误日志（通常是 /var/log/nginx/error.log）记录连接拒绝、上游不可达、超时、权限错误等底层问题。重点看 timestamp 最近的 ERROR 或 CRIT 级别行：
- 出现 "connect() failed (111: Connection refused)"：说明 Nginx 尝试连接 Hyperf 的 Swoole 服务（如 9501 端口）失败——检查 Hyperf 是否已启动、端口是否监听（
ss -tuln | grep 9501）、防火墙是否放行 - 出现 "upstream timed out (110: Connection timed out)"：Nginx 等待 Hyperf 响应超时，常见于 Swoole Worker 卡死、协程阻塞或 PHP 死循环；需结合
hyperf.log和dmesg排查内存或 OOM - 出现 "recv() failed (104: Connection reset by peer)"：Hyperf 进程在处理中意外退出（如段错误、被 kill），检查
systemctl status hyperf.service和journalctl -u hyperf.service
访问日志确认请求是否真正到达Hyperf
打开 Nginx 访问日志（如 /var/log/nginx/access.log），用 tail -f 实时观察请求流转：
- 如果请求在 access.log 中有记录，但 Hyperf 的
runtime/logs/hyperf.log完全无对应时间戳日志 → 请求未进入 Hyperf，问题在 Nginx 配置（如 location 匹配错误、proxy_pass 地址写错、缺少 proxy_set_header） - 如果 access.log 中状态码是 502 Bad Gateway，且 error.log 显示 upstream connect failed → Hyperf 服务未运行或端口不通
- 如果 access.log 中状态码是 499 Client Closed Request：客户端主动断开（如浏览器取消请求、前端超时），非服务端问题，但可能暴露接口响应过慢
比对Nginx与Hyperf日志时间戳和请求ID
确保 Nginx 和 Hyperf 日志使用统一时间源（建议启用 log_format 中的 $time_iso8601），并让 Hyperf 在响应头注入 X-Request-ID（通过中间件设置），再在 Nginx access_log 中加入 $http_x_request_id：
log_format main '$remote_addr - $remote_user [$time_iso8601] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_request_id"';
这样就能用同一个 request_id 串起 Nginx access log → Nginx error log → Hyperf hyperf.log → 数据库慢查询日志，实现端到端追踪。
检查Nginx代理配置是否适配Swoole长连接
Hyperf 基于 Swoole，本质是常驻进程，Nginx 必须正确代理 HTTP/1.1 并保持连接复用，否则易触发 502 或性能下降。关键配置项必须存在：
- proxy_http_version 1.1;（不能是 1.0）
- proxy_set_header Connection '';（清空 Connection 头，避免 close 干扰 keepalive）
- proxy_set_header Host $host; 和 proxy_set_header X-Real-IP $remote_addr;（确保 Hyperf 能获取真实客户端信息）
- proxy_buffering off; 可选，若接口返回流式内容（如 SSE、大文件下载），需关闭缓冲防止阻塞
