دليل البدء السريع للمساهمين الجدد

ترشدك هذه الصفحة خلال عملية إعداد بيئة تطوير AuroraSOC كاملة على جهازك. بحلول نهاية هذا الدليل، ستكون واجهة برمجة التطبيقات (API) قيد التشغيل، ولوحة التحكم (dashboard) تعمل، وستكون قادرًا على تشغيل مجموعة الاختبارات بالكامل.

---

المتطلبات الأساسية (Prerequisites)

قم بتثبيت هذه الأدوات قبل البدء:

الأداة (Tool)	الحد الأدنى للإصدار	وظيفتها (What It Does)	التثبيت (Install)
Python	3.12+	تشغيل الواجهة الخلفية (backend)، والوكلاء، والنصوص البرمجية الخاصة بالتدريب	python.org أو sudo apt install python3.12 python3.12-venv
Rust	1.75+	تجميع المحرك الأساسي (core edge engine) المبني بلغة Rust	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs
Node.js	18+	تشغيل لوحة تحكم Next.js وتوثيقات Docusaurus	nodejs.org أو nvm install 18
Docker & Docker Compose	24+ / v2	تشغيل PostgreSQL، Redis، NATS، Mosquitto، Grafana، إلخ.	docs.docker.com
Ollama	الأحدث (Latest)	تقديم نماذج LLM الخاصة بـ Granite 4 محليًا	`curl -fsSL https://ollama.com/install.sh
Git	2.30+	التحكم في الإصدارات (Version control)	sudo apt install git
Make	أي إصدار	تشغيل أوامر Makefile (الواجهة الرئيسية للمطورين)	sudo apt install build-essential

تلميح

قم بتشغيل الأمر make help في أي وقت لرؤية جميع الأوامر المتاحة مع وصف قصير لكل منها.

---

الخطوة 1: استنساخ المستودع والدخول إليه

git clone https://github.com/ahmeddwalid/AuroraSOC
cd AuroraSOC

---

الخطوة 2: بدء تشغيل خدمات البنية التحتية

يعتمد نظام AuroraSOC على عدة خدمات. يقوم Docker Compose بتشغيلها جميعًا بضغطة زر وبأمر واحد:

make docker-up

يشغل هذا الأمر الخدمات التالية:

الخدمة (Service)	المنفذ (Port)	الغرض (Purpose)
PostgreSQL 16	5432	قاعدة البيانات الرئيسية
Redis 7	6379	التخزين المؤقت (Cache)، إدارة تدفقات الأحداث، وتقييد معدل الطلبات (rate limiting)
Qdrant	6333	قاعدة بيانات المتجهات (Vector database) لذاكرة الوكيل
NATS JetStream	4222	اتحاد ومشاركة الأحداث عبر المواقع المختلفة (Cross-site event federation)
Mosquitto	1883/8883	وسيط MQTT الخاص بأجهزة إنترنت الأشياء (IoT)
Prometheus	9090	جمع مقاييس الأداء
Grafana	3001	لوحات تحكم المراقبة
OTel Collector	4317	تجميع مسارات وتتبعات النظام الموزعة (Distributed trace collection)

للتحقق من أن كل شيء يعمل بسلاسة:

docker compose ps

لعرض السجلات (logs):

make docker-logs

---

الخطوة 3: تثبيت اعتماديات ومكتبات بايثون

أنشئ بيئة افتراضية وقم بتثبيت كافة الاعتماديات (بما في ذلك إضافات وبيئات التطوير والاختبار):

python3 -m venv .venv
source .venv/bin/activate
make dev

يقوم هذا الأمر بتنفيذ pip install -e ".[dev,test]"، والذي يثبّت نظام AuroraSOC في الوضع القابل للتحرير (editable mode) بحيث تدخل تغييراتك في الشفرة حيز التنفيذ الفوري.

---

الخطوة 4: سحب وتحميل نماذج اللغات الكبيرة (LLM)

يستخدم نظام AuroraSOC نماذج IBM Granite 4 المٌقدمة عبر خدمة Ollama:

make ollama-pull-granite

يقوم هذا الأمر بسحب نموذجَين اثنين:

• granite4:8b — يُستخدم من قبل كافة الوكلاء المتخصصين الـ 16
• granite4:dense — يُستخدم من قبل وكيل التنظيم (Orchestrator) لإنجاز عمليات الاستنتاج المُعقدة

تحقق من توفر النماذج بنجاح:

make ollama-list

إذا لم تكن خدمة Ollama قيد التشغيل، قم بتشغيلها أولًا:

make ollama-serve

---

الخطوة 5: تشغيل عمليات تهجير قاعدة البيانات (Database Migrations)

قم بتطبيق مخطط البيانات (schema) على قاعدة بيانات PostgreSQL:

make migrate

يقوم هذا الأمر بتشغيل الأمر alembic upgrade head، والذي بدوره ينشئ جميع الجداول البالغ عددها 13 جدولًا (تتضمن الجداول الخاصة بالإنذارات، والحالات، والوكلاء، وكتب التشغيل playbook، إلخ). للتحقق من حالة التهجير الحالية:

alembic current

---

الخطوة 6: تشغيل واجهة برمجة تطبيقات الخلفية (Start the Backend API)

make api

يقوم هذا الأمر ببدء تشغيل خادم FastAPI على الرابط http://localhost:8000 مع تفعيل ميزة إعادة التحميل المباشر (hot-reload). من المفترض أن ترى مخرجات مشابهة لما يلي:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process

تحقق من عمل الخادم:

curl http://localhost:8000/health

توثيقات واجهة برمجة التطبيقات (API Documentation)

يُنشئ FastAPI توثيقات تفاعلية للواجهة برمجة التطبيقات (API) بشكل تلقائي:

• واجهة Swagger (Swagger UI): http://localhost:8000/docs
• واجهة ReDoc: http://localhost:8000/redoc

---

الخطوة 7: تشغيل لوحة التحكم (Start the Dashboard)

في نافذة أو تبويبة طرفية (terminal) جديدة:

make dashboard-install   # للمرة الأولى فقط
make dashboard-dev

سيتم تشغيل لوحة تحكم Next.js على الرابط http://localhost:3000. وتتصل هذه اللوحة بواجهة FastAPI الخلفية على المنفذ 8000.

اختصار

يمكنك تشغيل واجهة برمجة التطبيقات (API) ولوحة التحكم (Dashboard) معًا بأمر واحد فقط:

make dev-all

يقوم هذا بتشغيل كلتا العمليتين بشكل متزامن، ويوقفهما معًا عند الضغط على Ctrl+C.

---

الخطوة 8: تشغيل مجموعة الاختبارات

make test

يقوم هذا الأمر بتشغيل كافة اختبارات بايثون باستخدام pytest. للحصول على تقرير لتغطية الكود بالاختبارات:

make test-cov

يتم إنشاء تقرير التغطية بصيغة HTML في المسار htmlcov/index.html.

لتشغيل اختبارات Rust أيضًا:

make rust-test

لتشغيل جميع الفحوصات (تحليل الكود lint + التحقق من الأنواع + اختبارات بايثون + اختبارات وفحوصات Rust clippy + فحوصات لوحة التحكم):

make check

---

الخطوة 9: التحقق من عمل كل شيء

قم بإجراء مراجعة على قائمة التحقق هذه للتأكد من اكتمال الإعداد الخاص بك بنجاح:

• docker compose ps — جميع الخدمات تعمل وحالتها "Up"
• curl http://localhost:8000/health — يُرجع رسالة تفيد بأن الحالة "OK"
• make test — اجتياز جميع الاختبارات بنجاح
• make lint — لا يوجد أي أخطاء في التحليل المبدئي (linting)
• http://localhost:3000 — تُحمّل لوحة التحكم بشكل سليم في المتصفح
• ollama list — يظهر النموذجان granite4:8b و granite4:dense في المُخرجات

---

الإعداد المحلي المؤتمت (Automated Local Setup)

لإعداد البيئة لأول مرة بطريقة آلية ومؤتمتة بالكامل، شغّل:

make setup-local

ينفّذ هذا النص البرمجي (scripts/setup_local.sh) الآتي:

1. الفحص والتحقق من تواجد كافة الأدوات المطلوبة (Python، Rust، Node.js، Docker، Ollama).
2. سحب وتحميل نماذج Granite 4 من خلال Ollama.
3. إنشاء ملف .env الافتراضي في حال عدم وجوده.
4. التحقق التام من جميع التبعيات واعتماديات النظام.

---

مرجع سريع لأهداف Makefile الشائعة (Common Makefile Targets Reference)

التطوير (Development)

الهدف (Target)	الوصف (Description)
make install	تثبيت اعتماديات ومكتبات بايثون (لبيئة الإنتاج فقط)
make dev	تثبيت الاعتماديات مع إضافات وبيئات التطوير والاختبار
make api	تشغيل خلفية FastAPI (على المنفذ 8000، مع إعادة التحميل المباشر)
make dev-all	تشغيل واجهة برمجة التطبيقات (API) ولوحة التحكم معًا
make dashboard-dev	بناء وتشغيل لوحة تحكم Next.js (على المنفذ 3000)
make mcp	تشغيل خادم سجل أدوات وبروتوكولات MCP

الجودة والتحقق (Quality)

الهدف (Target)	الوصف (Description)
make test	تشغيل مجموعة اختبارات بايثون
make test-cov	البدء باختبارات الكود مع قياس نسبة التغطية
make lint	تشغيل أداة التحليل الأكاديمي ruff linter
make format	التنسيق التلقائي للكود باستخدام ruff
make type-check	تشغيل فحص والتحقق من الأنواع mypy
make check	تشغيل كافة الفحوصات والإجراءات (التحليل المبكر + تحقق الأنواع + الاختبارات + فئات Rust + لوحة التحكم)

رست (Rust)

الهدف (Target)	الوصف (Description)
make rust-build	بناء المحرك الأساسي المبني عبر Rust (وضع الإنتاج والإصدار)
make rust-test	تشغيل اختبارات لغة Rust
make rust-clippy	تشغيل التحليل الشكلي والجمالي (Linter) لكودات Rust

قاعدة البيانات (Database)

الهدف (Target)	الوصف (Description)
make migrate	تطبيق وتفعيل كافة التهجيرات المعلقة
make migrate-new MSG="description"	إنشاء هيكل تهجير قاعدة بيانات جديد
make migrate-down	التراجع عن آخر خطوة تهجير لقاعدة البيانات (Roll back one migration)

الدوكر (Docker)

الهدف (Target)	الوصف (Description)
make docker-up	إقلاع وتشغيل كافة خدمات البنية التحتية
make docker-down	إيقاف تمامی الخدمات
make docker-logs	تعقب ورصد سجلات النظام الخاصة بالحاويات (Tail container logs)
make docker-build	إعادة بناء وتقويم جميع صور أنظمة وحاويات الـ Docker

نماذج اللغات العملاقة / والتدريب (LLM / Training)

الهدف (Target)	الوصف (Description)
make ollama-pull-granite	سحب النماذج الأساسية المتعلقة بـ Granite 4
make ollama-serve	بدء أوامر وسير عمل خادم Ollama
make train-data	الانتهاء من تجهيز وتحضير حزم ومجموعات بيانات تدريب مركز عمليات الأمان (SOC)
make train	ضبط دقيق لـ Granite 4 (يحتاج ويستدعي استخدام وحدة معالجة رسومية GPU متطورة)
make train-agent AGENT=name	الضبط والتنقيح المعرفي الدقيق الموجه لوكيل محدد بعينه
make train-eval	تقييم الموديل أو النموذج بعد التعديل والضبط הדקות
make enable-finetuned	توجيه وتصحيح مسار الوكلاء لاستخدام النماذج المدربة والمعدلة بعناية
make disable-finetuned	إرجاع مسارات وتوجيهات الوكلاء للنماذج الافتراضية والأساسية

التنظيف (Cleanup)

الهدف (Target)	الوصف (Description)
make clean	تطهير ومسح وإزالة كافة التخزينات المؤقتة (Caches) وعناصر وجهات عمل أوامر البناء

---

متغيرات البيئة (Environment Variables)

يتم تكوين نظام وإعداد AuroraSOC والتحكم به من خلال متغيرات ومعاملات البيئة، والتي تدار من خلال ملف aurorasoc/config/settings.py باستخدام إعدادات مكتبة Pydantic. فيما يلي المتغيرات الرئيسية:

المتغير (Variable)	القيمة الافتراضية (Default)	الوصف (Description)
DATABASE_URL	postgresql+asyncpg://aurora:aurora@localhost:5432/aurorasoc	بيانات الاتصال بقاعدة بيانات PostgreSQL
REDIS_URL	redis://localhost:6379	بيانات الاتصال بقواعد بيانات الذاكرة Redis
QDRANT_URL	http://localhost:6333	قاعدة بيانات المتجهات الشُعاعية Qdrant
NATS_URL	nats://localhost:4222	نقطة اتصال NATS JetStream
MQTT_BROKER	localhost	المضيف والخادم المعني وتوجيه وسيط بروتوكول MQTT
OLLAMA_BASE_URL	http://localhost:11434	نقطة الانطلاقة لواجهة وبرمجة تطبيق Ollama
JWT_SECRET_KEY	(يجب ضبطه)	عبارة المرور والمفتاح السري لخدمة توقيع رمز JWT
GRANITE_USE_FINETUNED	false	استخدام وتشغيل النماذج المدربة بدقة في مقابل النماذج الأولية المعتادة والأساسية

يمكنك ضبط هذه القيم عبر ملف .env ووضعه في المجلد الجذري للمشروع (root) — البرنامج النصي المتمثل بأمر make setup-local سيقوم بتهيئة واحد مسبقًا بالنيابة عنك ونيابة عن متطلبات بيئتك.

---

استكشاف الأخطاء وإصلاحها (Troubleshooting)

رفض الاتصال "Connection refused" على أي من المنافذ 5432/6379/6333

هذه رسالة مفادها أن خدمات البنية التحتية قيد السكون والانقطاع وليست قيد التشغيل. قم بتشغيل وتشغيل الأمر make docker-up وانتظر ما بين 10–20 ثانية حتى إقلاعها.

تعذر العثور على نماذج Ollama (Ollama model not found)

نفذ الأمر make ollama-pull-granite. وإذا لم تكن خدمة أو بيئة Ollama نفسها مثبته من الاساس، فاسترجع وثمّن جدول "المتطلبات الأساسية (Prerequisites)" الظاهر في أعلى هذا المستند.

تواجد أخطاء ومشاكل في الاستيراد (Import errors) بعد استيرادك للتغييرات المحدّثة للشيفرة والشفرة

أعد تثبيت الاعتماديات بجميع متطلباتها: عبر تشغيل أمر make dev. وإذا كان هناك تغييرات مسجله قد حلت على مخطط بناء الجداول لقاعدة البيانات، لا تنس أن تنفذ في الوقت نفسة أمر التهجير make migrate.

الفشل ووجود أخطاء متعثرة في سير الاختبارات ولقاعدة البيانات

عليك التأكد من وجود الخادم وحاوية نظام قاعدة بيانات PostgreSQL على الخط وقيد التشغيل (من خلال استخدام التعليمة docker compose ps)، بالإضافة لتأكيدك والتأكد من تفعيل كافة عمليات التهجير والتحديث الجدولي (make migrate).

ظهور رسالة تفيد بـخطأ في الشبكة ("Network Error") بلوحة تحكم الواجهة الرقمية

الواجهة الخلفية (Backend) والمعني بها خدمة إطار خوادم وخدمات FastAPI، يجب أن تكون مستقرة وفي حالة الإقلاع والتشغيل المسبق (make api) وعلى وجه التحديد من خلال واجهة المنفذ والمنصة الرقمية 8000 حتى تستطيع وتعطي الإيعازات لوحة القيادة بالتواصل المباشر معها.

فشل خطوة وإجراء بناء حاوية ومسار Rust

تأكد مبدئياً وحالياً من كون أنظمة Rust قائمة وموجوده بالفعل وتعمل عن طريق التحقق المباشر بصيغة أمر (rustup --version). بعدها قم وأجر محاولتك مجددًا مع الخطوة make rust-build. وإذا لزم الأمر لدواعي الحاجات التشغيلية لملفات الامتداد بصيغة (proto)، فتحقق مسبقاً وتأكد تمامًا من كون النظام مدعوماً برحابة وتواجد البيئة التحتية وتثبيت حزمة وخدمة protoc.

---

الخطوات القادمة (Next Steps)

هكذا أصبحت بيئة العمل الخاصة بك جاهزة وقابلة لتصريف المهام. الآن:

1. أقرأ دليل المساهمة (Contribution Guide) لفهم أعمق لمدلولات ومفاهيم معايير كتابة الأكواد والبرمجة وسير وحركة التعديلات و(PR process).
2. اختر وقم بانتقاء مهمة — اطلع وتلمس أروقة وصفحة مشاركات ومسائل (Issues) من خلال موقع مشروع GitHub ابحث وفرد وابحث عن جميع المسائل المصنفة بوسم وتصنيف تعريفي يُدعى good first issue لتكلف ببدايات جيدة.
3. ابدأ في الشروع والمباشرة بالبرمجة — الأمرين البرمجيين make format والتعليمة make lint سيحافظون وبشكل سوي وسلس على سلامة ورصانة وقوة ووضوح أكواد ونصوص شيفراتك البرمجية.