本篇文章主要讲ngx_http_upstream_module模块下各指令的使用方法。
1. upstream 上游服务器组/集群
Syntax: upstream name { ... }
Default: ---
Context: http
upstream指令定义了一个上游服务器组/集群，便于反向代理中的proxy_pass使用。服务器可以监听不同的端口。此外，监听 TCP 和 UNIX-domain 套接字的服务器可以混合使用。
upstream dynamic {
zone upstream_dynamic 64k;
server backend1.example.com weight=5;
server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
server 192.0.2.1 max_fails=3;
server backend3.example.com resolve;
server backend4.example.com service=http resolve;
server backup1.example.com:8080 backup;
server backup2.example.com:8080 backup;
server unix:/tmp/backend3;
}
server {
location / {
proxy_pass http://dynamic;
health_check;
}
}
默认情况下，请求在服务器之间的分配采用加权循环平衡法。在下面示例中，如果一共有 7 个，那么这7个请求将按如下方式进行分配： 其中前5个请求发送到 backend1.example.com，第二个和第三个服务器各收到一个请求。如果在与某台服务器通信时发生错误，请求将被转发到Next Server，依此类推，直到所有正常运行的服务器都被尝试过。如果无法从任何一个服务器获得成功响应，客户端将收到最后一个服务器的返回响应结果。
upstream backend {
server backend1.example.com weight=5;
server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
server unix:/tmp/backend3;
server backup1.example.com backup;
}
2. server 定义服务器
Syntax: server address [parameters];
Default: ---
Context: upstream
定义服务器的地址和其他参数。address可指定为域名或 IP 地址，端口可选，或在 "unix: "前缀后指定 UNIX-domain 套接字路径。如果未指定端口，则使用80端口。能解析到多个IP地址的域名可同时定义多个服务器。
upstream backend {
server backend1.example.com weight=5;
server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
server unix:/tmp/backend3;
}
该指令还可配置以下几个可选参数：
- weight=number：设置向这台上游服务器转发的权重，默认是1。
- max_conns=number：
- max_fails=number：该选项与fail_timeout配合使用，指在fail_timeout时间段内，如果向当前的上游服务器转发失败次数超过number，则认为在当前的fail_timeout时间段内这台上游服务器不可用。max_fail默认为1，如果设置为0，表示不检查失败次数。
- fail_timeout=time：fail_timeout表示该时间段内转发失败多少次后认为上游服务器暂时不可用，用于优化反向代理功能。它与向上游服务器建立连接的超时时间、读取上游服务器的响应超时时间等完全无关。默认为10s。
- backup：在使用ip_hash配置项时它是无效的。表示所在的上游服务器只是备份服务器，只有在所有的非备份上游服务器都失效后，才会向所在的上游服务器转发请求。
- down：表示所有的上游服务器永久下线，只在使用ip_hash配置项时才有用。
- resolve：
- route=string：
- service=name：
- slow_start=time：
- drain：
3. zone
Syntax: zone name [size];
Default: ---
Context: upstream
This directive appeared in version 1.9.0.
4. state
Syntax: state file;
Default: ---
Context: upstream
This directive appeared in version 1.9.7.
5. hash
Syntax: hash key [consistent];
Default: ---
Context: upstream
This directive appeared in version 1.7.2.
6. ip_hash
Syntax: ip_hash;
Default: ---
Context: upstream
ip_hash是某个用户的请求始终落在固定的一台上游服务器上。它根据用户端的ip计算出一个key，将key按照upstream集群里的上游服务器数量进行取模，然后以取模后的结果把请求转发到相应的上游服务器中，这样确保了同一个客户端的请求只会转发到指定的上游服务器中。
ip_hash与weight(权重)配置不可同时使用。如果upstream中一台服务器不能使用时，不能直接删除，而是使用down标识，来确保转发策略的一惯性。
upstream backend {
ip_hash;
server backend1.example.com;
server backend2.example.com;
server backend3.example.com down;
server backend4.example.com;
}
7. keepalive
Syntax: keepalive connections;
Default: ---
Context: upstream
This directive appeared in version 1.1.4.
8. keepalive_requests
Syntax: keepalive_requests number;
Default: keepalive_requests 1000;
Context: upstream
This directive appeared in version 1.15.3.
9. keepalive_time
Syntax: keepalive_time time;
Default: keepalive_time 1h;
Context: upstream
This directive appeared in version 1.19.10.
10. keepalive_timeout
Syntax: keepalive_timeout timeout;
Default: keepalive_timeout 60s;
Context: upstream
This directive appeared in version 1.15.3.
11. ntlm
Syntax: ntlm;
Default: ---
Context: upstream
This directive appeared in version 1.9.2.
12. least_conn
Syntax: least_conn;
Default: ---
Context: upstream
This directive appeared in versions 1.3.1 and 1.2.2.
13. least_time
Syntax: least_time header | last_byte [inflight];
Default: ---
Context: upstream
This directive appeared in version 1.7.10.
14. queue
Syntax: queue number [timeout=time];
Default: ---
Context: upstream
This directive appeared in version 1.5.12.
15. random
Syntax: random [two [method]];
Default: ---
Context: upstream
This directive appeared in version 1.15.1.
16. resolver
Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: ---
Context: upstream
This directive appeared in version 1.17.5.
17. resolver_timeout
Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
This directive appeared in version 1.17.5.
18. sticky
Syntax: sticky cookie name [expires=time] [domain=domain] [httponly] [samesite=strict|lax|none|$variable] [secure] [path=path];
sticky route $variable ...;
sticky learn create=variable lookup=variable zone=name:size [timeout=time] [header] [sync];
Default: ---
Context: upstream
This directive appeared in version 1.5.7.
19. sticky_cookie_insert
Syntax: sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default: ---
Context: upstream