Nginx 工程实践 -- 9. 配置组织与热重载

配置少的时候,所有东西塞进 nginx.conf 也能跑;站点一多、团队一多,就会遇到"改一处要通读全文件"“两个人同时改冲突”“上线后发现改错了目录”。把配置按目录约定 + include 片段拆开,再配合 nginx -t + reload 的热重载流程,是 Nginx 运维的基本功。

flowchart TD
    A["nginx.conf"] --> B["include conf.d/*.conf
gzip / ssl / headers"] A --> C["include sites-enabled/*
各站点 server"] C --> D["include snippets/*
复用片段"] A --> E["HUP 热重载
语法检查 → 新 worker → 旧 worker 退出"]

一、目录约定

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/etc/nginx/
├── nginx.conf # 主配置:全局指令 + include
├── mime.types
├── conf.d/ # 全局通用片段(gzip、ssl、安全头等)
│ ├── gzip.conf
│ ├── ssl-common.conf
│ └── security-headers.conf
├── sites-available/ # 所有站点的完整配置(不一定是启用状态)
│ ├── example.com.conf
│ └── api.example.com.conf
├── sites-enabled/ # 软链到 sites-available,被 include 的就是它们
│ └── example.com.conf -> ../sites-available/example.com.conf
└── snippets/ # 可复用片段(proxy 头、upstream 等)
├── proxy-headers.conf
└── letsencrypt.conf
  • conf.d/ 放跨站点共享的指令;
  • sites-available/ + sites-enabled/ 是 Debian/Ubuntu 的惯例,方便"配置先写好、确认后再启用";
  • snippets/ 放会被多处 include 的片段,改一处全站生效。

二、nginx.conf 只留骨架

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
user  nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
worker_connections 1024;
}

http {
include /etc/nginx/mime.types;
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;
keepalive_timeout 65;

include /etc/nginx/conf.d/*.conf; # 全局片段
include /etc/nginx/sites-enabled/*; # 站点
}

include 语法是 include file | mask;,可用于任意配置块,通配符按文件名排序加载。要点:

  • 路径写错(文件不存在)会让 nginx -t 直接失败,不会静默跳过;
  • 片段内部不要写 http {}、server {} 这类块级结构,除非你确实在对应层级 include;
  • 同名指令在多处出现时,遵循 Nginx 的继承规则(子级定义则不继承父级,add_header 是典型)。

三、用 snippets 复用重复配置

snippets/proxy-headers.conf:

1
2
3
4
5
6
7
# 代理转发通用头,供多个 location include
proxy_http_version 1.1;
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_set_header Connection "";

使用处:

1
2
3
4
location /api/ {
proxy_pass http://backend;
include snippets/proxy-headers.conf;
}

这样第 4 篇里的转发头只需维护一份;新增 API 入口直接复用。

四、热重载的原理

改完配置后执行 nginx -s reload(等价于向 master 进程发 HUP),官方文档描述的过程是:

  1. master 重新读取配置并做语法检查;
  2. 尝试打开新的日志文件、新的 listen socket;
  3. 任一步失败 → 回滚,继续用旧配置服务;
  4. 成功 → 启动一批新 worker,并通知旧 worker 优雅退出:旧 worker 关闭 listen socket,把手上的连接处理完再退出。

所以 reload 的特点:不断连、不丢请求,且配置错误时不会把线上搞挂。

常用命令:

1
2
3
4
5
6
nginx -t          # 只检查语法(含 include 的文件都会检查)
nginx -T # 打印合并 include 后的完整配置,排查覆盖/继承问题
nginx -s reload # 平滑重载
nginx -s reopen # 重开日志文件(= USR1),配合日志轮转
nginx -s quit # 优雅退出(等连接处理完)
nginx -s stop # 快速退出

五、日志轮转

Nginx 的日志文件句柄不会因 mv 而自动切换,需要 USR1:

1
2
3
# logrotate 的 postrotate 常见写法
mv /var/log/nginx/access.log /var/log/nginx/access.log.1
nginx -s reopen

六、把配置当代码管

  • 版本控制:把 /etc/nginx 纳入 git,改动有 diff、可回滚;
  • 上线前校验:部署脚本里先 nginx -t,失败就中止;
  • 保留回滚点:reload 前备份当前配置目录,异常时 cp 回去再 reload;
  • CI 校验:PR 里跑 nginx -t(可用容器起一个 nginx),把语法错误挡在合并前;
  • 变更可观测:重载前后对比关键指标(502 率、延迟、错误日志增量)。

七、多站点与默认站点

一个 server {} 对应一个站点,靠 server_name 匹配:

1
2
3
4
5
6
7
8
9
10
11
server {
listen 80 default_server; # 未被任何 server_name 命中的请求落到这里
server_name _;
return 444;
}

server {
listen 80;
server_name example.com;
...
}
  • 每个 listen 上最多一个 default_server;
  • server_name 支持精确名、通配符(*.example.com)、正则(~^www\d+\.);
  • 多个站点共享证书时,确保证书的 SAN 覆盖所有域名。

八、排错

现象原因 / 处理
nginx -t 报 open() "...conf" failedinclude 的文件不存在、路径写错或权限不足
改了配置但没生效改的文件不在 include 范围内;或改完没 reload
配置互相覆盖用 nginx -T 看合并结果;注意 add_header 定义即不继承
某站点没起来sites-enabled 软链断了;server_name 没匹配
reload 后 502 增多新配置里的 upstream 地址/端口变了;先看 error.log
日志没写进新文件mv 后没执行 nginx -s reopen

参考链接

  1. Nginx 官方文档:ngx_core_module(include / error_log / pid) —— include 指令的语法与上下文;
  2. Nginx 官方文档:Controlling nginx —— HUP/USR1/USR2/WINCH 信号与重载、日志轮转、热升级流程;
  3. Nginx 官方文档:ngx_http_core_module(server_name / default_server / listen) —— 站点匹配规则;
  4. Nginx 官方文档:ngx_http_upstream_module —— upstream 应放在 http 块;
  5. Nginx 官方文档:add_header —— "定义即不继承"语义。

小结

  • 用 conf.d/ + sites-available/enabled + snippets/ 分层,主配置只留骨架与 include;
  • 重复片段抽成 snippets/*.conf,多处 include,改一处生效;
  • nginx -t 先过语法,nginx -T 看合并结果,nginx -s reload 平滑生效;
  • reload 失败会自动回滚,这是它比 restart 安全的原因;
  • 把配置纳入 git、CI 校验、留回滚点,是团队化运维的底线。

系列导航


Nginx 工程实践 -- 9. 配置组织与热重载
https://bubao.github.io/posts/f8a6b7c9.html
作者
一念
发布于
2026年11月21日
许可协议