Nginx - HttpUpstreamModule

英文文档地址：http://wiki.nginx.org/HttpUpstreamModule

摘要（Synopsis）

这个模块通过后端服务器提供简单的负载均衡（轮询调度和客户端IP哈希）

例如：

upstream backend  {
  server backend1.example.com weight=5;
  server backend2.example.com:8080;
  server unix:/tmp/backend3;
}
 
server {
  location / {
    proxy_pass  http://backend;
  }
}

指令（Directives）

ip_hash

语法: ip_hash

缺省值: none

语境: upstream

这个指令使请求按客户端的IP地址分配到不同upstream中。

哈希算法的key是客户端的C类网络地址。这个算法保证同一个客户端的请求总是先被分配给同一个后端服务器，但是如果要分配过去的后端服务器被认为是无效的，那么客户端的请求就会分配给其他后端服务器。这就保证了同一个客户端每次的请求有很大的概率都会被分配到同一个后端服务器。

不能在使用ip_hash规则的同时为服务器指定权值。如果在某些情况下要移除某个服务器，你必须把这个服务器标记为“down”。

例如：

upstream backend {
  ip_hash;
  server   backend1.example.com;
  server   backend2.example.com;
  server   backend3.example.com  down;
  server   backend4.example.com;
}

server

语法: server name [parameters]

缺省值: none

语境: upstream

这个指令指定后端服务器的名字以及各种参数。可以使用域名、IP地址、端口或者unix的socket作为服务器名字，如果域名指向多个地址，那么这些地址都会被使用。

• weight = NUMBER - 为服务器设置权值，如果没设置默认为1.
• max_fails = NUMBER - 指定在fail_timeout时间内，尝试去连接服务器的最大失败次数（即如果尝试连接服务器失败，那么次数加1，直到失败数达到 max_fails）。当失败次数达到max_fails，nginx会认为该服务器是无效的。如果没有设置，那么默认的次数为1。如果将该值设为0，那 么就会关闭这个最大失败次数上限的检验。失败的情况定义在proxy_next_upstream 或者fastcgi_next_upstream（http的404错误次数是不会算到max_fails次数上的）
• fail_timeout = TIME - 指定在fail_timeout时间内，如果连接服务器失败次数达到max_fails，那么服务器就会被认为是无效的。同时指定当连接服务器失败次数达 到max_fails的值时，nginx认为该服务器无效的（直到有连接成功的尝试）持续时间。如果不设置这个时间，默认值为10秒。 fail_timeout这个参数跟upstream的响应时间毫无关系，不过可以使用proxy_connect_timeout 和 proxy_read_timeout来控制响应时间。
• down - 标记服务器永久下线，需跟ip_hash指令一起使用。
• backup - （0.6.7及以上版本）标记服务器只会在所有非backup标记的服务器全部down或者忙碌的情况下才会被使用（不能和ip_hash指令一起使用）。

配置示例：

upstream  backend  {
  server   backend1.example.com    weight=5;
  server   127.0.0.1:8080          max_fails=3  fail_timeout=30s;
  server   unix:/tmp/backend3;
}

注意：如果你在upstream中指配置了一个服务器，那么nginx会将一个内部变量设为1，这就意味着nginx会忽略max_fails和fail_timeout这2个参数。

影响：如果nginx不能连接到upstream中的那个server，那么这个请求就丢失了。

解决办法：在upstream中多配置几个相同配置的服务器（即将那一个服务器的配置多复制几遍）。

 

upstream

语法: upstream name { ... }

缺省值: none

语境: http

这个指令描述了一组服务器。这个指令可以用在proxy_pass指令和fastcgi_pass指令中作为一个单一的入口。upstream可以监听不同端口上的服务器，并且可以使用一个服务器同时监听TCP和Unix的socket。

每个服务器可以指定不同的权值，如果没指定，默认情况下权值为1.

配置示例：

upstream backend {
  server backend1.example.com weight=5;
  server 127.0.0.1:8080       max_fails=3  fail_timeout=30s;
  server unix:/tmp/backend3;
}

请求是根据服务器的权值，按轮询调度算法被分配到不同的服务器中。

例如，按上述示例配置，每收到7个请求：5个请求会分配到backend1.example.com，另外2个分别分配到第2个和第3个服务器。如果一个服务器在尝试处理一个请求的过程中发生了错误，那么这个请求会传递给下一个服务器，如此，直到所有的服务器都尝试遍。如果所有的服务器都没能给出成功的响应，那么客户端就会得到最后一个服务器的处理结果。

 

变量（Variables）

从0.5.18版本开始，可以通过log_module模块的变量来定制日志的格式。

配置示例：

log_format timing '$remote_addr - $remote_user [$time_local]  $request '
  'upstream_response_time $upstream_response_time '
  'msec $msec request_time $request_time';
 
log_format up_head '$remote_addr - $remote_user [$time_local]  $request '
  'upstream_http_content_type $upstream_http_content_type';

$upstream_addr

upstream中处理请求的服务器的地址（ip:port or unix:socket-path）。如果处理请求的时候upstream中有多个地址是可访问的，那么这些地址以逗号和空分隔，例如：“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”。如果使用了“X-Accel-Redirect”或者error_page，有一个内部的重定向从一个服务器组到另一个组，那么这2个组的地址通过冒号和空格分隔，例如：“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”。注意空格：在定义日志格式的时候，使用引号将这个变量引起来，使日志格式解析更容易。

 

$upstream_cache_status

在0.8.3中引入了这个变量。可能的变量如下：

• MISS
• EXPIRED - expired, request was passed to backend
• UPDATING - expired, stale response was used due to proxy/fastcgi_cache_use_stale updating
• STALE - expired, stale response was used due to proxy/fastcgi_cache_use_stale
• HIT

 

$upstream_status

upstream服务器的响应状态。跟$upstream_addr变量一样，如果有多个upstream服务器地址是可访问的，那么这些值通过逗号以及带空格的冒号分隔。

 

$upstream_response_time

upstream中的服务器的响应时间，单位秒，精确到毫秒。跟$upstream_addr变量一样，如果有多个upstream服务器地址是可访问的，那么这些值通过逗号以及带空格的冒号分隔。

 

$upstream_http_$HEADER

任意的HTTP协议头，例如：

$upstream_http_host

记住如果有多个upstream服务器是可访问的，只有来自最后一个服务器的协议头可以通过这个变量得到。