在 linux 中,nginx 实现不停止服务升级模块的核心做法是:编译包含新模块的 nginx 二进制文件,替换旧的二进制文件,然后向主进程发送 sigusr1 信号。该信号会触发平滑重启流程:主进程记录日志文件名并启动新的工作进程,旧的工作进程处理完当前请求后退出,从而实现无缝升级。

如何编译带有特定动态模块的 Nginx
要添加或升级模块,必须重新编译 Nginx 源码。使用 --add-dynamic-module 参数指定模块源码路径,并通过 --module-type=nginx_http 等参数定义模块类型。编译完成后,生成的 .so 文件即为动态模块库,无需修改主配置文件即可加载。

# 假设源码在 /usr/local/src/nginx-1.24.0 # 进入源码目录 cd /usr/local/src/nginx-1.24.0 # 配置编译选项,注意保留原有配置参数 ./configure \ --prefix=/etc/nginx \ --sbin-path=/usr/sbin/nginx \ --modules-path=/usr/lib64/nginx/modules \ --conf-path=/etc/nginx/nginx.conf \ --error-log-path=/var/log/nginx/error.log \ --http-log-path=/var/log/nginx/access.log \ --with-http_ssl_module \ --add-dynamic-module=/path/to/new/module # 编译并安装(仅安装二进制和模块) make modules sudo make install
上述命令执行后,新的 nginx 二进制文件和 .so 模块文件会被放置到指定目录。此时服务仍在运行旧版本,但新文件已就绪。
如何在运行时加载新模块并平滑重启
加载新模块需要在 nginx.conf 中使用 load_module 指令指向新生成的 .so 文件。随后通过 kill -s SIGUSR1 向 Nginx 主进程发送信号,触发平滑重启。此过程不会中断现有连接,新请求将由加载了新模块的新工作进程处理。

# 1. 编辑 nginx.conf,添加模块加载指令 # 在 http 块之前或全局块中添加: load_module /usr/lib64/nginx/modules/ngx_http_new_module.so; # 2. 检查配置语法是否正确 sudo nginx -t # 3. 如果测试通过,发送 SIGUSR1 信号进行平滑重启 # 首先获取主进程 PID sudo cat /run/nginx.pid # 假设 PID 为 12345 sudo kill -s SIGUSR1 12345 # 4. 验证新模块是否生效 sudo nginx -V 2>&1 | grep -o 'loaded modules:.*' || \ sudo ls /usr/lib64/nginx/modules/ | grep new_module
执行 kill -s SIGUSR1 后,Nginx 主进程会保持运行,旧的工作进程在处理完所有当前请求后优雅退出,新的工作进程启动并加载新模块。整个过程对客户端透明,无服务中断。
升级后如何确认模块已成功加载且服务正常
升级完成后,需验证新模块是否被正确加载以及服务状态是否正常。可以通过检查 Nginx 错误日志、查看工作进程数量变化以及测试模块功能来确认。若出现异常,可通过 nginx -t 快速回滚配置。
首先,检查 /var/log/nginx/error.log,确保没有关于模块加载失败的错误信息。其次,观察工作进程的变化:旧进程应逐渐减少,新进程应稳定增加。最后,使用 curl 或其他工具测试依赖该模块的功能,例如访问一个由新模块处理的 URL,确认返回结果符合预期。若发现模块未生效,可立即停止服务,回滚 nginx.conf 中的 load_module 行,并重新启动 Nginx。


















