本文旨在提供一份Nginx常用配置的速查手册，覆盖了从基础部署到核心功能配置的重点内容，力求精简实用。

1. 基础设置

Docker部署

使用Docker Compose可以快速启动Nginx。

version: '3.3'
services:
  nginx:
    image: nginx
    container_name: nginx
    network_mode: "host"
    volumes:
      - $PWD/etc/nginx:/etc/nginx/:ro
    restart: unless-stopped

目录结构

一个推荐的配置结构：

  • compose.yaml: Docker Compose文件。
  • nginx.conf: Nginx主配置文件。
  • conf.d/: 存放所有站点配置（例如 default.conf）。
  • cert/: 存放SSL证书文件（.cer, .key）。

2. 主配置文件 nginx.conf

一个精简的nginx.conf，包含了核心配置项。

user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    default_type  application/octet-stream;
    client_max_body_size 100M;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    include /etc/nginx/conf.d/*.conf;
}

3. 常用配置片段

重定向

将HTTP流量或特定域名重定向到HTTPS。

# HTTP (80) 重定向到 HTTPS (443)
server {
    listen 80;
    server_name your.domain.com;
    return 301 https://$server_name$request_uri;
}

# 根域名重定向到子域名
server {
    listen 443 ssl;
    server_name old.domain.com;

    # SSL证书配置...
    ssl_certificate /etc/nginx/cert/your.domain.cer;
    ssl_certificate_key /etc/nginx/cert/your.domain.key;

    return 301 https://new.domain.com$request_uri;
}

反向代理

将请求转发到后端服务。

server {
    listen 443 ssl;
    server_name your.domain.com;

    # SSL证书配置
    ssl_certificate /etc/nginx/cert/your.domain.cer;
    ssl_certificate_key /etc/nginx/cert/your.domain.key;

    location / {
        proxy_pass http://127.0.0.1:8000; # 后端服务地址

        # 转发真实IP和协议信息
        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_pass 指向后端应用地址。
  • proxy_set_header 用于将客户端的原始信息（如域名、IP）传递给后端。
  • WebSocket支持对于需要实时通信的应用（如Alist、在线聊天）至关重要。

4. 核心功能

负载均衡

将流量分发到多个后端服务器，提高可用性。

# 定义上游服务器组
upstream backend_servers {
    # weight: 权重, max_fails: 失败次数, fail_timeout: 失败超时
    server 192.168.1.10:8080 weight=2 max_fails=3 fail_timeout=10s;
    server 192.168.1.11:8080;
    server 192.168.1.12:8080 backup; # 备份服务器
    server 192.168.1.13:8080 down;   # 停用服务器
}

server {
    listen 80;
    server_name your.domain.com;

    location / {
        proxy_pass http://backend_servers;
        proxy_set_header Host $host;
    }
}

关键参数:

  • weight: 数字越大，分配到的请求越多。
  • max_fails 和 fail_timeout: 在fail_timeout时间内失败max_fails次，服务器会被暂停服务fail_timeout秒。
  • backup: 主服务器全部宕机时才启用。
  • down: 永久停用。

请求体大小限制

用于控制客户端上传文件的大小，防止413 Request Entity Too Large错误。

# 可在 http, server, location 块中设置
client_max_body_size 100M; # 限制为100MB
# client_max_body_size 0; # 不限制大小 (慎用)

优先级: location > server > http。建议在需要的 location 或 server 中单独设置，而不是全局取消限制。

5. 调试排查

常用的排查命令：

# 查看错误日志
tail -f /var/log/nginx/error.log

# 检查配置文件语法
nginx -t

# 重新加载配置
nginx -s reload