Nginx 配置指令手册

Upstream directives

upstream

• 定义一组上游服务器;
• name
• 1

定义一组服务器。
服务器可以侦听不同的端口。
此外，可以混合侦听TCP和UNIX域套接字的服务器。

server

• 定义服务器的地址和其他参数;
• address [parameters], 示例 10.64.11:8080 weight=1;
• 2

hash

• 指定服务器组的负载平衡方法，其中客户端 - 服务器映射基于散列键值。
• key: $remote_addr|$request_uri
• 1

healthcheck

check

• 添加上游服务器的运行状况检查。
• interval=3000 rise=2 fall=2 timeout=1000 type=http;
• 5

check_http_send

• 将发送此http数据包以检查上游服务器。
• "GET /healthcheck.html HTTP/1.0 Host: 11bee.com Connection: close ";
• 3

check_http_expect_alive

• 这些状态代码表示上游服务器的http响应没问题，后端还活着。
• http_2xx|http_3xx

• = 2

Server directives

server_name

• 虚拟服务器的名称
• [server_name]

• = 1

listen

• 设置IP的地址和端口，或服务器将接受请求的UNIX域套接字的路径
• PORT (ssl)
• 1-2

location

• 根据请求URI设置配置。
• [expressions] [uri]
• 2

GZIP directives

gzip

• 启用或禁用gzipping响应;
• on | off;
• 1

gzip_buffers

• 设置用于压缩响应的缓冲区的数量和大小;
• 32 4k|16 8k;
• 2

设置用于压缩响应的缓冲区的数量和大小。
默认情况下，缓冲区大小等于一个内存页面。
这是4K或8K，具体取决于平台。

gzip_comp_level

• 设置响应的gzip压缩级别;
• level 1-9;
• 1

gzip_disable

• 对具有与任何指定正则表达式匹配的“User-Agent”标头字段的请求禁用gzipping响应。
• "MSIE 6";
• 1

gzip_http_version

• 设置压缩响应所需的最低HTTP请求版本。
• 1.1
• 1

gzip_min_length

• 设置将被gzip压缩的响应的最小长度。
• 1000
• 1

gzip_types

• 对指定的MIME类型进行gzipping响应。
• 默认application/x-javascript text/javascript application/json text/css;
• 大于0

Enables gzipping of responses for the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29). Responses with the “text/html” type are always compressed.

gzip_proxied

• 根据请求和响应启用或禁用对代理请求的响应的gzipping
• 默认所有 expired no-cache no-store private auth;
• 大于0, 或者不写

根据请求和响应启用或禁用对代理请求的响应的gzipping。
请求被代理的事实由“Via”请求头字段的存在确定。
该指令接受多个参数：

# off
disables compression for all proxied requests, ignoring other parameters;
# expired
enables compression if a response header includes the “Expires” field with a value that disables caching;
# no-cache
enables compression if a response header includes the “Cache-Control” field with the “no-cache” parameter;
# no-store
enables compression if a response header includes the “Cache-Control” field with the “no-store” parameter;
# private
enables compression if a response header includes the “Cache-Control” field with the “private” parameter;
# no_last_modified
enables compression if a response header does not include the “Last-Modified” field;
# no_etag
enables compression if a response header does not include the “ETag” field;
# auth
enables compression if a request header includes the “Authorization” field;
# any
enables compression for all proxied requests.

Proxy directives

proxy_pass

• 设置代理服务器的协议和地址以及应映射位置的可选URI。
• URL|Upstrem_name
• 2

设置代理服务器的协议和地址以及应映射位置的可选URI。作为协议，可以指定“http”或“https”。地址可以指定为域名或IP地址，以及可选端口：

proxy_buffer_size

• 设置用于读取从代理服务器接收的响应的第一部分的缓冲区的大小。
• 4k|8k;
• 1

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

proxy_buffering

• 启用或禁用来自代理服务器的响应缓冲。
• on | off; default on
• 1

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

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

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

proxy_buffers

• 用于单个连接。默认情况下，缓冲区大小等于一个内存页面;
• 8 8k|16k; default 64 4k
• 2

用于单个连接。默认情况下，缓冲区大小等于一个内存页面。这是4K或8K，具体取决于平台。

proxy_busy_buffers_size

• 当启用来自代理服务器的响应缓冲时，限制可能忙于向响应客户端发送响应的缓冲区的总大小，而响应尚未完全读取;
• 8k|16k;
• 1

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

proxy_cache

• 定义用于缓存的共享内存区域。
• zone | off; default off
• 1

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

proxy_connect_timeout

• 定义与代理服务器建立连接的超时。
• 60s;
• 1

应该注意，此超时通常不会超过75秒。

proxy_cookie_domain

• 设置应在代理服务器响应的“Set-Cookie”标头字段的domain属性中更改的文本;
• off | domain replacement;
• 1-2

proxy_http_version

• 设置代理的HTTP协议版本
• 1.0 | 1.1; default 1.0
• 1

设置代理的HTTP协议版本。默认情况下，使用版本1.0。建议将1.1版用于keepalive连接。

proxy_ignore_client_abort

• 确定在客户端关闭连接而不等待响应时是否应关闭与代理服务器的连接。
• on | off; default off
• 1

proxy_intercept_errors

• 确定代码大于或等于300的代理响应是应该传递给客户端还是被拦截并重定向到nginx以便使用error_page指令进行处理。
• on | off; default on
• 1

proxy_next_upstream

• 指定应将请求传递到下一个服务器的情况：
• 默认 error timeout invalid_header http_500 http_502 http_503 http_504 http_404;
• 8

error
an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_502
a server returned a response with the code 502;
http_503
a server returned a response with the code 503;
http_504
a server returned a response with the code 504;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429 (1.11.13);
non_idempotent
normally, requests with a non-idempotent method (POST, LOCK, PATCH) are not passed to the next server if a request has been sent to an upstream server (1.9.13); enabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.

proxy_pass_request_headers

• 指示是否将原始请求的标头字段传递给代理服务器。
• on | off; default on
• 1

proxy_read_timeout

• 定义从代理服务器读取响应的超时。
• 60s;
• 1

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

proxy_send_timeout

• 设置将请求传输到代理服务器的超时。
• 60s;
• 1

设置将请求传输到代理服务器的超时。仅在两个连续的写操作之间设置超时，而不是为整个请求的传输。如果代理服务器在此时间内未收到任何内容，则关闭连接。

proxy_set_header

• 允许将字段重新定义或附加到传递给代理服务器的请求标头。
• [field] [value]
• 2

允许将字段重新定义或附加到传递给代理服务器的请求标头。该值可以包含文本，变量及其组合。当且仅当在当前级别上没有定义proxy_set_header指令时，这些指令才从前一级继承。默认情况下，只重新定义了两个字段：

proxy_temp_file_write_size

• 当启用从代理服务器到临时文件的响应缓冲时，限制一次写入临时文件的数据大小
• 8k|16k;
• 1

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

add_header

• 将指定的字段添加到响应标头。
• name value
• 2

client_body_buffer_size

• 设置读取客户端请求主体的缓冲区大小
• size, 8k|16k
• 1

设置读取客户端请求主体的缓冲区大小。
如果请求主体大于缓冲区，则整个主体或仅其部分被写入临时文件。
默认情况下，缓冲区大小等于两个内存页。
这在x86，其他32位平台和x86-64上是8K。
在其他64位平台上通常为16K。

client_header_buffer_size

• 设置读取客户端请求标头的缓冲区大小
• size, 1k;
• 1

设置读取客户端请求标头的缓冲区大小。
对于大多数请求，1K字节的缓冲区就足够了。
但是，如果请求包含长cookie或来自WAP客户端，则可能不适合1K。
如果请求行或请求头字段不适合此缓冲区，则会分配由large_client_header_buffers指令配置的较大缓冲区。

client_max_body_size

• 设置客户端请求正文的最大允许大小;
• size, 1m;
• 1

设置客户端请求正文的最大允许大小，在“Content-Length”请求标头字段中指定。
如果请求中的大小超过配置的值，则会将413（请求实体太大）错误返回给客户端。
请注意，浏览器无法正确显示此错误。
将大小设置为0将禁用检查客户端请求正文大小。

ignore_invalid_headers

• 控制是否应忽略具有无效名称的标头字段。
• on|off
• 1

控制是否应忽略具有无效名称的标头字段。有效名称由英文字母，数字，连字符和可能的下划线组成（由underscores_in_headers指令控制）。

underscores_in_headers

• 启用或禁用客户端请求标头字段中下划线的使用
• on|off
• 1

启用或禁用客户端请求标头字段中下划线的使用。禁用下划线时，名称包含下划线的请求标头字段将标记为无效，并受到ignore_invalid_headers指令的约束。

ACL(访问控制列表) directives

allow

• 允许访问指定的网络或地址。
• address | CIDR | all
• 1

deny

• 拒绝访问指定的网络或地址。
• address | CIDR | all
• 1

Rewrite directives

more_set_headers

• 替换（如果有）或添加（如果不是）任何指定的输出头。
• "header"
• 1

if

• 评估指定的条件。如果为true，则执行在大括号内指定的此模块指令，并在if指令内为该请求分配配置;
• [condition]
• 1

评估指定的条件。如果为true，则执行在大括号内指定的此模块指令，并在if指令内为该请求分配配置。
if指令内的配置继承自先前的配置级别。

rewrite

• 如果指定的正则表达式与请求URI匹配，则URI将根据替换字符串中的指定进行更改。
• [regex] [replacement] [flag]
• 3

如果指定的正则表达式与请求URI匹配，则URI将根据替换字符串中的指定进行更改。重写指令按照它们在配置文件中的出现顺序执行。可以使用标志终止对指令的进一步处理。如果替换字符串以“http：//”，“https：//”或“$ scheme”开头，则处理停止并将重定向返回给客户端。

set

• 设置指定变量的值。该值可以包含文本，变量及其组合。
• [$variable] [value]
• 2

return

• 停止处理并将指定的代码返回给客户端。
• [code] [URL];
• 2

停止处理并将指定的代码返回给客户端。
非标准代码444在不发送响应头的情况下关闭连接。
从版本0.8.42开始，可以指定重定向URL（对于代码301,302,303,307和308）或响应正文文本（对于其他代码）。
响应正文文本和重定向URL可以包含变量。
作为特殊情况，可以将重定向URL指定为此服务器的本地URI，在这种情况下，根据请求方案（$ scheme）以及server_name_in_redirect和port_in_redirect指令形成完整重定向URL。
另外，可以将用于具有代码302的临时重定向的URL指定为唯一参数。
这样的参数应该以“http：//”，“https：//”或“$ scheme”字符串开头。
URL可以包含变量。

break

• 停止处理当前的ngx_http_rewrite_module指令集。
• 0

停止处理当前的ngx_http_rewrite_module指令集。
如果在该位置内指定了指令，则在该位置继续进一步处理该请求。