Nginx升级1.31.9后sticky指令报错的排查
记录时间:2026-11-20
环境:主机 nginx109 / x86_64 / gcc 4.8.5;nginx 1.28.1 升级到 1.31.9;第三方 nginx-sticky-module-1.2.6;OpenSSL 1.1.1w
一、问题现象
nginx2root 这批远程代码执行漏洞出来后,我决定把 nginx 从 1.28.1 升到 1.31.9。1.31.9 的 CHANGES 带了一批安全修复,包括 try_files 与 alias 组合的缓冲区溢出(CVE-2026-125283)、HTTP/2 流控窗口溢出(CVE-2026-123007)、HTTP/2 与 HTTP/3 的 use-after-free(CVE-2026-123633、CVE-2026-121810)等,这个升级躲不掉。
我沿用了现网 1.28.1 的 configure 参数,保留第三方 sticky 模块和 OpenSSL 1.1.1w:
./configure --prefix=/AppHome/nginx --user=nginx --group=nginx \
--with-http_ssl_module --with-http_stub_status_module --with-pcre \
--add-module=/usr/local/src/nginx-sticky-module-1.2.6 \
--with-openssl=/usr/local/src/openssl-1.1.1w \
--with-openssl-opt='enable-tls1_3 enable-weak-ssl-ciphers' \
--with-http_gzip_static_module --with-http_v2_module --with-http_sub_module \
--with-http_realip_module --with-stream --with-stream_ssl_module \
--with-stream_realip_module
make -j$(nproc)
编译通过,objs/nginx -V 也正常。把二进制拷到 /AppHome/nginx/sbin/ 后,./nginx -t 直接失败:
nginx: [emerg] invalid number of arguments in "sticky" directive in /AppHome/nginx/conf/conf.d/upstream.conf:24
nginx: configuration file /AppHome/nginx/conf/nginx.conf test failed
报错内容是参数数量不对,不是 unknown directive "sticky"。这说明新二进制里 sticky 指令是存在的,问题不在模块有没有编进去。
二、排查过程
2.1 先排除二进制和模块
我先确认编出来的到底是不是我以为的那个二进制:
cd /usr/local/src/nginx-1.31.9/objs
./nginx -V
输出里 --add-module=/usr/local/src/nginx-sticky-module-1.2.6 在,版本是 gzeport/1.31.9,OpenSSL 也确实是 1.1.1w。再结合报错是参数数量而不是未知指令,我排除了“模块没编进去”和“拷错二进制”这两个方向。
2.2 看配置本身
接着看报错的第 24 行:
sed -n '20,26p' /AppHome/nginx/conf/conf.d/upstream.conf
看到的是 swtj 这个 upstream 里的 sticky;,零参数。我又数了一遍整个文件,未注释的 sticky; 共 8 处(swtj、sysuser、cas、backed、shipmft、sysuser-singlewindow、airmanifests、open2),#sticky; 的注释行不参与解析。
这里对不上。第三方 1.2.6 的 sticky 指令在源码里是 NGX_CONF_ANY,允许零参数,sticky; 在 1.28.1 上跑了很久都没问题。既然 1.2.6 不会报这个错,说明报错来自另一个模块。
2.3 去翻 1.31.9 的源码
我把 1.31.9 源码解开,先找 sticky 相关文件:
grep -rn 'ngx_string("sticky")' src/
结果除了我加进来的第三方模块,还有一份内置的:
src/http/modules/ngx_http_upstream_sticky_module.c:171: { ngx_string("sticky"),
看它的指令定义,参数要求是 NGX_CONF_2MORE,至少两个参数:
{ ngx_string("sticky"),
NGX_HTTP_UPS_CONF|NGX_CONF_2MORE,
ngx_http_upstream_sticky,
0, 0, NULL },
再看 auto/options,这个模块默认就是开的(HTTP_UPSTREAM_STICKY=YES),只有显式加 --without-http_upstream_sticky_module 才关。CHANGES 里也写清楚了:内置 session affinity 是 1.29.6 引入的,1.31.0 起才提供关闭开关。
我升级的起点是 1.28.1,正好跨过了 1.29.6。老版本没有这个内置模块,所以同样的配置一直没事。
三、根因分析
根因是内置指令和第三方模块同名,内置模块先被匹配。
- nginx 1.29.6 起内置
ngx_http_upstream_sticky_module,默认编译,sticky指令要求NGX_CONF_2MORE,合法写法只有sticky cookie <cookie名> ...、sticky route $变量 ...、sticky learn zone=... ...。 - 第三方 nginx-sticky-module-1.2.6 的
sticky是NGX_CONF_ANY,允许sticky;。 - nginx 解析配置时按模块注册顺序找指令,内置模块排在
--add-module之前。sticky;先命中内置模块,参数数量校验不过,直接emerg。第三方模块虽然编进了二进制,但它的指令被遮蔽,永远轮不到执行。
所以 nginx -V 里有 --add-module 并不能证明第三方 sticky 在生效,这一点在排查时容易误判。
四、解决方案
4.1 方案选择
两条路:
- 方案 A:重编译时加
--without-http_upstream_sticky_module关掉内置模块,继续用第三方 1.2.6,配置一行不改。 - 方案 B:不重编译,把 8 处
sticky;改成内置模块的写法sticky cookie route path=/;。
生产上我选方案 A。这次升级的目的是补安全漏洞,不应该顺带更换粘性实现。
4.2 清理构建产物
加编译开关必须重新跑 configure,先清理旧的编译文件,直接执行 make clean:
cd /usr/local/src/nginx-1.31.9
make clean
nginx 生成的顶层 Makefile 里 clean 的动作就是 rm -rf Makefile objs,执行后 Makefile 和 objs/ 都会消失,源码目录本身不动,不需要重新解压 tar 包。nginx 没有 distclean,make clean 就是最彻底的一层。
注意:
make clean只删除构建产物,不会碰/AppHome/nginx/sbin/下已安装的二进制和/AppHome/nginx/conf下的配置。
4.3 重新编译
关键参数如下:
| 参数 | 值 | 说明 |
|---|---|---|
--without-http_upstream_sticky_module |
启用 | 关闭 1.29.6 起内置的 sticky 模块,避免与第三方同名指令冲突 |
--add-module |
/usr/local/src/nginx-sticky-module-1.2.6 |
保留现网使用的第三方 sticky,粘性行为不变 |
--with-openssl |
/usr/local/src/openssl-1.1.1w |
保持与现网一致,不换 OpenSSL |
--with-openssl-opt |
'enable-tls1_3 enable-weak-ssl-ciphers' |
保持原参数不变 |
完整命令:
cd /usr/local/src/nginx-1.31.9
./configure --prefix=/AppHome/nginx --user=nginx --group=nginx \
--with-http_ssl_module --with-http_stub_status_module --with-pcre \
--add-module=/usr/local/src/nginx-sticky-module-1.2.6 \
--with-openssl=/usr/local/src/openssl-1.1.1w \
--with-openssl-opt='enable-tls1_3 enable-weak-ssl-ciphers' \
--with-http_gzip_static_module --with-http_v2_module --with-http_sub_module \
--with-http_realip_module --with-stream --with-stream_ssl_module \
--with-stream_realip_module \
--without-http_upstream_sticky_module
make -j$(nproc)
4.4 替换并重启
先验证新二进制,再替换。顺序不能反,替换前 sbin/nginx 还是那个不兼容的版本,直接重启会起不来:
cd /usr/local/src/nginx-1.31.9
objs/nginx -t -c /AppHome/nginx/conf/nginx.conf
cd /AppHome/nginx/sbin
mv nginx nginx.builtin-sticky.1.31.9
cp /usr/local/src/nginx-1.31.9/objs/nginx .
./nginx -t
systemctl restart nginx
注意:
nginx -s reload不会加载新二进制。reload 只是让现有 master 重新读配置、fork 新 worker,程序还是内存里那一份旧镜像。要让新编译的二进制生效,必须重启 master,或者用 USR2 做平滑升级。
4.5 被否决的方案 B
方案 B 的改法是每个 upstream 里把 sticky; 换成:
sticky cookie route path=/;
我推演后放弃了,有三个原因:
- Cookie 值算法不一样。旧模块是
MD5(二进制 sockaddr),内置模块是MD5("10.196.68.126:56780" 这种可打印地址)。两边都是 32 位 hex,但值不通用,切换瞬间所有客户端的routeCookie 失效,粘性会断一次。 - 下发时机不一样。旧模块只在需要重新选后端时下发
Set-Cookie,内置模块每次代理成功都下发。后端响应如果经过缓存层,这个差异会带出额外影响。 - 内置模块 1.29.6 才引入,这次升级已经跨了三个大版本,不适合在同一个窗口再换一套粘性实现。
另外,path=/ 必须显式写。内置模块不配 path 时不输出 Path 属性,浏览器会按请求路径隔离 Cookie,多路径应用(比如 SSO)的粘性会失效;旧模块的默认值就是 /。
五、验证
编译完成后我先做了三项检查:
cd /usr/local/src/nginx-1.31.9
# 1. 编译参数里两个关键项都在
objs/nginx -V | tr ' ' '\n' | grep -E 'without-http_upstream_sticky|nginx-sticky-module'
# 2. 内置模块确实没编进去
grep -c ngx_http_upstream_sticky_module objs/ngx_modules.c
# 预期输出:0
# 3. 用现网配置做语法检查
objs/nginx -t -c /AppHome/nginx/conf/nginx.conf
三项结果都符合预期,-t 输出 test is successful,说明 sticky; 已经回到第三方 1.2.6 的解析路径。
六、注意事项
- 必须加
--without-http_upstream_sticky_module,--without-http_upstream_sticky是已废弃的旧写法。 - 这个开关会出现在
nginx -V的 configure arguments 里,以后走仓库install_nginx.sh upgrade时extract_configure_args会自动继承,不会丢。 nginx -V只能证明编译参数,不能证明指令由谁处理。遇到同名指令冲突,要看objs/ngx_modules.c和源码里的ngx_command_t。- 以后如果要用内置 sticky 的
cookie、route、learn能力,需要先移除第三方模块,并接受 Cookie 值不兼容带来的一次性切换。 make clean会删掉Makefile和objs/,源码目录不受影响,不需要重新解压。
七、补充:154 环境(swProxy1)的升级记录
154 这台原来跑 nginx 1.24.0,前缀 /AppHome/nginx2021,系统 RHEL 6.5,gcc 4.4.7。因为也有第三方 sticky,升级到 1.31.9 同样要加 --without-http_upstream_sticky_module。
和 nginx109 相比只多两处调整:
- 原来的
--with-openssl=/usr/local/openssl已经不是源码树(只剩 include),改用/usr/local/src/openssl-1.1.1w。 - gcc 4.4.7 把
ngx_proxy_protocol.c的未初始化警告当成错误,加--with-cc-opt='-Wno-uninitialized'绕过。这条是误报,value只在函数返回NGX_OK后使用,不改源码。
编译:
cd /usr/local/src/nginx-1.31.9
make clean
./configure --prefix=/AppHome/nginx2021 --user=nginx --group=nginx \
--with-http_ssl_module --with-http_stub_status_module --with-pcre \
--with-openssl=/usr/local/src/openssl-1.1.1w \
--add-module=/usr/local/src/nginx-sticky-module-1.2.6 \
--with-openssl-opt='enable-tls1_3 enable-weak-ssl-ciphers' \
--with-http_v2_module --with-http_sub_module --with-http_realip_module \
--without-http_upstream_sticky_module \
--with-cc-opt='-Wno-uninitialized'
make -j$(nproc)
验证并替换:
cd /usr/local/src/nginx-1.31.9
objs/nginx -V | grep -E 'built with OpenSSL|without-http_upstream_sticky|with-cc-opt'
grep -c ngx_http_upstream_sticky_module objs/ngx_modules.c # 预期 0
objs/nginx -t -c /AppHome/nginx2021/conf/nginx.conf
cd /AppHome/nginx2021/sbin
mv nginx nginx.bak.20261120
cp /usr/local/src/nginx-1.31.9/objs/nginx .
./nginx -t
/etc/init.d/nginx restart
这台编完后 -V 显示 built with OpenSSL 1.1.1w,关闭开关和 -Wno-uninitialized 都在,ngx_modules.c 计数为 0,-t 通过,/etc/init.d/nginx restart 正常拉起。reload 不换二进制,必须 restart。
八、参考资料
- nginx 1.31.9 CHANGES:https://nginx.org/en/CHANGES
- nginx 安全公告:https://nginx.org/en/security_advisories.html
- nginx configure 参数说明:https://nginx.org/en/docs/configure.html
- 内置 sticky 模块源码:
src/http/modules/ngx_http_upstream_sticky_module.c(nginx 1.31.9) - 第三方模块源码:
/usr/local/src/nginx-sticky-module-1.2.6/ngx_http_sticky_module.c