ngx_http_proxy_module 模块

翻译内容可能已经过旧。你可以通过 英文版本查看最近的更新。

ngx_http_proxy_module 模块允许传送请求到其它服务器。

location / {
    proxy_pass       http://localhost:8000;
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;
}

proxy_buffer_size 4k|8k;

设置缓冲区的大小为size。nginx从被代理的服务器读取响应时，使用该缓冲区保存响应的开始部分。这部分通常包含着一个小小的响应头。该缓冲区大小默认等于proxy_buffers指令设置的一块缓冲区的大小，但它也可以被设置得更小。

proxy_buffering on;

代理的时候，开启或关闭缓冲后端服务器的响应。

当开启缓冲时，nginx尽可能快地从被代理的服务器接收响应，再将它存入proxy_buffer_size和proxy_buffers指令设置的缓冲区中。如果响应无法整个纳入内存，那么其中一部分将存入磁盘上的临时文件。proxy_max_temp_file_size和proxy_temp_file_write_size指令可以控制临时文件的写入。

当关闭缓冲时，收到响应后，nginx立即将其同步传给客户端。nginx不会尝试从被代理的服务器读取整个请求，而是将proxy_buffer_size指令设定的大小作为一次读取的最大长度。

响应头“X-Accel-Buffering”传递“yes”或“no”可以动态地开启或关闭代理的缓冲功能。这个能力可以通过proxy_ignore_headers指令关闭。

proxy_buffers 8 4k|8k;

为每个连接设置缓冲区的数量为number，每块缓冲区的大小为size。这些缓冲区用于保存从被代理的服务器读取的响应。每块缓冲区默认等于一个内存页的大小。这个值是4K还是8K，取决于平台。

proxy_busy_buffers_size 8k|16k;

当开启缓冲响应的功能以后，在没有读到全部响应的情况下，写缓冲到达一定大小时，nginx一定会向客户端发送响应，直到缓冲小于此值。这条指令用来设置此值。同时，剩余的缓冲区可以用于接收响应，如果需要，一部分内容将缓冲到临时文件。该大小默认是proxy_buffer_size和proxy_buffers指令设置单块缓冲大小的两倍。

proxy_cache off;

指定用于页面缓存的共享内存。同一块共享内存可以在多个地方使用。off参数可以屏蔽从上层配置继承的缓存功能。

定义nginx不从缓存取响应的条件。如果至少一个字符串条件非空而且非“0”，nginx就不会从缓存中去取响应：

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

本指令可和与proxy_no_cache一起使用。

proxy_cache_key $scheme$proxy_host$request_uri;

定义如何生成缓存的键，比如

proxy_cache_key "$host$request_uri $cookie_user";

这条指令的默认值类似于下面字符串

proxy_cache_key $scheme$proxy_host$uri$is_args$args;

proxy_cache_lock off;

开启此功能时，对于相同的请求，同时只允许一个请求发往后端，并根据proxy_cache_key指令的设置在缓存中植入一个新条目。其他请求相同条目的请求将一直等待，直到缓存中出现相应的内容，或者锁在proxy_cache_lock_timeout指令设置的超时后被释放。

proxy_cache_lock_timeout 5s;

为proxy_cache_lock指令设置锁的超时。

proxy_cache_min_uses 1;

设置响应被缓存的最小请求次数。

设置缓存的路径和其他参数。缓存数据是保存在文件中的，缓存的键和文件名都是在代理URL上执行MD5的结果。levels参数定义了缓存的层次结构。比如，下面配置

proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

缓存中文件名看起来是这样的：

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

被缓存的响应首先写入一个临时文件，然后进行重命名。从0.8.9版本开始，临时文件和缓存可以放在不同的文件系统。但请注意，这将导致文件在这两个文件系统中进行拷贝，而不是廉价的重命名操作。因此，针对任何路径，都建议将缓存和proxy_temp_path指令设置的临时文件目录放在同一文件系统。

此外，所有活动的键和缓存数据相关的信息都被存放在共享内存中。共享内存通过keys_zone参数的name和size来定义。被缓存的数据如果在inactive参数指定的时间内未被访问，就会被从缓存中移除，不论它是否是刚产生的。inactive的默认值是10分钟。

特殊进程“cache manager”监控缓存的条目数量，如果超过max_size参数设置的最大值，使用LRU算法移除缓存数据。

nginx新启动后不就，特殊进程“cache loader”就被启动。该进程将文件系统上保存的过去缓存的数据的相关信息重新加载到共享内存。加载过程分多次迭代完成，每次迭代，进程只加载不多于loader_files参数指定的文件数量（默认值为100）。此外，每次迭代过程的持续时间不能超过loader_threshold参数的值（默认200毫秒）。每次迭代之间，nginx的暂停时间由loader_sleep参数指定（默认50毫秒）。

proxy_cache_use_stale off;

如果后端服务器出现状况，nginx是可以使用过期的响应缓存的。这条指令就是定义何种条件下允许开启此机制。这条指令的参数与proxy_next_upstream指令的参数相同。

此外，updating参数允许nginx在正在更新缓存的情况下使用过期的缓存作为响应。这样做可以使更新缓存数据时，访问源服务器的次数最少。

在植入新的缓存条目时，如果想使访问源服务器的次数最少，可以使用proxy_cache_lock指令。

为不同的响应状态码设置不同的缓存时间。比如，下面指令

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

设置状态码为200和302的响应的缓存时间为10分钟，状态码为404的响应的缓存时间为1分钟。

如果仅仅指定了time，

proxy_cache_valid 5m;

那么只有状态码为200、300和302的响应会被缓存。

如果使用了any参数，那么就可以缓存任何响应：

proxy_cache_valid 200 302 10m;
proxy_cache_valid 301      1h;
proxy_cache_valid any      1m;

缓存参数也可以直接在响应头中设定。这种方式的优先级高于使用这条指令设置缓存时间。“X-Accel-Expires”响应头可以以秒为单位设置响应的缓存时间，如果值为0，表示禁止缓存响应，如果值以@开始，表示自1970年1月1日以来的秒数，响应一直会被缓存到这个绝对时间点。如果不含“X-Accel-Expires”响应头，缓存参数仍可能被“Expires”或者“Cache-Control”响应头设置。如果响应头含有“Set-Cookie”，响应将不能被缓存。这些头的处理过程可以使用指令proxy_ignore_headers忽略。

proxy_connect_timeout 60s;

设置与后端服务器建立连接的超时时间。应该注意这个超时一般不可能大于75秒。

proxy_cookie_domain off;

设置“Set-Cookie”响应头中的domain属性的替换文本。假设后端服务器返回的“Set-Cookie”响应头含有属性“domain=localhost”，那么指令

proxy_cookie_domain localhost example.org;

将这个属性改写为“domain=example.org”。

domain和replacement配置字符串，以及domain属性中起始的点将被忽略。匹配过程大小写不敏感。

domain和replacement配置字符串中可以包含变量：

proxy_cookie_domain www.$host $host;

这条指令同样可以使用正则表达式。这时，domain应以“~”标志开始，且可以使用命名匹配组和位置匹配组，而replacement可以引用这些匹配组：

proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain;

可以同时定义多条proxy_cookie_domain指令：

proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;

off参数可以取消当前配置级别的所有proxy_cookie_domain指令：

proxy_cookie_domain off;
proxy_cookie_domain localhost example.org;
proxy_cookie_domain www.example.org example.org;

proxy_cookie_path off;

设置“Set-Cookie”响应头中的path属性的替换文本。假设后端服务器返回的“Set-Cookie”响应头含有属性“path=/two/some/uri/”，那么指令

proxy_cookie_path /two/ /;

将这个属性改写为“path=/some/uri/”。

path和replacement配置字符串可以包含变量：

proxy_cookie_path $uri /some$uri;

这条指令同样可以使用正则表达式。如果使用大小写敏感的匹配，path应以“~”标志开始，如果使用大小写不敏感的匹配，path应以“~*”标志开始。path可以使用命名匹配组和位置匹配组，replacement可以引用这些匹配组：

proxy_cookie_path ~*^/user/([^/]+) /u/$1;

可以同时定义多条proxy_cookie_path指令：

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;

off参数可以取消当前配置级别的所有proxy_cookie_path指令：

proxy_cookie_path off;
proxy_cookie_path /two/ /;
proxy_cookie_path ~*^/user/([^/]+) /u/$1;

nginx默认不会将“Date”、“Server”、“X-Pad”，和“X-Accel-...”响应头发送给客户端。proxy_hide_header指令则可以设置额外的响应头，这些响应头也不会发送给客户端。相反的，如果希望允许传递某些响应头给客户端，可以使用proxy_pass_header指令。

proxy_http_version 1.0;

设置代理使用的HTTP协议版本。默认使用的版本是1.0，而1.1版本则推荐在使用keepalive连接时一起使用。

proxy_ignore_client_abort off;

决定当客户端在响应传输完成前就关闭连接时，nginx是否应关闭后端连接。

不处理后端服务器返回的指定响应头。下面的响应头可以被设置：“X-Accel-Redirect”，“X-Accel-Expires”，“X-Accel-Limit-Rate” (1.1.6)，“X-Accel-Buffering” (1.1.6)，“X-Accel-Charset” (1.1.6)，“Expires”，“Cache-Control”，和“Set-Cookie” (0.8.44)。

如果不被取消，这些头部的处理可能产生下面结果：