代理#

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

配置示例#

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

    proxy_cache       cache_zone;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404      1m;
}

指令#

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_size 和 proxy_buffers 指令设置的缓冲区中。如果整个响应无法放入内存,则可以将其一部分保存到磁盘上的 临时文件 中。写入临时文件由 proxy_max_temp_file_size 和 proxy_temp_file_write_size 指令控制。

off

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

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

如果 proxy_buffering 参数被禁用(off),Angie 不会缓存响应。

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_size 和 proxy_buffers 指令设置的两个缓冲区大小的限制。

proxy_cache#

语法

proxy_cache zone | off [path=path];

默认值

proxy_cache off;

上下文

http, server, location

定义用于缓存的共享内存区域。 同一个区域可以在多个地方使用。 参数值可以包含变量。

off

禁用从上一级配置继承的缓存。

在 Angie PRO 中,您可以指定多个使用相同 keys_zone 值的 proxy_cache_path 指令来启用`缓存分片`。这样做时,您应该设置使用此 keys_zone 值的 proxy_cache 指令的 path 参数:

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;
       proxy_cache_valid 200 10m;
   }
}

这里有两个缓存路径和一个用于区分它们的变量映射。 如果 Content-Type 以 text/ 开头,将选择第一个路径, 否则选择第二个。

备注

使用 proxy_cache 时, 通常还需要设置 proxy_cache_valid 指令 来明确指定响应的缓存时间。 如果未设置,Angie 不使用默认值, 而是根据来自服务器的 HTTP 响应头 按以下优先级顺序确定响应缓存时间:

  1. X-Accel-Expires 头(最高优先级)。

  2. 带有 max-age 或 s-maxage 参数的 Cache-Control 头。

  3. Expires 头。

如果这些头都不包含有效值或根本不存在, 响应将不会被缓存,因为无法确定其过期时间。

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" 以进行缓存。如果禁用转换,:ref:缓存键 <proxy_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#

语法

proxy_cache_max_range_offset number;

默认值

—

上下文

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

默认值

proxy_cache_min_uses 1;

上下文

http, server, location

设置在多少次请求后响应将被缓存。

警告

缓存元数据存储在共享内存中。手动删除缓存文件不会重置计数器，可能导致不可预测的行为。要完全重置，请停止服务器，删除缓存目录，然后重新启动。

备注

第三方缓存清除模块（例如 缓存清除）仅删除文件，但不会重置 proxy_cache_min_uses 计数器。该指令旨在保护缓存免受不频繁请求的污染，在清除时重置计数器可能会对性能产生负面影响。

proxy_cache_path#

语法

proxy_cache_path path [levels=levels] [use_temp_path=on | off] keys_zone=name:size[:file=file] [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

设置缓存的 path 和其他参数。缓存数据存储在文件中。缓存中的文件名是对 缓存键 应用 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

设置用于存储所有活动键和数据信息的共享内存区域的名称和大小。缓存元数据存储在共享内存中。

1 兆字节的区域足以存储约 8000 个键。

当使用 keys_zone 指定可选的 file 时， Angie 会在主进程终止时将该区域的内容转储到磁盘， 并在下次 启动 或 二进制升级 后 尝试在相同的内存地址恢复它， 以确保更可靠的数据持久性并减少缓存加载时间。

如果由于区域大小更改、二进制版本不兼容或其他原因而无法恢复该区域， Angie 将记录警告（failed to restore zone at address） 并且不会使用区域恢复机制。 相反，不兼容的文件将被重命名为 .old； 您可以删除它， 或恢复其名称并将 Angie 还原到最初创建此文件的配置和版本。

警告

确保正确指定 file 的路径， 并具有 Angie 使用所需的访问权限， 并受到保护以防止未经授权的访问； 相对路径基于 prefix。

inactive

如果在此参数指定的时间内未访问缓存数据，则无论其新鲜度如何，数据都将被删除。

默认情况下，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 参数指定的有限数量的项， 确保不超过 loader_threshold， 然后进行由 loader_sleep 定义的短暂暂停， 再继续处理下一批。 迭代会持续进行， 直到加载器处理完磁盘上所有现有的缓存条目：

loader_files

一次迭代中要加载的最大缓存项数

默认值：100

loader_threshold

限制一次迭代的持续时间

默认值：200 毫秒

loader_sleep

配置迭代之间的暂停时间

默认值：50 毫秒

备注

为 keys_zone 参数指定 file 不会影响缓存加载器的操作。

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 [code ...] time;

默认值

—

上下文

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

默认值

proxy_connect_timeout 60s;

上下文

http, server, location

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

proxy_connection_drop#

语法

proxy_connection_drop time | on | off;

默认值

proxy_connection_drop off;

上下文

http, server, location

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

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

设置 time 启用连接终止 超时； 设置为 on 时，连接将立即断开。

proxy_force_ranges#

语法

proxy_force_ranges on | 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_header 和 proxy_set_header 指令使用的哈希表的桶大小。哈希表设置的详细信息在 单独的文档 中提供。

proxy_headers_hash_max_size#

语法

proxy_headers_hash_max_size size;

默认值

proxy_headers_hash_max_size 512;

上下文

http, server, location

设置 proxy_hide_header 和 proxy_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 连接 一起使用。

proxy_http3_hq#

语法

proxy_http3_hq on | off;

默认值

proxy_http3_hq off;

上下文

http, server

切换特殊的 hq-interop 协商模式， 该模式用于 Angie 依赖的 QUIC 互操作性测试。

警告

仅在运行明确需要此模式的专门测试时启用此模式。

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 连接。

proxy_http3_max_table_capacity#

语法

proxy_http3_max_table_capacity number;

默认值

proxy_http3_max_table_capacity 4096;

上下文

http, server, location

设置代理连接的 动态表 容量。

备注

类似的指令 http3_max_table_capacity 为服务器连接设置此值。 为避免错误，在代理模式下启用缓存时 会禁用动态表的使用。

proxy_http3_stream_buffer_size#

语法

proxy_http3_stream_buffer_size size;

默认值

proxy_http3_stream_buffer_size 64k;

上下文

http, server

设置用于读取和写入 QUIC 流 的缓冲区的 大小。

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 同时打开两个到代理服务器的连接，总速率将是指定限制的两倍。该限制仅在启用来自代理服务器的响应 缓冲 时有效。

proxy_max_temp_file_size#

语法

proxy_max_temp_file_size size;

默认值

proxy_max_temp_file_size 1024m;

上下文

http, server, location

当启用来自代理服务器的响应 缓冲 时,如果整个响应无法放入 proxy_buffer_size 和 proxy_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 组中的下一个服务器：

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

通常,如果请求已发送到上游服务器,则不会将使用 非幂等 方法 （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 time;

默认值

proxy_next_upstream_timeout 0;

上下文

http, server, location

限制可以将请求传递给 下一个服务器 的时间。

0

禁用此限制

proxy_next_upstream_tries#

语法

proxy_next_upstream_tries number;

默认值

proxy_next_upstream_tries 0;

上下文

http, server, location

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

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, limit_except

设置代理服务器的协议和地址,以及一个可选的 URI,用于映射 location。协议可以指定为 http 或 https。地址可以指定为域名或 IP 地址,以及一个可选的端口：

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

或者指定为 UNIX 域套接字路径,在 unix 关键字之后,并用冒号括起来：

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

如果域名解析为多个地址,所有地址将以轮询方式使用。此外,地址还可以指定为 服务器组。

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

请求 URI 按以下方式传递给服务器:

  • 如果 proxy_pass 指令**带有 URI** 指定,那么当请求传递给服务器时,:ref:规范化 <location> 请求 URI 中与 location 匹配的部分将被指令中指定的 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;
}

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

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

在这些情况下,:samp:proxy_pass 应该不带 URI 指定。

  • 当在代理的 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 放置在前缀带有尾部斜杠的 location 中 (例如,:samp:location /name/), 并且 auto_redirect 指令设置为 default, 则不带尾部斜杠的请求将被重定向 (/name -> /name/)。

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_header 和 proxy_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_header 和 proxy_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 redirect replacement;

默认值

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/

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 也可以包含变量:

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

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

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

允许重新定义或追加字段到 传递 给代理服务器的请求头。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 on | off;

默认值

proxy_socket_keepalive off;

上下文

http, server, location

配置到代理服务器的出站连接的 "TCP keepalive" 行为。

off

默认情况下,套接字使用操作系统的设置。

on

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

proxy_ssl_certificate#

语法

proxy_ssl_certificate file [file];

默认值

—

上下文

http, server, location

指定一个包含 PEM 格式证书的文件,用于向代理 HTTPS 服务器进行身份验证。可以在文件名中使用变量。

当启用 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_cache#

语法

proxy_ssl_certificate_cache off;

proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];

默认值

proxy_ssl_certificate_cache off;

上下文

http, server, location

定义一个缓存,用于存储使用变量指定的 SSL 证书 和 私钥。

该指令支持以下参数:

  • max — 设置缓存中的最大元素数量。当缓存溢出时,将删除最近最少使用 (LRU) 的元素。

  • inactive — 定义元素在未被访问后被删除的时间。默认为 10 秒。

  • valid — 定义缓存元素被视为有效并可以重用的时间。默认为 60 秒。在此期间之后,证书将被重新加载或重新验证。

  • off — 禁用缓存。

示例:

proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;

proxy_ssl_certificate_key#

语法

proxy_ssl_certificate_key file [file];

默认值

—

上下文

http, server, location

指定一个包含 PEM 格式私钥的文件,用于向代理的 HTTPS 服务器进行身份验证。

可以指定值 engine:`name`:id 来代替文件,这将从名为 name 的 OpenSSL 引擎中加载具有指定 id 的私钥。

文件名中可以使用变量。

当启用 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 命令查看完整列表。

警告

当使用 OpenSSL 时,:samp:proxy_ssl_ciphers 指令*不*配置 TLS 1.3 的加密套件。要使用 OpenSSL 调整 TLS 1.3 加密套件,请使用 proxy_ssl_conf_command 指令,该指令是为支持高级 SSL 配置而添加的。

  • 在 LibreSSL 中,TLS 1.3 加密套件*可以*使用 proxy_ssl_ciphers 配置。

  • 在 BoringSSL 中,TLS 1.3 加密套件完全无法配置。

proxy_ssl_conf_command#

语法

proxy_ssl_conf_command name value;

默认值

—

上下文

http, server, location

在与代理的 HTTPS 服务器建立连接时设置任意 OpenSSL 配置 命令。

备注

当使用 OpenSSL 1.0.2 或更高版本时支持该指令。 要使用 OpenSSL 配置 TLS 1.3 加密套件,请使用 ciphersuites 命令。

可以在同一级别指定多个 proxy_ssl_conf_command 指令。当且仅当当前级别没有定义 proxy_ssl_conf_command 指令时,这些指令才会从上一级配置继承。

警告

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

proxy_ssl_crl#

语法

proxy_ssl_crl file;

默认值

—

上下文

http, server, location

指定一个包含 PEM 格式吊销证书 (CRL) 的文件,用于 验证 代理的 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#

语法

proxy_ssl_ntls on | off;

默认值

proxy_ssl_ntls off;

上下文

http, server

使用 TongSuo TLS 库启用客户端对 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;
}

备注

Angie 必须使用 --with-ntls 配置参数以及相应的支持 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

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

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

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

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

根据 alias 或 root 指令中指定的路径保存文件

off

禁用文件保存

文件名可以使用带变量的 string 显式设置：

proxy_store /data/www$original_uri;

文件的修改时间根据响应中接收到的 Last-Modified 头字段设置。响应首先写入临时文件，然后重命名该文件。临时文件和响应的持久存储可以位于不同的文件系统上。但是，请注意，在这种情况下，文件将从一个文件系统复制到另一个文件系统，而不是在一个文件系统内进行廉价的重命名操作。因此建议对于任何给定的位置，保存的文件和由 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 users:permissions ...;

默认值

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

默认值

proxy_temp_file_write_size 8k|16k;

上下文

http, server, location

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

proxy_temp_path#

语法

proxy_temp_path path [level1 [level2 [level3]]]`;

默认值

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#

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