Damian Lau

Nginx文档【持续更新】

Mon, 21 Aug 2023 00:00:00 +0800

简介
How-To
开发
模块参考

简介

安装Nginx
源码编译Nginx
新手指南
管理员指南
控制Nginx
连接处理方法
设置hash
调试日志
打印日志到syslog
配置文件中的计量单位
命令行参数
Nginx for Windows
支持QUIC和HTTP/3
Nginx 是如何处理一个请求的
虚拟主机名 Server names
使用Nginx作为HTTP负载均衡器
配置HTTPS 服务
Nginx 是如何处理TCP/UDP会话的
njs 脚本
《The Architecture of Open Source Applications》中的nginx章节

How-To

使用VC在Win32平台下编译Nginx
在Amazon EC2上配置Nginx Plus环境
使用DTrace调试Nginx
转换重写规则
WebSocket 代理

开发

贡献变更
开发者指南

模块参考

指令列表
变量列表
核心功能
ngx_http_core_module
ngx_http_access_module
ngx_http_addition_module
ngx_http_api_module
ngx_http_auth_basic_module
ngx_http_auth_jwt_module
ngx_http_auth_request_module
ngx_http_autoindex_module
ngx_http_browser_module
ngx_http_charset_module
ngx_http_dav_module
ngx_http_empty_gif_module
ngx_http_f4f_module
ngx_http_fastcgi_module
ngx_http_flv_module
ngx_http_geo_module
ngx_http_geoip_module
ngx_http_gunzip_module
ngx_http_gzip_module
ngx_http_gzip_static_module
ngx_http_headers_module
ngx_http_hls_module
ngx_http_image_filter_module
ngx_http_index_module
ngx_http_js_module
ngx_http_keyval_module
ngx_http_limit_conn_module
ngx_http_limit_req_module
ngx_http_log_module
ngx_http_map_module
ngx_http_memcached_module
ngx_http_mirror_module
ngx_http_mp4_module
ngx_http_perl_module
ngx_http_proxy_module
ngx_http_random_index_module
ngx_http_realip_module
ngx_http_referer_module
ngx_http_rewrite_module
ngx_http_scgi_module
ngx_http_secure_link_module
ngx_http_session_log_module
ngx_http_spdy_module
ngx_http_split_clients_module
ngx_http_ssi_module
ngx_http_ssl_module
ngx_http_status_module
ngx_http_stub_status_module
ngx_http_sub_module
ngx_http_upstream_module
ngx_http_upstream_conf_module
ngx_http_upstream_hc_module
ngx_http_userid_module
ngx_http_uwsgi_module
ngx_http_v2_module
ngx_http_v3_module
ngx_http_xslt_module
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
ngx_stream_core_module
ngx_stream_access_module
ngx_stream_geo_module
ngx_stream_geoip_module
ngx_stream_js_module
ngx_stream_keyval_module
ngx_stream_limit_conn_module
ngx_stream_log_module
ngx_stream_map_module
ngx_stream_proxy_module
ngx_stream_realip_module
ngx_stream_return_module
ngx_stream_split_clients_module
ngx_stream_ssl_module
ngx_stream_ssl_preread_module
ngx_stream_upstream_module
ngx_stream_upstream_hc_module
ngx_stream_zone_sync_module
ngx_google_perftools_module
ngx_otel_module

reference

updated at 2023.08.21

Nginx开发指南

Thu, 18 Feb 2021 00:00:00 +0800

简介
字符串 String
时间
容器类型
内存管理
日志
生命周期 Cycle
缓冲区 Buffer
网络
- 链接 Connection
事件驱动
进程
线程
模块
HTTP
例子
编程风格
- 通用规范
- 文件
- 注释
- 预处理器
- 类型
- 变量
- 函数
- 表达式
- 条件和循环
- 标签
调试内存问题
常见问题

简介

代码目录结构

auto - 构建脚本
src
- core - 基本数据结构类型和方法：字符串，数组，日志，pool等。
- event - 事件框架核心
  - modules - 事件通知模块：epoll，kqueue，select等。
- http - 核心http模块和通用代码
  - modules - 其他http模块
  - v2 - http2相关
- mail - mail相关模块
- os - 操作系统平台相关代码
  - unix
  - win32
- stream - stream模块

头文件

下面两个头文件必须包含在所有nginx文件的开头：

#include <ngx_config.h>
#include <ngx_core.h>

另外，http相关的代码应当包含如下头文件：

#include <ngx_http.h>

Mail相关的代码应当包含：

#include <ngx_mail.h>

Stream相关的代码应当包含：

#include <ngx_stream.h>

整数类型

为了更好的通用型目的，nginx代码提供两个整数类型：ngx_int_t和ngx_uint_t，这两个类型分别是intptr_t和uintptr_t的别名。

通用返回值

Nginx中大部分函数返回以下返回值：

NGX_OK：操作成功时返回。
NGX_ERROR：操作失败时返回。
NGX_AGAIN：操作未完成时返回，函数后续会再次别调用。
NGX_DECLINED：操作拒绝时返回，比如，配置中关闭了某个功能可以在功能处理函数中返回该值。注意，这不是一个错误。
NGX_BUSY：资源不可用时返回。
NGX_DONE：操作完成或在其他地方继续时返回。也用作表示成功的状态码。
NGX_ABORT：函数异常退出时返回，也用作表示失败的状态码。

错误处理

宏ngx_errno用于返回上一次的系统错误码。在POSIX系统平台它对应errno变量，在Windows系统它对应GetLastError()调用的返回值。

宏ngx_socket_errno用于返回上一次的socket错误码。和ngx_errno宏一样，在POSIX系统平台它对应errno变量，但在Windows系统它对应WSAGetLastError()调用的返回值。

多次访问ngx_errno和ngx_socket_errno宏的值可能带来性能问题。如果一个错误值可能被使用多次，请将它保存在ngx_err_t类型的本次变量中使用。

设置错误使用ngx_set_errno(errno)和ngx_set_socket_errno(errno)两个宏。

ngx_errno和ngx_socket_errno宏的值可以传递给打印日志的函数ngx_log_error()和ngx_log_debugX()，此时，系统错误文本会添加到日志中。

下面是使用ngx_errno的一个例子：

ngx_int_t
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;

    if (kill(pid, signo) == -1) {
        err = ngx_errno;

        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);

        if (err == NGX_ESRCH) {
            return 2;
        }

        return 1;
    }

    return 0;
}

字符串 String

简介

在Nginx中使用无符号字符指针 u_char*来表示C字符串。

Nginx的字符串类型ngx_str_t的定义如下：

typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;

其中，len保存了字符串的长度，data保存了字符串数据。

ngx_str_t保存的字符串末尾可能包含\0也可能不包含。大部分情况下是不包含\0结尾的。

但是在某些代码中（比如，解析配置的代码），ngx_str_t表示的字符串是以\0结尾的，这么做的目的是简化字符串比较和更易于向系统调用传递字符串。

Nginx中的字符串操作在src/core/ngx_string.h中定义，其中很多是对标准C函数的简单封装，如：

ngx_strcmp()
ngx_strncmp()
ngx_strstr()
ngx_strlen()
ngx_strchr()
ngx_memcmp()
ngx_memset()
ngx_memcpy()
ngx_memmove()

其他的字符串函数是Nginx特有的：

ngx_memzero() - 用0填充内存
ngx_explicit_memzero() - 和ngx_memzero()一样，但这个函数永远不会被编译器的dead-store-elimination优化所移除。该方法可用于清除敏感数据，如密码，私钥等。
ngx_cpymem() - 和ngx_memcpy()一样，但返回最终的目的地址，因此，可用于一次串联多个字符串。
ngx_movemem() - 和ngx_memmove()一样，但返回最终的目的地址。
ngx_strlchr - 字符串中查找某个字符，源字符串使用首尾地址界定。

以下方法用于字符串的大小写转化和比较：

ngx_tolower()
ngx_toupper()
ngx_strlow()
ngx_strcasecmp()
ngx_strncasecmp()

以下宏用于简化字符串初始化：

ngx_string(text) - 从C字符串常量text中初始化ngx_str_t类型字符串
ngx_null_string - 初始化一个ngx_str_t类型的空字符串
ngx_str_set(str, text) - 从C字符串常量text中初始化ngx_str_t类型字符串变量str
ngx_str_null(str) - 以空字符串初始化ngx_str_t类型字符串str

字符串格式化

以下格式化方式支持Nginx特有的类型：

ngx_sprintf(buf, fmt, …)
ngx_snprintf(buf, max, fmt, …)
ngx_slprintf(buf, last, fmt, …)
ngx_vslprintf(buf, last, fmt, args)
ngx_vsnprintf(buf, max, fmt, args)

这些格式化方法支持的格式化参数的完整列表在src/core/ngx_string.c文件中定义。

部分参数如下：

%O - off_t
%T - time_t
%z - ssize_t
%i - ngx_int_t
%p - void *
%V - ngx_str_t *
%s - u_char *
%*s - size_t + u_char * **

你可以在大部分类型前面前置u使其成为无符号类型。如果要转化成16进制输出，使用X或者x。

例如：

u_char      buf[NGX_INT_T_LEN];
size_t      len;
ngx_uint_t  n;

/* set n here */

len = ngx_sprintf(buf, "%ui", n) — buf;

数字转换

Nginx中实现了多种数字转换方法。

以下四个函数将给定长度的字符串转换为指定类型的正整数。错误返回NGX_ERROR。

ngx_atoi(line, n) - ngx_int_t
ngx_atosz(line, n) - ssize_t
ngx_atoof(line, n) - off_t
ngx_atotm(line, n) - time_t

下面两个数字转换函数，错误也返回NGX_ERROR。

ngx_atofp(line, n, point) - 字符串表示的浮点数转换为ngx_int_t类型正整数。结果会将小数点左移若干位，位数由point参数指定。比如，ngx_atofp(“10.5”, 4, 2)返回1050。
ngx_hextoi(line, n) - 将十六进制表示的正整数转换为ngx_int_t类型正整数。

正则表达式

时间

容器类型

数组 Array

链表 List

双向链表 Queue

红黑树 RB-Tree

哈希表 Hash

通配符匹配

内存管理

堆栈 Heap

池 Pool

共享内存

日志

生命周期 Cycle

缓冲区 Buffer

网络

链接 Connection

事件驱动

事件

I/O 事件

定时器事件

后处理事件

事件循环

进程

线程

模块

添加新模块

核心模块

配置指令

HTTP

链接 Connction

请求 Request

配置

处理阶段

变量

访问已存在的变量

创建新变量

复杂值

请求重定向

子请求

终止请求

请求体

响应

响应头

响应头过滤处理

响应体

响应体过滤处理

创建过滤模块

缓冲区复用

负载均衡

例子

编程风格

通用规范

文件

注释

预处理器

类型

变量

函数

表达式

条件和循环

调试内存问题

常见问题

写C模块

C字符串

全局变量

手动内存管理

线程

阻塞库

HTTP请求到外部服务

ngx_http_core_module模块

Thu, 15 Aug 2019 00:00:00 +0800

listen指令

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

address[:port]

设置监听地址和端口或者Unix Domain Socket的文件路径，用于服务器接收请求。可以同时设定地址和端口，也可以只设定地址或只设定端口。地址也可以是域名，比如：

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPV6地址在中括号中指定：

listen [::]:8000;
listen [::1];

指定Unix Doamin Socket以unix:开头：

listen unix:/var/run/nginx.sock;

如果只指定了地址，端口会默认使用80。如果没有配置listen指令，端口会使用80，如果80不可用则使用8000。

default_server

指定默认主机，如果不指定，第一个会作为默认主机。

ssl

指示所有经过该端口接收的请求应该以SSL模式工作。

http2

配置端口接收HTTP2连接。一般情况下，应该同时开启ssl选项，但Nginx也可以配置成不适用SSL接收HTTP2连接。

spdy

配置端口接收SPDY连接。一般情况下，应该同时开启ssl选项，但Nginx也可以配置成不适用SSL接收SPDY连接。

proxy_protocol

指示所有经过该端口接收的请求都适用PROXY协议。

socket相关选项

listen指令还提供了一些和socket系统调用相关的配置选项。这些配置选项可以再任何listen指令中指定，但每个address:port对只能指定一次。

setfib=number

当前仅FreeBSD有效。

fastopen=number

为监听的socket开启TCP Fast Open功能，并指定尚未完成三次握手的连接队列的最大长度。

backlog=number

指定listen()调用的backlog参数，以限制pending连接队列的最大长度。默认情况下，FreeBSD，DragonBSD和MacOS系统backlog设置为-1，其他平台设置为511。

rcvbuf/sndbuf=number

为监听socket设置接收缓冲区大小和发送缓冲区大小。

accept_filter=filter

仅FreeBSD和NetBSD 5.0+有效。

deferred

在Linux系统上指示使用deferred accept()（TCP_DEFER_ACCEPT的socket选项）。

bind

针对给定的address:port对单独执行bind()调用。如果存在不同的address但相同port的多个listen指令，并且有一个listen指令监听了指定端口的所有地址(:port)，此时nginx只会对:port执行bind()。值得注意的是，此时getsockname()系统调用可用于确定接收连接的address。如果给定的address:port对指定了setfib, backlog, rcvbuf, sndbuf, accept_filter, deferred, ipv6only 或 so_keepalive 参数，那么始终会单独执行bind()。

ipv6only=on|off

该参数（通过IPV6_V6ONLY socket选项）用于决定一个监听了通配符(::)地址的IPv6 socket是仅接收IPv6连接还是IPv6和IPv4连接都接收。该选项默认开启。仅在启动时设置一次。

reuseport

该参数指示为每个worker进程创建单独的监听socket，允许内核在worker进程间分配进入的连接。该参数当前仅在linux 3.9+，DragonFly BSD和FreeBSD 12+有效。

so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]

该参数用于为监听socket设定”TCP keepalive”行为。如果没有设置该选项，将应用操作系统设置。如果设置为”on”，socket将开启SO_KEEPALIVE选项。如果设置为”off”，会关闭SO_KEEPALIVE选项。有些操作系统支持为每个socket设定TCP keepalive参数，这些参数包括TCP_KEEPIDLE, TCP_KEEPINTVL和 TCP_KEEPCNT。在这些操作系统（如linux 2.4+）中可以使用keepidle, keepintvl和 keepcnt配置参数。可以不设置一个或两个参数，此时使用操作系统设置作为对应的参数设置。例如：

so_keepalive=30m::10

此时，会设置空闲超时时间（TCP_KEEPIDLE）30分钟，探测时间间隔（TCP_KEEPINTVL）则使用系统默认值，探测次数（TCP_KEEPCNT）设置为10次。

例子

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

Nginx listen

Nginx模块梳理

Fri, 26 Jul 2019 00:00:00 +0800

当前Nginx共提供111个模块，分类如下：

10个CORE模块

ngx_core_module
- 提供main conf下的指令，如deamon等
ngx_errlog_module
- 仅提供errlog指令
ngx_events_module
- 仅提供event指令块
ngx_http_module
- 仅提供http指令块
ngx_mail_module
- 仅提供mail指令块
ngx_stream_module
- 仅提供stream指令块
ngx_thread_pool_module
- 仅提供thread_pool指令
ngx_regex_module
- 仅提供pcre_jit指令
ngx_openssl_module
- 仅提供ssl_engine指令
ngx_google_perftools_module
- 仅提供google_perftools_profiles指令

1个CONF模块

ngx_conf_module
- 仅提供include指令

9个EVENT模块

ngx_event_core_module
ngx_epoll_module
ngx_select_module
ngx_kqueue_module
ngx_poll_module
ngx_devpoll_module
ngx_eventport_module
ngx_win32_poll_module
ngx_win32_select_module

65个HTTP模块

ngx_http_core_module
略

19个STREAM模块

ngx_stream_core_module
略

7个MAIL模块

ngx_mail_core_module
略

虚拟主机名称

Tue, 16 Jul 2019 00:00:00 +0800

正则表达式名字
其他类型的名字
优化

虚拟主机名使用server_name指令定义，用于决定由某台虚拟主机来处理请求。虚拟主机名可以使用确切的名字，通配符，或者是正则表达式来定义：

server {
    listen       80;
    server_name  example.org  www.example.org;
    ...
}

server {
    listen       80;
    server_name  *.example.org;
    ...
}

server {
    listen       80;
    server_name  mail.*;
    ...
}

server {
    listen       80;
    server_name  ~^(?<user>.+)\.example\.net$;
    ...
}

nginx以名字查找虚拟主机时，如果名字可以匹配多于一个主机名定义，比如同时匹配了通配符的名字和正则表达式的名字，那么nginx按照下面的优先级别进行查找，并选中第一个匹配的虚拟主机：

确切的名字；
最长的以星号起始的通配符名字：*.example.org；
最长的以星号结束的通配符名字：mail.*；
第一个匹配的正则表达式名字（按在配置文件中出现的顺序）。
通配符名字

通配符名字只可以在名字的起始处或结尾处包含一个星号，并且星号与其他字符之间用点分隔。所以，“www.*.example.org”和“w*.example.org”都是非法的。不过，上面的两个名字可以使用正则表达式描述，即“~^www..+.example.org$”和“~^w.*.example.org$”。星号可以匹配名字的多个节（各节都是以点号分隔的）。“*.example.org”不仅匹配www.example.org，也匹配www.sub.example.org。

有一种形如“.example.org”的特殊通配符，它可以既匹配确切的名字“example.org”，又可以匹配一般的通配符名字“*.example.org”。

正则表达式名字

nginx使用的正则表达式兼容PCRE。为了使用正则表达式，虚拟主机名必须以波浪线“~”起始：

server_name  ~^www\d+\.example\.net$;

否则该名字会被认为是个确切的名字，如果表达式含星号，则会被认为是个通配符名字（而且很可能是一个非法的通配符名字）。不要忘记设置“^”和“$”锚点，语法上它们不是必须的，但是逻辑上是的。同时需要注意的是，域名中的点“.”需要用反斜线“\”转义。含有“{”和“}”的正则表达式需要被引用，如：

server_name  "~^(?<name>\w\d{1,3}+)\.example\.net$";

否则nginx就不能启动，错误提示是：

directive "server_name" is not terminated by ";" in ...

命名的正则表达式捕获组在后面可以作为变量使用：

server {
    server_name   ~^(www\.)?(?<domain>.+)$;

    location / {
        root   /sites/$domain;
    }
}

PCRE使用下面语法支持命名捕获组：

?<name>    从PCRE-7.0开始支持，兼容Perl 5.10语法
?'name'    从PCRE-7.0开始支持，兼容Perl 5.10语法
?P<name>    从PCRE-4.0开始支持，兼容Python语法

如果nginx不能启动，并显示错误信息：

pcre_compile() failed: unrecognized character after (?< in ...

说明PCRE版本太旧，应该尝试使用?P。捕获组也可以以数字方式引用：

server {
    server_name   ~^(www\.)?(.+)$;

    location / {
        root   /sites/$2;
    }
}

不过，这种用法只限于简单的情况（比如上面的例子），因为数字引用很容易被覆盖。

其他类型的名字

有一些主机名会被特别对待。

如果需要用一个非默认的虚拟主机处理请求头中不含“Host”字段的请求，需要指定一个空名字：

server {
    listen       80;
    server_name  example.org  www.example.org  "";
    ...
}

如果server块中没有定义server_name，nginx使用空名字作为虚拟主机名。

nginx 0.8.48版本以下（含）在同样的情况下会使用机器名作为虚拟主机名。如果以“$hostname”（nginx 0.9.4及以上版本）定义虚拟主机名，机器名将被使用。

如果使用IP地址而不是主机名来请求服务器，那么请求头的“Host”字段包含的将是IP地址。可以将IP地址作为虚拟主机名来处理这种请求：

server {
    listen       80;
    server_name  nginx.org
                 www.nginx.org
                 ""
                 192.168.1.1
                 ;
    ...
}

在匹配所有的服务器的例子中，可以见到一个奇怪的名字“_”：

server {
    listen       80  default_server;
    server_name  _;
    return       444;
}

这没什么特别的，它只不过是成千上万的与真实的名字绝无冲突的非法域名中的一个而已。当然，也可以使用“–”和“!@#”等等。

nginx直到0.6.25版本还支持一个特殊的名字“*”，这个名字一直被错误地理解成是一个匹配所有的名字。但它从来没有像匹配所有的名字，或者通配符那样工作过，而是用来支持一种功能，此功能现在已经改由server_name_in_redirect指令提供支持了。所以，现在这个特殊的名字“*”已经过时了，应该使用server_name_in_redirect指令取代它。需要注意的是，使用server_name指令无法描述匹配所有的名字或者默认服务器。这是listen指令的属性，而不是server_name指令的属性。可以定义两个服务器都监听*:80和*:8080端口，然后指定一个作为端口*:8080的默认服务器，另一个作为端口*:80的默认服务器：

server {
    listen       80;
    listen       8080  default_server;
    server_name  example.net;
    ...
}

server {
    listen       80  default_server;
    listen       8080;
    server_name  example.org;
    ...
}

优化

确切名字和通配符名字存储在哈希表中。哈希表和监听端口关联。哈希表的尺寸在配置阶段进行了优化，可以以最小的CPU缓存命中失败来找到名字。设置哈希表的细节参见这篇文档。

nginx首先搜索确切名字的哈希表，如果没有找到，搜索以星号起始的通配符名字的哈希表，如果还是没有找到，继续搜索以星号结束的通配符名字的哈希表。

因为名字是按照域名的节来搜索的，所以搜索通配符名字的哈希表比搜索确切名字的哈希表慢。注意特殊的通配符名字“.example.org”存储在通配符名字的哈希表中，而不在确切名字的哈希表中。

正则表达式是一个一个串行的测试，所以是最慢的，而且不可扩展。

鉴于以上原因，请尽可能使用确切的名字。举个例子，如果使用example.org和www.example.org来访问服务器是最频繁的，那么将它们明确的定义出来就更为有效：

server {
    listen       80;
    server_name  example.org  www.example.org  *.example.org;
    ...
}

下面这种方法相比更简单，但是效率也更低：

server {
    listen       80;
    server_name  .example.org;
    ...
}

如果定义了大量名字，或者定义了非常长的名字，那可能需要在http配置块中使用server_names_hash_max_size和server_names_hash_bucket_size指令进行调整。server_names_hash_bucket_size的默认值可能是32，或者是64，或者是其他值，取决于CPU的缓存行的长度。如果这个值是32，那么定义“too.long.server.name.example.org”作为虚拟主机名就会失败，而nginx显示下面错误信息：

could not build the server_names_hash,
you should increase server_names_hash_bucket_size: 32

出现了这种情况，那就需要将指令的值扩大一倍：

http {
    server_names_hash_bucket_size  64;
    ...
}

如果定义了大量名字，得到了另外一个错误：

could not build the server_names_hash,
you should increase either server_names_hash_max_size: 512
or server_names_hash_bucket_size: 32

那么应该先尝试设置server_names_hash_max_size的值差不多等于名字列表的名字总量。如果还不能解决问题，或者服务器启动非常缓慢，再尝试提高server_names_hash_bucket_size的值。

如果只为一个监听端口配置了唯一的主机，那么nginx就完全不会测试虚拟主机名了（也不会为监听端口建立哈希表）。不过，有一个例外，如果定义的虚拟主机名是一个含有捕获组的正则表达式，这时nginx就不得不执行这个表达式以得到捕获组。

Nginx如何处理请求

Tue, 16 Jul 2019 00:00:00 +0800

基于名字的虚拟主机
如何防止处理未定义主机名的请求
基于域名和IP混合的虚拟主机
一个简单PHP站点配置

基于名字的虚拟主机

Nginx首先选定由哪一个虚拟主机来处理请求。让我们从一个简单的配置（其中全部3个虚拟主机都在端口*:80上监听）开始：

server {
    listen      80;
    server_name example.org www.example.org;
    ...
}

server {
    listen      80;
    server_name example.net www.example.net;
    ...
}

server {
    listen      80;
    server_name example.com www.example.com;
    ...
}

在这个配置中，nginx仅仅检查请求的Host头以决定该请求应由哪个虚拟主机来处理。如果Host头没有匹配任意一个虚拟主机，或者请求中根本没有包含Host头，那nginx会将请求分发到定义在此端口上的默认虚拟主机。在以上配置中，第一个被列出的虚拟主机即nginx的默认虚拟主机——这是nginx的默认行为。而且，可以显式地设置某个主机为默认虚拟主机，即在”listen”指令中设置”default_server”参数：

server {
    listen      80 default_server;
    server_name example.net www.example.net;
    ...
}

“default_server”参数从0.8.21版开始可用。在之前的版本中，应该使用”default”参数代替。请注意”default_server”是监听端口的属性，而不是主机名的属性。后面会对此有更多介绍。

如何防止处理未定义主机名的请求

如果不允许请求中缺少Host头，可以定义如下主机，丢弃这些请求：

server {
    listen       80;
    server_name  "";
    return       444;
}

在这里，我们设置主机名为空字符串以匹配未定义Host头的请求，而且返回了一个nginx特有的，非http标准的返回码444，它可以用来关闭连接。

从0.8.48版本开始，这已成为主机名的默认设置，所以可以省略server_name ““。而之前的版本使用机器的hostname作为主机名的默认值。

基于域名和IP混合的虚拟主机

下面让我们来看一个复杂点的配置，在这个配置里，有几个虚拟主机在不同的地址上监听：

server {
    listen      192.168.1.1:80;
    server_name example.org www.example.org;
    ...
}

server {
    listen      192.168.1.1:80;
    server_name example.net www.example.net;
    ...
}

server {
    listen      192.168.1.2:80;
    server_name example.com www.example.com;
    ...
}

这个配置中，nginx首先测试请求的IP地址和端口是否匹配某个server配置块中的listen指令配置。接着nginx继续测试请求的Host头是否匹配这个server块中的某个server_name的值。如果主机名没有找到，nginx将把这个请求交给默认虚拟主机处理。例如，一个从192.168.1.1:80端口收到的访问www.example.com的请求将被监听192.168.1.1:80端口的默认虚拟主机处理，本例中就是第一个服务器，因为这个端口上没有定义名为www.example.com的虚拟主机。

默认服务器是监听端口的属性，所以不同的监听端口可以设置不同的默认服务器：

server {
    listen      192.168.1.1:80;
    server_name example.org www.example.org;
    ...
}

server {
    listen      192.168.1.1:80 default_server;
    server_name example.net www.example.net;
    ...
}

server {
    listen      192.168.1.2:80 default_server;
    server_name example.com www.example.com;
    ...
}

一个简单PHP站点配置

现在我们来看在一个典型的，简单的PHP站点中，nginx怎样为一个请求选择location来处理：

server {
    listen      80;
    server_name example.org www.example.org;
    root        /data/www;

    location / {
        index   index.html index.php;
    }

    location ~* \.(gif|jpg|png)$ {
        expires 30d;
    }

    location ~ \.php$ {
        fastcgi_pass  localhost:9000;
        fastcgi_param SCRIPT_FILENAME
                      $document_root$fastcgi_script_name;
        include       fastcgi_params;
    }
}

首先，nginx使用前缀匹配找出最准确的location，这一步nginx会忽略location在配置文件出现的顺序。上面的配置中，唯一的前缀匹配location是”/”，而且因为它可以匹配任意的请求，所以被作为最后一个选择。接着，nginx继续按照配置中的顺序依次匹配正则表达式的location，匹配到第一个正则表达式后停止搜索，匹配到的location将被使用。如果没有匹配到正则表达式的location，则使用刚刚找到的最准确的前缀匹配的location。

请注意所有location匹配测试只使用请求的URI部分，而不使用参数部分。这是因为写参数的方法很多，比如：

/index.php?user=john&page=1
/index.php?page=1&user=john

除此以外，任何人在请求串中都可以随意添加字符串：

/index.php?page=1&something+else&user=john

现在让我们来看使用上面的配置，请求是怎样被处理的：

请求”/logo.gif”。首先匹配上location “/”，然后匹配上正则表达式”.(gif|jpg|png)$”。因此，它将被后者处理。根据”root /data/www”指令，nginx将请求映射到文件/data/www/logo.gif”，并发送这个文件到客户端。
请求”/index.php”。首先也匹配上location “/”，然后匹配上正则表达式”.(php)$“。因此，它将被后者处理，进而被发送到监听在localhost:9000的FastCGI服务器。 fastcgi_param指令将FastCGI的参数SCRIPT_FILENAME的值设置为”/data/www/index.php”，接着FastCGI服务器执行这个文件。变量$document_root等于root指令设置的值，变量$fastcgi_script_name的值是请求的uri，”/index.php”。
请求”/about.html”。仅能匹配上location “/”，因此，它将使用此location进行处理。根据”root /data/www”指令，nginx将请求映射到文件”/data/www/about.html”，并发送这个文件到客户端。
请求”/”的处理更为复杂。它仅能匹配上location “/”，因此，它将使用此location进行处理。然后，index指令使用它的参数和”root /data/www”指令所组成的文件路径来检测对应的文件是否存在。如果文件/data/www/index.html不存在，而/data/www/index.php存在，此指令将执行一次内部重定向到”/index.php”，接着nginx将重新寻找匹配”/index.php”的location，就好像这次请求是从客户端发过来一样。正如我们之前看到的那样，这个重定向的请求最终交给FastCGI服务器来处理。

调试日志

Tue, 16 Jul 2019 00:00:00 +0800

要开启调试日志，首先需要在配置nginx时打开调试功能，然后编译：

./configure --with-debug ...

然后在配置文件中设置error_log的级别为debug：

error_log  /path/to/log  debug;

nginx的windows二进制版本总是将调试日志开启的，因此只需要设置debug的日志级别即可。

注意，重新定义错误日志时，如过没有指定debug级别，调试日志会被屏蔽。

下面的例子里，在server层中重新定义的日志就屏蔽了这个虚拟主机的调试日志：

error_log  /path/to/log  debug;
http {
    server {
        error_log  /path/to/log;
        ...

为了避免这个问题，注释这行重新定义日志的配置，或者也给日志指定debug级别：

error_log  /path/to/log  debug;
http {
    server {
        error_log  /path/to/log  debug;
        ...

另外，也可以只针对选定的客户端地址开启调试日志：

error_log  /path/to/log;
events {
    debug_connection   192.168.1.1;
    debug_connection   192.168.10.0/24;
}

转换rewrite规则

Tue, 16 Jul 2019 00:00:00 +0800

重定向到主站

共享站点的管理员，习惯于只在Apache下使用.htaccess文件配置所有信息，通常会将下面规则

RewriteCond  %{HTTP_HOST}  example.org
RewriteRule  (.*)          http://www.example.org$1

翻译成nginx配置是这样：

server {
    listen       80;
    server_name  www.example.org  example.org;
    if ($http_host = example.org) {
        rewrite  (.*)  http://www.example.org$1;
    }
    ...
}

这种做法是错的，复杂而且低效。正确的方式是为example.org定义一个单独的服务器：

server {
    listen       80;
    server_name  example.org;
    return       301 http://www.example.org$request_uri;
}

server {
    listen       80;
    server_name  www.example.org;
    ...
}

在0.9.1版本（含）以前，可以这样实现重定向：

rewrite      ^ http://www.example.org$request_uri?;

再举一个例子，处理一个和刚才相反的逻辑：既不是来自example.com，又不是来自www.example.com：

RewriteCond  %{HTTP_HOST}  !example.com
RewriteCond  %{HTTP_HOST}  !www.example.com
RewriteRule  (.*)          http://www.example.com$1

应该按下面这样分开定义example.com、www.example.com和其他站点：

server {
    listen       80;
    server_name  example.com www.example.com;
    ...
}

server {
    listen       80 default_server;
    server_name  _;
    return       301 http://example.com$request_uri;
}

在0.9.1版本（含）以前，可以这样实现重定向：

rewrite      ^ http://example.com$request_uri?;

转化混合规则

典型的混合规则如下：

DocumentRoot /var/www/myapp.com/current/public

RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$ %{DOCUMENT_ROOT}/system/maintenance.html [L]

RewriteCond %{REQUEST_FILENAME} -f
RewriteRule ^(.*)$ $1 [QSA,L]

RewriteCond %{REQUEST_FILENAME}/index.html -f
RewriteRule ^(.*)$ $1/index.html [QSA,L]

RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^(.*)$ $1/index.html [QSA,L]

RewriteRule ^/(.*)$ balancer://mongrel_cluster%{REQUEST_URI} [P,QSA,L]

转换成nginx配置应该是这样：

location / {
    root       /var/www/myapp.com/current/public;

    try_files  /system/maintenance.html
               $uri  $uri/index.html $uri.html
               @mongrel;
}

location @mongrel {
    proxy_pass  http://mongrel;
}

源码安装Nginx

Tue, 16 Jul 2019 00:00:00 +0800

使用configure命令进行创建。它最后会创建makefile文件。configure命令支持如下参数：

–prefix=path - Nginx的安装根目录。

该路径用于configure命令和nginx.conf中配置的所有相对路径。默认路径为/usr/local/nginx。

–sbin-path=path - Nginx可执行文件名。

仅用于安装时，默认是prefix/sbin/nginx。

–conf-path=path - nginx.conf配置文件名。

-c选项可以用于指定nginx启动时的配置文件。默认是prefix/conf/nginx.conf。

–pid-path=path - nginx pid文件名。

安装完成后可以通过pid指令在nginx.conf中配置。默认为prefix/logs/nginx.pid。

–error-log-path=path - 错误、警告和诊断信息文件名。

安装完成后可以通过error_log指令在nginx.conf中配置。默认是prefix/logs/error.log。

–http-log-path=path - HTTP服务器的请求日志文件名。

安装完成后可以通过access_log指令在nginx.conf中配置。默认是prefix/logs/access.log。

–user=name - 设置未授权用户名。

工作进程会使用其证书。安装完成后可以通过user指令在nginx.conf中配置。默认是nobody。

–group=name - 设置组的名字。

具体用法同–user。默认也是nobody。

–with-select_module/–without-select_module - 使用select module处理事件驱动。

如果系统不支持其他方法如kqueue、epoll、rtsig、/dev/poll等，自动使用该选项。

–with-poll_module/–without-poll_module - 用法同select。
–without-http_gzip_module - 不安装http gzip module。

根据配置文件中指定的content-type压缩HTTP的响应包。需要zlib库的支持。

–without-http_rewrite_module - 不安装http rewrite module。

该模块提供HTTP请求在nginx服务内部的重定向功能，依赖PCRE库。

–without-http_proxy_module - 不安装http proxy module。

该模块提供基本的HTTP反向代理功能。

–with-http_ssl_module - 安装http ssl module。

该模块是nginx支持ssl协议，提供HTTPS服务，依赖OpenSSL库。

–with-pcre=path - 指定PCRE源码目录。

使用PCRE库解析配置文件中location的正则表达式。

–with-pcre-jit - 编译带jit的PCRE库。
–with-zlib=path - 指定zlib库的源码目录。

如果使用了gzip压缩功能，需要zlib库的支持。

–with-cc-opt=parameters - 设置额外参数到CFLAGS变量中。

例如，--with-cc-opt="-D FD_SETSIZE=2048"，--with-cc-opt="-I /usr/local/include"。

–with-ld-opt=parameters - 链接阶段设置额外参数。

例如，--with-ld-opt="-L /usr/local/lib"。

使用示例：

./configure
    --sbin-path=/usr/local/nginx/nginx
    --conf-path=/usr/local/nginx/nginx.conf
    --pid-path=/usr/local/nginx/nginx.pid
    --with-http_ssl_module
    --with-pcre=../pcre-4.4
    --with-zlib=../zlib-1.1.3

Love you always

Thu, 18 Oct 2018 00:00:00 +0800

“草在结它的种子风在摇它的叶子我们站着不说话就十分美好。” — 顾城

Damian Lau

Nginx文档【持续更新】

简介

How-To

开发

模块参考

Nginx开发指南

简介

代码目录结构

头文件

整数类型

通用返回值

错误处理

字符串 String

简介

字符串格式化

数字转换

正则表达式

时间

容器类型

数组 Array

链表 List

双向链表 Queue

红黑树 RB-Tree

哈希表 Hash

通配符匹配

内存管理

堆栈 Heap

池 Pool

共享内存

日志

生命周期 Cycle

缓冲区 Buffer

网络

链接 Connection

事件驱动

事件

I/O 事件

定时器事件

后处理事件

事件循环

进程

线程

模块

添加新模块

核心模块

配置指令

HTTP

链接 Connction

请求 Request

配置

处理阶段

变量

访问已存在的变量

创建新变量

复杂值

请求重定向

子请求

终止请求

请求体

响应

响应头

响应头过滤处理

响应体

响应体过滤处理

创建过滤模块

缓冲区复用

负载均衡

例子

编程风格

通用规范

文件

注释

预处理器

类型

变量

函数

表达式

条件和循环

标签