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

تقدم هذه الصفحة نظرة معمقة على بنية AuroraSOC للمطورين الذين يساهمون في المنصة أو يوسعونها. فهم هذه البنية ضروري قبل تعديل أي مكون.

إذا كنت جديدًا على قاعدة الشفرة، فاقرأ الصفحة كاملة مرة واحدة ثم عد إلى الصفحات المتخصصة المرتبطة في نهايتها.

يعتمد المكدس الافتراضي في Compose على مسار Python API ومعالجة الأحداث في بايثون. فعّل --profile rust-core فقط عندما تحتاج إلى المسار السريع الاختياري للـ ingest عالي الإنتاجية أو لأحمال عمل التوثيق والتحقق السريع.

إذا كنت تبحث عن مسار التشغيل العملي للمشغلين، فابدأ من نشر أسطول وكلاء الذكاء الاصطناعي ثم عُد إلى هذه الصفحة عندما تحتاج إلى تفاصيل التنفيذ.

متى تستخدم هذه الصفحة

استخدم هذه الصفحة قبل أن تقوم بـ:

• إضافة وكلاء أو أدوات أو أحداث أو تكاملات تخزين جديدة
• تغيير توجيه الرسائل أو تنفيذ المهام أو سلوك API
• التخطيط لاختبارات الأداء أو أعمال التقوية للإنتاج

المتطلبات المعرفية المسبقة

الخلفية الموصى بها قبل تعديل البنية:

• إلمام ببرمجة Python غير المتزامنة مع asyncio وFastAPI وSQLAlchemy
• فهم أساسي لمجموعات المستهلكين في Redis Streams
• إلمام بشبكات الحاويات في Compose وأسماء الخدمات
• معرفة عملية بأساسيات OpenTelemetry وPrometheus

البنية عالية المستوى

في النشر الافتراضي، يكون المسار الفعّال لاستيعاب أحداث الحافة هو MQTT_S --> PY_EDGE --> REDIS_S. تظهر عقدة Rust فقط عندما يتم تمكين --profile rust-core.

هيكل المشروع

AuroraSOC/
├── aurorasoc/              # الواجهة الخلفية الرئيسية ببايثون
│   ├── agents/             # 13 وكيلًا متخصصًا + المنسق + prompts
│   ├── api/                # تطبيق FastAPI
│   ├── config/             # إعدادات Pydantic للأنظمة الفرعية
│   ├── core/               # المصادقة، قاعدة البيانات، التسجيل، التتبع
│   ├── engine/             # محرك SOAR playbooks
│   ├── events/             # Redis Streams وNATS وMQTT consumers
│   ├── workers/            # عمال Redis stream لتنفيذ مهام الوكلاء
│   ├── memory/             # نظام الذاكرة ثلاثي الطبقات
│   ├── models/             # Pydantic domain models + enums
│   ├── services/           # جدولة الخلفية
│   ├── tools/              # أكثر من 50 أداة MCP
│   └── workflows/          # BeeAI AgentWorkflows
├── rust_core/              # المسار السريع الاختياري بلغة Rust
│   └── src/                # التطبيع وsecurity middleware والناشرون
├── dashboard/              # الواجهة الأمامية Next.js 15
│   └── src/                # مكونات React وZustand وعميل API
├── firmware/               # ثلاث منصات firmware
│   ├── esp32s3/            # Zephyr RTOS (C)
│   ├── nrf52840/           # Embassy-rs (Rust)
│   └── stm32/              # Ada SPARK (Ada)
├── infrastructure/         # Docker والمراقبة وإعدادات الوسطاء
├── tests/                  # حزمة pytest
├── alembic/                # ترحيلات قاعدة البيانات
└── docs/                   # موقع Docusaurus

تفاعلات المكونات

مسار الطلب: التحقيق في الإنذار

تدفق بيانات التشغيل في مسار العامل

يكمل هذا التدفق المسار المرتبط بـ API أعلاه ويركز على سلوك العامل عند الارتباط والربط بين النتائج.

مبادئ التصميم

1. التدهور المتدرج

سلوك التدهور هنا مقصود ويعتمد على وضع التشغيل:

• تعطل PostgreSQL في وضع dummy -> يمكن لبعض واجهات القراءة المختارة أن تعرض بيانات showcase داخل الذاكرة
• تعطل PostgreSQL في dry_run أو real -> تفشل القراءات المعتمدة على قاعدة البيانات بوضوح بدلاً من الاستبدال الصامت ببيانات عرض
• تعطل Redis -> تتراجع بعض آليات الحماية التشغيلية إلى بدائل داخل الذاكرة عندما يكون ذلك مطبقًا صراحةً
• تعطل pgvector -> تتراجع ذاكرة الوكيل إلى الذاكرة العاملة فقط
• تعطل وكيل -> تمنع circuit breakers والمهلات الفشل المتسلسل

2. التكوين قبل تعديل الشفرة

كل السلوكيات قابلة للضبط عبر متغيرات البيئة بقيم افتراضية مناسبة. لا تحتاج إلى تعديل الشفرة من أجل:

• تبديل مزود LLM
• تغيير المنافذ
• تغيير سلاسل الاتصال
• تفعيل أو تعطيل الخصائص
• تعديل حدود المعدل

3. فصل المسؤوليات

لكل وحدة مسؤولية واحدة:

• agents/ إنشاء الوكلاء وتكوينهم
• tools/ تكامل الأنظمة الخارجية
• events/ نقل الرسائل
• memory/ حفظ المعرفة
• engine/ تنفيذ playbooks
• core/ الاهتمامات المشتركة مثل auth وlogging وtracing

4. Event Sourcing Lite

رغم أن AuroraSOC ليس نظامًا قائمًا بالكامل على event sourcing، فإنه يسجل تغيرات الحالة في Redis Streams بما يوفر:

• سجل تدقيق كامل
• القدرة على إعادة تشغيل الأحداث
• فك الارتباط بين المنتجين والمستهلكين

مصفوفة الفشل والاسترداد

وضع الفشل	إشارة الاكتشاف	السلوك الفوري	إستراتيجية الاسترداد
تعطل نقطة A2A	probe عند البدء + خطأ dispatch	بدء متدهور مع circuit breaker	استعادة الخدمة وإعادة فتح breaker بنجاح
تعطل PostgreSQL	فشل health checks أو الاستعلامات	API يعيد استجابات متدهورة لبعض الواجهات	استعادة DB وإعادة المحاولات اللازمة
ازدياد تأخر Redis streams	مؤشرات lag وretry وdead-letter	ازدياد زمن التحقيق	زيادة عدد العمال وفحص المعالجات البطيئة
عدم تطابق correlation	ارتفاع aurora_agent_results_unmatched_total	قد تنتهي futures بمهلة	التحقق من correlation IDs وبنية payload
تعارض منفذ metrics	تحذير عند بدء العامل	العامل يكمل من دون منفذ metrics محلي	تغيير AGENT_TASK_WORKER_METRICS_PORT وإعادة التشغيل

اعتبارات الأداء

المسار الحساس للزمن

أكثر المسارات حساسية للزمن هو:

1. نشر المهمة من API
2. استهلاك العامل للمهمة وتوزيعها
3. نشر النتيجة وربطها
4. استجابة API أو بث WebSocket

المؤشرات التي يجب مراقبتها:

• aurora_agent_task_worker_task_duration_ms
• aurora_agent_result_correlation_latency_ms
• aurora_agent_result_futures_pending

مفاتيح تحسين الإنتاجية

المفتاح	الموقع	التأثير
REDIS_BATCH_SIZE	العامل والمستهلكون	إنتاجية أعلى مع احتمال زيادة التقطع
REDIS_BLOCK_MS	مستهلكو الـ streams	تقليل overhead مع تأثير على سرعة الاستجابة
عدد نسخ العامل	النشر أو compose	موازاة أعلى لمعالجة المهام
مهلات A2A	طبقة dispatch	تمنع التعليق الطويل أثناء الأعطال الجزئية

صفحات ذات صلة

• Redis Streams
• توزيع المنسق
• المراقبة
• REST Endpoints

مصفوفة قرارات مجموعة التكنولوجيا

المكون	التكنولوجيا	سبب الاختيار	البدائل المدروسة
إطار AI	BeeAI	دعم أصلي لـ A2A وMCP	LangChain, CrewAI, AutoGen
API	FastAPI	غير متزامن وآمن نوعيًا ويدعم OpenAPI	Django, Flask, Express
ORM	SQLAlchemy 2.0	ناضج وغير متزامن وآمن نوعيًا	Tortoise ORM, Prisma
ناقل الأحداث	Redis Streams	زمن انتقال منخفض ومجموعات مستهلكين	Kafka, RabbitMQ
الاتحاد	NATS JetStream	خفيف الوزن مع استمرارية	Kafka, Pulsar
نقل IoT	MQTT v5	معيار صناعي ويدعم QoS	AMQP, CoAP
البحث المتجهي	pgvector	بساطة قاعدة واحدة وفهارس HNSW	Qdrant, Pinecone, Weaviate, Milvus
المحرك الأساسي	Rust (اختياري)	مسار سريع للتطبيع والتوثيق	Go, C++
الواجهة الأمامية	Next.js 15	SSR وReact وTurbopack	Nuxt, SvelteKit
البرامج الثابتة	C/Rust/Ada	مزايا خاصة بكل منصة	MicroPython, Arduino
قاعدة البيانات	PostgreSQL 16	JSONB واعتمادية وتوسعات	MySQL, MongoDB
التتبع	OpenTelemetry	معيار محايد عن المزود	Jaeger, Zipkin

خريطة المنافذ

المنفذ	الخدمة	البروتوكول
8000	FastAPI	HTTP/WS
8080	Rust Core Engine (ملف اختياري)	HTTP
3000	Next.js Dashboard	HTTP
5432	PostgreSQL + pgvector	TCP
6379	Redis	TCP
4222	NATS	TCP
1883	MQTT	TCP
4317	OTLP gRPC	gRPC
9000-9016	A2A Agents	HTTP
9090	Prometheus	HTTP
3001	Grafana	HTTP