技能
Reference
Nginx 版本兼容性
在编写配置前先探测正在运行的 nginx 版本,然后将指令语法映射到该版本。在任何涉及 nginx 的任务中于 /dr-plan 中加载。
概述
Nginx 在不同版本间会改变指令语法,因此涉及 nginx 配置的计划必须先确定目标版本,而不能假设某种语法。这是针对任何编辑 nginx 配置的任务在 /dr-plan 中使用的内联检查清单。
1. 先探测正在运行的版本
ssh <host> 'nginx -v' # prints "nginx version: nginx/1.MM.p" to stderr
ssh <host> 'nginx -V 2>&1 | tr " " "\n" | grep -- --with' # compiled-in modules (http_v2, http_v3)
在计划中记录确切的 1.MM.p。绝不要假设 — 各发行版会锁定旧分支(Debian bookworm 附带 1.22.x,Ubuntu 22.04 附带 1.18.x)。
2. 版本到语法的映射
- HTTP/2 — 直到 1.25.0:
listen 443 ssl http2;。从 1.25.1 起:listen 443 ssl;外加单独的http2 on;指令。 - HTTP/3 / QUIC — 1.25.0 之前不可用。从 1.25.1 起:
listen 443 quic reuseport;外加http3 on;(需要--with-http_v3_module)。
从 1.25.1 起,http2 和 http3 是独立指令,而非 listen 参数 — 旧的 listen ... http2 形式已弃用,并在 1.25.1+ 上产生警告。
3. 常见的破坏性变更陷阱
quic/http3需要以--with-http_v3_module构建的 nginx(大多数发行版软件包中不包含)— 在规划 HTTP/3 前通过nginx -V确认。ssl_protocols和加密套件默认值因构建而异 — 应显式声明它们,而不是依赖默认值。- 安全重载:
nginx -t(配置测试)必须在nginx -s reload之前通过。