upstream块必须定义在http上下文中,不可置于server或location内,否则报错“unknown directive upstream”;默认轮询策略无需额外参数,需配合proxy_pass引用并设置proxy_set_header传递真实客户端信息。

Upstream块必须定义在http上下文中
直接写在server块里会报错 unknown directive "upstream"。Nginx的upstream是HTTP级别的配置,只能放在http{}块内(通常在/etc/nginx/nginx.conf或/etc/nginx/conf.d/*.conf中),不能嵌套进server或location里。
常见错误是把upstream当成location里的一个指令去配,结果reload时失败。确认位置的方法:打开主配置文件,找http {开头的大括号,在它内部、server {外部加定义。
轮询是默认策略,无需额外参数
Nginx的upstream默认就是轮询(round-robin),只要不显式写least_conn或ip_hash,所有后端服务器就会按顺序逐个分发请求。
示例配置:
upstream backend {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
server 192.168.1.12:8080;
}
注意点:
-
server行末不加分号以外的符号(比如不能写server ... weight=1;却不加;) - IP和端口要确保真实可达,否则Nginx启动时不会报错,但请求会502
- 如果某台服务器宕机,Nginx默认会尝试一次后标记为失效,30秒内不再转发(可通过
fail_timeout和max_fails调)
server指令支持权重、健康检查等关键参数
轮询不是“绝对平均”,可以通过weight调整每台机器承接流量的比例。比如一台性能强的机器可以设更高权重:
upstream backend {
server 192.168.1.10:8080 weight=3;
server 192.168.1.11:8080 weight=1;
}
其他实用参数:
-
max_fails=2 fail_timeout=10s:连续2次失败后,10秒内不发请求过去 -
backup:仅当其他server都不可用时才启用(适合冷备节点) -
down:手动标记该server暂时下线(常用于维护)
注意:weight只在轮询模式下生效;ip_hash或least_conn模式下会被忽略。
server块里必须用proxy_pass引用upstream名称
定义完upstream后,得在location里用proxy_pass http://backend;(注意协议+斜杠+名称),不能写成proxy_pass http://192.168.1.10:8080;——那样就绕过负载均衡了。
典型反代配置片段:
server {
listen 80;
location / {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
容易漏的坑:
- 忘记
http://前缀,写成proxy_pass backend;会导致404或500 - 在
proxy_pass末尾加路径(如http://backend/api)会触发重写行为,轮询逻辑仍有效,但URL路径会被截断,需小心 - 没配
proxy_set_header可能导致后端日志里全是Nginx本机IP
改完记得nginx -t校验语法,再systemctl reload nginx生效。轮询效果没法靠单次请求验证,要用curl循环多次或用ab/wrk压测看后端访问分布。











