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 | |
conf.d/放跨站点共享的指令;sites-available/+sites-enabled/是 Debian/Ubuntu 的惯例,方便"配置先写好、确认后再启用";snippets/放会被多处include的片段,改一处全站生效。
二、nginx.conf 只留骨架
1 | |
include 语法是 include file | mask;,可用于任意配置块,通配符按文件名排序加载。要点:
- 路径写错(文件不存在)会让
nginx -t直接失败,不会静默跳过; - 片段内部不要写
http {}、server {}这类块级结构,除非你确实在对应层级 include; - 同名指令在多处出现时,遵循 Nginx 的继承规则(子级定义则不继承父级,
add_header是典型)。
三、用 snippets 复用重复配置
snippets/proxy-headers.conf:
1 | |
使用处:
1 | |
这样第 4 篇里的转发头只需维护一份;新增 API 入口直接复用。
四、热重载的原理
改完配置后执行 nginx -s reload(等价于向 master 进程发 HUP),官方文档描述的过程是:
- master 重新读取配置并做语法检查;
- 尝试打开新的日志文件、新的 listen socket;
- 任一步失败 → 回滚,继续用旧配置服务;
- 成功 → 启动一批新 worker,并通知旧 worker 优雅退出:旧 worker 关闭 listen socket,把手上的连接处理完再退出。
所以 reload 的特点:不断连、不丢请求,且配置错误时不会把线上搞挂。
常用命令:
1 | |
五、日志轮转
Nginx 的日志文件句柄不会因 mv 而自动切换,需要 USR1:
1 | |
六、把配置当代码管
- 版本控制:把
/etc/nginx纳入 git,改动有 diff、可回滚; - 上线前校验:部署脚本里先
nginx -t,失败就中止; - 保留回滚点:reload 前备份当前配置目录,异常时
cp回去再 reload; - CI 校验:PR 里跑
nginx -t(可用容器起一个 nginx),把语法错误挡在合并前; - 变更可观测:重载前后对比关键指标(502 率、延迟、错误日志增量)。
七、多站点与默认站点
一个 server {} 对应一个站点,靠 server_name 匹配:
1 | |
- 每个
listen上最多一个default_server; server_name支持精确名、通配符(*.example.com)、正则(~^www\d+\.);- 多个站点共享证书时,确保证书的 SAN 覆盖所有域名。
八、排错
| 现象 | 原因 / 处理 |
|---|---|
nginx -t 报 open() "...conf" failed | include 的文件不存在、路径写错或权限不足 |
| 改了配置但没生效 | 改的文件不在 include 范围内;或改完没 reload |
| 配置互相覆盖 | 用 nginx -T 看合并结果;注意 add_header 定义即不继承 |
| 某站点没起来 | sites-enabled 软链断了;server_name 没匹配 |
| reload 后 502 增多 | 新配置里的 upstream 地址/端口变了;先看 error.log |
| 日志没写进新文件 | mv 后没执行 nginx -s reopen |
参考链接
- Nginx 官方文档:ngx_core_module(include / error_log / pid) ——
include指令的语法与上下文; - Nginx 官方文档:Controlling nginx —— HUP/USR1/USR2/WINCH 信号与重载、日志轮转、热升级流程;
- Nginx 官方文档:ngx_http_core_module(server_name / default_server / listen) —— 站点匹配规则;
- Nginx 官方文档:ngx_http_upstream_module —— upstream 应放在 http 块;
- 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
