模块 ngx_http_proxy_module
ngx_http_proxy_module
模块允许将请求传递到另一个服务器。
示例配置
location / { proxy_pass https://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }
指令
语法 |
proxy_bind |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 0.8.22 版本中。
使传出到代理服务器的连接源自指定的本地 IP 地址以及可选端口 (1.11.2)。参数值可以包含变量 (1.3.12)。特殊值 off
(1.3.12) 取消从先前配置级别继承的 proxy_bind
指令的效果,从而允许系统自动分配本地 IP 地址和端口。
transparent
参数 (1.11.0) 允许传出到代理服务器的连接源自非本地 IP 地址,例如客户端的真实 IP 地址。
proxy_bind $remote_addr transparent;
为了使此参数生效,通常需要使用 超级用户 权限运行 Nginx 工作进程。在 Linux 上则不需要 (1.13.8),因为如果指定了 transparent
参数,工作进程将从主进程继承 CAP_NET_RAW
功能。还需要配置内核路由表以拦截来自代理服务器的网络流量。
语法 |
proxy_buffer_size |
---|---|
默认值 |
proxy_buffer_size 4k|8k; |
上下文 |
http 、server 、location |
设置用于读取从代理服务器接收到的响应第一部分的缓冲区 大小
。此部分通常包含一个小的响应头。默认情况下,缓冲区大小等于一个内存页。这可能是 4K 或 8K,具体取决于平台。但是,它可以缩小。
语法 |
proxy_buffering |
---|---|
默认值 |
proxy_buffering on; |
上下文 |
http 、server 、location |
启用或禁用从代理服务器缓冲响应。
启用缓冲时,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 |
---|---|
默认值 |
proxy_buffers 8 4k|8k; |
上下文 |
http 、server 、location |
设置用于读取从代理服务器接收到的响应的缓冲区的 数量
和 大小
,适用于单个连接。默认情况下,缓冲区大小等于一个内存页。这可能是 4K 或 8K,具体取决于平台。
语法 |
proxy_busy_buffers_size |
---|---|
默认值 |
proxy_busy_buffers_size 8k|16k; |
上下文 |
http 、server 、location |
当启用从代理服务器 缓冲 响应时,限制可以忙于将响应发送到客户端的缓冲区的总 大小
,而响应尚未完全读取。同时,其余缓冲区可用于读取响应,并在需要时将响应的一部分缓冲到临时文件。默认情况下,大小
受限于由 proxy_buffer_size 和 proxy_buffers 指令设置的两个缓冲区的大小。
语法 |
proxy_cache |
---|---|
默认值 |
proxy_cache off; |
上下文 |
http 、server 、location |
定义用于缓存的共享内存区域。同一区域可以在多个地方使用。参数值可以包含变量 (1.7.9)。off
参数禁用从先前配置级别继承的缓存。
语法 |
proxy_cache_background_update |
---|---|
默认值 |
proxy_cache_background_update off; |
上下文 |
http 、server 、location |
此指令出现在 1.11.10 版本中。
允许启动一个后台子请求来更新过期的缓存项,同时将陈旧的缓存响应返回给客户端。请注意,在更新缓存响应时,有必要 允许 使用陈旧的缓存响应。
语法 |
proxy_cache_bypass |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
定义不会从缓存中获取响应的条件。如果字符串参数的至少一个值不为空且不等于“0”,则不会从缓存中获取响应。
proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; proxy_cache_bypass $http_pragma $http_authorization;
可以与 proxy_no_cache 指令一起使用。
语法 |
proxy_cache_convert_head |
---|---|
默认值 |
proxy_cache_convert_head on; |
上下文 |
http 、server 、location |
此指令出现在 1.9.7 版本中。
启用或禁用将“HEAD
”方法转换为“GET
”以进行缓存。禁用转换时,应配置 缓存键 以包含 $request_method
。
语法 |
proxy_cache_key |
---|---|
默认值 |
proxy_cache_key $scheme$proxy_host$request_uri; |
上下文 |
http 、server 、location |
定义缓存键,例如
proxy_cache_key "$host$request_uri $cookie_user";
默认情况下,指令的值接近于字符串
proxy_cache_key $scheme$proxy_host$uri$is_args$args;
语法 |
proxy_cache_lock |
---|---|
默认值 |
proxy_cache_lock off; |
上下文 |
http 、server 、location |
此指令出现在 1.1.12 版本中。
启用后,一次只允许一个请求填充根据 proxy_cache_key 指令标识的新缓存元素,方法是将请求传递到代理服务器。同一缓存元素的其他请求将等待响应出现在缓存中或等待此元素的缓存锁释放,直到 proxy_cache_lock_timeout 指令设置的时间为止。
语法 |
proxy_cache_lock_age |
---|---|
默认值 |
proxy_cache_lock_age 5s; |
上下文 |
http 、server 、location |
此指令出现在 1.7.8 版本中。
如果传递到代理服务器以填充新缓存元素的最后一个请求在指定 时间
内未完成,则可以将另一个请求传递到代理服务器。
语法 |
proxy_cache_lock_timeout |
---|---|
默认值 |
proxy_cache_lock_timeout 5s; |
上下文 |
http 、server 、location |
此指令出现在 1.1.12 版本中。
设置 proxy_cache_lock 的超时时间。当 时间
到期时,请求将传递到代理服务器,但是响应不会被缓存。
在 1.7.8 之前,响应可以被缓存。
语法 |
proxy_cache_max_range_offset |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.11.6 版本中。
设置字节范围请求的偏移量(以字节为单位)。如果范围超出偏移量,则字节范围请求将传递到代理服务器,并且响应不会被缓存。
语法 |
proxy_cache_methods |
---|---|
默认值 |
proxy_cache_methods GET HEAD; |
上下文 |
http 、server 、location |
此指令出现在 0.7.59 版本中。
如果客户端请求方法在此指令中列出,则响应将被缓存。“GET
”和“HEAD
”方法始终添加到列表中,尽管建议显式指定它们。另请参阅 proxy_no_cache 指令。
语法 |
proxy_cache_min_uses |
---|---|
默认值 |
proxy_cache_min_uses 1; |
上下文 |
http 、server 、location |
设置响应将在其后被缓存的请求 数量
。
语法 |
proxy_cache_path |
---|---|
默认值 | — |
上下文 |
http |
设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的文件名是将 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
参数配置。一个兆字节的区域可以存储大约 8000 个密钥。
作为商业订阅的一部分,共享内存区域还存储扩展缓存信息,因此,对于相同数量的密钥,需要指定更大的区域大小。例如,一个兆字节的区域可以存储大约 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 毫秒)。
此外,以下参数作为我们商业订阅的一部分提供。
-
purger
=on
|off
- 指示是否由缓存清除器(1.7.12)从磁盘中删除与通配符密钥匹配的缓存条目。将参数设置为
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 毫秒。
在 1.7.3、1.7.7 和 1.11.10 版本中,缓存头格式已更改。升级到较新的 nginx 版本后,先前缓存的响应将被视为无效。
语法 |
proxy_cache_purge string ...; |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.5.7 版本中。
定义请求被视为缓存清除请求的条件。如果字符串参数的至少一个值不为空且不等于“0”,则删除具有相应缓存密钥的缓存条目。成功操作的结果通过返回 204(无内容)响应来指示。
如果清除请求的缓存密钥以星号(“*
”)结尾,则将删除与通配符密钥匹配的所有缓存条目。但是,这些条目将保留在磁盘上,直到它们因不活动而被删除,或者由缓存清除器(1.7.12)处理,或者客户端尝试访问它们。
示例配置
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; } }
此功能作为我们商业订阅的一部分提供。
语法 |
proxy_cache_revalidate |
---|---|
默认值 |
proxy_cache_revalidate off; |
上下文 |
http 、server 、location |
此指令出现在 1.5.7 版本中。
使用带“If-Modified-Since”和“If-None-Match”报头字段的条件请求启用已过期缓存项的重新验证。
语法 |
proxy_cache_use_stale |
---|---|
默认值 |
proxy_cache_use_stale off; |
上下文 |
http 、server 、location |
确定在与代理服务器通信期间何时可以使用陈旧的缓存响应。指令的参数与proxy_next_upstream指令的参数匹配。
error
参数还允许在无法选择代理服务器来处理请求时使用陈旧的缓存响应。
此外,updating
参数允许在当前正在更新缓存响应时使用陈旧的缓存响应。这允许在更新缓存数据时最大程度地减少对代理服务器的访问次数。
也可以在响应标头中直接为响应变为陈旧后的指定秒数启用使用陈旧的缓存响应(1.11.10)。这比使用指令参数的优先级低。
- “Cache-Control”报头字段的“stale-while-revalidate”扩展允许在当前正在更新缓存响应时使用陈旧的缓存响应。
- “Cache-Control”报头字段的“stale-if-error”扩展允许在发生错误时使用陈旧的缓存响应。
为了最大程度地减少在填充新缓存元素时对代理服务器的访问次数,可以使用proxy_cache_lock指令。
语法 |
proxy_cache_valid [ |
---|---|
默认值 | — |
上下文 |
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”报头字段以秒为单位设置响应的缓存时间。零值禁用响应的缓存。如果该值以
@
前缀开头,则设置自纪元以来的绝对时间(以秒为单位),在此时间之前可以缓存响应。 - 如果标头不包含“X-Accel-Expires”字段,则可以在“Expires”或“Cache-Control”报头字段中设置缓存参数。
- 如果标头包含“Set-Cookie”字段,则不会缓存此类响应。
- 如果标头包含具有特殊值“
*
”的“Vary”字段,则不会缓存此类响应(1.7.7)。如果标头包含具有其他值的“Vary”字段,则将缓存此类响应,并考虑相应的请求标头字段(1.7.7)。
可以使用proxy_ignore_headers指令禁用对这些响应标头字段中的一个或多个的处理。
语法 |
proxy_connect_timeout |
---|---|
默认值 |
proxy_connect_timeout 60s; |
上下文 |
http 、server 、location |
定义与代理服务器建立连接的超时时间。需要注意的是,此超时时间通常不能超过 75 秒。
语法 |
proxy_cookie_domain proxy_cookie_domain |
---|---|
默认值 |
proxy_cookie_domain off; |
上下文 |
http 、server 、location |
此指令出现在 1.1.15 版本中。
设置应在代理服务器响应的“Set-Cookie”报头字段的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;
如果多个指令可以应用于 cookie,则将选择第一个匹配的指令。
off
参数取消从先前配置级别继承的proxy_cookie_domain
指令的效果。
语法 |
proxy_cookie_flags |
---|---|
默认值 |
proxy_cookie_flags off; |
上下文 |
http 、server 、location |
此指令出现在 1.19.3 版本中。
为 cookie 设置一个或多个标志。cookie
可以包含文本、变量及其组合。flag
可以包含文本、变量及其组合(1.19.8)。secure
、httponly
、samesite=strict
、samesite=lax
、samesite=none
参数添加相应的标志。nosecure
、nohttponly
、nosamesite
参数删除相应的标志。
cookie 也可以使用正则表达式指定。在这种情况下,cookie
应以“~
”符号开头。
可以在同一配置级别上指定多个proxy_cookie_flags
指令
proxy_cookie_flags one httponly; proxy_cookie_flags ~ nosecure samesite=strict;
如果多个指令可以应用于 Cookie,则将选择第一个匹配的指令。在示例中,httponly
标志被添加到 Cookie one
中,对于所有其他 Cookie,则添加 samesite=strict
标志并删除 secure
标志。
off
参数取消从上一级配置继承的 proxy_cookie_flags
指令的效果。
语法 |
proxy_cookie_path proxy_cookie_path |
---|---|
默认值 |
proxy_cookie_path off; |
上下文 |
http 、server 、location |
此指令出现在 1.1.15 版本中。
设置应在代理服务器响应的“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
应以“~
”符号开头以进行区分大小写的匹配,或以“~*
”符号开头以进行不区分大小写的匹配。正则表达式可以包含命名和位置捕获,而 replacement
可以引用它们
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
可以在同一级别上指定多个 proxy_cookie_path
指令
proxy_cookie_path /one/ /; proxy_cookie_path / /two/;
如果多个指令可以应用于 cookie,则将选择第一个匹配的指令。
off
参数取消从上一级配置继承的 proxy_cookie_path
指令的效果。
语法 |
proxy_force_ranges |
---|---|
默认值 |
proxy_force_ranges off; |
上下文 |
http 、server 、location |
此指令出现在 1.7.7 版本中。
无论这些响应中的“Accept-Ranges”字段如何,都启用代理服务器缓存和未缓存响应的字节范围支持。
语法 |
proxy_headers_hash_bucket_size |
---|---|
默认值 |
proxy_headers_hash_bucket_size 64; |
上下文 |
http 、server 、location |
设置 proxy_hide_header 和 proxy_set_header 指令使用的哈希表的桶 size
。哈希表设置的详细信息在单独的 文档 中提供。
语法 |
proxy_headers_hash_max_size |
---|---|
默认值 |
proxy_headers_hash_max_size 512; |
上下文 |
http 、server 、location |
设置 proxy_hide_header 和 proxy_set_header 指令使用的哈希表的最大 size
。哈希表设置的详细信息在单独的 文档 中提供。
语法 |
proxy_hide_header |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
默认情况下,nginx 不会将代理服务器响应的“Date”、“Server”、“X-Pad”和“X-Accel-...”报头字段传递给客户端。proxy_hide_header
指令设置不会传递的其他字段。相反,如果需要允许传递字段,则可以使用 proxy_pass_header 指令。
语法 |
proxy_http_version |
---|---|
默认值 |
proxy_http_version 1.0; |
上下文 |
http 、server 、location |
此指令出现在 1.1.4 版本中。
设置代理的 HTTP 协议版本。默认情况下,使用版本 1.0。建议将版本 1.1 用于 保持活动 连接和 NTLM 身份验证。
语法 |
proxy_ignore_client_abort |
---|---|
默认值 |
proxy_ignore_client_abort off; |
上下文 |
http 、server 、location |
确定当客户端关闭连接而不等待响应时是否应关闭与代理服务器的连接。
语法 |
proxy_ignore_headers |
---|---|
默认值 | — |
上下文 |
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”设置响应 缓存 的参数;
- “X-Accel-Redirect”执行对指定 URI 的 内部重定向;
- “X-Accel-Limit-Rate”设置对客户端传输响应的 速率限制;
- “X-Accel-Buffering”启用或禁用响应的 缓冲;
- “X-Accel-Charset”设置响应所需的 字符集。
语法 |
proxy_intercept_errors |
---|---|
默认值 |
proxy_intercept_errors off; |
上下文 |
http 、server 、location |
确定是否应将代码大于或等于 300 的代理响应传递给客户端,或者拦截并重定向到 nginx 以使用 error_page 指令进行处理。
语法 |
proxy_limit_rate |
---|---|
默认值 |
proxy_limit_rate 0; |
上下文 |
http 、server 、location |
此指令出现在 1.7.7 版本中。
限制从代理服务器读取响应的速度。rate
以每秒字节数指定。零值禁用速率限制。限制为每个请求设置,因此如果 nginx 同时打开两个到代理服务器的连接,则总体速率将是指定限制的两倍。仅当启用了来自代理服务器的响应的 缓冲 时,限制才有效。参数值可以包含变量 (1.27.0)。
语法 |
proxy_max_temp_file_size |
---|---|
默认值 |
proxy_max_temp_file_size 1024m; |
上下文 |
http 、server 、location |
当启用了来自代理服务器的响应的 缓冲 并且整个响应不适合 proxy_buffer_size 和 proxy_buffers 指令设置的缓冲区时,响应的一部分可以保存到临时文件。此指令设置临时文件的最大 size
。一次写入临时文件的数据大小由 proxy_temp_file_write_size 指令设置。
零值禁用将响应缓冲到临时文件。
此限制不适用于将 缓存 或 存储 到磁盘上的响应。
语法 |
proxy_method |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
指定在转发到代理服务器的请求中使用的 HTTP method
,而不是客户端请求中的方法。参数值可以包含变量 (1.11.6)。
语法 |
proxy_next_upstream |
---|---|
默认值 |
proxy_next_upstream error timeout; |
上下文 |
http 、server 、location |
指定在哪些情况下应将请求传递到下一个服务器
error
- 在与服务器建立连接、向其传递请求或读取响应报头时发生错误;
timeout
- 在与服务器建立连接、向其传递请求或读取响应报头时发生超时;
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),则不会将具有 非幂等 方法 (
POST
、LOCK
、PATCH
) 的请求传递到下一个服务器;明确启用此选项允许重试此类请求; off
- 禁用将请求传递到下一个服务器。
应该记住,只有在尚未向客户端发送任何内容时,才能将请求传递到下一个服务器。也就是说,如果在传输响应过程中发生错误或超时,则无法修复此问题。
该指令还定义了将什么视为与服务器通信的 不成功尝试。error
、timeout
和 invalid_header
的情况始终被视为不成功尝试,即使它们未在指令中指定也是如此。http_500
、http_502
、http_503
、http_504
和 http_429
的情况仅在指令中指定时才被视为不成功尝试。http_403
和 http_404
的情况永远不被视为不成功尝试。
将请求传递到下一个服务器可以受 尝试次数 和 时间 的限制。
语法 |
proxy_next_upstream_timeout |
---|---|
默认值 |
proxy_next_upstream_timeout 0; |
上下文 |
http 、server 、location |
此指令出现在 1.7.5 版本中。
限制可以将请求传递到 下一个服务器 的时间。0
值关闭此限制。
语法 |
proxy_next_upstream_tries |
---|---|
默认值 |
proxy_next_upstream_tries 0; |
上下文 |
http 、server 、location |
此指令出现在 1.7.5 版本中。
限制将请求传递到 下一个服务器 的可能尝试次数。0
值关闭此限制。
语法 |
proxy_no_cache |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
定义响应不会保存到缓存的条件。如果字符串参数的至少一个值不为空且不等于“0”,则不会保存响应
proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; proxy_no_cache $http_pragma $http_authorization;
可以与 proxy_cache_bypass 指令一起使用。
语法 |
proxy_pass |
---|---|
默认值 | — |
上下文 |
location 、if in location 、limit_except |
设置代理服务器的协议和地址以及应将位置映射到的可选 URI。可以指定“http
”或“https
”作为协议。地址可以指定为域名或 IP 地址,以及可选端口
proxy_pass https://127.0.0.1:8000/uri/;
或作为在“unix
”一词之后指定并在冒号中括起来的 UNIX 域套接字路径
proxy_pass http://unix:/tmp/backend.socket:/uri/;
如果域名解析为多个地址,则将以循环方式使用所有这些地址。此外,地址可以指定为 服务器组。
参数值可以包含变量。在这种情况下,如果地址指定为域名,则在描述的服务器组中搜索该名称,如果未找到,则使用 解析器 确定。
请求 URI 传递到服务器的方式如下
- 如果
proxy_pass
指令与 URI 一起指定,则当请求传递到服务器时,与位置匹配的 规范化 请求 URI 的一部分将替换为指令中指定的 URIlocation /name/ { proxy_pass http://127.0.0.1/remote/; }
- 如果
proxy_pass
未指定 URI,则请求 URI 将以与客户端发送时相同的形式传递到服务器,或者在处理更改的 URI 时传递完整的规范化请求 URIlocation /some/path/ { proxy_pass http://127.0.0.1; }
在 1.1.12 版本之前,如果
proxy_pass
未指定 URI,则在某些情况下可能会传递原始请求 URI 而不是更改的 URI。
在某些情况下,无法确定要替换的请求 URI 的一部分
- 当使用正则表达式指定位置时,以及在命名位置内部。
在这些情况下,应在不带 URI 的情况下指定
proxy_pass
。 - 当使用 rewrite 指令在代理位置内部更改 URI 时,并且将使用相同的配置来处理请求 (
break
)location /name/ { rewrite /name/([^/]+) /users?name=$1 break; proxy_pass http://127.0.0.1; }
在这种情况下,将忽略指令中指定的 URI,并将完整的更改后的请求 URI 传递到服务器。
- 当在
proxy_pass
中使用变量时
在这种情况下,如果在指令中指定了 URI,则按原样传递到服务器,替换原始请求 URI。location /name/ { proxy_pass http://127.0.0.1$request_uri; }
WebSocket 代理需要特殊的配置,并且从 1.3.13 版本开始受支持。
语法 |
proxy_pass_header |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
允许将来自代理服务器的 其他情况下禁用的 报头字段传递给客户端。
语法 |
proxy_pass_request_body |
---|---|
默认值 |
proxy_pass_request_body on; |
上下文 |
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 指令。
语法 |
proxy_pass_request_headers |
---|---|
默认值 |
proxy_pass_request_headers on; |
上下文 |
http 、server 、location |
指示是否将原始请求的报头字段传递到代理服务器。
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 指令。
语法 |
proxy_pass_trailers |
---|---|
默认值 |
proxy_pass_trailers off; |
上下文 |
http 、server 、location |
此指令出现在 1.27.2 版本中。
允许将代理服务器的尾部字段传递到客户端。
HTTP/1.1 中的尾部部分是 显式启用的。
location / { proxy_http_version 1.1; proxy_set_header Connection "te"; proxy_set_header TE "trailers"; proxy_pass_trailers on; proxy_pass ... }
语法 |
proxy_read_timeout |
---|---|
默认值 |
proxy_read_timeout 60s; |
上下文 |
http 、server 、location |
定义从代理服务器读取响应的超时时间。超时时间仅设置在两个连续的读取操作之间,而不是整个响应的传输。如果代理服务器在此时间内未传输任何内容,则连接将关闭。
语法 |
proxy_redirect proxy_redirect proxy_redirect |
---|---|
默认值 |
proxy_redirect default; |
上下文 |
http 、server 、location |
设置应在代理服务器响应的“Location”和“Refresh”报头字段中更改的文本。假设代理服务器返回了报头字段“Location: https://127.0.0.1:8000/two/some/uri/
”。指令
proxy_redirect https://127.0.0.1:8000/two/ http://frontend/one/;
将此字符串重写为“Location: http://frontend/one/some/uri/
”。
可以在replacement
字符串中省略服务器名称
proxy_redirect https://127.0.0.1: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 https://127.0.0.1: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 https://127.0.0.1:8000/ /; proxy_redirect http://www.example.com/ /;
如果多个指令可以应用于代理服务器响应的报头字段,则将选择第一个匹配的指令。
off
参数取消从先前配置级别继承的proxy_redirect
指令的效果。
使用此指令,还可以将主机名添加到代理服务器发出的相对重定向中
proxy_redirect / /;
语法 |
proxy_request_buffering |
---|---|
默认值 |
proxy_request_buffering on; |
上下文 |
http 、server 、location |
此指令出现在 1.7.11 版本中。
启用或禁用客户端请求正文的缓冲。
启用缓冲时,整个请求正文将从客户端读取,然后再将其发送到代理服务器。
禁用缓冲时,请求正文将在收到后立即发送到代理服务器。在这种情况下,如果 nginx 已经开始发送请求正文,则无法将其传递到下一个服务器。
当使用 HTTP/1.1 分块传输编码发送原始请求正文时,无论指令值如何,请求正文都将被缓冲,除非为代理启用了 HTTP/1.1 enabled。
语法 |
proxy_send_lowat |
---|---|
默认值 |
proxy_send_lowat 0; |
上下文 |
http 、server 、location |
如果将指令设置为非零值,则 nginx 将尝试通过使用kqueue方法的NOTE_LOWAT
标志或SO_SNDLOWAT
套接字选项(使用指定的size
)来最大程度地减少对代理服务器的出站连接上的发送操作次数。
此指令在 Linux、Solaris 和 Windows 上被忽略。
语法 |
proxy_send_timeout |
---|---|
默认值 |
proxy_send_timeout 60s; |
上下文 |
http 、server 、location |
设置将请求传输到代理服务器的超时时间。超时时间仅设置在两个连续的写入操作之间,而不是整个请求的传输。如果代理服务器在此时间内未收到任何内容,则连接将关闭。
语法 |
proxy_set_body |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
允许重新定义传递到代理服务器的请求正文。value
可以包含文本、变量及其组合。
语法 |
proxy_set_header |
---|---|
默认值 |
proxy_set_header Host $proxy_host; proxy_set_header Connection close; |
上下文 |
http 、server 、location |
允许重新定义或追加传递到代理服务器的请求报头passed的字段。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”报头字段不会传递到代理服务器。
可以像这样传递未更改的“Host”请求报头字段
proxy_set_header Host $http_host;
但是,如果客户端请求报头中不存在此字段,则不会传递任何内容。在这种情况下,最好使用$host
变量 - 其值等于“Host”请求报头字段中的服务器名称,或者如果此字段不存在,则为主服务器名称
proxy_set_header Host $host;
此外,可以将服务器名称与代理服务器的端口一起传递
proxy_set_header Host $host:$proxy_port;
如果报头字段的值为空字符串,则此字段将不会传递到代理服务器
proxy_set_header Accept-Encoding "";
语法 |
proxy_socket_keepalive |
---|---|
默认值 |
proxy_socket_keepalive off; |
上下文 |
http 、server 、location |
此指令出现在 1.15.6 版本中。
配置对代理服务器的出站连接的“TCP keepalive”行为。默认情况下,操作系统的设置对套接字有效。如果将指令设置为“on
”值,则套接字的SO_KEEPALIVE
套接字选项将被打开。
语法 |
proxy_ssl_certificate |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.7.8 版本中。
指定用于对代理 HTTPS 服务器进行身份验证的 PEM 格式证书的file
。
从 1.21.0 版本开始,可以在file
名称中使用变量。
语法 |
proxy_ssl_certificate_key |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.7.8 版本中。
指定用于对代理 HTTPS 服务器进行身份验证的 PEM 格式密钥的file
。
可以指定engine
:name
:id
而不是file
(1.7.9),它从 OpenSSL 引擎name
加载具有指定id
的密钥。
从 1.21.0 版本开始,可以在file
名称中使用变量。
语法 |
proxy_ssl_ciphers |
---|---|
默认值 |
proxy_ssl_ciphers DEFAULT; |
上下文 |
http 、server 、location |
此指令出现在 1.5.6 版本中。
指定对代理 HTTPS 服务器的请求启用的密码。密码以 OpenSSL 库理解的格式指定。
可以使用“openssl ciphers
”命令查看完整列表。
语法 |
proxy_ssl_conf_command |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.19.4 版本中。
在与代理 HTTPS 服务器建立连接时,设置任意 OpenSSL 配置命令。
使用 OpenSSL 1.0.2 或更高版本时支持此指令。
可以在同一级别上指定多个proxy_ssl_conf_command
指令。如果当前级别上未定义proxy_ssl_conf_command
指令,则这些指令将从先前的配置级别继承。
请注意,直接配置 OpenSSL 可能会导致意外行为。
语法 |
proxy_ssl_crl |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.7.0 版本中。
指定用于验证代理 HTTPS 服务器证书的 PEM 格式吊销证书 (CRL) 的file
。
语法 |
proxy_ssl_key_log path; |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.27.2 版本中。
启用代理 HTTPS 服务器连接 SSL 密钥的日志记录,并指定密钥日志文件的路径。密钥以与 Wireshark 兼容的SSLKEYLOGFILE格式记录。
此指令作为我们商业订阅的一部分提供。
语法 |
proxy_ssl_name |
---|---|
默认值 |
proxy_ssl_name $proxy_host; |
上下文 |
http 、server 、location |
此指令出现在 1.7.0 版本中。
允许覆盖用于验证代理 HTTPS 服务器证书的服务器名称,并在与代理 HTTPS 服务器建立连接时通过 SNI 传递。
默认情况下,使用proxy_pass URL 的主机部分。
语法 |
proxy_ssl_password_file |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.7.8 版本中。
指定包含密钥密码的file
,其中每个密码都在单独的行上指定。加载密钥时将依次尝试密码。
语法 |
proxy_ssl_protocols [ |
---|---|
默认值 |
proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; |
上下文 |
http 、server 、location |
此指令出现在 1.5.6 版本中。
为对代理 HTTPS 服务器的请求启用指定的协议。
从 1.23.4 开始,默认使用TLSv1.3
参数。
语法 |
proxy_ssl_server_name |
---|---|
默认值 |
proxy_ssl_server_name off; |
上下文 |
http 、server 、location |
此指令出现在 1.7.0 版本中。
启用或禁用在与代理 HTTPS 服务器建立连接时通过TLS 服务器名称指示扩展(SNI,RFC 6066)传递服务器名称。
语法 |
proxy_ssl_session_reuse |
---|---|
默认值 |
proxy_ssl_session_reuse on; |
上下文 |
http 、server 、location |
确定在与代理服务器一起工作时是否可以重用 SSL 会话。如果日志中出现“SSL3_GET_FINISHED:digest check failed
”错误,请尝试禁用会话重用。
语法 |
proxy_ssl_trusted_certificate |
---|---|
默认值 | — |
上下文 |
http 、server 、location |
此指令出现在 1.7.0 版本中。
指定用于验证代理 HTTPS 服务器证书的 PEM 格式受信任的 CA 证书的file
。
语法 |
proxy_ssl_verify |
---|---|
默认值 |
proxy_ssl_verify off; |
上下文 |
http 、server 、location |
此指令出现在 1.7.0 版本中。
启用或禁用代理 HTTPS 服务器证书的验证。
语法 |
proxy_ssl_verify_depth |
---|---|
默认值 |
proxy_ssl_verify_depth 1; |
上下文 |
http 、server 、location |
此指令出现在 1.7.0 版本中。
设置代理 HTTPS 服务器证书链中的验证深度。
语法 |
proxy_store |
---|---|
默认值 |
proxy_store off; |
上下文 |
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; }
语法 |
proxy_store_access |
---|---|
默认值 |
proxy_store_access user:rw; |
上下文 |
http 、server 、location |
设置新创建的文件和目录的访问权限,例如:
proxy_store_access user:rw group:rw all:r;
如果指定了任何group
或all
访问权限,则可以省略user
权限。
proxy_store_access group:rw all:r;
语法 |
proxy_temp_file_write_size |
---|---|
默认值 |
proxy_temp_file_write_size 8k|16k; |
上下文 |
http 、server 、location |
限制一次写入临时文件的数据size
,当启用从代理服务器到临时文件的响应缓冲时。默认情况下,size
受 proxy_buffer_size 和 proxy_buffers 指令设置的两个缓冲区的限制。临时文件的最大大小由 proxy_max_temp_file_size 指令设置。
语法 |
proxy_temp_path |
---|---|
默认值 |
proxy_temp_path proxy_temp; |
上下文 |
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
参数。
嵌入式变量
ngx_http_proxy_module
模块支持嵌入变量,这些变量可用于使用 proxy_set_header 指令组合标头。
$proxy_host
- 在 proxy_pass 指令中指定的代理服务器的名称和端口;
$proxy_port
- 在 proxy_pass 指令中指定的代理服务器的端口,或协议的默认端口;
-
$proxy_add_x_forwarded_for
- “X-Forwarded-For”客户端请求头字段,后面附加了
$remote_addr
变量,并用逗号分隔。如果客户端请求头中不存在“X-Forwarded-For”字段,则$proxy_add_x_forwarded_for
变量等于$remote_addr
变量。