nginx长连接需协同客户端、反向代理链路与swoole协程资源三侧配置：客户端启用keep-alive并设合理超时；upstream启用keepalive并匹配后端连接池容量；禁用connection: close响应头，统一proxy_read_timeout与swoole请求超时，调大系统文件描述符限制，并配合cpu亲和性与可观测性措施保障稳定性。
要让 Nginx 长连接配置真正支撑 Hyperf + Swoole 单机高并发协程服务的稳定性，不能只设 keepalive_timeout，而需从客户端接入、反向代理链路、后端协程资源三侧协同控制。核心是避免连接错配、复用失控和资源挤占——这三类问题在协程模型下会直接引发连接堆积、协程阻塞甚至进程重启。
客户端到 Nginx 的长连接控制
这是第一道入口关。Hyperf 通常通过 HTTP 客户端（如 hyperf/http-client）发起请求，若客户端未启用 keep-alive 或超时过短，Nginx 就无法复用连接：
- 确保客户端请求头含
Connection: keep-alive，且不主动发送Connection: close - Nginx 端设置合理空闲保持时间：
keepalive_timeout 60s 60s;（响应头也同步设为 60 秒，避免客户端提前断连） - 限制单连接请求数：
keepalive_requests 1000;，防止单连接长期占用导致协程调度延迟 - 开启
tcp_nodelay on;，减少小包延迟，适配高频低延迟的协程交互场景
Nginx 到 Hyperf 后端的连接复用
Hyperf 基于 Swoole 常驻内存运行，其 TCP 连接池容量有限。Nginx 若盲目复用连接，可能超出后端承受能力：
- upstream 中必须启用
keepalive，例如：keepalive 64;（建议值 = CPU 核数 × 2～4，如 8 核配 32～64） - 强制使用 HTTP/1.1 并清空 Connection 头：
proxy_http_version 1.1;+proxy_set_header Connection ''; - 匹配 Hyperf 的连接池上限：Swoole 的
max_connection默认 10000，但实际可用连接受worker_num × max_coroutine限制；Nginx 总复用连接数（keepalive × worker_processes）应 ≤ 后端总连接池容量 × 0.7 - 若使用 HTTPS 回源，加
ssl_session_reuse on;加速 TLS 握手，避免协程卡在 handshake 阶段
规避协程环境下的典型失效点
Hyperf 的协程调度对连接状态极其敏感，以下配置失误会直接触发异常：
- 后端返回
Connection: close响应头（常见于调试模式或异常中间件），Nginx 会立即关闭复用连接 → 检查 Hyperf 全局中间件，禁用自动注入该头的行为 - Nginx
proxy_read_timeout> Hyperf 的server.settings.request_timeout→ 协程长时间挂起无响应，最终超时被 kill → 建议设为一致，如均为 30s - 未关闭 proxy_buffering（
proxy_buffering off;）处理流式响应（如 SSE、大文件下载），否则缓冲区满会导致协程阻塞 - 系统级限制不足：调大
worker_rlimit_nofile 65535;，并确认/etc/security/limits.conf中 nginx 用户的 nofile 上限 ≥ 65535
配套系统与可观测性建议
单机协程稳定性不仅靠 Nginx 配置，还需底层协同：
- 启用 CPU 亲和性：
worker_cpu_affinity auto;，避免 worker 进程跨核调度影响协程上下文缓存 - 监控真实连接复用率：用
netstat -an | grep :8080 | wc -l对比ss -s | grep "TCP:"中已建立连接数，验证复用是否生效 - 在 Hyperf 中开启
opcache.enable=1和opcache.preload，减少协程冷启动开销，配合 Nginx 长连接发挥最大吞吐 - 日志中开启
$upstream_addr和$upstream_connect_time，快速定位是建连慢还是后端处理慢
