GitHub go.mod Go 版本 GitHub 发布版本 GitHub 许可证欢迎贡献

NGINX Agent 是 NGINX 开源版或 NGINX Plus 实例的配套守护程序。它可以实现：

远程管理 NGINX 配置
收集和报告实时 NGINX 性能和操作系统指标
NGINX 事件通知

Grafana 仪表板显示 NGINX Agent 报告的指标

工作原理

NGINX Agent 作为一个伴随进程运行在运行 NGINX 的系统上。它为配置管理和从 NGINX 进程和操作系统收集指标提供 gRPC 和 REST 接口。NGINX Agent 使用常见的 Linux 工具实现远程与 NGINX 交互，并解锁构建复杂监控和控制系统的能力，可以管理大量 NGINX 实例。

NGINX Agent 工作原理

配置管理

NGINX Agent 提供 API 接口用于提交更新的配置文件。收到新文件后，它会检查 nginx -V 的输出以确定现有配置的位置。然后使用 nginx -t 验证新配置，在应用之前通过向 NGINX 主进程发送 HUP 信号。

收集指标

NGINX Agent 与 NGINX 进程信息交互并解析 NGINX 日志以计算和报告指标。与 NGINX Plus 交互时，NGINX Agent 从 NGINX Plus API 获取相关信息。报告的指标可以被 Prometheus 聚合并使用 Grafana 等工具可视化。

NGINX Agent 保持与 NGINX Plus API 的连接开放，并根据收集间隔进行查询。这个连接会在指标中报告，根据报告阶段的不同，该连接可能显示为空闲或活跃。

NGINX 开源版

当与 NGINX 开源版实例一起运行时，NGINX Agent 要求打开 NGINX 访问和错误日志，并包含所有默认变量。

NGINX Plus

为了使 NGINX Agent 能够与 NGINX Plus 实例正常工作，需要在该实例的 nginx.conf 中配置 API。详情请参阅实例指标概览。一旦 NGINX Plus 配置了 /api/ 端点，NGINX Agent 将在启动时自动使用它。

事件通知

NGINX Agent 允许 gRPC 连接的控制系统为特定事件注册监听器。当 NGINX Agent 发送相关系统信号时，控制机制会被调用。通知的来源可以是 NGINX 实例或 NGINX Agent 本身。以下是当前支持的事件列表：

事件	描述
AGENT_START_MESSAGE	NGINX Agent 进程启动
AGENT_STOP_MESSAGE	NGINX Agent 进程停止
NGINX_FOUND_MESSAGE	系统上检测到 NGINX 主进程
NGINX_STOP_MESSAGE	NGINX 主进程停止
NGINX_RELOAD_SUCCESS_MESSAGE	NGINX 主进程成功重新加载
NGINX_RELOAD_FAILED_MESSAGE	NGINX 主进程重新加载失败
NGINX_WORKER_START_MESSAGE	新的 NGINX 工作进程启动
NGINX_WORKER_STOP_MESSAGE	NGINX 工作进程停止
CONFIG_APPLY_SUCCESS_MESSAGE	成功应用新的 NGINX 配置
CONFIG_APPLY_FAILURE_MESSAGE	应用新的 NGINX 配置失败
CONFIG_ROLLBACK_SUCCESS_MESSAGE	成功回滚 NGINX 配置
CONFIG_ROLLBACK_FAILURE_MESSAGE	回滚 NGINX 配置失败

安装

安装 NGINX

NGINX Agent 直接与安装在同一系统上的 NGINX 服务器进程交互。如果您还没有安装，请按照以下步骤安装 NGINX 开源版或 NGINX Plus。安装完成后，确保 NGINX 实例正在运行。

从软件包文件安装 NGINX Agent

要在您的系统上安装 NGINX Agent，请前往 Releases 下载最新的适用于您的操作系统发行版和 CPU 架构的软件包。

使用系统的包管理器安装软件包。以下是一些示例：

Debian、Ubuntu 和其他使用 dpkg 包管理器的发行版。

sudo dpkg -i nginx-agent-<agent-version>.deb

RHEL、CentOS RHEL、Amazon Linux、Oracle Linux 和其他使用 yum 包管理器的发行版

sudo yum localinstall nginx-agent-<agent-version>.rpm

RHEL 和其他使用 rpm 包管理器的发行版

sudo rpm -i nginx-agent-<agent-version>.rpm

Alpine Linux

sudo apk add nginx-agent-<agent-version>.apk

FreeBSD

sudo pkg add nginx-agent-<agent-version>.pkg

启动和启用开机自启

要在使用 systemd 的系统上启动 NGINX Agent，运行以下命令：

sudo systemctl start nginx-agent

要启用 NGINX Agent 在开机时自动启动，运行以下命令：

sudo systemctl enable nginx-agent

在 Alpine Linux 上，使用以下命令启动代理：

sudo service nginx-agent start

要在 Alpine Linux 上启用代理在开机时自动启动，运行以下命令：

sudo rc-update add nginx-agent default

日志记录

NGINX Agent 使用格式化的日志文件来收集指标。扩展日志格式和实例数量也会增加 NGINX Agent 日志文件的大小。我们建议为 /var/log/nginx-agent 添加一个单独的分区。如果没有日志轮转或存储在单独的分区上，日志文件可能会占用所有可用磁盘空间，导致系统对某些服务无响应。

日志轮转

默认情况下，NGINX Agent 使用 logrotate 每天轮转日志，配置如下：

/var/log/nginx-agent/*.log
{
   # 每天轮转日志文件
   daily
   # 如果日志文件大小超过 5M，则进行轮转
   size 5M
   # 创建副本后截断原始日志文件
   copytruncate
   # 删除超过 10 天的轮转日志
   maxage 10
   # 日志文件轮转 10 次后被删除
   rotate 10
   # 压缩旧的日志文件
   compress
   # 如果日志文件丢失，将继续处理下一个文件，不发出错误消息
   missingok 
   # 如果日志为空，则不进行轮转
   notifempty
}

如果需要更改默认配置，可以在此处更新文件：/etc/logrotate.d/nginx-agent

有关 logrotate 配置的更多详细信息，请参阅 Logrotate 配置选项

构建 Docker 镜像

要构建包含最新 NGINX Agent、最新主线版本的 NGINX OSS 和最新 Alpine 的镜像，运行以下命令：

make official-oss-image

要构建包含最新 NGINX Agent、最新稳定版本的 NGINX OSS 和最新 Alpine 的镜像，运行以下命令：

make official-oss-stable-image

有关如何运行 NGINX Agent 容器以及如何构建使用 NGINX Plus 而不是 NGINX OSS 的镜像的更多信息，请参阅 Docker 镜像

NGINX Agent 入门

按照以下步骤配置和运行 NGINX Agent 以及一个模拟接口（"控制平面"），NGINX Agent 将向其报告。

安装 NGINX

按照安装部分的步骤下载、安装和运行 NGINX。

克隆 NGINX Agent 仓库

使用您喜欢的方法，将 NGINX Agent 仓库克隆到您的开发目录中。如需额外帮助，请参阅克隆 GitHub 仓库。

安装 Go

NGINX Agent 和模拟控制平面是用 Go 编写的。需要 Go 1.22 或更高版本才能从源代码目录构建和运行任一应用程序。您可以从官方网站下载 Go。

启动 gRPC 模拟控制平面

通过在 agent 源代码根目录运行以下命令来启动模拟控制平面：

go run sdk/examples/server.go

# 命令输出
INFO[0000] http listening at 54790 # 模拟控制平面端口
INFO[0000] gRPC listening at 54789 # NGINX Agent 将报告的 gRPC 控制平面端口

NGINX Agent 设置

如果 /etc/nginx-agent/ 目录不存在，请创建它，并从项目根目录将 nginx-agent.conf 文件复制到其中。

sudo mkdir /etc/nginx-agent
sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/

在 /etc/nginx-agent/ 目录中创建 agent-dynamic.conf 文件，这是 NGINX Agent 运行所必需的。

sudo touch /var/lib/nginx-agent/agent-dynamic.conf

启用 gRPC 接口

将以下设置添加到 /etc/nginx-agent/nginx-agent.conf：

server:
  host: 127.0.0.1 # 模拟控制平面主机
  grpcPort: 54789 # 模拟控制平面 gRPC 端口

# gRPC TLS 选项 - 不建议在生产环境中禁用 TLS
tls:
  enable: false
  skip_verify: true

有关更多信息，请参阅 Agent 协议定义和文档

启用 REST 接口

可以通过验证 /etc/nginx-agent/nginx-agent.conf 文件中是否存在以下行来公开 NGINX Agent REST 接口：

api:
  # 设置 API 地址以允许远程管理
  host: 127.0.0.1
  # 将此值设置为安全的端口号以防止信息泄露
  port: 8038
  
  # REST TLS 参数
  cert: "<TLS-CERTIFICATE>.crt"
  key: "<PRIVATE-KEY>.key"

模拟控制平面可以使用 gRPC 或 REST 协议与 NGINX Agent 通信。

启动 Swagger UI

Swagger UI 需要安装 goswagger。有关安装 goswagger 的其他帮助，请参阅 goswagger 安装说明。

要启动 REST 接口的 Swagger UI，运行以下命令：

make launch-swagger-ui

打开 Web 浏览器，在 http://localhost:8082/docs 查看 Swagger UI。

扩展

扩展是一段代码，对 NGINX Agent 负责的主要功能不是至关重要的。这通常超出了管理 NGINX 配置和报告 NGINX 指标的范围。

要启用扩展，必须将其添加到 /etc/nginx-agent/nginx-agent.conf 中的扩展列表中。以下是启用高级指标扩展的示例：

extensions:
  - advanced-metrics

启动 NGINX Agent

如果已经运行，重新启动 NGINX Agent 以应用新配置。或者，如果 NGINX Agent 未运行，您可以从源代码根目录运行它。

打开另一个终端窗口并启动 NGINX Agent。从 agent 源代码根目录发出以下命令。

sudo make run

# 命令输出片段
WARN[0000] Log level is info
INFO[0000] setting displayName to XXX
INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX
INFO[0000] NginxBinary initializing
INFO[0000] Commander initializing
INFO[0000] Comms initializing
INFO[0000] OneTimeRegistration initializing
INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX
INFO[0000] Metrics initializing
INFO[0000] MetricsThrottle initializing
INFO[0000] DataPlaneStatus initializing
INFO[0000] MetricsThrottle waiting for report ready
INFO[0000] Metrics waiting for handshake to be completed
INFO[0000] ProcessWatcher initializing
INFO[0000] Extensions initializing
INFO[0000] FileWatcher initializing
INFO[0000] FileWatchThrottle initializing
INFO[0001] Events initializing
INFO[0001] OneTimeRegistration completed

打开 Web 浏览器，在 http://localhost:54790 查看模拟控制平面。Web 界面将显示以下链接：