1006 lines
29 KiB
Markdown
1006 lines
29 KiB
Markdown
---
|
||
tags: [tech, infrastructure, web-server, proxy]
|
||
create time: 2026-05-18 20:30
|
||
---
|
||
|
||
# Nginx
|
||
|
||
## 概述
|
||
|
||
Nginx（读作 "engine-x"）是一个高性能的 **HTTP 服务器**和**反向代理服务器**，同时也支持 IMAP/POP3/SMTP 协议。由 Igor Sysoev 开发，以其高并发、低内存消耗闻名。
|
||
|
||
> [!QUESTION] 为什么选择 Nginx？
|
||
> - **异步事件驱动架构**：能轻松支撑数万并发连接
|
||
> - **轻量级**：处理静态文件只需 Apache 1/5 的内存
|
||
> - **热部署**：配置文件修改后可无缝 reload，不中断现有请求
|
||
> - **生态成熟**：大量第三方模块和社区方案
|
||
|
||
核心用途：**反向代理**、**负载均衡**、**静态资源服务**、**SSL/TLS 终止**、**API 网关**。
|
||
|
||
## 安装
|
||
|
||
### 主流方式
|
||
|
||
| 方式 | 适用场景 | 命令示例 |
|
||
|------|---------|---------|
|
||
| 系统包管理器 | 快速部署、稳定优先 | `sudo apt install nginx` / `sudo yum install nginx` |
|
||
| 官方仓库 | 需要最新版本 | 添加 `nginx.org` 源后安装 |
|
||
| Docker | 容器化部署 | `docker run -d --name nginx -p 80:80 nginx:alpine` |
|
||
| 源码编译 | 需要自定义模块 | `./configure --with-http_ssl_module && make && sudo make install` |
|
||
|
||
> [!TIP] 生产环境推荐
|
||
> 使用官方仓库或 Docker Alpine 镜像，体积小且更新及时。开发环境直接用系统包管理器即可。
|
||
|
||
### 验证安装
|
||
|
||
```bash
|
||
nginx -v # 查看版本
|
||
nginx -t # 测试配置语法
|
||
systemctl status nginx # 查看服务状态
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### 架构模型
|
||
|
||
```mermaid
|
||
graph LR
|
||
Master["Master Process 管理进程"] --> WorkerA["Worker Process 1 处理请求"]
|
||
Master --> WorkerB["Worker Process 2 处理请求"]
|
||
Master --> WorkerC["Worker Process 3 处理请求"]
|
||
WorkerA --> Conn1["Connection A"]
|
||
WorkerA --> Conn2["Connection B"]
|
||
WorkerB --> Conn3["Connection C"]
|
||
WorkerB --> Conn4["Connection D"]
|
||
WorkerC --> Conn5["Connection E"]
|
||
style Master fill:#f9d,stroke:#333
|
||
style WorkerA fill:#ccf,stroke:#333
|
||
style WorkerB fill:#ccf,stroke:#333
|
||
style WorkerC fill:#ccf,stroke:#333
|
||
```
|
||
|
||
Nginx 采用 **Master-Worker 多进程模型**：
|
||
|
||
- **Master 进程**：负责读取配置、管理 Worker、平滑重载
|
||
- **Worker 进程**：每个 Worker 独立运行，用**事件驱动**方式处理请求。一个请求不会在其他 Worker 中排队
|
||
|
||
> [!NOTE] 关键问题
|
||
> 为什么不用多线程？因为线程切换开销大、锁竞争严重。Nginx 的事件驱动模型（epoll/kqueue）在 Linux/BSD 上能做到单个 Worker 处理上万并发连接，这就是著名的 **"C10K 问题"**解决方案之一。
|
||
|
||
### 配置文件结构
|
||
|
||
主配置文件通常是 `/etc/nginx/nginx.conf`，采用**嵌套块结构**：
|
||
|
||
```nginx
|
||
# 全局块
|
||
worker_processes auto; # Worker 数量（auto = CPU 核数）
|
||
error_log /var/log/nginx/error.log warn;
|
||
|
||
events { # events 块
|
||
worker_connections 1024; # 每个 Worker 的最大连接数
|
||
}
|
||
|
||
http { # http 块
|
||
include mime.types;
|
||
default_type application/octet-stream;
|
||
sendfile on;
|
||
|
||
# upstream 块 — 定义后端服务器池
|
||
upstream backend {
|
||
server 127.0.0.1:8080;
|
||
}
|
||
|
||
server { # server 块 — 虚拟主机
|
||
listen 80;
|
||
server_name example.com;
|
||
|
||
location / { # location 块 — URL 匹配路由
|
||
proxy_pass http://backend;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
配置文件加载顺序：**全局块 → events 块 → http 块 → server 块 → location 块**。外层指令对内层生效（继承关系）。
|
||
|
||
## 常用配置实战
|
||
|
||
### 1. 反向代理
|
||
|
||
最经典的用法——将客户端请求转发到后端服务。
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name api.example.com;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3000;
|
||
|
||
# 必须传递的信息头
|
||
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;
|
||
|
||
# WebSocket 支持
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
|
||
# ── Proxy Buffering（缓冲控制）──
|
||
proxy_buffering on; # 默认开启，先接收后端完整响应再发给客户端
|
||
proxy_buffer_size 4k; # 第一块缓冲区大小（通常存响应头）
|
||
proxy_buffers 8 4k; # 后续缓冲区数量和大小
|
||
proxy_busy_buffers_size 8k; # 忙缓冲区（一边发客户端一边收后端）
|
||
# proxy_buffering off; # 关闭缓冲 = 流式转发，适合 SSE/WebSocket
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!NOTE] 反向代理 vs 正向代理
|
||
> - **正向代理**：代理**客户端**，帮内网用户访问外网（如 VPN）
|
||
> - **反向代理**：代理**服务端**，对外隐藏后端真实地址（Nginx 的主要角色）
|
||
|
||
> [!NOTE] Proxy Buffering 工作原理
|
||
> ```mermaid
|
||
> sequenceDiagram
|
||
> participant Client as 客户端
|
||
> participant Nginx as Nginx (Buffer)
|
||
> participant Backend as 后端服务
|
||
> Client->>Nginx: 请求
|
||
> Nginx->>Backend: 转发请求
|
||
> Backend-->>Nginx: 响应数据写入 Buffer
|
||
> Note over Nginx: 整个响应写完后...
|
||
> Nginx-->>Client: 从 Buffer 发送给客户端
|
||
> alt buffering off
|
||
> Nginx-->>Client: 实时转发 (Stream)
|
||
> end
|
||
> ```
|
||
> - **开启 buffering**（默认）：后端可以先完成处理再发送，Nginx 承担内存压力，提升吞吐
|
||
> - **关闭 buffering**：实时转发，内存占用低但要求后端尽快返回；适合 SSE、大文件下载
|
||
|
||
#### Proxy Cache — 反向缓存
|
||
|
||
Nginx 还可以作为**反向缓存代理**，将后端的响应缓存在本地磁盘。
|
||
|
||
```nginx
|
||
http {
|
||
# 定义缓存区域
|
||
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app_cache:10m
|
||
max_size=1g inactive=60m use_temp_path=off;
|
||
|
||
server {
|
||
location /api/ {
|
||
proxy_pass http://backend;
|
||
|
||
# 启用缓存
|
||
proxy_cache app_cache; # 使用哪个缓存区
|
||
proxy_cache_key "$scheme$request_method$host$request_uri"; # 缓存 key
|
||
proxy_cache_valid 200 302 10m; # 200/302 响应缓存 10 分钟
|
||
proxy_cache_valid 404 1m; # 404 缓存 1 分钟
|
||
proxy_cache_valid any 5m; # 其他状态码缓存 5 分钟
|
||
|
||
# 缓存命中时添加头部（方便调试）
|
||
add_header X-Cache-Status $upstream_cache_status;
|
||
|
||
# 绕过缓存的条件（未登录用户不走缓存）
|
||
proxy_cache_bypass $http_authorization;
|
||
proxy_no_cache $http_authorization;
|
||
|
||
# 过期后仍向客户端提供旧缓存（stale），后台异步刷新
|
||
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
|
||
proxy_cache_background_update on;
|
||
proxy_cache_revalidate on;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
`X-Cache-Status` 返回值说明：
|
||
|
||
| 值 | 含义 |
|
||
|------|------|
|
||
| `HIT` | 缓存命中，直接返回 |
|
||
| `MISS` | 缓存未命中，回源获取并缓存 |
|
||
| `EXPIRED` | 缓存过期，向后端重新验证 |
|
||
| `UPDATING` | 后台正在更新缓存，返回旧版本 |
|
||
| `BYPASS` | 被配置主动跳过 |
|
||
|
||
### 2. 负载均衡
|
||
|
||
当后端有多台服务器时，Nginx 可以将流量分发到不同节点。
|
||
|
||
```nginx
|
||
upstream frontend {
|
||
# 三种常用策略：
|
||
|
||
# 轮询（默认）— 按顺序依次分配
|
||
# server 10.0.0.1:8080;
|
||
# server 10.0.0.2:8080;
|
||
|
||
# 权重 — 数值越大分到的请求越多
|
||
server 10.0.0.1:8080 weight=3;
|
||
server 10.0.0.2:8080 weight=1;
|
||
|
||
# IP Hash — 同一客户端 IP 固定分配到同一台后端
|
||
# ip_hash;
|
||
|
||
# 最少连接 — 分配到当前活跃连接最少的节点
|
||
# least_conn;
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
location / {
|
||
proxy_pass http://frontend;
|
||
}
|
||
}
|
||
```
|
||
|
||
常见策略对比：
|
||
|
||
| 策略 | 适用场景 | 注意 |
|
||
|------|---------|------|
|
||
| **轮询 (round-robin)** | 通用场景 | 各节点性能相近时效果最好 |
|
||
| **加权轮询 (weight)** | 节点性能差异大 | 可根据硬件能力分配权重 |
|
||
| **IP Hash** | 有 Session 粘性需求 | Cookie 登录可能失效 |
|
||
| **最少连接 (least_conn)** | 请求处理时间不均 | 长连接场景需留意偏差 |
|
||
|
||
### 3. 健康检查与后端管理
|
||
|
||
Nginx 社区版提供**被动式**健康检查（通过 fail_timeout 和 max_fails 参数），商业版（Plus）支持主动探测。
|
||
|
||
```nginx
|
||
upstream backend {
|
||
server 10.0.0.1:8080 weight=3 max_fails=3 fail_timeout=30s;
|
||
server 10.0.0.2:8080 weight=1 max_fails=3 fail_timeout=30s;
|
||
|
||
# 标记为 down — 不参与任何流量（常用于灰度发布逐步放量）
|
||
# server 10.0.0.3:8080 down;
|
||
|
||
# max_conns — 限制分配到该节点的并发数，超限时返回错误
|
||
# server 10.0.0.4:8080 max_conns=100;
|
||
|
||
# keepalive — 保持与后端的长连接，避免频繁建连开销
|
||
keepalive 32; # 每个 Worker 最多保持的空闲连接数
|
||
keepalive_timeout 60s;
|
||
keepalive_requests 100;
|
||
}
|
||
```
|
||
|
||
> [!NOTE] passive health check 机制
|
||
> `max_fails=3 fail_timeout=30s` 含义：**在 30 秒内，某个后端失败超过 3 次，则该后端在 30 秒内被剔除**。失败次数计数是从后端恢复后重新累加的。
|
||
|
||
使用 `keepalive` 时需要在 proxy 层做配套设置：
|
||
|
||
```nginx
|
||
http {
|
||
upstream backend {
|
||
server 127.0.0.1:8080;
|
||
keepalive 32;
|
||
}
|
||
|
||
server {
|
||
location / {
|
||
proxy_pass http://backend;
|
||
|
||
# 关键：使用 HTTP/1.1 + Connection 头告诉 Nginx 复用连接
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Connection "";
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!QUESTION] 为什么需要 `proxy_set_header Connection ""`？
|
||
>
|
||
> HTTP/1.0 默认关闭 keepalive，如果后端期望长连接，客户端（Nginx）发送的 `Connection: close` 会导致连接立即关闭，使 `keepalive` 配置形同虚设。清空该头部即可让 TCP 连接持续复用。
|
||
|
||
### 4. 静态文件服务
|
||
|
||
利用 Nginx 处理静态资源的优势，大幅减轻后端压力。
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name cdn.example.com;
|
||
|
||
# 根目录指向
|
||
root /var/www/html;
|
||
index index.html index.htm;
|
||
|
||
# 精确匹配
|
||
location /assets/ {
|
||
expires 30d; # 浏览器缓存 30 天
|
||
add_header Cache-Control "public, immutable";
|
||
gzip_static on; # 提供 .gz 预压缩文件
|
||
}
|
||
|
||
# 错误页面
|
||
error_page 404 /404.html;
|
||
error_page 500 502 503 504 /50x.html;
|
||
}
|
||
```
|
||
|
||
> [!TIP] 静态文件优化要点
|
||
> - **gzip_static on**：如果预先生成了 `.gz` 文件，直接发送，节省 CPU
|
||
> - **sendfile on**：启用内核零拷贝，静态文件传输效率极高
|
||
> - **expires**：合理设置缓存头部，减少重复请求
|
||
|
||
### 5. HTTPS / SSL
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl http2;
|
||
server_name example.com;
|
||
|
||
ssl_certificate /etc/nginx/ssl/cert.pem;
|
||
ssl_certificate_key /etc/nginx/ssl/key.pem;
|
||
|
||
# 推荐的现代 TLS 配置
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
|
||
ssl_prefer_server_ciphers off;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3000;
|
||
}
|
||
}
|
||
|
||
# HTTP → HTTPS 自动跳转
|
||
server {
|
||
listen 80;
|
||
server_name example.com;
|
||
return 301 https://$host$request_uri;
|
||
}
|
||
```
|
||
|
||
> [!NOTE] Let's Encrypt 免费证书
|
||
> 用 Certbot 可以一键申请和续期免费证书：
|
||
> ```bash
|
||
> sudo certbot --nginx -d example.com
|
||
> ```
|
||
> Certbot 会自动帮你写入 Nginx 配置并完成 SSL 设置。
|
||
|
||
### 6. 读写分离 & 限流
|
||
|
||
```nginx
|
||
# 请求速率限制
|
||
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
|
||
|
||
# 连接数限制
|
||
limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
|
||
|
||
server {
|
||
location /api/ {
|
||
limit_req zone=api_limit burst=20 nodelay; # 突发 20 个请求
|
||
limit_conn conn_limit 10; # 每个 IP 最多 10 连接
|
||
|
||
proxy_pass http://backend;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. IP 访问控制
|
||
|
||
通过 `allow` / `deny` 指令实现基于客户端 IP 的白名单和黑名单。
|
||
|
||
```nginx
|
||
# ── 场景 1：管理后台仅允许内网访问 ──
|
||
location /admin/ {
|
||
allow 10.0.0.0/8; # 允许内网段
|
||
allow 192.168.1.0/24; # 允许办公网
|
||
deny all; # 拒绝其余所有 IP
|
||
|
||
proxy_pass http://admin-backend;
|
||
}
|
||
|
||
# ── 场景 2：特定接口封禁恶意 IP ──
|
||
map $remote_addr $blocked_ip {
|
||
default 0;
|
||
192.168.1.100 1; # 已知攻击者
|
||
10.99.0.0/16 1; # 整个 C 段封禁
|
||
}
|
||
|
||
server {
|
||
location / {
|
||
if ($blocked_ip) {
|
||
return 403; # 直接返回，不转发到后端
|
||
}
|
||
|
||
proxy_pass http://backend;
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!TIP] 推荐做法
|
||
> `allow/deny` 是在 Nginx 层面直接拦截（return 403），比让请求到达后端更安全高效。对于大名单封禁场景，使用 `geo` / `map` 模块配合数组匹配更灵活。
|
||
|
||
### 8. HTTP Basic Auth 认证
|
||
|
||
为特定接口添加用户名密码登录。
|
||
|
||
```bash
|
||
# 生成密码文件（首次）
|
||
sudo htpasswd -c /etc/nginx/.htpasswd admin
|
||
# 后续添加用户去掉 -c 参数即可
|
||
sudo htpasswd /etc/nginx/.htpasswd developer
|
||
```
|
||
|
||
```nginx
|
||
location /api/internal/ {
|
||
auth_basic "Restricted Area"; # 弹窗提示标题
|
||
auth_basic_user_file /etc/nginx/.htpasswd;
|
||
|
||
proxy_pass http://backend;
|
||
}
|
||
```
|
||
|
||
## 安全加固
|
||
|
||
生产环境中的 Nginx 是第一道防线，需要做好基础安全设置。
|
||
|
||
```nginx
|
||
http {
|
||
# ── 隐藏版本信息 ──
|
||
server_tokens off; # response header 中不显示 Nginx 版本
|
||
more_clear_headers Server; # 需 headers-more 模块，完全抹除 Server 头
|
||
|
||
# ── 安全响应头 ──
|
||
add_header X-Frame-Options "SAMEORIGIN" always; # 防止点击劫持
|
||
add_header X-Content-Type-Options "nosniff" always; # 禁止 MIME 嗅探
|
||
add_header X-XSS-Protection "1; mode=block" always; # XSS 过滤器
|
||
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||
|
||
# ── HSTS（强制 HTTPS）──
|
||
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
|
||
|
||
# ── CORS 跨域支持 ──
|
||
set $cors_origin "";
|
||
if ($http_origin ~* "^https://(app\.example\.com|cdn\.example\.com)$") {
|
||
set $cors_origin $http_origin;
|
||
}
|
||
|
||
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, X-Requested-With" always;
|
||
|
||
location /api/ {
|
||
# 处理浏览器预检请求 (OPTIONS)
|
||
if ($request_method = OPTIONS) {
|
||
return 204;
|
||
}
|
||
|
||
proxy_pass http://backend;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 防盗链
|
||
|
||
```nginx
|
||
location ~* \.(jpg|jpeg|png|gif|webp|svg|ico)$ {
|
||
root /var/www/static;
|
||
|
||
# valid_referers — 只允许指定域名引用图片
|
||
valid_referers none blocked server_names
|
||
*.example.com example.com;
|
||
|
||
if ($invalid_referer) {
|
||
# 非法引用时返回 403 或一张占位图
|
||
return 403;
|
||
# rewrite ^/ https://example.com/no-hotlink.png break;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 高级特性
|
||
|
||
### Location 匹配优先级
|
||
|
||
```mermaid
|
||
graph TD
|
||
A["URL请求到达"] --> B{"精确匹配\\n^~ ?"}
|
||
B -->|"是"| E["使用精确匹配"]
|
||
B -->|"否"| C{"正则匹配\\n按顺序?"}
|
||
C -->|"第一个匹配"| F["使用正则匹配 \\n立即停止"]
|
||
C -->|"无匹配"| D{"前缀最长匹配\\n是否有^~ ?"}
|
||
D -->|"是"| G["使用前缀匹配 \\n跳过正则"]
|
||
D -->|"否"| H["使用最长前缀匹配"]
|
||
style E fill:#9f9,stroke:#333
|
||
style F fill:#f99,stroke:#333
|
||
style G fill:#9cf,stroke:#333
|
||
style H fill:#ff9,stroke:#333
|
||
```
|
||
|
||
Location 匹配遵循严格优先级：
|
||
|
||
| 优先级 | 类型 | 写法 | 说明 |
|
||
|--------|------|------|------|
|
||
| ① | 精确 | `=` | 完全相等才命中 |
|
||
| ② | 最佳前缀 | `^~` | 最长前缀匹配后立即停止搜索正则 |
|
||
| ③ | 正则 | `~` / `~*` | 按配置文件中的**顺序**匹配，第一个命中就停止 |
|
||
| ④ | 普通前缀 | （无前缀符） | 记录最长匹配，但最终可能被正则覆盖 |
|
||
|
||
```nginx
|
||
location = /exact-match { # ① 精确匹配
|
||
return 200 "exact";
|
||
}
|
||
|
||
location ^~ /static/ { # ② 最佳前缀，跳过正则
|
||
root /var/www;
|
||
}
|
||
|
||
location ~* \.(jpg|png|gif)$ { # ③ 正则，忽略大小写
|
||
expires 7d;
|
||
}
|
||
|
||
location /images { # ④ 普通前缀
|
||
alias /var/www/images;
|
||
}
|
||
```
|
||
|
||
> [!QUESTION] 思考题
|
||
> 请求 `/images/logo.png` 会被哪个 location 处理？
|
||
> - ① `/images` 和普通前缀
|
||
> - ② `~* \.(jpg|png|gif)$` 正则
|
||
>
|
||
> **答案**：②。虽然 `/images` 的前缀更长，但正则匹配的优先级高于普通前缀。只有 `^~` 才能阻止正则匹配。
|
||
|
||
### Gzip 压缩
|
||
|
||
```nginx
|
||
http {
|
||
gzip on;
|
||
gzip_vary on; # 添加 Vary: Accept-Encoding
|
||
gzip_proxied any; # 对所有代理请求都压缩
|
||
gzip_comp_level 6; # 压缩级别 1-9，6 是性价比最优
|
||
gzip_min_length 1k; # 小于 1k 的不压缩
|
||
|
||
gzip_types text/plain text/css application/json application/javascript
|
||
text/xml application/xml application/xml+rss text/javascript
|
||
image/svg+xml; # 需要压缩的内容类型
|
||
}
|
||
```
|
||
|
||
### 日志配置
|
||
|
||
```nginx
|
||
http {
|
||
# 自定义日志格式
|
||
log_format main '$remote_addr - $remote_user [$time_local] '
|
||
'"$request" $status $body_bytes_sent '
|
||
'"$http_referer" "$http_user_agent" '
|
||
'$request_time $upstream_response_time';
|
||
|
||
access_log /var/log/nginx/access.log main;
|
||
error_log /var/log/nginx/error.log warn;
|
||
|
||
# 按小时分割日志
|
||
map $time_iso8601 $logdate {
|
||
~^(\d{4}-\d{2}-\d{2}) %Y-%m-%d;
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!NOTE] 常用变量速查
|
||
> | 变量 | 含义 |
|
||
> |------|------|
|
||
> | `$remote_addr` | 客户端真实 IP |
|
||
> | `$request_uri` | 原始请求 URI（含参数） |
|
||
> | `$status` | 响应状态码 |
|
||
> | `$body_bytes_sent` | 发送给客户端的字节数 |
|
||
> | `$request_time` | 请求处理总耗时（秒） |
|
||
> | `$upstream_response_time` | 后端响应耗时 |
|
||
> | `$http_host` | Host 请求头 |
|
||
> | `$https` | 是否 HTTPS（on/off） |
|
||
|
||
### Stream 模块 — L4 四层代理
|
||
|
||
Nginx 不仅可以代理 HTTP（L7），通过 `stream` 块还可以做 **TCP/UDP 四层负载均衡**。
|
||
|
||
```nginx
|
||
# stream 块在 http 块同级
|
||
stream {
|
||
# SSH 连接到内网跳板机
|
||
upstream ssh_backend {
|
||
server 10.0.0.5:22;
|
||
server 10.0.0.6:22;
|
||
}
|
||
|
||
# Redis / MySQL 等数据库代理
|
||
upstream redis_backend {
|
||
least_conn;
|
||
server 10.0.1.10:6379;
|
||
server 10.0.1.11:6379;
|
||
}
|
||
|
||
server {
|
||
listen 8022; # 对外暴露 SSH 端口
|
||
proxy_pass ssh_backend;
|
||
proxy_timeout 30s;
|
||
}
|
||
|
||
server {
|
||
listen 6379; # 对外暴露 Redis 端口
|
||
proxy_pass redis_backend;
|
||
}
|
||
}
|
||
|
||
http {
|
||
# ... HTTP 配置照常
|
||
}
|
||
```
|
||
|
||
> [!NOTE] Stream vs HTTP
|
||
> | 维度 | `http {}` 块 | `stream {}` 块 |
|
||
> |------|-------------|----------------|
|
||
> | 工作层级 | L7 应用层 | L4 传输层 |
|
||
> | 协议支持 | HTTP、HTTPS | TCP、UDP |
|
||
> | 可解析内容 | URL、Header、Cookie | 无法解析应用数据 |
|
||
> | 典型场景 | Web 代理、静态服务 | SSH/DB 代理、游戏服务器 |
|
||
|
||
### SSI — 服务端包含
|
||
|
||
Nginx 内置 SSI 支持，可以在 HTML 页面中嵌入其他页面的片段。
|
||
|
||
```nginx
|
||
location / {
|
||
ssi on; # 启用 SSI
|
||
ssi_silent_errors on; # 忽略子请求错误，不影响主响应
|
||
root /var/www;
|
||
}
|
||
```
|
||
|
||
HTML 中使用 `<!--#include -->` 指令：
|
||
|
||
```html
|
||
<!--# include virtual="/includes/header.html" -->
|
||
<div class="content">主内容区域</div>
|
||
<!--# include virtual="/includes/footer.html" -->
|
||
```
|
||
|
||
> [!CAUTION] 性能注意
|
||
> SSI 会为每个 include 发起内部子请求，频繁使用会增加响应延迟。现代架构中更推荐前端组件化方案（React/Vue）。仅在遗留系统维护时考虑 SSI。
|
||
|
||
---
|
||
|
||
## 性能调优
|
||
|
||
### 核心参数参考值
|
||
|
||
```nginx
|
||
worker_processes auto; # 等于 CPU 核心数
|
||
|
||
events {
|
||
worker_connections 4096; # 根据预期并发调整
|
||
use epoll; # Linux 默认就是 epoll，可显式指定
|
||
}
|
||
|
||
http {
|
||
sendfile on; # 零拷贝传输静态文件
|
||
tcp_nopush on; # 与 sendfile 配合，减少数据包数量
|
||
tcp_nodelay on; # 禁用 Nagle 算法，降低延迟
|
||
|
||
keepalive_timeout 65; # 保持连接超时
|
||
client_max_body_size 20m; # 上传文件大小限制
|
||
|
||
open_file_cache max=10000 inactive=20s; # 文件描述符缓存
|
||
open_file_cache_valid 30s;
|
||
open_file_cache_min_uses 2;
|
||
}
|
||
```
|
||
|
||
### 调优原则
|
||
|
||
| 方向 | 方法 | 效果 |
|
||
|------|------|------|
|
||
| **并发提升** | `worker_connections` + `worker_processes` | 最大并发 ≈ workers × connections |
|
||
| **I/O 优化** | `sendfile` + `tcp_nopush` | 静态文件传输减少 30%~50% |
|
||
| **连接复用** | `keepalive_timeout` + `proxy_keepalive` | 减少 TCP 握手开销 |
|
||
| **磁盘 I/O** | `open_file_cache` | 避免频繁打开文件描述符 |
|
||
|
||
## 故障排查
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 查看 Nginx 进程信息
|
||
ps aux | grep nginx
|
||
|
||
# 重新加载配置（零停机）
|
||
sudo nginx -s reload
|
||
|
||
# 测试配置文件语法
|
||
sudo nginx -t
|
||
|
||
# 查看监听端口
|
||
sudo ss -tlnp | grep nginx
|
||
|
||
# 实时查看错误日志
|
||
sudo tail -f /var/log/nginx/error.log
|
||
|
||
# 检查配置中包含的所有 server_name
|
||
grep -r server_name /etc/nginx/
|
||
```
|
||
|
||
### 常见问题速查
|
||
|
||
> [!ERROR] 502 Bad Gateway
|
||
> **原因**：后端服务未启动或无法连接。
|
||
> **排查**：确认后端服务正常运行；检查 `proxy_pass` 的地址和端口；查看后端日志。
|
||
|
||
> [!ERROR] 504 Gateway Timeout
|
||
> **原因**：后端响应超时（默认 60 秒）。
|
||
> **解决**：增加 `proxy_read_timeout`，或优化后端查询性能。
|
||
> ```nginx
|
||
> proxy_connect_timeout 5s;
|
||
> proxy_send_timeout 10s;
|
||
> proxy_read_timeout 60s;
|
||
> ```
|
||
|
||
> [!ERROR] 413 Request Entity Too Large
|
||
> **原因**：上传文件超过 `client_max_body_size`。
|
||
> **解决**：在对应 location 中增大限制。
|
||
> ```nginx
|
||
> client_max_body_size 100m;
|
||
> ```
|
||
|
||
> [!WARNING] 403 Forbidden（静态文件）
|
||
> **常见原因**：权限不足或 `index` 文件不存在。
|
||
> **解决**：确认 Nginx 用户（`www-data`/`nginx`）对目录有读权限；确认文件存在。
|
||
|
||
## 配置管理与部署
|
||
|
||
### 配置文件拆分
|
||
|
||
生产环境中，不建议把所有配置写在一个大文件中。利用 `include` 实现模块化拆分。
|
||
|
||
```
|
||
/etc/nginx/
|
||
├── nginx.conf # 主配置（全局 + events + http）
|
||
├── conf.d/
|
||
│ ├── api.conf # API 代理配置
|
||
│ ├── web.conf # Web 前端配置
|
||
│ └── static.conf # 静态资源服务配置
|
||
├── sites-available/ # 可用站点配置（软链到 enabled）
|
||
│ ├── example.com
|
||
│ └── staging.example.com
|
||
├── sites-enabled/ # 已启用站点
|
||
├── upstream/
|
||
│ ├── backend-pool.conf # 后端服务器池定义
|
||
│ └── cache.conf
|
||
├── snippets/ # 可复用片段
|
||
│ ├── ssl-params.conf # SSL 安全参数
|
||
│ ├── rate-limit.conf # 限流规则
|
||
│ └── security-headers.conf
|
||
└── mime.types
|
||
```
|
||
|
||
```nginx
|
||
# nginx.conf — 主入口保持精简
|
||
worker_processes auto;
|
||
pid /run/nginx.pid;
|
||
error_log /var/log/nginx/error.log warn;
|
||
|
||
events { worker_connections 1024; }
|
||
|
||
http {
|
||
include /etc/nginx/mime.types;
|
||
default_type application/octet-stream;
|
||
|
||
# 引入所有 upstream 定义
|
||
include /etc/nginx/upstream/*.conf;
|
||
|
||
# 引入所有 server 配置
|
||
include /etc/nginx/conf.d/*.conf;
|
||
include /etc/nginx/sites-enabled/*;
|
||
}
|
||
```
|
||
|
||
> [!TIP] 为什么这样设计？
|
||
> - `conf.d/` 下的 `.conf` 文件按功能划分，每个文件一个主题
|
||
> - `sites-available` / `sites-enabled` 模式源自 Apache：修改后通过 `ln -s` 启用，方便回滚
|
||
> - `snippets/` 存放通用模板，避免多处复制粘贴同一份 SSL 或安全配置
|
||
|
||
### Docker Compose 完整示例
|
||
|
||
用 Docker Compose 一键拉起 Nginx + 后端服务的开发环境。
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
services:
|
||
nginx:
|
||
image: nginx:alpine
|
||
ports:
|
||
- "80:80"
|
||
- "443:443"
|
||
volumes:
|
||
- ./nginx/conf.d:/etc/nginx/conf.d:ro
|
||
- ./nginx/certs:/etc/nginx/certs:ro
|
||
- ./frontend/dist:/usr/share/nginx/html:ro
|
||
- nginx-cache:/var/cache/nginx
|
||
- nginx-run:/var/run
|
||
depends_on:
|
||
- api
|
||
- webapp
|
||
restart: unless-stopped
|
||
|
||
api:
|
||
build: ./api
|
||
environment:
|
||
- NODE_ENV=production
|
||
- DATABASE_URL=${DATABASE_URL}
|
||
expose:
|
||
- "3000"
|
||
restart: unless-stopped
|
||
|
||
webapp:
|
||
build: ./webapp
|
||
expose:
|
||
- "8080"
|
||
restart: unless-staged
|
||
|
||
volumes:
|
||
nginx-cache:
|
||
nginx-run:
|
||
```
|
||
|
||
```nginx
|
||
# nginx/conf.d/default.conf
|
||
upstream api_backend {
|
||
server api:3000;
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
server_name _;
|
||
|
||
location /api/ {
|
||
proxy_pass http://api_backend;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
|
||
location / {
|
||
root /usr/share/nginx/html;
|
||
try_files $uri $uri/ /index.html; # SPA 路由兜底
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!NOTE] Docker Nginx 注意事项
|
||
> - 挂载配置时使用 `:ro` 只读标志，防止容器内被篡改
|
||
> - `/var/run` 和 `/var/cache/nginx` 需要用 volume，否则重载时会因缺少 pid 文件而报错
|
||
> - SPA 应用需要 `try_files` 兜底到 `index.html`，否则直接刷新子路由会 404
|
||
|
||
### 灰度发布（Canary Release）
|
||
|
||
Nginx 可以实现基于权重或客户端特征的渐进式流量切分。
|
||
|
||
```nginx
|
||
http {
|
||
# 基于请求头实现灰度（前端在特定版本时携带 x-canary: true）
|
||
map $http_x_canary $canary_upstream {
|
||
default "";
|
||
"true" canary_group;
|
||
}
|
||
|
||
# 基于用户 IP 的哈希分流（同一 IP 始终访问同一版本）
|
||
geo $hash_upstream {
|
||
default production_pool;
|
||
10.0.0.0/8 canary_group; # 仅内部 IP 走新版
|
||
}
|
||
|
||
upstream production_pool {
|
||
server 10.1.0.1:8080;
|
||
server 10.1.0.2:8080;
|
||
}
|
||
|
||
upstream canary_group {
|
||
server 10.2.0.1:8080; # 新版本仅一台机器测试
|
||
}
|
||
|
||
server {
|
||
location / {
|
||
# 优先使用 header 分流，其次 IP hash，最后默认生产
|
||
set $target $canary_upstream;
|
||
if ($target = "") {
|
||
set $target $hash_upstream;
|
||
}
|
||
if ($target = "") {
|
||
set $target production_pool;
|
||
}
|
||
|
||
proxy_pass http://$target;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> [!TIP] 灰度发布常见策略
|
||
> | 阶段 | 流量分配 | 适用场景 |
|
||
> |------|---------|---------|
|
||
> | **内部测试** | 100% 内部 IP → 新版 | 开发团队自测 |
|
||
> | **小流量灰度** | 1% ~ 5% 随机 → 新版 | 验证核心指标 |
|
||
> | **逐步放量** | 逐步提升 10% → 50% → 100% | A/B 结果良好 |
|
||
> | **全量上线** | 100% → 新版 | 灰度结束 |
|
||
|
||
### NJS — Nginx JavaScript 脚本
|
||
|
||
Nginx 支持嵌入 JavaScript 代码，实现动态配置逻辑（无需 reload）。
|
||
|
||
```bash
|
||
# 安装 njs 模块
|
||
apt install nginx-module-njs # Debian/Ubuntu
|
||
```
|
||
|
||
```nginx
|
||
# 加载 JS 脚本
|
||
load_module /usr/lib/nginx/modules/ngx_http_js_module.so;
|
||
|
||
http {
|
||
js_import filter.js;
|
||
|
||
server {
|
||
location / {
|
||
js_content filter.add_custom_header;
|
||
proxy_pass http://backend;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
```javascript
|
||
// filter.js
|
||
export function addCustomHeader(r) {
|
||
r.headersOut["X-Custom-Version"] = "v2.1";
|
||
r.headersOut["X-Served-By"] = r.serverName;
|
||
r.sendHeader();
|
||
r.finish();
|
||
}
|
||
|
||
export default { addCustomHeader };
|
||
```
|
||
|
||
> [!NOTE] NJS vs OpenResty
|
||
> - **NJS**：轻量级，适合简单逻辑（改 Header、条件路由），语法受限但性能极高
|
||
> - **OpenResty**（Nginx + Lua）：完整的编程平台，可以操作数据库、调用外部 API，适合复杂网关场景
|
||
|
||
---
|
||
|
||
## 与 CDN 的配合
|
||
|
||
典型的生产架构中，Nginx 常作为 **边缘节点** 或 **回源层** 与 CDN 配合工作：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as 客户端
|
||
participant CDN as CDN 边缘节点
|
||
participant Nginx as Nginx 边缘/回源
|
||
participant App as 应用后端
|
||
|
||
Client->>CDN: 请求静态资源
|
||
CDN->>CDN: 缓存命中？
|
||
alt 命中
|
||
CDN-->>Client: 返回缓存内容
|
||
else 未命中
|
||
CDN->>Nginx: 回源请求
|
||
Nginx->>App: 转发请求
|
||
App-->>Nginx: 响应数据
|
||
Nginx-->>CDN: 返回内容并缓存
|
||
CDN-->>Client: 返回内容
|
||
end
|
||
```
|
||
|
||
> [!TIP] Nginx + CDN 的最佳实践
|
||
> - 静态资源走 CDN，动态请求回源到 Nginx + 后端
|
||
> - Nginx 可以作为 CDN 的边缘服务器，做一层统一入口
|
||
> - 通过 `X-Forwarded-For` 追踪真实的用户 IP（即使经过了 CDN）
|
||
|
||
## 关联笔记
|
||
|
||
- [[hhs/DEV/Docker/Docker.md]]
|
||
- [[hhs/DEV/Linux/Linux.md]]
|