README.ar.md

تطبيق الطقم المكمل متعدد الطبقات

اللغة: English | العربية | Español

تطبيق شامل متعدد الطبقات والميزات مبني باستخدام Nuxt 4، يحتوي على ميزات الاتصال الفوري (websocket)، التحقق من المستخدم (auth)، ويدعم العديد من المنصات. لمزيد من المعلومات التفصيلية، راجع وثائق Nuxt.

فهرس المحتويات

• المتطلبات الأساسية
• الشروع في العمل
• التطوير
• تكوين البيئة
• إعداد Docker
• البناء للإنتاج
• تطبيق الجوال
• تطبيق Electron (تطبيقات الحاسوب)
• تشغيل الموقع النهائي
• تأمين الموقع
• استكشاف الأخطاء وإصلاحها

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

قبل الشروع في هذا المشروع، تأكد من أن لديك الأدوات التالية مثبتة على نظامك:

• Docker و Docker Compose
• Bun بيئة تشغيل JavaScript
• نظام التحكم في الإصدار Git

تثبيت المتطلبات

تثبيت Docker:

# تنزيل وتشغيل البرنامج النصي الرسمي لتثبيت Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# إضافة المستخدم الحالي إلى مجموعة docker (Linux فقط)
sudo usermod -aG docker $USER

Important

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

تثبيت Bun:

# باستخدام المثبت الرسمي لـ Bun
curl -fsSL https://bun.sh/install | bash

# أو باستخدام npm
npm install -g bun

تثبيت Git:

# لـ Ubuntu/Debian
sudo apt install git
# لـ macOS
xcode-select --install
# لـ Windows، قم بتنزيله من https://git-scm.com/

Important

بعد تشغيل usermod -aG docker $USER، يجب عليك تسجيل الخروج ثم تسجيل الدخول مرة أخرى أو إعادة التشغيل لتطبيق تغييرات مجموعة Docker. لمزيد من التكوينات بعد التثبيت، راجع خطوات ما بعد التثبيت لـ Docker.

الشروع في العمل

استنساخ المستودع

git clone https://github.com/Bader-Idris/nuxt4-fullstack-portfolio.git ./portfolio

# يُوصى بإعادة تسمية دليل المشروع إلى 'portfolio' إذا لم تستخدم الأمر السابق
sudo mv nuxt4-fullstack-portfolio portfolio
cd portfolio

تثبيت التبعيات

Important

تأكد من أنك قد ثبت Bun قبل تشغيل هذه الأوامر.

bun install

ترحيلات قاعدة البيانات

Important

ترحيل قاعدة البيانات حيوي للبناء الأول! تم فصله بشكل قصدي عن عملية البناء الرئيسية لمنح السيطرة.

قبل تشغيل التطبيق، تأكد من أن مخطط قاعدة بياناتك محدث بتشغيل ترحيلات Prisma:

bunx prisma migrate deploy
bunx prisma generate

التطوير

بدء خادم التطوير

لبدء خادم التطوير، انتقل إلى http://localhost:3000:

bun run dev

Tip

للحصول على تجربة التطوير الكاملة مع جميع خدمات الخلفية، استخدم إعداد Docker كما هو موضح أدناه.

تكوين البيئة

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

أنشئ تكوين بيئة من ملف المثال:

cp .env.example .env

Caution

عدل القيم في ملف .env لتحصل على خدماتك الخاصة.

Caution

إذا كنت تستخدم Windows، تأكد من تثبيت Git واستخدام Git Bash لتجربة تطوير محسنة.

ملفات تكوين البيئة الخاصة بالمنصة

يتضمن المشروع تكوين بيئة لأنظمة مختلفة:

• .env.example - متغيرات بيئة التطبيق الرئيسي
• .env.electron.example - متغيرات بيئة تطبيق Electron
• .env.capacitor.example - متغيرات بيئة تطبيق الجوال

أوامر MongoDB CLI v8

show dbs
// اسم قاعدة البيانات الخاصة بك MONGO_DB_NAME
use MONGO_DB_NAME
show collections
// على سبيل المثال مجموعة المستخدمين
db.getCollection("users").find()
// للبحث في المجموعات:
db.users.find({ field: "value" }) // مثل
db.users.find({ "email": "contact@baderidris.com" })

// لتعديل الصلاحية بناءً على البريد الإلكتروني:
db.users.updateOne(
  { "email": "contact@baderidris.com" },
  { $set: { "role": "admin" } }
)
// للحذف:
db.users.deleteOne({ "email": "contact@baderidris.com" })

أمر الترحيل من MongoDB 4.4.29 إلى 8.2.5

# بعد تنفيذ أمر النسخ الاحتياطي مع:
docker exec mongo sh -c 'mongodump --archive --gzip -u <Mongo_user> -p <Mongo_password> --authenticationDatabase admin' > /path/to/your/backup-4.4.gz
# بعض البيانات ستُفقد، لقد لاحظت أن المحادثات فُقدت! لكن ليس رسائل المشرفين!

# ثم نفذ هذا الأمر لاستعادة البيانات: (أفضل نهج هو الترحيل التسلسلي للإصدارات مثل 4 -> 5 -> 6 إلخ...)

docker exec -i mongo mongorestore \
  --archive --gzip \
  -u <Mongo_user> \
  -p <Mongo_password> \
  --authenticationDatabase admin \
  < /path/to/your/backup-4.4.gz

# وللتوافق نفذ هذا:
docker exec -it mongo mongosh -u <Mongo_user> -p <Mongo_password> --authenticationDatabase admin --eval '
  db.adminCommand({ setFeatureCompatibilityVersion: "8.2", confirm: true });
  db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 });
'

إعداد Docker

بيئة التطوير

يستخدم المشروع Docker Compose لبيئة تطوير كاملة تتضمن جميع خدمات الخلفية الضرورية.

1. تكوين متغيرات البيئة

   cp .env.example .env
   # حرّر .env من نسخة المثال

2. بدء خدمات Docker

   docker compose -f b.dev.yml up -d --build

3. الوصول إلى التطبيق

   • الواجهة الأمامية: http://localhost:3000
   • سيتم تكوين خدمات الخلفية تلقائيًا

Warning

يستخدم التطبيق خدمات خلفية مكثفة ويؤدي أفضل أداء مع Docker لتجربة متسقة.

بيئة الإنتاج

Important

تأكد من تثبيت Docker على جهاز الإنتاج.

لنشر في الإنتاج مع شهادات SSL:

docker compose -f ./a.prod-certbot.yml up -d --build

Important

حاسم: يجب أن يُسمى مجلد المشروع portfolio للنشر الإنتاجي. تم تضمين تكوين Nginx لبحث الحاويات في دليل portfolio. إذا قمت باستنساخ المجلد باسم مختلف، يجب عليك إما إعادة تسمية المجلد إلى portfolio أو تحديث ملفات تكوين Nginx وفقًا لذلك.

البناء للإنتاج

بناء قياسي

لبناء التطبيق للإنتاج:

# حول ملف داكر إلى نسختك الخاصة
cp ./compose.prod.test.yaml.example ./compose.prod.test.yaml
# ومن ثم أوقف نسخة التطوير وابدأ في بناء المشروع
docker compose -f b.dev.yml down; docker compose -f compose.prod.test.yaml up -d redis postgres mongo ; docker compose -f compose.prod.test.yaml build --progress=plain app; docker compose -f compose.prod.test.yaml up -d 

Caution

بناء التطبيق على خادم بموارد محدودة يُعتبر ممارسة سيئة. لأداء وموثوقية مثلى، نوصي بشدة باستخدام صورة Docker المبنية مسبقًا المتوفرة في Docker Hub بدلاً من البناء من المصدر على الخادم. إذا كان لا بد من البناء على خادم ضعيف، يرجى اتباع التعليمات في ملف weak_servers.md لضمان عملية بناء ناجحة.

لمعاينة البناء الإنتاجي محليًا:

bun run preview

صورة Docker للإنتاج

Tip

توجد صورة Docker مبنية مسبقًا في Docker Hub. يمكنك العثور على تعليمات حول كيفية سحب الصورة وتشغيلها مع Docker Compose في وثائق المستودع.

تطبيق الجوال

الإعداد

لإضافة دعم Android وiOS:

bunx cap add android ios

أنشئ ملف بيئة الجوال:

cp .env.capacitor.example .env.capacitor
# قم بتكوين متغيرات البيئة

تخصيص أيقونات التطبيق

لتخصيص أيقونات تطبيقك، عدّل الأيقونات في مجلد /assets حسب الرغبة، ثم شغّل:

bunx capacitor-assets generate --assetPath "./assets" --ios --android

يمكنك مراجعة متطلبات التكوين في ملف assets/requirements.md.

إشعارات الدفع عبر Firebase

Warning

مطلوب لمنع تعطل التطبيق مع إشعارات الدفع.

لتشغيله بشكل صحيح ومنع تعطل تطبيق الجوال، يجب أن يكون لديك الملف android/app/google-services.json. راجع وثائق Capacitor ووثائق Firebase.

إعداد تطوير Android

لبناء تطبيق Android، تأكد من أنك قد ثبت Android Studio وعيّن متغيرات البيئة التالية:

• ANDROID_HOME
• CAPACITOR_ANDROID_STUDIO_PATH

Caution

أعد تشغيل جلسة shell بعد إضافة متغيرات البيئة.

إصلاح توافق Android 15+

Caution

لتوافق Android 15+، بعد إنشاء مشروع Android، تحتاج إلى إضافة السطر التالي إلى كل قسم نمط مع Theme.AppCompat.* في الملف android/app/src/main/res/values/styles.xml لإصلاح خطأ overlay=true في Capacitor:

<item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>

هذا يضمن سلوك العرض المناسب على أجهزة Android 15+ عند استخدام Capacitor مع إعدادات overlay=true.

يمكنك الاطلاع على المشكلة هنا

تطبيق Electron

الإعداد

لإنشاء بناء إنتاج لـ Electron:

1. أنشئ ملف بيئة Electron:

   cp .env.electron.example .env.electron
   # قم بتكوين متغيرات البيئة

2. استخدم الأوامر التالية لبناء تطبيق Electron:

   • bun run build:electron: بناء للمنصة الحالية
   • bun run build:electron:all: بناء لـ Windows وmacOS وLinux
   • bun run build:electron:win: بناء لـ Windows فقط
   • bun run build:electron:mac: بناء لـ macOS فقط
   • bun run build:electron:linux: بناء لـ Linux فقط
   • bun run build:electron:dir: بناء في دليل غير مضغوط للاختبار

تكوين النطاق

تأكد من تحديث اسم النطاق baderidris.com في الملف b.dev.yml وفي ملفات التكوين المرتبطة باسم النطاق الخاص بك.

نشر الإنتاج

إدارة شهادة SSL

إعداد تجديد الشهادة

لأتمتة تجديد الشهادات، أنشئ مهمة cron عن طريق تعديل المسارات في الملف /server/config/nginx/ssl_renew.sh، ثم أضف هذا إلى crontab:

# لتحرير crontab، شغّل:
crontab -e

# أضف السطر التالي لجدولة نص البرمجة للتجديد:
0 12 * * * /home/bader/portfolio/server/config/nginx/ssl_renew.sh >> /var/log/cron.log 2>&1

Tip

راجع ملف ssl_renew.sh لمزيد من النصائح والمكونات المفيدة.

إعداد الشهادة بعد النشر

بعد النشر الأولي، ستحتاج إلى إجبار Certbot على تجديد الشهادات لإزالة علامة --staging. يُوصى بإنشاء ملف compose منفصل لهذا الغرض وللتجديدات المستقبلية.

تأمين الموقع

لتعزيز أمن تطبيقك ومنع الهجمات الشائعة مثل DDoS، تم تنفيذ Fail2Ban.

تكوين Fail2Ban

الملفات التالية مدرجة في تكوين الأمان:

ls server/config/fail2ban/
# يحتوي على:
# - دليل filter.d
# - ملف my_custom_jail.local

السجون والمرشحات المخصصة

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

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

المشاكل الشائعة

• Builds الخوادم الضعيفة: راجع weak_servers.md للحصول على إرشادات حول تحسين البناء للموارد المحدودة
• مشكلات Docker: تأكد من تثبيت Docker وDocker Compose وتشغيلهما بشكل صحيح
• متغيرات البيئة: تأكد من تكوين جميع متغيرات البيئة المطلوبة بشكل صحيح

المجتمع

انضم إلى مناقشات مجتمعنا! لا تتردد في التواصل مع المشرف والأعضاء الآخرين في المجتمع على مناقشات GitHub.

---

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