当前位置：首页 > backend >正文

NGINX Plus 管理与上报模块`ngx_mgmt_module`

backend 2025/6/17 10:48:22

一、模块定位与依赖

模块名称：ngx_mgmt_module
首次引入：NGINX Plus 1.27.2（nginx-plus-r33）
应用场景：
- 强制许可证校验：首次启动及续期需向 F5 授权端点上报
- 使用量统计：每小时收集并上报实例指标
- 企业内部隔离：支持上报给 NGINX Instance Manager（NIM）
依赖条件：商业订阅版默认编译，无需额外 --add-module。

二、核心指令详解

所有管理指令均位于顶层 nginx.conf 的 mgmt { … } 块内：

mgmt {[license_token <file>];[enforce_initial_report on|off];[state_path <path>];[resolver <addr> …];[ssl_verify on|off];[ssl_trusted_certificate <file>];[ssl_crl <file>];proxy <host:port>;proxy_username <user>;proxy_password <pass>;usage_report [endpoint=<addr>] [interval=<time>];
}

指令	含义
`license_token file`	指定 JWT 许可证文件路径，默认 `/etc/nginx/license.jwt`
`enforce_initial_report on/off`	初始上报策略；`on`（默认）若首报失败则阻止流量，`off` 可享180天宽限期
`state_path path`	存储模块状态文件（`nginx-mgmt-*`），默认 `/var/lib/nginx/state`
`resolver`	DNS 解析上报端点域名，默认系统 resolver
`ssl_verify on/off`	TLS 握手时是否校验证书，默认 `on`
`ssl_trusted_certificate file`	验证上报端点服务器证书的 CA 列表
`ssl_crl file`	验证上报端点证书吊销列表
`proxy host:port`	通过 HTTP CONNECT 代理发送上报
`proxy_username`／`proxy_password`	代理认证凭据
`usage_report [endpoint=][interval=]`	指定上报目标地址与周期，默认 `product.connect.nginx.com 1h`

三、典型配置示例

3.1 基础许可证校验与上报

# 顶层开启管理块
mgmt {# 指定自定义 license.jwt 路径（可选）license_token /etc/nginx/my-license.jwt;# 若首报 180 天内未成功仍可先处理流量enforce_initial_report off;# 上报端点，默认 product.connect.nginx.com:443usage_report endpoint=prod.connect.nginx.com interval=1h;
}

流程：NGINX 启动时立即加载并校验 JWT；
随后每小时向 F5 授权服务上报使用量；
若网络阻断，首次上报成功前应用仍可在 180 天内正常运行。

3.2 通过代理上报

mgmt {license_token /etc/nginx/license.jwt;# 企业内网需走代理proxy          10.0.0.1:3128;proxy_username report_user;proxy_password s3cr3t;# 上报给 NGINX Instance Managerusage_report endpoint=nim.company.local:8443 interval=30m;# TLS 校验配置ssl_verify on;ssl_trusted_certificate /etc/nginx/certs/nim-ca.pem;ssl_crl /etc/nginx/certs/nim-crl.pem;
}

上报请求经 HTTP CONNECT 到本地 3128 代理，再转发到 NIM；
上报通道启用 TLS 并校验对端证书与 CRL；
上报周期缩短至 30 分钟，提高实时监控精度。

四、故障容忍与重试策略

连接重试：
- 采用系统默认 DNS，若解析失败，可自定义 resolver 8.8.8.8 valid=60s
- 代理不可用时，报错日志输出后每小时再试，管理模块不影响 NGINX 主流程
状态持久化：
- state_path 下会生成 JSON 状态文件，内含上报成功时间戳与失败计数
- 重启时自动加载，确保不中断上报进度