ngx_http_proxy_module

• 示例配置

• 指令

• proxy_bind

• proxy_buffer_size

• proxy_buffering

• proxy_buffers

• proxy_busy_buffers_size

• proxy_cache

• proxy_cache_background_update

• proxy_cache_bypass

• proxy_cache_convert_head

• proxy_cache_key

• proxy_cache_lock

• proxy_cache_lock_age

• proxy_cache_lock_timeout

• proxy_cache_max_range_offset

• proxy_cache_methods

• proxy_cache_min_uses

• proxy_cache_path

• proxy_cache_purge

• proxy_cache_revalidate

• proxy_cache_use_stale

• proxy_cache_valid

• proxy_connect_timeout

• proxy_cookie_domain

• proxy_cookie_path

• proxy_force_ranges

• proxy_headers_hash_bucket_size

• proxy_headers_hash_max_size

• proxy_hide_header

• proxy_http_version

• proxy_ignore_client_abort

• proxy_ignore_headers

• proxy_intercept_errors

• proxy_limit_rate

• proxy_max_temp_file_size

• proxy_method

• proxy_next_upstream

• proxy_next_upstream_timeout

• proxy_next_upstream_tries

• proxy_no_cache

• proxy_pass

• proxy_pass_header

• proxy_pass_request_body

• proxy_pass_request_headers

• proxy_read_timeout

• proxy_redirect

• proxy_request_buffering

• proxy_send_lowat

• proxy_send_timeout

• proxy_set_body

• proxy_set_header

• proxy_ssl_certificate

• proxy_ssl_certificate_key

• proxy_ssl_ciphers

• proxy_ssl_crl

• proxy_ssl_name

• proxy_ssl_password_file

• proxy_ssl_server_name

• proxy_ssl_session_reuse

• proxy_ssl_protocols

• proxy_ssl_trusted_certificate

• proxy_ssl_verify

• proxy_ssl_verify_depth

• proxy_store

• proxy_store_access

• proxy_temp_file_write_size

• proxy_temp_path

• 嵌入式变量

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

示例配置

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

指令

句法：	proxy_bind地址 | 关闭;
默认：	—
语境：	http，服务器，位置

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

transparent参数（1.11.0）允许与代理服务器传出连接从一个非本地的IP地址发起，例如，来自客户端的实际IP地址：

proxy_bind $remote_addr transparent;

为了使此参数有效，需要以超级用户权限运行nginx工作进程，并配置内核路由表以拦截来自代理服务器的网络流量。

句法：	proxy_buffer_size大小;
默认：	proxy_buffer_size 4k | 8k;
语境：	http，服务器，位置

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

句法：	proxy_buffering 开启|关闭;
默认：	proxy_buffering;
语境：	http，服务器，位置

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

启用缓冲后，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 数量大小;
默认：	proxy_buffers 8 4k | 8k;
语境：	http，服务器，位置

设置number和size用于读取从所述代理服务器的响应，供用于单个连接的缓冲器。默认情况下，缓冲区大小等于一个内存页面。这是4K或8K，取决于平台。

句法：	proxy_busy_buffers_size大小;
默认：	proxy_busy_buffers_size 8k | 16k;
语境：	http，服务器，位置

当启用对代理服务器的响应缓冲时，限制size可能正忙于向客户端发送响应的缓冲区总数，而响应尚未完全读取。同时，其余的缓冲区可以用于读取响应，并且如果需要的话，缓冲部分对临时文件的响应。默认情况下，size受到proxy_buffer_size和proxy_buffers指令设置的两个缓冲区的大小的限制。

句法：	proxy_cache 区域| 关闭;
默认：	proxy_cache关闭;
语境：	http，服务器，位置

定义用于缓存的共享内存区域。同一个区域可以在几个地方使用。参数值可以包含变量（1.7.9）。该off参数禁用从先前配置级别继承的缓存。

句法：	proxy_cache_background_update 开启|关闭;
默认：	proxy_cache_background_update关闭;
语境：	http，服务器，位置

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

句法：	proxy_cache_bypass string ...;
默认：	—
语境：	http，服务器，位置

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

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

可以与proxy_no_cache指令一起使用。

句法：	proxy_cache_convert_head 开启|关闭;
默认：	proxy_cache_convert_head 开启;
语境：	http，服务器，位置

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

句法：	proxy_cache_key字符串;
默认：	proxy_cache_key $ scheme $ proxy_host $ request_uri;
语境：	http，服务器，位置

例如，定义缓存的关键字

proxy_cache_key "$host$request_uri $cookie_user";

默认情况下，指令的值接近字符串

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

句法：	proxy_cache_lock 开启| 关闭;
默认：	proxy_cache_lock 关闭;
语境：	http，服务器，位置

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

句法：	proxy_cache_lock_age时间;
默认：	proxy_cache_lock_age 5s;
语境：	http，服务器，位置

如果传递给代理服务器的用于填充新缓存元素的最后一个请求未完成指定time，则可以将另一个请求传递给代理服务器。

句法：	proxy_cache_lock_timeout时间;
默认：	proxy_cache_lock_timeout 5s;
语境：	http，服务器，位置

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

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

句法：	proxy_cache_max_range_offset编号;
默认：	—
语境：	http，服务器，位置

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

句法：	proxy_cache_methods GET | HEAD | POST ...;
默认：	proxy_cache_methods GET HEAD;
语境：	http，服务器，位置

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

句法：	proxy_cache_min_uses数字;
默认：	proxy_cache_min_uses 1;
语境：	http，服务器，位置

设置number请求之后的响应将被缓存。

句法：	proxy_cache_path path levels = levels keys_zone = name：size inactive = time manager_files = number manager_threshold = time loader_sleep = time purger = on | off purger_sleep = time;
默认：	—
语境：	HTTP

设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的文件名是将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参数设置的最大缓存大小。 当超过此大小时，它将删除最近最少使用的数据。 数据在由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指示缓存清除程序（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版本后，以前缓存的响应将被视为无效。

句法：	proxy_cache_purge string ...;
默认：	—
语境：	http，服务器，位置

定义将请求视为缓存清除请求的条件。如果字符串参数中至少有一个值不为空并且不等于“0”，则带有相应缓存键的缓存条目将被删除。通过返回204（无内容）响应来指示成功操作的结果。

如果清除请求的缓存键以星号（“ *”）结尾，则匹配通配符键的所有缓存条目将从缓存中删除。但是，这些条目将保留在磁盘上，直到它们被删除以进行不活动或由缓存清除程序（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 开启|关闭;
默认：	proxy_cache_revalidate 关闭;
语境：	http，服务器，位置

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

句法：	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关闭;
语境：	http，服务器，位置

确定在与代理服务器通信期间可以使用过时的缓存响应。该指令的参数与proxy_next_upstream指令的参数相匹配。

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

此外，如果updating参数当前正在更新，则该参数允许使用陈旧的缓存响应。这允许在更新缓存数据时最大限度地减少对代理服务器的访问次数。

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

• “Cache-Control”头字段的“ reale-revalidate ”扩展允许使用陈旧的缓存响应，如果它正在更新。

• “Cache-Control”头字段的“ stale-if-error ”扩展允许在发生错误时使用陈旧的缓存响应。

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

句法：	proxy_cache_valid code ... time;
默认：	—
语境：	http，服务器，位置

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

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

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

如果只指定了缓存时间

proxy_cache_valid 5m;

那么只缓存200,301和302响应。

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

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

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

• “X-Accel-Expires”标题字段以秒为单位设置响应的缓存时间。零值会禁用响应的缓存。如果值以@前缀开头，则它设置自Epoch以来的绝对时间（以秒为单位），最多可以缓存该响应。

• 如果标题不包含“X-Accel-Expires”字段，则可以在标题字段“Expires”或“Cache-Control”中设置缓存参数。

• 如果标题包含“Set-Cookie”字段，则不会缓存这样的响应。

• 如果头部包含具有特殊值“ *” 的“Vary”字段，则这种响应不会被缓存（1.7.7）。如果头部包含带有另一个值的“Vary”字段，则考虑到相应的请求头字段（1.7.7），这样的响应将被缓存。

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

句法：	proxy_connect_timeout时间;
默认：	proxy_connect_timeout 60s;
语境：	http，服务器，位置

定义与代理服务器建立连接的超时时间。应该指出的是，这个超时通常不能超过75秒。

句法：	proxy_cookie_domain关闭; proxy_cookie_domain域名替换;
默认：	proxy_cookie_domain关闭;
语境：	http，服务器，位置

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

proxy_cookie_domain localhost example.org;

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

域的开始点和替换字符串以及域属性被忽略。 匹配不区分大小写。

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

proxy_cookie_domain www.$host $host;

该指令也可以使用正则表达式指定。 在这种情况下，域应该从“〜”符号开始。 正则表达式可以包含命名和位置捕获，并且替换可以引用它们：

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;

该off参数取消proxy_cookie_domain当前级别上所有指令的作用：

proxy_cookie_domain off;
proxy_cookie_domain localhost example.org;
proxy_cookie_domain www.example.org example.org;

句法：	proxy_cookie_path关闭; proxy_cookie_path路径替换;
默认：	proxy_cookie_path关闭;
语境：	http，服务器，位置

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

proxy_cookie_path /two/ /;

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

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

proxy_cookie_path $uri /some$uri;

该指令也可以使用正则表达式指定。 在这种情况下，路径应该从用于区分大小写的匹配的“〜”符号开始，或者从用于区分大小写的匹配的“〜*”符号开始。 正则表达式可以包含命名和位置捕获，并且替换可以引用它们：

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

可能有几个proxy_cookie_path指令：

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

该off参数取消当前级别上所有proxy_cookie_path指令的作用：

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

句法：	proxy_force_ranges 开启|关闭;
默认：	proxy_force_ranges关闭;
语境：	http，服务器，位置

无论这些响应中的“接受范围”字段如何，均可为来自代理服务器的缓存和未缓存的响应启用字节范围支持。

句法：	proxy_headers_hash_bucket_size大小;
默认：	proxy_headers_hash_bucket_size 64;
语境：	http，服务器，位置

设置size由proxy_hide_header和proxy_set_header指令使用的散列表的存储桶。设置散列表的细节在单独的文档中提供。

句法：	proxy_headers_hash_max_size大小;
默认：	proxy_headers_hash_max_size 512;
语境：	http，服务器，位置

设置proxy_hide_header和proxy_set_header伪指令使用的散列表的最大大小。 设置散列表的细节在单独的文档中提供。

句法：	proxy_hide_header字段;
默认：	—
语境：	http，服务器，位置

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

句法：	proxy_http_version 1.0 | 1.1;
默认：	proxy_http_version 1.0;
语境：	http，服务器，位置

设置代理的HTTP协议版本。默认情况下，使用版本1.0。推荐使用版本1.1与Keepalive连接和NTLM身份验证一起使用。

句法：	proxy_ignore_client_abort 开启|关闭;
默认：	proxy_ignore_client_abort关闭;
语境：	http，服务器，位置

确定当客户端关闭连接而不等待响应时是否应关闭与代理服务器的连接。

句法：	proxy_ignore_headers字段...;
默认：	—
语境：	http，服务器，位置

禁止处理来自代理服务器的某些响应头字段。以下字段可以忽略：“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 开启|关闭;
默认：	proxy_intercept_errors 关闭;
语境：	http，服务器，位置

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

句法：	proxy_limit_rate率;
默认：	proxy_limit_rate 0;
语境：	http，服务器，位置

限制从代理服务器读取响应的速度。在rate被以每秒字节数指定。零值禁用速率限制。该限制是根据请求设置的，因此如果nginx同时打开到代理服务器的两个连接，整体速率将是指定限制的两倍。该限制仅在启用对代理服务器的响应缓冲时起作用。

句法：	proxy_max_temp_file_size大小;
默认：	proxy_max_temp_file_size 1024m;
语境：	http，服务器，位置

当启用对代理服务器响应的缓冲，并且整个响应不适合proxy_buffer_size和proxy_buffers指令设置的缓冲区时，响应的一部分可以保存到临时文件中。 该指令设置临时文件的最大大小。 一次写入临时文件的数据大小由proxy_temp_file_write_size指令设置。

零值禁用缓冲对临时文件的响应。

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

句法：	proxy_method方法;
默认：	—
语境：	http，服务器，位置

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

句法：	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错误超时;
语境：	http，服务器，位置

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

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禁用将请求传递给下一个服务器。

人们应该记住，只有在没有任何内容发送给客户端的情况下，才能将请求传递到下一个服务器。也就是说，如果在响应传输过程中发生错误或超时，修复这是不可能的。

该指令还定义了与服务器进行通信的不成功尝试。 错误，超时和invalid_header的情况总是被认为是不成功的尝试，即使它们没有在指令中指定。 只有在指令中指定了http_500，http_502，http_503，http_504和http_429的情况下，才会将其视为不成功尝试。 http_403和http_404的情况永远不会被视为不成功的尝试。

将请求传递给下一台服务器可能受到尝试次数和时间的限制。

句法：	proxy_next_upstream_timeout时间;
默认：	proxy_next_upstream_timeout 0;
语境：	http，服务器，位置

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

句法：	proxy_next_upstream_tries编号;
默认：	proxy_next_upstream_tries 0;
语境：	http，服务器，位置

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

句法：	proxy_no_cache string ...;
默认：	—
语境：	http，服务器，位置

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

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

可以与proxy_cache_bypass指令一起使用。

句法：	proxy_pass URL;
默认：	—
语境：	位置，如果在位置，limit_except

设置代理服务器的协议和地址以及应将位置映射到的可选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 /远程/; }

• 如果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部分：

• 当使用正则表达式指定位置时，以及指定位置内。在这些情况下，proxy_pass应该指定没有URI。

• 当使用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_header字段;
默认：	—
语境：	http，服务器，位置

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

句法：	proxy_pass_request_body开启|关闭;
默认：	proxy_pass_request_body 开启;
语境：	http，服务器，位置

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

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...
}

另请参阅proxy_set_header和proxy_pass_request_headers指令。

句法：	proxy_pass_request_headers开启|关闭;
默认：	proxy_pass_request_headers开启;
语境：	http，服务器，位置

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

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时间;
默认：	proxy_read_timeout 60s;
语境：	http，服务器，位置

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

句法：	proxy_redirect默认; proxy_redirect关闭; proxy_redirect重定向替换;
默认：	proxy_redirect默认值;
语境：	http，服务器，位置

设置应在代理服务器响应的“位置”和“刷新”标题字段中更改的文本。假设代理服务器返回了头字段“ 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）。 在这种情况下，重定向应该以“〜”符号开始，区分大小写匹配，或者使用“〜*”符号进行区分大小写匹配。 正则表达式可以包含命名和位置捕获，并且替换可以引用它们：

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 off;
proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;

使用此指令，还可以将主机名添加到由代理服务器发出的相对重定向中：

proxy_redirect / /;

句法：	proxy_request_buffering 开启|关闭;
默认：	proxy_request_buffering 开启;
语境：	http，服务器，位置

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

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

当禁用缓冲时，请求主体会在收到请求时立即发送到代理服务器。在这种情况下，如果nginx已经开始发送请求主体，则请求不能传递到下一个服务器。

当使用HTTP / 1.1分块传输编码发送原始请求主体时，不管指令值如何，请求主体都将被缓存，除非启用了HTTP / 1.1代理。

句法：	proxy_send_lowat大小;
默认：	proxy_send_lowat 0;
语境：	http，服务器，位置

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

该指令在Linux，Solaris和Windows上被忽略。

句法：	proxy_send_timeout时间;
默认：	proxy_send_timeout 60s;
语境：	http，服务器，位置

设置向代理服务器发送请求的超时时间。超时只在两次连续写入操作之间设置，而不是用于传输整个请求。如果代理服务器在此时间内没有收到任何内容，则连接将关闭。

句法：	proxy_set_body值;
默认：	—
语境：	http，服务器，位置

允许重新定义传递给代理服务器的请求主体。该value可以包含文本，变量，他们的组合。

句法：	proxy_set_header字段值;
默认：	proxy_set_header Host $proxy_host;proxy_set_header Connection 关闭;
语境：	http，服务器，位置

允许重新定义或附加字段到传递给代理服务器的请求标头。该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变量 - 它的值等于“主机”请求标头字段中的服务器名称或主服务器名称（如果此字段不存在）：

proxy_set_header Host       $host;

另外，服务器名称可以与代理服务器的端口一起传递：

proxy_set_header Host       $host:$proxy_port;

如果头字段的值是空字符串，则该字段不会传递给代理服务器：

proxy_set_header Accept-Encoding "";

句法：	proxy_ssl_certificate文件;
默认：	—
语境：	http，服务器，位置

指定一个file包含用于对代理HTTPS服务器进行身份验证的PEM格式的证书。

句法：	proxy_ssl_certificate_key文件;
默认：	—
语境：	http，服务器，位置

指定file带有PEM格式的密钥，用于对代理HTTPS服务器进行身份验证。

值engine：name：id 可以指定代替file（1.7.9），它加载与指定的秘密密钥id从OpenSSL的发动机name。

句法：	proxy_ssl_ciphers密码;
默认：	proxy_ssl_ciphers DEFAULT;
语境：	http，服务器，位置

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

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

句法：	proxy_ssl_crl文件;
默认：	—
语境：	http，服务器，位置

指定file带有PEM格式的撤销证书（CRL），用于验证代理HTTPS服务器的证书。

句法：	proxy_ssl_name名称;
默认：	proxy_ssl_name $ proxy_host;
语境：	http，服务器，位置

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

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

句法：	proxy_ssl_password_file文件;
默认：	—
语境：	http，服务器，位置

指定file密码的密码，其中每个密码在单独的行上指定。加载密钥时会依次尝试密码。

句法：	proxy_ssl_server_name 开启| 关闭;
默认：	proxy_ssl_server_name 关闭;
语境：	http，服务器，位置

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

句法：	proxy_ssl_session_reuse 开启|关闭;
默认：	proxy_ssl_session_reuse 开启;
语境：	http，服务器，位置

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

句法：	proxy_ssl_protocols SSLv2 TLSv1 TLSv1.2;
默认：	proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
语境：	http，服务器，位置

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

句法：	proxy_ssl_trusted_certificate文件;
默认：	—
语境：	http，服务器，位置

指定file 带有用于验证代理HTTPS服务器证书的PEM格式的可信CA证书。

句法：	proxy_ssl_verify 开启 | 关闭;
默认：	proxy_ssl_verify 关闭;
语境：	http，服务器，位置

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

句法：	proxy_ssl_verify_depth数字;
默认：	proxy_ssl_verify_depth 1;
语境：	http，服务器，位置

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

句法：	proxy_store 开启|关闭| 串;
默认：	proxy_store关闭;
语境：	http，服务器，位置

启用将文件保存到磁盘。 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用户：权限...;
默认：	proxy_store_access user：rw;
语境：	http，服务器，位置

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

proxy_store_access user:rw group:rw all:r;

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

proxy_store_access group:rw all:r;

句法：	proxy_temp_file_write_size大小;
默认：	proxy_temp_file_write_size 8k | 16k;
语境：	http，服务器，位置

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

句法：	proxy_temp_path路径[level1 [level2 level3]];
默认：	proxy_temp_path proxy_temp;
语境：	http，服务器，位置

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

proxy_temp_path /spool/nginx/proxy_temp 1 2;

临时文件可能如下所示：

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

另请参阅use_temp_pathproxy_cache_path指令的参数。

嵌入式变量

该ngx_http_proxy_module模块支持可用于使用proxy_set_header指令组合标头的嵌入式变量：

$ proxy_hostname和proxy_pass指令中指定的代理服务器的端口; proxy_pass指令中指定的代理服务器的$ proxy_portport或协议的默认端口; $ proxy_add_x_forwarded_forthe“X-Forwarded-For”客户端请求标头字段，其中$ 附加到它的remote_addr变量，用逗号分隔。 如果客户端请求头中不存在“X-Forwarded-For”字段，则$ proxy_add_x_forwarded_for变量等于$ remote_addr变量。