nginx 1.31.5 的控制 API 将失败的重新加载转... 笔记

nginx 1.31.5 的控制 API 将失败的重新加载转换为 HTTP 422 状态码,而不是记录为日志行。

Nginx 1.31.5 版本引入了一个新的控制 API,可通过 Unix 套接字或 TCP 端口访问。该 API 支持基于 HTTP 的重载,并提供结构化响应,不同于传统的基于信号的重载方式。它可通过命令行标志启用,官方 Docker 镜像已包含必要的编译支持。API 的端点树可通过顺序发送 GET 请求进行发现。关键端点包括 /1/control/processes,用于获取工作进程 PID;以及 /1/control/config,用于获取当前配置。向 /1/control/config 发送 PATCH 请求会触发配置重载,通过重新从磁盘读取配置文件实现。该 API 的一大优势在于重载失败时会返回可解析的 JSON 错误消息,而传统信号方式提供的信息较少。尽管最初有假设,但测试表明 API 重载方式在速度上并未明显优于信号方式。并发测试显示,无论采用何种方法,重载均不会影响正在处理的请求。若将控制 API 绑定到网络端口,则存在显著的安全风险,因其缺乏原生身份验证,任何拥有网络访问权限的用户均可利用。建议将套接字绑定到 Unix 套接字并设置严格的文件权限,作为有效的缓解措施,从而阻止非特权用户访问。启用控制套接字会使主进程产生少量内存开销。测试发现,对主机端已挂载的配置文件的编辑可能不会传播到正在运行的容器中,需要借助 docker cp 等方法才能实现即时更新。控制 API 的主要优势在于其在重载过程中提供更优越的错误报告,使其对部署脚本具有价值。强烈建议仅将控制套接字绑定到具有适当权限的 Unix 套接字。管理员应审计系统,检查 Nginx 1.31.5 及更高版本是否存在绑定到网络端口的控制套接字。