nginx 使用笔记 nginx 指令与模块说明大全

现在系统整理一下nginx的使用笔记 .

一.安装

http://nginx.org/en/linux_packages.html

ubuntu

apt-get install nginx

centos
yum install nginx

二.命令行使用

http://nginx.org/en/docs/switches.html

service nginx restart 重启 nginx

nginx -s reload 重新加载配置

三.default server

server {
    listen       80

default_server

;
    server_name  baidu.com  www.baidu.com;
    ...
}

先看看上面这段配置，listen 指令后面有一个参数 default_server ，这个参数是在 0.8.21 版本以后才有的，而之前是 default 指令。

Nginx 的虚拟主机是通过HTTP请求中的Host值来找到对应的虚拟主机配置，如果找不到呢？那 Nginx 就会将请求送到指定了 default_server 的 节点来处理，如果没有指定为 default_server 的话，就跑到 localhost 的节点，如果没有 localhost 的节点，那只好 404 了。

另外你也可以指定对于没有匹配的 Host 值时，返回错误到客户端，这在现在国内用来处理未备案域名指向自己时非常有用，看看下面的配置：

server {
    listen       80

default_server

;
    server_name  _;
    return       444;
}

通过返回444这个Nginx的非标准错误码来让Nginx断开与浏览器之间的连接。

四.配置ip直接访问:

server {
listen 80;
server_name 127.0.0.1

五.内置变量表

http://nginx.org/en/docs/varindex.html

六.核心功能

示例配置

user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
    use kqueue;
    worker_connections 2048;
}

...

指令

accept_mutex on;

如果使用，nginx的多个工作进程将以串行方式接入新连接。否则，新连接将通报给所有工作进程，而且如果新连接数量较少，某些工作进程可能只是在浪费系统资源。

accept_mutex_delay 500ms;

使用accept_mutex时，可以指定某个工作进程检测到其它工作进程正在接入新连接时，自身等待直到重新开始尝试接入新连接的最大时间间隔。

daemon on;

决定nginx是否应以守护进程的方式工作。主要用于开发。

开启针对特定客户端连接的调试日志。除开这些连接，其它连接将使用error_log指令设置的日志级别。 被调试的连接可以使用IPv4或IPv6(1.3.0, 1.2.1)网络地址来指定， 也可以使用主机名来设置连接。 对于UNIX域套接字(1.3.0, 1.2.1)，使用“unix:”参数来启用调试日志。

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    ...
}

只有在编译时设置--with-debug，上述指令才可以工作。

这条指令用于调试。

当nginx检测到内部错误，比如重启工作进程时出现套接字泄漏，开启debug_points将导致创建core文件(abort)， 或者停止进程(stop)以便使用系统调试器进行进一步分析。

error_log logs/error.log error;

配置日志。可以指定多个日志(1.5.2)在同一级别.

第一个参数定义了存放日志的文件。 如果设置为特殊值stderr，nginx会将日志输出到标准错误输出。可以配置日志记录syslog通过指定“syslog:”前缀。Logging to a cyclic memory buffer can be configured by specifying the “memory:” prefix and buffer size, and is generally used for debugging (1.7.11).

第二个参数定义日志级别。 日志级别在上面已经按严重性由轻到重的顺序列出。 设置为某个日志级别将会使指定级别和更高级别的日志都被记录下来。 比如，默认级别error会使nginx记录所有error、crit、alert和emerg级别的消息。 如果省略这个参数，nginx会使用error。

为了使debug日志工作，需要添加--with-debug编译选项。see “A debugging log”

The directive can be specified on the stream level starting from version 1.7.11.

The directive can be specified on the mail level starting from version 1.9.0.

env TZ;

nginx默认会删除从父进程继承的除TZ变量以外的所有环境变量。 这条指令允许nginx保留某些继承的环境变量，改变它们的值，或者创建新的环境变量。 这些变量将：

• 在热升级nginx执行文件时被继承；
• 被ngx_http_perl_module模块使用；
• 被工作进程使用。 请大家牢记于心，使用这种方法控制系统库不总是可行的，因为在这条指令设置环境变量以前，系统库初始化时就已检查这些环境变量的情况也并非少见。 但有一个例外，就是上面提到的热升级nginx执行文件。

TZ变量总是被继承，并且可被ngx_http_perl_module模块使用， 除非明确配置不允许这样。

使用示例：

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

NGINX环境变量是由nginx内部设置和使用，用户不应直接设置它。

提供配置上下文，以解析那些影响连接处理的指令。

将另一个file，或者匹配指定mask的文件，包含到配置中。 被包含的文件应由语法正确的指令和块组成。

使用示例：

include mime.types;
include vhosts/*.conf;

lock_file logs/nginx.lock;

nginx使用锁机制来实现accept_mutex，并将访问串行化到共享内存。 绝大多数系统中，锁是由原子操作实现，那么可以忽略这条指令。 另外一些系统使用“锁文件”的机制，那么这条指令将指定锁文件的前缀。

master_process on;

决定是否启动工作进程。这条指令是为nginx开发者设计的。

multi_accept off;

关闭时，工作进程一次只会接入一个新连接。否则，工作进程一次会将所有新连接全部接入。

使用kqueue连接处理方式时，可忽略这条指令，因为kqueue可以报告有多少新连接等待接入。

pcre_jit off;

开启或禁止在配置解析阶段为正则表达式使用“即时编译”(PCRE JIT)技术。

PCRE JIT可以显著提升处理正则表达式的速度。

从PCRE 8.20版本开始，可用PCRE的--enable-jit编译选项打开JIT功能。 当使用PCRE源码库编译nginx时(--with-pcre=)， 应该使用nginx的--with-pcre-jit编译选项开启JIT支持。

pid nginx.pid;

定义存储nginx主进程ID的file。

定义SSL硬件加速器的名字。

thread_pool default threads=32 max_queue=65536;

此指令出现于版本 1.7.11.

定义命名的线程池用于多线程读取和发送文件  不阻塞   worker 进程.

线程threads参数定义线程池中的线程数目。

事件中线程池中的所有线程都都繁忙，新进任务将在队列中等待。max_queueparameter 限制允许在队列中等待的任务的数目。默认情况下，最多 65536 任务可以等待在队列中。当队列溢出时，任务以出错结束。

在工作进程中降低定时器的精度，因此可以减少产生gettimeofday()系统调用的次数。 默认情况下，每收到一个内核事件，nginx都会调用gettimeofday()。 使用此指令后，nginx仅在每经过指定的interval时间间隔后调用一次gettimeofday()。

Example:

timer_resolution 100ms;

时间间隔的内部实现取决于使用的方法：

• 使用kqueue时，会使用EVFILT_TIMER过滤器；
• 使用eventport时，会使用timer_create()；
• 否则会使用setitimer()。

指定使用的连接处理method(方式)。 通常不需要明确设置，因为nginx默认会使用最高效的方法。

user nobody nobody;

定义工作进程使用的user和group身份。 如果省略group，nginx会使用与user相同的组名。

worker_aio_requests 32;

在使用epoll连接处理方式的情况下使用aio时， 可以设置单个工作进程未处理的异步I/O操作的最大number(数量)。

worker_connections 512;

设置每个工作进程可以打开的最大并发连接数。

需要记住，这个数量包含所有连接(比如，和后端服务器建立的连接，还有其他的）， 而不仅仅是和客户端的连接。 另外需要考虑的是，实际的并发连接数是不能超过打开文件的最大数量限制的，这个限制可以用worker_rlimit_nofile指令修改。

绑定工作进程到指定的CPU集合。每个CPU集合使用一个标记允许使用的CPU的位图来表示。 需要为每个工作进程分别设置CPU集合。 工作进程默认不会绑定到任何特定的CPU。

比如

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

将每个工作进程分别绑定至不同的CPU，而

worker_processes    2;
worker_cpu_affinity 0101 1010;

将第一个工作进程绑定至CPU0/CPU2，将第二个工作进程绑定至CPU1/CPU3。 上面第二个例子适合于超线程的机器。

这条指令仅在FreeFSD和Linux系统有效。

worker_priority 0;

定义工作进程的调度优先级。这与nice命令行所做的相同： number为负数代表优先级更高。通常允许的范围是[-20, 20]。

举例：

worker_priority -10;

worker_processes 1;

定义工作进程的数量。

关于这个值的优化依赖很多因素，其中包括（但不限于）CPU的核数，存储数据的硬盘数量和负载模式。 如果感觉到迷惑，将它设置为等于可用的CPU核数是一个不错的开始（值为“auto”时，nginx会自动检测它）。

auto参数从版本1.3.8和1.2.5开始支持。

修改工作进程的core文件尺寸的最大值限制(RLIMIT_CORE)，用于在不重启主进程的情况下增大该限制。

修改工作进程的打开文件数的最大值限制(RLIMIT_NOFILE)，用于在不重启主进程的情况下增大该限制。

定义工作进程的当前工作路径。 主要用于设置core文件的目标地址。工作进程应当具有指定路径的写权限。

七.模块参考

(1)核心模块

1. AIO(异步IO),支持freebsd及linux,

linux 配置如下

location /video/ {
    aio            on;
    directio       512;  #此行需要in linux
    output_buffers 1 128k;
}

当AIO及sendfile都可用在linux上, AIO用于文件大小大于或等于指定的directio指令,而sendfile用于较小的文件大小或者当directio是禁用的

location /video/ {
    sendfile       on;
    aio            on;
    directio       8m;
}

最后,文件可以用多线程读取和发送(1.7.11),它不会阻塞工作进程.(只支持linux,默认是禁用的)

location /video/ {
    sendfile       on;
    aio            threads;
}

核心模块其它指令 中文参考 http://tengine.taobao.org/nginx_docs/cn/docs/http/ngx_http_core_module.html

aio 在FreeBSD和Linux操作系统上启用或者禁用异步文件I/O(AIO)。
alias 定义指定路径的替换路径
chunked_transfer_encoding 允许关闭HTTP/1.1中的分块传输编码。在客户端软件不支持分块传输编码的时候，这条指令才有用.
client_body_buffer_size 设置读取客户端请求正文的缓冲容量。
client_body_in_file_only 决定nginx是否将客户端请求正文整个写入文件。
client_body_in_single_buffer 决定nginx将整个客户端请求正文保存在一块缓冲中。
client_body_temp_path 定义存储客户端请求正文的临时文件的目录。
client_body_timeout 定义读取客户端请求正文的超时。
client_header_buffer_size 设置读取客户端请求头部的缓冲容量。
client_header_timeout 定义读取客户端请求头部的超时。
client_max_body_size 设置允许客户端请求正文的最大长度
connection_pool_size 允许微调为每个连接分配的内存。
default_type 定义响应的默认MIME类型。
directio 当读入长度大于等于指定size的文件时，开启DirectIO功能。
directio_alignment 为directio设置文件偏移量对齐。
disable_symlinks 决定nginx打开文件时如何处理符号链接.
error_page 为指令错误定义显示的URI。
etag 开启或关闭为静态文件自动计算“ETag”响应头。
http 为HTTP服务器提供配置上下文。
if_modified_since 指定响应的修改时间和“If-Modified-Since”请求头的比较方法
ignore_invalid_headers 控制是否忽略非法的请求头字段名。
internal 指定一个路径是否只能用于内部访问。
keepalive_disable 针对行为异常的浏览器关闭长连接功能。
keepalive_requests 设置通过一个长连接可以处理的最大请求数。
keepalive_timeout 第一个参数设置客户端的长连接在服务器端保持的最长时间
large_client_header_buffers 设置读取客户端请求超大请求的缓冲最大number(数量)和每块缓冲的size(容量)。
limit_except 允许按请求的HTTP方法排除对某路径的请求的限制
limit_rate 限制向客户端传送响应的速率限制.
limit_rate_after 设置不限速传输的响应大小。当传输量大于此值时，超出部分将限速传送。
lingering_close 控制nginx如何关闭客户端连接。
lingering_time   lingering_close生效时，这条指令定义nginx处理(读取但忽略)客户端额外数据的最长时间。
lingering_timeout lingering_close生效时，这条指令定义nginx等待客户端更多数据到来的最长时间。
listen 设置nginx监听地址，nginx从这里接受请求。对于IP协议，这个地址就是address和port；对于UNIX域套接字协议，这个地址就是path。
location 为某个请求URI（路径）建立配置。
log_not_found 开启或者关闭在error_log中记录文件不存在的错误。
log_subrequest 开启或者关闭在access_log中记录子请求的访问日志。
max_ranges 如果请求中含有字节范围的请求头，这条指令可以限制此范围允许的最大值。如果请求头的值超过此限制，将按请求未携带此请求头的情况处理。
merge_slashes 开启或者关闭将请求URI中相邻两个或更多斜线合并成一个的功能。
msie_padding 在响应状态码大于等于400时，在响应正文中添加一段注释，使响应正文达到512字节。
msie_refresh 为MSIE客户端开启或者关闭用页面刷新取代页面重定向的功能.
open_file_cache 用于配置文件缓存
open_file_cache_errors 开启或者关闭缓存文件查找的错误结果。
open_file_cache_min_uses 设置在由open_file_cache指令的inactive参数配置的超时时间内， 文件应该被访问的最小number(次数)。
open_file_cache_valid 设置检查open_file_cache缓存的元素的时间间隔。
output_buffers 设置用于从磁盘读取一个响应的缓冲的大小和数量
port_in_redirect 开启或关闭nginx发起重定向时指定端口。
postpone_output 如果可能，到客户端的数据将被推迟发送，直到nginx需要发送的数据至少有size字节。
read_ahead 设置内核参数，控制文件预读的数量。
recursive_error_pages 允许或禁止error_page指令进行多次重定向。
request_pool_size 允许对每个请求的内存分配进行细调。这条指令对性能影响很小，通常情况下不应使用。
reset_timedout_connection 开启或关闭重置超时连接的功能。
resolver 配置将后端服务器upstream servers的名字解析成ip地址的名字服务器
resolver_timeout 为名字解析设置超时.
root 为请求设置根目录
satisfy nginx进行访问限制的有ngx_http_access_module模块和 ngx_http_auth_basic_module模块。 本指令设置成all时，表示只有当两个模块的所有限制条件(写入配置的)都授权访问时，允许请求访问； 设置成any时，表示如果当任意模块的任意限制条件授权访问时，允许请求访问
send_lowat 如果设置成非0值，nginx将尝试最小化向客户端发送数据的次数。
send_timeout 设置向客户端传输响应的超时。
sendfile 开启或关闭使用sendfile()调用。
sendfile_max_chunk 设置为非0值时，可以限制在一次sendfile()调用时传输的数据量。
server 表示开始设置虚拟主机的配置。
server_name 设置虚拟主机名
server_name_in_redirect 开启或关闭nginx将server_name指令指定的首要虚拟主机名用于发起的重定向的功能。
server_names_hash_bucket_size 设置主机名哈希桶大小
server_names_hash_max_size 设置主机名哈希表的最大size(容量)
server_tokens 开启或关闭在错误信息或在“Server”响应头中输出nginx版本号。
tcp_nodelay 开启或关闭nginx使用TCP_NODELAY选项的功能。 这个选项仅在将连接转变为长连接的时候才被启用。（译者注，在upstream发送响应到客户端时也会启用）。
tcp_nopush 开启或者关闭nginx在FreeBSD上使用TCP_NOPUSH套接字选项， 在Linux上使用TCP_CORK套接字选项。 选项仅在使用sendfile的时候才开启。 开启此选项允许 :在Linux和FreeBSD 4.*上将响应头和正文的开始部分一起发送；一次性发送整个文件。
try_files 按指定顺序检查文件是否存在.
types 设置文件扩展名和响应的MIME类型的映射表。
types_hash_bucket_size 设置MIME类型哈希桶大小，其默认值取决于处理器的缓存线长度。
types_hash_max_size 设置MIME类型哈希表的最大size(容量)
underscores_in_headers 允许或禁止在客户端请求头中使用下划线。
variables_hash_bucket_size 设置变量哈希桶大小，其默认值取决于处理器的缓存线长度。
variables_hash_max_size 设置变量哈希表的最大size(容量)。
Embedded Variables 内嵌变量

（2）其它模块

• ngx_http_access_module 模块 ngx_http_access_module 允许限制某些IP地址的客户端访问。
• ngx_http_addition_module ngx_http_addition_module 是一个过滤模块，它可以在回复正文前后加上内容。 这个模块默认不会编译进去，若要开启需加上编译选项：--with-http_addition_module。
• ngx_http_auth_basic_module 模块ngx_http_auth_basic_module 允许使用“HTTP基本认证”协议验证用户名和密码来限制对资源的访问。
• ngx_http_auth_request_module 实现基于服务器内部子请求的返回结果来控制用户鉴权.
• ngx_http_autoindex_module ngx_http_autoindex_module 模块可以列出目录中的文件。 一般当ngx_http_index_module模块找不到默认主页的时候，会把请求转给ngx_http_autoindex_module模块去处理
• ngx_http_browser_module 浏览器重定向模块.
• ngx_http_charset_module ngx_http_charset_module模块为响应头的“Content-Type”添加指定的字符集。
• ngx_http_dav_module  ngx_http_dav_module模块通过WebDAV协议用于文件管理自动化.
• ngx_http_empty_gif_module 模块 ngx_http_empty_gif_module 只返回一个像素的透明GIF图片
• ngx_http_f4f_module  The ngx_http_f4f_module module provides server-side support for Adobe HTTP Dynamic Streaming (HDS).
• ngx_http_fastcgi_module 充许传送请求到一个fastcgi服务器.一般用于解析PHP用.
• ngx_http_flv_module 模块ngx_http_flv_module 为Flash Video(FLV)文件 提供服务端伪流媒体支持
• ngx_http_geo_module ngx_http_geo_module 模块创建变量，并根据客户端IP地址对变量赋值。
• ngx_http_geoip_module ngx_http_geoip_module 模块（0.8.6+）创建变量，使用预编译的MaxMind数据库解析客户端IP地址，得到变量值。
• ngx_http_gunzip_module ngx_http_gunzip_module模块是一个过滤器， 它为不支持“gzip”编码方法的客户端解压具有“Content-Encoding: gzip”头的响应。 当希望存储压缩后的数据以节省空间和减少I/O开销，又不希望对那些不支持gzip压缩的客户端造成不利影响时， 此模块会派上用途。
• ngx_http_gzip_module ngx_http_gzip_module模块是一个过滤器,使用“gzip方法压缩响应。这通常有助于减少传输数据的大小了一半甚至更多
• ngx_http_gzip_static_module 模块 ngx_http_gzip_static_module 允许发送以“.gz”作为文件扩展名的预压缩文件，以替代发送普通文件。
• ngx_http_headers_module  ngx_http_headers_module模块提供了两个重要的指令add_header和expires，来添加 “Expires” 和 “Cache-Control” 头字段，对响应头添加任何域字段。
• ngx_http_hls_module 提供HTTP直播(HLS)服务器端支持MP4和MOV媒体文件
• ngx_http_image_filter_module ngx_http_image_filter_module 模块（0.7.54+）是一个 过滤器，它可以对JPEG,GIF和PNG等图像进行变换.
• ngx_http_index_module 模块 ngx_http_index_module 处理以斜线字符(‘/’)结尾的请求。
• ngx_http_limit_conn_module ngx_http_limit_conn_module 模块可以按照定义的键限定每个键值的连接数。特别的，可以设定单一 IP 来源的连接数。
• ngx_http_limit_req_module ngx_http_limit_req_module模块(0.7.21)可以通过定义的 键值来限制请求处理的频率。特别的，它可以限制来自单个IP地址的请求处理频率。
• ngx_http_log_module ngx_http_log_module模块按指定的格式写访问日志.
• ngx_http_map_module 模块 ngx_http_map_module 可以创建一些和另外变量相关联的变量。
• ngx_http_memcached_module   从memcached 服务器获取响应.
• ngx_http_mp4_module 模块ngx_http_mp4_module为H.264/AAC文件，主要是以 .mp4、.m4v、和.m4a为扩展名的文件， 提供伪流媒体服务端支持。
• ngx_http_perl_module 该模块使nginx可以直接使用perl或通过ssi调用perl
• ngx_http_proxy_module 模块允许传送请求到其它服务器
• ngx_http_random_index_module ngx_http_random_index_module模块在文件夹中随机选择一个文件作为默认页
• ngx_http_realip_module 允许从请求标头更改客户端的IP地址值
• ngx_http_referer_module ngx_http_referer_module模块允许拦截“Referer”请求头中含有非法值的请求，阻止它们访问站点。常用于防盗链.
• ngx_http_rewrite_module ngx_http_rewrite_module模块允许正则替换URI，返回页面重定向，和按条件选择配置。
• ngx_http_scgi_module 该模块用来启用SCGI协议支持
• ngx_http_secure_link_module nginx安全下载模块可以给服务器文件链接添加时间戳和校验码，从而保护服务器文件不被任意下载盗用。
• ngx_http_session_log_module ngx_http_session_log_module模块启用日志会话(即聚合多个HTTP请求)代替单独的HTTP请求。
• ngx_http_spdy_module spdy模块,被 HTTP/2模块取代.
• ngx_http_split_clients_module ngx_http_split_clients_module模块创建适合于A/B测试（也叫做分离测试）的变量。
• ngx_http_ssi_module 此模块处理服务器端包含文件(ssi)的处理
• ngx_http_ssl_module 提供了必要的HTTPS支持
• ngx_http_status_module 提供对各种状态信息的访问
• ngx_http_stub_status_module 这个模块能够获取Nginx自上次启动以来的基本工作状态
• ngx_http_sub_module ngx_http_sub_module模块是一个过滤器，它修改网站响应内容中的字符串
• ngx_http_upstream_module ngx_http_upstream_module模块 允许定义一组服务器。它们可以在指令proxy_pass、 fastcgi_pass和 memcached_pass中被引用到。Nginx 负载均衡模块.
• ngx_http_upstream_conf_module  允许动态配置负载均衡服务器组通过一个简单的HTTP接口不需要重新启动nginx
• ngx_http_userid_module ngx_http_userid_module模块适合客户端设置cookie识别
• ngx_http_uwsgi_module uwsgi 模块
• ngx_http_v2_module HTTP/2 模块
• ngx_http_xslt_module 一个过滤器,使用一个或多个XSLT样式表转换XML响应

邮件模块

• ngx_mail_core_module
• ngx_mail_auth_http_module
• ngx_mail_proxy_module
• ngx_mail_ssl_module
• ngx_mail_imap_module
• ngx_mail_pop3_module
• ngx_mail_smtp_module

stream 模块用于一般的 TCP 代理和负载均衡.  这个模块在1.90版本后将被启用。但是并不会默认安装，需要在编译时通过指定 --with-stream 参数来激活这个模块。.

• ngx_stream_core_module
• ngx_stream_access_module
• ngx_stream_limit_conn_module
• ngx_stream_proxy_module
• ngx_stream_ssl_module
• ngx_stream_upstream_module

转载请注明出处http://blog.p2hp.com/archives/2457。

最后更新于 2019年3月31日