agent
v2.39.0
يعد NGINX Agent برنامجًا خفيًا مصاحبًا لمثيل NGINX Open Source أو NGINX Plus. أنها تمكن:
لوحة معلومات Grafana تعرض المقاييس التي أبلغ عنها وكيل NGINX
يعمل NGINX Agent كعملية مصاحبة على نظام يقوم بتشغيل NGINX. وهو يوفر واجهات gRPC وREST لإدارة التكوين وجمع المقاييس من عملية NGINX ونظام التشغيل. يتيح NGINX Agent التفاعل عن بعد مع NGINX باستخدام أدوات Linux الشائعة ويفتح القدرة على إنشاء أنظمة مراقبة وتحكم متطورة يمكنها إدارة مجموعات كبيرة من مثيلات NGINX.
يوفر NGINX Agent واجهة API لإرسال ملفات التكوين المحدثة. عند استلام ملف جديد، فإنه يتحقق من مخرجات nginx -V لتحديد موقع التكوينات الموجودة. ثم يقوم بعد ذلك بالتحقق من صحة التكوين الجديد باستخدام nginx -t قبل تطبيقه عبر إشارة HUP إلى عملية NGINX الرئيسية.
يتعامل وكيل NGINX مع معلومات عملية NGINX ويوزع سجلات NGINX لحساب المقاييس والإبلاغ عنها. عند التواصل مع NGINX Plus، يقوم وكيل NGINX بسحب المعلومات ذات الصلة من NGINX Plus API. قد يتم تجميع المقاييس المُبلغ عنها بواسطة Prometheus وتصورها باستخدام أدوات مثل Grafana.
يحتفظ وكيل NGINX بالاتصال مفتوحًا بـ NGINX Plus API والاستعلامات بناءً على الفاصل الزمني للمجموعة. يتم الإبلاغ عن هذا الاتصال في المقاييس، واعتمادًا على مرحلة الإبلاغ، يمكن أن يظهر هذا الاتصال على أنه خامل أو نشط.
عند التشغيل جنبًا إلى جنب مع مثيل مفتوح المصدر لـ NGINX، يتطلب NGINX Agent تشغيل سجلات الوصول والأخطاء في NGINX وتحتوي على جميع المتغيرات الافتراضية.
لكي يعمل NGINX Agent بشكل صحيح مع مثيل NGINX Plus، يجب تكوين واجهة برمجة التطبيقات (API) في nginx.conf لهذا المثيل. راجع نظرة عامة على مقاييس المثيل لمزيد من التفاصيل. بمجرد تكوين NGINX Plus بنقطة النهاية /api/ ، سيستخدمها NGINX Agent تلقائيًا عند بدء التشغيل.
يسمح NGINX Agent لنظام التحكم المتصل بـ gRPC بتسجيل المستمع لحدث معين. يتم بعد ذلك استدعاء آلية التحكم عندما يرسل NGINX Agent إشارة نظام مرتبطة. يمكن أن يكون مصدر الإشعار إما مثيل 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 Agent مباشرة مع عملية خادم NGINX المثبتة على نفس النظام. إذا لم يكن لديك بالفعل، فاتبع هذه الخطوات لتثبيت NGINX Open Source أو NGINX Plus. بمجرد التثبيت، تأكد من تشغيل مثيل NGINX.
لتثبيت NGINX Agent على نظامك، انتقل إلى الإصدارات وقم بتنزيل أحدث حزمة مدعومة بتوزيع نظام التشغيل وبنية وحدة المعالجة المركزية لديك.
استخدم مدير الحزم الخاص بنظامك لتثبيت الحزمة. بعض الأمثلة:
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
جبال الألب لينكس
sudo apk add nginx-agent-<agent-version>.apk
فري بي إس دي
sudo pkg add nginx-agent-<agent-version>.pkg
لبدء تشغيل وكيل NGINX على أنظمة systemd، قم بتشغيل الأمر التالي:
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 Agent ملفات السجل المنسقة لجمع المقاييس. سيؤدي توسيع تنسيقات السجل وعدد المثيلات أيضًا إلى زيادة حجم ملفات سجل وكيل 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
لمزيد من التفاصيل حول تكوين السجل، راجع خيارات تكوين السجل
لإنشاء صورة تحتوي على أحدث وكيل NGINX، يقوم أحدث إصدار رئيسي من NGINX OSS على أحدث إصدار من Alpine بتشغيل الأمر التالي:
make official-oss-imageلإنشاء صورة تحتوي على أحدث إصدار من NGINX Agent، يقوم أحدث إصدار ثابت من NGINX OSS على أحدث إصدار من Alpine بتشغيل الأمر التالي:
make official-oss-stable-imageلمزيد من المعلومات حول كيفية تشغيل حاويات وكيل NGINX وكيفية إنشاء صورة تستخدم NGINX Plus بدلاً من NGINX OSS، راجع صور Docker
اتبع هذه الخطوات لتكوين وتشغيل NGINX Agent وواجهة وهمية ("مستوى التحكم") والتي سيقدم وكيل NGINX تقريرًا إليها.
اتبع الخطوات الموجودة في قسم التثبيت لتنزيل NGINX وتثبيته وتشغيله.
باستخدام طريقتك المفضلة، قم باستنساخ مستودع وكيل NGINX في دليل التطوير الخاص بك. راجع استنساخ مستودع GitHub للحصول على مساعدة إضافية.
تمت كتابة وكيل NGINX وطائرة التحكم الوهمية بلغة 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/
قم بإنشاء ملف agent-dynamic.conf في الدليل /etc/nginx-agent/ ، المطلوب لتشغيل 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لمزيد من المعلومات، راجع تعريفات بروتوكول الوكيل ووثائقه
يمكن الكشف عن واجهة NGINX Agent REST من خلال التحقق من وجود الأسطر التالية في الملف /etc/nginx-agent/nginx-agent.conf :
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.
يتطلب Swagger UI تثبيت goswagger. راجع تعليمات تثبيت goswagger للحصول على مساعدة إضافية.
لتشغيل Swagger UI لواجهة REST، قم بتشغيل الأمر التالي
make launch-swagger-ui
افتح متصفح الويب لعرض Swagger UI على http://localhost:8082/docs.
الامتداد عبارة عن جزء من التعليمات البرمجية، وليس مهمًا للوظيفة الرئيسية التي يكون وكيل NGINX مسؤولاً عنها. يقع هذا بشكل عام خارج نطاق إدارة تكوين NGINX والإبلاغ عن مقاييس NGINX.
لتمكين ملحق، يجب إضافته إلى قائمة الملحقات في /etc/nginx-agent/nginx-agent.conf . فيما يلي مثال لتمكين ملحق المقاييس المتقدمة:
extensions :
- advanced-metrics إذا كان قيد التشغيل بالفعل، فأعد تشغيل NGINX Agent لتطبيق التكوين الجديد. وبدلاً من ذلك، إذا لم يكن وكيل 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
افتح متصفح الويب لعرض مستوى التحكم الوهمي على http://localhost:54790. ستظهر الروابط التالية في واجهة الويب:
لمزيد من حالات استخدام وكيل 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:
قبل بدء التطوير على وكيل NGINX، من المهم تنزيل وتثبيت الأداة والتبعيات الضرورية التي يتطلبها وكيل NGINX. يمكنك القيام بذلك عن طريق تشغيل الأمر make التالي:
make install-tools
قم بتشغيل الأوامر التالية لإنشاء وتشغيل NGINX Agent:
make build
sudo make run
يمكن تشغيل NGINX Agent في معظم البيئات. للحصول على قائمة بالتوزيعات المدعومة، راجع دليل المواصفات الفنية لـ NGINX.
يمكن نشر وكيل NGINX في البيئات التالية:
يعمل NGINX Agent مع جميع الإصدارات المدعومة من NGINX Open Source وNGINX Plus.
الحد الأدنى لتوصيات حجم النظام لوكيل NGINX:
| وحدة المعالجة المركزية | ذاكرة | شبكة | تخزين |
|---|---|---|---|
| 1 وحدة المعالجة المركزية الأساسية | 1 جيجا رام | بطاقة واجهة شبكة بسعة 1 جيجا بايت | 20 جيجابايت |
تُعد قناة Slack #nginx-agent الخاصة بنا المكان الأمثل لبدء طرح الأسئلة ومشاركة أفكارك.
توفر صفحة مشكلات GitHub الخاصة بنا مساحة لمزيد من المناقشة الفنية بالسرعة التي تناسبك.
شارك في المشروع من خلال المساهمة! يرجى الاطلاع على دليل المساهمة لدينا للحصول على التفاصيل.
راجع صفحة الإصدار الخاصة بنا لتتبع التحديثات.
ترخيص أباتشي، الإصدار 2.0
