TROUBLESHOOTING.md

دليل استكشاف الأخطاء وإصلاحها | Troubleshooting Guide

🚨 الأخطاء الشائعة | Common Errors

1. خطأ الاستيراد | Import Error

NameError: name 'Request' is not defined

الحل | Solution:

# تأكد من أن جميع الاستيرادات موجودة
# Make sure all imports are present
python fix_imports.py

السبب | Cause: استيراد مفقود في ملف app.py

2. خطأ الذاكرة | Memory Error

RuntimeError: [enforce fail at alloc_cpu.cpp:75] 

الحل | Solution:

# قلل حجم الدفعة
# Reduce batch size
export BATCH_SIZE=2

# استخدم التحميل بالقطع
# Use chunk loading
export ENABLE_CHUNK_LOADING=true

3. خطأ الرموز المميزة | Token Error

HTTPError: 401 Client Error: Unauthorized

الحل | Solution:

1. تحقق من صحة الرمز المميز
2. أضف الرمز في إعدادات البيئة
3. استخدم واجهة إدارة الرموز

4. خطأ DICOM | DICOM Error

ImportError: No module named 'pydicom'

الحل | Solution:

# تثبيت مكتبات DICOM
pip install pydicom SimpleITK

🔧 خطوات الإصلاح السريع | Quick Fix Steps

الخطوة 1: فحص النظام | Step 1: System Check

python fix_imports.py

الخطوة 2: تشغيل النسخة المبسطة | Step 2: Run Minimal Version

python app_minimal.py

الخطوة 3: فحص الصحة | Step 3: Health Check

curl http://localhost:8000/health

الخطوة 4: فحص التصحيح | Step 4: Debug Check

curl http://localhost:8000/debug

🐛 تصحيح الأخطاء المتقدم | Advanced Debugging

تفعيل وضع التصحيح | Enable Debug Mode

export DEBUG=true
export LOG_LEVEL=DEBUG
python app.py

مراقبة الذاكرة | Memory Monitoring

# مراقبة استهلاك الذاكرة
watch -n 1 'free -h'

# مراقبة العمليات
htop

فحص السجلات | Check Logs

# عرض السجلات الحديثة
tail -f logs/app.log

# البحث في السجلات
grep "ERROR" logs/app.log

🔍 تشخيص المشاكل | Problem Diagnosis

مشكلة بطء الأداء | Performance Issues

الأعراض | Symptoms:

• بطء في التحميل
• استهلاك عالي للذاكرة
• توقف التطبيق

الحلول | Solutions:

1. تقليل حجم الدفعة
2. استخدام التحميل بالقطع
3. تفعيل تحسينات CPU
4. مراقبة الذاكرة

مشكلة الاتصال | Connection Issues

الأعراض | Symptoms:

• خطأ 500 في الخادم
• عدم الاستجابة
• انقطاع الاتصال

الحلول | Solutions:

1. فحص المنفذ
2. تحقق من الجدار الناري
3. إعادة تشغيل الخادم

مشكلة النماذج | Model Issues

الأعراض | Symptoms:

• فشل تحميل النموذج
• خطأ في التنسيق
• نفاد الذاكرة

الحلول | Solutions:

1. تحقق من تنسيق النموذج
2. استخدم التحميل بالقطع
3. قلل حجم النموذج

🛠️ أدوات الإصلاح | Repair Tools

1. أداة فحص الاستيرادات | Import Checker

python fix_imports.py

2. النسخة المبسطة | Minimal Version

python app_minimal.py

3. سكريبت البدء السريع | Quick Start Script

./start.sh --check-only

4. تنظيف الذاكرة | Memory Cleanup

# تنظيف يدوي للذاكرة
curl -X POST http://localhost:8000/api/system/cleanup

📊 مراقبة الأداء | Performance Monitoring

مقاييس النظام | System Metrics

# معلومات الذاكرة
curl http://localhost:8000/api/system/memory

# معلومات الأداء
curl http://localhost:8000/api/system/performance

مراقبة الموارد | Resource Monitoring

# استهلاك المعالج
top -p $(pgrep -f "python.*app")

# استهلاك الذاكرة
ps aux | grep python | grep app

🔐 مشاكل الأمان | Security Issues

مشكلة الرموز المميزة | Token Issues

المشكلة | Problem: رمز غير صحيح الحل | Solution:

1. تحقق من صحة الرمز
2. أنشئ رمز جديد
3. استخدم النوع الصحيح للرمز

مشكلة التشفير | Encryption Issues

المشكلة | Problem: فشل التشفير الحل | Solution:

1. احذف ملف .token_key
2. أعد تشغيل التطبيق
3. أعد إنشاء الرموز

🐳 مشاكل Docker | Docker Issues

مشكلة البناء | Build Issues

# بناء الصورة مع التفاصيل
docker build -f Dockerfile.optimized -t ai-distillation . --no-cache

# فحص السجلات
docker logs container_name

مشكلة التشغيل | Runtime Issues

# تشغيل مع متغيرات البيئة
docker run -p 8000:8000 --env-file .env ai-distillation

# دخول الحاوية للتصحيح
docker exec -it container_name /bin/bash

📞 الحصول على المساعدة | Getting Help

معلومات النظام | System Information

# جمع معلومات التصحيح
curl http://localhost:8000/debug > debug_info.json

تقرير الخطأ | Error Report

عند الإبلاغ عن خطأ، يرجى تضمين:

1. معلومات النظام | System Info:

   • نظام التشغيل
   • إصدار Python
   • حجم الذاكرة

2. رسالة الخطأ | Error Message:

   • النص الكامل للخطأ
   • السجلات ذات الصلة

3. خطوات الإعادة | Reproduction Steps:

   • الخطوات لإعادة إنتاج الخطأ
   • الإعدادات المستخدمة

الموارد المفيدة | Helpful Resources

• التوثيق الرسمي | Official Documentation: README.md
• دليل الميزات | Features Guide: FEATURES.md
• ملف التكوين | Configuration File: config.yaml
• متغيرات البيئة | Environment Variables: .env.example

✅ قائمة التحقق | Checklist

قبل الإبلاغ عن مشكلة، تأكد من:

• تشغيل python fix_imports.py
• فحص السجلات في logs/app.log
• تجربة النسخة المبسطة app_minimal.py
• التحقق من متغيرات البيئة
• فحص مساحة القرص والذاكرة
• تحديث التبعيات pip install -r requirements.txt

---

💡 نصيحة: استخدم النسخة المبسطة app_minimal.py لتشخيص المشاكل بسرعة!