Nginx反向代理Hyperf的核心是将HTTP/HTTPS请求转发至Swoole监听的127.0.0.1:9501，正确透传X-Forwarded-*头及协议信息，并配合Hyperf的TrustProxies中间件识别真实客户端IP与HTTPS协议。
单机用 Nginx 反向代理 Hyperf 服务，核心是让 Nginx 接收外部 HTTP 请求，再转发给 Hyperf 启动的 Swoole TCP 服务（默认监听 127.0.0.1:9501），同时正确透传请求头、协议、客户端真实 IP 等关键信息。
基础反向代理配置（HTTP）
确保 Hyperf 已启动（如执行 php bin/hyperf.php start），默认监听 127.0.0.1:9501。Nginx 配置示例如下：
- 在
/etc/nginx/conf.d/hyperf.conf中写入：
upstream hyperf_backend {
server 127.0.0.1:9501;
keepalive 16;
}
server {
listen 80;
server_name api.example.com;
location / {
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://hyperf_backend;
proxy_redirect off;
}
}
-
upstream块定义后端服务地址；keepalive提升长连接复用效率 -
proxy_http_version 1.1和Connection ''是必须项，否则 Swoole 可能无法正确处理 Keep-Alive -
X-Forwarded-*系列头用于在 Hyperf 中获取真实客户端信息（需在 Hyperf 的中间件或配置中启用信任代理）
HTTPS 支持与 SSL 终止
若需 HTTPS 访问，在 server 块中启用 SSL 并指定证书路径：
- 修改监听为
listen 443 ssl http2;，并添加：
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
- 建议同时加一个 80 → 443 的强制跳转 server 块：
server {
listen 80;
server_name api.example.com;
return 301 https://$server_name$request_uri;
}
Hyperf 侧适配要点
Nginx 仅做转发，Hyperf 需主动识别代理头才能正确生成 URL、判断协议、记录真实 IP：
- 在
config/autoload/server.php中确认settings['enable_static_handler'] = false（静态资源应由 Nginx 处理） - 在
config/autoload/middlewares.php中注册Hyperf\HttpServer\Middleware\TrustProxiesMiddleware::class - 配置
config/autoload/trust_proxies.php，设置允许的代理网段（如['127.0.0.1']） - 验证是否生效：在控制器中打印
$request->getUri()->getScheme()和$request->getHeaderLine('x-forwarded-for')，应返回https和真实客户端 IP
常见问题排查提示
-
502 Bad Gateway：检查 Hyperf 是否运行、端口是否被占用、防火墙是否放行
9501（本地转发通常无需开放） -
URL 协议错误（http 而非 https）：确认 Nginx 传了
X-Forwarded-Proto，且 Hyperf 启用了 TrustProxies 中间件 -
POST 数据为空或超时：检查
client_max_body_size（Nginx 默认 1MB），按需在 server 或 location 块中设置，如client_max_body_size 20M; - WebSocket 连接失败：若需支持 ws/wss，location 需额外配置升级头：
location /ws {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_pass http://hyperf_backend;
}
