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
