nginx单机负载均衡搭配多实例hyperf部署，本质是通过本机不同端口运行多个hyperf进程，由nginx反向代理实现进程级隔离与简单负载分发，适用于测试、中小型业务或资源受限场景。
Nginx负载均衡搭配单机多实例Hyperf部署，本质是用一台物理/虚拟机跑多个Hyperf进程（不同端口），再由本机Nginx反向代理+负载分发。这种方式适合测试、中小型业务或资源受限环境，既避免跨机器网络开销，又能实现进程级隔离与简单负载能力。
一、Hyperf多实例部署要点
Hyperf默认监听 0.0.0.0:9501，要启动多个实例，必须指定不同端口和独立的运行时目录（避免PID、日志、协程内存冲突）：
- 实例1：
bin/hyperf.php start --port=9501 --pid-file=/tmp/hyperf-1.pid --log-dir=/var/log/hyperf-1/ - 实例2：
bin/hyperf.php start --port=9502 --pid-file=/tmp/hyperf-2.pid --log-dir=/var/log/hyperf-2/ - 实例3：
bin/hyperf.php start --port=9503 --pid-file=/tmp/hyperf-3.pid --log-dir=/var/log/hyperf-3/
✅ 关键细节：
- 所有实例共用同一份代码，但需确保
.env中数据库连接、Redis等配置支持并发访问（如连接池大小充足）；- Supervisor管理时，每个
[program]段必须设置唯一process_name和numprocs=1，避免自动扩缩容干扰；- 推荐用
--daemon=false启动（交由Supervisor托管），禁用--reload（热重载在多实例下易冲突）。
二、Nginx upstream配置（单机负载）
在 /etc/nginx/conf.d/hyperf-balancer.conf 中定义：
upstream hyperf_cluster {
server 127.0.0.1:9501 weight=3 max_fails=3 fail_timeout=30s;
server 127.0.0.1:9502 weight=2 max_fails=3 fail_timeout=30s;
server 127.0.0.1:9503 weight=1 max_fails=3 fail_timeout=30s;
# 可加 backup：server 127.0.0.1:9504 backup;
}
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://hyperf_cluster;
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_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_connect_timeout 10s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
}
}
✅ 注意事项：
weight值反映各实例处理能力（如CPU核数差异），非必须相等；max_fails/fail_timeout启用被动健康检查——某端口连续失败3次，30秒内不再转发请求；- 若Hyperf启用了WebSocket，必须保留
Upgrade和Connection头，否则握手失败。
三、Supervisor进程守护配置示例
每个Hyperf实例对应一个独立program段（以实例1为例）：
[program:hyperf-1] command=/usr/bin/php /www/wwwroot/hyperf-project/bin/hyperf.php start --port=9501 --pid-file=/tmp/hyperf-1.pid directory=/www/wwwroot/hyperf-project autostart=true autorestart=true startsecs=5 user=www redirect_stderr=true stdout_logfile=/var/log/supervisor/hyperf-1.log stderr_logfile=/var/log/supervisor/hyperf-1.err.log
✅ 操作建议：
- 所有实例使用相同用户（如
www），避免权限问题；startsecs设为5秒以上，确保Hyperf完全初始化后再判定启动成功；- 日志路径需提前创建并赋权：
mkdir -p /var/log/supervisor && chown www:www /var/log/supervisor
四、验证与调优提示
- 检查Nginx配置：
nginx -t→systemctl reload nginx - 查看Supervisor状态：
supervisorctl status，确认全部RUNNING - 测试负载分发：用
curl -H "Host: api.example.com" http://localhost/health多次，观察响应头X-Powered-By或日志中端口号变化 - 若出现
502 Bad Gateway：优先排查Hyperf进程是否真在监听、防火墙是否拦截本地端口、SELinux是否限制socket绑定
不复杂但容易忽略端口冲突和日志隔离。
