Nginx 中 Brotli 压缩如何在升级版本时保障业务零中断且压缩正常

必须先动态编译启用ngx_brotli模块再平滑升级Nginx二进制，确保ABI兼容、模块加载正常、压缩持续生效且业务零中断。

要让 Nginx 在升级版本时既完成 Brotli 支持（或同步更新），又保障业务零中断、压缩持续生效，核心在于模块集成与二进制升级必须分离执行、分步验证。不能一边加模块一边换主程序，否则极易导致 brotli on 报错、worker 崩溃或响应头丢失 Content-Encoding: br。

必须先动态编译 ngx_brotli 模块，再平滑升级 Nginx 二进制

Brotli 不是 Nginx 内置功能，模块加载和主程序版本强耦合。若新旧 Nginx 版本 ABI 不兼容，直接替换二进制会导致动态模块加载失败，即使配置没变，nginx -t 也可能通过，但运行时 worker 启动即退出。

1. 先确认当前 Nginx 已支持 Brotli：运行 nginx -V 2>&1 | grep with-http_brotli_module，有输出才代表模块已编译进当前运行版本
2. 若尚未集成，不要跳过这步直接升级——应先在当前稳定版本上动态编译并启用 ngx_brotli（不重启，仅 reload）：
   1. 安装 libbrotli（./configure --prefix=/usr/local && make install + ldconfig）
   2. 使用原版 nginx -V 输出的 configure 参数，追加 --add-dynamic-module=/path/to/ngx_brotli --with-compat，执行 make（勿 make install）
   3. 将生成的 objs/ngx_http_brotli_filter_module.so 复制到模块目录，并在 nginx.conf 开头添加 load_module modules/ngx_http_brotli_filter_module.so;
   4. nginx -t && nginx -s reload，验证 curl -H "Accept-Encoding: br" -I http://yoursite/ 返回 Content-Encoding: br

升级 Nginx 二进制时，必须用平滑升级流程（USR2 → WINCH → QUIT）

当新版 Nginx（如从 1.24.0 升至 1.26.0）需启用更高 OpenSSL、HTTP/3 或修复安全漏洞时，必须通过信号机制切换，而非 systemctl restart 或 kill -9：

1. 备份旧二进制：cp /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx.old
2. 用完全一致的 configure 参数（包括 --prefix、--modules-path、所有 --with-* 和 --add-dynamic-module）编译新版，确保 .so 模块仍能被识别
3. 覆盖二进制后，发送 kill -USR2 $(cat nginx.pid)：新 master 启动，旧 master 与新 master 并存，worker 继续服务
4. 确认新 master 进程正常、日志无报错后，发 kill -WINCH $(cat nginx.pid.oldbin)：旧 worker 优雅退出，不再接受新连接
5. 待旧 worker 全部消失，再发 kill -QUIT $(cat nginx.pid.oldbin)：终止旧 master

升级后必须验证 Brotli 是否真实生效，而非仅配置存在

平滑升级完成后，模块虽未重载，但新 master 加载的是新二进制+旧模块路径，仍需确认：

1. nginx -V 输出中仍有 with-http_brotli_module（证明新二进制编译时已注入）
2. nginx -t 不报 unknown directive "brotli"（说明语法解析正常）
3. 实际请求返回 Content-Encoding: br，且 Content-Length 明显小于 gzip 或未压缩版本
4. 若启用了 brotli_static on，检查 .br 文件权限（Nginx worker 用户可读）、MIME 类型是否在 brotli_types 中精确匹配（如 application/javascript ≠ text/javascript）

不复杂但容易忽略