المستنداتدليل المطوريندليل استكشاف الأخطاء الشائعة وحلها (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. فحص سجلات التشغيل المركزية واستكشاف الأخطاء

استخدم لوحة تحكم Portainer CE أو أمر 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

8. HTTP 403 Forbidden during Translation Sync from Strapi

If clicking Sync Translations from Strapi yields an HTTP 403 Forbidden error, the Public role lacks permission to read storefront settings. Go to Settings > Users & Permissions > Roles > Public, enable the find permission for both Storefront-setting and Media Library, and save.

٩. تجمّد حقل البحث وعدم إمكانية الكتابة في نافذة البحث

السبب: يعتمد شريط البحث في الواجهة على React InstantSearch ويتصل مباشرة من متصفح المستخدم بـ Meilisearch. إذا لم يتم تعريف النطاق الفرعي search.yourdomain.com في سجلات Cloudflare DNS أو تعذر الوصول إلى محرك البحث، يتجمد حقل الإدخال ولا يقبل أي كتابة.

الحل:
١. في لوحة Cloudflare (ضمن DNS > Records)، أنشئ سجل نوع A للاسم search يشير إلى IP الخادم الخاص بك.
٢. تأكد من أن الرابط يعمل بشكل سليم عبر:
curl -I https://search.yourdomain.com/health
٣. تأكد من ضبط متغيرات NEXT_PUBLIC_MEILISEARCH_HOST و NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY أثناء بناء حاوية الواجهة.

فحص جاهزية Meilisearch

bash

curl -I https://search.yourdomain.com/health
# الاستجابة المتوقعة: HTTP 200 OK