Nginx 核心配置指南：从模块化到 HTTP/3

2025-08-17

从基础的模块化配置，到反向代理、WebDAV 服务的实战部署，再到前沿的 QUIC & HTTP/3 详解。本文通过逐行注释的方式，为你提供一份结构清晰、内容现代的 Nginx 核心配置指南，助你轻松驾驭 Nginx。

1 全局配置与 Events 模块

Nginx 的配置文件通常以全局设置开始，定义了服务器的基础运行参数。

1
2
3
4
5
6
user  www-data;
worker_processes 4;

events {
    worker_connections  1024;
}
  • user www-data: 指定 Nginx 工作进程的运行用户和用户组。
  • worker_processes 4: 设置工作进程的数量，通常建议设置为 CPU 的核心数。
  • events { ... }: 配置与网络连接处理相关的参数。
  • worker_connections 1024: 定义了每个工作进程可以处理的最大并发连接数。

2 HTTP 模块配置

http 模块是 Nginx 配置的核心部分，用于处理所有与 HTTP 协议相关的服务。

2.1 HTTP 全局配置

这部分定义了 HTTP 模块的全局配置，其中包含了 SSL、Gzip 压缩、代理头部等通用参数。将这些配置放在这里，可以被该 http 块中所有的 server 块继承，从而避免重复配置，并确保了配置的一致性。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
http {
    # ================== 基础设置 ==================
    # 引用外部的 MIME 类型定义文件，让 Nginx 能识别如 .css, .js, .jpg 等文件类型
    include       mime.types;
    # 如果找不到匹配的 MIME 类型，则使用此默认类型，告知浏览器这是一个二进制文件
    default_type  application/octet-stream;
    # 安全设置：关闭在错误页面和响应头中显示 Nginx 版本号，防止信息泄露
    server_tokens off;

    # ================== 性能优化 ==================
    # 开启高效文件传输模式，减少内核和用户空间之间的数据拷贝
    sendfile        on;
    # 防止网络阻塞，将多个小数据包组合成一个大的数据包一次性发送
    tcp_nopush      on;
    # 客户端连接保持活动的超时时间，单位是秒
    keepalive_timeout  65;
    # 开启 Gzip 压缩，可以显著减小传输文件的大小，加快网站加载速度
    gzip  on;

    # ================== 通用SSL设置 ==================
    # 定义默认的 SSL 证书文件路径
    ssl_certificate /etc/nginx/ssl/example.com.cer;
    # 定义默认的 SSL 证书私钥文件路径
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    # SSL 会话的超时时间，客户端可以在此时间内重用会话，加快后续连接速度
    ssl_session_timeout 60m;
    # 启用安全的 TLS 协议版本，禁用老旧不安全的 SSLv3 等版本
    ssl_protocols TLSv1.2 TLSv1.3;
    # 定义服务器支持的加密算法套件，这是一个推荐的安全配置，优先使用椭圆曲线算法
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
    # 优先使用服务器端定义的加密算法，而不是客户端的
    ssl_prefer_server_ciphers on;
    # 设置 SSL 会话缓存，可以存储 10MB 的会话信息，有助于提高性能
    ssl_session_cache shared:SSL:10m;
    # 当客户端使用 HTTP 访问 HTTPS 端口时（错误码 497），自动通过 301 重定向到正确的 HTTPS 地址
    error_page 497 301 https://$http_host$request_uri;

    # ================== 通用反向代理头部设置 ==================
    # 当 Nginx 作为反向代理时，这些头部设置非常重要，
    # 它们将客户端的真实信息传递给后端的应用程序。
    # 传递客户端的真实 IP 地址
    proxy_set_header X-Real-IP $remote_addr;
    # 传递完整的客户端 IP 地址链
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    # 传递客户端请求的原始域名
    proxy_set_header Host $http_host;
    # 传递客户端请求使用的协议（http 或 https）
    proxy_set_header X-Forwarded-Proto $scheme;
    # 为 WebSocket 连接设置的头部
    proxy_set_header Upgrade $http_upgrade;
    # 为 WebSocket 连接设置的头部
    proxy_set_header Connection 'upgrade';

    # ================== 加载模块化配置 ==================
    # 这是实现模块化的关键，Nginx 会读取并加载指定目录下所有以 .conf 结尾的文件
    include /etc/nginx/conf.d/*.conf;
    # 另一种常见的风格是使用 sites-enabled 目录
    # include /etc/nginx/sites-enabled/*;
}

最后，也是最关键的一步，为了真正激活模块化配置，你需要在这个 http 块的末尾（紧跟在右花括号 } 之后，或者在 http 块内部的末尾），使用 include 指令来加载所有独立的网站配置文件。这通常是这样配置的：

1
2
3
4
5
# 加载 conf.d 目录下所有以 .conf 结尾的配置文件
include /etc/nginx/conf.d/*.conf;

# 另一种常见的风格是使用 sites-enabled 目录
# include /etc/nginx/sites-enabled/*;

通过这行指令，Nginx 就会读取 conf.d 目录下的所有 .conf 文件，并将它们的内容合并到主配置中。这样，你的每个网站都可以拥有一个独立的配置文件，大大方便了管理。

2.2 反向代理服务示例

反向代理是 Nginx 最常见的用途之一。你可以把它想象成一个”接待员”，它接收来自客户端的请求，然后根据规则将请求转发给内部网络中一台或多台真正的业务服务器，并将后端服务器的响应再返回给客户端。这样做的好处有很多，比如隐藏后端服务器的真实 IP、实现负载均衡、以及集中处理 SSL 加密等。

下面是一个典型的反向代理配置，它将所有对 example.com 的 HTTPS 请求，都转发到内网的 192.168.1.10:8080 这台服务器上。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
server {
    # 监听 443 端口，用于 HTTPS 流量
    listen       443    ssl;
    # 同时监听 IPv6 地址的 443 端口
    listen  [::]:443    ssl;
    # 在此 server 块中启用 HTTP/2 协议
    http2 on;

    # --- 服务器名称 ---
    # 绑定域名，Nginx 会根据请求的域名来匹配这个 server 块
    server_name example.com;

    # --- 路由规则 ---
    # location / 表示匹配所有请求路径
    location / {
        # --- 核心指令 ---
        # 将请求转发给后端的真实服务地址
        proxy_pass http://192.168.1.10:8080;
        # 关闭 Nginx 的默认重定向处理，让后端应用自己决定重定向行为
        proxy_redirect off;
        # 设置允许客户端上传文件的最大尺寸，这里设置为 20GB
        client_max_body_size 20000m;
    }
}
  • proxy_pass: 这是反向代理的核心指令，它指定了后端真实服务的地址。
  • client_max_body_size: 这个指令非常实用，它定义了客户端请求中包体的最大允许大小，常用于设置文件上传的大小限制。

2.3 开启 QUIC (HTTP/3)

随着技术的发展，基于 UDP 的 QUIC 协议和 HTTP/3 正在逐步普及，它们能有效改善连接建立速度和网络切换时的体验。Nginx 从 1.25.0 版本开始正式支持 QUIC 和 HTTP/3。

开启 HTTP/3 的配置与 HTTP/2 略有不同，它需要在 listen 指令中明确启用 quic 参数，并添加一个 Alt-Svc 头部来告知浏览器此站点支持 HTTP/3。

下面是一个同时支持 TLSv1.3 (for TCP) 和 HTTP/3 (for QUIC) 的 listen 配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
server {
    # --- TCP 监听 (for HTTP/1.1 & HTTP/2) ---
    # 这是传统的 TCP 监听，为不支持 HTTP/3 的老客户端提供服务。
    # 在这里使用 `listen ... http2` 的写法，是为了明确定义这条 TCP 链路上的协议。
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    # --- UDP 监听 (for HTTP/3) ---
    # 这是为 QUIC/HTTP/3 准备的 UDP 监听。
    # `reuseport` 参数允许多个工作进程监听同一个端口，提高性能。
    listen 443 quic reuseport;
    listen [::]:443 quic reuseport;

    server_name example.com;

    # --- 关键头部 ---
    # 添加 Alt-Svc (Alternative Services) 头部，
    # 这是一个 HTTP 响应头，用来告知浏览器："嘿，除了 TCP，你还可以通过 UDP 上的 HTTP/3 协议访问我。"
    # h3=":443" 表示 HTTP/3 在 443 端口上可用。
    # ma=2592000 表示此信息让浏览器缓存 30 天 (2592000秒)。
    add_header Alt-Svc 'h3=":443"; ma=2592000';

    # --- SSL 证书 ---
    # QUIC/HTTP/3 同样需要 SSL 证书进行加密
    ssl_certificate /etc/nginx/ssl/example.com.cer;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    # QUIC 协议强制要求使用 TLSv1.3，因此这里只启用它
    ssl_protocols TLSv1.3;

    location / {
        # ... 你的网站配置，例如 proxy_pass ...
    }
}

注意： 开启 QUIC/HTTP/3 有几个前提条件：

  • 你的 Nginx 版本需要是 1.25.0 或更高。
  • 编译 Nginx 时需要加入了 --with-http_v3_module 模块。
  • 服务器的防火墙需要放行 UDP 443 端口的流量。

重点说明：为什么这里又用 listen ... http2 了？

你可能会困惑：为什么在 2.2 节中我们推荐使用 http2 on;，而在这里又用回了 listen ... http2 的写法？这是一个非常棒的问题！

  • 简单场景 (如 2.2): 当你只需要开启 HTTP/2 时，http2 on; 是最简洁的”自动挡”写法。
  • 复杂场景 (如 2.3): 当你需要同时为 HTTP/2 (在 TCP 上) 和 HTTP/3 (在 UDP 上) 提供服务时，你就必须使用 listen ... http2; 这种更精确的”手动挡”写法，来明确告诉 Nginx 每一条”链路”上分别使用什么协议。

所以，这两种写法都是正确的，分别适用于不同的场景。

2.4 WebDAV 服务

WebDAV (Web-based Distributed Authoring and Versioning) 是一个 HTTP 协议的扩展，它允许客户端像管理本地文件一样，对 Web 服务器上的文件进行创建、修改、移动和删除等操作。简单来说，通过 Nginx 开启 WebDAV 服务，你可以将服务器上的一个目录变成一个可以通过网络访问的”网络硬盘”。

以下配置启用了一个功能完善的 WebDAV 服务，并使用密码文件进行身份认证。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
server {
    # 监听一个非标准的 HTTPS 端口 8443，避免与主网站冲突
    listen       8443    ssl;
    listen  [::]:8443    ssl;
    # 在此 server 块中启用 HTTP/2 协议
    http2 on;
    server_name example.com;

    # --- 日志记录 ---
    # 为 WebDAV 服务指定独立的访问日志
    access_log /var/log/nginx/dav_access.log;
    # 为 WebDAV 服务指定独立的错误日志
    error_log /var/log/nginx/dav_error.log;

    location / {
        # --- 基础设置 ---
        # 设置 WebDAV 服务的根目录，即"网络硬盘"的根路径
        root /var/www/webdav;
        # 开启目录列表功能，当访问目录时，会显示文件列表
        autoindex on;

        # --- 身份认证 ---
        # 设置认证提示信息，会显示在浏览器的登录弹窗中
        auth_basic "WebDAV Authentication";
        # 指定用于身份认证的密码文件路径
        auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

        # --- WebDAV 核心指令 ---
        # 设置客户端上传文件的大小限制，0 表示不限制
        client_max_body_size 0;
        # 允许客户端通过 PUT 请求自动创建所有不存在的父目录
        create_full_put_path  on;
        # 定义通过 WebDAV 创建的文件和目录的默认权限 (用户:读写, 组:读写, 其他:只读)
        dav_access user:rw group:rw all:r;
        # 启用 WebDAV 的"写"操作方法，如上传(PUT)、删除(DELETE)、创建目录(MKCOL)等
        dav_methods PUT DELETE MKCOL COPY MOVE;
        # 启用 WebDAV 的扩展方法，用于获取属性(PROPFIND)、锁定(LOCK)等
        dav_ext_methods PROPFIND OPTIONS LOCK UNLOCK;
    }
}
  • dav_methods: 这个指令是开启 WebDAV “写”功能（如上传、删除、创建目录）的关键。如果只读，可以注释掉此行。
  • dav_access: 定义了通过 WebDAV 创建的文件和目录的默认权限。

3 Stream 模块 (TCP 端口转发)

虽然 Nginx 以其强大的 HTTP 功能而闻名，但它同样可以处理 TCP 和 UDP 流量。这是通过 stream 模块实现的。与工作在网络第 7 层 (应用层) 的 http 模块不同，stream 模块工作在第 4 层 (传输层)。这意味着它不关心具体的应用协议（如 HTTP），只负责转发 TCP 连接。因此，stream 模块的配置必须放在 http 模块之外的顶层。

这个功能非常适合用来做端口转发，例如将公网服务器的某个端口映射到内网的 SSH、数据库或远程桌面等服务。

1
2
3
4
5
6
7
8
9
10
stream {
    server {
        listen 2222; # 监听外部端口
        proxy_pass 192.168.1.10:22; # 转发到内网 SSH
    }
    server {
        listen 33890; # 监听外部端口
        proxy_pass 192.168.1.11:3389; # 转发到内网 Win RDP
    }
}

通过这种模块化的配置方式，可以清晰地管理 Nginx 的各项功能，使其在提供高性能 Web 服务的同时，也能满足多样化的网络需求。

总结

本文通过一个结构化的 Nginx 配置实例，全面展示了从基础到进阶的各项核心功能。我们不仅探讨了将配置模块化管理的最佳实践，还深入了几个关键应用场景：

  • HTTP 核心服务: 学习了如何通过反向代理将流量安全地转发给后端应用。
  • 现代协议支持: 掌握了如何配置 Nginx 以同时支持 HTTP/2 和前沿的 QUIC & HTTP/3，提升网站访问速度和体验。
  • 多功能扩展: 了解了如何利用 Nginx 快速搭建一个功能完善的 WebDAV 网络硬盘服务。
  • 超越 HTTP: 最后，我们还探索了 stream 模块的强大能力，实现了在 TCP 层面的端口转发。

将这些功能点进行模块化拆分，不仅使配置结构清晰、易于维护，更能让你在面对复杂需求时，游刃有余地组合和扩展 Nginx 的能力。希望这份指南能为你构建高效、安全、功能丰富的现代网络服务提供坚实的基础。

Nginx Configuration

RELATED POSTS
Nginx 编译及安装第三方模块
Debian 默认安装的 Nginx 对 WebDav 的支持有限，需要重新进行编译和安装第三方功能模块，以下是具体流程 ( 以安装 WebDav 模块为例 )：
Debian, Nginx, WebDav Aug 10 1 min
Debian 设置密钥进行 SSH 连接
使用密钥进行 SSH 连接是一项重要的安全措施，可以降低服务器遭到密码破解的风险，整个过程主要包含以下三个步骤 (以 MacBook 为例) :
Debian, SSH Aug 07 1 min
Hello World
Welcome to Hexo! This is your very first post. Check documentation for more info. If you get any problems when using Hex...
Dec 31 1 min
View More Posts
COMMENTS