agent
v2.39.0
NGINX Agent 是 NGINX Open Source 或 NGINX Plus 实例的配套守护进程。它可以：
Grafana 仪表板显示 NGINX 代理报告的指标
NGINX 代理在运行 NGINX 的系统上作为伴随进程运行。它提供 gRPC 和 REST 接口，用于 NGINX 进程和操作系统的配置管理和指标收集。 NGINX Agent 支持使用常见的 Linux 工具与 NGINX 进行远程交互，并释放了构建复杂的监控和控制系统的能力，该系统可以管理大量 NGINX 实例。
NGINX Agent 提供 API 接口用于提交更新的配置文件。收到新文件后，它会检查nginx -V的输出以确定现有配置的位置。然后，它使用nginx -t验证新配置，然后通过信号 HUP 将其应用到 NGINX 主进程。
NGINX 代理与 NGINX 进程信息交互并解析 NGINX 日志以计算和报告指标。当与 NGINX Plus 交互时，NGINX Agent 从 NGINX Plus API 中提取相关信息。报告的指标可以由 Prometheus 聚合，并使用 Grafana 等工具进行可视化。
NGINX 代理保持与 NGINX Plus API 的连接打开，并根据收集间隔进行查询。此连接会在指标中报告，并且根据报告的阶段，此连接可能显示为空闲或活动。
当与 NGINX 的开源实例一起运行时，NGINX 代理要求 NGINX 访问和错误日志打开并包含所有默认变量。
为了使 NGINX Agent 能够与 NGINX Plus 实例正常工作，需要在该实例的 nginx.conf 中配置 API。有关更多详细信息，请参阅实例指标概述。一旦 NGINX Plus 配置了/api/端点，NGINX Agent 将在启动时自动使用它。
NGINX 代理允许 gRPC 连接的控制系统为特定事件注册侦听器。当 NGINX 代理发送关联的系统信号时，就会调用控制机制。通知的来源可以是 NGINX 实例或 NGINX 代理本身。以下是当前支持的事件列表：
| 事件 | 描述 |
|---|---|
| AGENT_START_MESSAGE | NGINX 代理进程已启动 |
| AGENT_STOP_MESSAGE | NGINX 代理进程已停止 |
| 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 服务器进程连接。如果您还没有，请按照以下步骤安装 NGINX Open Source 或 NGINX Plus。安装后，确保 NGINX 实例正在运行。
要在您的系统上安装 NGINX Agent，请转至版本并下载您的操作系统发行版和 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
阿尔卑斯Linux
sudo apk add nginx-agent-<agent-version>.apk
自由BSD
sudo pkg add nginx-agent-<agent-version>.pkg
要在 systemd 系统上启动 NGINX 代理，请运行以下命令：
sudo systemctl start nginx-agent
要使 NGINX 代理能够在引导时启动，请运行以下命令：
sudo systemctl enable nginx-agent
在 Alpine Linux 上，使用以下命令启动代理：
sudo service nginx-agent start
要使代理在 Alpine Linux 上启动时启动，请运行以下命令：
sudo rc-update add nginx-agent default
NGINX 代理使用格式化日志文件来收集指标。扩展日志格式和实例计数也会增加 NGINX 代理日志文件的大小。我们建议为/var/log/nginx-agent添加单独的分区。如果没有日志轮换或存储在单独的分区上，日志文件可能会耗尽所有可用驱动器空间，并导致系统对某些服务无响应。
默认情况下，NGINX 代理每天使用 logrotate 轮换日志，配置如下：
/var/log/nginx-agent/*.log
{
# log files are rotated every day
daily
# log files are rotated if they grow bigger than 5M
size 5M
# truncate the original log file after creating a copy
copytruncate
# remove rotated logs older than 10 days
maxage 10
# log files are rotated 10 times before being removed
rotate 10
# old log files are compressed
compress
# if the log file is missing it will go on to the next one without issuing an error message
missingok
# do not rotate the log if it is empty
notifempty
}如果需要更改默认配置，可以在此处更新文件/etc/logrotate.d/nginx-agent
有关 logrotate 配置的更多详细信息，请参阅 Logrotate 配置选项
要构建包含最新 NGINX 代理、最新 Alpine 上最新主线版本 NGINX OSS 的映像，请运行以下命令：
make official-oss-image要构建包含最新 NGINX Agent 的映像，最新稳定版本的 NGINX OSS 在最新的 Alpine 上运行以下命令：
make official-oss-stable-image有关如何运行 NGINX Agent 容器以及如何构建使用 NGINX Plus 而不是 NGINX OSS 的映像的更多信息，请参阅 Docker Images
按照以下步骤配置和运行 NGINX 代理以及 NGINX 代理将向其报告的模拟接口（“控制平面”）。
按照安装部分中的步骤下载、安装和运行 NGINX。
使用您首选的方法，将 NGINX 代理存储库克隆到您的开发目录中。请参阅克隆 GitHub 存储库以获取更多帮助。
NGINX 代理和模拟控制平面是用 Go 编写的。从源代码目录构建和运行任一应用程序都需要 Go 1.23 或更高版本。您可以从官方网站下载Go。
通过从agent源代码根目录运行以下命令来启动模拟控制平面：
go run sdk/examples/server.go
# Command Output
INFO[0000] http listening at 54790 # mock control plane port
INFO[0000] gRPC listening at 54789 # gRPC control plane port which NGINX Agent will report to
如果尚不存在，请创建/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
将以下设置添加到/etc/nginx-agent/nginx-agent.conf ：
server :
host : 127.0.0.1 # mock control plane host
grpcPort : 54789 # mock control plane gRPC port
# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION
tls :
enable : false
skip_verify : true有关更多信息，请参阅代理协议定义和文档
可以通过验证/etc/nginx-agent/nginx-agent.conf文件中是否存在以下行来公开 NGINX 代理 REST 接口：
api :
# Set API address to allow remote management
host : 127.0.0.1
# Set this value to a secure port number to prevent information leaks
port : 8038
# REST TLS parameters
cert : " <TLS-CERTIFICATE>.crt "
key : " <PRIVATE-KEY>.key "模拟控制平面可以使用 gRPC 或 REST 协议与 NGINX Agent 进行通信。
Swagger UI 需要安装 goswagger。请参阅安装 goswagger 的说明以获得更多帮助。
要启动 REST 界面的 Swagger UI，请运行以下命令
make launch-swagger-ui
打开 Web 浏览器以查看 Swagger UI，网址为 http://localhost:8082/docs。
扩展是一段代码，对于 NGINX 代理负责的主要功能并不重要。这通常不属于管理 NGINX 配置和报告 NGINX 指标的范围。
要启用扩展，必须将其添加到/etc/nginx-agent/nginx-agent.conf中的扩展列表中。以下是启用高级指标扩展的示例：
extensions :
- advanced-metrics 如果已在运行，请重新启动 NGINX 代理以应用新配置。或者，如果 NGINX 代理未运行，您可以从源代码根目录运行它。
打开另一个终端窗口并启动 NGINX 代理。从agent源代码根目录发出以下命令。
sudo make run
# Command Output snippet
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 界面中将显示以下链接：
有关更多 NGINX 代理用例，请参阅 https://github.com/nginx/agent/tree/main/sdk/examples
虽然大多数 Linux 或 FreeBSD 操作系统都可用于为 NGINX Agent 项目做出贡献，但以下步骤是针对 Ubuntu 设计的。 Ubuntu 打包了构建和运行 NGINX Agent 所需的大多数库，并且是 NGINX Agent 开发的推荐平台。
按照安装部分中的步骤下载并安装 NGINX。安装后确保 NGINX 实例正在运行。
按照 NGINX 代理入门部分中的步骤克隆 NGINX 代理存储库
根据操作系统的发行版，可能需要安装以下软件包才能构建 NGINX 代理。
切换到 NGINX 代理源目录：
cd <path_to_development_directory>/agent
安装品牌：
sudo apt install make
NGINX 代理是用 Go 编写的。您可以下载 Go 并按照同一页面上的安装说明进行操作或运行：
sudo apt install golang-go
安装协议：
sudo apt install -y protobuf-compiler
安装 NGINX Agent 工具和依赖项：
在开始 NGINX Agent 开发之前，下载并安装 NGINX Agent 所需的必要工具和依赖项非常重要。您可以通过运行以下make命令来完成此操作：
make install-tools
运行以下命令来构建并运行 NGINX 代理：
make build
sudo make run
NGINX Agent 可以在大多数环境中运行。有关受支持发行版的列表，请参阅 NGINX 技术规范指南。
NGINX Agent可以部署在以下环境中：
NGINX Agent 可与所有受支持的 NGINX Open Source 和 NGINX Plus 版本配合使用。
NGINX 代理的最小系统大小建议：
| 中央处理器 | 记忆 | 网络 | 贮存 |
|---|---|---|---|
| 1个CPU核心 | 1 GB 内存 | 1GbE 网卡 | 20GB |
我们的 Slack 频道 #nginx-agent 是开始提出问题和分享您的想法的首选地方。
我们的 GitHub 问题页面提供了按照您自己的节奏进行更多技术讨论的空间。
通过贡献参与该项目！有关详细信息，请参阅我们的贡献指南。
请参阅我们的发布页面以跟踪更新。
Apache 许可证，版本 2.0
