Deployment - FailproofAI

title: “النشر” description: “وثائق نشر AgentEye.”

يغطي هذا الدليل نشر خادم AgentEye والقائمة الأمامية في الإنتاج.

نظرة عامة على العمارة

  [ آلات وكيل AI ]                  [ البنية التحتية الخاصة بك ]

    Python SDK
       |  writes JSONL                       +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (relational store)   |
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (events / analytics) |
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (optional) |
                      | Dashboard |           +----------------------+
                      +-----------+

الخادم: خدمة HTTP بلغة Rust؛ تستقبل دفعات الأحداث وتكتبها إلى ClickHouse وتحافظ على الحالة العلائقية في PostgreSQL.
القائمة الأمامية: تطبيق Next.js؛ تقرأ وتكتب حصريًا من خلال API الخادم.
agenteye-collector: تُنشر على آلات الوكيل وليس على مضيف الخادم.
Postgres 15+: مطلوب. (تم رفعه من 14 في الإصدار متعدد المستأجرين؛ مخطط العضوية في المنظمة يستخدم مفتاحًا أجنبيًا ON DELETE SET NULL قائمًا على قائمة الأعمدة، وهو مطلوب في Postgres 15+. قم بترقية Postgres قبل نشر هذا الإصدار.) يخزن حالة OLTP: api_keys، users، sessions، evaluation_jobs (الطابور)، dashboards، saved_queries، otp_codes، بالإضافة إلى جداول متعددة المستأجرين orgs، org_memberships، org_settings.
ClickHouse 24+: مطلوب. مخزن التحليلات لكل حدث مُدخَل. محرك: ReplacingMergeTree، مقسم حسب الشهر، مرتب حسب (session_id, ts, dedup_key). يتصل الخادم عبر CLICKHOUSE_URL؛ تتضمن الحزمة المجمعة deploy/base/clickhouse/ تكوينًا أحادي العقدة محسّنًا للأداء. متطلب متعدد المستأجرين: يفعّل التكوين المجمع إدارة الوصول إلى SQL + users_without_row_policies_can_read_rows=false بحيث يمكن للخادم إنشاء مستخدم ClickHouse للقراءة فقط + سياسة صف واحدة لكل منظمة (حد العزل الذي يفرضه المحرك للمحرر الخاص بـ SQL والوكيل الذكي). إذا قدمت تكوين ClickHouse الخاص بك، فنقل هذه الإعدادات (انظر deploy/base/clickhouse/configmap.yaml).
Redis 7+: اختياري ذاكرة تخزين مؤقت مشتركة + خادم حد المعدل. يتصل الخادم والقائمة الأمامية عبر REDIS_URL. إذا كان غير موجود، يتدهور كلاهما برفق إلى مسارات Postgres فقط. انظر Redis (ذاكرة تخزين مؤقت اختيارية) أدناه.

الخادم

سحب الصورة

echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
docker pull ghcr.io/agenteye-enterprise/server:beta-latest

الإصدارات الحالية تُنشر تحت beta-latest؛ يتم تعيين latest فقط للإصدارات المستقرة. للإنتاج، ثبّت علامة إصدار محددة :v<version>؛ انظر علامات الصور المتاحة.

متغيرات البيئة

المتغير	مطلوب	القيمة الافتراضية	الوصف
`DATABASE_URL`	نعم	بلا	DSN خاص بـ Postgres. سلسلة اتصال libpq قياسية بصيغة `postgres://`. يدعم `?sslmode=require` ومعاملات libpq الأخرى. لا يجب أن تحتوي كلمة المرور على `/` أو `+` أو `=`؛ استخدم `openssl rand -hex` لإنشاء كلمات مرور آمنة للعناوين.
`ADMIN_KEY`	لا	بلا	مفتاح API الإدارة التمهيدي. يتم الترقية أو الإدراج مع جميع الأذونات عند كل بدء تشغيل. أدر دوريًا بتغيير القيمة وإعادة التشغيل.
`LISTEN_ADDR`	لا	`0.0.0.0:8080`	عنوان TCP للربط
`MAX_BODY_BYTES`	لا	`134217728` (128 MB)	حد أقصى لحجم طلب الجسم
`ADMIN_EMAIL`	لا	بلا	البريد الإلكتروني لمستخدم الإدارة التمهيدي. يتم الترقية أو الإدراج مع جميع الأذونات عند كل بدء تشغيل ويتم وضع علامة محمية: لا يمكن تعطيله أو تعديل أذوناته عبر لوحة التحكم/API. لتدوير إدارة التمهيد، غيّر `ADMIN_EMAIL` وأعد التشغيل؛ يتم ترقية البريد الإلكتروني الجديد كمحمي، والبريد الإلكتروني السابق يحتفظ بحمايته حتى يتم مسحه يدويًا في قاعدة البيانات.
`ALLOWED_EMAILS`	لا	بلا (الكل محظور)	قائمة بفواصل منفصلة بالبريد الإلكتروني المسموح به لإنشاء المستخدم وتسجيل الدخول. يدعم العناوين الدقيقة (`user@example.com`) ومتغيرات النطاق (`@example.com`). إذا لم يتم التعيين، لا يمكن لأي مستخدم أن ينشئ حسابًا أو يسجل دخول. بذر التمهيد الأول فقط*: يبذر قائمة المنظمة الافتراضية المسموح بها عند التمهيد الأول؛ بعد ذلك صفحة `/<org>/settings` الخاصة بكل منظمة هي مصدر الحقيقة وتغيير متغير البيئة هذا ليس له تأثير.
`SMTP_HOST`	لا	بلا	اسم مضيف خادم SMTP لإرسال رسائل بريد إلكتروني OTP. إذا لم يتم التعيين، يتم تسجيل رموز OTP في stdout بدلاً من ذلك.
`SMTP_PORT`	لا	`587`	منفذ خادم SMTP
`SMTP_USERNAME`	لا	بلا	اسم مستخدم مصادقة SMTP
`SMTP_PASSWORD`	لا	بلا	كلمة مرور مصادقة SMTP
`SMTP_FROM`	لا	بلا	عنوان البريد الإلكتروني للمرسل لرسائل بريد إلكتروني OTP
`SMTP_TLS`	لا	STARTTLS	يتم استخدام STARTTLS ما لم تقم بإيقافه بشكل صريح: `false` أو `0` يرسل نصًا عاديًا (بدون TLS)؛ أي قيمة أخرى — بما في ذلك عدم التعيين — تفعّل STARTTLS.
`DASHBOARD_URL`	لا	القيمة الافتراضية المدمجة	أصل القائمة الأمامية المستخدم لإنشاء كل من ارتباط السحر في رسالة البريد الإلكتروني OTP وارتباطات السحر للحادث في إخطارات التنبيه. إذا لم يتم التعيين، فسيعود إلى قيمة افتراضية مدمجة (وبالنسبة إلى OTP فقط، إلى أصل الطلب المشتق من لوحة التحكم أولاً). اضبط هذا للإعدادات المقسومة حسب النطاق بحيث يشير كل من البريد الإلكتروني وارتباطات Slack/الحادث إلى لوحة التحكم الخاصة بك. انظر عنوان URL لارتباط السحر في البريد الإلكتروني أدناه؛ معظم المشغلين لا يحتاجون إلى تعيين هذا.
`SESSION_TTL_SECS`	لا	`86400` (24 ساعة)	مدة جلسة لوحة التحكم بالثواني. بذر التمهيد الأول فقط: عدّل لكل منظمة عبر `/<org>/settings` بعد النشر الأول.
`OTP_TTL_SECS`	لا	`600` (10 دقائق)	فترة صلاحية رمز OTP بالثواني. بذر التمهيد الأول فقط: عدّل لكل منظمة عبر `/<org>/settings` بعد النشر الأول.
`REDIS_URL`	لا	بلا	ذاكرة تخزين مؤقت مشتركة اختيارية + خادم حد معدل، مثل `redis://redis:6379/0`. عند التعيين، يخزن الخادم عمليات البحث عن مفتاح API المصرح، وإجمالي `/models` القائمة الأمامية، وقائمة الجلسات، وجوانب قائمة البيئة؛ كما أنه ينقل حد معدل طلب OTP من Postgres COUNT إلى Redis INCR. إذا لم يتم التعيين أو لم يكن قابلاً للوصول إليه، يعمل الخادم بدون ذاكرة التخزين المؤقت (حد OTP ينخفض إلى Postgres، وكل نداء ذاكرة تخزين مؤقت آخر ينخفض إلى مصدر الحقيقة). انظر Redis (ذاكرة تخزين مؤقت اختيارية) أدناه.
`CLICKHOUSE_URL`	نعم	بلا	عنوان URL الأساسي لمثيل ClickHouse، مثل `http://clickhouse:8123`. يطبق الخادم مخطط الأحداث الخاص به على قاعدة البيانات هذه عند كل بدء تشغيل ويرفض التمهيد إذا لم يتمكن من الوصول إلى ClickHouse. انظر ClickHouse (مخزن التحليلات المطلوب) أدناه.
`CLICKHOUSE_DATABASE`	لا	`agenteye`	اسم قاعدة بيانات ClickHouse (المخطط). ينشئها الخادم عند بدء التشغيل إذا لم تكن موجودة.
`ORG_CH_SECRET`	لا (أحادي المستأجر) / نعم (متعدد المنظمات)	افتراضي للتطوير	مفتاح HMAC الذي يشتق منه كلمة مرور ClickHouse الخاصة بكل منظمة. يقوم محرر SQL والوكيل الذكي `run_query` بالتنفيذ كمستخدم ClickHouse للقراءة فقط الخاص بالمنظمة، وتفرض سياسة الصف الخاصة به عزل المستأجرين في المحرك. تعمل النشرات أحادية المستأجر بشكل جيد على الافتراضي المدمج للتطوير؛ قبل توفير منظمة ثانية يجب عليك تعيين قيمة قوية ومستقرة، لأن CLI `agenteye-orgctl org create` يرفض الركض على الافتراضي المدمج للتطوير. يؤدي تدويره إلى حذف مستخدم ClickHouse الخاص بكل منظمة حتى إعادة المزامنة التالية عند بدء التشغيل (يشفي المصالحة في وقت التمهيد هذا تلقائيًا). ابقِ محافظًا على سريته وبدون تغيير عبر النسخ المتماثلة. توفير المنظمات نفسه خاص بالمشغل فقط؛ انظر المنظمات (تعدد المستأجرين) أدناه.
`DEFAULT_ORG_NAME`	لا	`Default`	اسم العرض المبذور للمنظمة الافتراضية المدمجة. بذر التمهيد الأول فقط وفقط بينما تحمل المنظمة هويتها العامة المنقولة حديثًا، تم التطبيق عند بدء التشغيل، ثم يتم تجاهله. بمجرد إعادة تسمية المنظمة (`agenteye-orgctl org rename`) تصبح إعادة التسمية موثوقة ولا يكون لمتغير البيئة هذا تأثير آخر.
`DEFAULT_ORG_SLUG`	لا	`default`	عنوان URL slug للمنظمة الافتراضية المدمجة، مسار لوحة التحكم الذي تعيش فيه (`/<slug>/…`). نفس دلالات بذر التمهيد الأول / البذور فقط كما هو الحال مع `DEFAULT_ORG_NAME`. يجب أن يكون 1-40 أحرفًا صغيرة وأرقامًا مع واصلات داخلية واحدة وليس كلمة محجوزة؛ تُتجاهل القيمة غير الصالحة (تحتفظ المنظمة بـ `default`). يسمح لتثبيت أحادي المستأجر بالعرض بـ `/acme` بدلاً من `/default` دون أي خطوة CLI بعد النشر.
`RUST_LOG`	لا	`info`	تفاصيل السجل (`debug`، `warn`، `error`، `agenteye_server=trace`)
`EVALUATOR_ENDPOINT`	لا	بلا	عنوان URL الأساسي لخدمة المقيّم الخاصة بك (مثل `http://evaluator:9000`). عند عدم التعيين، تكون خط أنابيب التقييم بأكمله نو-أوب؛ لا يتم كتابة صفوف الطابور، ولا يعمل أي عمال. انظر مجموعة التقييم.
`EVALUATOR_TOKEN`	لا	بلا	مرسل كـ `Authorization: Bearer <token>` إلى المقيّم. يجب أن يساوي نفس القيمة التي تم تكوين خدمة المقيّم بها. اختياري فقط إذا تم تكوين المقيّم الخاص بك بدون توكن.
`EVALUATOR_WORKERS`	لا	`2`	التزامن: عدد مهام العمل لكل مثيل خادم تُرسل التقييمات. آمن للتشغيل عبر عدة خوادم مدرجة أفقيًا.
`EVALUATOR_CLAIM_BATCH`	لا	`4`	الحد الأقصى لعدد التقييمات التي يطالب بها عامل واحد لكل تكة. يتم إرسال الدفعات بشكل متزامن، لذا فإن إجمالي التزامن على نقطة نهاية المقيّم الخاصة بك هو `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`.
`EVALUATOR_POLL_IDLE_SECS`	لا	`2`	مدة نوم العامل بين محاولات الإرسال عندما لا يكون شيء مستحقًا.
`EVALUATOR_POLLING_INTERVAL_SECS`	لا	`10`	آلية الاستقصاء النهائية (الثواني) لـ `GET /evaluate/{id}` عندما لا يُرجع المقيّم `next_poll_secs` لكل استجابة ولا يعلن `default_poll_interval_secs` من `GET /config`.
`EVALUATOR_REQUEST_TIMEOUT_MS`	لا	`30000`	انتظار HTTP لكل طلب ضد المقيّم (بالميلي ثانية).
`EVALUATOR_MAX_ATTEMPTS`	لا	`5`	بعد هذا العدد من المحاولات الفاشلة يتم تسجيل التقييم كخطأ نهائي `error` (أو `timeout` إذا كانت الإخفاقات طلبات المهلة الزمنية).
`EVALUATOR_CONFIG_REFRESH_SECS`	لا	`300` (5 دقائق)	بأي تكرار يعيد الخادم جلب `GET /config` من المقيّم.
`EVALUATOR_MAX_POLL_DURATION_SECS`	لا	`3600` (ساعة واحدة)	الحد الأقصى لوقت الجدار الذي قد تبقى فيه جلسة واحدة في طابور الاستقصاء قبل أن ينهيها AgentEye كـ `timeout`. حماية ضد مقيّم يعود `pending` للأبد.
`ALERT_WORKERS`	لا	`1`	التزامن: عدد مهام العمل لكل مثيل خادم التي تقيّم قواعد التنبيه. انظر التنبيهات.
`ALERT_CLAIM_BATCH`	لا	`16`	الحد الأقصى لعدد التنبيهات التي يطالب بها عامل واحد لكل تكة.
`ALERT_POLL_IDLE_SECS`	لا	`5`	مدة نوم عامل التنبيهات عندما يكون الطابور فارغًا.
`ALERT_REQUEST_TIMEOUT_MS`	لا	`15000`	انتظار لكل تقييم محفز (استعلامات ClickHouse + HTTP قنوات صادرة).
`ALERT_MAX_ATTEMPTS`	لا	`5`	إخفاقات عابرة متتالية قبل أن يُعاد جدولة التنبيه بالتكرار الطبيعي بدلاً من التراجع الأسي.
`AUDIT_WORKERS`	لا	`1`	التزامن: عدد مهام العمل لكل مثيل خادم التي تنفذ التدقيقات. انظر التدقيقات.
`AUDIT_CLAIM_BATCH`	لا	`1`	الحد الأقصى لعدد التدقيقات المستحقة التي يطالب بها عامل واحد لكل تكة. التحقيق الاستشعاري الواحد هو حلقة طويلة واحدة، لذا الافتراضي هو 1.
`AUDIT_POLL_IDLE_SECS`	لا	`30`	مدة نوم عامل التدقيق عندما لا يكون أي تدقيق مستحقًا.
`AUDIT_REQUEST_TIMEOUT_MS`	لا	`30000`	انتظار لكل استعلام سياسة ضد ClickHouse (بالميلي ثانية).
`AUDIT_LLM_TIMEOUT_MS`	لا	`1440000`	المهلة الزمنية لاستدعاء التحقيق الاستشعاري لخدمة مساعد AI. تعمل حلقة عميل كاملة لعدة دقائق؛ ابقِ هذا فوق `AGENTEYE_AUDIT_TIMEOUT_MS` الخاص بالعميل بحيث يعود العميل بنتائجه الجزئية قبل أن يستسلم الخادم.
`AUDIT_MAX_ATTEMPTS`	لا	`5`	إخفاقات عابرة متتالية قبل أن يُعاد جدولة التدقيق بالتكرار الطبيعي بدلاً من التراجع الأسي.
`AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN`	لا	—	يستدعي التحقيق الاستشعاري خدمة المساعد الذكي `agent`، معاد استخدام نفس الاتصال مع المساعد — لذا اضبط هذين على الخادم أيضًا (تفعل المظاهر/الحزم المجمعة). كلاهما مضبوط ⇒ تعمل التدقيقات على التحقيق الذكي؛ أي واحد غير مضبوط ⇒ تعمل التدقيقات سياسة فقط (تمر السياسة SQL الحتمية لا تزال تعمل)، بغض النظر عن علم `llm_enabled` لكل تدقيق. يجب أن يكون لدى العميل أيضًا نموذج لغة مُعد — انظر assistant.md.

خدمة مساعد AI — إعدادات التدقيق والصندوق الرملي. يتم ضبط التحقيق الاستشعاري والصندوق الرملي الخاص به داخل القرية على خدمة العميل (وليس الخادم)، الكل على بادئة AGENTEYE_AUDIT_* وكل اختياري:

المتغير	الافتراضي	المعنى
`AGENTEYE_AUDIT_MAX_STEPS`	`200`	أقصى أدوار عميل لكل تحقيق.
`AGENTEYE_AUDIT_TIMEOUT_MS`	`1200000`	جدار الساعة لتحقيق واحد (20 دقيقة). يجب أن يبقى تحت `AUDIT_LLM_TIMEOUT_MS` الخاص بالخادم.
`AGENTEYE_AUDIT_MAX_CONCURRENCY`	`1`	تحقيقات متزامنة لكل وحدة عميل (منفصلة عن ميزانية مساعد الدردشة).
`AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES`	`20000` / `768` / `10` / `64000` / `64000`	حدود لكل برنامج نصي للصندوق الرملي bubblewrap.

متطلب منصة الصندوق الرملي. يعمل صندوق الرملي الخاص بتدقيق الكود من خلال Python النموذج داخل سجن bubblewrap، والذي يحتاج إلى مسافات أسماء المستخدم غير المتميزة. يجب أن تسمح وحدة العميل بعلامات clone() — اضبط seccompProfile: Unconfined (k8s) أو security_opt: [seccomp:unconfined] (compose) على العميل. حيث يعطّل نواة العقدة مسافات الأسماء غير المتميزة (مثل بعض صور COS في GKE)، فإن الفحص المسبق للصندوق الرملي يفشل والمدقّق ينحط إلى SQL فقط تلقائيًا — لا خطأ، فقط sandbox_available: false على /health الخاص بالعميل.

التشغيل

اضبط DATABASE_URL في بيئتك، ثم مرره عبر الحاوية:

docker run -d --restart unless-stopped \
  --name agenteye-server \
  -e DATABASE_URL="$DATABASE_URL" \
  -e ADMIN_KEY="$ADMIN_KEY" \
  -p 8080:8080 \
  ghcr.io/agenteye-enterprise/server:beta-latest

يقوم الخادم بتشغيل هجرات قاعدة البيانات تلقائيًا عند بدء التشغيل؛ لا توجد خطوة هجرة منفصلة مطلوبة.

فحص الصحة

GET /health    # liveness  - دائمًا {"status":"ok"} بمجرد أن تكون العملية مرفوعة
GET /ready     # readiness - 200 عندما يكون Postgres + ClickHouse قابلين للوصول، وإلا 503

لا يوجد مصادقة مطلوبة. استخدم /health لمسابر liveness و /ready لمسابر readiness / موازن التحميل. يتحقق /ready من التبعيات الصعبة التي لا يستطيع الخادم العمل بدونها (Postgres + ClickHouse)، لذا فإن الخادم الذي يعمل لكن لا يستطيع الوصول إلى قاعدة بيانات يتم إخراجه من التدوير ويظهر كـ NotReady؛ يتم الإبلاغ عن Redis لكنه لا يفشل في الاستعداد أبدًا. على المظاهر Kubernetes المجمعة، تشير مسبار الاستعداد بالفعل إلى /ready ويبقى liveness على /health. انظر enterprise-docs/health-monitoring.md للصورة الكاملة، بما في ذلك تنبيهات فشل القرية الأصلية Kubernetes المدمجة إلى Slack.

عنوان URL لارتباط السحر في البريد الإلكتروني

رسائل البريد الإلكتروني OTP تتضمن زر افتح لوحة التحكم على نقرة واحدة. سيؤدي النقر عليه إلى هبوط المستخدم على /login?token=<code>&email=<address>؛ تتبادل لوحة التحكم هذا الزوج لجلسة وتعيد التوجيه إلى التطبيق، بدون إعادة إدخال يدوية للرمز. يحل الخادم أصل لوحة التحكم المستخدم لإنشاء الارتباط في ثلاث طبقات:

رأس X-AgentEye-Dashboard-Url: يتم تعيينه تلقائيًا بواسطة وكيل /api/auth/otp/request الخاص بالقائمة الأمامية من أصله العام الخاص. في نشر نفس الأصل (الخادم والقائمة الأمامية يشتركان في مضيف خلف ingress واحد يعيد توجيه رؤوس الوكيل)، لا يلزم أي تكوين.
متغير البيئة DASHBOARD_URL: اضبط هذا إذا كانت لوحة التحكم الخاصة بك قابلة للوصول على أصل مختلف عن الذي يراه نقطة نهاية طلب OTP الخاصة بالخادم (انقسام api.example.com / app.example.com)، أو إذا لم يقم ingress الخاص بك بنشر المضيف العام في وحدة القائمة الأمامية (بحيث request.nextUrl.origin سيحل بطريقة أخرى إلى ربط بدل مثل 0.0.0.0:3000). مثال: DASHBOARD_URL=https://app.example.com.
الافتراضي: https://app.befailproof.ai، مستخدم فقط إذا لم يكن أي من الأعلى موجودًا.

يتم التحقق من قيمة الرأس: فقط أصول https://* و loopback (http://localhost*، http://127.0.0.1*) مقبول، ويتم رفض عناوين ربط البدل (0.0.0.0، [::]) حتى مع مخطط https://. أي شيء آخر ينخفض عبر الطبقة 2. اضبطه على مجموعة تشغيل باستخدام أمر سطر واحد؛ بدون ملف، بدون إعادة بناء kustomize:

kubectl set env deployment/server -n agenteye \
  DASHBOARD_URL=https://app.example.com

هذا ينجز تطوير؛ تختار الوحدات الجديدة القيمة عند أول طلب. لاحظ أن الإلغاء يعيش فقط على النشر؛ kustomize build | kubectl apply لاحقة ضد الإضافة الخاصة بك ستمسحها ما لم تضف نفس متغير البيئة إلى server-env.yaml الخاص بك.

القائمة الأمامية

سحب الصورة

docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest

متغيرات البيئة

المتغير	مطلوب	القيمة الافتراضية	الوصف
`AGENTEYE_SERVER_URL`	نعم	بلا	عنوان URL الأساسي للخادم، مثل `http://localhost:8080`
`AGENTEYE_API_KEY`	نعم	بلا	مفتاح API الذي تستخدمه لوحة التحكم للمصادقة مع الخادم. يحتاج إلى جميع الأذونات (مفتاح الإدارة موصى به).
`AE_LOG_LEVEL`	لا	`info`	تفاصيل السجل من جانب الخادم: `debug`، `info`، `warn`، `error`. اضبط على `debug` لرؤية أسطر الطلب/الرد المرسل والتتبع ضمن التحقق من صحة الجلسة عند تشخيص المشاكل.
`AE_LOG_JSON`	لا	auto	`1` يفرض إخراج JSON لكل سطر؛ `0` يفرض إخراج قابل للقراءة من قبل البشر. عند عدم التعيين، يتم تفعيل JSON تلقائيًا إذا كان `NODE_ENV=production`. يُنصح به JSON في الإنتاج بحيث تُحلل السجلات بشكل نظيف مع `jq` أو محمع سجلات.
`AE_ANALYTICS_DISABLED`	لا	بلا	اضبط على `1`/`true` لتعطيل قياس الاستخدام المجهول للمنتج الخاص بالقائمة الأمامية. انظر البيانات الوصفية والخصوصية أدناه.
`REDIS_URL`	لا	بلا	خادم ذاكرة تخزين مؤقت مشترك اختياري، مثل `redis://redis:6379/0`. عند التعيين، تخزن لوحة التحكم نتائج `validateSession()` عبر النسخ المتماثلة وتشارك ذاكرة التخزين المؤقت جلب Next.js لطرق وكيل الإجمالي الكامن / البيئة قائمة. حدود معدل طلب OTP والتحقق من OTP على الحافة تستخدم أيضًا Redis عند وجودها (الفشل المفتوح إذا كان Redis غير قابل للوصول؛ حد الخادم من الجانب الآمن هو backstop الأمان). انظر Redis (ذاكرة تخزين مؤقت اختيارية) أدناه.
`AGENTEYE_AGENT_URL`	لا	بلا	عنوان URL الأساسي لخدمة المساعد الذكي `agent` الاختيارية، مثل `http://agent:9100`. تركه بدون تعيين لإخفاء المساعد بالكامل: لا يظهر فقاعة مساعد في لوحة التحكم. انظر enterprise-docs/assistant.md.
`AGENTEYE_AGENT_TOKEN`	لا	بلا	السر المشترك الذي تعرضه لوحة التحكم لخدمة `agent`. يجب أن يتطابق مع `AGENTEYE_AGENT_TOKEN` المُعد على العميل. انظر enterprise-docs/assistant.md.

التشغيل

docker run -d --restart unless-stopped \
  --name agenteye-dashboard \
  -e AGENTEYE_SERVER_URL="http://your-server-host:8080" \
  -e AGENTEYE_API_KEY="$ADMIN_KEY" \
  -p 3000:3000 \
  ghcr.io/agenteye-enterprise/dashboard:beta-latest

البيانات الوصفية والخصوصية

تُرسل لوحة التحكم قياس الاستخدام المجهول للمنتج إلى خدمة تحليل Exosphere (PostHog): صفحات لوحة التحكم التي يتم عرضها وحفنة من إجراءات واجهة المستخدم مثل إنشاء مفتاح API أو إعادة تقييم جلسة. تُخبر إشارة الاستخدام هذه ميزات الأولويات التي يتم تحديدها.

لا تغادر بيانات الوكيل أو الجلسة أو الحدث البنية التحتية الخاصة بك أبدًا. يتم الإبلاغ عن استخدام واجهة مستخدم لوحة التحكم فقط. يتم تجريد عناوين URL للصفحة من المعرفات قبل الإرسال، ويتم تحديد هويات المشغلين فقط بمعرّف داخلي معتم، وليس عبر البريد الإلكتروني.
البيانات الوصفية مفعّلة افتراضيًا. لإيقافها تمامًا، اضبط AE_ANALYTICS_DISABLED=1 على حاوية القائمة الأمامية وأعد التشغيل.
يتم إرسال البيانات الوصفية إلى مسار /ingest الخاص بلوحة التحكم الخاصة، الذي تعيد توجيهه لوحة التحكم إلى PostHog (https://us.i.posthog.com). إن إبقاء الطلبات من الطرف الأول يعني أن حاجبات الإعلانات الخاصة بمتصفح لن تسقطها. حاوية القائمة الأمامية تحتاج إلى وصول صادر إلى PostHog؛ إذا تم حظره، لا تفعل البيانات الوصفية شيئًا بصمت وتبقى لوحة التحكم غير متأثرة.

مساعد AI (اختياري)

يسمح مساعد AI داخل لوحة التحكم لفريقك بطرح أسئلة حول بيانات وكيلهم باللغة الطبيعية (تلخيص الجلسات، وصياغة SQL لمحرر /queries، وتحويل الاستعلامات المحفوظة إلى بلاطات لوحة التحكم) دون ترك لوحة التحكم. يعمل كحاوية agent داخلية منفصلة (على Agents SDK) التي يمكن فقط للقائمة الأمامية الوصول إليها، ويبقى معطلاً حتى تقوم بتكوين نقطة نهاية LLM. لتفعيله تضبط، على خدمة agent، اتصال LLM (Portkey عبر PORTKEY_API_KEY + slug كتالوج النموذج AGENTEYE_AGENT_MODEL=@<slug>/<model>، Anthropic مباشر عبر ANTHROPIC_API_KEY، بوابة أخرى عبر ANTHROPIC_BASE_URL، أو Bedrock/Vertex)، مفتاح بيانات مخصص، و AGENTEYE_AGENT_TOKEN مشترك يطابق لوحة التحكم. يحتاج مستخدمو لوحة التحكم أيضًا إلى إذن agent:use. بالنسبة لمفتاح بيانات المساعد، لا تُصنع أي شيء يدويًا: اختر سرًا عشوائيًا، اضبطه كـ AGENTEYE_API_KEY على agent و كـ AGENT_API_KEY على server، وينشئ الخادم ميزة مجموعة أذونات ثابتة عند بدء التشغيل. وصول البيانات الخاص به يكون للقراءة فقط (events:read، evaluations:read، dashboards:read، queries:read)، وبالإضافة إلى ذلك يحمل نطاقات تأليف بوابة موافقة (dashboards:write، queries:write، queries:run) بحيث يمكنه صياغة والتحقق من صحة الاستعلامات المحفوظة وبناء بلاطات لوحة التحكم نيابة عن المستخدم؛ لا يزال كل SQL يعمل من خلال دور ClickHouse للقراءة فقط الخاص بالمنظمة، لذا يوسع هذا ما يمكن للمساعد تأليفه، وليس البيانات التي يمكنه الوصول إليها. يتم إصلاح النطاقات في الكود ولا يمكن توسيعها بواسطة التكوين. هذا المفتاح محمي؛ لا يمكن تعطيله أو إعادة توليده عبر API، فقط إعادة تدويره بتغيير القيمة وإعادة التشغيل. لا تعيد استخدام مفتاح الإدارة/لوحة التحكم لهذا. الإعداد الكامل، ومرجع متغير البيئة الكامل، وخيارات البيانات الوصفية، والنموذج الأمني موجود في enterprise-docs/assistant.md.

ClickHouse (مخزن التحليلات المطلوب)

يحافظ ClickHouse على استجابة لوحات التحكم الخاصة بك عند مجلدات الأحداث العالية ويسمح لمحرر SQL /queries بالانضمام عبر الأحداث والتقييمات والجلسات في متجر واحد. إنه متجر قانوني مطلوب لكل حدث مُدخَل، وكل نتيجة تقييم نهائية، والمجاميع المشتقة لكل جلسة. يحتفظ PostgreSQL بجداول الحالة القابلة للتغيير (api_keys، users، otp_codes، evaluation_jobs، dashboards، saved_queries)؛ السطح التحليلي يعيش في ClickHouse بحيث يمكن لتجميعات لوحة التحكم والاستعلامات الخاصة بك الفحص والانضمام بشكل أصلي، بدون round-trips قاعدة بيانات متقاطعة. يرفض الخادم التمهيد بدون CLICKHOUSE_URL.

المخطط

يتم إنشاء ثلاثة كائنات ClickHouse عند بدء تشغيل الخادم، الكل idempotent (CREATE IF NOT EXISTS):

agenteye.events: ReplacingMergeTree(ingested_at)، مقسم حسب toYYYYMM(ts)، مرتب حسب (session_id, ts, dedup_key). تسقط الإدراجات المكررة (إعادة محاولات المجمع) إلى صف واحد في وقت الدمج؛ يحسب الخادم dedup_key SHA-256 حتمي لكل حدث بحيث تكون إعادة المحاولات آمنة.
agenteye.evaluations: ReplacingMergeTree(ingested_at)، مقسم حسب toYYYYMM(finished_at)، مرتب حسب (session_id, finished_at, dedup_key). كتب مرة واحدة لكل نتيجة تقييم نهائية بواسطة خط أنابيب المقيّم. نموذج dedup-key نفسه كما هو الحال في events.
agenteye.agent_sessions: VIEW عبر agenteye.events، وليس جدول مادي. كل عمود مشتق (started_at = min(ts)، last_event_at = max(ts)، ended_at = max(if event_type='agent_end', ts, NULL)، event_count = count()، إلخ). لا upsert لكل حدث ولا ملء منفصل؛ يعكس العرض تلقائيًا كل ما هو في events.

من أجل التوافقية للخلف مع الاستعلامات المحفوظة التي تشير إلى analytics.evaluations / analytics.sessions، ينشئ الخادم أيضًا قاعدة بيانات analytics ClickHouse مع عروض عبر جداول agenteye.*؛ analytics.events، analytics.evaluations، analytics.agent_sessions، analytics.sessions جميعها تحل بشكل صحيح.

التكوين

توفير docker-compose المجمع و deploy/base/clickhouse/ خدمة ClickHouse محسّنة لعبء عمل AgentEye:

2 GiB مطلوب / 4 GiB حد الذاكرة في الإضافة الأساسية المشحونة (بحجم تناسب عقد POC/staging الصغيرة)؛ يجب على عملاء الإنتاج ترقية الإضافة — الأرضية الموصى بها هي 2c / 4Gi الطلب، 6c / 8Gi الحد. max_server_memory_usage_to_ram_ratio=0.9
ذاكرة تخزين مؤقت 5 GiB علامة + 8 GiB ذاكرة غير مضغوطة
background_pool_size=16، background_merges_mutations_concurrency_ratio=2
MergeTree: parts_to_throw_insert=3000، parts_to_delay_insert=1500، non_replicated_deduplication_window=1000
local_io_method=auto (io_uring على النوى المدعومة)
fsync_metadata=0: قابل للقبول بسبب ضمان على الأقل مرة واحدة ingest + ReplacingMergeTree dedup
query_log مفعّل مع TTL 30 يوم؛ تم إزالة query_thread_log (مكلفة عند QPS عالي)
max_execution_time=30 للاستعلامات من جانب المستخدم
PVC 100 GiB في قالب StatefulSet (يجب على الإضافات الخاصة بالعميل تجاوز فئة التخزين SSD السريع للإنتاج)

النسخ الاحتياطية

يتم التقاط المجموعة البيانات الكاملة الخاصة بك كل ليلة في أرشيف استعادة واحد، لذا فإن فقدان المجموعة أو التخزين قابل للاسترجاع. يتم عمل نسخة احتياطية من ClickHouse تلقائيًا بواسطة CronJob agenteye-backup اليومي، الذي يُفرغ PostgreSQL و ClickHouse في مسار واحد. يتم قراءة ClickHouse عبر HTTP API الخاص به: يتم تفريغ agenteye.events و agenteye.evaluations بتنسيق ClickHouse الأصلي (يتم إعادة إنشاء العروض وسياسات الصفوف بواسطة الخادم عند بدء التشغيل، لذا بيانات الجدول هي الصورة الكاملة) وتجميعها مع تفريغ Postgres في أرشيف مضغوط واحد تم تحميله إلى التخزين الموضوعي الخاص بك. يتم تكوين الدلو الوجهة وبيانات اعتماد السحابة لكل إضافة. انظر قسم النسخ الاحتياطية من enterprise-docs/kubernetes-deployment.md لتكوين التحميل وخطوات الاستعادة.

Redis (ذاكرة تخزين مؤقت اختيارية)

Redis هي ذاكرة تخزين مؤقت مشتركة اختيارية + خادم حد معدل يستخدمه الخادم والقائمة الأمامية. مع Redis المنشرة و REDIS_URL المضبوط على كلا الخدمتين:

الخادم يخزن بحثًا مفتاح API مصرح، قوائم /events/environments + /evaluations/environments، إجمالي /events/latency_aggregate (الاستعلام الأثقل الذي تستقصيه لوحة التحكم)، قائمة /sessions، وينقل معدل حد طلب OTP من COUNT(*) Postgres إلى Redis INCR + EXPIRE.
القائمة الأمامية تخزن نتائج validateSession() بحيث تشارك مكالمات API المصرحة 10-20 لتحميل صفحة نموذجية فحص جلسة رفع واحد. كما تعدّل معدل طلب OTP والتحقق من OTP في حافة لوحة التحكم.

كلا الخدمتين يتدهوران برفق إذا كان Redis غير قابل للوصول إليه. كل نداء ذاكرة تخزين مؤقت يعود Err في انتظار محدود والمستدعي ينخفض إلى مصدر الحقيقة (Postgres على الخادم، الخادم Rust الرفع على لوحة التحكم). يسقط معدل حد OTP إلى مسار COUNT(*) Postgres على الخادم (الخاصية الأمان تُحفظ)؛ حد حافة OTP الخاص بلوحة التحكم ينفتح بينما حد من الجانب الخادم لا يزال ثابتًا. Redis كونه معطلاً يتدهور الكمون، وليس الصحة.

التكوين

حزمة docker-compose بالفعل تتضمن خدمة Redis وتسلك REDIS_URL=redis://redis:6379/0 في الخادم والقائمة الأمامية. لاستخدام Redis خارجي، اضبط REDIS_URL على نقطة النهاية الخاصة بك وأزل خدمة redis من ملف الإنشاء.

الذاكرة والمثابرة

تعمل صورة Redis المجمعة مع --appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru. إن AOF المثابرة تعني أن ذاكرة التخزين المؤقت تنجو من إعادة تشغيل الحاوية؛ everysec هي الموازنة الصحيحة بين المتانة والأداء لأن فقدان كتابات ذاكرة التخزين المؤقت الثانية الأخيرة بلا ضرر. سقط الإزالة يحد من نمو الذاكرة.

عندما لا يتم نشر Redis

تطوير/QA مثيل واحد. ذاكرات التخزين المؤقت داخل العملية على الخادم وحده توفر معظم الفائدة لكل نسخة؛ تضيف Redis المشاركة عبر النسخ المتماثلة التي لا تحتاج إليها إعدادات المثيل الواحد.
التثبيتات المنقطعة عن الشبكة حيث تفوق التكلفة التشغيلية لتشغيل خدمة أخرى فائدة الكمون.

Docker Compose (موصى به)

docker-compose.yml متاح في agenteye-enterprise/releases repo. يحضر Postgres والخادم والقائمة الأمامية بأمر واحد.

GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \
  --repo agenteye-enterprise/releases \
  --pattern 'docker-compose.yml' \
  --dir ./agenteye
cd agenteye

تجاوز الافتراضيات عبر .env:

# استخدم كلمات مرور آمنة للعناوين (لا /, +, أو =).
# توليد باستخدام: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# مصادقة لوحة التحكم
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# SMTP لرسائل بريد إلكترونية OTP (حذف لتسجيل رموز OTP في stdout)
# SMTP_HOST=smtp.yourprovider.com
# SMTP_PORT=587
# SMTP_USERNAME=your-smtp-user
# SMTP_PASSWORD=your-smtp-password
# SMTP_FROM=noreply@yourcompany.com

RUST_LOG=info

docker compose up -d

التوقف (يحافظ على حجم البيانات):

docker compose down

التوقف والمسح النظيف لجميع البيانات:

docker compose down -v

الإعدادات التشغيلية

مجموعة صغيرة من مقابض التشغيل التي كانت مثبتة بواسطة متغيرات البيئة يمكن الآن تحريرها لكل منظمة من صفحة /<org>/settings الخاصة بلوحة التحكم؛ تكوّن كل منظمة ملكها. تُصبح التغييرات ساري المفعول خلال ثوانٍ، بدون إعادة تشغيل وبدون إعادة نشر.

الإعداد	متغير البيئة التمهيدي	ما الذي يتحكم
السماح بعمليات تسجيل الدخول	`ALLOWED_EMAILS`	رسائل بريد إلكترونية (أو `*@domain.com` من الأحرف الكبيرة) مسموح بها لاستقبال OTP وإضافة كمستخدمين
أذونات المستخدم الافتراضية	`DEFAULT_USER_PERMISSIONS`	رموز الأذونات المفصولة بفاصلة محددة مسبقًا عند فتح إدارة + مستخدم جديد. يجب أن يكون كل رمز واحدًا من السلاسل المدرجة تحت أذونات مفتاح API. الافتراضي هو معيار `standard`: وصول للقراءة فقط بالإضافة إلى إجراءات يومية في الخدمة (تقييمات إعادة التشغيل، استعلامات مسموح، حوادث ack، استخد

​title: “النشر” description: “وثائق نشر AgentEye.”

​نظرة عامة على العمارة

​الخادم

​سحب الصورة

​متغيرات البيئة

​التشغيل

​فحص الصحة

​عنوان URL لارتباط السحر في البريد الإلكتروني

​القائمة الأمامية

​سحب الصورة

​متغيرات البيئة

​التشغيل

​البيانات الوصفية والخصوصية

​مساعد AI (اختياري)

​ClickHouse (مخزن التحليلات المطلوب)

​المخطط

​التكوين

​النسخ الاحتياطية

​Redis (ذاكرة تخزين مؤقت اختيارية)

​التكوين

​الذاكرة والمثابرة

​عندما لا يتم نشر Redis

​Docker Compose (موصى به)

​الإعدادات التشغيلية

title: “النشر” description: “وثائق نشر AgentEye.”

نظرة عامة على العمارة

الخادم

سحب الصورة

متغيرات البيئة

التشغيل

فحص الصحة

عنوان URL لارتباط السحر في البريد الإلكتروني

القائمة الأمامية

سحب الصورة

متغيرات البيئة

التشغيل

البيانات الوصفية والخصوصية

مساعد AI (اختياري)

ClickHouse (مخزن التحليلات المطلوب)

المخطط

التكوين

النسخ الاحتياطية

Redis (ذاكرة تخزين مؤقت اختيارية)

التكوين

الذاكرة والمثابرة

عندما لا يتم نشر Redis

Docker Compose (موصى به)

الإعدادات التشغيلية