المستنداتدليل المطوريندليل استكشاف الأخطاء الشائعة وحلها (Troubleshooting)

دليل استكشاف الأخطاء وحلها (Troubleshooting Guide)

حلول عملية وسريعة لأكثر المشاكل والاستفسارات التقنية شيوعاً أثناء التطوير أو النشر على خوادم الإنتاج.

1. عدم تحديث التغييرات في الواجهة بعد الحفظ في Strapi

تحقق من إعدادات الـ Webhook في Strapi وتأكد من مطابقة قيمة ترويسة x-strapi-secret مع المتغير REVALIDATE_SECRET في ملف .env.

.env

env

STORE_CORS=http://localhost:8000,https://store.yourdomain.com
ADMIN_CORS=http://localhost:9000,https://api.yourdomain.com
AUTH_CORS=http://localhost:8000,http://localhost:9000,https://store.yourdomain.com

2. خطأ اتصال Medusa أو عدم ظهور المنتجات

فحص مفتاح الـ Publishable API Key

تأكد من تمرير المفتاح القابل للنشر الصحيح في ملف .env وتأكد من ربط قناة المبيعات (Sales Channel) بالمنتجات داخل لوحة تحكم Medusa.

3. مشاكل شهادات SSL التلقائية في Caddy

تأكد من توجيه سجلات A لمجالك بشكل صحيح إلى عنوان IP العام لخادمك وفتح المنفذين 80 و 443 في جدار الحماية (UFW / Security Groups).

4. حاوية PostgreSQL أو Redis ترفض الاتصال

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

أوامر فحص سلامة الحاويات

bash

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

5. فحص سجلات التشغيل المركزية واستكشاف الأخطاء

استخدم لوحة تحكم OpenObserve أو أمر docker compose logs -f لمراقبة السجلات الحية وتشخيص أي خطأ في أجزاء من الثانية.

مراقبة سجلات الحاويات المباشرة

bash

docker compose logs -f storefront
docker compose logs -f medusa
docker compose logs -f strapi

6. إعادة بناء حاوية معينة دون إيقاف بقية الخدمات

إذا قمت بتعديل كود الواجهة أو الخلفية وترغب في تحديثها دون التأثير على بقية الخدمات:

أمر إعادة بناء حاوية مفردة

bash

docker compose up -d --build storefront

7. إعادة ضبط قواعد البيانات وملء البيانات التجريبية

في بيئة التطوير، يمكنك في أي وقت إعادة تشغيل سكريبت التعبئة لإدراج المنتجات التجريبية وتصنيفات Strapi الأولية:

أمر تعبئة البيانات التجريبية

env

docker compose exec medusa yarn seed