共计 3188 个字符,预计需要花费 8 分钟才能阅读完成。
执行 nginx -s reload 后,如果 master 在检查配置语法或应用新配置时失败,它会回滚更改并继续以旧配置工作;这时不要按“成功 reload 后旧 worker 优雅退出”的路径去理解进程状态。本文讨论默认 master/worker 模型下的配置重载,不适用于 master_process off 这种面向开发者的运行方式(Core functionality)。control 文档把 HUP 描述为更改配置:master 先检查语法,再尝试打开日志文件和新监听套接字;失败回滚,成功才启动新 worker 并请求旧 worker 优雅关闭(Controlling nginx)。命令行 -s reload 表达的也是重新加载配置、以新配置启动新 worker、优雅关闭旧 worker 的语义(Command-line parameters)。
关键边界在于:失败回滚时旧 worker 是否继续接受新连接,文档没有展开。下面先看 master 的回滚发生在哪一步,再区分成功路径下旧 worker 的行为,最后给出回滚后的核对顺序。
失败回滚发生在哪一步
按 control 文档,HUP 到达 master 后,master 先检查配置语法,然后尝试应用新配置,也就是打开日志文件和新监听套接字。如果这一步失败,master 回滚更改并继续以旧配置工作;只有应用成功,才会启动新 worker,并向旧 worker 发送消息请求其优雅关闭(Controlling nginx)。因此,“回滚”的核心是运行时更改被撤回,master 仍按旧配置继续工作,而不是进入新配置的启动流程。
命令行 -t 是 reload 前的前置检查:它检查配置语法,并尝试打开配置中引用的文件;-T 与 -t 相同,但额外把配置文件转储到标准输出,该参数从 1.9.2 起提供(Command-line parameters)。这能提前暴露语法和文件可打开性问题,但不要把“测试通过”等同于“reload 必然成功”。control 文档把打开日志文件和新监听套接字列为应用新配置的步骤,而文档没有逐项说明 -t 是否覆盖所有监听绑定条件。
定位 master 时,先看 pid 指令指定的文件。该指令定义存放主进程 PID 的文件,默认值是 logs/nginx.pid;control 文档给出的默认路径是 /usr/local/nginx/logs/nginx.pid,并说明可在配置时或通过 pid 指令修改(Core functionality、Controlling nginx)。命令行 -s 是向 master 发送信号,PID 文件指错时,后续检查也会偏离对象。
| 观察点 | 成功 reload | master 应用新配置失败 |
|---|---|---|
| master | 启动新 worker,请求旧 worker 优雅关闭 | 回滚更改,继续旧配置 |
| 旧 worker | 关闭监听套接字,继续服务旧客户端,服务完退出 | 文档未说明是否被关闭,或是否继续接受新连接 |
| 新配置 | 由新 worker 承载 | 不生效,旧配置继续 |
表中的成功路径来自 control 文档对 HUP 成功后的描述;失败列里的“文档未说明”是边界,不能据此推断旧 worker 一定继续接受新连接。
旧 worker 的“继续工作”只适用于成功路径
成功 reload 后,旧 worker 会关闭监听套接字,但继续服务旧客户端;等所有旧客户端都被服务完,旧 worker 才退出(Controlling nginx)。官方示例中,旧 worker 会短暂显示为 worker process is shutting down,随后退出;新 worker 的父进程仍指向同一个 master。这个示例说明的是成功 reload 的过渡状态,不是失败回滚的证据。
如果旧 worker 因长连接等原因退出较慢,可以用 worker_shutdown_timeout 配置优雅关闭超时;该指令从 1.11.11 起提供,时间到期后 nginx 会尝试关闭当前打开的连接以促进关闭(Core functionality)。它控制的是成功路径下旧 worker 的退出节奏,不是 reload 失败时的回滚机制。失败路径下,文档只说明 master 回滚并继续旧配置,没有描述旧 worker 被关闭或新 worker 启动。旧 worker 是否继续接受新连接,仍待核实。
另外两个与 reload 相关的条件也容易混入判断:HUP 在 FreeBSD 和 Linux 上还会跟进时区变化;如果使用 QUIC,control 文档提示在升级或 reload 期间保留已建立的 QUIC 连接应启用 quic_bpf(Controlling nginx)。它们不改变失败回滚的核心结论,但属于同一信号的其他语义。
回滚后按什么顺序核对
- 先确认 PID 文件和 master 进程。读取
pid指令指向的文件,确认 master 仍在。不要仅凭 master PID 不变判断 reload 成功或失败:成功 reload 的官方示例中 master PID 也保持不变(Controlling nginx)。 - 重新测试磁盘上的配置。以下命令是未执行示例,需在能读取 nginx 配置的账户下运行;如果使用
-c YOUR_NGINX_CONF指定替代配置,请把YOUR_NGINX_CONF替换为实际路径,并在测试与 reload 中使用同一路径,否则测试对象不同。-T会输出完整配置,可能包含证书路径等信息,注意终端记录和转发范围。
nginx -t
nginx -T
观察命令是否报告配置测试失败;失败时先修正配置,不要直接再次 reload。测试通过后,再核对应用阶段需要的资源:日志文件路径是否可打开,监听套接字是否可以绑定。control 文档把这两类动作列为应用新配置的一部分;-t 是否覆盖所有监听绑定条件,文档没有逐项说明,因此测试通过仍不是充分条件。
- 修正磁盘配置或恢复备份,再测试,再决定是否 reload。文档描述的是 master 回滚运行时更改并继续旧配置,没有说会还原磁盘上的配置文件;操作上应把磁盘上的配置视为仍需修正的版本。这个判断来自文档对回滚对象的描述,属于操作推断,不是文档明确承诺。
- 查看实际日志。先确认
error_log的日志文件和级别;该指令省略级别时默认使用error,设置某个级别会记录该级别及更严重的消息(Core functionality)。文档没有给出 reload 失败时的固定日志文本,不能靠某个关键字直接下结论。
观察进程时,control 文档在 FreeBSD 上给出的示例命令如下。它是未执行示例,输出字段和可用性随系统而异;其他系统请使用本机可用的进程查看工具,重点看 master PID、worker 的 PPID,以及 worker 命令行是否出现 is shutting down。
ps axw -o pid,ppid,user,%cpu,vsz,wchan,command | egrep '(nginx|PID)'
成功 reload 的官方示例中,旧 worker 会短暂显示 worker process is shutting down,新 worker 的 PPID 指向 master;失败回滚没有对应的进程列表示例,不能据此判断旧 worker 是否接受新连接(Controlling nginx)。
还不能从文档确认的边界
- 失败回滚时旧 worker 是否继续接受新连接:control 文档未说明。
- 回滚时已打开的新日志文件如何处理:control 文档未说明。
- 失败回滚时 master 自身状态变化的更多细节:control 文档未给出。
- reload 失败时错误日志的具体提示:文档没有给出固定格式,应以实际日志为准。
这些边界不影响“master 回滚更改并继续旧配置”这一结论,但会影响对进程状态的断言。实际处理时,先把成功 reload 与失败回滚分开:失败后的基线是 master 继续旧配置工作;先修复磁盘配置,完成 nginx -t,再核对日志路径和监听资源,最后才决定是否再次 reload。不要把重启 nginx 当作默认回滚步骤,文档没有这样描述,重启还会中断现有连接。
常见问题
reload 失败后旧 worker 会被关闭吗?
文档只明确失败时 master 回滚更改并继续旧配置;成功路径才会请求旧 worker 优雅关闭。失败路径下旧 worker 是否被关闭,文档没有展开。
回滚后磁盘上的配置文件会自动恢复吗?
文档描述的是 master 回滚更改并继续旧配置,没有说会改写磁盘上的配置文件。操作上应把磁盘配置视为仍需修正的版本,先修复或恢复备份。
nginx -t 通过就不会 reload 失败吗?
不能这样保证。-t 检查语法并尝试打开配置引用的文件;control 把应用新配置描述为打开日志文件和新监听套接字,失败回滚就在这些步骤失败时发生。文档未逐项说明 -t 是否覆盖所有监听绑定条件。
为什么成功 reload 后还能看到旧 worker?
旧 worker 关闭监听套接字后继续服务旧客户端,全部服务完才退出;官方示例中会显示 worker process is shutting down。这是成功路径,不是失败回滚路径。
引用资料
资料链接仅表示正文使用了该素材,不代表所有结论已独立核验。