Master 进程#

master 进程是”管理者”，它不处理任何网络事件，不负责业务执行。它的核心职责是：

• 接收来自外界的信号：如 kill -HUP、kill -USR2、nginx -s reload 等；
• 向各 worker 进程发送信号：把外界的控制意图传递下去；
• 监控 worker 运行状态：当 worker 异常退出时，master 会自动重新启动一个新 worker，保证 worker 数量稳定。

控制 Nginx 只需通过 kill 向 master 发送信号即可——这就是为什么不需要停服就能 reload、滚日志、热升级。

经典的”从容重启”流程（kill -HUP <master_pid> 或 nginx -s reload）：

1. master 收到 HUP 信号后，重新加载配置文件；
2. master 启动新的 worker 进程（用新配置）；
3. master 向老 worker 发信号令其退出——但老 worker 不会立刻退出：
   • 老 worker 不再接受新的连接（不再 accept）；
   • 已经在处理的请求继续处理完毕；
   • 处理完所有请求后，老 worker 才真正退出。

整个过程中已建立的连接不中断、用户的请求不丢失，这就是 Nginx “zero downtime reload” 的原理。

Worker 进程#

worker 是真正干活的进程，主要功能包括：

• 接收客户端请求：通过 epoll/kqueue 拿到连接，读取字节流；
• 请求过滤处理：将请求依次送入各功能模块（11 个 phase）做过滤处理；
• 与后端服务器通信：通过 proxy_pass、fastcgi_pass 等把请求转发给后端，并接收后端处理结果；
• 数据缓存：通过 proxy_cache 模块把后端响应缓存到本地；
• 响应客户端：把响应数据写回 TCP 连接。

核心原则：一个请求完全由一个 worker 进程处理，且只在一个 worker 进程中处理。

这条原则意味着：请求从建立连接、读取 Header、解析、转发后端、接收响应、写回客户端，整个生命周期都在同一个 worker 里完成，不会在 worker 之间迁移。这样的好处是：① 没有 worker 之间的锁竞争；② 请求上下文可以放在 worker 私有的内存池里，不需要跨进程同步。

Worker 之间如何”公平”地接受连接？#

worker 进程之间是平等的，都由 master 进程 fork 而来。master 在 fork 之前就已经建立了需要 listen 的 socket（listenfd），所以 fork 之后所有 worker 都继承了同一个 listenfd。当新连接到来时，所有 worker 的 listenfd 都会变为”可读”。

如果所有 worker 都去 accept()，会出现”惊群”问题——多个 worker 被唤醒去抢同一个连接，最终只有一个成功，其他被白白唤醒。为避免这种情况，Nginx 让所有 worker 在注册 listenfd 读事件前抢占 accept_mutex 互斥锁：

• 抢到锁的 worker：注册 listenfd 读事件，在读事件中调用 accept() 接受连接。之后该 worker 完成读取请求、解析、处理、返回数据、断开连接的全流程；
• 没抢到锁的 worker：这次没机会接受新连接，等下一轮 epoll_wait 再尝试抢锁。

这种”惊群避免”机制使得：① 只有一个 worker 被唤醒处理新连接；② worker 之间负载天然均衡（每个 worker 抢锁的机会均等）。

现代 Nginx 在大多数 Linux 上默认 accept_mutex off 也能工作得很好（内核已不再向所有进程派发同一连接），但在某些场景下 accept_mutex on 仍能减少唤醒次数。可通过 events { accept_mutex on; } 显式开启。

连接内存池#

每个新连接都会分配一个连接内存池，初始大小由 connection_pool_size 控制。这个内存池是 Nginx 内存管理的核心——所有该连接相关的内存分配都从池里取，连接关闭时整池释放，避免了 malloc/free 的碎片开销。

注意 client_header_buffer_size 的”按块分配”特性：哪怕请求只有 100 字节，Nginx 也会从内存池中切出整块 1k。这种”宁多勿少”的策略是为了避免反复 realloc，也方便后续 Header 解析状态机连续推进。

回调设置#

HTTP 模块启动时调用 ngx_http_init_connection 完成回调方法的设置：

• 将新连接的读事件通过 epoll_ctl 加入 epoll 监听；
• 同时给该连接加一个超时定时器（默认 60s）。

如果客户端建了连接但在 60 秒内没发任何数据，定时器触发，Nginx 主动关闭连接，防止空连接占用资源。

请求内存池#

请求内存池和连接内存池是分开的：连接内存池用于 socket 层面的资源，请求内存池用于 HTTP 处理层面的资源。一条连接可以复用（HTTP keep-alive），但每个请求都有自己的请求内存池。

大 Header 缓冲：large_client_header_buffers#

正常情况下 1k 的 client_header_buffer_size 够用，但如果请求行特别长（比如超长 URL）或 Header 特别多（比如带大量 Cookie），1k 就不够了。这时启用大 Header 缓冲：

分配策略的关键点：Nginx 不是一次性分配 32k，而是按需渐进分配：

1. 先用 1k 的 client_header_buffer_size 解析请求行；
2. 不够 → 分配第一个 8k 大缓冲区，继续解析；
3. 还不够 → 分配第二个 8k；
4. 最多到 4 个 8k（32k）为止，超过就返回 414 Request-URI Too Large 或 400 Bad Request。

重要约束：请求行和 Header 共用这 4 个 8k 的配额——不是请求行单独 32k、Header 又有 32k。这意味着如果你有一个超长 URL，留给 Header 的空间就会变小。

为什么需要 realip？#

当 Nginx 前面有 CDN、负载均衡器或上层代理时，TCP 连接的对端是上层代理而不是终端用户，$remote_addr 取到的是代理的 IP，而不是用户真实 IP。这会导致两个问题：① 限流（limit_req/limit_conn）会针对代理 IP 而非用户 IP，等于把所有用户当成一个人；② 日志里看不到真实用户 IP，审计和风控失效。

realip 模块就是为了解决这个问题：从 HTTP Header 中取出真实 IP，改写 $remote_addr 变量，让后续所有阶段都拿到的是用户真实 IP。

两个相关 Header 字段#

• X-Forwarded-For：标准的”代理链”字段，格式为 client, proxy1, proxy2, ...，逗号分隔；每一跳代理会把自己的上一跳 IP 追加到末尾；
• X-Real-IP：Nginx 独有的字段，非 RFC 规范，只记录单一真实 IP。如果中间有非 Nginx 代理，可能取不到这个 Header。

指令#

1
set_real_ip_from 192.168.0.108;      # 信任的上游代理地址
2
real_ip_header X-Forwarded-For;      # 从哪个 Header 取真实 IP
3
real_ip_recursive on;                # 是否从尾部递归过滤可信地址

set_real_ip_from 指定哪些地址是可信的上游代理——只有可信代理发来的 Header 才会被采信，否则任意用户伪造一个 X-Forwarded-For: 1.1.1.1 就能骗过 Nginx。

real_ip_recursive 控制过滤策略：开启后从 X-Forwarded-For 的尾部开始，逐个剔除可信地址，剩下的最后一个就是真实 IP——这能正确处理多层代理链的场景。

关键变量#

$realip_remote_addr / $realip_remote_port 保存的是原始 TCP 连接的对端地址，即使 $remote_addr 被改写过，也能通过这俩变量拿到原始代理 IP，用于审计。

示例：

1
server {
2
    listen 80;
3
    server_name ziyang.realip.com;
4
    set_real_ip_from 192.168.0.108;
5
    real_ip_recursive off;
6
    real_ip_header X-Forwarded-For;
7
    location / {
8
        return 200 "Client real ip: $remote_addr\n";
9
    }
10
}

测试：

1
curl -H 'X-Forwarded-For: 1.1.1.1,192.168.0.108' ziyang.realip.com
2
# → Client real ip: 192.168.0.108

将 real_ip_recursive 改为 on 后：

1
curl -H 'X-Forwarded-For: 1.1.1.1,2.2.2.2,192.168.0.108' ziyang.realip.com
2
# → Client real ip: 2.2.2.2   （从尾部过滤掉可信的 192.168.0.108，取剩下的最后一个）

location 指令语法#

1
location [ = | ~ | ~* | ^~ ] uri { ... }
2
location @name { ... }

三类匹配规则#

1. 前缀字符串匹配：常规匹配（无修饰符）、=（精确匹配，URI 必须完全相等）、^~（匹配后不再走正则，优先于正则）；
2. 正则表达式匹配：~（大小写敏感）、~*（大小写不敏感），按配置文件中的出现顺序依次匹配；
3. 命名 location：@name，不参与外部匹配，仅用于内部跳转（如 error_page、try_files 跳转）。

匹配优先级流程（关键）#

Nginx 的 location 匹配顺序是反直觉的——不是”先匹配到先赢”，而是：

1. 先遍历所有前缀字符串，选出最长匹配的那一个；若该最长前缀带有 = 或 ^~ 修饰符，则直接使用并终止后续匹配；
2. 否则记住最长前缀 location（作为后备），按 nginx.conf 配置顺序依次匹配正则表达式；
3. 正则一旦命中即使用，不再继续往下匹配；
4. 所有正则都没命中，回退到第 2 步记住的最长前缀 location。

这个流程的关键点在于：① 前缀匹配选最长的，与配置顺序无关；② 正则匹配按配置顺序，先到先得；③ = 和 ^~ 能”截断”正则匹配流程。

实战配置#

1
server {
2
    listen 80;
3
    server_name location.ziyang.com;
4
    merge_slashes off;
5

6
    location ~ /Test1/$ {
7
        return 200 'first regular expressions match!\n';
8
    }
9
    location ~* /Test1/(\w+)$ {
10
        return 200 'longest regular expressions match!\n';
11
    }
12
    location ^~ /Test1/ {
13
        return 200 'stop regular expressions match!\n';
14
    }
15
    location /Test1/Test2 {
16
        return 200 'longest prefix string match!\n';
17
    }
18
    location /Test1 {
19
        return 200 'prefix string match!\n';
20
    }
21
    location = /Test1 {
22
        return 200 'exact match!\n';
23
    }
24
}

merge_slashes 默认 on，会把 URL 中连续的 / 合并成一个；改 off 可保留路径中的双斜杠语义。

5.4.1 return 指令#

1
return code [text];
2
return code URL;
3
return URL;

return 指令直接终止当前请求处理，返回指定状态码或重定向。可返回的状态码类型：

301 vs 308 / 302 vs 307 的区别：HTTP/1.0 时代的 301/302 允许浏览器把 POST 改成 GET 重发，这在表单提交场景会导致”重复提交”问题；HTTP/1.1 引入 307/308 强制保持原方法，更安全。现代配置推荐用 308/307 替代 301/302，避免方法被改写。

5.4.2 error_page 指令#

1
error_page 404 /404.html;
2
error_page 500 502 503 504 /50x.html;
3
error_page 404 =200 /empty.gif;      # 把 404 改写为 200 响应
4
error_page 404 = /404.php;
5
error_page 404 = @fallback;          # 跳到命名 location
6
error_page 403 http://example.com/forbidden.html;
7
error_page 404 =301 http://example.com/notfound.html;

关键结论：server 块的 error_page 与 location 块的 return 不会合并，谁先执行看阶段；location 里的 return 属于 REWRITE 阶段，会先于 ACCESS 等后续阶段生效。

5.4.3 rewrite 指令#

1
rewrite regex replacement [flag];

将 regex 匹配的 URL 替换为 replacement；replacement 以 http://、https:// 或 $schema 开头时直接返回 302。

flag 参数：

实战：

1
server {
2
    listen 80;
3
    server_name rewrite.ziyang.com;
4
    rewrite_log on;
5
    error_log logs/rewrite_error.log notice;
6

7
    location /first {
8
        rewrite /first(.*) /second$1 last;
9
        return 200 'first!\n';
10
    }
11
    location /second {
12
        rewrite /second(.*) /third$1;     # 无 flag
13
        return 200 'second!\n';
14
    }
15
    location /third {
16
        return 200 'third!\n';
17
    }
18
    location /redirect1 {
19
        rewrite /redirect1(.*) $1 permanent;   # → 301
20
    }
21
    location /redirect2 {
22
        rewrite /redirect2(.*) $1 redirect;    # → 302
23
    }
24
    location /redirect3 {
25
        rewrite /redirect3(.*) http://rewrite.ziyang.com$1;        # → 302
26
    }
27
    location /redirect4 {
28
        rewrite /redirect4(.*) http://rewrite.ziyang.com$1 permanent;  # → 301
29
    }
30
}

测试 curl rewrite.ziyang.com/first/3.txt：

• 默认（/second 中 rewrite 无 flag）→ 返回 second!；
• 给 /second 的 rewrite 加 break → 返回 test3（继续走完 break 后命中 /third）。

5.4.4 if 指令#

1
if (condition) { ... }

condition 支持的判断：

1. 变量为空或为 0；
2. = / != 字符串匹配；
3. ~ / !~（大小写敏感）、~* / !~*（大小写不敏感）正则匹配；
4. -f / !-f 文件存在；
5. -d / !-d 目录存在；
6. -e / !-e 文件/目录/软链接存在；
7. -x / !-x 可执行文件。

示例：

1
if ($http_user_agent ~ MSIE) {
2
    rewrite ^(.*)$ /msie/$1 break;
3
}
4
if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
5
    set $id $1;
6
}
7
if ($request_method = POST) {
8
    return 405;
9
}
10
if ($invalid_referer) {
11
    return 403;
12
}

5.4.5 rewrite_log#

1
rewrite_log on | off;

开启后 rewrite 日志写入 logs/rewrite_error.log，调试神器。

5.6.1 limit_conn 模块#

限制并发连接数。基于共享内存，对所有 worker 生效。它的有效性依赖于前置的 realip 模块——如果 realip 没启用，$binary_remote_addr 取到的是上层代理 IP，限流就成了针对代理 IP 的限流，所有用户被当成一个人。

limit_conn 适合防止”瞬时大量连接打爆后端”的场景，比如恶意爬虫并发开几十条连接拉取页面。

1
limit_conn_zone $binary_remote_addr zone=addr:10m;
2

3
server {
4
    location / {
5
        limit_conn_status 500;          # 超限返回码，默认 503
6
        limit_conn_log_level warn;      # 超限日志级别，默认 error
7
        limit_conn addr 1;              # 每 IP 并发连接上限 1
8
        limit_rate 50;                  # 每秒 50 字节
9
    }
10
}

5.6.2 limit_req 模块#

基于漏桶算法（Leaky Bucket）：想象一个固定容量的桶，请求像水一样倒入桶中，桶底以恒定速率漏出（被处理）；如果倒水速度超过漏水速度，多余的水会溢出（被拒绝）。漏桶算法的特点是输出速率恒定，不管输入多突发，后端收到的请求速率永远是匀速的。

这与”令牌桶”算法不同——令牌桶允许突发（桶里存了令牌就可以瞬间处理一批），漏桶不允许突发，只能匀速输出。

rate=2r/m 表示每分钟 2 个请求的漏水速率（即每 30 秒处理 1 个）。burst 参数控制桶的容量——超出速率的请求可以排队等待，最多排 burst 个；nodelay 让排队的请求立即处理而不是等待。

1
limit_req_zone $binary_remote_addr zone=one:10m rate=2r/m;

rate=2r/m 表示每分钟 2 个请求的速率。

1
location / {
2
    limit_req zone=one;                  # 严格按速率，超出立即 503
3
    limit_req zone=one burst=3;          # 允许 3 个排队等待
4
    limit_req zone=one burst=3 nodelay;  # 3 个立即处理，超出 503
5
}

三种行为的差异：

重要：limit_req 阶段在 limit_conn 之前执行，所以两个一起配时，req 优先级更高。

5.7.1 access 模块（IP 黑白名单）#

1
location / {
2
    deny 192.168.1.1;
3
    allow 192.168.1.0/24;
4
    allow 10.1.1.0/16;
5
    allow 2001:0db8::/32;
6
    deny all;
7
}

顺序执行，命中一条就停止。

5.7.2 auth_basic 模块（HTTP Basic 认证）#

基于 RFC2617 的 HTTP Basic Authentication 协议：浏览器弹框让用户输入用户名密码，浏览器把它们以 user:pass 形式 Base64 编码后放在 Authorization: Basic ... Header 里发给服务器。Nginx 解码后与本地密码文件比对，匹配则放行，不匹配返回 401 + WWW-Authenticate 头让浏览器再弹框。

注意 Base64 不是加密，等于明文传输，必须配合 HTTPS 使用，否则密码会被中间人嗅探。默认编译进 Nginx，可通过 --without-http_auth_basic_module 禁用。

1
location /auth_basic {
2
    satisfy any;
3
    auth_basic "test auth_basic";
4
    auth_basic_user_file example/auth.pass;
5
    deny all;
6
}

用 htpasswd 生成密码文件（依赖 httpd-tools）：

1
htpasswd -bc auth.pass ziyang 123456

文件格式：

1
name1:password1
2
name2:password2:comment

5.7.3 auth_request 模块（子请求鉴权）#

向上游服务转发请求做鉴权：Nginx 生成一个子请求发到指定的内部 location，该 location 通过 proxy_pass 转发到上游鉴权服务；上游返回 2xx 则原请求继续执行，返回 401/403 则把该状态响应给客户端。

这种模式的好处是：把鉴权逻辑完全交给后端服务实现，Nginx 只做”转发 + 判断状态码”，可以做复杂的权限校验（如 JWT 验证、API token 校验、多租户权限检查）。默认不编译，需 --with-http_auth_request_module。

1
location / {
2
    auth_request /test_auth;
3
}
4
location = /test_auth {
5
    internal;
6
    proxy_pass http://127.0.0.1:8090/auth_upstream;
7
    proxy_pass_request_body off;
8
    proxy_set_header Content-Length "";
9
    proxy_set_header X-Original-URI $request_uri;
10
}

5.7.4 satisfy 指令#

1
satisfy all | any;

• all：所有 ACCESS 阶段模块必须全部通过；
• any：任一通过即可。

对 access、auth_basic、auth_request 三个模块都生效。

几个关键认知：

1. return 属于 REWRITE 阶段，先于 ACCESS，因此 location 里写了 return 后 ACCESS 阶段不再执行；
2. 多个 ACCESS 模块的执行顺序由源码 ngx_module_names 数组决定，与配置文件中的指令顺序无关；
3. satisfy any + auth_basic + deny all：输对密码即可访问；
4. allow all 会使 auth_basic 没机会执行（access 模块先于 auth_basic）。

5.9.1 try_files 模块#

依次尝试一组文件，命中则返回，都不命中则跳到最后一个 URI（命名 location 或内部跳转）或返回指定 code。常用于：① 维护页面切换——把 /system/maintenance.html 放在第一位，维护时上传该文件即可一键切流；② 静态资源 fallback——先找 $uri，找不到再找 $uri/index.html、$uri.html，都不存在再返回 404 或转给后端。

1
location /first {
2
    try_files /system/maintenance.html
3
              $uri $uri/index.html $uri.html
4
              @lasturl;
5
}
6
location @lasturl {
7
    return 200 'lasturl!\n';
8
}
9
location /second {
10
    try_files $uri $uri/index.html $uri.html =404;
11
}

5.9.2 mirror 模块#

流量镜像：处理真实请求的同时，生成子请求复制到其他服务，对子请求返回值不做处理。常用于线上流量预演、新版本灰度验证。

1
location / {
2
    mirror /mirror;
3
    mirror_request_body off;
4
}
5
location = /mirror {
6
    internal;
7
    proxy_pass http://127.0.0.1:10020$request_uri;
8
    proxy_pass_request_body off;
9
    proxy_set_header Content-Length "";
10
    proxy_set_header X-Original-URI $request_uri;
11
}

5.10.1 static 模块：root 与 alias#

1
alias path;          # location 后的 URI 映射到 path
2
root  path;          # 完整 URI 映射到 path

两者的差别：root 把完整 URL 拼到 path 后；alias 只把 location 之后的 URL 拼到 path 后。这是 Nginx 配置最容易踩的坑之一：

• root 是”在 path 末尾追加完整 URI”——location /root { root html; } 访问 /root/1.txt 会去找 html/root/1.txt；
• alias 是”把 location 部分替换成 path”——location /alias { alias html; } 访问 /alias/1.txt 会去找 html/1.txt（/alias 被替换成 html）。

经验法则：location 与文件路径有”前缀替换”关系时用 alias；location 就是文件路径的一部分时用 root。正则 location 里几乎总是用 alias，因为正则匹配的 URI 需要被替换掉。

1
location /root {
2
    root html;       # /root/1.txt → html/root/1.txt（不存在）
3
}
4
location /alias {
5
    alias html;      # /alias/1.txt → html/1.txt（存在）
6
}
7
location ~ /root/(\w+\.txt) {
8
    root html/first/$1;     # /root/1.txt → html/first/1.txt/root/1.txt（不存在）
9
}
10
location ~ /alias/(\w+\.txt) {
11
    alias html/first/$1;    # /alias/1.txt → html/first/1.txt（存在）
12
}

5.10.2 三个相关变量#

5.10.3 目录重定向相关#

访问目录不带 / 时，static 模块返回 301 加 /：

1
server_name_in_redirect on;     # 用 server_name 拼跳转地址
2
port_in_redirect on;            # 拼端口
3
absolute_redirect on;           # 拼成绝对 URL

5.10.4 index 与 autoindex#

1
index index.html;
2
autoindex on;                   # index 不存在时列出目录
3
autoindex_exact_size on;        # 显示精确字节数
4
autoindex_format html;          # html / xml / json / jsonp
5
autoindex_localtime on;         # 用本地时间

index 模块先于 autoindex 执行：index 文件存在 → 显示文件；不存在 → 走 autoindex 列目录。

5.10.5 concat 模块（Tengine）#

阿里巴巴开发，合并多个小文件请求，减少 HTTP 请求数。需 --add-module=../nginx-http-concat/ 编译。

1
server {
2
    concat on;
3
    concat_max_files 20;
4
    concat_types text/plain;
5
    concat_unique on;
6
    concat_delimiter ':::';
7
    concat_ignore_file_error on;
8
}

请求形如 /??a.js,b.js?ver=1 可一次拉回合并后的内容。

默认 combined 格式#

1
log_format combined '$remote_addr - $remote_user [$time_local] '
2
                    '"$request" $status $body_bytes_sent '
3
                    '"$http_referer" "$http_user_agent"';

access_log 配置#

1
access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]];
2
access_log off;

特性：

• path 可含变量，但每条日志都需打开/关闭文件，性能差；
• if 通过变量值控制是否记录；
• 日志缓存：批量写盘，触发条件为缓存满、flush 到期、worker reopen 或关闭；
• 日志压缩：buffer 默认 64KB，gzip 级别默认 1（1 最快压缩率最低，9 最慢压缩率最高），开启压缩自动启用缓存。

含变量日志路径的优化#

1
open_log_file_cache max=1000 inactive=20s min_uses=2 valid=1m;

• max：缓存最大文件句柄数，超出 LRU 淘汰；
• inactive：多久未访问则关闭，默认 10s；
• min_uses：inactive 内使用次数达到此值才留在内存；
• valid：多久校验文件是否还存在，默认 60s。

依赖#

1
yum install -y pcre pcre-devel openssl openssl-devel patch \
2
               libxml2 libxml2-dev libxslt-devel gd gd-devel \
3
               perl-devel perl-ExtUtils-Embed gperftools

拉源码与打补丁#

1
git clone https://github.com/yaoweibin/nginx_upstream_check_module.git
2
wget http://nginx.org/download/nginx-1.7.5.tar.gz
3
tar zxf nginx-1.7.5.tar.gz
4
cd nginx-1.7.5
5

6
# 选与 Nginx 版本匹配的补丁
7
patch -p1 < ../nginx_upstream_check_module/check_1.7.5+.patch

编译#

1
./configure --prefix=/usr/local/nginx \
2
            --add-module=/path/to/nginx_upstream_check_module \
3
            --with-http_ssl_module \
4
            --with-http_gzip_static_module \
5
            --with-http_stub_status_module
6
make
7
make install        # 全新安装
8
# 已安装过：仅替换二进制
9
cp /usr/local/nginx/sbin/nginx{,.bak}
10
cp objs/nginx /usr/local/nginx/sbin/nginx

check 指令参数表#

支持的协议类型#

不同后端服务用不同的应用层协议，健康检查也要”说同一种语言”。upstream_check_module 支持 5 种协议探测：