wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0eccd338da36f4c79a075b4f2e67f8ecf034ab2f
cs-note/hhs/DEV/Nginx/Nginx.md
T

1006 lines
29 KiB
Markdown
Raw Normal View History

Init
2026-05-24 11:42:38 +08:00
---
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]]
Reference in New Issue Copy Permalink