Module ngx_http_proxy_module

ngx_http_proxy_module模块允许将请求传递到另一台服务器。

Example Configuration

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

Directives

Syntax:	`proxy_bind address [transparent] \| off;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在版本 0.8.22 中。

到代理服务器的传出连接源自具有可选端口(1.11.2)的指定本地 IP 地址。参数值可以包含变量(1.3.12)。特殊值off(1.3.12)取消了从以前的配置级别继承的proxy_bind指令的效果，这使系统可以自动分配本地 IP 地址和端口。

transparent参数(1.11.0)允许到代理服务器的传出连接源自 nonlocalIP 地址，例如，源自客户端的真实 IP 地址：

proxy_bind $remote_addr transparent;

为了使此参数起作用，通常必须使用superuser特权运行 nginx worker 进程。在 Linux 上，不需要(1.13.8)，就好像指定了transparent参数一样，辅助进程从主进程继承CAP_NET_RAW功能。还必须配置内核路由表以拦截来自代理服务器的网络流量。

Syntax:	`proxy_buffer_size size;`
Default:	`proxy_buffer_size 4k\|8k;`
Context:	`http` , `server` , `location`

设置用于读取从代理服务器接收到的响应的第一部分的缓冲区的size。这部分通常包含一个小的响应头。默认情况下，缓冲区大小等于一个内存页。根据平台的不同，它可以是 4K 或 8K。但是，它可以做得更小。

Syntax:	`proxy_buffering on \| off;`
Default:	`proxy_buffering on;`
Context:	`http` , `server` , `location`

启用或禁用代理服务器响应的缓冲。

启用缓冲后，nginx 会尽快从代理服务器收到响应，并将其保存到proxy_buffer_size和proxy_buffers指令设置的缓冲区中。如果整个响应都无法容纳到内存中，则可以将一部分响应保存到磁盘上的temporary file。写入临时文件由proxy_max_temp_file_size和proxy_temp_file_write_size指令控制。

禁用缓冲后，响应一收到就立即同步传递给客户端。 nginx 不会尝试从代理服务器读取整个响应。 proxy_buffer_size指令设置了 nginx 一次可以从服务器接收的最大数据大小。

也可以通过在“ X-Accel-Buffering”响应标题字段中传递“ yes”或“ no”来启用或禁用缓冲。可以使用proxy_ignore_headers指令禁用此功能。

Syntax:	`proxy_buffers number size;`
Default:	`proxy_buffers 8 4k\|8k;`
Context:	`http` , `server` , `location`

为单个连接设置用于从代理服务器读取响应的缓冲区的number和size。默认情况下，缓冲区大小等于一个内存页。根据平台的不同，它可以是 4K 或 8K。

Syntax:	`proxy_busy_buffers_size size;`
Default:	`proxy_busy_buffers_size 8k\|16k;`
Context:	`http` , `server` , `location`

启用来自代理服务器的响应buffering时，将限制在忙于向客户端发送响应而尚未完全读取响应的缓冲区总数size。同时，其余的缓冲区可用于读取响应，并在需要时将响应的一部分缓冲到临时文件中。默认情况下，size受proxy_buffer_size和proxy_buffers指令设置的两个缓冲区的大小限制。

Syntax:	`proxy_cache zone \| off;`
Default:	`proxy_cache off;`
Context:	`http` , `server` , `location`

定义用于缓存的共享内存区域。同一区域可以在多个地方使用。参数值可以包含变量(1.7.9)。 off参数禁用从先前配置级别继承的缓存。

Syntax:	`proxy_cache_background_update on \| off;`
Default:	`proxy_cache_background_update off;`
Context:	`http` , `server` , `location`

该指令出现在 1.11.10 版本中。

允许启动后台子请求以更新过期的缓存项，同时将陈旧的缓存响应返回给客户端。请注意，在更新过时的缓存响应时，有必要allow使用。

Syntax:	`proxy_cache_bypass string ...;`
Default:	—
Context:	`http` , `server` , `location`

定义不从缓存中获取响应的条件。如果字符串参数的至少一个值不为空且不等于“ 0”，那么将不会从缓存中获取响应：

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

可以与proxy_no_cache指令一起使用。

Syntax:	`proxy_cache_convert_head on \| off;`
Default:	`proxy_cache_convert_head on;`
Context:	`http` , `server` , `location`

该指令出现在 1.9.7 版中。

启用或禁用将“ HEAD”方法转换为“ GET”以进行缓存。禁用转换后，应将cache key配置为包含$request_method。

Syntax:	`proxy_cache_key string;`
Default:	`proxy_cache_key $scheme$proxy_host$request_uri;`
Context:	`http` , `server` , `location`

定义用于缓存的密钥，例如

proxy_cache_key "$host$request_uri $cookie_user";

默认情况下，指令的值接近字符串

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

Syntax:	`proxy_cache_lock on \| off;`
Default:	`proxy_cache_lock off;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.1.12 中。

启用后，一次只允许一个请求通过将请求传递到代理服务器来填充根据proxy_cache_key指令标识的新缓存元素。在proxy_cache_lock_timeout指令设置的时间之前，同一缓存元素的其他请求将 await 响应出现在缓存中，或者 await 该元素被释放的缓存锁。

Syntax:	`proxy_cache_lock_age time;`
Default:	`proxy_cache_lock_age 5s;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.8 中。

如果针对指定的time传递到代理服务器的用于填充新缓存元素的最后一个请求尚未完成，则可以再将一个请求传递给代理服务器。

Syntax:	`proxy_cache_lock_timeout time;`
Default:	`proxy_cache_lock_timeout 5s;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.1.12 中。

为proxy_cache_lock设置超时。当time过期时，请求将被传递到代理服务器，但是，响应将不会被缓存。

Note

在 1.7.8 之前，可以缓存响应。

Syntax:	`proxy_cache_max_range_offset number;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在 1.11.6 版本中。

设置字节范围请求的字节偏移量。如果范围超出偏移量，则范围请求将传递到代理服务器，并且不会缓存响应。

Syntax:	`proxy_cache_methods GET \| HEAD \| POST ...;`
Default:	`proxy_cache_methods GET HEAD;`
Context:	`http` , `server` , `location`

该指令出现在版本 0.7.59 中。

如果此伪指令中列出了客户端请求方法，则将缓存响应。尽管建议显式指定“ GET”和“ HEAD”方法，但始终将它们添加到列表中。另请参见proxy_no_cache指令。

Syntax:	`proxy_cache_min_uses number;`
Default:	`proxy_cache_min_uses 1;`
Context:	`http` , `server` , `location`

设置number请求，之后将缓存响应。

Syntax:	`proxy_cache_path path [levels=levels] [use_temp_path=on\|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on\|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];`
Default:	—
Context:	`http`

设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的文件名是对cache key应用 MD5 功能的结果。 levels参数定义缓存的层次结构级别：从 1 到 3，每个级别接受值 1 或 2.例如，在以下配置中

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

缓存中的文件名如下所示：

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

首先将缓存的响应写入临时文件，然后重命名该文件。从 0.8.9 版本开始，可以将临时文件和缓存放在不同的文件系统上。但是，请注意，在这种情况下，文件是跨两个文件系统复制的，而不是廉价的重命名操作。因此，建议对于任何给定位置，将高速缓存和保存临时文件的目录都放在同一文件系统上。临时文件的目录是根据use_temp_path参数(1.7.10)设置的。如果省略此参数或将其设置为值on，则将使用proxy_temp_path指令为给定位置设置的目录。如果该值设置为off，则临时文件将直接放置在缓存目录中。

此外，所有活动键和有关数据的信息都存储在共享存储区中，该存储区的name和size由keys_zone参数配置。一个 1 MB 的区域可以存储大约 8000 个密钥。

Note

作为commercial subscription的一部分，共享内存区域还存储扩展的缓存information，因此，需要为相同数量的键指定更大的区域大小。例如，一个 1 MB 的区域可以存储大约 4000 个密钥。

在inactive参数指定的时间内未访问的缓存数据将被从缓存中删除，无论它们是否新鲜。默认情况下，inactive设置为 10 分钟。

特殊的“高速缓存管理器”过程监视具有高速缓存的文件系统上max_size参数设置的最大高速缓存大小和min_free(1.19.1)参数设置的最小可用空间。当超出大小或没有足够的可用空间时，它将删除最近最少使用的数据。在由manager_files，manager_threshold和manager_sleep参数(1.11.5)配置的迭代中删除数据。在一次迭代中，最多删除manager_files个项目(默认为 100)。一次迭代的持续时间受manager_threshold参数的限制(默认情况下为 200 毫秒)。在迭代之间，由manager_sleep参数配置的暂停(默认为 50 毫秒)。

启动一分钟后，特殊的“缓存加载器”过程被激活。它将有关存储在文件系统上的先前缓存的数据的信息加载到缓存区域中。加载也以迭代方式完成。在一次迭代中，最多加载loader_files个项目(默认情况下为 100)。此外，一次迭代的持续时间受到loader_threshold参数的限制(默认为 200 毫秒)。在迭代之间，由loader_sleep参数配置的暂停(默认为 50 毫秒)。

此外，以下参数是我们的commercial subscription的一部分：

purger =开|关

指示是否将由缓存清除器(1.7.12)从磁盘上删除与wildcard key匹配的缓存条目。将参数设置为on(默认值为off)将激活“缓存清除器”过程，该过程将永久性地遍历所有缓存条目，并删除与通配符匹配的条目。

purger_files= number

设置一次迭代(1.7.12)期间要扫描的项目数。默认情况下，purger_files设置为 10.

purger_threshold= number

设置一次迭代的持续时间(1.7.12)。默认情况下，purger_threshold设置为 50 毫秒。

purger_sleep= number

设置迭代之间的暂停(1.7.12)。默认情况下，purger_sleep设置为 50 毫秒。

Note

在版本 1.7.3、1.7.7 和 1.11.10 中，缓存头格式已更改。升级到较新的 nginx 版本后，以前缓存的响应将被视为无效。

Syntax:	`proxy_cache_purge string ...;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在 1.5.7 版中。

定义将请求视为高速缓存清除请求的条件。如果字符串参数的至少一个值不为空且不等于“ 0”，则将删除具有相应cache key的缓存条目。通过返回 204(无内容)响应来指示成功操作的结果。

如果清除请求的cache key以星号(“ *”)结尾，则所有与通配符匹配的高速缓存条目都将从高速缓存中删除。但是，这些条目将保留在磁盘上，直到它们被删除为inactivity或被cache purger(1.7.12)处理或客户端尝试访问它们为止。

Example configuration:

proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        proxy_pass http://backend;
        proxy_cache cache_zone;
        proxy_cache_key $uri;
        proxy_cache_purge $purge_method;
    }
}

Note

此功能是我们commercial subscription的一部分。

Syntax:	`proxy_cache_revalidate on \| off;`
Default:	`proxy_cache_revalidate off;`
Context:	`http` , `server` , `location`

该指令出现在 1.5.7 版中。

使用带有“ If-Modified-Since”和“ If-None-Match”头域的条件请求，启用过期缓存项的重新验证。

Syntax:	`proxy_cache_use_stale error \| timeout \| invalid_header \| updating \| http_500 \| http_502 \| http_503 \| http_504 \| http_403 \| http_404 \| http_429 \| off ...;`
Default:	`proxy_cache_use_stale off;`
Context:	`http` , `server` , `location`

确定在哪种情况下与代理服务器通信期间可以使用陈旧的缓存响应。该指令的参数与proxy_next_upstream指令的参数匹配。

如果无法选择代理服务器来处理请求，则error参数还允许使用陈旧的缓存响应。

另外，如果当前正在更新，则updating参数允许使用陈旧的缓存响应。这样可以在更新缓存的数据时最大程度地减少对代理服务器的访问次数。

在响应过时(1.11.10)后，还可以在响应 Headers 中直接启用使用过时的缓存响应达指定的秒数。这比使用指令参数的优先级低。

如果当前正在更新“ Cache_Control”头字段的“ stale-while-revalidate”extensions，则允许使用陈旧的缓存响应。
“ Cache-Control”Headers 字段的“ stale-if-error”extensions 允许在发生错误的情况下使用过期的缓存响应。

为了在填充新的缓存元素时最大程度地减少对代理服务器的访问次数，可以使用proxy_cache_lock指令。

Syntax:	`proxy_cache_valid [code ...] time;`
Default:	—
Context:	`http` , `server` , `location`

设置不同响应代码的缓存时间。例如，以下指令

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

为代码 200 和 302 的响应设置 10 分钟的缓存，为代码 404 的响应设置 1 分钟的缓存。

如果仅指定缓存time

proxy_cache_valid 5m;

那么仅缓存 200、301 和 302 响应。

另外，可以指定any参数来缓存任何响应：

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

缓存参数也可以直接在响应头中设置。这比使用伪指令设置缓存时间具有更高的优先级。

“ X-Accel-Expires”Headers 字段以秒为单位设置响应的缓存时间。零值禁用缓存响应。如果该值以@前缀开头，则它设置自 Epoch 以来的绝对时间(以秒为单位)，可以在该绝对时间之前缓存响应。
如果标题不包括“ X-Accel-Expires”字段，则可以在标题字段“ Expires”或“ Cache-Control”中设置缓存参数。
如果 Headers 包含“ Set-Cookie”字段，则不会缓存此类响应。
如果 Headers 包含具有特殊值“ *”的“ Vary”字段，则不会缓存此类响应(1.7.7)。如果 Headers 包含带有另一个值的“ Vary”字段，则将考虑相应的请求 Headers 字段(1.7.7)来缓存此类响应。

可以使用proxy_ignore_headers指令禁用对这些响应头字段中的一个或多个的处理。

Syntax:	`proxy_connect_timeout time;`
Default:	`proxy_connect_timeout 60s;`
Context:	`http` , `server` , `location`

定义与代理服务器构建连接的超时。请注意，此超时通常不能超过 75 秒。

Syntax:	`proxy_cookie_domain off;`
`proxy_cookie_domain domain replacement;`
默认值：	`proxy_cookie_domain off;`
上下文： `http`，`server`，`location`

该指令出现在 1.1.15 版中。

设置应在代理服务器响应的“ Set-Cookie”Headers 字段的domain属性中更改的文本。假设代理服务器返回属性为“ domain=localhost”的“ Set-Cookie”头字段。指令

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;

Syntax:	`proxy_cookie_path off;`
`proxy_cookie_path path replacement;`
默认值：	`proxy_cookie_path off;`
上下文： `http`，`server`，`location`

该指令出现在 1.1.15 版中。

设置应在代理服务器响应的“ Set-Cookie”Headers 字段的path属性中更改的文本。假设代理服务器返回属性为“ path=/two/some/uri/”的“ Set-Cookie”头字段。指令

proxy_cookie_path /two/ /;

将将此属性重写为“ path=/some/uri/”。

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

proxy_cookie_path $uri /some$uri;

指令也可以使用正则表达式指定。在这种情况下，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;

Syntax:	`proxy_force_ranges on \| off;`
Default:	`proxy_force_ranges off;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.7 中。

不管代理响应中的“接受范围”字段如何，都对来自代理服务器的缓存和未缓存响应启用字节范围支持。

Syntax:	`proxy_headers_hash_bucket_size size;`
Default:	`proxy_headers_hash_bucket_size 64;`
Context:	`http` , `server` , `location`

为proxy_hide_header和proxy_set_header指令使用的哈希表设置存储区size。设置哈希表的详细信息在单独的document中提供。

Syntax:	`proxy_headers_hash_max_size size;`
Default:	`proxy_headers_hash_max_size 512;`
Context:	`http` , `server` , `location`

设置proxy_hide_header和proxy_set_header指令使用的哈希表的最大size。设置哈希表的详细信息在单独的document中提供。

Syntax:	`proxy_hide_header field;`
Default:	—
Context:	`http` , `server` , `location`

默认情况下，nginx 不会将代理服务器的响应中的 Headers 字段“日期”，“服务器”，“ X-Pad”和“ X-Accel -...”传递给客户端。 proxy_hide_header指令设置了不会传递的其他字段。相反，如果需要允许传递字段，则可以使用proxy_pass_header指令。

Syntax:	`proxy_http_version 1.0 \| 1.1;`
Default:	`proxy_http_version 1.0;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.1.4 中。

设置用于代理的 HTTP 协议版本。默认情况下，使用 1.0 版。建议将版本 1.1 与keepalive连接和NTLM authentication一起使用。

Syntax:	`proxy_ignore_client_abort on \| off;`
Default:	`proxy_ignore_client_abort off;`
Context:	`http` , `server` , `location`

确定当客户端在不 await 响应的情况下关闭连接时，是否应关闭与代理服务器的连接。

Syntax:	`proxy_ignore_headers field ...;`
Default:	—
Context:	`http` , `server` , `location`

禁用来自代理服务器的某些响应头字段的处理。可以忽略以下字段：“ 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)和“ Vary”(1.7.7)。

如果未禁用，则处理这些头字段具有以下效果：

“ X-Accel-Expires”，“ Expires”，“ Cache-Control”，“ Set-Cookie”和“ Vary”设置响应caching的参数；
“ X-Accel-Redirect”对指定的 URI 执行internal redirect；
“ X-Accel-Limit-Rate”设置rate limit用于将响应传输到客户端；
“ X-Accel-Buffering”启用或禁用响应buffering；
“ X-Accel-Charset”设置所需的响应charset。

Syntax:	`proxy_intercept_errors on \| off;`
Default:	`proxy_intercept_errors off;`
Context:	`http` , `server` , `location`

确定代码大于或等于 300 的代理响应应该传递给客户端还是被拦截并重定向到 nginx 以使用error_page指令进行处理。

Syntax:	`proxy_limit_rate rate;`
Default:	`proxy_limit_rate 0;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.7 中。

限制从代理服务器读取响应的速度。 rate以每秒字节数指定。零值禁用速率限制。该限制是根据请求设置的，因此，如果 nginx 同时打开到代理服务器的两个连接，则总速率将是指定限制的两倍。仅当启用buffering来自代理服务器的响应时，此限制才有效。

Syntax:	`proxy_max_temp_file_size size;`
Default:	`proxy_max_temp_file_size 1024m;`
Context:	`http` , `server` , `location`

如果启用了来自代理服务器的buffering响应，并且整个响应不适合proxy_buffer_size和proxy_buffers指令设置的缓冲区，则可以将一部分响应保存到临时文件中。此伪指令设置临时文件的最大size。一次写入proxy_temp_file_write_size指令设置写入临时文件的数据大小。

零值禁用对临时文件的响应的缓冲。

Note

此限制不适用于磁盘上为cached或stored的响应。

Syntax:	`proxy_method method;`
Default:	—
Context:	`http` , `server` , `location`

指定在转发到代理服务器的请求中使用的 HTTP method，而不是客户端请求中的方法。参数值可以包含变量(1.11.6)。

Syntax:	`proxy_next_upstream error \| timeout \| invalid_header \| http_500 \| http_502 \| http_503 \| http_504 \| http_403 \| http_404 \| http_429 \| non_idempotent \| off ...;`
Default:	`proxy_next_upstream error timeout;`
Context:	`http` , `server` , `location`

指定在哪种情况下将请求传递到下一个服务器：

error
- 与服务器构建连接，向服务器传递请求或读取响应头时发生错误；
timeout
- 与服务器构建连接，向服务器传递请求或读取响应 Headers 时发生超时；
invalid_header
- 服务器返回了空的或无效的响应；
http_500
- 服务器返回响应，代码为 500；
http_502
- 服务器返回响应码为 502；
http_503
- 服务器返回响应，代码为 503；
http_504
- 服务器返回代码为 504 的响应；
http_403
- 服务器返回响应，代码为 403；
http_404
- 服务器返回了代码为 404 的响应；
http_429
- 服务器返回响应，代码为 429(1.11.13)；

non_idempotent

通常，如果请求已发送到上游服务器(1.9.13)，则使用non-idempotent方法(POST，LOCK，PATCH)的请求不会传递到下一个服务器。明确启用此选项将允许重试此类请求；
off
- 禁用将请求传递到下一个服务器。

应该记住的是，只有在还没有任何内容发送给客户端的情况下，才有可能将请求传递给下一台服务器。即，如果在响应的传输过程中发生错误或超时，则无法解决该问题。

该指令还定义了与服务器通信的unsuccessful attempt。 error，timeout和invalid_header的情况始终被认为是失败的尝试，即使未在指令中指定它们也是如此。 http_500，http_502，http_503，http_504和http_429的情况只有在指令中指定时才被认为是不成功的尝试。绝不会将http_403和http_404的情况视为未成功的尝试。

将请求传递到下一个服务器可能受到尝试次数和time的限制。

Syntax:	`proxy_next_upstream_timeout time;`
Default:	`proxy_next_upstream_timeout 0;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.5 中。

限制可以将请求传递到next server的时间。 0值关闭了此限制。

Syntax:	`proxy_next_upstream_tries number;`
Default:	`proxy_next_upstream_tries 0;`
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.5 中。

限制将请求传递到next server的可能尝试次数。 0值关闭了此限制。

Syntax:	`proxy_no_cache string ...;`
Default:	—
Context:	`http` , `server` , `location`

定义不将响应保存到缓存的条件。如果字符串参数的至少一个值不为空且不等于“ 0”，则将不保存响应：

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;

可以与proxy_cache_bypass指令一起使用。

Syntax:	`proxy_pass URL;`
Default:	—
Context:	`location` , `if in location` , `limit_except`

设置代理服务器的协议和地址以及位置应映射到的可选 URI。作为协议，可以指定“ http”或“ https”。该地址可以指定为域名或 IP 地址，以及一个可选端口：

proxy_pass http://localhost:8000/uri/;

或作为在单词“ unix”之后指定并用冒号括起来的 UNIX 域套接字路径：

proxy_pass http://unix:/tmp/backend.socket:/uri/;

如果一个域名解析为多个地址，则所有这些地址都将以循环方式使用。另外，可以将地址指定为server group。

参数值可以包含变量。在这种情况下，如果将地址指定为域名，则在描述的服务器组中搜索该名称，如果找不到，则使用resolver确定。

请求 URI 如下传递给服务器：

如果proxy_pass指令是用 URI 指定的，则当请求传递到服务器时，与该位置匹配的normalized请求 URI 的一部分将由指令中指定的 URI 代替：

location /name/ {
    proxy_pass http://127.0.0.1/remote/;
}

如果指定的proxy_pass没有 URI，则将请求 URI 以与原始请求处理时客户端发送的格式相同的形式传递到服务器，或者在处理更改的 URI 时传递完整的规范化请求 URI：

location /some/path/ {
    proxy_pass http://127.0.0.1;
}

Note

在版本 1.1.12 之前，如果指定的proxy_pass没有 URI，则在某些情况下，可能会传递原始请求 URI 而不是更改的 URI。

在某些情况下，无法确定请求 URI 中要替换的部分：

使用正则表达式指定位置时，以及在命名位置中。

在这种情况下，应指定proxy_pass且不带 URI。

当使用rewrite指令在代理位置内更改 URI 时，将使用相同的配置来处理请求(break)：

location /name/ {
    rewrite    /name/([^/]+) /users?name=$1 break;
    proxy_pass http://127.0.0.1;
}

在这种情况下，伪指令中指定的 URI 将被忽略，并将更改后的完整请求 URI 传递到服务器。

在proxy_pass中使用变量时：

location /name/ {
    proxy_pass http://127.0.0.1$request_uri;
}

在这种情况下，如果在指令中指定了 URI，则它将照原样传递到服务器，从而替换原始请求 URI。

WebSocket代理需要特殊配置，并且自 1.3.13 版本开始受支持。

Syntax:	`proxy_pass_header field;`
Default:	—
Context:	`http` , `server` , `location`

允许将otherwise disabledHeaders 字段从代理服务器传递到客户端。

Syntax:	`proxy_pass_request_body on \| off;`
Default:	`proxy_pass_request_body on;`
Context:	`http` , `server` , `location`

指示是否将原始请求正文传递到代理服务器。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...
}

另请参见proxy_set_header和proxy_pass_request_headers指令。

Syntax:	`proxy_pass_request_headers on \| off;`
Default:	`proxy_pass_request_headers on;`
Context:	`http` , `server` , `location`

指示是否将原始请求的 Headers 字段传递到代理服务器。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_headers off;
    proxy_pass_request_body off;

    proxy_pass ...
}

另请参见proxy_set_header和proxy_pass_request_body指令。

Syntax:	`proxy_read_timeout time;`
Default:	`proxy_read_timeout 60s;`
Context:	`http` , `server` , `location`

定义用于从代理服务器读取响应的超时。超时仅在两次连续的读取操作之间设置，而不用于传输整个响应。如果代理服务器在此时间内未传输任何内容，则连接将关闭。

Syntax:	`proxy_redirect default;`
`proxy_redirect off;` `proxy_redirect redirect replacement;`
默认值：	`proxy_redirect default;`
上下文： `http`，`server`，`location`

设置应在代理服务器响应的“位置”和“刷新”Headers 字段中更改的文本。假设代理服务器返回了 Headers 字段“ Location: http://localhost:8000/two/some/uri/”。指令

proxy_redirect http://localhost:8000/two/ http://frontend/one/;

将将此字符串重写为“ Location: http://frontend/one/some/uri/”。

replacement字符串中可以省略服务器名称：

proxy_redirect http://localhost:8000/two/ /;

然后将插入主服务器的名称和端口(如果与 80 不同)。

default参数指定的默认替换使用location和proxy_pass伪指令的参数。因此，以下两个配置是等效的：

location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect default;

location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect http://upstream:port/two/ /one/;

如果使用变量指定了proxy_pass，则不允许使用default参数。

replacement字符串可以包含变量：

proxy_redirect http://localhost:8000/ http://$host:$server_port/;

redirect还可以包含(1.1.11)变量：

proxy_redirect http://$proxy_host:8000/ /;

可以使用正则表达式指定该指令(1.1.11)。在这种情况下，redirect应该以“ ~”符号开头以区分大小写，或者以“ ~*”符号开头以区分大小写。正则表达式可以包含命名捕获和位置捕获，replacement可以引用它们：

proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;

可能有多个proxy_redirect指令：

proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;

off参数取消所有proxy_redirect指令对当前级别的影响：

proxy_redirect off;
proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;

使用此伪指令，还可以将主机名添加到代理服务器发出的相对重定向中：

proxy_redirect / /;

Syntax:	`proxy_request_buffering on \| off;`
Default:	`proxy_request_buffering on;`
Context:	`http` , `server` , `location`

该指令出现在 1.7.11 版本中。

启用或禁用客户端请求正文的缓冲。

启用缓冲后，在将请求发送到代理服务器之前，整个请求正文都是来自客户端的read。

禁用缓冲后，请求主体将在收到请求后立即发送到代理服务器。在这种情况下，如果 nginx 已经开始发送请求正文，则无法将请求传递给next server。

当使用 HTTP/1.1 分块传输编码发送原始请求正文时，无论指令值如何，都将对请求正文进行缓冲，除非 HTTP/1.1 是用于代理的enabled。

Syntax:	`proxy_send_lowat size;`
Default:	`proxy_send_lowat 0;`
Context:	`http` , `server` , `location`

如果指令设置为非零值，则 nginx 将尝试通过使用kqueue方法的NOTE_LOWAT标志或SO_SNDLOWAT套接字选项(带有指定的size)来最小化到代理服务器的传出连接上的发送操作数。

在 Linux，Solaris 和 Windows 上，此伪指令将被忽略。

Syntax:	`proxy_send_timeout time;`
Default:	`proxy_send_timeout 60s;`
Context:	`http` , `server` , `location`

设置将请求传输到代理服务器的超时。超时仅在两个连续的写操作之间设置，而不用于整个请求的传输。如果代理服务器在此时间内未收到任何信息，则连接将关闭。

Syntax:	`proxy_set_body value;`
Default:	—
Context:	`http` , `server` , `location`

允许重新定义传递给代理服务器的请求正文。 value可以包含文本，变量及其组合。

Syntax:	`proxy_set_header field value;`
Default:	`proxy_set_header Host $proxy_host;` `proxy_set_header Connection close;`
Context:	`http` , `server` , `location`

允许将字段重新定义或附加到请求 Headerspassed到代理服务器。 value可以包含文本，变量及其组合。当且仅当当前级别上未定义proxy_set_header指令时，这些指令才从上一级继承。默认情况下，仅重新定义两个字段：

proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;

如果启用了缓存，则标题字段“ If-Modified-Since”，“ If-Unmodified-Since”，“ If-None-Match”，“ If-Match”，“ Range”和“ If-Range”原始请求不会传递到代理服务器。

可以像这样传递未更改的“主机”请求 Headers 字段：

proxy_set_header Host       $http_host;

但是，如果客户端请求 Headers 中不存在此字段，则不会传递任何内容。在这种情况下，最好使用$host变量-其值等于“主机”请求 Headers 字段中的服务器名称，或者如果不存在此字段，则等于主服务器名称：

proxy_set_header Host       $host;

另外，服务器名称可以与代理服务器的端口一起传递：

proxy_set_header Host       $host:$proxy_port;

如果 Headers 字段的值为空字符串，则此字段将不会传递到代理服务器：

proxy_set_header Accept-Encoding "";

Syntax:	`proxy_socket_keepalive on \| off;`
Default:	`proxy_socket_keepalive off;`
Context:	`http` , `server` , `location`

该指令出现在 1.15.6 版中。

为与代理服务器的传出连接配置“ TCP 保持活动”行为。默认情况下，os 的设置对套接字有效。如果伪指令设置为值“ on”，则将为套接字打开SO_KEEPALIVE套接字选项。

Syntax:	`proxy_ssl_certificate file;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.8 中。

使用带有用于对代理 HTTPS 服务器进行身份验证的 PEM 格式的证书来指定file。

Syntax:	`proxy_ssl_certificate_key file;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.8 中。

使用 PEM 格式的密钥指定一个file，用于对代理 HTTPS 服务器进行身份验证。

可以指定值engine：name：id而不是file(1.7.9)，后者从 OpenSSL 引擎name加载具有指定id的 Secret 密钥。

Syntax:	`proxy_ssl_ciphers ciphers;`
Default:	`proxy_ssl_ciphers DEFAULT;`
Context:	`http` , `server` , `location`

该指令出现在 1.5.6 版中。

指定对代理 HTTPS 服务器的请求的启用密码。密码以 OpenSSL 库可以理解的格式指定。

可以使用“ openssl ciphers”命令查看完整列表。

Syntax:	`proxy_ssl_crl file;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在 1.7.0 版中。

使用 PEM 格式指定file带有吊销证书(CRL)，该证书用于verify代理 HTTPS 服务器的证书。

Syntax:	`proxy_ssl_name name;`
Default:	`proxy_ssl_name $proxy_host;`
Context:	`http` , `server` , `location`

该指令出现在 1.7.0 版中。

与代理 HTTPS 服务器构建连接时，允许覆盖用于verify代理 HTTPS 服务器的证书和通过 SNI的服务器名称。

默认情况下，使用proxy_pass URL 的主机部分。

Syntax:	`proxy_ssl_password_file file;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在版本 1.7.8 中。

指定一个带有secret keys密码短语的file，其中每个密码短语都在单独的行上指定。加载密钥时依次尝试使用密码短语。

Syntax:	`proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];`
Default:	`proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;`
Context:	`http` , `server` , `location`

该指令出现在 1.5.6 版中。

启用对代理 HTTPS 服务器的请求的指定协议。

Syntax:	`proxy_ssl_server_name on \| off;`
Default:	`proxy_ssl_server_name off;`
Context:	`http` , `server` , `location`

该指令出现在 1.7.0 版中。

与代理 HTTPS 服务器构建连接时，启用或禁用服务器名称通过TLS 服务器名称指示扩展(SNI，RFC 6066)的传递。

Syntax:	`proxy_ssl_session_reuse on \| off;`
Default:	`proxy_ssl_session_reuse on;`
Context:	`http` , `server` , `location`

确定在使用代理服务器时是否可以重用 SSL 会话。如果日志中出现错误“ SSL3_GET_FINISHED:digest check failed”，请尝试禁用会话重用。

Syntax:	`proxy_ssl_trusted_certificate file;`
Default:	—
Context:	`http` , `server` , `location`

该指令出现在 1.7.0 版中。

指定带有file的 PEM 格式的受信任 CA 证书，用于verify代理 HTTPS 服务器的证书。

Syntax:	`proxy_ssl_verify on \| off;`
Default:	`proxy_ssl_verify off;`
Context:	`http` , `server` , `location`

该指令出现在 1.7.0 版中。

启用或禁用对代理 HTTPS 服务器证书的验证。

Syntax:	`proxy_ssl_verify_depth number;`
Default:	`proxy_ssl_verify_depth 1;`
Context:	`http` , `server` , `location`

该指令出现在 1.7.0 版中。

在代理的 HTTPS 服务器证书链中设置验证深度。

Syntax:	`proxy_store on \| off \| string;`
Default:	`proxy_store off;`
Context:	`http` , `server` , `location`

允许将文件保存到磁盘。 on参数保存具有与指令alias或root相对应的路径的文件。 off参数禁用文件保存。另外，可以使用带有变量的string显式设置文件名：

proxy_store /data/www$original_uri;

根据收到的“ Last-Modified”响应头字段设置文件的修改时间。首先将响应写入临时文件，然后重命名该文件。从 0.8.9 版本开始，可以将临时文件和永久存储放在不同的文件系统上。但是，请注意，在这种情况下，文件是跨两个文件系统复制的，而不是廉价的重命名操作。因此，建议将对于任何给定位置的已保存文件和由proxy_temp_path指令设置的保存临时文件的目录都放在同一文件系统上。

该指令可用于创建静态不可更改文件的本地副本，例如：

location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    proxy_pass         http://backend/;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    alias              /data/www/;
}

或像这样：

location /images/ {
    root               /data/www;
    error_page         404 = @fetch;
}

location @fetch {
    internal;

    proxy_pass         http://backend;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    root               /data/www;
}

Syntax:	`proxy_store_access users:permissions ...;`
Default:	`proxy_store_access user:rw;`
Context:	`http` , `server` , `location`

设置新创建的文件和目录的访问权限，例如：

proxy_store_access user:rw group:rw all:r;

如果指定了任何group或all访问权限，则可以省略user权限：

proxy_store_access group:rw all:r;

Syntax:	`proxy_temp_file_write_size size;`
Default:	`proxy_temp_file_write_size 8k\|16k;`
Context:	`http` , `server` , `location`

当启用从代理服务器到临时文件的响应缓冲时，一次限制写入临时文件的数据size。默认情况下，size受proxy_buffer_size和proxy_buffers伪指令设置的两个缓冲区的限制。临时文件的最大大小由proxy_max_temp_file_size指令设置。

Syntax:	`proxy_temp_path path [level1 [level2 [level3]]];`
Default:	`proxy_temp_path proxy_temp;`
Context:	`http` , `server` , `location`

定义一个目录，用于存储包含从代理服务器接收到的数据的临时文件。在指定目录下最多可以使用三级子目录层次结构。例如，在以下配置中

proxy_temp_path /spool/nginx/proxy_temp 1 2;

临时文件可能如下所示：

/spool/nginx/proxy_temp/7/45/00000123457

另请参见proxy_cache_path指令的use_temp_path参数。

Embedded Variables

ngx_http_proxy_module模块支持嵌入式变量，可使用proxy_set_header指令来构成 Headers：

$proxy_host

proxy_pass指令中指定的代理服务器的名称和端口；

$proxy_port

proxy_pass指令中指定的代理服务器的端口，或协议的默认端口；

$proxy_add_x_forwarded_for

附加了$remote_addr变量的“ X-Forwarded-For”客户端请求 Headers 字段，以逗号分隔。如果客户端请求 Headers 中不存在“ X-Forwarded-For”字段，则$proxy_add_x_forwarded_for变量等于$remote_addr变量。