الانتقال إلى المحتوى الرئيسي
يضمن خادم agenteye-collector أن تصل بيانات المراقبة (telemetry) لوكلائك إلى AgentEye دون أن يعطل تطبيقك أبداً. يكتب الكود الخاص بك الأحداث إلى دليل محلي ثم ينتقل; يتولى المجمّع المسؤولية من هناك، ويرفع كل ملف خلال ملي ثوان ويبقى صامداً في وجه إعادة التشغيل والانقطاعات الشبكية والأخطاء العابرة في الخادم. تُعاد محاولات الرفع الفاشلة مع تأخير بتراجع أسي (exponential backoff)، وكنس دوري للاسترجاع يعيد قائمة أي شيء تُرك خلفه عند تعطل أو نشر. والنتيجة هي توصيل متين وتجاهل وانطلق (fire-and-forget): يواصل الوكلاء الخاص بك العمل بسرعة كاملة بينما يضمن المجمّع عدم فقدان أي أحداث أثناء النقل. من الناحية الميكانيكية، المجمّع هو خادم خفيف الوزن يراقب $AGENTEYE_HOME/events/ (الافتراضي: ~/.agenteye/events/) بحثاً عن ملفات .jsonl مكتوبة بواسطة Python SDK ويرفعها إلى خادم AgentEye.
تمت إعادة التسمية: أصبح أمر المجمّع الآن agenteye-collector (كان يُسمى سابقاً agenteye). اسم agenteye الأقصر يعود الآن إلى AgentEye CLI. إذا كنت تقوم بترقية تثبيت موجود، انظر enterprise-docs/collector-migration.md.

المتطلبات الأساسية


الخيار أ: الملف الثنائي (موصى به)

ملفات ثنائية ثابتة مجهزة مسبقاً متاحة لـ Linux و macOS و Windows (x86_64 و arm64). حمّل الملف الثنائي لنظامك مباشرة من مستودع agenteye-enterprise/releases تحت أحدث علامة إصدار collector/v<version>. أسماء الأعمال المتاحة:
المنصةالأعمال
Linux x86_64agenteye-collector-linux-x86_64
Linux arm64agenteye-collector-linux-arm64
macOS x86_64agenteye-collector-darwin-x86_64
macOS arm64agenteye-collector-darwin-arm64
Windows x86_64agenteye-collector-windows-x86_64.exe
Windows arm64agenteye-collector-windows-arm64.exe
التحميل باستخدام CLI gh (استبدل الإصدار واختر أعمال منصتك):
أو باستخدام curl:

الخيار ب: Docker

تنشر إصدارات بيتا الحالية العلامة العائمة :beta-latest؛ يتم تعيين :latest فقط للإصدارات المستقرة. للنشرات القابلة للتكرار، فضّل علامة إصدار محددة مثل :v0.0.1-beta.13.
التشغيل:
تعمل الصورة الرسمية كمستخدم غير الجذر، لذا اضبط AGENTEYE_HOME بشكل صريح وجهز مجلد الانتظار المضيف له. يشاركك وصل المجلد نفس دليل ~/.agenteye/ الذي يكتب إليه Python SDK على المضيف. إذا كنت قد ضبطت AGENTEYE_HOME في مكان آخر على المضيف، جهز ذلك الدليل بدلاً من $HOME/.agenteye.

الإعدادات

يمكن تعيين جميع الخيارات بثلاث طرق (من الأعلى أولويةً أولاً):
  1. علم سطر الأوامر: agenteye-collector start --url https://...
  2. متغير البيئة: AGENTEYE_URL=https://...
  3. ملف الإعدادات: ~/.agenteye/config.json

الخيارات المطلوبة

الخيارعلم CLIمتغير البيئةمفتاح config.json
عنوان URL للواجهة الخلفية--url <URL>AGENTEYE_URL"url"
مفتاح API--key <KEY>AGENTEYE_KEY"key"

الخيارات الاختيارية (مع الافتراضيات)

الخيارعلم CLIمتغير البيئةمفتاح config.jsonالافتراضي
الحد الأقصى للرفع المتزامن--max-concurrent-uploads <N>AGENTEYE_MAX_CONCURRENT_UPLOADS"max_concurrent_uploads"64
فترة الكنس (ث)--sweep-interval <S>AGENTEYE_SWEEP_INTERVAL"sweep_interval_secs"60
الحد الأدنى لعمر الملف في الكنس (ث)--sweep-min-age <S>AGENTEYE_SWEEP_MIN_AGE"sweep_min_age_secs"120
الحد الأقصى للملفات لكل كنس--sweep-max-files <N>AGENTEYE_SWEEP_MAX_FILES"sweep_max_files"64
الحد الأقصى لمحاولات الرفع--max-retries <N>AGENTEYE_MAX_RETRIES"max_retries"5
تأخير أساس إعادة المحاولة (مللي ث)--retry-base-delay <MS>AGENTEYE_RETRY_BASE_DELAY"retry_base_delay_ms"1000

خيارات mTLS (اختياري)

بالنسبة للنشرات التي تتطلب TLS المتبادل (mTLS)، يمكن للمجمّع تقديم شهادة عميل أثناء مصافحة TLS. عندما لا يتم تعيين هذه الخيارات، يستخدم المجمّع HTTPS القياسي.
الخيارعلم CLIمتغير البيئةمفتاح config.json
شهادة العميل (PEM)--tls-cert <PATH>AGENTEYE_TLS_CERT"tls_cert"
المفتاح الخاص للعميل (PEM)--tls-key <PATH>AGENTEYE_TLS_KEY"tls_key"
شهادة CA مخصصة (PEM)--tls-ca <PATH>AGENTEYE_TLS_CA"tls_ca"
يجب تعيين --tls-cert و --tls-key معاً. يجب أن تكون الملفات بصيغة PEM. --tls-ca مستقل وضروري فقط عندما يقدم خادم AgentEye شهادة TLS لم تصدرها جهة اعتماد موثوقة علناً (على سبيل المثال، موقّعة ذاتياً بواسطة مُصدر cert-manager داخل المجموعة عندما لا يكون لديك نطاق DNS حقيقي). يضيف المجمّع الشهادة المرفوعة كنقطة ثقة إضافية؛ تبقى الجذور العامة الموثوقة موثوقة، لذا لا تتأثر النشرات الموجودة. قد يحتوي الملف على شهادة PEM واحدة أو سلسلة كاملة (كتل PEM متعددة متسلسلة). تشغيل المجمّع كـ sidecar في حاوية تطبيقك؟ انظر enterprise-docs/single-pod-deployment.md لنمط EKS من النهاية إلى النهاية: حزمة mTLS يتم تسليمها عبر AWS Secrets Manager + Secrets Store CSI Driver + IRSA، مع الدوران التلقائي. عند التشغيل في Kubernetes مع نمط تسليم الخدمة السرية، جهز الخدمة السرية للشهادة كمجلد وأشر هذه المسارات إلى الملفات المجهزة:

مثال ~/.agenteye/config.json

مع mTLS:
مع mTLS بالإضافة إلى جهة اعتماد مخصصة (خادم AgentEye موقّع ذاتياً):
إذا تم ضبط AGENTEYE_HOME، يتم استخدام ذلك الدليل بدلاً من ~/.agenteye.

الإعداد للمرة الأولى

بعد التثبيت، جهز المجمّع برقم خادم عنوان URL ومفتاح API:
استخدم https لأي نشر يعبر شبكة غير موثوقة بحيث لا يتم إرسال الأحداث بنص عادي. نموذج النص العادي http://your-server-host:8080/events مناسب فقط للاختبار المحلي تماماً ضد خادم على نفس المضيف.
اختبر الاتصال (تطبيق الامتصاص الواحد، الخروج بعد استنزاف الأحداث المعلقة):
يقرّر flush تقدمه إلى stdout. عندما يكون مجلد الانتظار فارغاً يطبع No pending files. والخروج 0. خلاف ذلك يطبع سطراً واحداً لكل ملف ([UPLOADED] <file> أو [FAILED] <file> (<reason>)), متبوعاً بملخص Done: <uploaded>/<total> uploaded, <failed> failed.. هذا يجعل flush فحصاً مفيداً للاستخدام الواحد بأن عنوان URL ومفتاح API وإعدادات TLS الخاصة بك صحيحة قبل بدء الخادم.

التشغيل كخادم

مباشر

الحاوية / Docker

عندما يشاركك المجمّع والتطبيق حاوية، شغلهما تحت مراقب العملية. الخيار الأبسط هو supervisord؛ يأتي في كل توزيع رئيسي، ويعيد تشغيل العمليات المتعطلة، ويعيد توجيه الإشارات، وينتظر الإغلاق البطيء. Dockerfile:
supervisord.conf:
لماذا هذه الإعدادات:
  • autorestart=true على agenteye-collector: أعد التشغيل عند أي خروج (تعطل، ذعر، OOM).
  • autorestart=unexpected على التطبيق: أعد التشغيل فقط عند خروج غير صفري، بحيث لا يحلقة وكيل الاستخدام الواحد الذي يخرج 0.
  • stopwaitsecs=30: يعطي المجمّع مجالاً لاستنزاف الرفع المعلقة على SIGTERM قبل أن يصعد supervisord إلى SIGKILL.
  • stdout_logfile=/dev/stdout, *_maxbytes=0: بث إخراج كلا البرنامجين إلى حاوية stdout؛ لا توجد ملفات سجل داخل الحاوية.
مرّر AGENTEYE_URL / AGENTEYE_KEY (وأي متغيرات بيئة TLS) على docker run -e كما هو الحال من قبل؛ يرث supervisord البيئة.
حاويات منفصلة؟ إذا قمت بتشغيل المجمّع كحاوية منفصلة (خدمة Docker Compose, Kubernetes sidecar, إلخ.)، لا تستخدم supervisord؛ سياسة إعادة تشغيل الحاوية runtime تقوم بهذه الوظيفة بالفعل. انظر enterprise-docs/single-pod-deployment.md لنمط EKS sidecar.
مسبار حيوية Kubernetes (ينطبق سواء تم تشغيل المجمّع وحده أو تحت supervisord):
يكتب الخادم الجاري نبضة قلب إلى $AGENTEYE_HOME/health.json كل 30 ثانية. يقرأ agenteye-collector health ذلك الملف والخروج 0 (صحي) فقط عندما تكون نبضة القلب طازجة وتعمل مهام الرفع بشكل طبيعي؛ يخرج 1 (غير صحي) عندما تكون نبضة القلب أقدم من 90 ثانية (على سبيل المثال، توقف الخادم) أو بينما يتم إعادة تشغيل المراقب والكنس بعد خروج غير متوقع. يتم كتابة نبضة القلب فقط بواسطة start, لذا قم بتشغيل المسبار ضد الخادم طويل الأمد وليس الأمر flush الواحد.

systemd (Linux، موصى به للإنتاج)

أنشئ /etc/agenteye/env:

launchd (macOS)


ترقية المجمّع

لا يحدّث المجمّع نفسه. للترقية:
  • الملف الثنائي: حمّل أعمال agenteye-collector-<os>-<arch> الجديدة من أحدث إصدار collector/v<version> (انظر الخيار أ)، استبدل /usr/local/bin/agenteye-collector، ثم أعد تشغيل الخدمة (sudo systemctl restart agenteye-collector, إعادة launchctl load، أو إعادة تشغيل مراقبك).
  • Docker: docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (أو علامة :v<version> محددة؛ :latest موجودة فقط للإصدارات المستقرة) وأعد إنشاء الحاوية.
AGENTEYE_TOKEN مطلوب لتحميل الملفات الثنائية/الصور الجديدة من مستودع الإصدارات الخاص، لكنه ليس ضروري بواسطة الخادم الجاري.

الأوامر الفرعية

الأمرالوصف
agenteye-collector startابدأ الخادم طويل الأمد. عند بدء التشغيل، يقوم بتطبيق امتصاص أي أحداث متبقية من التشغيل السابق، ثم يراقب الملفات الجديدة ويرفعها. يتم إعادة تشغيل المراقب والكنس تلقائياً عند خروج غير متوقع، وتتم كتابة نبضة قلب إلى health.json كل 30 ثانية.
agenteye-collector flushاستخدام واحد: رفع جميع الملفات المعلقة والخروج. يطبع No pending files. عندما يكون مجلد الانتظار فارغاً, خلاف ذلك لكل ملف [UPLOADED]/[FAILED] سجل وملخص Done: <uploaded>/<total> uploaded, <failed> failed..
agenteye-collector healthاقرأ نبضة القلب health.json للخادم. الخروج 0 عندما يكون طازجاً وصحياً؛ الخروج 1 عندما تكون نبضة القلب قديمة (أقدم من 90 ثانية) أو تعاد تشغيل المهام.

تخطيط الدليل

الملفات في failed/ لا تُعاد محاولة تلقائياً. لإعادة قائمة متابعتها يدويّاً، انقل الملفات مرة أخرى إلى events/ وشغّل agenteye-collector flush.