Nginx on 纪伟的个人博客

Nginx 学习笔记（四）：深入原理

Mon, 08 Jun 2026 10:00:00 +0800

写在前面

本文是 Nginx 学习笔记系列的最后一篇，深入 Nginx 的底层实现：Master/Worker 进程模型、事件驱动机制、请求处理的 11 个阶段、内存管理，以及 Nginx 为什么这么快。最后对比 Nginx、OpenResty 和 Envoy。

一、Master/Worker 进程模型

1.1 进程架构

Nginx 启动后的进程结构：

  PID  PPID COMMAND
  1001  1   nginx: master process       ← Master 进程（以 root 运行）
  1002 1001 nginx: worker process       ← Worker 进程（以 www-data 运行）
  1003 1001 nginx: worker process
  1004 1001 nginx: worker process
  1005 1001 nginx: worker process       ← 4 个 Worker = 4 核 CPU
  1006 1001 nginx: cache manager process ← 缓存管理
  1007 1001 nginx: cache loader process  ← 缓存加载

进程分工：

  Master 进程：
    - 读取和验证配置文件
    - 创建、绑定、监听 Socket
    - 管理 Worker 进程（fork、监控、重启）
    - 处理信号（reload、reopen、stop）
    - 不处理任何业务请求

  Worker 进程：
    - 接收和处理客户端请求
    - 每个 Worker 独立、互不干扰
    - 一个 Worker 崩溃不影响其他 Worker
    - Worker 之间通过共享内存通信

  Cache Manager：
    - 管理磁盘缓存
    - 检查缓存有效期，删除过期缓存

  Cache Loader：
    - Nginx 启动时加载磁盘缓存到内存索引
    - 加载完成后退出

1.2 为什么不用多线程

多进程 vs 多线程：

  Nginx 选择多进程：
    ✓ Worker 崩溃不影响其他 Worker（隔离性好）
    ✓ 无锁设计，无死锁风险
    ✓ 配合 epoll 事件驱动，单进程处理万级并发
    ✓ 方便利用多核（每个 Worker 绑定一个 CPU 核心）

  多线程的问题：
    ✗ 线程间共享内存，需要大量锁
    ✗ 锁竞争导致性能下降
    ✗ 一个线程崩溃可能导致整个进程崩溃
    ✗ 调试困难

  实际上 Nginx 的 Worker 内部也有辅助线程（file aio），
  但核心请求处理是单线程事件驱动。

1.3 进程管理

# 查看 Nginx 进程
ps aux | grep nginx

# Worker 数量配置
# nginx.conf
worker_processes auto;                # 自动 = CPU 核心数
# 或手动指定
worker_processes 4;

# 绑定 Worker 到 CPU 核心（减少 CPU 切换开销）
worker_cpu_affinity auto;

# Worker 进程优先级
worker_priority -5;                   # 值越小优先级越高（-20 到 19）

# Worker 最大打开文件数
worker_rlimit_nofile 65535;

Master 处理信号：

  TERM, INT    → 优雅停止
  QUIT         → 优雅停止（等请求处理完）
  HUP          → 重新加载配置
  USR1         → 重新打开日志文件
  USR2         → 升级可执行文件（热升级）
  WINCH        → 优雅停止 Worker

reload 时发生了什么：
  1. Master 收到 HUP 信号
  2. 重新读取配置文件
  3. 如果配置合法，fork 新的 Worker 进程
  4. 向旧 Worker 发送 QUIT 信号
  5. 旧 Worker 处理完当前请求后退出
  6. 全程无中断（零停机 reload）

二、事件驱动机制（epoll）

2.1 为什么需要事件驱动

传统方式（多进程/线程模型）：
  每个连接分配一个线程
  连接空闲时，线程阻塞在 read() 上
  1万个连接 = 1万个线程

  问题：
    ✗ 线程占用内存（每个线程约 8MB 栈空间）
    ✗ 线程切换开销大（上下文切换、CPU 缓存失效）
    ✗ 难以扩展到 C10K（万级并发）

事件驱动模型：
  一个线程管理所有连接
  只在连接有事件（可读/可写）时才处理
  空闲连接不消耗 CPU

  优势：
    ✓ 少量线程即可处理万级并发
    ✓ 空闲连接零开销
    ✓ CPU 只在做有用的工作

2.2 I/O 多路复用技术

Linux I/O 多路复用的演进：

1. select
   - 最多监听 1024 个文件描述符（FD）
   - 每次调用需要传入所有 FD，内核遍历全部
   - O(n) 复杂度，性能差

2. poll
   - 没有连接数限制
   - 仍然需要传入所有 FD，内核遍历全部
   - O(n) 复杂度

3. epoll（Linux 2.6+）
   - 没有连接数限制
   - 只返回就绪的 FD，不需要遍历全部
   - O(1) 复杂度，性能极好
   - Nginx 在 Linux 上的默认选择

4. kqueue（FreeBSD / macOS）
   - 类似 epoll，性能优秀
   - Nginx 在 macOS 上的默认选择

2.3 epoll 工作原理

epoll 的三个系统调用：

1. epoll_create()
   创建 epoll 实例（红黑树 + 就绪链表）

2. epoll_ctl()
   注册/修改/删除要监听的 FD
   内核会为每个 FD 注册回调

3. epoll_wait()
   阻塞等待就绪事件
   只返回有事件的 FD（不需要遍历全部）

工作流程：
  ┌─────────────┐
  │  epoll 实例   │
  │ ┌───────────┐ │
  │ │ 红黑树     │ │  ← 存储所有注册的 FD
  │ │ (FD 集合)  │ │
  │ └───────────┘ │
  │ ┌───────────┐ │
  │ │ 就绪链表   │ │  ← 有事件的 FD（由内核回调自动添加）
  │ │ (活跃 FD)  │ │
  │ └───────────┘ │
  └─────────────┘

  网络数据到达 → 网卡中断 → 内核回调 → FD 加入就绪链表
  epoll_wait() 返回就绪链表 → Nginx 处理活跃连接

  关键优势：
    不需要遍历所有连接，只处理有事件的
    1万个连接中可能只有 100 个活跃 → 只处理 100 个

2.4 Nginx 的事件模型

# nginx.conf events 块
events {
    # 使用 epoll（Linux 默认）
    use epoll;

    # 每个 Worker 的最大连接数
    worker_connections 65535;

    # 尽可能多地接收连接
    multi_accept on;

    # 禁用 accept 互斥锁（Worker 数少时）
    accept_mutex off;
}

Nginx Worker 的事件循环（简化版）：

  while (true) {
      events = epoll_wait(epoll_fd, ...);     // 等待事件

      for (event in events) {
          if (event 是新连接) {
              accept 新连接;
              将新连接注册到 epoll;
          }
          else if (event 可读) {
              读取请求数据;
              处理请求;
              生成响应;
          }
          else if (event 可写) {
              发送响应数据;
          }
      }
  }

  注意：
    - 事件循环中不执行阻塞操作
    - 文件 I/O 用线程池（file aio）
    - DNS 解析有缓存，避免阻塞

2.5 连接处理流程

一个 HTTP 请求的完整生命周期：

  1. 客户端发起 TCP 连接
     → 三次握手完成，epoll 通知有新连接

  2. Worker accept 连接
     → 创建 connection 对象
     → 注册到 epoll 监听读事件

  3. 客户端发送 HTTP 请求
     → epoll 通知可读事件
     → Worker 读取请求数据
     → 解析 HTTP 请求行、头部、请求体

  4. 处理请求
     → 匹配 location
     → 执行 rewrite、access、content 等阶段
     → 生成响应

  5. 发送响应
     → 注册可写事件到 epoll
     → epoll 通知可写时发送数据

  6. keepalive 复用或关闭连接
     → keepalive：连接保持，等待下一个请求
     → 超时或 Connection: close：关闭连接

  整个过程：一个 Worker 线程处理，不创建新线程

三、请求处理完整流程（11 个阶段）

3.1 HTTP 请求处理管道

Nginx 把 HTTP 请求处理分为 11 个阶段，模块按阶段执行：

  ┌─────────────────────────────────────────┐
  │          HTTP Request                    │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  1. POST_READ        读取请求后          │  ngx_http_realip_module
  │     （获取真实 IP）                      │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  2. SERVER_REWRITE    server 级重写       │  ngx_http_rewrite_module
  │     （server 块中的 rewrite）             │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  3. FIND_CONFIG       查找配置           │  Nginx 核心
  │     （匹配 location）                    │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  4. REWRITE           location 级重写     │  ngx_http_rewrite_module
  │     （location 块中的 rewrite）           │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  5. POST_REWRITE      重写后处理         │  Nginx 核心
  │     （检查是否需要重新匹配 location）      │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  6. PREACCESS         访问前检查         │  ngx_http_limit_conn_module
  │     （限流、连接数限制）                   │  ngx_http_limit_req_module
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  7. ACCESS            访问控制           │  ngx_http_access_module
  │     （IP 黑白名单、认证）                 │  ngx_http_auth_basic_module
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  8. POST_ACCESS       访问后处理         │  Nginx 核心
  │     （satisfy 配合 access 阶段）          │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  9. PRECONTENT        内容前处理         │  ngx_http_try_files_module
  │     （try_files）                        │
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  10. CONTENT          生成内容           │  ngx_http_proxy_module
  │      （代理、静态文件、FastCGI）           │  ngx_http_static_module
  └──────────────┬──────────────────────────┘
                 ▼
  ┌─────────────────────────────────────────┐
  │  11. LOG              记录日志           │  ngx_http_log_module
  │      （access_log）                      │
  └─────────────────────────────────────────┘

3.2 各阶段详解

# 以下配置展示了各阶段对应的指令

server {
    listen 80;
    server_name example.com;

    # 阶段 1: POST_READ — 获取真实 IP
    set_real_ip_from 10.0.0.0/8;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    # 阶段 2: SERVER_REWRITE — server 级重写
    rewrite ^/old-api/(.*)$ /api/$1 last;

    location /api/ {
        # 阶段 4: REWRITE — location 级重写
        rewrite ^/api/v1/(.*)$ /api/v2/$1 break;

        # 阶段 6: PREACCESS — 限流
        limit_req zone=api_limit burst=50 nodelay;
        limit_conn conn_limit 20;

        # 阶段 7: ACCESS — 访问控制
        allow 10.0.0.0/8;
        allow 192.168.0.0/16;
        deny all;
        auth_basic "Restricted";
        auth_basic_user_file /etc/nginx/.htpasswd;

        # 阶段 9: PRECONTENT — try_files
        try_files $uri $uri/ @proxy;

        # 阶段 10: CONTENT — 生成内容
        proxy_pass http://backend;
    }

    location @proxy {
        proxy_pass http://backend;
    }

    # 阶段 11: LOG — 日志
    access_log /var/log/nginx/example.com.access.log detailed;
}

3.3 阶段执行的特点

1. 顺序执行
   请求按阶段 1→2→3→...→11 顺序经过各阶段

2. 模块注册
   每个模块可以注册到特定阶段
   同一阶段可以有多个模块，按配置顺序执行

3. 阶段跳转
   rewrite 的 last 会跳回阶段 3（FIND_CONFIG）
   rewrite 的 break 跳过后续 rewrite，进入下一阶段
   return 直接跳到阶段 11（LOG）

4. 内容阶段只有一个执行
   proxy_pass、fastcgi_pass、root/alias 只能选一个
   先匹配到的执行

5. 日志阶段总是执行
   无论前面的阶段返回什么状态码，日志阶段都会执行

四、内存管理

4.1 Nginx 的内存管理策略

为什么不直接用 malloc/free：

  问题：
    ✗ 频繁的 malloc/free 导致内存碎片
    ✗ 每次分配有系统调用开销
    ✗ 容易忘记 free 导致内存泄漏
    ✗ 多线程环境下需要锁

  Nginx 的方案：
    ✓ 内存池（pool）— 批量分配，一次性释放
    ✓ 共享内存 — Worker 间通信
    ✓ slab 分配器 — 管理共享内存中的固定大小对象

4.2 内存池（ngx_pool_t）

内存池结构：

  ngx_pool_t
  ├── d: last, end, next, failed     ← 数据区链表
  ├── max: 最大可分配大小
  ├── current: 当前工作的小块内存池
  ├── chain: 缓冲区链表
  ├── large: 大块内存链表
  ├── cleanup: 清理回调链表
  └── hostnet: 子内存池

  ┌──────────────────────────────┐
  │          pool                 │ ← 一次 malloc 分配一整块（如 4KB）
  │  ┌────────────────────────┐  │
  │  │  已使用  │    空闲       │  │ ← last 指针标记空闲起始位置
  │  └────────────────────────┘  │
  │          next pool            │ ← 空间不够时，再 malloc 一块链上
  │  ┌────────────────────────┐  │
  │  │        空闲             │  │
  │  └────────────────────────┘  │
  └──────────────────────────────┘

  小块分配（≤ max，通常 ≤ 4096 字节）：
    从当前 pool 的空闲区域直接切出
    移动 last 指针即可，极快
    不需要 free，整个 pool 一起释放

  大块分配（> max）：
    直接 malloc 分配
    加入 large 链表管理
    pool 销毁时一起释放

内存池的分配和释放：

  创建：
    pool = ngx_create_pool(4096, log)     // 分配 4KB 内存池

  小块分配：
    p = ngx_palloc(pool, 128)             // 从池中切 128B，极快
    p = ngx_pnalloc(pool, 256)            // 同上，不要求对齐

  大块分配：
    p = ngx_palloc(pool, 8192)            // > max，直接 malloc

  使用完毕：
    ngx_destroy_pool(pool)                // 一次性释放所有内存

  重置（复用）：
    ngx_reset_pool(pool)                  // 重置 last 指针，不释放内存

优势：
  ✓ 小块分配只需要移动指针，O(1) 复杂度
  ✓ 没有内存碎片（同一 pool 中连续分配）
  ✓ 不需要逐个 free，一键销毁
  ✓ 每个请求一个 pool，请求结束销毁，不会泄漏

4.3 请求与内存池的生命周期

一个 HTTP 请求的内存管理：

  请求开始
    → 创建请求级内存池（request pool）

  请求处理过程中
    → 解析请求行 → palloc 分配
    → 解析请求头 → palloc 分配
    → 读取请求体 → palloc 分配
    → 生成响应   → palloc 分配
    → 所有分配都从池中获取，不需要 free

  请求结束
    → 销毁请求级内存池
    → 所有内存一次性释放
    → 不会泄漏任何字节

  对比传统方式：
    传统：malloc/free 配对，容易漏 free
    Nginx：只管分配，不管释放，请求结束统一释放

4.4 共享内存

Worker 进程之间需要共享数据（如限流的计数器）：

  Nginx 共享内存：

    ngx_shm_zone_t
    ├── shm_zone: 共享内存区域名称
    ├── shm_size: 共享内存大小
    ├── data:     自定义数据
    └── init:     初始化回调

  使用场景：
    limit_req_zone  — 限流计数器
    limit_conn_zone — 连接数计数器
    ssl_session_cache — SSL 会话缓存
    proxy_cache     — 代理缓存
    upstream        — 负载均衡状态

  配置示例：
    limit_req_zone $binary_remote_addr zone=api:10m rate=100r/s;
    #                     ↑ IP              ↑ 名称 ↑ 10MB 共享内存

4.5 slab 分配器

共享内存中使用 slab 分配器管理固定大小的对象：

  slab 分配器结构：
    ┌─────────────────────────────────────────────┐
    │              共享内存（如 10MB）               │
    │  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
    │  │ Page 0  │ │ Page 1  │ │ Page 2  │ ...   │
    │  └─────────┘ └─────────┘ └─────────┘       │
    │  每个 Page 4KB                               │
    │                                              │
    │  Page 内部按 slot 大小分割：                   │
    │  slot 大小：8, 16, 32, 64, 128, 256, ...     │
    │                                              │
    │  如 slot_size = 64：                          │
    │  ┌───┬───┬───┬───┬───┬───┬───┬───┐         │
    │  │64B│64B│64B│64B│64B│64B│64B│64B│  ← 8个slot│
    │  └───┴───┴───┴───┴───┴───┴───┴───┘         │
    └─────────────────────────────────────────────┘

  工作方式：
    分配：根据对象大小选择合适的 slot，从 page 中分配一个 slot
    释放：标记 slot 为空闲，可以复用
    无碎片：固定大小分配，不会产生碎片

  应用场景：
    限流：每个 IP 的计数器是固定大小（如 64B），用 slab 分配
    SSL 缓存：每个会话条目大小固定
    负载均衡：upstream 的状态信息

五、为什么 Nginx 这么快

5.1 性能数据

典型性能基准：

  静态文件服务：
    简单 HTML：50,000+ req/s（单机）
    小文件（<10KB）：30,000+ req/s

  反向代理：
    简单代理：20,000+ req/s
    带 SSL：10,000+ req/s

  对比 Apache（prefork 模式）：
    同等硬件：Nginx 快 2-10 倍
    内存占用：Nginx 低 5-20 倍

5.2 快的原因总结

1. 事件驱动 + epoll
   单线程处理万级并发
   只处理活跃连接，空闲连接零开销
   epoll O(1) 复杂度，不随连接数增长而变慢

2. 零拷贝（sendfile）
   静态文件不需要经过用户空间
   内核直接从文件描述符拷贝到 Socket
   减少两次内存拷贝和上下文切换

   传统方式：
     磁盘 → 内核缓冲区 → 用户空间 → Socket 缓冲区 → 网卡
   sendfile：
     猖盘 → 内核缓冲区 → 网卡（直接 DMA 传输）

3. 内存池
   批量分配，一次性释放
   小块内存分配只需移动指针（O(1)）
   无内存碎片，无泄漏

4. 无锁设计
   Worker 进程独立，互不干扰
   不需要互斥锁，无锁竞争
   共享内存用原子操作和 slab 分配器

5. 高效的 I/O 处理
   sendfile 零拷贝
   tcp_nopush 优化数据包发送
   tcp_nodelay 禁用 Nagle 算法
   文件 AIO（异步 I/O）处理大文件

6. 精心优化的数据结构
   红黑树：定时器、location 匹配
   单/双链表：缓冲区管理
   哈希表：变量查找
   基数树：IP 匹配

7. 模块化架构
   只编译需要的模块
   减少不必要的代码路径

5.3 Nginx 优化配置

# 综合性能优化配置
user www-data;
worker_processes auto;                    # 自动匹配 CPU 核心数
worker_cpu_affinity auto;                 # 自动绑定 CPU
worker_rlimit_nofile 100000;              # 提高文件描述符限制

events {
    worker_connections 65535;             # 每个Worker最大连接数
    use epoll;                            # 使用 epoll
    multi_accept on;                      # 一次性接收所有新连接
    accept_mutex off;                     # Worker多时关闭互斥锁
}

http {
    sendfile on;                          # 零拷贝
    tcp_nopush on;                        # 优化数据包发送
    tcp_nodelay on;                       # 禁用 Nagle
    keepalive_timeout 65;
    keepalive_requests 100000;            # 一个长连接最多处理多少请求

    # 文件描述符缓存
    open_file_cache max=10000 inactive=60s;
    open_file_cache_valid 90s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    # 连接优化
    reset_timedout_connection on;         # 超时连接直接 reset
    client_body_timeout 12;
    send_timeout 10;

    # 压缩
    gzip on;
    gzip_comp_level 4;
    gzip_min_length 256;
    gzip_types text/plain text/css application/javascript application/json;

    # 输出缓冲
    output_buffers 1 32k;
    postpone_output 1460;                 # 累积到 MSS 大小再发送
}

六、Nginx vs OpenResty vs Envoy

6.1 对比总览

特性              Nginx            OpenResty         Envoy
─────────────────────────────────────────────────────────────
基础              Nginx 核心        Nginx + LuaJIT    C++ 自研
语言              C                C + Lua           C++
配置              静态配置文件       静态 + Lua 动态    xDS 动态 API
可编程性          模块（C）         Lua 脚本          WASM / Lua / C++
动态配置          需 reload         运行时动态         实时推送
负载均衡          基础策略丰富       同 Nginx + Lua     高级（区域感知、加权等）
可观测性          基础日志          Lua 扩展          内置（Metrics、Tracing、Logging）
服务发现          手动配置          Lua 脚本          原生支持（DNS、xDS、EDS）
gRPC 支持         基础             基础              原生（双向流）
HTTP/3            实验性           实验性            支持
管理 API          信号（reload）    Lua API           REST gRPC API
定位              Web/代理服务器    可编程 Web 平台    服务网格代理
诞生年份          2004             2011              2016

6.2 OpenResty

OpenResty = Nginx + LuaJIT + 大量 Lua 库

核心特点：
  在 Nginx 中嵌入 Lua 虚拟机
  可以用 Lua 脚本处理请求（不限于静态配置）
  几乎可以访问 Nginx 所有内部 API

典型用途：
  - API 网关（Kong 基于 OpenResty）
  - WAF（ModSecurity 替代）
  - 动态路由
  - 限流、认证（复杂逻辑）
  - 缓存（Redis + Lua）

示例：
  location /api {
      content_by_lua_block {
          local redis = require "resty.redis"
          local red = redis:new()
          red:set_timeouts(1000, 1000, 1000)
          local ok, err = red:connect("127.0.0.1", 6379)
          local res, err = red:get("cache:" .. ngx.var.uri)
          if res then
              ngx.say(res)
              return
          end
          -- 缓存未命中，请求后端
          local res = ngx.location.capture("/backend" .. ngx.var.uri)
          red:setex("cache:" .. ngx.var.uri, 300, res.body)
          ngx.say(res.body)
      }
  }

适用场景：
  需要动态逻辑、API 网关、复杂认证
  不想写 C 模块但需要超越静态配置

6.3 Envoy

Envoy = Lyft 开源的 L4/L7 代理，CNCF 项目

核心特点：
  面向微服务和云原生设计
  动态配置 API（xDS 协议）
  内置可观测性（Metrics、Tracing、Logging）
  Istio 的数据平面

优势：
  - 动态配置：通过 xDS API 实时更新，不需要 reload
  - 服务发现：原生支持 DNS、EDS、Consul 等
  - 高级负载均衡：区域感知、故障注入、灰度发布
  - 可观测性：原生 Prometheus 指标、分布式追踪
  - gRPC 一等公民
  - WASM 扩展

xDS 协议：
  LDS（Listener）   — 监听器配置
  RDS（Route）      — 路由配置
  CDS（Cluster）    — 集群（upstream）配置
  EDS（Endpoint）   — 集群成员（服务发现）
  SDS（Secret）     — 证书配置

适用场景：
  微服务架构、服务网格
  Kubernetes Ingress / Gateway
  需要动态配置和高级可观测性的场景

6.4 如何选择

选 Nginx：
  ✓ 传统 Web 服务、反向代理、负载均衡
  ✓ 静态文件服务
  ✓ 配置变更不频繁
  ✓ 团队熟悉 Nginx
  ✓ 社区最成熟，资料最多

选 OpenResty：
  ✓ 需要动态逻辑（API 网关、WAF）
  ✓ 想用脚本扩展 Nginx
  ✓ 已有 Nginx 基础设施
  ✓ 使用 Kong API 网关

选 Envoy：
  ✓ 微服务架构 / 服务网格
  ✓ 需要动态配置（Kubernetes 环境）
  ✓ Istio 服务网格
  ✓ 需要高级可观测性
  ✓ gRPC 为主的服务

很多公司的架构：
  边缘层：Nginx（HTTPS 终端、静态资源、基础代理）
  内部层：Envoy（微服务间通信、服务网格）

七、小结

本文深入了 Nginx 的底层原理：

进程模型：Master 管理 Worker，Worker 独立处理请求，崩溃不扩散
事件驱动：epoll 实现高效 I/O 多路复用，单线程处理万级并发
请求处理：11 个阶段按顺序执行，模块注册到特定阶段
内存管理：内存池批量分配/释放，slab 管理共享内存
为什么快：事件驱动 + 零拷贝 + 内存池 + 无锁 + 高效数据结构
技术选型：Nginx（传统 Web）、OpenResty（可编程代理）、Envoy（云原生/服务网格）

系列总结

四篇 Nginx 学习笔记到此结束：

基础与核心配置 — 安装、配置结构、静态文件、虚拟主机、location
反向代理与负载均衡 — 代理配置、负载策略、健康检查、四层/七层
HTTPS、性能优化与实战 — 证书、压缩、缓存、限流、.NET 部署
深入原理 — 进程模型、epoll、11 阶段、内存管理、技术对比

Nginx 的学习曲线：配置入门不难，但深入理解原理需要时间。建议边学边练，在自己的服务器上实际配置和调优。

Nginx 学习笔记（三）：HTTPS、性能优化与实战

Sun, 07 Jun 2026 10:00:00 +0800

写在前面

本文是 Nginx 学习笔记系列的第三篇，聚焦生产环境实战：HTTPS 证书配置、性能优化技巧（压缩、缓存、限流、跨域），以及 .NET 应用部署和常见问题排查。

一、HTTPS 配置

1.1 为什么需要 HTTPS

HTTP 的问题：
  - 明文传输       — 数据可被窃听
  - 不验证身份     — 可能被冒充（钓鱼）
  - 数据可被篡改   — 运营商插广告、劫持

HTTPS = HTTP + TLS
  - 加密传输       — 数据被加密，无法窃听
  - 身份验证       — 证书验证服务器身份
  - 完整性校验     — 数据被篡改可检测
  - SEO 加分       — Google 优先收录 HTTPS

1.2 申请免费证书（Let’s Encrypt）

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 自动获取并配置证书（一条命令搞定）
sudo certbot --nginx -d example.com -d www.example.com

# 仅获取证书（手动配置）
sudo certbot certonly --nginx -d example.com

# 手动获取（DNS 验证，适合泛域名）
sudo certbot certonly --manual --preferred-challenges dns -d "*.example.com" -d example.com

证书文件位置：
  /etc/letsencrypt/live/example.com/fullchain.pem    — 证书（含中间证书）
  /etc/letsencrypt/live/example.com/privkey.pem      — 私钥

证书有效期：90 天
自动续期：Certbot 安装时会自动创建定时任务
  查看：systemctl list-timers | grep certbot
  手动续期：sudo certbot renew --dry-run

1.3 自动续期配置

# 检查自动续期定时任务
systemctl status certbot.timer

# 手动测试续期（不会真的续）
sudo certbot renew --dry-run

# 续期后自动重载 Nginx（配置 hook）
# /etc/letsencrypt/renewal-hooks/post/reload-nginx.sh
#!/bin/bash
nginx -t && systemctl reload nginx

1.4 手动配置 HTTPS

server {
    # HTTP → HTTPS 重定向
    listen 80;
    server_name example.com www.example.com;
    return 301 https://www.example.com$request_uri;
}

server {
    listen 443 ssl http2;                   # 开启 HTTP/2
    server_name www.example.com;

    # 证书配置
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    # SSL 参数
    ssl_protocols TLSv1.2 TLSv1.3;          # 只允许 TLS 1.2 和 1.3
    ssl_ciphers HIGH:!aNULL:!MD5;           # 高强度加密套件
    ssl_prefer_server_ciphers on;           # 优先使用服务器端的加密套件

    # SSL 会话缓存
    ssl_session_cache shared:SSL:10m;       # 10MB 缓存，约 4万个会话
    ssl_session_timeout 10m;                # 会话超时 10 分钟
    ssl_session_tickets off;                # 禁用 Session Tickets（前向安全）

    # OCSP Stapling（在线证书状态检查）
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # HSTS（告诉浏览器只能用 HTTPS 访问）
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # 安全头部
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

1.5 SSL 安全等级测试

# 用 SSL Labs 测试（在线）
# https://www.ssllabs.com/ssltest/

# 用 openssl 测试连接
openssl s_client -connect example.com:443 -servername example.com

# 测试支持的协议
openssl s_client -connect example.com:443 -tls1_2
openssl s_client -connect example.com:443 -tls1_3

# 查看证书信息
openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -text -noout

1.6 自签名证书（开发环境）

# 生成自签名证书
openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout selfsigned.key \
  -out selfsigned.crt \
  -subj "/CN=localhost"

server {
    listen 443 ssl;
    server_name localhost;

    ssl_certificate     /etc/nginx/ssl/selfsigned.crt;
    ssl_certificate_key /etc/nginx/ssl/selfsigned.key;
}

二、性能优化

2.1 gzip 压缩

http {
    # 开启 gzip
    gzip on;
    gzip_vary on;                           # 添加 Vary: Accept-Encoding 头
    gzip_proxied any;                       # 代理请求也压缩
    gzip_comp_level 4;                      # 压缩级别 1-9（4 是最佳平衡点）
    gzip_min_length 256;                    # 小于 256 字节不压缩
    gzip_buffers 16 8k;                     # 压缩缓冲区
    gzip_http_version 1.1;                  # 最低 HTTP 版本
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/json
        application/xml
        application/rss+xml
        application/atom+xml
        image/svg+xml
        font/opentype
        font/ttf
        font/woff2
        application/wasm;
}

压缩效果对比：
  未压缩 HTML（50KB）→ gzip 后（~8KB）   减少 84%
  未压缩 CSS（100KB）→ gzip 后（~15KB）  减少 85%
  未压缩 JS（200KB） → gzip 后（~50KB）  减少 75%

注意：
  - 图片（jpg/png/gif）和视频已经压缩过，不要再 gzip
  - gzip_comp_level 不是越高越好，6 以上 CPU 开销增大但压缩收益递减
  - 推荐值 4-6

2.2 Brotli 压缩（比 gzip 更好）

# 需要安装 ngx_brotli 模块
# Docker 可用 nginx:1.26-alpine 自行编译或使用 openresty

http {
    brotli on;
    brotli_comp_level 6;
    brotli_types text/plain text/css application/javascript application/json;

    # 同时支持 gzip 和 brotli
    # Nginx 会根据客户端 Accept-Encoding 自动选择
    gzip on;
    gzip_comp_level 4;
}

Brotli vs gzip：
  Brotli 通常比 gzip 多压缩 15-25%
  但压缩速度比 gzip 慢（CPU 开销更大）
  大多数现代浏览器都支持
  建议静态资源预压缩用 Brotli，动态内容用 gzip

2.3 浏览器缓存

server {
    root /var/www/html;

    # 静态资源 — 长期缓存
    location ~* \.(css|js)$ {
        expires 1y;                         # 1 年
        add_header Cache-Control "public, immutable";
        # immutable：告诉浏览器不需要重新验证
    }

    # 图片 — 中期缓存
    location ~* \.(jpg|jpeg|png|gif|ico|svg|webp|avif)$ {
        expires 6M;                         # 6 个月
        add_header Cache-Control "public";
    }

    # 字体 — 长期缓存
    location ~* \.(woff|woff2|ttf|otf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # HTML — 不缓存或短缓存
    location ~* \.html$ {
        add_header Cache-Control "no-cache";
        # no-cache：每次都验证（304 Not Modified）
    }
}

缓存策略总结：
  文件类型           策略              时间
  ──────────────────────────────────────────
  HTML              no-cache          每次验证
  CSS/JS（带hash）   immutable         1 年
  图片               public            6 个月
  字体               immutable         1 年
  API 响应           no-store          不缓存

  带 hash 的文件名（app.3a4b5c.js）→ 可以永久缓存
  不带 hash 的文件名（app.js）    → 不能长期缓存

2.4 限流

http {
    # 基于 IP 的请求速率限制
    # binary_remote_addr：二进制格式的 IP，占用更少内存
    # zone=api_limit:10m：共享内存区域，10MB（约 16万个 IP）
    # rate=100r/s：每个 IP 每秒 100 个请求
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/s;

    # 基于IP的并发连接数限制
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

    server {
        # 请求速率限制
        location /api/ {
            limit_req zone=api_limit burst=50 nodelay;
            # burst=50：允许短时突发 50 个请求
            # nodelay：突发请求不延迟处理

            proxy_pass http://backend;
        }

        # 并发连接限制
        location /download/ {
            limit_conn conn_limit 10;        # 每个 IP 最多 10 个并发连接
            limit_rate 500k;                 # 每个连接限速 500KB/s
        }

        # 限流后的自定义响应
        limit_req_status 429;                # 返回 429 Too Many Requests
        limit_conn_status 429;
    }
}

限流参数说明：
  rate=10r/s    — 每秒 10 个请求
  rate=600r/m   — 每分钟 600 个请求（更适合 API）

  burst=N       — 允许排队的请求数
  nodelay       — 突发请求立即处理（不延迟）

  不加 burst：
    超过 rate 立即返回 429
  加 burst + nodelay：
    允许瞬时突发，但总速率不超过 rate

2.5 跨域（CORS）配置

server {
    # CORS 配置
    location /api/ {
        # 允许的源
        add_header Access-Control-Allow-Origin "https://www.example.com" always;

        # 允许的方法
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;

        # 允许的头部
        add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;

        # 允许携带凭证（Cookie）
        add_header Access-Control-Allow-Credentials "true" always;

        # 预检请求缓存时间
        add_header Access-Control-Max-Age 3600 always;

        # 处理 OPTIONS 预检请求
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin "https://www.example.com" always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
            add_header Access-Control-Max-Age 3600 always;
            add_header Content-Length 0;
            add_header Content-Type text/plain;
            return 204;
        }

        proxy_pass http://backend;
    }
}

CORS 要点：
  Access-Control-Allow-Origin：
    - 只能设置一个源，不能设置多个
    - 动态设置可以用 $http_origin 变量（但需维护白名单）

  预检请求（OPTIONS）：
    - 浏览器自动发送
    - 必须正确响应，否则实际请求不会发出
    - 非简单请求（带自定义头、PUT/DELETE 等）会触发预检

2.6 动态 CORS（多域名白名单）

# 定义允许的域名
map $http_origin $cors_origin {
    default "";
    "https://www.example.com"    "https://www.example.com";
    "https://app.example.com"    "https://app.example.com";
    "https://admin.example.com"  "https://admin.example.com";
    "http://localhost:3000"      "http://localhost:3000";
}

server {
    location /api/ {
        # 动态设置 CORS
        add_header Access-Control-Allow-Origin $cors_origin always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;

        if ($cors_origin = "") {
            return 403;                    # 不在白名单的源直接拒绝
        }

        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin $cors_origin always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Max-Age 3600 always;
            return 204;
        }

        proxy_pass http://backend;
    }
}

三、.NET 应用部署实战

3.1 部署架构

客户端 → Nginx（443/80）→ .NET 应用（5000）

Nginx 负责：
  ✓ HTTPS 终端（.NET 应用不需要处理 TLS）
  ✓ 静态文件服务（wwwroot）
  ✓ 压缩、缓存
  ✓ 限流、安全
  ✓ 负载均衡（多实例）

.NET 应用负责：
  ✓ API 处理
  ✓ 业务逻辑
  ✓ SSR（Blazor Server / Razor Pages）

3.2 发布 .NET 应用

# 发布应用
dotnet publish -c Release -o /app/publish

# 运行
cd /app/publish
./MyApp --urls http://0.0.0.0:5000

# 推荐用 systemd 管理

3.3 systemd 服务配置

# /etc/systemd/system/myapp.service
[Unit]
Description=My .NET Application
After=network.target

[Service]
Type=notify
WorkingDirectory=/app/publish
ExecStart=/app/publish/MyApp --urls http://0.0.0.0:5000
Restart=always
RestartSec=10
SyslogIdentifier=myapp
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://0.0.0.0:5000
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable myapp
sudo systemctl start myapp

# 查看状态
sudo systemctl status myapp

# 查看日志
sudo journalctl -u myapp -f

3.4 Nginx 配置

# /etc/nginx/conf.d/myapp.conf

# HTTP → HTTPS 重定向
server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

# HTTPS
server {
    listen 443 ssl http2;
    server_name api.example.com;

    # SSL 证书
    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    # SSL 参数
    include /etc/nginx/snippets/ssl-params.conf;

    # 安全头部
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Strict-Transport-Security "max-age=31536000" always;

    # 请求体大小
    client_max_body_size 50m;

    # API 请求转发到 .NET
    location /api/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 5s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }

    # Swagger（仅开发/测试环境）
    location /swagger/ {
        proxy_pass http://127.0.0.1:5000/swagger/;
    }

    # 健康检查
    location /health {
        access_log off;
        proxy_pass http://127.0.0.1:5000/health;
    }
}

3.5 ASP.NET Core 配合 Nginx

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// 配置转发头（必须在使用路径基之前）
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor
                            | ForwardedHeaders.XForwardedProto;
    options.KnownNetworks.Clear();
    options.KnownProxies.Clear();
});

var app = builder.Build();

// 必须在其他中间件之前调用
app.UseForwardedHeaders();

// 其他中间件
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

// appsettings.json
{
  "Urls": "http://0.0.0.0:5000",
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:5000"
      }
    },
    "Limits": {
      "MaxRequestBodySize": 52428800
    }
  }
}

关键配置：
  UseForwardedHeaders()  — 让 ASP.NET Core 读取 X-Forwarded-* 头
  KnownNetworks.Clear()  — 信任所有代理（按需限制）
  Kestrel 只监听 HTTP    — HTTPS 由 Nginx 处理

3.6 Docker Compose 部署

version: '3.8'

services:
  myapp:
    image: myapp:latest
    container_name: myapp
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://0.0.0.0:5000
    expose:
      - "5000"
    restart: always
    networks:
      - internal

  nginx:
    image: nginx:1.26
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf:/etc/nginx
      - ./nginx/ssl:/etc/nginx/ssl
      - ./nginx/logs:/var/log/nginx
    depends_on:
      - myapp
    restart: always
    networks:
      - internal

networks:
  internal:
    internal: true        # 内部网络，不对外暴露

好处：
  - myapp 只在内部网络，外部无法直接访问
  - Nginx 是唯一的入口
  - 升级 myapp 不影响 Nginx
  - 可以轻松扩展 myapp 实例

四、常见问题排查

4.1 502 Bad Gateway

原因：Nginx 无法连接到后端服务

排查步骤：
  1. 检查后端是否运行
     systemctl status myapp
     curl http://127.0.0.1:5000/health

  2. 检查端口是否正确
     ss -tlnp | grep 5000

  3. 检查防火墙
     sudo iptables -L -n

  4. 查看 Nginx 错误日志
     tail -f /var/log/nginx/error.log
     # 常见错误：
     # connect() failed (111: Connection refused)
     # connect() failed (113: No route to host)

4.2 504 Gateway Timeout

原因：后端响应超时

解决：
  # 增加超时时间
  proxy_read_timeout 120s;        # 默认 60s，慢接口可以增大
  proxy_connect_timeout 10s;

  # 或者优化后端性能

4.3 413 Request Entity Too Large

原因：请求体超过限制

解决：
  client_max_body_size 50m;       # 默认 1m，按需调大

4.4 配置不生效

# 检查配置语法
nginx -t

# 重新加载配置
nginx -s reload

# 检查是否加载了正确的配置文件
nginx -T | grep "configuration file"
# 确认 include 路径是否正确

# 检查是否有缓存
curl -H "Cache-Control: no-cache" http://localhost

4.5 权限问题

常见错误：403 Forbidden

排查：
  1. 检查文件权限
     ls -la /var/www/html/
     # Nginx 用户（www-data）需要读取权限

  2. 检查 SELinux（CentOS/RHEL）
     getenforce
     # 如果是 Enforcing，需要设置上下文
     chcon -R -t httpd_sys_content_t /var/www/html/

  3. 检查 user 指令
     # nginx.conf 中的 user 是否有权限访问文件
     user www-data;

4.6 性能排查

# 查看 Nginx 状态（需要 stub_status 模块）
location /nginx_status {
    stub_status;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

# 访问状态
curl http://localhost/nginx_status
# Active connections: 5
# server accepts handled requests
#  10 10 100
# Reading: 0 Writing: 1 Waiting: 4

# 分析访问日志（慢请求）
awk '$NF > 1 {print $0}' /var/log/nginx/access.log | sort -kNF -rn | head -20

# 查看 Nginx 进程状态
ps aux | grep nginx
top -p $(pgrep nginx | tr '\n' ',')

五、生产环境检查清单

# ✅ 一个完整的生产级配置模板
server {
    listen 443 ssl http2;
    server_name example.com;

    # --- SSL ---
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_stapling on;
    ssl_stapling_verify on;

    # --- 安全头部 ---
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # --- 性能 ---
    gzip on;
    gzip_vary on;
    gzip_min_length 256;
    gzip_comp_level 4;
    gzip_types text/plain text/css application/javascript application/json;

    # --- 安全 ---
    client_max_body_size 50m;
    server_tokens off;                     # 隐藏 Nginx 版本号

    # --- 代理 ---
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# HTTP → HTTPS
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

六、小结

本文学习了 Nginx 生产环境实战：

HTTPS 配置（Let’s Encrypt、手动配置、安全参数）
SSL 安全优化（HSTS、OCSP Stapling、安全头部）
性能优化（gzip、Brotli、浏览器缓存、限流）
CORS 跨域配置（静态和动态白名单）
.NET 应用部署（systemd、Docker Compose）
ASP.NET Core 配合 Nginx（ForwardedHeaders）
常见问题排查（502、504、413、权限、性能）
生产环境配置检查清单

下一篇将深入 Nginx 的底层原理：进程模型、事件驱动机制、请求处理流程和内存管理。

Nginx 学习笔记（二）：反向代理与负载均衡

Sat, 06 Jun 2026 10:00:00 +0800

写在前面

本文是 Nginx 学习笔记系列的第二篇，深入讲解反向代理的原理和配置、负载均衡策略、upstream 健康检查，以及四层和七层代理的区别。这是 Nginx 在生产环境最核心的用途。

一、反向代理

1.1 正向代理 vs 反向代理

正向代理（代理客户端）：
  客户端 → [代理服务器] → 目标服务器
  客户端知道要访问谁，代理帮客户端转发
  例：VPN、科学上网、公司出口代理

反向代理（代理服务端）：
  客户端 → [代理服务器] → 后端服务器
  客户端不知道真正提供服务的是谁
  例：Nginx、CDN、API 网关

关键区别：
  正向代理 — 客户端配置代理，服务端不知道真实客户端
  反向代理 — 服务端躲在代理后面，客户端不知道真实服务端

1.2 反向代理能做什么

1. 隐藏后端服务器      — 客户端只看到 Nginx 的 IP
2. 负载均衡           — 请求分发到多台后端服务器
3. SSL 终端           — Nginx 处理 HTTPS，后端用 HTTP
4. 缓存              — 缓存后端响应，减少后端压力
5. 压缩              — Nginx 压缩响应，减少带宽
6. 安全              — 统一的访问控制、限流、WAF
7. 静态文件分离        — Nginx 处理静态，后端处理动态

1.3 基本配置

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://192.168.1.100:5000;    # 后端地址
    }
}

就这么简单，所有请求都会被转发到 http://192.168.1.100:5000。

1.4 完整的反向代理配置

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://192.168.1.100:5000;

        # 传递客户端真实信息
        proxy_set_header Host $host;                    # 原始域名
        proxy_set_header X-Real-IP $remote_addr;        # 客户端真实 IP
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # 代理链
        proxy_set_header X-Forwarded-Proto $scheme;     # 原始协议（http/https）

        # 超时设置
        proxy_connect_timeout 10s;    # 连接后端超时
        proxy_send_timeout 60s;       # 发送请求超时
        proxy_read_timeout 60s;       # 读取响应超时

        # 缓冲设置
        proxy_buffering on;           # 开启缓冲（默认开启）
        proxy_buffer_size 4k;         # 响应头缓冲区
        proxy_buffers 8 16k;          # 响应体缓冲区（8 个 16KB）

        # 错误处理
        proxy_intercept_errors on;    # 拦截后端错误响应
        proxy_next_upstream error timeout http_502 http_503 http_504;
        # 出错时尝试下一个后端
    }
}

1.5 proxy_pass 的路径规则

# 情况一：proxy_pass 带 URI（带 / 或路径）
location /api/ {
    proxy_pass http://backend/v1/;
    # /api/users → http://backend/v1/users
    # /api/ 被替换为 /v1/
}

# 情况二：proxy_pass 不带 URI（没有路径）
location /api/ {
    proxy_pass http://backend;
    # /api/users → http://backend/api/users
    # /api/ 前缀被保留
}

# 情况三：精确替换
location /old/ {
    proxy_pass http://backend/new/;
    # /old/users → http://backend/new/users
}

⚠️ 带不带尾斜线的区别：
  proxy_pass http://backend;     → 保留 location 前缀
  proxy_pass http://backend/;    → 替换 location 前缀

  这是 Nginx 最容易踩的坑之一，务必记住。

1.6 WebSocket 代理

location /ws/ {
    proxy_pass http://backend;

    # WebSocket 必需的头部
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 超时设置（WebSocket 长连接）
    proxy_read_timeout 3600s;    # 1 小时
    proxy_send_timeout 3600s;
}

二、负载均衡

2.1 upstream 基本配置

# 定义后端服务器组
upstream backend {
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;
    server 192.168.1.103:5000;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://backend;    # 引用 upstream
    }
}

2.2 负载均衡策略

轮询（Round Robin，默认）

upstream backend {
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;
    server 192.168.1.103:5000;
    # 请求依次分配：101 → 102 → 103 → 101 → ...
}

加权轮询（Weight）

upstream backend {
    server 192.168.1.101:5000 weight=5;     # 5/8 的请求
    server 192.168.1.102:5000 weight=2;     # 2/8 的请求
    server 192.168.1.103:5000 weight=1;     # 1/8 的请求
    # 适合服务器配置不同的场景
}

权重分配示例（总权重 8）：
  101（性能好）→ 62.5% 请求
  102（普通）  → 25%   请求
  103（低配）  → 12.5% 请求

IP 哈希（ip_hash）

upstream backend {
    ip_hash;                                # 基于客户端 IP 做哈希
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;
    server 192.168.1.103:5000;
}

特点：
  同一客户端 IP 的请求总是打到同一台后端
  适合需要会话保持（Session）的场景

  缺点：
    - 后端服务器变化时，大量会话重新分配
    - 大量请求来自同一 IP（如公司出口 NAT）会导致负载不均

最少连接（least_conn）

upstream backend {
    least_conn;                             # 分配给当前连接数最少的服务器
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;
    server 192.168.1.103:5000;
}

1
2
3

适合场景：
  请求处理时间差异大（有的快有的慢）
  避免某些服务器积压大量慢请求

一致性哈希（hash）

upstream backend {
    hash $request_uri consistent;           # 基于请求 URI 做一致性哈希
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;
    server 192.168.1.103:5000;
}

特点：
  同一 URI 总是路由到同一台后端（提高缓存命中率）
  consistent 参数：添加/删除节点时只影响相邻节点
  可以基于 $uri、$arg_user_id 等任何变量

随机（random）

upstream backend {
    random two least_conn;                  # 随机选 2 个，挑连接少的
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;
    server 192.168.1.103:5000;
}

2.3 策略选择总结

场景                          推荐策略
──────────────────────────────────────────────────
一般 Web 应用                 轮询（默认）
服务器性能不均                加权轮询
需要会话保持                  ip_hash / hash $cookie_sessionid
请求耗时差异大                least_conn
缓存命中率优先                hash $request_uri consistent
分布式文件/缓存               一致性哈希

三、upstream 服务器状态

upstream backend {
    server 192.168.1.101:5000 weight=5;

    server 192.168.1.102:5000 weight=3;

    server 192.168.1.103:5000 backup;      # 备用服务器，其他全挂才启用

    server 192.168.1.104:5000 down;        # 标记为下线，不参与负载

    server 192.168.1.105:5000 max_fails=3 fail_timeout=30s;
    # max_fails=3：30s 内失败 3 次认为不可用
    # fail_timeout=30s：不可用后 30s 后再尝试
}

参数说明：
  weight=N          — 权重（默认 1）
  max_conns=N       — 最大并发连接数（默认 0，不限制）
  max_fails=N       — 最大失败次数（默认 1）
  fail_timeout=T    — 失败超时时间（默认 10s）
  backup            — 备份服务器
  down              — 标记下线
  resolve           — 动态解析域名（适合 Docker/K8s 环境）

3.1 动态解析域名

upstream backend {
    # resolve：当后端是域名时，Nginx 会定期重新解析
    # 适合 Docker/K8s 环境，容器 IP 可能变化
    server api-service:5000 resolve;
}

server {
    resolver 127.0.0.11 valid=10s;    # Docker 内部 DNS
    # 或者使用公共 DNS
    # resolver 8.8.8.8 8.8.4.4 valid=30s;

    location / {
        # 使用变量触发运行时解析（另一种方式）
        set $backend_host "api-service:5000";
        proxy_pass http://$backend_host;
    }
}

四、健康检查

4.1 被动健康检查（内置）

Nginx 开源版只支持被动健康检查：在实际请求失败时才标记服务器不可用。

upstream backend {
    server 192.168.1.101:5000 max_fails=3 fail_timeout=30s;
    server 192.168.1.102:5000 max_fails=3 fail_timeout=30s;

    proxy_next_upstream error timeout http_502 http_503 http_504;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_next_upstream error timeout http_502 http_503 http_504;
        proxy_next_upstream_timeout 10s;     # 重试总时间
        proxy_next_upstream_tries 3;          # 最多重试 3 次
    }
}

工作流程：
  1. 请求到达 Nginx → 转发给 backend-101
  2. 101 超时或返回 502/503/504 → 记录一次失败
  3. 自动重试下一个服务器 → 转发给 backend-102
  4. 101 失败 3 次（max_fails=3）→ 标记为不可用
  5. 30s 后（fail_timeout=30s）→ 再次尝试 101

4.2 主动健康检查（Nginx Plus / 第三方模块）

开源版 Nginx 不支持主动健康检查，但有替代方案：

方案一：用 location 模拟

# 健康检查端点
server {
    listen 80;

    # 简单的健康检查
    location /health {
        access_log off;
        return 200 "healthy\n";
    }

    # 带后端检测的健康检查
    location /health/backend {
        access_log off;
        proxy_pass http://backend/health;
        proxy_intercept_errors on;
        error_page 502 503 504 = /health/unhealthy;
    }

    location /health/unhealthy {
        return 503 "unhealthy\n";
    }
}

方案二：用第三方模块 nginx_upstream_check_module

# 需要编译时添加模块
upstream backend {
    server 192.168.1.101:5000;
    server 192.168.1.102:5000;

    # 主动健康检查（Tengine / 第三方模块）
    check interval=3000 rise=2 fall=3 timeout=1000 type=http;
    check_http_send "GET /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
}

# 查看健康状态
location /status {
    check_status;
    access_log off;
}

方案三：外部健康检查脚本

#!/bin/bash
# health-check.sh — 配合 crontab 使用
BACKENDS=("192.168.1.101:5000" "192.168.1.102:5000")
NGINX_CONF="/etc/nginx/conf.d/backends.conf"

for backend in "${BACKENDS[@]}"; do
    host=$(echo $backend | cut -d: -f1)
    port=$(echo $backend | cut -d: -f2)

    if curl -sf -o /dev/null "http://$backend/health"; then
        echo "$backend: healthy"
    else
        echo "$backend: unhealthy"
        # 动态更新配置，标记 down
        sed -i "s/server $backend;/server $backend down;/" $NGINX_CONF
        nginx -s reload
    fi
done

五、四层与七层代理

5.1 区别

OSI 七层模型：
  7. 应用层      — HTTP、HTTPS、FTP、SMTP
  6. 表示层      — SSL/TLS、JPEG
  5. 会话层      — RPC
  4. 传输层      — TCP、UDP
  3. 网络层      — IP
  2. 数据链路层   — 以太网
  1. 物理层      — 网线

四层代理（L4）：工作在传输层（TCP/UDP）
  - 只看到 IP + 端口
  - 不解析应用层协议
  - 速度更快，开销更小
  - 不支持基于路径/域名的路由

七层代理（L7）：工作在应用层（HTTP）
  - 能看到 HTTP 请求内容
  - 支持基于域名、路径、头部、Cookie 的路由
  - 支持 rewrite、缓存、压缩等
  - 开销更大

5.2 四层代理配置（stream 模块）

# 注意：stream 块和 http 块是平级的，都在 main 层级
# /etc/nginx/nginx.conf

stream {
    # TCP 负载均衡 — MySQL
    upstream mysql {
        server 192.168.1.101:3306;
        server 192.168.1.102:3306;
    }

    server {
        listen 3306;
        proxy_pass mysql;
        proxy_connect_timeout 5s;
        proxy_timeout 300s;
    }

    # TCP 负载均衡 — Redis
    upstream redis {
        server 192.168.1.101:6379;
        server 192.168.1.102:6379;
    }

    server {
        listen 6379;
        proxy_pass redis;
    }

    # UDP 负载均衡 — DNS
    upstream dns {
        server 8.8.8.8:53;
        server 8.8.4.4:53;
    }

    server {
        listen 53 udp;
        proxy_pass dns;
    }
}

四层代理的典型场景：
  - 数据库代理（MySQL、PostgreSQL）
  - Redis 代理
  - 邮件代理（SMTP、IMAP）
  - 游戏服务器代理
  - MQTT 代理

5.3 七层代理（http 模块，前面讲的反向代理）

# 这就是我们一直在用的 proxy_pass
http {
    upstream api {
        server 192.168.1.101:5000;
        server 192.168.1.102:5000;
    }

    server {
        listen 80;

        # 按路径路由
        location /api/ {
            proxy_pass http://api/;
        }

        location /admin/ {
            proxy_pass http://admin-service/;
        }

        # 按请求头路由（灰度发布）
        location /api/ {
            if ($http_x_version = "v2") {
                proxy_pass http://api-v2;
            }
            proxy_pass http://api-v1;
        }
    }
}

5.4 四层 vs 七层选择

选择四层代理：
  ✓ 非 HTTP 协议（MySQL、Redis、MQTT）
  ✓ 追求极致性能（不需要解析应用层）
  ✓ 只需要简单的 TCP/UDP 转发

选择七层代理：
  ✓ HTTP/HTTPS 服务
  ✓ 需要基于路径/域名/头部的路由
  ✓ 需要 SSL 终端
  ✓ 需要缓存、压缩、限流

常见架构：四层 + 七层组合
  客户端 → L4 负载均衡（VIP）→ L7 Nginx 集群 → 后端服务
  L4 做入口流量分发
  L7 做精细路由和业务处理

六、实战：完整的代理配置

# /etc/nginx/conf.d/api.conf

upstream api_servers {
    least_conn;
    server 10.0.1.101:5000 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.102:5000 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.103:5000 weight=2 max_fails=3 fail_timeout=30s;
    server 10.0.1.104:5000 backup;

    keepalive 32;                          # 保持与后端的长连接
}

server {
    listen 80;
    server_name api.example.com;

    # 请求体大小限制
    client_max_body_size 50m;

    location / {
        proxy_pass http://api_servers;

        # 传递真实信息
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 长连接
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # 超时
        proxy_connect_timeout 5s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;

        # 缓冲
        proxy_buffering on;
        proxy_buffer_size 8k;
        proxy_buffers 8 32k;

        # 失败重试
        proxy_next_upstream error timeout http_502 http_503 http_504;
        proxy_next_upstream_timeout 10s;
        proxy_next_upstream_tries 3;
    }

    # WebSocket
    location /ws/ {
        proxy_pass http://api_servers;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
    }

    # 健康检查
    location /health {
        access_log off;
        proxy_pass http://api_servers/health;
    }
}

七、获取客户端真实 IP

多层代理后，如何获取客户端真实 IP？

7.1 单层代理

# Nginx 代理层
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

# 后端获取（以 ASP.NET Core 为例）
var ip = HttpContext.Connection.RemoteIpAddress;          // Nginx 的 IP
var realIp = HttpContext.Request.Headers["X-Real-IP"];    // 客户端真实 IP
var forwarded = HttpContext.Request.Headers["X-Forwarded-For"]; // 代理链

7.2 多层代理

客户端(1.1.1.1) → CDN(2.2.2.2) → Nginx(3.3.3.3) → 后端

X-Forwarded-For: 1.1.1.1, 2.2.2.2
X-Real-IP: 1.1.1.1

# 第一层 Nginx（或 CDN）
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

# 第二层 Nginx
# 使用 set 指令获取最左侧的 IP（最原始的客户端）
set_real_ip_from 10.0.0.0/8;            # 信任的代理 IP 段
set_real_ip_from 172.16.0.0/12;
real_ip_header X-Forwarded-For;         # 从这个头部获取真实 IP
real_ip_recursive on;                   # 递归排除信任的代理 IP

# 现在 $remote_addr 就是客户端真实 IP 了

7.3 ASP.NET Core 配置

// Program.cs
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor
                            | ForwardedHeaders.XForwardedProto;
    options.KnownNetworks.Clear();       // 信任所有代理（按需调整）
    options.KnownProxies.Clear();
});

// 在 UseHttpsRedirection 之前调用
app.UseForwardedHeaders();

八、小结

本文学习了 Nginx 反向代理和负载均衡：

正向代理 vs 反向代理的区别
反向代理配置（proxy_pass、proxy_set_header、超时、缓冲）
proxy_pass 路径规则（带不带尾斜线的坑）
WebSocket 代理
负载均衡策略（轮询、加权、ip_hash、least_conn、一致性哈希）
upstream 服务器状态管理
被动/主动健康检查
四层代理（stream）vs 七层代理（http）
获取客户端真实 IP

下一篇将学习 HTTPS 配置、性能优化和 .NET 应用部署实战。

Nginx 学习笔记（一）：基础与核心配置

Fri, 05 Jun 2026 10:00:00 +0800

写在前面

本文是 Nginx 学习笔记系列的第一篇，介绍 Nginx 的核心概念、安装方式、配置文件结构，以及静态文件托管和虚拟主机配置。基于 Nginx 1.26 稳定版。

一、Nginx 是什么

1.1 定义

Nginx（engine-x）是一个高性能的 HTTP 和反向代理服务器，也是一个 IMAP/POP3/SMTP 代理服务器。

核心能力：
- Web 服务器       — 高性能静态文件服务
- 反向代理         — 转发请求到后端应用
- 负载均衡         — 分发流量到多台服务器
- 缓存             — 缓存后端响应，降低负载
- 流媒体           — MP4、FLV 流媒体支持
- 邮件代理         — IMAP/POP3/SMTP 代理（用得少）

1.2 为什么选择 Nginx

1. 高并发
   单机支持数万并发连接（C10K 问题而设计）
   官方基准：单机 5万+ 并发连接

2. 低资源
   内存占用极小（相比 Apache）
   1万空闲连接仅占约 2.5MB 内存

3. 高可靠性
   Master/Worker 架构，Worker 崩溃不影响整体
   支持热加载配置（不停机 reload）

4. 功能丰富
   反向代理、负载均衡、缓存、限流、HTTPS
   模块化设计，按需扩展

5. 生态成熟
   全球 Top 1000 网站中超过 30% 使用 Nginx
   OpenResty、Tengine 等衍生版本

1.3 Nginx vs Apache

对比项          Nginx                 Apache
───────────────────────────────────────────────
并发模型        事件驱动（epoll）      进程/线程驱动
内存占用        低（万级连接几MB）     高（每连接一线程）
静态文件        极快                  快
动态内容        需要反向代理           原生支持（mod_php 等）
配置语法        简洁                  复杂（.htaccess）
适用场景        高并发、反向代理       动态内容、.htaccess
市场份额        ~34%（持续增长）      ~30%（缓慢下降）

二、安装

2.1 Linux 安装

# Ubuntu / Debian
sudo apt update
sudo apt install nginx

# CentOS / RHEL
sudo yum install nginx

# 查看版本
nginx -v
# nginx version: nginx/1.26.2

2.2 Docker 安装（推荐）

docker run -d \
  --name nginx \
  -p 80:80 \
  -p 443:443 \
  -v /opt/nginx/conf:/etc/nginx \
  -v /opt/nginx/html:/usr/share/nginx/html \
  -v /opt/nginx/logs:/var/log/nginx \
  nginx:1.26

目录映射说明：
  /etc/nginx           — 配置文件目录
  /usr/share/nginx/html — 默认网站根目录
  /var/log/nginx        — 日志目录

建议生产环境用 Docker Compose 管理：
  方便升级、回滚、扩容

2.3 Windows 安装

# 方式一：winget
winget install Nginx.Nginx

# 方式二：下载解压
# https://nginx.org/en/download.html
# 解压后运行 nginx.exe 即可

Windows 注意事项：
  - 仅适合开发测试，不推荐生产环境
  - 性能远低于 Linux（IOCP 不如 epoll）
  - 不支持某些高级功能（如 sendfile 优化）

2.4 验证

# 检查配置文件语法
nginx -t
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

# 查看版本和编译参数
nginx -V

# 快速测试
curl http://localhost
# 返回 Welcome to nginx! 页面

三、常用命令

# 启动
nginx                                    # 直接启动
systemctl start nginx                    # systemd 方式

# 停止
nginx -s stop                            # 立即停止
nginx -s quit                            # 优雅停止（处理完当前请求再停）
systemctl stop nginx

# 重载配置（不停机，生产环境常用）
nginx -s reload
systemctl reload nginx

# 重新打开日志文件（日志切割后使用）
nginx -s reopen

# 检查配置
nginx -t                                 # 检查语法
nginx -T                                 # 检查语法 + 打印完整配置

# 指定配置文件
nginx -c /etc/nginx/nginx.conf

# 查看帮助
nginx -h

1
2
3

生产环境常用操作：
  修改配置 → nginx -t 检查 → nginx -s reload 重载
  永远不要用 stop + start，用 reload 实现零停机

四、配置文件结构

4.1 目录结构

/etc/nginx/
├── nginx.conf              # 主配置文件
├── conf.d/                 # 额外配置（推荐放在这里）
│   └── *.conf              # 每个站点一个文件
├── sites-available/        # 可用站点（Debian/Ubuntu）
│   └── default
├── sites-enabled/          # 已启用站点（符号链接）
│   └── default -> ../sites-available/default
├── modules-enabled/        # 动态模块
├── snippets/               # 可复用的配置片段
│   ├── ssl-params.conf
│   └── proxy-params.conf
├── mime.types              # MIME 类型映射
├── fastcgi_params          # FastCGI 参数
├── scgi_params             # SCGI 参数
└── uwsgi_params            # uWSGI 参数

4.2 主配置文件

# /etc/nginx/nginx.conf

# 全局块 — 影响 Nginx 整体
user www-data;                          # 运行用户
worker_processes auto;                  # Worker 进程数（auto = CPU 核心数）
error_log /var/log/nginx/error.log;     # 错误日志
pid /run/nginx.pid;                     # PID 文件

# events 块 — 影响网络连接
events {
    worker_connections 1024;            # 每个 Worker 最大连接数
    # 总最大并发 = worker_processes × worker_connections
    # 4核 × 1024 = 4096 并发连接
}

# http 块 — HTTP 服务器配置
http {
    include       mime.types;           # MIME 类型映射
    default_type  application/octet-stream;

    # 日志格式
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log main;

    sendfile        on;                 # 零拷贝发送文件
    tcp_nopush      on;                 # 优化数据包发送
    tcp_nodelay     on;                 # 禁用 Nagle 算法
    keepalive_timeout 65;               # 长连接超时
    types_hash_max_size 2048;

    # gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json;

    # 包含其他配置文件
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

4.3 配置层级关系

nginx.conf
├── 全局块（main）
│   ├── user
│   ├── worker_processes
│   └── error_log
├── events 块
│   └── worker_connections
└── http 块
    ├── 全局 HTTP 配置
    ├── upstream 块（负载均衡组）
    └── server 块（虚拟主机）
        ├── 全局 server 配置
        └── location 块（URL 路由）
            └── 具体处理规则

记忆口诀：
  从外到内：main → events → http → server → location
  嵌套关系：http 包含 server，server 包含 location
  配置继承：内层可以覆盖外层的配置

五、静态文件托管

5.1 基本静态网站

server {
    listen 80;                           # 监听端口
    server_name example.com;             # 域名
    root /var/www/html;                  # 网站根目录
    index index.html index.htm;          # 默认首页

    location / {
        try_files $uri $uri/ =404;       # 尝试找文件，找不到返回 404
    }

    # 静态文件缓存
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff2)$ {
        expires 30d;                     # 浏览器缓存 30 天
        add_header Cache-Control "public, immutable";
    }

    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }
}

5.2 try_files 详解

# 按顺序查找文件
location / {
    try_files $uri $uri/ /index.html;
    # 1. 查找请求的文件（$uri）
    # 2. 查找请求的目录（$uri/）
    # 3. 都找不到则返回 /index.html（SPA 应用常用）
}

# 自定义错误页面
location / {
    try_files $uri $uri/ @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

SPA 应用（Vue/React）的典型配置：
  try_files $uri $uri/ /index.html;
  所有未匹配的路径都返回 index.html
  让前端路由（history 模式）来处理

5.3 目录列表

# 开启目录浏览（适合文件服务器）
location /files/ {
    alias /data/files/;
    autoindex on;                        # 开启目录列表
    autoindex_exact_size off;            # 显示人类可读的文件大小
    autoindex_localtime on;              # 显示本地时间
}

六、虚拟主机

虚拟主机允许一台 Nginx 服务器同时托管多个网站。

6.1 基于域名的虚拟主机（最常用）

# 网站 A
server {
    listen 80;
    server_name www.site-a.com site-a.com;

    root /var/www/site-a;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    access_log /var/log/nginx/site-a.access.log;
    error_log  /var/log/nginx/site-a.error.log;
}

# 网站 B
server {
    listen 80;
    server_name www.site-b.com;

    root /var/www/site-b;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    access_log /var/log/nginx/site-b.access.log;
    error_log  /var/log/nginx/site-b.error.log;
}

原理：
  Nginx 根据请求头中的 Host 字段匹配 server_name
  不同域名 → 不同的 server 块 → 不同的 root 目录

推荐做法：
  每个虚拟主机一个 .conf 文件
  放在 /etc/nginx/conf.d/ 目录下
  如：site-a.conf、site-b.conf

6.2 基于端口的虚拟主机

# 端口 80 — 主站
server {
    listen 80;
    server_name example.com;
    root /var/www/main;
}

# 端口 8080 — 测试站
server {
    listen 8080;
    server_name example.com;
    root /var/www/test;
}

# 端口 9090 — 管理后台
server {
    listen 9090;
    server_name example.com;
    root /var/www/admin;
}

6.3 基于IP的虚拟主机（少用）

server {
    listen 192.168.1.10:80;
    server_name example.com;
    root /var/www/site-a;
}

server {
    listen 192.168.1.11:80;
    server_name example.com;
    root /var/www/site-b;
}

七、location 匹配规则

location 是 Nginx 配置的核心，决定请求如何被处理。

7.1 匹配语法

# 精确匹配（最高优先级）
location = /exact/path {
    # 只匹配 /exact/path，不匹配 /exact/path/
}

# 前缀匹配（优先级高于正则）
location ^~ /images/ {
    # 匹配以 /images/ 开头的请求
    # 一旦匹配，不再检查正则
}

# 正则匹配（区分大小写）
location ~ \.php$ {
    # 匹配以 .php 结尾的请求
}

# 正则匹配（不区分大小写）
location ~* \.(jpg|png|gif)$ {
    # 匹配以 .jpg/.png/.gif 结尾的请求（不区分大小写）
}

# 普通前缀匹配（最低优先级）
location /docs/ {
    # 匹配以 /docs/ 开头的请求
}

7.2 匹配优先级

优先级从高到低：

1. = 精确匹配          location = /path
2. ^~ 前缀匹配         location ^~ /path
3. ~ 正则匹配（区分）   location ~ /path
4. ~* 正则匹配（不区分） location ~* /path
5. 普通前缀匹配         location /path

记忆：先精确 > 前缀^~ > 正则 > 普通
      正则之间按配置文件中的顺序匹配（先写的优先）

7.3 实际案例

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # 1. 精确匹配首页
    location = / {
        # 只匹配 /
    }

    # 2. 静态资源（前缀匹配，跳过正则检查，性能更好）
    location ^~ /static/ {
        expires 30d;
        alias /data/static/;
    }

    # 3. 图片（正则匹配）
    location ~* \.(jpg|jpeg|png|gif|ico|svg|webp)$ {
        expires 7d;
        add_header Cache-Control "public";
    }

    # 4. PHP 文件
    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # 5. 其他请求
    location / {
        try_files $uri $uri/ =404;
    }
}

八、常用变量

# 请求相关
$request            # 完整的请求行（GET /path HTTP/1.1）
$request_method     # 请求方法（GET、POST、PUT 等）
$request_uri        # 完整的原始 URI（包含参数）
$uri                # 当前 URI（可能被重写，不含参数）
$args               # 查询参数（? 后面的部分）
$query_string       # 同 $args

# 客户端相关
$remote_addr        # 客户端 IP
$remote_port        # 客户端端口
$http_user_agent    # 用户代理（浏览器信息）
$http_referer       # 来源页面
$http_cookie        # Cookie

# 服务器相关
$host               # 请求头中的 Host 字段
$server_name        # 当前 server 块的 server_name
$server_port        # 服务器监听端口
$document_root      # 当前请求的 root 目录
$request_filename   # 请求对应的文件完整路径

# 响应相关
$status             # 响应状态码（200、404 等）
$body_bytes_sent    # 发送给客户端的字节数（不含响应头）
$request_time       # 请求处理时间（秒）

变量可以在以下位置使用：
  - if 条件判断
  - rewrite 重写规则
  - access_log 日志格式
  - proxy_set_header 设置请求头
  - return 返回内容

九、rewrite 重写规则

9.1 基本语法

# rewrite regex replacement [flag];
# flag:
#   last      — 重写后重新开始匹配 location（默认）
#   break     — 重写后不再匹配后续 rewrite，但继续在当前 location 中处理
#   redirect  — 返回 302 临时重定向
#   permanent — 返回 301 永久重定向

server {
    listen 80;

    # HTTP 重定向到 HTTPS
    return 301 https://$host$request_uri;

    # 旧路径重定向到新路径
    rewrite ^/old-page$ /new-page permanent;
    rewrite ^/blog/(\d+)/(.*)$ /article/$2?category=$1 last;

    # 域名重定向
    if ($host != 'www.example.com') {
        rewrite ^/(.*)$ https://www.example.com/$1 permanent;
    }
}

9.2 if 指令

# if 可以使用的条件：
# 变量名             — 非空非0为 true
# = !=               — 字符串比较
# ~ ~*               — 正则匹配
# -f !-f             — 文件是否存在
# -d !-d             — 目录是否存在
# -e !-e             — 文件/目录/符号链接是否存在

location / {
    # 根据UA返回不同内容
    if ($http_user_agent ~* "Mobile") {
        rewrite ^ /mobile$uri last;
    }

    # 防盗链
    location ~* \.(jpg|png|gif)$ {
        valid_referers none blocked server_names *.example.com;
        if ($invalid_referer) {
            return 403;
        }
    }

    # 维护页面
    if (-f /var/www/maintenance.html) {
        return 503;
    }
}

⚠️ if 的陷阱（if is evil）：
  Nginx 的 if 不像编程语言的 if
  它属于 rewrite 模块，行为可能不符合预期

  安全用法：
    return、rewrite 指令
  危险用法：
    在 if 里使用 proxy_pass、try_files 等

  建议：能用 location 匹配就不使用 if

十、日志配置

10.1 访问日志

http {
    # 自定义日志格式
    log_format detailed '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent" '
                        '$request_time';

    # 使用自定义格式
    access_log /var/log/nginx/access.log detailed;

    # 某个 location 不记录日志
    location /health {
        access_log off;
        return 200 "ok";
    }
}

10.2 错误日志

1
2
3

# 错误日志级别：debug | info | notice | warn | error | crit | alert | emerg
error_log /var/log/nginx/error.log warn;      # 全局
error_log /var/log/nginx/error.log error;     # 只记录 error 及以上

10.3 日志轮转

# 手动切割日志
mv /var/log/nginx/access.log /var/log/nginx/access.log.$(date +%Y%m%d)
nginx -s reopen

# 用 logrotate 自动管理（大多数系统自带）
# /etc/logrotate.d/nginx
/var/log/nginx/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 0640 www-data adm
    sharedscripts
    postrotate
        [ -f /run/nginx.pid ] && kill -USR1 $(cat /run/nginx.pid)
    endscript
}

十一、Docker Compose 示例

# docker-compose.yml
version: '3.8'

services:
  nginx:
    image: nginx:1.26
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf:/etc/nginx
      - ./html:/usr/share/nginx/html
      - ./logs:/var/log/nginx
    restart: always
    networks:
      - web

networks:
  web:
    external: true

目录结构：
  docker-compose.yml
  conf/
  ├── nginx.conf
  ├── conf.d/
  │   ├── site-a.conf
  │   └── site-b.conf
  └── mime.types
  html/
  ├── site-a/
  └── site-b/
  logs/

十二、小结

本文学习了 Nginx 的基础：

Nginx 是什么和为什么选择 Nginx
安装方式（Linux、Docker、Windows）
常用命令（启动、停止、重载、检查）
配置文件结构和层级关系
静态文件托管和 try_files
虚拟主机（基于域名、端口、IP）
location 匹配规则和优先级
常用变量和 rewrite 规则
日志配置和轮转

下一篇将学习反向代理与负载均衡。