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

تغطي هذه الصفحة المشكلات الشائعة عند تشغيل Fenfa وحلولها.

تثبيت iOS

"Unable to Install" / فشل التثبيت

الأعراض: الضغط على زر التثبيت في iOS يُظهر "Unable to Install" أو لا يحدث شيء.

الأسباب والحلول:

1. HTTPS غير مُعيَّن. يتطلب iOS HTTPS مع شهادة TLS صالحة للتثبيت OTA. الشهادات الموقّعة ذاتياً لا تعمل.

   • الحل: أعدّ وكيلاً عكسياً مع شهادة TLS صالحة. راجع النشر الإنتاجي.
   • للاختبار: استخدم ngrok لإنشاء نفق HTTPS: ngrok http 8000

2. primary_domain خاطئ. يحتوي ملف manifest plist على روابط تنزيل مبنية على primary_domain. إذا كان خاطئاً، لا يمكن لـ iOS جلب ملف IPA.

   • الحل: اضبط FENFA_PRIMARY_DOMAIN على URL HTTPS الدقيق الذي يصل إليه المستخدمون (مثلاً https://dist.example.com).

3. مشكلات الشهادة. يجب أن تغطي شهادة TLS النطاق وأن تكون موثوقة من iOS.

   • الحل: استخدم Let's Encrypt للحصول على شهادات مجانية وموثوقة.

4. انتهاء صلاحية توقيع IPA. قد تكون صلاحية ملف التعريف أو شهادة التوقيع منتهية.

   • الحل: أعد توقيع IPA بشهادة صالحة وأعد الرفع.

ربط UDID لا يعمل

الأعراض: يُثبَّت ملف التكوين لكن الجهاز غير مسجَّل.

الأسباب والحلول:

1. رابط الرد غير قابل للوصول. يجب أن يكون رابط رد UDID قابلاً للوصول من الجهاز.

   • الحل: تأكد من صحة primary_domain وإمكانية الوصول إليه من شبكة الجهاز.

2. انتهاء صلاحية الـ nonce. تنتهي صلاحية nonces الملفات الشخصية بعد مهلة.

   • الحل: أعد تنزيل ملف التكوين وحاول مجدداً.

مشكلات الرفع

الرفع يفشل بخطأ 401

الأعراض: {"ok": false, "error": {"code": "UNAUTHORIZED", ...}}

الحل: تحقق من أن رأس X-Auth-Token يحتوي على رمز صالح. نقاط نهاية الرفع تقبل رموز الرفع والإدارة.

# تحقق من عمل رمزك
curl -H "X-Auth-Token: YOUR_TOKEN" http://localhost:8000/admin/api/products

الرفع يفشل بخطأ 413 (طلب أكبر من المسموح)

الأعراض: فشل رفع الملفات الكبيرة بخطأ 413.

الحل: هذا عادةً حد الوكيل العكسي، وليس Fenfa نفسه. ازد الحد:

Nginx:

client_max_body_size 2G;

Caddy: Caddy لا يحد حجم الجسم افتراضياً، لكن إذا كنت قد ضبطته:

dist.example.com {
    request_body {
        max_size 2GB
    }
    reverse_proxy localhost:8000
}

الرفع الذكي لا يكتشف البيانات الوصفية

الأعراض: الإصدار ورقم البناء فارغان بعد الرفع الذكي.

الحل: الكشف التلقائي للرفع الذكي يعمل فقط لملفات IPA وAPK. لصيغ سطح المكتب (DMG وEXE وDEB إلخ.)، أدخل version وbuild صراحةً في طلب الرفع.

مشكلات Docker

الحاوية تبدأ لكن لوحة الإدارة فارغة

الأعراض: تُحمَّل لوحة الإدارة لكنها لا تُظهر بيانات أو صفحة فارغة.

الحل: تحقق من تشغيل الحاوية وصحة تعيين المنفذ:

docker ps
docker logs fenfa

فقدان البيانات بعد إعادة تشغيل الحاوية

الأعراض: تختفي جميع المنتجات والمتغيرات والإصدارات بعد إعادة تشغيل الحاوية.

الحل: ارفع أجزاءً دائمة:

docker run -d --name fenfa -p 8000:8000 \
  -v ./data:/data \
  -v ./uploads:/app/uploads \
  fenfa/fenfa:latest

رفض الإذن على الأجزاء المثبّتة

الأعراض: يفشل Fenfa في الكتابة إلى /data أو /app/uploads.

الحل: تأكد من وجود المجلدات المضيفة وامتلاكها للأذونات الصحيحة:

mkdir -p data uploads
chmod 777 data uploads  # Or set appropriate UID/GID

مشكلات قاعدة البيانات

خطأ "database is locked"

الأعراض: يُعيد SQLite "database is locked" في ظل تزامن عالٍ.

الحل: يتعامل SQLite جيداً مع القراءات المتزامنة لكنه يُسلسل الكتابات. يحدث هذا الخطأ عادةً في ظل حمل كتابة عالٍ جداً. الحلول:

• تأكد من كتابة نسخة واحدة فقط من Fenfa إلى نفس ملف قاعدة البيانات.
• إذا كنت تشغّل نسخاً متعددة، استخدم تخزين S3 وقاعدة بيانات مشتركة (أو الانتقال إلى قاعدة بيانات مختلفة في إصدار مستقبلي).

قاعدة بيانات تالفة

الأعراض: يفشل Fenfa في البدء مع أخطاء SQLite.

الحل: استعادة من النسخ الاحتياطي:

# إيقاف Fenfa
docker stop fenfa

# استعادة النسخة الاحتياطية
cp /backups/fenfa-latest.db /path/to/data/fenfa.db

# إعادة التشغيل
docker start fenfa

الوقاية

أعدّ نسخاً احتياطية يومية آلية. راجع النشر الإنتاجي للاطلاع على سكريبت النسخ الاحتياطي.

مشكلات الشبكة

manifest iOS يُعيد روابط خاطئة

الأعراض: يحتوي ملف manifest plist على http://localhost:8000 بدلاً من النطاق العام.

الحل: اضبط FENFA_PRIMARY_DOMAIN على URL HTTPS العام الخاص بك:

FENFA_PRIMARY_DOMAIN=https://dist.example.com

التنزيلات بطيئة أو تنتهي مهلتها

الأعراض: تنزيلات الملفات الكبيرة بطيئة أو تفشل.

الحلول المحتملة:

• ازد مهلة الوكيل العكسي: proxy_read_timeout 600s; (Nginx)
• أوقف تفعيل تخزين الطلبات المؤقت: proxy_request_buffering off; (Nginx)
• فكّر في استخدام تخزين متوافق مع S3 مع CDN للملفات الكبيرة

الحصول على المساعدة

إذا لم تُغطَّ مشكلتك هنا:

1. تحقق من مشكلات GitHub للمشكلات المعروفة.
2. راجع سجلات الحاوية: docker logs fenfa
3. افتح مشكلة جديدة مع:
   • إصدار Fenfa (docker inspect fenfa | grep Image)
   • مخرجات السجل ذات الصلة
   • خطوات إعادة الإنتاج