10.9. nginx基础配置说明¶

10.9.1. 核心模块¶

10.9.1.1. user¶

Syntax:     user user [group];
Default:
user nobody nobody;
Context:    main

默认值是nobody，但是rpm包编译都是指定的nginx了，即使你没有指定该配置也是nginx。

10.9.1.2. pid¶

Syntax:     pid file;
Default:
pid logs/nginx.pid;
Context:    main

这个配置项指定了nginx的master主进程的进程id存储的文件。

10.9.1.3. include¶

Syntax:     include file | mask;
Default:    —
Context:    any

包含特定的配置文件到当前文件中来。

10.9.1.4. load_module¶

Syntax:     load_module file;
Default:    —
Context:    main
This directive appeared in version 1.9.11.

加载特定的模块进来。

10.9.1.5. worker_cpu_affinity¶

Syntax:     worker_cpu_affinity cpumask ...;
worker_cpu_affinity auto [cpumask];
Default:    —
Context:    main
样例：
    worker_processes    4;
    worker_cpu_affinity 0001 0010 0100 1000;

10.9.1.6. worker_processes¶

Syntax:     worker_processes number | auto;
Default:
worker_processes 1;
Context:    main

定义下worker进程的个数， auto的话就是cpu的个数。

10.9.1.7. worker_priority¶

Syntax:     worker_priority number;
Default:
worker_priority 0;
Context:    main

指定工作进程的优先级的，数值越大，优先级越低。

10.9.1.8. worker_rlimit_nofile¶

Syntax:     worker_rlimit_nofile number;
Default:    —
Context:    main

每个worker进程可以打开的文件数量。

10.9.1.9. worker_connections¶

Syntax:     worker_connections number;
Default:
worker_connections 512;
Context:    events

工作进程的连接数量。

10.9.1.10. use¶

Syntax:     use method;
Default:    —
Context:    events
样例：
    use epoll;

指明并发连接请求的处理方法，默认自动选择最优方法

10.9.1.11. accept_mutex¶

Syntax:     accept_mutex on | off;
Default:
accept_mutex off;
Context:    events

处理新连接请求的方法， on代表有新连接的时候，唤醒所有worker进程，但是只有一个获得连接。

10.9.1.12. daemon¶

Syntax:     daemon on | off;
Default:
daemon on;
Context:    main

on代表nginx后台运行的，off代表前台运行。

10.9.1.13. master_process¶

Syntax:     master_process on | off;
Default:
master_process on;
Context:    main

是否以master/worker模型去运行nginx, 默认为on,off将不启动worker。

10.9.1.14. error_log¶

Syntax:     error_log file [level];
Default:
error_log logs/error.log error;
Context:    main, http, mail, stream, server, location

指定错误日志位置的，可以指定到stderr,syslog,memory。

10.9.2. 标准模块¶

10.9.2.1. listen¶

Syntax:     listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
listen unix:path [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default:
listen *:80 | *:8000;
Context:    server

指定监听地址。

10.9.2.2. server_name¶

Syntax:     server_name name ...;
Default:
server_name "";
Context:    server

指定主机名字

匹配优先级机制从高到低：

首先是字符串精确匹配如：www.magedu.com
左侧*通配符如：*.magedu.com
右侧*通配符如：www.magedu.*
正则表达式如： ~^.*.magedu.com$
default_server

10.9.2.3. root¶

Syntax:     root path;
Default:
root html;
Context:    http, server, location, if in location

指定根位置的

10.9.2.4. tcp_nodelay¶

Syntax:     tcp_nodelay on | off;
Default:
tcp_nodelay on;
Context:    http, server, location

keepalived模式下是不是延迟发送，将多个请求合并在发送。

10.9.2.5. sendfile¶

Syntax:     sendfile on | off;
Default:
sendfile off;
Context:    http, server, location, if in location

是否开启sendfile功能，在内核中封装报文直接发送，默认是off的。

10.9.2.6. server_tokens¶

Syntax:     server_tokens on | off | build | string;
Default:
server_tokens on;
Context:    http, server, location

是否在响应报文的server首部显示nginx版本信息。

10.9.2.7. location¶

Syntax:     location [ = | ~ | ~* | ^~ ] uri { ... }
location @name { ... }
Default:    —
Context:    server, location

在一个server中location配置端可以有多个，用于实现从uri到文件系统的路径映射，找到最佳的应用配置。

匹配优先级从高到低： =, ^~, ～/～*, 不带符号

10.9.2.8. alias¶

Syntax:     alias path;
Default:    —
Context:    location

定义路径别名的，文档映射的另外一种机制。

10.9.2.9. index¶

Syntax:     index file ...;
Default:
index index.html;
Context:    http, server, location

指定默认网页的，默认值是index.html

10.9.2.10. error_page¶

Syntax:     error_page code ... [=[response]] uri;
Default:    —
Context:    http, server, location, if in location
样例配置：
    error_page 404             /404.html;
    error_page 500 502 503 504 /50x.html;
    error_page 404 =200 /empty.gif;

定义错误页的。

10.9.2.11. try_files¶

Syntax:     try_files file ... uri;
try_files file ... =code;
Default:    —
Context:    server, location
样例：
    location / {
        try_files $uri $uri/index.html $uri.html =404;
    }

是否在响应报文的server首部显示nginx版本信息。

10.9.2.12. keepalive_timeout¶

Syntax:     keepalive_timeout timeout [header_timeout];
Default:
keepalive_timeout 75s;
Context:    http, server, location

设定保存连接超时时长，0表示禁止长连接，默认是75s。

10.9.2.13. keepalive_requests¶

Syntax:     keepalive_requests number;
Default:
keepalive_requests 100;
Context:    http, server, location
This directive appeared in version 0.8.0.

在一次长连接上所运行请求的资源的最大数量，默认是100。

10.9.2.14. keepalive_disable¶

Syntax:     keepalive_disable none | browser ...;
Default:
keepalive_disable msie6;
Context:    http, server, location

对特定浏览器禁用长连接。

10.9.2.15. send_timeout¶

Syntax:     send_timeout time;
Default:
send_timeout 60s;
Context:    http, server, location

向客户端发送响应报文的超时时长，此处是指两次写操作之间的间隔时长，而非整个响应过程的传输时长。

10.9.2.16. client_body_buffer_size¶

Syntax:     client_body_buffer_size size;
Default:
client_body_buffer_size 8k|16k;
Context:    http, server, location

用于接受每个客户端请求报文的body部分的缓冲区大小，默认为16k,超过这个大小就将其暂存到磁盘上的client_body_temp_path位置。

10.9.2.17. client_body_temp_path¶

Syntax:     client_body_temp_path path [level1 [level2 [level3]]];
Default:
client_body_temp_path client_body_temp;
Context:    http, server, location

设定用于存储客户端请求报文的body部分的临时存储路径及子目录结构和数量

10.9.2.18. limit_rate¶

Syntax:     limit_rate_after size;
Default:
limit_rate_after 0;
Context:    http, server, location, if in location
This directive appeared in version 0.8.0.

用于限制响应给客户端的传输速率，单位是bytes,0代表不限制。

10.9.2.19. limit_except¶

Syntax:     limit_except method ... { ... }
Default:    —
Context:    location
样例：
    limit_except GET {
    allow 192.168.1.0/24;
    deny all;
    }
代表处理get,head之外的其他方法，只允许192.168.1.0/24网段访问。

限制客户端使用除了特定的请求方法之外的其他方法。

10.9.2.20. aio¶

Syntax:     aio on | off | threads[=pool];
Default:
aio off;
Context:    http, server, location
This directive appeared in version 0.8.11.

是否启用异步io功能。

10.9.2.21. directio¶

Syntax:     directio size | off;
Default:
directio off;
Context:    http, server, location
This directive appeared in version 0.7.7.

大于给定的文件大小的死后，直接同步到磁盘，而非写文件。

10.9.2.22. open_file_cache¶

Syntax:     open_file_cache off;
open_file_cache max=N [inactive=time];
Default:
open_file_cache off;
Context:    http, server, location

是否打开文件缓存，需要配合open_file_cache max=N使用，可以缓存的信息如下：

文件元数据信息
打开的目录结构
没有找到的或者没有访问权限的文件的相关信息。

10.9.2.23. open_file_cache_errors¶

Syntax:     open_file_cache_errors on | off;
Default:
open_file_cache_errors off;
Context:    http, server, location

是否缓存查找时发生错误的文件一类的信息，默认是off。

10.9.2.24. open_file_cache_min_uses¶

Syntax:     open_file_cache_min_uses number;
Default:
open_file_cache_min_uses 1;
Context:    http, server, location

在指定的时常内，至少被明智特定的次数才可以归为活动项。

10.9.2.25. open_file_cache_valid¶

Syntax:     open_file_cache_valid time;
Default:
open_file_cache_valid 60s;
Context:    http, server, location

缓存项邮箱型检查的频率，默认是60s。

10.9.3. ngx_http_access_module¶

10.9.3.1. allow¶

用法： allow address | CIDR | unix: | all;

用于允许特定主机访问

10.9.3.2. deny¶

用法： deny address | CIDR | unix: | all;

用于禁止特定主机访问

Attention

这里的allow、deny和apache中不一样，如果有一条匹配就返回对应结果。

10.9.4. ngx_http_auth_basic_module¶

10.9.4.1. auth_basic¶

用法：auth_basic string | off;

提示认证的信息文本内容

10.9.4.2. auth_basic_user_file¶

用法：auth_basic_user_file file;

认证的基本用户文件，口令文件使用htpasswd命令实现（在httpd-tools包里面提供）

样例：

location /admin/ {
auth_basic "Admin Area";
auth_basic_user_file /etc/nginx/.ngxpasswd;
}

10.9.5. ngx_http_stub_status_module¶

10.9.5.1. auth_basic¶

提示输出nginx的基本状态信息。

样例：

location /status {
stub_status;
allow 172.16.0.0/16;
deny all;
}

10.9.6. ngx_http_log_module¶

10.9.6.1. log_format¶

用法：log_format name string …;

日志格式定义

10.9.6.2. access_log¶

用法：access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]];

访问日志文件路径，格式和相关的缓冲区压缩等相关配置。

样例：

log_format compression '$remote_addr-$remote_user [$time_local] '
'"$request" $status $bytes_sent '
'"$http_referer" "$http_user_agent" "$gzip_ratio"';
access_log /spool/logs/nginx-access.log compression buffer=32k;

10.9.6.3. open_log_file_cache¶

用法 open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];

缓存各个日志文件的信息。

10.9.7. ngx_http_gzip_module¶

10.9.7.1. log_format¶

用法：gzip on | off;

启用或者禁用gzip压缩

10.9.7.2. gzip_comp_level¶

用法：gzip_comp_level level;

压缩比，默认是1

10.9.7.3. gzip_disable¶

用法：gzip_disable regex …;

匹配到特定浏览器客户端不执行压缩功能。

10.9.7.4. gzip_min_length¶

用法：gzip_min_length length;

启用压缩功能的响应报文的大小阈值，低于特定值就不压缩了。

10.9.7.5. gzip_http_version¶

用法： gzip_http_version 1.0 | 1.1;

设定启用压缩功能时，协议的最小版本。

10.9.7.6. gzip_buffers¶

用法：gzip_buffers number size;

支持实现压缩功能时缓冲区熟练及每个缓存区的大小。

10.9.7.7. gzip_types¶

用法： gzip_types mime-type …;

那些资源进行压缩

10.9.7.8. gzip_vary¶

用法：gzip_vary on | off;

如果启用了压缩，是否在响应报文首部插入“Vary: Accept-Encoding”

10.9.7.9. gzip_proxied¶

充当代理服务器的时候，对于后端服务器的响应报文何种条件下启动压缩功能。

样例：

gzip on;
gzip_comp_level 6;
gzip_min_length 64;
gzip_proxied any;
gzip_types text/xml text/css application/javascript;

10.9.8. ngx_http_ssl_module¶

10.9.8.1. ssl¶

用法：ssl on | off;

是否启用ssl功能

10.9.8.2. ssl_certificate¶

用法： ssl_certificate file;

ssl证书文件

10.9.8.3. ssl_certificate_key¶

用法： ssl_certificate_key file;

证书私钥

10.9.8.4. ssl_protocols¶

用法： ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1]

支持ssl版本协议，默认为后面3个。

10.9.8.5. ssl_session_cache¶

用法：ssl_session_cache off | none | [builtin[:size]] [shared:name:size];

ssl会话缓存

10.9.8.6. ssl_session_timeout¶

用法： ssl_session_timeout time;

ssl会话超时

样例：

server {
listen 443 ssl;
server_name www.linuxpanda.com;
root /vhosts/ssl/htdocs;
ssl on;
ssl_certificate /etc/nginx/ssl/nginx.crt;
ssl_certificate_key /etc/nginx/ssl/nginx.key;
ssl_session_cache shared:sslcache:20m;
ssl_session_timeout 10m;
}

10.9.9. ngx_http_rewrite_module¶

10.9.9.1. rewrite¶

用法： rewrite regex replacement [flag]

将用户请求的URI基于regex所描述的模式进行检查，匹配到时将其替换为replacement指定的新的URI

last: 重写完成后停止对当前URI在当前location中后续的其它重写操作，而后对新的URI启动新一轮重写检查；提前重启新一轮循环，不建议在location中使用
break: 重写完成后停止对当前URI在当前location中后续的其它重写操作，而后直接跳转至重写规则配置块之后的其它配置；结束循环，建议在location中使用。
redirect: 临时重定向，重写完成后以临时重定向方式直接返回重写后生成的新URI给客户端，由客户端重新发起请求；使用相对路径,或者http://或https://开头，状态码：302
permanent: 重写完成后以永久重定向方式直接返回重写后生成的新URI给客户端，由客户端重新发起请求，状态码：301

10.9.9.2. return¶

用法： return code [text]; 或者 return code [text]; 或者 return URL;

停止处理，并返回给客户端指定的响应码。

10.9.9.3. rewrite_log¶

用法： rewrite_log on | off;

是否开启重写日志，发送到error_log

10.9.9.4. set¶

用法： set $variable value;

设置自定义变量

10.9.9.5. if¶

用法： if (condition) { … }

针对特定条件判定

比较操作符：
    = 相同
    != 不同
    ~：模式匹配，区分字符大小写
    ~*：模式匹配，不区分字符大小写
    !~：模式不匹配，区分字符大小写
    !~*：模式不匹配，不区分字符大小写

文件及目录存在性判断：
    -e, !-e 存在（包括文件，目录，软链接）
    -f, !-f 文件
    -d, !-d 目录
    -x, !-x 执行

10.9.10. ngx_http_referer_module¶

10.9.10.1. valid_referers¶

用法： valid_referers none|blocked|server_names|string …;

定义referer首部的合法可用值，不能匹配的将是非法值。

node: 报文首部没有referer首部
blocked: 请求报文没有referer首部，但无有效值
server_names: 主机名或者主机名模式
arbitray_string:任意字符串，但可以使用*作为通配符
regular expression: 正则表达式模式匹配到的字符串，要使用~开头。

样例：

valid_referers none block server_names *.linuxpanda.tech;
if ($invalid_referer) {
return 403 http://www.magedu.com;
}

10.9.11. ngx_http_proxy_module¶

10.9.11.1. proxy_pass¶

用法： proxy_pass URL;

代理的路径，样例：

server {
...
server_name HOSTNAME;
location /uri/ {
proxy_pass http://host[:port]; 最后没有/
}
...
}

使用此功能，可以动静分离，将静态文件和动态文件分开调度。

10.9.11.2. proxy_set_header¶

用法： proxy_set_header field value;

设定发往后端主机的请求报文的请求首部的值。

10.9.11.3. proxy_cache_path¶

用法： proxy_cache_path;

用于定义可用于proxy功能的缓存

10.9.11.4. proxy_cache¶

用法：proxy_cache zone | off; 默认off

指定调用的缓存，或关闭缓存机制

10.9.11.5. proxy_cache_key¶

用法： proxy_cache_key string;

缓存中用于键的内容，默认： proxy_cache_key $scheme$proxy_host$request_uri;

10.9.11.6. proxy_cache_valid¶

用法： proxy_cache_valid [code …] time;

定义对特定响应码的响应内容的缓存时长

样例：

proxy_cache proxycache;
proxy_cache_key $request_uri;
proxy_cache_valid 200 302 301 1h;
proxy_cache_valid any 1m;

10.9.11.7. proxy_cache_use_stale;¶

在被代理的后端服务器出现哪种问题的情况下，可以直接使用过期的响应客户端。

10.9.11.8. proxy_cache_method¶

用法：proxy_cache_methods GET | HEAD | POST …;

对那些客户端的请求方法对应的响应进行缓存，get和head方法总是被缓存的。

10.9.11.9. proxy_hide_header¶

用法： proxy_hide_header field;

用于隐藏后端服务器的特定的响应首部

10.9.11.10. proxy_connect_timeout¶

用法： proxy_connect_timeout time;

与后端服务器建立连接的超时时长，超过返回502错误。

10.9.11.11. proxy_send_timeout¶

用法：proxy_send_timeout time

将请求发送给后端服务器的超时时长。

10.9.11.12. proxy_read_timeout¶

用法： proxy_read_timeout time;

等待后端服务器发送响应报文的超时时长

10.9.12. ngx_http_headers_module¶

10.9.12.1. set¶

用法： set $variable value;

设置自定义变量

10.9.12.2. add_header¶

用法： add_header name value [always];

添加自定义头信息

10.9.12.3. add_trailer¶

用法：add_trailer name value [always];

add_trailer添加自定义响应信息的尾部

10.9.13. ngx_http_fastcgi_module¶

10.9.13.1. fastcgi_pass¶

用法： fastcgi_pass address;

后端的fastcgi服务器地址

10.9.13.2. fastcgi_index¶

用法： fastcgi_index name;

fastcgi 默认主页资源

10.9.13.3. fastcgi_param¶

用法： fastcgi_param parameter value [if_not_empty];

设置传递给 FastCGI服务器的参数值，可以是文本，变量或组合

样例：

location ~* \.php$ {
fastcgi_pass 后端fpm服务器IP:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME
/usr/share/nginx/html$fastcgi_script_name;
include fastcgi_params;
…
}


location ~* ^/(pm_status|ping)$ {
include fastcgi_params;
fastcgi_pass 后端fpm服务器IP :9000;
fastcgi_param SCRIPT_FILENAME $fastcgi_script_name;
}

10.9.13.4. fastcgi_cache_path¶

用法：fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];

缓存路径。

10.9.13.5. fastcgi_cache¶

用法： fastcgi_cache zone | off;

调用指定的缓存空间来缓存数据

10.9.13.6. fastcgi_cache_key¶

用法： fastcgi_cache_key string;

定义用作缓存项的key的字符串

10.9.13.7. fastcgi_cache_method¶

用法： fastcgi_cache_methods GET | HEAD | POST …;

为哪些请求方法使用缓存

10.9.13.8. fastcgi_cache_min_uses¶

用法：fastcgi_cache_min_uses number;

缓存空间中的缓存项在inactive定义的非活动时间内至少要被访问到此处所指定的次数方可被认作活动项

10.9.13.9. fastcgi_keep_conn¶

用法： fastcgi_keep_conn on | off;

收到后端服务器响应后，fastcgi服务器是否关闭连接，建议启用长连接

10.9.13.10. fastcgi_cache_valid¶

用法： fastcgi_cache_valid [code …] time;

不同的响应码各自的缓存时长

样例：

http {
    fastcgi_cache_path /var/cache/nginx/fcgi_cache
    levels=1:2:1 keys_zone=fcgicache:20m inactive=120s;
    ...
    server {
        location ~* \.php$ {
        ...
        fastcgi_cache fcgicache;
        fastcgi_cache_key $request_uri;
        fastcgi_cache_valid 200 302 10m;
        fastcgi_cache_valid 301 1h;
        fastcgi_cache_valid any 1m;
        ...
        }
}

10.9.14. ngx_http_upstream_module¶

10.9.14.1. upstream¶

用法： upstream name { … }

定义后端服务器组，会引入一个新的上下文。

10.9.14.2. server¶

用法： server address [parameters];

定义后端服务器成员，weight定义权重，max_conn最大连接数量，max_fails失败尝试最大次数 faile_timeout后端标记不可用状态的时长，backup备用，down不可用。

10.9.14.3. ip_hash¶

用法： ip_hash

源地址hash调度算法

10.9.14.4. least_conn¶

用法： least_conn

最小连接调度算法

10.9.14.5. hash key¶

用法：hash key [consistent]

基于特定的key的hash表来实现对请求的调度。

10.9.14.6. keepalive¶

用法：keepalive 连接数N

为每个worker进程保留的空闲的长连接数量。

10.9.14.7. health_check¶

用法： health_check [parameters];

健康性检查，interval检查频率，fails失败次数，passes判定成功次数，uri测试目标，match指定的match配置块。

10.9.14.8. match¶

用法： match name { … }

对后端的服务器做健康检查时候，定义其结果判断机制，只能用于http上下文。

10.9.14.9. fastcgi_cache_valid¶

用法： fastcgi_cache_valid [code …] time;

不同的响应码各自的缓存时长

10.9.15. ngx_stream_core_module¶

10.9.15.1. stream¶

用法： stream { … }

不同的响应码各自的缓存时长

样例：

stream {
    upstream mysqlsrvs {
    server 192.168.22.2:3306;
    server 192.168.22.3:3306;
    least_conn;
    }
    server {
    listen 10.1.0.6:3306;
    proxy_pass mysqlsrvs;
    }
}

10.9.15.2. listen¶

用法： listen address:port [ssl] [udp] [proxy_protocol] [backlog=number] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];

定义监听信息

10.9.16. ngx_stream_proxy_module¶

10.9.16.1. proxy_pass¶

用法：proxy_pass address;

指定后端服务器地址

10.9.16.2. proxy_timeout¶

用法：proxy_timeout timeout;

无数据传输时候，保存连接状态的超时时长

10.9.16.3. porxy_connect_timeout¶

用法：proxy_connect_timeout time;

设置nginx与被代理的服务器尝试建立连接的超时时长默认为60s

样例配置

stream {

    upstream mysqlsrvs {
    server 192.168.0.10:3306;
    server 192.168.0.11:3306;
    hash $remote_addr consistent;
    }

    server {
    listen 172.16.100.100:3306;
    proxy_pass mysqlsrvs;
    proxy_timeout 60s;
    proxy_connect_timeout 10s;
    }
}