# 代理 允许将请求传递到另一个(被代理的)服务器。 ## 配置示例 ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_bind` address [`transparent`] | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 使到被代理服务器的出站连接从指定的本地 IP 地址(可选端口)发起。参数值可以包含变量。特殊值 `off` 取消从上一级配置继承的 proxy_bind 指令的效果,允许系统自动分配本地 IP 地址和端口。 `transparent` 参数允许到被代理服务器的出站连接从非本地 IP 地址发起,例如,从客户端的真实 IP 地址: ```nginx proxy_bind $remote_addr transparent; ``` 为了使此参数生效,通常需要以 [超级用户](https://cn.angie.software//angie/docs/configuration/modules/core.md#user) 权限运行 Angie 工作进程。在 Linux 上不需要这样做,因为如果指定了 `transparent` 参数,工作进程会从主进程继承 CAP_NET_RAW 能力。 #### NOTE 需要配置内核路由表以拦截来自被代理服务器的网络流量。 ### proxy_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffer_size` size; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | `proxy_buffer_size 4k|8k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置用于读取从被代理服务器接收的响应的第一部分的缓冲区大小。这部分通常包含一个小的响应头。默认情况下,缓冲区大小等于一个内存页。根据平台不同,这可能是 4K 或 8K。但可以设置得更小。 ### proxy_buffering | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffering` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | `proxy_buffering on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用来自被代理服务器的响应的缓冲。 | `on` | Angie 尽快从被代理服务器接收响应,将其保存到由 [proxy_buffer_size](#proxy-buffer-size) 和 [proxy_buffers](#proxy-buffers) 指令设置的缓冲区中。向客户端发送会并行进行: 已填满的缓冲区会被交给发送,但总量不超过 [proxy_busy_buffers_size](#proxy-busy-buffers-size)。如果缓冲区未被完全填满,则不会被送去发送,除非这是响应的最后一部分。因此,当需要即时传输每隔几个字节时,缓冲读取模式并不适合。如果整个响应无法放入内存,则可以将其一部分保存到磁盘上的 [临时文件](#proxy-temp-path) 中。写入临时文件由 [proxy_max_temp_file_size](#proxy-max-temp-file-size) 和 [proxy_temp_file_write_size](#proxy-temp-file-write-size) 指令控制。 | |--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `off` | 响应在接收时立即传递给客户端。Angie 以"读取 — 发送"的循环工作,不会等待缓冲区被填满: 例如从 4K 缓冲区读取到 10 字节时就会立即发送。同时,如果整个响应可以放入缓冲区,Angie 也可能一次读完整。Angie 一次可以从服务器接收的数据的最大大小由 [proxy_buffer_size](#proxy-buffer-size) 指令设置。使用 `off` 时,Angie 不会缓存响应,并且 [proxy_limit_rate](#proxy-limit-rate) 不生效。 | 也可以通过在 `X-Accel-Buffering` 响应头字段中传递 "yes" 或 "no" 来启用或禁用缓冲。可以使用 [proxy_ignore_headers](#proxy-ignore-headers) 指令禁用此功能。 ### proxy_buffers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_buffers` number size; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `proxy_buffers 8 4k | 8k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置用于从被代理服务器读取响应的缓冲区的数量和大小,针对单个连接。 默认情况下,缓冲区大小等于一个内存页。根据平台不同,这可能是 4K 或 8K。 ### proxy_busy_buffers_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_busy_buffers_size` size; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `proxy_busy_buffers_size 8k | 16k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 当启用来自被代理服务器的响应的 [缓冲](#proxy-buffering) 时,限制在响应尚未完全读取时可以忙于向客户端发送响应的缓冲区的总大小。同时,其余的缓冲区可用于读取响应,如果需要,还可以将部分响应缓冲到临时文件中。 默认情况下,大小受 [proxy_buffer_size](#proxy-buffer-size) 和 [proxy_buffers](#proxy-buffers) 指令设置的两个缓冲区大小的限制。 ### proxy_cache | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache` zone | `off` [`path=`path]; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `proxy_cache off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义用于缓存的共享内存区域。 同一个区域可以在多个地方使用。 参数值可以包含变量。 | `off` | 禁用从上一级配置继承的缓存。 | |---------|------------------| 在 Angie PRO 中,您可以指定多个使用相同 `keys_zone` 值的 [proxy_cache_path](#proxy-cache-path) 指令来启用\`缓存分片\`。这样做时,您应该设置使用此 `keys_zone` 值的 [proxy_cache](#proxy-cache) 指令的 `path` 参数: | `path=`path | 该值在从后端\*缓存\*响应时进行评估,预期使用变量,包括那些包含来自响应的信息的变量。

如果响应从缓存中获取,则不会重新评估 path;
因此,缓存的响应保留其原始 path,
直到它从缓存中删除。 | |---------------|-------------------------------------------------------------------------------------------------------------------------| 这允许通过将 [map](https://cn.angie.software//angie/docs/configuration/modules/http/http_map.md#id3) 指令或脚本应用于来自后端的响应来选择所需的缓存路径。`Content-Type` 的示例: ```nginx 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/` 开头,将选择第一个路径, 否则选择第二个。 #### NOTE 使用 [proxy_cache](#proxy-cache) 时, 通常还需要设置 [proxy_cache_valid](#proxy-cache-valid) 指令 来明确指定响应的缓存时间。 如果未设置,Angie 不使用默认值, 而是根据来自服务器的 HTTP 响应头 按以下优先级顺序确定响应缓存时间: 1. `X-Accel-Expires` 头(最高优先级)。 2. 带有 `max-age` 或 `s-maxage` 参数的 `Cache-Control` 头。 3. `Expires` 头。 如果这些头都不包含有效值或根本不存在, 响应将不会被缓存,因为无法确定其过期时间。 ### proxy_cache_background_update | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_background_update` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------------------| | 默认值 | `proxy_cache_background_update off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许启动后台子请求来更新过期的缓存项,同时将陈旧的缓存响应返回给客户端。 #### WARNING 在更新陈旧缓存响应时使用它必须被 [允许](#proxy-cache-use-stale-updating)。 ### proxy_cache_bypass | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_bypass` ...; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义不从缓存中获取响应的条件。如果字符串参数中至少有一个值不为空且不等于 "0",则不会从缓存中获取响应: ```nginx proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; proxy_cache_bypass $http_pragma $http_authorization; ``` 可以与 [proxy_no_cache](#proxy-no-cache) 指令一起使用。 ### proxy_cache_convert_head | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_convert_head` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | `proxy_cache_convert_head on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用将 "HEAD" 方法转换为 "GET" 以进行缓存。如果禁用转换,:ref:缓存键 必须包含 [$request_method](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-request-method)。 ### proxy_cache_key | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_key` string; | |--------------------------------------------------------------------------------------|---------------------------------------------------| | 默认值 | `proxy_cache_key $scheme$proxy_host$request_uri;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义缓存的键,例如: ```nginx proxy_cache_key "$host$request_uri $cookie_user"; ``` 默认情况下,该指令的值接近于以下字符串 ```nginx proxy_cache_key $scheme$proxy_host$uri$is_args$args; ``` ### proxy_cache_lock | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `proxy_cache_lock off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用后,一次只允许一个请求通过向被代理服务器传递请求来填充根据 [proxy_cache_key](#proxy-cache-key) 指令标识的新缓存元素。对于相同缓存元素的其他请求将等待响应出现在缓存中,或者等待该元素的缓存锁被释放,最长等待时间由 [proxy_cache_lock_timeout](#proxy-cache-lock-timeout) 指令设置。 ### proxy_cache_lock_age | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock_age` time; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `proxy_cache_lock_age 5s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果传递给被代理服务器以填充新缓存元素的最后一个请求在指定时间内未完成,则可以再向被代理服务器传递一个请求。 ### proxy_cache_lock_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_lock_timeout` time; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `proxy_cache_lock_timeout 5s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置 [proxy_cache_lock](#proxy-cache-lock) 的超时时间。当超时时间到期时,请求将被传递给被代理服务器,但响应不会被缓存。 ### proxy_cache_max_range_offset | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_max_range_offset` number; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 为字节范围请求设置偏移量（以字节为单位）。如果范围超出指定的偏移量，范围请求将被传递到代理服务器，并且响应将不会被缓存。 ### proxy_cache_methods | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_methods` `GET` | `HEAD` | `POST` ...; | |--------------------------------------------------------------------------------------|------------------------------------------------------| | 默认值 | `proxy_cache_methods GET HEAD;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果客户端请求方法在此指令中列出，则响应将被缓存。"GET" 和 "HEAD" 方法始终会添加到列表中，但建议显式指定它们。另请参阅 [proxy_no_cache](#proxy-no-cache) 指令。 ### proxy_cache_min_uses | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_min_uses` number; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `proxy_cache_min_uses 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置在多少次请求后响应将被缓存。 #### WARNING 缓存元数据存储在共享内存中。手动删除缓存文件不会重置计数器，可能导致不可预测的行为。要完全重置，请停止服务器，删除缓存目录，然后重新启动。 #### NOTE 第三方缓存清除模块（例如 [缓存清除](https://cn.angie.software//angie/docs/installation/external-modules/cache-purge.md#external-cache-purge)）仅删除文件，但不会重置 proxy_cache_min_uses 计数器。该指令旨在保护缓存免受不频繁请求的污染，在清除时重置计数器可能会对性能产生负面影响。 ### proxy_cache_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `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]; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http | 设置缓存的 path 和其他参数。缓存数据存储在文件中。缓存中的文件名是对 [缓存键](#proxy-cache-key) 应用 MD5 函数的结果。 | `levels` | 定义缓存的层次结构级别：从 1 到 3，每个级别接受值 1 或 2。 | |------------|--------------------------------------| 例如，在以下配置中： ```nginx proxy_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m; ``` 缓存中的文件名将如下所示： ```nginx /data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c ``` 缓存的响应首先写入临时文件，然后重命名该文件。临时文件和缓存可以放在不同的文件系统上。但是，请注意，在这种情况下，文件将在两个文件系统之间复制，而不是执行廉价的重命名操作。因此，建议对于任何给定位置，将缓存和存放临时文件的目录放在同一文件系统上。 | `use_temp_path=on` | `off` | 确定用于临时文件的目录 | |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `on` | 如果未指定该参数或设置为 `on`，将使用给定 location 的 [proxy_temp_path](#proxy-temp-path) 指令指定的目录 | | `off` | 临时文件将直接放置在缓存目录中 | | `keys_zone` | 设置用于存储所有活动键和数据信息的共享内存区域的名称和大小。缓存元数据存储在共享内存中。

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

当使用 `keys_zone` 指定可选的 file 时，
Angie 会在主进程终止时将该区域的内容转储到磁盘，
并在下次 [启动](https://cn.angie.software//angie/docs/configuration/runtime.md#runtime) 或 [二进制升级](https://cn.angie.software//angie/docs/configuration/runtime.md#service-upgrade) 后
尝试在相同的内存地址恢复它，
以确保更可靠的数据持久性并减少缓存加载时间。

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

#### WARNING
确保正确指定 file 的路径，
并具有 Angie 使用所需的访问权限，
并受到保护以防止未经授权的访问；
相对路径基于 [prefix](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths)。 | | `inactive` | 如果在此参数指定的时间内未访问缓存数据，则无论其新鲜度如何，数据都将被删除。

默认情况下，`inactive` 为 10 分钟。 | #### NOTE #### Versionadded Added in version 1.2.0: PRO 在 Angie PRO 中，可以使用相同的 `keys_zone` 值指定多个 proxy_cache_path 指令。共享内存区域大小只能在第一个指令中指定。将根据相应 [proxy_cache](#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` 毫秒 | #### NOTE 为 `keys_zone` 参数指定 file 不会影响缓存加载器的操作。 ### proxy_cache_revalidate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_revalidate` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `proxy_cache_revalidate off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用使用带有 `If-Modified-Since` 和 `If-None-Match` 头字段的条件请求来重新验证过期的缓存项。 ### proxy_cache_use_stale | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `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;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定在哪些情况下可以使用过期的缓存响应。该指令的参数与 [proxy_next_upstream](#proxy-next-upstream) 指令的参数相匹配。 | `error` | 如果无法选择代理服务器来处理请求，则允许使用过期的缓存响应。 | |------------|-----------------------------------------------------------| | `updating` | 附加参数，如果缓存响应当前正在更新，则允许使用过期的缓存响应。这可以在更新缓存数据时最小化对代理服务器的访问次数。 | 也可以直接在响应头中启用使用过期的缓存响应，指定响应过期后的秒数： * `Cache-Control` 头字段的 [stale-while-revalidate](https://datatracker.ietf.org/doc/html/rfc5861#section-3) 扩展允许在缓存响应当前正在更新时使用过期的缓存响应。 * `Cache-Control` 头字段的 [stale-if-error](https://datatracker.ietf.org/doc/html/rfc5861#section-4) 扩展允许在发生错误时使用过期的缓存响应。 #### NOTE 这比使用指令参数的优先级更低。 要在填充新缓存元素时最小化对代理服务器的访问次数，可以使用 [proxy_cache_lock](#proxy-cache-lock) 指令。 ### proxy_cache_valid | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cache_valid` [code ...] time; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 为不同的响应代码设置缓存时间。例如，以下指令 ```nginx proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m; ``` 为代码 200 和 302 的响应设置 10 分钟的缓存时间，为代码 404 的响应设置 1 分钟的缓存时间。 如果只指定了缓存时间， ```nginx proxy_cache_valid 5m; ``` 则只缓存 200、301 和 302 响应。 此外，可以指定 `any` 参数来缓存任何响应： ```nginx proxy_cache_valid 200 302 10m; proxy_cache_valid 301 1h; proxy_cache_valid any 1m; ``` #### NOTE 缓存参数也可以直接在响应头中设置。这比使用指令设置缓存时间具有更高的优先级。 * `X-Accel-Expires` 头字段以秒为单位设置响应的缓存时间。零值会禁用响应的缓存。如果值以 `@` 前缀开头，则设置自 Epoch 以来的绝对时间（以秒为单位），直到该时间响应可以被缓存。 * 如果头中不包含 `X-Accel-Expires` 字段，则可以在 `Expires` 或 `Cache-Control` 头字段中设置缓存参数。 * 如果头中包含 `Set-Cookie` 字段，则不会缓存此类响应。 * 如果头中包含值为 "`*`" 的 `Vary` 字段，则不会缓存此类响应。如果头中包含其他值的 `Vary` 字段，则会考虑相应的请求头字段来缓存此类响应。 可以使用 [proxy_ignore_headers](#proxy-ignore-headers) 指令禁用对这些响应头字段中一个或多个的处理。 ### proxy_connect_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connect_timeout` time; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `proxy_connect_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义与被代理服务器建立连接的超时时间。需要注意的是，此超时时间通常不能超过 75 秒。 ### proxy_connection_drop | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_connection_drop` time | `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | `proxy_connection_drop off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用在被代理服务器从组中移除或被 [reresolve](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) 进程或 [API 命令](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-methods) `DELETE` 标记为永久不可用后，终止到该服务器的所有连接。 当为客户端或被代理服务器处理下一个读取或写入事件时，连接将被终止。 设置 time 启用连接终止 [超时](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)； 设置为 `on` 时，连接将立即断开。 ### proxy_cookie_domain | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_domain` `off`;

`proxy_cookie_domain` domain replacement; | |--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| | 默认值 | `proxy_cookie_domain off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置应在被代理服务器响应的 `Set-Cookie` 头字段的 domain 属性中更改的文本。假设被代理服务器返回的 `Set-Cookie` 头字段带有属性 "domain=localhost"。指令 ```nginx proxy_cookie_domain localhost example.org; ``` 将把此属性重写为 "domain=example.org"。 domain 和 replacement 字符串以及 domain 属性中的前导点将被忽略。该值不区分大小写。 domain 和 replacement 字符串可以包含变量： ```nginx proxy_cookie_domain www.$host $host; ``` 该指令也可以使用正则表达式指定。在这种情况下，domain 应以 "~" 符号开头。正则表达式可以包含命名捕获和位置捕获，replacement 可以引用它们： ```nginx proxy_cookie_domain ~\.(?P[-0-9a-z]+\.[a-z]+)$ $sl_domain; ``` 可以在同一级别指定多个 proxy_cookie_domain 指令： ```nginx proxy_cookie_domain localhost example.org; proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1; ``` 如果多个指令可以应用于 cookie，将选择第一个。 `off` 参数取消从上一级配置继承的 proxy_cookie_domain 指令的效果。 ### proxy_cookie_flags | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_flags` `off` | cookie [flag ...]; | |--------------------------------------------------------------------------------------|---------------------------------------------------| | 默认值 | `proxy_cookie_flags off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 为 cookie 设置一个或多个标志。cookie 可以包含文本、变量及其组合。标志可以包含文本、变量及其组合。 `secure`、`httponly`、`samesite=strict`、 `samesite=lax`、`samesite=none` 参数添加相应的标志。 `nosecure`、`nohttponly`、`nosamesite` 参数删除相应的标志。 cookie 也可以使用正则表达式指定。在这种情况下，cookie 应以 "~" 符号开头。 可以在同一配置级别指定多个 `proxy_cookie_flags` 指令： ```nginx proxy_cookie_flags one httponly; proxy_cookie_flags ~ nosecure samesite=strict; ``` 如果多个指令可以应用于 cookie，将选择第一个匹配的指令。在示例中，为 cookie `one` 添加 `httponly` 标志，对于所有其他 cookie 添加 `samesite=strict` 标志并删除 `secure` 标志。 `off` 参数取消从上一级配置继承的 proxy_cookie_flags 指令的效果。 ### proxy_cookie_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_cookie_path` `off`;

`proxy_cookie_path` path replacement; | |--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | 默认值 | `proxy_cookie_path off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置应在被代理服务器响应的 `Set-Cookie` 头字段的 path 属性中更改的文本。假设被代理服务器返回的 `Set-Cookie` 头字段带有属性 "path=/two/some/uri/"。指令 ```nginx proxy_cookie_path /two/ /; ``` 将把此属性重写为 "path=/some/uri/"。 path 和 replacement 字符串可以包含变量： ```nginx proxy_cookie_path $uri /some$uri; ``` 该指令也可以使用正则表达式指定。在这种情况下，path 应以 "~" 符号开头进行区分大小写的匹配，或以 "~\*" 符号开头进行不区分大小写的匹配。正则表达式可以包含命名捕获和位置捕获，replacement 可以引用它们： ```nginx proxy_cookie_path ~*^/user/([^/]+) /u/$1; ``` 可以在同一级别指定多个 proxy_cookie_path 指令： ```nginx proxy_cookie_path /one/ /; proxy_cookie_path / /two/; ``` 如果多个指令可以应用于 cookie，将选择第一个匹配的指令。 `off` 参数取消从上一级配置继承的 proxy_cookie_path 指令的效果。 ### proxy_force_ranges | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_force_ranges` `on` | `off`; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `proxy_force_ranges off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 无论被代理服务器响应中的 `Accept-Ranges` 字段如何，都为来自被代理服务器的缓存和非缓存响应启用字节范围支持。 ### proxy_headers_hash_bucket_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_headers_hash_bucket_size` size; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `proxy_headers_hash_bucket_size 64;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置 [proxy_hide_header](#proxy-hide-header) 和 [proxy_set_header](#proxy-set-header) 指令使用的哈希表的桶大小。哈希表设置的详细信息在 [单独的文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes) 中提供。 ### proxy_headers_hash_max_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_headers_hash_max_size` size; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `proxy_headers_hash_max_size 512;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置 [proxy_hide_header](#proxy-hide-header) 和 [proxy_set_header](#proxy-set-header) 指令使用的哈希表的最大大小。哈希表设置的详细信息在 [单独的文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes) 中提供。 ### proxy_hide_header | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_hide_header` field; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 默认情况下，Angie 不会将被代理服务器响应中的 `Date`、`Server`、`X-Pad` 和 `X-Accel-...` 头字段传递给客户端。proxy_hide_header 指令设置不会被传递的附加字段。相反，如果需要允许传递字段，可以使用 [proxy_pass_header](#proxy-pass-header) 指令。 ### proxy_http_version | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http_version` `1.0` | `1.1` | `3`; | |--------------------------------------------------------------------------------------|------------------------------------------------------| | 默认值 | `proxy_http_version 1.0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location, limit_except | 设置代理的 HTTP 协议版本。 默认使用 1.0 版本。 建议使用 1.1 或更高版本 与 [keepalive 连接](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive) 一起使用。 ### proxy_http3_hq | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_hq` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `proxy_http3_hq off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 切换特殊的 `hq-interop` 协商模式， 该模式用于 Angie 依赖的 [QUIC](#proxy-http-version) [互操作性测试](https://github.com/marten-seemann/quic-interop-runner)。 #### WARNING 仅在运行明确需要此模式的专门测试时启用此模式。 ### proxy_http3_max_concurrent_streams | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_max_concurrent_streams` number; | |--------------------------------------------------------------------------------------|------------------------------------------------| | 默认值 | `proxy_http3_max_concurrent_streams 128;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 初始化 HTTP/3 和 QUIC 设置， 并设置 [连接](#proxy-http-version) 中并发 HTTP/3 请求流的最大数量。 需要启用 [keepalive 连接](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-keepalive)。 ### proxy_http3_max_table_capacity | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_max_table_capacity` number; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | `proxy_http3_max_table_capacity 4096;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置代理连接的 [动态表](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table) 容量。 #### NOTE 类似的指令 [http3_max_table_capacity](https://cn.angie.software//angie/docs/configuration/modules/http/http_v3.md#http3-max-table-capacity) 为服务器连接设置此值。 为避免错误，在代理模式下启用缓存时 会禁用动态表的使用。 ### proxy_http3_stream_buffer_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_http3_stream_buffer_size` size; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `proxy_http3_stream_buffer_size 64k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置用于读取和写入 [QUIC 流](#proxy-http-version) 的缓冲区的 [大小](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax)。 ### proxy_ignore_client_abort | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ignore_client_abort` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `proxy_ignore_client_abort off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 决定当客户端在未等待响应的情况下关闭连接时，是否应关闭与被代理服务器的连接。 ### proxy_ignore_headers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ignore_headers` field ...; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | 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` 设置响应 [缓存](#proxy-cache-valid) 的参数； * `X-Accel-Redirect` 执行到指定 URI 的 [内部重定向](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#internal)； * `X-Accel-Limit-Rate` 设置向客户端传输响应的 [速率限制](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate)； * `X-Accel-Buffering` 启用或禁用响应的 [缓冲](#proxy-buffering)； * `X-Accel-Charset` 设置响应所需的 [字符集](https://cn.angie.software//angie/docs/configuration/modules/http/http_charset.md#id3)。 ### proxy_intercept_errors | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_intercept_errors` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `proxy_intercept_errors off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定状态码大于或等于 300 的代理响应应该传递给客户端，还是被拦截并重定向到 Angie 以使用 [error_page](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#error-page) 指令进行处理。 ### proxy_limit_rate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_limit_rate` rate; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `proxy_limit_rate 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制从代理服务器读取响应的速度。 rate 以每秒字节数指定；允许使用变量。 | `0` | 禁用速率限制 | |-------|----------| #### NOTE 该限制是针对每个请求设置的，因此如果 Angie 同时打开两个到代理服务器的连接，总速率将是指定限制的两倍。该限制仅在启用来自代理服务器的响应 [缓冲](#proxy-buffering) 时有效。 ### proxy_max_temp_file_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_max_temp_file_size` size; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `proxy_max_temp_file_size 1024m;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 当启用来自代理服务器的响应 [缓冲](#proxy-buffering) 时,如果整个响应无法放入 [proxy_buffer_size](#proxy-buffer-size) 和 [proxy_buffers](#proxy-buffers) 指令设置的缓冲区中,响应的一部分可以保存到临时文件中。此指令设置临时文件的最大大小。一次写入临时文件的数据大小由 [proxy_temp_file_write_size](#proxy-temp-file-write-size) 指令设置。 | `0` | 禁用将响应缓冲到临时文件 | |-------|----------------| #### NOTE 此限制不适用于将被 [缓存](#proxy-cache) 或 [存储](#proxy-store) 到磁盘的响应。 ### proxy_method | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_method` method; | |--------------------------------------------------------------------------------------|--------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定在转发到代理服务器的请求中使用的 HTTP 方法,而不是来自客户端请求的方法。参数值可以包含变量。 ### proxy_next_upstream | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `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;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定在哪些情况下应将请求传递给 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-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` | 通常,如果请求已发送到上游服务器,则不会将使用 [非幂等](https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2) 方法
（`POST`、`LOCK`、`PATCH`）的请求传递给下一个
服务器；启用此选项将明确允许重试此类请求； | | `off` | 禁用将请求传递给下一个服务器。 | #### NOTE 应该理解,只有在尚未向客户端发送任何内容时,才可能将请求传递给下一个服务器。也就是说,如果在传输响应的过程中发生错误或超时,则无法修复此问题。 该指令还定义了什么被视为与服务器通信的 [不成功尝试](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails)。 | `error`

`timeout`

`invalid_header` | 始终被视为不成功尝试,即使它们未在指令中指定 | |--------------------------------------------------------------------------------------------|--------------------------| | `http_500`

`http_502`

`http_503`

`http_504`

`http_429` | 仅在指令中指定时才被视为不成功尝试 | | `http_403`

`http_404` | 永远不会被视为不成功尝试 | 将请求传递给下一个服务器可以通过 [尝试次数](#proxy-next-upstream-tries) 和 [时间](#proxy-next-upstream-timeout) 进行限制。 ### proxy_next_upstream_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_timeout` time; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `proxy_next_upstream_timeout 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制可以将请求传递给 [下一个服务器](#proxy-next-upstream) 的时间。 | `0` | 禁用此限制 | |-------|---------| ### proxy_next_upstream_tries | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_next_upstream_tries` number; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `proxy_next_upstream_tries 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 限制将请求传递给 [下一个服务器](#proxy-next-upstream) 的可能尝试次数。 | `0` | 禁用此限制 | |-------|---------| ### proxy_no_cache | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_no_cache` string ...; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义响应不被保存到缓存的条件。如果字符串参数中至少有一个值不为空且不等于"0",则响应将不会被保存： ```nginx proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; proxy_no_cache $http_pragma $http_authorization; ``` 可以与 [proxy_cache_bypass](#proxy-cache-bypass) 指令一起使用。 ### proxy_pass | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass` uri; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location, if in location, limit_except | 设置代理服务器的协议和地址,以及一个可选的 URI,用于映射 location。协议可以指定为 `http` 或 `https`。地址可以指定为域名或 IP 地址,以及一个可选的端口： ```nginx proxy_pass http://localhost:8000/uri/; ``` 或者指定为 UNIX 域套接字路径,在 `unix` 关键字之后,并用冒号括起来： ```nginx proxy_pass http://unix:/tmp/backend.socket:/uri/; ``` 如果域名解析为多个地址,所有地址将以轮询方式使用。此外,地址还可以指定为 [服务器组](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream)。 参数值可以包含变量。在这种情况下,如果地址指定为域名,则会在已描述的服务器组中搜索该名称,如果未找到,则使用 [resolver](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver) 来确定。 请求 URI 按以下方式传递给服务器: * 如果 `proxy_pass` 指令\*\*带有 URI\*\* 指定,那么当请求传递给服务器时,:ref:规范化 请求 URI 中与 location 匹配的部分将被指令中指定的 URI 替换: ```nginx location /name/ { proxy_pass http://127.0.0.1/remote/; } ``` * 如果 `proxy_pass` **不带 URI** 指定,则在处理原始请求时,请求 URI 以客户端发送的相同形式传递给服务器,或者在处理更改后的 URI 时传递完整的规范化请求 URI: ```nginx location /some/path/ { proxy_pass http://127.0.0.1; } ``` 在某些情况下,无法确定要替换的请求 URI 部分: * 当 `location` 使用正则表达式指定时,以及在命名 `location` 内部。 在这些情况下,:samp:proxy_pass 应该不带 URI 指定。 * 当在代理的 `location` 内部使用 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 指令更改 URI 时,并且将使用此相同配置来处理请求 (break): ```nginx location /name/ { rewrite /name/([^/]+) /users?name=$1 break; proxy_pass http://127.0.0.1; } ``` 在这种情况下,指令中指定的 URI 将被忽略,完整的更改后的请求 URI 将传递给服务器。 * 当在 `proxy_pass` 中使用变量时: ```nginx location /name/ { proxy_pass http://127.0.0.1$request_uri; } ``` 在这种情况下,如果在指令中指定了 URI,它将按原样传递给服务器,替换原始请求 URI。 [WebSocket](https://cn.angie.software//angie/docs/configuration/processing.md#websocket-proxy) 代理需要特殊配置。 #### NOTE 如果 `proxy_pass` 放置在前缀带有尾部斜杠的 `location` 中 (例如,:samp:location /name/), 并且 [auto_redirect](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) 指令设置为 `default`, 则不带尾部斜杠的请求将被重定向 (`/name -> /name/`)。 ### proxy_pass_header | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_header` field ...; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许将代理服务器的 [原本禁用](#proxy-hide-header) 的头字段传递给客户端。 ### proxy_pass_request_body | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_request_body` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | `proxy_pass_request_body on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指示是否将原始请求正文传递给代理服务器。 ```nginx location /x-accel-redirect-here/ { proxy_method GET; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_pass ...; } ``` 另请参阅 [proxy_set_header](#proxy-set-header) 和 [proxy_pass_request_headers](#proxy-pass-request-headers) 指令。 ### proxy_pass_request_headers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_request_headers` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------------------| | 默认值 | `proxy_pass_request_headers on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指示是否将原始请求的头字段传递给代理服务器。 ```nginx location /x-accel-redirect-here/ { proxy_method GET; proxy_pass_request_headers off; proxy_pass_request_body off; proxy_pass ...; } ``` 另请参阅 [proxy_set_header](#proxy-set-header) 和 [proxy_pass_request_body](#proxy-pass-request-body) 指令。 ### proxy_pass_trailers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_pass_trailers` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `proxy_pass_trailers off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许将代理服务器的尾部字段传递给客户端。 HTTP/1.1 中的尾部部分需要 [显式启用](https://datatracker.ietf.org/doc/html/rfc9110#section-6.5.1)。 ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_active_connection_id_limit` number; | |--------------------------------------------------------------------------------------|---------------------------------------------------| | 默认值 | `proxy_quic_active_connection_id_limit 2;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置 [QUIC](#proxy-http-version) `active_connection_id_limit` 传输参数值。 这是每个服务器可以维护的最大活动 [连接 ID](https://www.rfc-editor.org/rfc/rfc9000.html#name-connection-id) 数量。 ### proxy_quic_gso | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_gso` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `proxy_quic_gso off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 切换使用 [通用分段卸载](https://docs.kernel.org/networking/segmentation-offloads.html#generic-segmentation-offload) 以 [QUIC](#proxy-http-version) 优化批处理模式发送数据。 ### proxy_quic_host_key | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_quic_host_key` file; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 设置一个包含密钥的 file, 该密钥与 [QUIC](#proxy-http-version) 一起使用来加密 [无状态重置](https://www.rfc-editor.org/rfc/rfc9000.html#name-stateless-reset) 和 [地址验证](https://www.rfc-editor.org/rfc/rfc9000.html#address-validation) 令牌。 默认情况下,每次重启时都会生成一个随机密钥。 使用旧密钥生成的令牌不被接受。 ### proxy_read_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_read_timeout` time; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `proxy_read_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义从代理服务器读取响应的超时时间。超时仅在两次连续读取操作之间设置,而不是用于整个响应的传输。如果代理服务器在此时间内未传输任何内容,则连接将关闭。 ### proxy_redirect | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_redirect` `default`;

`proxy_redirect` `off`;

`proxy_redirect` redirect replacement; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | 默认值 | `proxy_redirect default;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置应在代理服务器响应的 "Location" 和 "Refresh" 头字段中更改的文本。 假设代理服务器返回了头字段: ```console Location: http://localhost:8000/two/some/uri/ ``` 指令 ```nginx proxy_redirect http://localhost:8000/two/ http://frontend/one/; ``` 将把此字符串重写为: ```console Location: http://frontend/one/some/uri/ ``` replacement 字符串中可以省略服务器名称: ```nginx proxy_redirect http://localhost:8000/two/ /; ``` 然后将插入主服务器的名称和端口(如果不是 80)。 由 `default` 参数指定的默认替换使用 [location](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#location) 和 [proxy_pass](#proxy-pass) 指令的参数。因此,以下两个配置是等效的: ```nginx location /one/ { proxy_pass http://upstream:port/two/; proxy_redirect default; } ``` ```nginx location /one/ { proxy_pass http://upstream:port/two/; proxy_redirect http://upstream:port/two/ /one/; } ``` #### WARNING 如果 [proxy_pass](#proxy-pass) 使用变量指定,则不允许使用 `default` 参数。 replacement 字符串可以包含变量: ```nginx proxy_redirect http://localhost:8000/ http://$host:$server_port/; ``` redirect 也可以包含变量: ```nginx proxy_redirect http://$proxy_host:8000/ /; ``` 该指令可以使用正则表达式指定。在这种情况下,\`redirect\` 应该以 "~" 符号开头表示区分大小写的匹配,或者以 "~\*" 符号开头表示不区分大小写的匹配。正则表达式可以包含命名捕获和位置捕获,\`replacement\` 可以引用它们: ```nginx proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2; proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2; ``` 可以在同一级别指定多个 proxy_redirect 指令: ```nginx proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /; ``` 如果多个指令可以应用于代理服务器响应的头字段,将选择第一个匹配的指令。 `off` 参数取消从上一级配置继承的 proxy_redirect 指令的效果。 使用此指令,还可以向代理服务器发出的相对重定向添加主机名: ```nginx proxy_redirect / /; ``` ### proxy_request_buffering | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_request_buffering` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | `proxy_request_buffering on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用客户端请求体的缓冲。 | `on` | 在将请求发送到代理服务器之前,从客户端 [读取](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#client-body-buffer-size) 整个请求体。 | |--------|--------------------------------------------------------------------------------------------------------------------------------------| | `off` | 请求体在接收时立即发送到代理服务器。在这种情况下,如果 Angie 已经开始发送请求体,则无法将请求传递到 [下一个服务器](#proxy-next-upstream)。 | 当使用 HTTP/1.1 分块传输编码发送原始请求体时,无论指令值如何,请求体都将被缓冲,除非为代理 [启用](#proxy-http-version) HTTP/1.1。 ### proxy_send_lowat | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_send_lowat` size; | |--------------------------------------------------------------------------------------|----------------------------| | 默认值 | `proxy_send_lowat 0;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 如果该指令设置为非零值,Angie 将尝试通过使用 [kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue) 方法的 NOTE_LOWAT 标志或 SO_SNDLOWAT 套接字选项,以指定的大小最小化到代理服务器的出站连接上的发送操作数量。 #### NOTE 此指令在 Linux、Solaris 和 Windows 上被忽略。 ### proxy_send_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_send_timeout` time; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `proxy_send_timeout 60s;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置向代理服务器传输请求的超时时间。超时仅在两次连续的写操作之间设置,而不是用于整个请求的传输。如果代理服务器在此时间内没有接收到任何内容,连接将被关闭。 ### proxy_set_body | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_set_body` value; | |--------------------------------------------------------------------------------------|---------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许重新定义传递给代理服务器的请求体。该值可以包含文本、变量及其组合。 ### proxy_set_header | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_set_header` field value; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `proxy_set_header Host $proxy_host;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许重新定义或追加字段到 [传递](#proxy-pass-request-headers) 给代理服务器的请求头。value 可以包含文本、变量及其组合。当且仅当当前级别没有定义 proxy_set_header 指令时,这些指令才从上一级配置继承。默认情况下,只重新定义两个字段: ```nginx 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" 请求头字段: ```nginx proxy_set_header Host $http_host; ``` 但是,如果客户端请求头中不存在此字段,则不会传递任何内容。在这种情况下,最好使用 [$host](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-host) 变量 - 它的值等于 "Host" 请求头字段中的服务器名称,或者如果此字段不存在则为主服务器名称: ```nginx proxy_set_header Host $host; ``` 此外,服务器名称可以与代理服务器的端口一起传递: ```nginx proxy_set_header Host $host:$proxy_port; ``` 如果头字段的值为空字符串,则此字段不会传递给代理服务器: ```nginx proxy_set_header Accept-Encoding ""; ``` ### proxy_socket_keepalive | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_socket_keepalive` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------------| | 默认值 | `proxy_socket_keepalive off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 配置到代理服务器的出站连接的 "TCP keepalive" 行为。 | `off` | 默认情况下,套接字使用操作系统的设置。 | |---------|----------------------------| | `on` | 为套接字打开 SO_KEEPALIVE 套接字选项。 | ### proxy_ssl_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate` file [file]; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 PEM 格式证书的文件,用于向代理 HTTPS 服务器进行身份验证。可以在文件名中使用变量。 当启用 [proxy_ssl_ntls](#proxy-ssl-ntls) 时,该指令接受两个参数而不是一个: ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_cache` `off`;

`proxy_ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time]; | |--------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| | 默认值 | `proxy_ssl_certificate_cache off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义一个缓存,用于存储使用变量指定的 [SSL 证书](#proxy-ssl-certificate) 和 [私钥](#proxy-ssl-certificate-key)。 该指令支持以下参数: - `max` — 设置缓存中的最大元素数量。当缓存溢出时,将删除最近最少使用 (LRU) 的元素。 - `inactive` — 定义元素在未被访问后被删除的时间。默认为 10 秒。 - `valid` — 定义缓存元素被视为有效并可以重用的时间。默认为 60 秒。在此期间之后,证书将被重新加载或重新验证。 - `off` — 禁用缓存。 示例: ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_certificate_key` file [file]; | |--------------------------------------------------------------------------------------|--------------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 PEM 格式私钥的文件,用于向代理的 HTTPS 服务器进行身份验证。 可以指定值 `engine:`name`:id` 来代替文件,这将从名为 name 的 OpenSSL 引擎中加载具有指定 id 的私钥。 文件名中可以使用变量。 当启用 [proxy_ssl_ntls](#proxy-ssl-ntls) 时,该指令接受两个参数而不是一个: ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ciphers` ciphers; | |--------------------------------------------------------------------------------------|--------------------------------| | 默认值 | `proxy_ssl_ciphers DEFAULT;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定向代理的 HTTPS 服务器发送请求时启用的加密套件。加密套件以 OpenSSL 库能够理解的格式指定。 加密套件列表取决于安装的 OpenSSL 版本。 可以使用 `openssl ciphers` 命令查看完整列表。 #### WARNING 当使用 OpenSSL 时,:samp:proxy_ssl_ciphers 指令\*不\*配置 TLS 1.3 的加密套件。要使用 OpenSSL 调整 TLS 1.3 加密套件,请使用 [proxy_ssl_conf_command](#proxy-ssl-conf-command) 指令,该指令是为支持高级 SSL 配置而添加的。 - 在 LibreSSL 中,TLS 1.3 加密套件\*可以\*使用 `proxy_ssl_ciphers` 配置。 - 在 BoringSSL 中,TLS 1.3 加密套件完全无法配置。 ### proxy_ssl_conf_command | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_conf_command` name value; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 在与代理的 HTTPS 服务器建立连接时设置任意 OpenSSL 配置 [命令](https://docs.openssl.org/master/man3/SSL_CONF_cmd/)。 #### NOTE 当使用 OpenSSL 1.0.2 或更高版本时支持该指令。 要使用 OpenSSL 配置 TLS 1.3 加密套件,请使用 `ciphersuites` 命令。 可以在同一级别指定多个 proxy_ssl_conf_command 指令。当且仅当当前级别没有定义 proxy_ssl_conf_command 指令时,这些指令才会从上一级配置继承。 #### WARNING 请注意,直接配置 OpenSSL 可能会导致意外行为。 ### proxy_ssl_crl | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_crl` file; | |--------------------------------------------------------------------------------------|-------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 PEM 格式吊销证书 (CRL) 的文件,用于 [验证](#proxy-ssl-verify) 代理的 HTTPS 服务器的证书。 ### proxy_ssl_name | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_name` name; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | `proxy_ssl_name $proxy_host;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 允许覆盖用于 [验证](#proxy-ssl-verify) 代理的 HTTPS 服务器证书的服务器名称,以及在与代理的 HTTPS 服务器建立连接时 [通过 SNI 传递](#proxy-ssl-server-name) 的服务器名称。 默认情况下,使用 [proxy_pass](#proxy-pass) URL 的主机部分。 ### proxy_ssl_ntls | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_ntls` `on` | `off`; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | `proxy_ssl_ntls off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server | 使用 [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS 库启用客户端对 NTLS 的支持。 ```nginx 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; } ``` #### NOTE Angie 必须使用 `--with-ntls` 配置参数以及相应的支持 NTLS 的 SSL 库进行构建 ```default ./configure --with-openssl=../Tongsuo-8.3.0 \ --with-openssl-opt=enable-ntls \ --with-ntls ``` ### proxy_ssl_password_file | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_password_file` file; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 [私钥](#proxy-ssl-certificate-key) 密码短语的文件,每个密码短语单独占一行。加载密钥时会依次尝试这些密码短语。 ### proxy_ssl_protocols | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| | 默认值 | `proxy_ssl_protocols TLSv1.2 TLSv1.3;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | #### Versionchanged 在 1.2.0 版本发生变更: `TLSv1.3` 参数已添加到默认设置中。 启用向代理的 HTTPS 服务器发送请求时使用的指定协议。 ### proxy_ssl_server_name | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_server_name` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------------| | 默认值 | `proxy_ssl_server_name off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用在与代理的 HTTPS 服务器建立连接时，通过 [服务器名称指示](http://en.wikipedia.org/wiki/Server_Name_Indication) TLS 扩展（SNI，[RFC 6066](https://datatracker.ietf.org/doc/html/rfc6066.html)）传递由 [proxy_ssl_name](#proxy-ssl-name) 指令设置的服务器名称。 ### proxy_ssl_session_reuse | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_session_reuse` `on` | `off`; | |--------------------------------------------------------------------------------------|-------------------------------------------| | 默认值 | `proxy_ssl_session_reuse on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 确定在与代理服务器通信时是否可以重用 SSL 会话。如果日志中出现错误 "SSL3_GET_FINISHED:digest check failed"，请尝试禁用会话重用。 ### proxy_ssl_trusted_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_trusted_certificate` file; | |--------------------------------------------------------------------------------------|-----------------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 指定一个包含 PEM 格式受信任 CA 证书的文件，用于 [验证](#proxy-ssl-verify) 代理的 HTTPS 服务器的证书。 ### proxy_ssl_verify | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify` `on` | `off`; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `proxy_ssl_verify off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用或禁用对代理的 HTTPS 服务器证书的验证。 ### proxy_ssl_verify_depth | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_ssl_verify_depth` number; | |--------------------------------------------------------------------------------------|------------------------------------| | 默认值 | `proxy_ssl_verify_depth 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置代理的 HTTPS 服务器证书链中的验证深度。 ### proxy_store | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_store` `on` | `off` | string; | |--------------------------------------------------------------------------------------|----------------------------------------| | 默认值 | `proxy_store off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 启用将文件保存到磁盘。 | `on` | 根据 [alias](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#alias) 或 [root](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#root) 指令中指定的路径保存文件 | |--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `off` | 禁用文件保存 | 文件名可以使用带变量的 `string` 显式设置： ```nginx proxy_store /data/www$original_uri; ``` 文件的修改时间根据响应中接收到的 `Last-Modified` 头字段设置。响应首先写入临时文件，然后重命名该文件。临时文件和响应的持久存储可以位于不同的文件系统上。但是，请注意，在这种情况下，文件将从一个文件系统复制到另一个文件系统，而不是在一个文件系统内进行廉价的重命名操作。因此建议对于任何给定的位置，保存的文件和由 [proxy_temp_path](#proxy-temp-path) 指令设置的临时文件目录都放在同一个文件系统上。 此指令可用于创建静态不可变文件的本地副本，例如： ```nginx 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/; } ``` 或者像这样： ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_store_access` users:permissions ...; | |--------------------------------------------------------------------------------------|-----------------------------------------------| | 默认值 | `proxy_store_access user:rw;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 设置新创建的文件和目录的访问权限，例如： ```nginx proxy_store_access user:rw group:rw all:r; ``` 如果指定了任何 `group` 或 `all` 访问权限，则可以省略 `user` 权限： ```nginx proxy_store_access group:rw all:r; ``` ### proxy_temp_file_write_size | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_temp_file_write_size` size; | |--------------------------------------------------------------------------------------|--------------------------------------| | 默认值 | `proxy_temp_file_write_size 8k|16k;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 当启用将代理服务器的响应缓冲到临时文件时，限制一次写入临时文件的数据大小。默认情况下，大小受 [proxy_buffer_size](#proxy-buffer-size) 和 [proxy_buffers](#proxy-buffers) 指令设置的两个缓冲区限制。临时文件的最大大小由 [proxy_max_temp_file_size](#proxy-max-temp-file-size) 指令设置。 ### proxy_temp_path | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `proxy_temp_path` path [level1 [level2 [level3]]]\`; | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | 默认值 | `proxy_temp_path proxy_temp;`
(路径取决于 [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-proxy-temp-path`) | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location | 定义用于存储从代理服务器接收的数据的临时文件的目录。在指定目录下可以使用最多三级子目录层次结构。例如，在以下配置中 ```nginx proxy_temp_path /spool/angie/proxy_temp 1 2; ``` 临时文件可能如下所示： ```nginx /spool/angie/proxy_temp/7/45/00000123457 ``` 另请参阅 [proxy_cache_path](#proxy-cache-path) 指令的 `use_temp_path` 参数。 ## 内置变量 http_proxy 模块支持内置变量，可用于使用 [proxy_set_header](#proxy-set-header) 指令组合头部： ### `$proxy_host` [proxy_pass](#proxy-pass) 指令中指定的被代理服务器的名称和端口； ### `$proxy_port` [proxy_pass](#proxy-pass) 指令中指定的被代理服务器的端口，或协议的默认端口； ### `$proxy_add_x_forwarded_for` 客户端请求头字段 `X-Forwarded-For` 附加 [$remote_addr](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) 变量后的值，以逗号分隔。如果客户端请求头中不存在 `X-Forwarded-For` 字段，则 [$proxy_add_x_forwarded_for](#v-proxy-add-x-forwarded-for) 变量等于 [$remote_addr](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-remote-addr) 变量。