nginx的配置

nginx的配置

通用语法

块配置项由一个块配置项和一对大括号组成，块配置项可嵌套。
配置项的语法格式：配置项名配置项值1 配置项值2;
在一行前面加"#"表示注释

配置项的单位

指定空间大小

    K或者k千字节(KB)

    M或者m千字节(MB)

指定时间

    ms(毫秒)

    s(秒)

    m(分钟)

    h(小时)

    d(天)

    w(周，包含7天)

    M(月，包含30天)

    y(年，包含365天)

基本配置

用于调试进程、定位问题的配置项
- daemon on | off; 是否以守护进程方式运行nginx，默认是
- master_process on | off; 是否以master/worker方式工作，默认是
- error_log /path/file level; error日志设置
  - /path/file参数可以是一个具体的文件，默认为logs/error.log文件
  - /path/file可以是/dev/null，这是关闭error日志的唯一手段
  - /path/file可以是stderr，这样日志会输出到标准错误文件中
  - level是日志的输出级别，取值范围：debug、info、notice、warn、error、crit、alert、emerg
  - 当设定为一个级别时，大于或等于该级别的日志都会被输出到/path/file文件中，小于该级别的日志则不会输出
  - 如果日志级别设定到debug，必须在configure时加入--with-debug配置项
- debug_points [stop | abort]; 是否处理几个特殊的调试点（通常不会使用这个配置项）
- debug_connection [IP | CIDR]; 仅对指定的客户端输出debug级别的日志
  - 这个配置项属于事件类配置项，必须放在events {...}中才有效
  - 使用debug_connection前，必须在configure时加入--with-debug配置项
- worker_rlimit_core size; 限制coredump核心转储文件的大小
- working_directory path; 指定coredump文件生成目录
  - 需确保worker进程有权限向working_directory指定的目录中写入文件
正常运行的配置项
- env VAR|VAR=VALUE; 定义环境变量
- include /path/file; 嵌入其他配置文件
- pid path/file; pid文件的路径，默认为pid logs/nginx.pid;
- user username [groupname]; nginx worker进程运行的用户及用户组，默认为user nobody nobody;
- worker_rlimit_nofile limit; 指定nginx worker进程可以打开的最大句柄描述符个数
- worker_rlimit_sigpending limit; 限制信号队列
优化性能的配置项
- worker_processes number; nginx worker进程个数，默认为worker_processes 1
  - 模块间确认不会出现阻塞式的调用，则有多少CPU内核就应该配置多少个进程(内核个数可以通过命令cat /proc/stat查看stat文件)
  - 模块间确认会出现阻塞式的调用，则根据需要配置稍多一些的worker进程
- worker_cpu_affinity cpumask [cpumask...] 绑定nginx worker进程到指定的cpu内核
  - 2核是 01，四核是0001，8核是00000001，有多少个核，就有几位数，1表示该内核开启，0表示该内核关闭。
  - worker_processes最多开启8个，8个以上性能提升不会再提升了，而且稳定性变得更低，所以8个进程够用了。
```
2核CPU开8进程，那么可以写为：

worker_processes  8;

worker_cpu_affinity 01 10 01 10 01 10 01 10;
```
- ssl_engine device; SSL硬件加速
  - 需确保服务器上有SSL硬件加速设备，通过命令openssl engine -t查看是否有SSL硬件加速设备
- timer_resolution t; 系统调用gettimeofday的执行频率（一般不用配置）
- worker_priority nice; nginx worker进程优先级设置，默认为worker_priority=0;
  - nice值是进程的静态优先级，取值范围是-20~+19，-20是最高优先级
  - 不建议把worker进程的nice值设置比内核进程的nice值(通常为-5)小
事件类配置项
- accept_mutex [on | off]; 是否打开accept(负载均衡)锁，默认为accept_mutex on;
- lock_file path/file; lock文件的路径，默认为lock_file logs/nginx.lock;
  - 打开accept锁并且nginx不支持原子锁，lock_file配置才会生效
- accept_mutex_delay Nms; 使用accept锁后到真正建立连接之间的延迟时间，默认为accept_mutex_delay 500ms;cept off;
- use [kqueue | rtsig | epoll | /dev/poll | select | poll | even
- multi_accept [on | off]; 批量建立新连接，默认为multi_actport]; 选择事件模型，默认nginx会自动使用最合适的事件模型
- worker_connections number; 每个worker的最大连接数
```
      从用户的角度，http 1.1协议下，由于浏览器默认使用两个并发连接,因此计算方法：

      nginx作为http服务器的时候：max_clients = worker_processes * worker_connections/2

      nginx作为反向代理服务器的时候：max_clients = worker_processes * worker_connections/4
```

静态web服务器的配置项

虚拟主机与请求的分发
- listen address:port [ default | default_server | backlog=num | rcvbuf=size | sndbuf=size | accept_filter=filter | deferred | bind | ipv6only=[on | off] | ssl]; 监听端口，直属于server块，默认listen 80;
  - default、default_server：将所在的server块作为整个web服务的默认server块;默认将nginx.conf中找到的第一个server块作为默认server块
  - backlog=num：表示TCP中backlog队列的大小,默认为-1(不予设置)
  - rcvbuf=size：设置监听句柄的SO_RCVBUF参数
  - sndbuf=size：设置监听句柄的SO_SNDBUF参数
  - accept_filter：设置accept过滤器，只对FreeBSD操作系统有用
  - deferred：当请求数据来临时，worker进程才会开始处理这个连接
  - bind：绑定当前端口/地址对，只有同时对一个端口监听多个地址时才会生效
  - ssl：在当前监听的端口上建立的连接必须基于SSL协议
- server_name name [...]; 主机名称，直属于server块，默认server_name "";
  - server_name后可以跟多个主机名称
  - server_name与host的匹配优先级
    - 首先选择所有字符串完全匹配的server_name,如www.testweb.com
    - 其次选择通配符在前面的server_name,如*.testweb.com
    - 再次选择通配符在后面的server_name,如www.testweb.*
    - 最后选择使用正则表达式才匹配的server_name,如~^\.testweb\.com$
  - server_name与host不匹配
    - 优先选择在listen配置项后加入[default | default_server]的server块
    - 找到匹配listen端口的第一个server块
- server_names_hash_bucket_size size; 每个散列桶占用的内存大小，直属于http、server、location，默认serveer_names_hash_bucket_size 32|64|128;
- server_names_hash_max_size size; 散列表的冲突率，直属于http、server、location，默认server_names_hash_max_size 512;
- server_name_in_redirect on | off; 重定向主机名称的处理，直属于http、server、location，默认server_name_in_redirect on;
  - 本配置需要配合server_name使用
- location [=|_|*|^~|@] /uri/ {...} 根据用户请求中的URI来匹配/uri/表达式，直属于server
  - = 表示把URI作为字符串，以便与参数中的uri做完全匹配
  - ~ 表示匹配URI时是字母大小写敏感
  - ~* 表示匹配URI忽略字母大小写问题
  - ^~ 表示匹配URI时只需要其前半部分与uri参数匹配即可
  - @ 表示仅用于nginx服务内部请求之间的重定向，带有@的location不直接处理用户请求
  - 如果需要表达“如果不匹配...则...”，可以在最后一个location中使用/作为参数，它会匹配所有的http请求，这样就可以表示如果不能匹配前面的所有location,则有“/”这个location处理
文件路径的定义
- root path; 以root方式设置资源路径，直属于http、server、location、if，默认root html;
- alias path; 以alias方式设置资源路径，直属于location
  - root和alias区别在于是否会根据完整的URI请求来映射
- index file; 访问首页，直属于http、server、location，默认index index.html
- error_page code [code...] [= | =answer-code] uri | @named_location; 根据http返回码重定向页面，直属于http、server、location、if
- recursive_error_pages [on | off]; 是否允许递归使用error_page，直属于http、server、location，默认recursive_error_pages off;
- try_files path1 [path2...] uri; 如果所有path都找不到有效的文件，就重定向到最后的参数uri上，直属于server、location
内存及磁盘资源的分配
- client_body_in_file_only on | clean | off; http包体只存储到磁盘文件中，直属于http、server、location，默认client_body_in_file_only off;
  - 该配置一般用于调试、定位问题
- client_body_in_single_buffer on | off; http包体尽量写入到一个内存buffer中，直属于http、server、location，默认client_body_in_single_buffer off;
- client_body_buffer_size size; 存储http包体的内存buffer大小，直属于http、server、location，默认client_body_buffer_size 8k/16k;
- client_body_temp_path dir_path [level1 [level2[level 3]]]; http包体的临时存放目录，直属于http、server、location，默认client_body_temp_path client_body_temp;
  - [level1 [level2[level 3]]]是为了防止一个目录下的文件数量太多，按照临时文件名最多再加三层目录
- client_header_buffer_size size; 存储http头部的内存buffer大小，直属于http、server，默认client_header_buffer_size 1k;
- large_client_header_buffers number size; 存储超大http头部的内存buffer大小，直属于http、server，默认large_client_header_buffers 4 8k;
- connection_pool_size size; 指定tcp连接的内存池的初始大小，直属于http、server，默认connection_pool_size 256;
- request_pool_size size; 指定http请求的内存池的初始大小，直属于http、server，默认request_pool_size 4k;
网络连接的设置
- client_header_timeout time; 读取http头部的超时时间，直属于http、server、location，默认client_header_timeout 60;(默认单位：秒)
- client_body_timeout time; 读取http包体的超时时间，直属于http、server、location，默认client_body_timeout 60;(默认单位：秒)
- send_timeout time; 发送响应的超时时间，直属于http、server、location，默认send_timeout 60;(默认单位：秒)
- reset_timeout_connection on | off; 连接超时后将通过向客户端发送RST包来直接重置连接，直属于http、server、location，默认reset_timeout_connection off;
- lingering_close off | on | always; 控制nginx关闭用户连接的方式，直属于http、server、location，默认lingering_close on;
- lingering_time time; 控制nginx关闭用户连接的时间，直属于http、server、location，默认lingering_time 30s;
- lingering_timeout time; 控制nginx关闭用户连接的时间，直属于http、server、location，默认lingering_timeout 5s;
- keepalive_disable [msie6 | safari | none]; 对某些浏览器禁用keepalive功能，直属于http、server、location，默认keepalive_disable msie6 safari;
- keepalive_timeout time; keepalive超时时间，直属于http、server、location，默认keepalive_timeout 75;（默认单位：秒）
- keepalive_request n; 一个keepalive长连接上允许承载的请求最大数，直属于http、server、location，默认keepalive_request 100;（默认单位：秒）
- tcp_nodelay on | off; 确认对keepalive连接是否使用TCP_NODELAY选项，直属于http、server、location，默认tcp_nodelay on;
- tcp_nopush on | off; 在打开sendfile选项时，确定是否开启FreeBSD系统上的TCP_NOPUSH或Linux系统上的TCP_CORK功能，直属于http、server、location，默认tcp_nopush off;
MIME类型的设置
- type {...} MIME type与文件扩展的映射，直属于http、server、location
- default_type MIME-type; 默认MIME type，直属于http、server、location，默认default_type text/plain;
- types_hash_bucket_size size; 设置每个散列桶占用的内存大小，直属于http、server、location，默认types_hash_bucket_size 32|64|128;
- types_hash_max_size size; 散列表的冲突率，直属于http、server、location，默认types_hash_max_size 1024;
对客户端请求的限制
- limit_except method ... {...} 按http方法名限制用户请求，直属于http
- client_max_body_size size; http请求包体的最大值，直属于http、server、location，默认client_max_body_size 1m;
  - 用于限制Content-Length所示值的大小的，非常有用处
- limit_rate speed; 对请求的限速，直属于http、server、location、if，默认limit_rate 0;
- limit_rate_after time; nginx向客户端发送的响应长度超过limit_rate_after后才开始限速，直属于http、server、location、if，默认limit_rate_after 1m;
文件操作的优化
- sendfile on | off; sendfile系统调用，直属于http、server、location，默认sendfile系统调用
- aio on | off; AIO系统调用，直属于http、server、location，默认aio off;
  - 该配置与sendfile功能互斥
- directio size | off; 使用O_DIRECT选项去读取文件，缓冲区大小为size，直属于http、server、location，默认directio off;
  - 该配置通常对大文件的读取速度有优化作用
  - 该配置与sendfile功能互斥
- directio_alignment size; 指定以O_DIRECT选项去读取文件时的对其方式，直属于http、server、location，默认directio_alignment 512;
  - 该配置与directio配合使用
- open_file_cache max=N [inactive=time] | off; 打开文件缓存，直属于http、server、location，默认open_file_cache off;
  - max：表示在内存中存储元素的最大个数
  - inactive：表示在inactive指定的时间段内没有被访问过的元素将会被淘汰，默认时间为60秒
  - off：关闭缓存功能
- open_file_cache_errors on | off; 是否缓存打开文件错误的信息，直属于http、server、location，默认open_file_cache_errors off;
- open_file_cache_min_uses number; 不被淘汰的最小访问次数，直属于http、server、location，默认open_file_cache_min_uses 1;
- open_file_cache_valid time; 检验缓存中元素有效性的频率，直属于http、server、location，默认open_file_cache_valid 60s;
对客户端请求的特殊处理
- ignore_invalid_headers on | off; 忽略不合法的http头部，直属于http、server，默认ignore_invalid_headers on;
- underscores_in_headers on | off; http头部是否允许下画线，直属于http、server，默认underscores_in_headers off;
- If-Modified-Since [off | exact | before]; 对If-Modified-Since头部的处理策略，直属于http、server、location，默认If-Modified-Since exact;
- merge_slashes on | off; 是否合并相邻的"/"，直属于http、server、location，默认merge_slashes on;
- resolver address ...; 设置DNS名字解析服务器的地址
- resolver_timeout time; 设置DNS解析的超时时间，直属于http、server、location，默认resolver_timeout 30s;
- server_tokens on | off; 返回错误页面时是否在server中注明nginx版本，直属于http、server、location，默认server_tokens on;
ngx_http_core_module模块提供的变量
- $arg_PARAMETER：http请求中某个参数的值，如/index.html?size=100,可以用$arg_size取得100这个值
- $args：http请求中的完整参数。例如，在请求/index.html?_w=120&_h=120中，$args表示字符串_w=120&_h=120
- $binary_remote_addr：二进制格式的客户端地址。例如：\x0A\xE0B\x0E
- $body_bytes_sent：表示在向客户端发送的http响应中，包体部分的字节数
- $content_length：表示客户端请求头部中的Content-Length字段
- $content_type：表示客户端请求头部中的Content-Type字段
- $cookie_COOKIE：表示在客户端请求头部中的cookie字段
- $document_root：表示当前请求所使用的root配置项的值
- $uri：表示当前请求的URI，不带任何参数
- $document_uri：与$uri含义相同
- $request_uri：表示客户端发来的原始请求URI，带完整的参数
- $host：表示客户端请求头部中的Host字段
- $hostname：表示nginx所在机器的名称
- $http_HEADER：表示当前http请求中相应头部的值，HEADER名称全小写。例如，$http_host：表示请求头部对应的值
- $sent_http_HEADER：表示返回客户端的http响应中相应头部的值，HEADER名称全小写。例如，$sent_http_content_type表示响应中Content-Type头部对应的值
- $is_args：表示请求中的URI是否带参数，如果带参数，$is_args值为?,如果不带参数，则是空字符串
- $limit_rate：表示当前连接的限速是多少，0表示无限速
- $nginx_version：表示当前nginx的版本号
- $query_string：请求URI中的参数
- $remote_addr：表示客户端的地址
- $remote_port：表示客户端连接使用的端口
- $remote_user：表示使用Auth Basic Module时定义的用户名
- $request_filename：表示用户请求中的URI经过root或者alias转换后的文件路径
- $request_body：表示http请求中的包体，该参数只在proxy_pass或fastcgi_pass中有意义
- $request_body_file：表示http请求中的包体存储的临时文件名
- $request_completion：表示请求是否已经全部完成
- $request_method：表示http请求的方法名，如GET、PUT、POST等
- $scheme：表示http scheme,如在请求https://nginx.com/中表示https
- $server_addr：表示服务器地址
- $server_name：表示服务器名称
- $server_port：表示服务器端口
- $server_protocol：表示服务器向客户端发送响应的协议，如HTTP/1.1或者HTTP/1.0

反向代理服务器的配置项

负载均衡的基本配置
- upstream name {...} upstream块定义了一个上游服务器的集群，便于反向代理中的proxy_pass使用，直属于http
```
upstream backend {

    server backend1.example.com;

    server backend2.example.com;

    server backend3.example.com;

}

server {

    location / {

        proxy_pass http://backend;

    }

}
```
- server name [parameters]; 指定一台上有服务器的名字(域名、IP地址端口、UNIX句柄等)，直属于upstream
  - parameters可为weight=number：设置向这台上游服务器转发的权重，weigh和ip_hash配置不可同时使用，默认为1
  - parameters可为max_fails=number：向上游服务器转发失败最大次数，该选项与fail_timeout配合使用
  - parameters可为fail_timeout=time：该时间段内转发失败多少次后就认为上游服务器暂时不可用，用于优化反向代理功能。默认为10秒
  - down：表示所在的上游服务器永久下线，只在使用ip_hash配置项时才有用
  - backup：表示上游服务器是备份服务器，在使用ip_hash配置项时无效
```
upstream backend {

    server backend1.example.com weight=5;

    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;

    server unix:/tmp/backend3;

}
```
- ip_hash; 可确保同一个客户端的请求只会转发到指定的上游服务器中，直属于upstream
```
upstream backend {

    ip_hash;

    server backend1.example.com;

    server backend2.example.com;

    server backend3.example.com down;

    server backend4.example.com;

}
```
- 记录日志时支持的变量
  - $upstream_addr 处理请求的上游服务器地址
  - $upstream_cache_status 表示是否命中缓存，取值范围：MISS、EXPIRED、UPDATING、STALE、HIT
  - $upstream_status 上游服务器返回的响应中的HTTP响应码
  - $upstream_response_time 上游服务器的响应时间，精度到毫秒
  - $upstream_http_$HEADER HTTP的头部，如$upstream_http_host
```
    log_format timing '$remote_addr - $remote_user [$time_local] $request '

        'upstream_response_time $upstream_response_time'

        'msec $msec request_time $request_time';
```
```
    log_format up_head '$remote_addr - $remote_user [$time_local] $request '

        'upstream_http_content_type $upstream_http_content_type';
```
反向代理的基本配置
- proxy_pass URL; 将当前请求反向代理到URL参数指定的服务器上，URL可以是主机名、IP地址加端口的形式、Unix句柄，直属于location、if
- 默认情况下反向代理不会转发请求中的host头部的，如果需要转发，那么必须加上配置：proxy_set_header Host $host;
- proxy_method method; 转发时的协议方法名，直属于http、server、location，例如：proxy_method POST;
- proxy_hide_header the_header; 将上游服务器的响应转发给客户端，直属于http、server、location
- proxy_pass_header the_header; 将原来禁止转发的header设置为允许转发，直属于http、server、location
- proxy_pass_request_body on | off; 确定是否向上游服务器发送HTTP包体部分，直属于http、server、location，默认proxy_pass_request_body on;
- proxy_pass_request_headers on | off; 确定是否转发HTTP头部，直属于http、server、location，默认proxy_pass_request_headers on;
- proxy_redirect [default | off | redirect replacement] 当上游服务器返回的响应是重定向或刷新请求时，重设HTTP头部的location或者refresh字段，直属于http、server、location，默认proxy_redirect default;
- proxy_next_upstream [error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_404 | off]; 表示当向一台上游服务器转发请求出现错误时，继续换一台上游服务器处理这个请求，直属于http、server、location，默认proxy_next_upstream error timeout;

巴特西

Nginx模块开发与架构解析(nginx安装、配置说明)

nginx的配置

通用语法

基本配置

静态web服务器的配置项

反向代理服务器的配置项

最新文章

热门文章