代理#

允许将请求传递给另一个(代理)服务器。

配置示例#

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

指令#

proxy_bind#

语法

proxy_bind address [transparent] | off;

默认

上下文

http, server, location

使发送到代理服务器的外部连接源自指定的本地 IP 地址,并可选择端口。参数值可以包含变量。特殊值 off 取消从先前配置级别继承的 proxy_bind 指令的效果,允许系统自动分配本地 IP 地址和端口。

transparent 参数允许从非本地 IP 地址发起的外部连接,例如,从客户端的真实 IP 地址:

proxy_bind $remote_addr transparent;

为了使该参数生效,通常需要以 超级用户 权限运行 Angie 工作进程。在 Linux 上这是不需要的,因为如果指定了 transparent 参数,工作进程将从主进程继承 CAP_NET_RAW 权限。

重要

必须配置内核路由表以拦截来自代理服务器的网络流量。

proxy_buffer_size#

语法

proxy_buffer_size size;

默认

proxy_buffer_size 4k|8k;

上下文

http, server, location

设置用于读取从代理服务器接收的响应的第一部分的缓冲区大小。该部分通常包含一个小的响应头。默认情况下,缓冲区大小等于一个内存页。这是 4K 或 8K,具体取决于平台。然而,它可以被设置得更小。

proxy_buffering#

语法

proxy_buffering on | off;

默认

proxy_buffering on;

上下文

http, server, location

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

on

Angie 尽快接收来自代理服务器的响应,并将其保存到由 proxy_buffer_sizeproxy_buffers 指令设置的缓冲区中。如果整个响应无法适应内存,部分响应可以保存到磁盘上的 临时文件 中。写入临时文件受 proxy_max_temp_file_sizeproxy_temp_file_write_size 指令控制。

off

响应同步传递给客户端,立即传递给接收的响应。Angie 不会尝试从代理服务器读取整个响应。Angie 从服务器一次可以接收的数据的最大大小由 proxy_buffer_size 指令设置。

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

proxy_buffers#

语法

proxy_buffers number size;

默认

proxy_buffers 8 4k | 8k;

上下文

http, server, location

设置用于从代理服务器读取响应的缓冲区数量和大小,针对单个连接。

默认情况下,缓冲区大小等于一个内存页。这是 4K 或 8K,具体取决于平台。

proxy_busy_buffers_size#

语法

proxy_busy_buffers_size size;

默认

proxy_busy_buffers_size 8k | 16k;

上下文

http, server, location

当启用来自代理服务器的响应的 缓冲 时,限制在响应尚未完全读取时可以忙于发送响应到客户端的缓冲区的总大小。在此期间,其余的缓冲区可以用于读取响应,并在需要时将部分响应缓冲到临时文件中。

默认情况下,大小由 proxy_buffer_sizeproxy_buffers 指令设置的两个缓冲区的大小限制。

proxy_cache#

语法

proxy_cache zone | off [path=path];

默认

proxy_cache off;

上下文

http, server, location

定义用于缓存的共享内存区域。 该区域可以在配置中多次使用。 参数值允许变量。

off

禁用从先前配置级别继承的缓存。

Added in version 1.2.0: PRO

在 Angie PRO 中,您可以指定多个 proxy_cache_path 指令, 它们共享相同的 keys_zone 值以实现 cache sharding。如果您这样做,请设置 path 参数的 proxy_cache 指令,引用此 keys_zone

path=path

该值在后端的响应被 缓存 时确定, 这意味着涉及到变量,包括存储响应某些信息的变量。

如果从缓存中获得响应,path 不会重新评估; 因此,来自缓存的响应将保留其原始 path 直到将其从缓存中删除。

这允许通过将 map 指令或脚本应用于来自后端的响应来选择缓存路径。一个 Content-Type 示例:

proxy_cache_path /cache/one keys_zone=zone:10m;
proxy_cache_path /cache/two keys_zone=zone;

map $upstream_http_content_type $cache {
   ~^text/  one;
   default  two;
}

server {
   ...
   location / {
       proxy_pass http://backend;
       proxy_cache zone path=/cache/$cache;
   }
}

这添加了两个缓存路径和一个变量映射来选择它们。 如果 Content-Typetext/ 开头,则使用第一个路径; 否则,使用第二个。

proxy_cache_background_update#

语法

proxy_cache_background_update on | off;

默认

proxy_cache_background_update off;

上下文

http, server, location

允许启动后台子请求以更新过期的缓存项,同时将过期的缓存响应返回给客户端。

注意

请注意,必须 允许 使用过期的缓存响应进行更新。

proxy_cache_bypass#

语法

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 | off;

默认

proxy_cache_convert_head on;

上下文

http, server, location

启用或禁用将 "HEAD" 方法转换为 "GET" 以进行缓存。当禁用转换时, cache key 应配置为包含 $request_method

proxy_cache_key#

语法

proxy_cache_key string;

默认

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 on | off;

默认

proxy_cache_lock off;

上下文

http, server, location

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

proxy_cache_lock_age#

语法

proxy_cache_lock_age time;

默认

proxy_cache_lock_age 5s;

上下文

http, server, location

如果传递给代理服务器的最后一个请求以填充新缓存元素的请求在指定时间内未完成,则可以传递另一个请求到代理服务器。

proxy_cache_lock_timeout#

语法

proxy_cache_lock_timeout time;

默认

proxy_cache_lock_timeout 5s;

上下文

http, server, location

设置 proxy_cache_lock 的超时。当时间到期时,请求将传递到代理服务器,但响应不会被缓存。

语法

proxy_cache_max_range_offset 数字;

默认值

上下文

http, server, location

为字节范围请求设置字节偏移量。如果范围超出该偏移量,则范围请求将转发给被代理服务器,响应将不被缓存。

proxy_cache_methods#

语法

proxy_cache_methods GET | HEAD | POST ...;

默认值

proxy_cache_methods GET HEAD;

上下文

http, server, location

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

proxy_cache_min_uses#

语法

proxy_cache_min_uses 数字;

默认值

proxy_cache_min_uses 1;

上下文

http, server, location

设置响应被缓存之前的请求数量。

proxy_cache_path#

语法

proxy_cache_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];

默认值

上下文

http

设置缓存的 路径 和其他参数。缓存数据存储在文件中。缓存中的文件名是对 缓存键 应用 MD5 函数的结果。

levels

定义缓存的层级:从 1 到 3,每层接受值 1 或 2。

例如,在以下配置中:

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

缓存中的文件名将如下所示:

/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c

缓存响应首先写入临时文件,然后重命名该文件。临时文件和缓存可以放在不同的文件系统上。然而,请注意,在这种情况下,文件是在两个文件系统之间复制,而不是便宜的重命名操作。因此,建议对于任何给定的位置,缓存和存放临时文件的目录放在同一文件系统上。

use_temp_path=on | off

设置临时文件的目录

    on

如果省略此参数或设置为 on,将使用为给定 location 设置的 proxy_temp_path 指令的目录。

    off

临时文件将直接放在缓存目录中。

keys_zone

配置共享内存区域的名称和大小,以存储所有活动的键和数据的信息。

一个兆字节的区域可以存储大约 8000 个键。

inactive

在此参数指定的时间内未被访问的缓存数据将从缓存中移除,无论其新鲜度如何。

默认设置为 10 分钟。

备注

Added in version 1.2.0: PRO

在 Angie PRO 中,允许多个共享相同 keys_zone 值的 proxy_cache_path 指令。仅第一个此类指令可以设置共享内存区域的大小。选择此类指令是通过相关 proxy_cache 指令的 path 参数来完成的。

一个特殊的 缓存管理器 进程监视缓存的最大大小和文件系统中缓存的最小可用空间,当超过大小或可用空间不足时,它会删除最少最近使用的数据。数据以迭代的方式被删除。

max_size

最大缓存大小

min_free

文件系统中缓存的最小可用空间

manager_files

限制每次迭代中删除的项目数量

默认值为 100

manager_threshold

限制每次迭代的持续时间

默认值为 200 毫秒

manager_sleep

配置交互之间的暂停时间

默认值为 50 毫秒

Angie 启动后的一分钟内,将激活一个特殊的 缓存加载器 进程。它将加载存储在文件系统上的以前缓存数据的信息到缓存区域。加载也是以迭代的方式进行的。

loader_files

限制每次迭代中加载的项目数量

默认值为 100

loader_threshold

限制每次迭代的持续时间

默认值为 200 毫秒

loader_sleep

配置交互之间的暂停时间

默认值为 50 毫秒

proxy_cache_revalidate#

语法

proxy_cache_revalidate on | off;

默认值

proxy_cache_revalidate off;

上下文

http, server, location

启用使用 "If-Modified-Since" 和 "If-None-Match" 头字段的条件请求重新验证过期缓存项。

proxy_cache_use_stale#

语法

proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off ...;

默认值

proxy_cache_use_stale off;

上下文

http, server, location

确定在与被代理服务器通信时,可以在何种情况下使用过期的缓存响应。该指令的参数与 proxy_next_upstream 指令的参数匹配。

error

如果无法选择处理请求的被代理服务器,则允许使用过期的缓存响应。

updating

附加参数,如果当前正在更新,则允许使用过期的缓存响应。这有助于在更新缓存数据时最小化对被代理服务器的访问。

使用过期的缓存响应也可以在响应头中直接启用,在响应过期后指定的秒数内:

  • "Cache-Control" 头字段的 stale-while-revalidate 扩展允许在当前正在更新时使用过期的缓存响应。

  • "Cache-Control" 头字段的 stale-if-error 扩展允许在出现错误时使用过期的缓存响应。

备注

这优先级低于使用指令参数。

为了在填充新的缓存元素时最小化对被代理服务器的访问,可以使用 proxy_cache_lock 指令。

proxy_cache_valid#

语法

proxy_cache_valid [代码 ...] 时间;

默认值

上下文

http, server, location

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

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

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

如果仅指定缓存时间

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" 头字段以秒为单位设置响应的缓存时间。零值禁用响应缓存。如果值以 @ 前缀开头,则设置一个绝对时间(自 Epoch 起的秒数),在此时间之前响应可以被缓存。

  • 如果头中不包含 "X-Accel-Expires" 字段,缓存参数可以在 "Expires" 或 "Cache-Control" 头字段中设置。

  • 如果头中包含 "Set-Cookie" 字段,则该响应将不被缓存。

  • 如果头中包含 "Vary" 字段且特殊值为 "*",则该响应将不被缓存。如果头中包含 "Vary" 字段且值为其他值,则该响应将根据相应的请求头字段进行缓存。

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

proxy_connect_timeout#

语法

proxy_connect_timeout 时间;

默认值

proxy_connect_timeout 60s;

上下文

http, server, location

定义与被代理服务器建立连接的超时时间。需要注意的是,这个超时时间通常不能超过 75 秒。

proxy_connection_drop#

语法

proxy_connection_drop 时间 | on | off;

默认值

proxy_connection_drop off;

上下文

http, server, location

启用在被代理服务器被从组中移除或被 reresolve 过程或 API 命令 DELETE 标记为永久不可用后,终止与其所有连接。

当处理客户端或被代理服务器的下一个读或写事件时,连接将被终止。

设置 时间 启用连接终止 超时; 当设置为 on 时,连接立即被断开。

设置一个文本,用于更改代理服务器响应的“Set-Cookie”头字段中的域属性。假设代理服务器返回的“Set-Cookie”头字段的属性为“domain=localhost”。该指令

proxy_cookie_domain localhost example.org;

将该属性重写为“domain=example.org”。

domainreplacement 字符串开头的点和域属性会被忽略。匹配不区分大小写。

domainreplacement 字符串可以包含变量:

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_force_ranges#

语法

proxy_force_ranges off;

默认

proxy_force_ranges off;

上下文

http, server, location

启用对代理服务器的缓存和未缓存响应的字节范围支持,而不考虑这些响应中的“Accept-Ranges”字段。

proxy_headers_hash_bucket_size#

语法

proxy_headers_hash_bucket_size size;

默认

proxy_headers_hash_bucket_size 64;

上下文

http, server, location

设置用于 proxy_hide_headerproxy_set_header 指令的哈希表的桶大小。哈希表的设置细节将在 单独 提供。

proxy_headers_hash_max_size#

语法

proxy_headers_hash_max_size size;

默认

proxy_headers_hash_max_size 512;

上下文

http, server, location

设置用于 proxy_hide_headerproxy_set_header 指令的哈希表的最大大小。哈希表的设置细节将在 单独 提供。

proxy_hide_header#

语法

proxy_hide_header field;

默认

上下文

http, server, location

默认情况下,Angie不会将“Date”、“Server”、“X-Pad”和“X-Accel-...”头字段从代理服务器的响应传递给客户端。 proxy_hide_header 指令设置将不被传递的附加字段。如果相反,需要允许传递字段,可以使用 proxy_pass_header 指令。

proxy_http_version#

语法

proxy_http_version 1.0 | 1.1 | 3;

默认

proxy_http_version 1.0;

上下文

http, server, location, if in location, limit_except

设置代理的HTTP协议版本。默认情况下,使用版本1.0。建议使用版本1.1或更高版本与 keepalive connections 配合使用。

proxy_http3_hq#

语法

proxy_http3_hq on | off;

默认

proxy_http3_hq off;

上下文

http, server

切换特殊的 hq-interop 协商模式,该模式用于 QUICinterop tests,Angie依赖于此。

proxy_http3_max_concurrent_streams#

语法

proxy_http3_max_concurrent_streams number;

默认

proxy_http3_max_concurrent_streams 128;

上下文

http, server

初始化HTTP/3和QUIC设置,并设置在 连接 中并发HTTP/3请求流的最大数量。需要启用 keepalive connections

proxy_http3_max_table_capacity#

语法

proxy_http3_max_table_capacity number;

默认

proxy_http3_max_table_capacity 4096;

上下文

http, server, location

设置代理连接的 dynamic table 容量。

备注

类似的 http3_max_table_capacity 指令用于服务器连接。为了避免错误,当启用缓存代理时,禁用动态表的使用。

proxy_http3_stream_buffer_size#

语法

proxy_http3_stream_buffer_size size;

默认

proxy_http3_stream_buffer_size 64k;

上下文

http, server

设置与 QUIC streams 一起使用的读写缓冲区的 大小

proxy_ignore_client_abort#

语法

proxy_ignore_client_abort on | off;

默认

proxy_ignore_client_abort off;

上下文

http, server, location

确定当客户端在未等待响应的情况下关闭连接时,是否应关闭与代理服务器的连接。

proxy_ignore_headers#

语法

proxy_ignore_headers field ...;

默认

上下文

http, server, location

禁用处理来自代理服务器的某些响应头字段。可以忽略的字段包括:“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”、“X-Accel-Buffering”、“X-Accel-Charset”、“Expires”、“Cache-Control”、“Set-Cookie”和“Vary”。

如果未禁用,对这些头字段的处理具有以下效果:

  • “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 on | off;

默认值

proxy_intercept_errors off;

上下文

http, server, location

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

proxy_limit_rate#

语法

proxy_limit_rate rate;

默认值

proxy_limit_rate 0;

上下文

http, server, location

限制从代理服务器读取响应的速度。 rate 以字节每秒为单位指定,可以包含变量。

0

禁用速率限制

备注

限制是针对每个请求设置的,因此如果Angie同时打开两个与代理服务器的连接,则总体速率将是指定限制的两倍。限制仅在启用 buffering 来自代理服务器的响应时有效。

proxy_max_temp_file_size#

语法

proxy_max_temp_file_size size;

默认值

proxy_max_temp_file_size 1024m;

上下文

http, server, location

当启用来自代理服务器的响应的 buffering 时,如果整个响应不适合由 proxy_buffer_sizeproxy_buffers 指令设置的缓冲区,则可以将部分响应保存到临时文件中。此指令设置临时文件的最大大小。写入临时文件的数据大小由 proxy_temp_file_write_size 指令设置。

0

禁用响应缓冲到临时文件

备注

此限制不适用于将被缓存或 存储在磁盘上 的响应。

proxy_method#

语法

proxy_method method;

默认值

上下文

http, server, location

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

proxy_next_upstream#

语法

proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;

默认值

proxy_next_upstream error timeout;

上下文

http, server, location

指定在什么情况下请求应传递给 upstream pool 中的下一个服务器:

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的响应;

non_idempotent

通常,使用 non-idempotent 方法的请求 (POST, LOCK, PATCH) 在向上游服务器发送请求后不会传递给下一个 服务器;启用此选项可明确允许重试此类请求;

off

禁用将请求传递给下一个服务器。

备注

应当记住,只有在尚未向客户端发送任何内容的情况下,才可以将请求传递给下一个服务器。也就是说,如果在传输响应的过程中发生错误或超时,则无法修复此问题。

该指令还定义了与服务器通信的不成功尝试的 定义

error

timeout

invalid_header

始终被视为不成功的尝试,即使它们未在指令中指定

http_500

http_502

http_503

http_504

http_429

仅在指令中指定时被视为不成功的尝试

http_403

http_404

从不被视为不成功的尝试

将请求传递给下一个服务器的次数可以通过 triestime 限制。

proxy_next_upstream_timeout#

语法

proxy_next_upstream_timeout time;

默认值

proxy_next_upstream_timeout 0;

上下文

http, server, location

限制可以传递给 next 服务器的请求的时间。

0

关闭此限制

proxy_next_upstream_tries#

语法

proxy_next_upstream_tries number;

默认值

proxy_next_upstream_tries 0;

上下文

http, server, location

限制将请求传递给 next 服务器的可能尝试次数。

0

关闭此限制

proxy_no_cache#

语法

proxy_no_cache string ...;

默认值

上下文

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#

语法

proxy_pass uri;

默认值

上下文

location, if in location

设置代理服务器的协议和地址以及可选的URI,以便将位置映射到该URI。可以指定的协议有 httphttps。地址可以指定为域名或IP地址,并可选地指定端口:

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

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

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

如果域名解析为多个地址,则将以轮询方式使用所有这些地址。此外,可以将地址指定为 server group。 如果使用了组,则不能与其一起指定端口;而是,单独为组内的每个服务器指定端口。

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

请求URI的传递方式如下:

  • 如果指定了 带URI的 proxy_pass 指令,则在将请求传递给服务器时,将与位置匹配的 normalized 请求URI部分替换为指令中指定的URI:

location /name/ {
    proxy_pass http://127.0.0.1/remote/;
}
  • 如果指定了 不带URI的 proxy_pass,则请求URI将以客户端发送的原始请求的形式传递给服务器,或者在处理更改的URI时传递完整的规范请求URI:

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

在某些情况下,要替换的请求URI部分无法确定:

  • 当使用正则表达式指定 location 时,以及在命名的 locations 内部

在这些情况下,应当不带URI指定 proxy_pass

  • 当在代理的 location 内部使用 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 代理需要特殊配置。

proxy_pass_header#

语法

proxy_pass_header field ...;

默认值

上下文

http, server, location

允许将 否则禁用的 头字段从代理服务器传递给客户端。

proxy_pass_request_body#

语法

proxy_pass_request_body on | off;

默认

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_headerproxy_pass_request_headers 指令。

proxy_pass_request_headers#

语法

proxy_pass_request_headers on | off;

默认

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_headerproxy_pass_request_body 指令。

proxy_pass_trailers#

语法

proxy_pass_trailers on | off;

默认

proxy_pass_trailers off;

上下文

http, server, location

允许将来自被代理服务器的尾部字段传递给客户端。

在 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_quic_active_connection_id_limit#

语法

proxy_quic_active_connection_id_limit number;

默认

proxy_quic_active_connection_id_limit 2;

上下文

http, server

设置 QUIC active_connection_id_limit 传输参数值。 这是每个服务器可以维护的最大活跃 连接 ID 数量。

proxy_quic_gso#

语法

proxy_quic_gso on | off;

默认

proxy_quic_gso off;

上下文

http, server

切换以使用 QUIC 优化的批量模式发送数据, 利用 (通用分段卸载)。

proxy_quic_host_key#

语法

proxy_quic_host_key file;

默认

上下文

http, server

设置一个 file,其中包含与 QUIC 一起使用的秘密密钥, 用于加密 无状态重置地址验证 令牌。 默认情况下,每次重启时会生成一个随机密钥。 使用旧密钥生成的令牌将不被接受。

proxy_read_timeout#

语法

proxy_read_timeout time;

默认

proxy_read_timeout 60s;

上下文

http, server, location

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

proxy_redirect#

语法

proxy_redirect default;

proxy_redirect off;

proxy_redirect 重定向替换;

默认

proxy_redirect default;

上下文

http, server, location

设置在被代理服务器响应的 "Location" 和 "Refresh" 头字段中应更改的文本。

假设被代理服务器返回了头字段:

Location: http://localhost:8000/two/some/uri/

指令

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

将把该字符串重写为:

Location: http://frontend/one/some/uri/

替换 字符串中可以省略服务器名称:

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

那么主服务器的名称和端口(如果不同于 80)将被插入。

default 参数指定的默认替换使用 locationproxy_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,则不允许使用默认参数。

替换 字符串可以包含变量:

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

重定向 也可以包含变量:

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

该指令可以使用正则表达式指定。在这种情况下,重定向 应该以 "~" 符号开头以进行区分大小写的匹配,或者以 "~*" 符号开头以进行不区分大小写的匹配。正则表达式可以包含命名和位置捕获,替换 可以引用它们:

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 / /;

proxy_request_buffering#

语法

proxy_request_buffering on | off;

默认

proxy_request_buffering on;

上下文

http, server, location

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

on

在将请求发送到被代理服务器之前,会 读取 整个请求体。

off

请求体会在接收时立即发送到被代理服务器。在这种情况下,如果 Angie 已经开始发送请求体,则请求无法传递给 下一个服务器

当使用 HTTP/1.1 分块传输编码发送原始请求体时,无论指令值如何,请求体都将被缓冲,除非 HTTP/1.1 被 启用 进行代理。

proxy_send_lowat#

语法

proxy_send_lowat size;

默认

proxy_send_lowat 0;

上下文

http, server, location

如果指令设置为非零值,Angie 将尝试通过使用 kqueue 方法的 NOTE_LOWAT 标志或指定大小的 SO_SNDLOWAT 套接字选项来最小化对被代理服务器的发送操作次数。

备注

此指令在 Linux、Solaris 和 Windows 上会被忽略。

proxy_send_timeout#

语法

proxy_send_timeout time;

默认

proxy_send_timeout 60s;

上下文

http, server, location

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

proxy_set_body#

语法

proxy_set_body value;

默认

上下文

http, server, location

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

proxy_set_header#

语法

proxy_set_header field value;

默认

proxy_set_header Host $proxy_host;

上下文

http, server, location

允许重新定义或附加字段到请求头 传递 给被代理服务器。 可以包含文本、变量及其组合。如果当前级别没有定义 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 on | off;

默认

proxy_socket_keepalive off;

上下文

http, server, location

配置与被代理服务器的外发连接的 "TCP keepalive" 行为。

""

默认情况下,操作系统的设置对套接字生效。

on

为套接字开启 SO_KEEPALIVE 套接字选项。

proxy_ssl_certificate#

语法

proxy_ssl_certificate file [file];

默认

上下文

http, server, location

指定用于身份验证被代理 HTTPS 服务器的 PEM 格式证书文件。文件名中可以使用变量。

Added in version 1.2.0.

proxy_ssl_ntls 启用时,该指令接受两个参数而不是一个,即证书的签名和加密部分:

location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}

proxy_ssl_certificate_key#

语法

proxy_ssl_certificate_key file [file];

默认

上下文

http, server, location

指定用于身份验证被代理 HTTPS 服务器的 PEM 格式秘密密钥文件。

可以指定值 "engine:name:id" 代替文件,从 OpenSSL 引擎名称加载具有指定 id 的秘密密钥。文件名中可以使用变量。

Added in version 1.2.0.

proxy_ssl_ntls 启用时,该指令接受两个参数而不是一个:签名和加密部分的密钥:

location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}

proxy_ssl_ciphers#

语法

proxy_ssl_ciphers ciphers;

默认

proxy_ssl_ciphers DEFAULT;

上下文

http, server, location

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

密码列表取决于已安装的 OpenSSL 版本。可以使用 openssl ciphers 命令查看完整列表。

proxy_ssl_conf_command#

语法

proxy_ssl_conf_command name value;

默认

上下文

http, server, location

在与被代理 HTTPS 服务器建立连接时设置任意 OpenSSL 配置 commands

重要

该指令在使用 OpenSSL 1.0.2 或更高版本时受到支持。

可以在同一层上指定多个 proxy_ssl_conf_command 指令。如果当前层没有定义 proxy_ssl_conf_command 指令,则这些指令将从上一个配置层继承。

小心

请注意,直接配置 OpenSSL 可能会导致意外行为。

proxy_ssl_crl#

语法

proxy_ssl_crl file;

默认

上下文

http, server, location

指定包含被吊销证书 (CRL) 的 PEM 格式文件,用于 验证 被代理 HTTPS 服务器的证书。

proxy_ssl_name#

语法

proxy_ssl_name name;

默认

proxy_ssl_name $proxy_host;

上下文

http, server, location

允许覆盖用于 验证 被代理 HTTPS 服务器证书的服务器名称,并在与被代理 HTTPS 服务器建立连接时通过 传递 SNI

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

proxy_ssl_ntls#

Added in version 1.2.0.

语法

proxy_ssl_ntls on | off;

默认

proxy_ssl_ntls off;

上下文

http, server

启用客户端对 NTLS 的支持,使用 TongSuo 库。

location /proxy {
    proxy_ssl_ntls  on;

    proxy_ssl_certificate      sign.crt enc.crt;
    proxy_ssl_certificate_key  sign.key enc.key;

    proxy_ssl_ciphers "ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3:RSA";

    proxy_pass https://backend:443;
}

重要

使用 --with-ntls 构建选项构建 Angie,并链接与 NTLS 启用的 SSL 库

./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls

proxy_ssl_password_file#

语法

proxy_ssl_password_file file;

默认

上下文

http, server, location

指定一个文件,其中包含 秘密密钥 的密码,每个密码单独占一行。在加载密钥时,会依次尝试这些密码。

proxy_ssl_protocols#

语法

proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

默认值

proxy_ssl_protocols TLSv1.2 TLSv1.3;

上下文

http, server, location

在 1.2.0 版本发生变更: TLSv1.3 参数已添加到默认集。

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

proxy_ssl_server_name#

语法

proxy_ssl_server_name on | off;

默认

proxy_ssl_server_name off;

上下文

http, server, location

启用或禁用通过 proxy_ssl_name 指令设置的服务器名称在与被代理 HTTPS 服务器建立连接时通过 服务器名称指示 TLS 扩展(SNI,RFC 6066)的传递。

proxy_ssl_session_reuse#

语法

proxy_ssl_session_reuse on | off;

默认

proxy_ssl_session_reuse on;

上下文

http, server, location

确定在与被代理服务器工作时是否可以重用 SSL 会话。如果日志中出现错误 "SSL3_GET_FINISHED:digest check failed",请尝试禁用 会话重用

proxy_ssl_trusted_certificate#

语法

proxy_ssl_trusted_certificate file;

默认

上下文

http, server, location

指定一个文件,其中包含用于 验证 被代理 HTTPS 服务器证书的受信任 CA 证书,格式为 PEM。

proxy_ssl_verify#

语法

proxy_ssl_verify on | off;

默认

proxy_ssl_verify off;

上下文

http, server, location

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

proxy_ssl_verify_depth#

语法

proxy_ssl_verify_depth number;

默认

proxy_ssl_verify_depth 1;

上下文

http, server, location

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

proxy_store#

语法

proxy_store on | off | string;

默认

proxy_store off;

上下文

http, server, location

启用将文件保存到磁盘。

on

使用与指令 aliasroot 对应的路径保存文件

off

禁用文件保存

文件名可以通过带有变量的 string 显式设置:

proxy_store /data/www$original_uri;

文件的修改时间根据收到的“Last-Modified”响应头字段进行设置。响应首先被写入临时文件,然后该文件被重命名。临时文件和持久存储可以放在不同的文件系统上。然而,请注意,在这种情况下,文件是在两个文件系统之间复制,而不是简单的重命名操作。因此,建议对于任何给定的 location,保存的文件和由 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 用户:权限 ...;

默认

proxy_store_access user:rw;

上下文

http, server, location

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

proxy_store_access user:rw group:rw all:r;

如果指定了任何 groupall 访问权限,则可以省略用户权限:

proxy_store_access group:rw all:r;

proxy_temp_file_write_size#

语法

proxy_temp_file_write_size 大小;

默认

proxy_temp_file_write_size 8k|16k;

上下文

http, server, location

限制在启用从代理服务器到临时文件的响应缓冲时,每次写入临时文件的数据大小。默认情况下,大小由 proxy_buffer_sizeproxy_buffers 指令设置的两个缓冲区限制。临时文件的最大大小由 proxy_max_temp_file_size 指令设置。

proxy_temp_path#

语法

proxy_temp_path 路径 [级别1 [级别2 [级别3]]]`;

默认

proxy_temp_path proxy_temp; (路径取决于 --http-proxy-temp-path 构建选项

上下文

http, server, location

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

proxy_temp_path /spool/angie/proxy_temp 1 2;

临时文件可能如下所示:

/spool/angie/proxy_temp/7/45/00000123457

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

内置变量#

http_proxy 模块支持可用于使用 proxy_set_header 指令构造头的内置变量:

$proxy_host#

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

$proxy_port#

代理服务器的端口,如 proxy_pass 指令中指定的,或协议的默认端口;

$proxy_add_x_forwarded_for#

带有 $remote_addr 变量的“X-Forwarded-For”客户端请求头字段,二者之间用逗号分隔。如果客户端请求头中没有“X-Forwarded-For”字段,则 $proxy_add_x_forwarded_for 变量等于 $remote_addr 变量。