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，则将选择第一个匹配的指令。在示例中，httponly 标志被添加到 cookie one，对于所有其他 cookie，添加 samesite=strict 标志并删除 secure 标志。

off 参数取消从先前配置级别继承的 proxy_cookie_flags 指令的效果。

proxy_cookie_path off;

设置应在代理服务器响应的“Set-Cookie”标头字段的 path 属性中更改的文本。假设代理服务器返回带有属性“path=/two/some/uri/”的“Set-Cookie”标头字段。指令

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。建议将版本 1.1 用于 keepalive 连接和 NTLM 身份验证。

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

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

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

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，位置应该映射到该URI。作为协议，可以指定“http”或“https”。地址可以指定为域名或IP地址，以及可选的端口：

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

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

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

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

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

请求URI传递到服务器的方式如下：

• 如果proxy_pass指令指定了URI，则当请求传递到服务器时，与位置匹配的规范化请求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的一部分：

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

  在这些情况下，应该在没有URI的情况下指定proxy_pass。

• 当使用rewrite指令在代理位置内更改URI时，并且将使用相同的配置来处理请求（break）：

  location /name/ {
      rewrite    /name/([^/]+) /users?name=$1 break;
      proxy_pass http://127.0.0.1;
  }
  

  在这种情况下，指令中指定的URI将被忽略，完整的更改请求URI将传递到服务器。

• 当在proxy_pass中使用变量时：

  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_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/”。

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

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参数。

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

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

重定向也可以包含（1.1.11）变量：

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

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

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 套接字选项。

指定用于向代理 HTTPS 服务器进行身份验证的 PEM 格式证书的 file。

从 1.21.0 版本开始，变量可以在 file 名称中使用。

指定用于向代理 HTTPS 服务器进行身份验证的 PEM 格式私钥的 file。

可以指定值 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 格式的已吊销证书 (CRL) 的 文件，用于 验证 代理 HTTPS 服务器的证书。

proxy_ssl_name $proxy_host;

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

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

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

proxy_ssl_protocols TLSv1 TLSv1.1 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 会话。如果日志中出现错误“SSL3_GET_FINISHED:digest check failed”，请尝试禁用会话重用。

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

proxy_ssl_verify off;

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

proxy_ssl_verify_depth 1;

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

proxy_store off;

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

proxy_store /data/www$original_uri;

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

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

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

location /fetch/ {
    internal;

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

    alias              /data/www/;
}

或像这样：

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

location @fetch {
    internal;

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

    root               /data/www;
}

proxy_store_access 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 变量。