Module ngx_http_proxy_module

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

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

使到代理服务器的传出连接从指定的本地 IP 地址发起，可选择包含端口（1.11.2）。参数值可以包含变量（1.3.12）。特殊值 off (1.3.12) 取消继承自上一配置级别的 proxy_bind 指令效果，从而允许系统自动分配本地 IP 地址和端口。

transparent 参数（1.11.0）允许到代理服务器的传出连接从非本地 IP 地址发起，例如，从客户端的真实 IP 地址发起。

proxy_bind $remote_addr transparent;

为了使此参数生效，通常需要以 超级用户 权限运行 nginx 工作进程。在 Linux 上则不需要（1.13.8），因为如果指定了 transparent 参数，工作进程会从主进程继承 CAP_NET_RAW 能力。此外，还需要配置内核路由表以拦截来自代理服务器的网络流量。

proxy_buffer_size 4k|8k;

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

proxy_buffering on;

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

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

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

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

proxy_buffers 8 4k|8k;

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

proxy_busy_buffers_size 8k|16k;

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

proxy_cache off;

定义用于缓存的共享内存区域。同一区域可以在多个位置使用。参数值可以包含变量（1.7.9）。参数 off 禁用继承自上一配置级别的缓存。

proxy_cache_background_update off;

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

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

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

可以与 proxy_no_cache 指令一起使用。

proxy_cache_convert_head on;

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

proxy_cache_key $scheme$proxy_host$request_uri;

定义缓存键，例如：

proxy_cache_key "$host$request_uri $cookie_user";

默认情况下，此指令的值接近于以下字符串：

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

proxy_cache_lock off;

启用后，一次只允许一个请求通过向代理服务器发送请求来填充由 proxy_cache_key 指令标识的新缓存元素。同一缓存元素的其他请求将等待响应出现在缓存中或此元素的缓存锁被释放，最长等待时间由 proxy_cache_lock_timeout 指令设置。

proxy_cache_lock_age 5s;

如果最后一次发送到代理服务器用于填充新缓存元素的请求在指定 time（时间）内未完成，则可能会再发送一个请求到代理服务器。

proxy_cache_lock_timeout 5s;

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

在 1.7.8 之前，响应可能会被缓存。

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

proxy_cache_methods GET HEAD;

如果客户端请求方法在此指令中列出，则响应将被缓存。“GET”和“HEAD”方法总是添加到列表中，但建议显式指定它们。另请参阅 proxy_no_cache 指令。

proxy_cache_min_uses 1;

设置响应在多少个请求后将被缓存的 number（次数）。

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

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

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

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

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

此外，所有活动键和数据信息存储在共享内存区域中，其 name（名称）和 size（大小）由 keys_zone 参数配置。一兆字节的区域可以存储大约 8 千个键。

作为商业订阅的一部分，共享内存区域也存储扩展的缓存信息，因此，对于相同数量的键，需要指定更大的区域大小。例如，一兆字节的区域可以存储大约 4 千个键。

在 inactive 参数指定的时间内未被访问的缓存数据将从缓存中移除，无论其新鲜度如何。默认情况下，inactive 设置为 10 分钟。

特殊的“缓存管理器”进程监控由 max_size 参数设置的最大缓存大小，以及由 min_free（1.19.1）参数设置的缓存文件系统上的最小可用空间量。当大小超出限制或可用空间不足时，它会移除最近最少使用的数据。数据通过由 manager_files、manager_threshold 和 manager_sleep 参数（1.11.5）配置的迭代方式移除。在一个迭代中，删除的项目不超过 manager_files（默认为 100）。一个迭代的持续时间由 manager_threshold 参数限制（默认为 200 毫秒）。在迭代之间，会进行由 manager_sleep 参数配置的暂停（默认为 50 毫秒）。

启动一分钟后，特殊的“缓存加载器”进程会激活。它将存储在文件系统上的先前缓存数据的信息加载到缓存区域中。加载也以迭代方式进行。在一个迭代中，加载的项目不超过 loader_files（默认为 100）。此外，一个迭代的持续时间由 loader_threshold 参数限制（默认为 200 毫秒）。在迭代之间，会进行由 loader_sleep 参数配置的暂停（默认为 50 毫秒）。

此外，以下参数作为我们的商业订阅的一部分可用：

purger=on|off

指示缓存清理器（cache purger，1.7.12）是否将与通配符键匹配的缓存条目从磁盘中移除。将参数设置为 on（默认为 off）将激活“缓存清理器”进程，该进程永久迭代所有缓存条目并删除与通配符键匹配的条目。

purger_files=number

设置在一个迭代中将扫描的项目数量（1.7.12）。默认情况下，purger_files 设置为 10。

purger_threshold=number

设置一个迭代的持续时间（1.7.12）。默认情况下，purger_threshold 设置为 50 毫秒。

purger_sleep=number

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

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

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

如果清除请求的缓存键以星号（“*”）结尾，则所有匹配通配符键的缓存条目将从缓存中移除。然而，这些条目将保留在磁盘上，直到因不活动被删除，或由缓存清理器（1.7.12）处理，或客户端尝试访问它们时被删除。

配置示例

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

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

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

此功能作为我们的商业订阅的一部分可用。

proxy_cache_revalidate off;

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

proxy_cache_use_stale off;

确定在与代理服务器通信期间，何时可以使用陈旧的缓存响应。此指令的参数与 proxy_next_upstream 指令的参数匹配。

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

此外，updating 参数允许在使用陈旧缓存响应的同时对其进行更新。这有助于在更新缓存数据时最大限度地减少对代理服务器的访问次数。

也可以直接在响应头中启用使用陈旧的缓存响应，持续时间为响应变为陈旧后的指定秒数（1.11.10）。这比使用指令参数的优先级低。

• “Cache-Control”头字段的“stale-while-revalidate”扩展允许在使用陈旧缓存响应的同时对其进行更新。
• “Cache-Control”头字段的“stale-if-error”扩展允许在发生错误时使用陈旧的缓存响应。

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

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

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

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

如果只指定了缓存 time（时间）：

proxy_cache_valid 5m;

则只缓存 200、301 和 302 响应。

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

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

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

• “X-Accel-Expires”头字段以秒为单位设置响应的缓存时间。零值禁用该响应的缓存。如果值以 @ 前缀开头，则设置自 Epoch 以来的绝对时间（秒），直到该时间点，响应都可以被缓存。
• 如果头部不包含“X-Accel-Expires”字段，则可以在“Expires”或“Cache-Control”头字段中设置缓存参数。
• 如果头部包含“Set-Cookie”字段，则此类响应不会被缓存。
• 如果头部包含值为特殊值“*”的“Vary”字段，则此类响应不会被缓存（1.7.7）。如果头部包含具有其他值的“Vary”字段，则此类响应将考虑相应的请求头字段进行缓存（1.7.7）。

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

proxy_connect_timeout 60s;

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

proxy_cookie_domain off;

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

proxy_cookie_domain localhost example.org;

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

domain 和 replacement 字符串以及 domain 属性开头的点会被忽略。匹配不区分大小写。

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

proxy_cookie_domain www.$host $host;

也可以使用正则表达式指定此指令。在这种情况下，domain 应该以“~”符号开头。正则表达式可以包含命名捕获和位置捕获，并且 replacement 可以引用它们：

proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain;

可以在同一级别指定多个 proxy_cookie_domain 指令：

proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;

如果多个指令可以应用于同一个 cookie，则选择第一个匹配的指令。

off 参数取消继承自上一配置级别的 proxy_cookie_domain 指令效果。

proxy_cookie_flags off;

为 cookie 设置一个或多个标志。cookie 可以包含文本、变量及其组合。flag 可以包含文本、变量及其组合（1.19.8）。secure、httponly、samesite=strict、samesite=lax、samesite=none 参数添加相应的标志。nosecure、nohttponly、nosamesite 参数移除相应的标志。

也可以使用正则表达式指定 cookie。在这种情况下，cookie 应该以“~”符号开头。

可以在同一配置级别指定多个 proxy_cookie_flags 指令：

proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;

如果多个指令可以应用于同一个 cookie，则选择第一个匹配的指令。在示例中，为 cookie one 添加了 httponly 标志，对于所有其他 cookie，添加了 samesite=strict 标志并删除了 secure 标志。

off 参数取消继承自上一配置级别的 proxy_cookie_flags 指令效果。

proxy_cookie_path off;

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

proxy_cookie_path /two/ /;

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

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

proxy_cookie_path $uri /some$uri;

也可以使用正则表达式指定此指令。在这种情况下，path 应以“~”符号开头表示区分大小写的匹配，或以“~*”符号开头表示不区分大小写的匹配。正则表达式可以包含命名捕获和位置捕获，并且 replacement 可以引用它们：

proxy_cookie_path ~*^/user/([^/]+) /u/$1;

可以在同一级别指定多个 proxy_cookie_path 指令：

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;

如果多个指令可以应用于同一个 cookie，则选择第一个匹配的指令。

off 参数取消继承自上一配置级别的 proxy_cookie_path 指令效果。

proxy_force_ranges off;

无论来自代理服务器的缓存和未缓存响应中是否存在“Accept-Ranges”字段，都启用字节范围支持。

proxy_headers_hash_bucket_size 64;

为 proxy_hide_header 和 proxy_set_header 指令使用的哈希表设置桶 size（大小）。有关设置哈希表的详细信息请参见另一份文档。

proxy_headers_hash_max_size 512;

为 proxy_hide_header 和 proxy_set_header 指令使用的哈希表设置最大 size（大小）。有关设置哈希表的详细信息请参见另一份文档。

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

proxy_http_version 1.0;

设置代理使用的 HTTP 协议版本。默认使用 1.0 版本。建议对 keepalive 连接和 NTLM 认证使用 1.1 版本。

proxy_ignore_client_abort off;

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

禁用对代理服务器响应中某些头字段的处理。以下字段可以被忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”（1.1.6）、“X-Accel-Buffering”（1.1.6）、“X-Accel-Charset”（1.1.6）、“Expires”、“Cache-Control”、“Set-Cookie”（0.8.44）和“Vary”（1.7.7）。

如果未禁用，对这些头字段的处理会产生以下效果：

• “X-Accel-Expires”、“Expires”、“Cache-Control”、“Set-Cookie”和“Vary”设置响应缓存的参数；
• “X-Accel-Redirect”执行到指定 URI 的内部重定向；
• “X-Accel-Limit-Rate”设置向客户端传输响应的速率限制；
• “X-Accel-Buffering”启用或禁用响应的缓冲；
• “X-Accel-Charset”设置响应所需的字符集。

proxy_intercept_errors off;

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

proxy_limit_rate 0;

限制从代理服务器读取响应的速度。rate（速率）以每秒字节数指定。零值禁用速率限制。该限制是按请求设置的，因此如果 nginx 同时打开两个到代理服务器的连接，总速率将是指定限制的两倍。此限制仅在启用来自代理服务器的响应缓冲时有效。参数值可以包含变量（1.27.0）。

proxy_max_temp_file_size 1024m;

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

零值禁用将响应缓冲到临时文件。

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

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

proxy_next_upstream error timeout;

指定在哪些情况下应将请求传递给下一个服务器：

error

与服务器建立连接、向其发送请求或读取响应头时发生错误；

timeout

与服务器建立连接、向其发送请求或读取响应头时发生超时；

invalid_header

服务器返回了空响应或无效响应；

http_500

服务器返回了代码为 500 的响应；

http_502

服务器返回了代码为 502 的响应；

http_503

服务器返回了代码为 503 的响应；

http_504

服务器返回了代码为 504 的响应；

http_403

服务器返回了代码为 403 的响应；

http_404

服务器返回了代码为 404 的响应；

http_429

服务器返回了代码为 429 的响应（1.11.13）；

non_idempotent

通常，如果请求已发送到上游服务器（1.9.13），具有非幂等方法（POST、LOCK、PATCH）的请求不会传递给下一个服务器；启用此选项明确允许重试此类请求；

off

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

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

该指令还定义了哪些情况被视为与服务器通信的非成功尝试。error、timeout 和 invalid_header 这几种情况总是被视为失败尝试，即使它们未在指令中指定。http_500、http_502、http_503、http_504 和 http_429 这几种情况仅当它们在指令中指定时才被视为失败尝试。http_403 和 http_404 这几种情况从不被视为失败尝试。

将请求传递给下一个服务器可以通过尝试次数以及时间来限制。

proxy_next_upstream_timeout 0;

限制了请求可以传递给下一个服务器的时间。0 值关闭此限制。

proxy_next_upstream_tries 0;

限制了将请求传递给下一个服务器的可能尝试次数。0 值关闭此限制。

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

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

可以与proxy_cache_bypass指令一起使用。

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

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

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

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

如果域名解析到多个地址，所有这些地址将以轮询方式使用。此外，地址也可以指定为一个服务器组。

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

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

• 如果 proxy_pass 指令指定了 URI，那么当请求传递给服务器时，与 location 匹配的标准化请求 URI 的部分将被指令中指定的 URI 替换

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

• 如果 proxy_pass 未指定 URI，请求 URI 将以客户端发送原始请求时的形式传递给服务器，或者在处理已更改的 URI 时传递完整的标准化请求 URI

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

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

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

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

  在这些情况下，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 代理需要特殊配置，并且自 1.3.13 版本起支持。

允许传递否则被禁用的头部字段，从被代理服务器到客户端。

proxy_pass_request_body on;

指示原始请求体是否传递给被代理服务器。

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

指示原始请求的头部字段是否传递给被代理服务器。

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

允许传递被代理服务器的 trailer 字段到客户端。

HTTP/1.1 中的 trailer 部分明确启用。

location / {
    proxy_http_version 1.1;
    proxy_set_header Connection "te";
    proxy_set_header TE "trailers";
    proxy_pass_trailers on;

    proxy_pass ...
}

proxy_read_timeout 60s;

定义了从被代理服务器读取响应的超时时间。此超时时间仅设置在两次连续的读取操作之间，而非针对整个响应的传输。如果被代理服务器在此时间内没有传输任何数据，则连接将被关闭。

proxy_redirect default;

设置应在被代理服务器响应的“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 也可以包含变量 (1.1.11)

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

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

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

可以在同一级别指定多个 proxy_redirect 指令。

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

如果多个指令可以应用于被代理服务器响应的头部字段，则将选择第一个匹配的指令。

off 参数取消从上一配置级别继承的 proxy_redirect 指令的效果。

使用此指令，也可以向被代理服务器发出的相对重定向添加主机名：

proxy_redirect / /;

proxy_request_buffering on;

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

启用缓冲后，在将请求发送到被代理服务器之前，会从客户端读取整个请求体。

禁用缓冲后，请求体在接收到后会立即发送给被代理服务器。在这种情况下，如果 nginx 已经开始发送请求体，则请求无法传递给下一个服务器。

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

proxy_send_lowat 0;

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

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

proxy_send_timeout 60s;

设置向被代理服务器传输请求的超时时间。此超时时间仅设置在两次连续的写入操作之间，而非针对整个请求的传输。如果被代理服务器在此时间内没有接收到任何数据，则连接将被关闭。

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

proxy_set_header Host $proxy_host;

proxy_set_header Connection close;

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

配置了向被代理服务器的传出连接的“TCP keepalive”行为。默认情况下，套接字使用操作系统的设置。如果指令设置为值“on”，则会为套接字开启 SO_KEEPALIVE 套接字选项。

指定 PEM 格式的file文件，其中包含用于向被代理 HTTPS 服务器进行身份验证的证书。

自 1.21.0 版本起，可以在 file 名称中使用变量。

proxy_ssl_certificate_cache off;

定义了一个缓存，用于存储使用变量指定的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;

指定 PEM 格式的file文件，其中包含用于向被代理 HTTPS 服务器进行身份验证的秘密密钥。

可以指定值 engine:name:id 来代替 file (1.7.9)，这将从 OpenSSL 引擎 name 加载具有指定 id 的秘密密钥。

自 1.21.0 版本起，可以在 file 名称中使用变量。

proxy_ssl_ciphers DEFAULT;

指定用于向被代理 HTTPS 服务器发出请求的启用加密套件。加密套件采用 OpenSSL 库理解的格式指定。

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

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

使用 OpenSSL 1.0.2 或更高版本时支持此指令。

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

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

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

启用记录被代理 HTTPS 服务器连接的 SSL 密钥，并指定密钥日志文件的路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

此指令作为我们的商业订阅的一部分提供。

proxy_ssl_name $proxy_host;

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

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

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

proxy_ssl_protocols TLSv1.2 TLSv1.3;

为向被代理 HTTPS 服务器发出的请求启用指定的协议。

自 1.23.4 版本起，默认使用 TLSv1.3 参数。

proxy_ssl_server_name off;

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

proxy_ssl_session_reuse on;

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

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

proxy_ssl_verify off;

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

proxy_ssl_verify_depth 1;

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

proxy_store off;

启用将文件保存到磁盘。on 参数会保存文件到与alias或root指令对应的路径。off 参数禁用文件保存。此外，可以使用包含变量的 string 显式设置文件名：

proxy_store /data/www$original_uri;

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

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

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

location /fetch/ {
    internal;

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

    alias              /data/www/;
}

或者像这样：

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

location @fetch {
    internal;

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

    root               /data/www;
}

proxy_store_access user:rw;

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

proxy_store_access user:rw group:rw all:r;

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

proxy_store_access group:rw all:r;

proxy_temp_file_write_size 8k|16k;

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

proxy_temp_path proxy_temp;

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

proxy_temp_path /spool/nginx/proxy_temp 1 2;

一个临时文件可能看起来像这样：

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

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

ngx_http_proxy_module 模块支持嵌入式变量，可以使用proxy_set_header指令来组合头部：

$proxy_host

被代理服务器的名称和端口，如proxy_pass指令中指定的那样；

$proxy_port

被代理服务器的端口，如proxy_pass指令中指定的那样，或者是协议的默认端口；

$proxy_add_x_forwarded_for

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