نشر الواجهة الخلفية على Hugging Face Spaces

Hugging Face Spaces منصة استضافة مجانية تعمل بـ Docker. وهي تمنحك 2 vCPU وذاكرة RAM سعتها 16GB ومساحة تخزين 50GB — وهو أكثر من كافٍ لهذا المشروع.

ما ستتعلمه

• إنشاء مساحة (Space) على Hugging Face
• نشر تطبيق Flask مغلّف بـ Docker في بيئة الإنتاج
• إدارة الأسرار (مفاتيح API) على Hugging Face
• ربط تطبيق الجوال بالواجهة الخلفية في الإنتاج

المتطلبات المسبقة

• حساب على Hugging Face — سجّل من https://huggingface.co/join
• تثبيت Git وإعداده (git --version)
• أن يكون مشروعك محفوظًا في commit داخل مستودع git على GitHub (أو أي remote آخر لـ git)
• قاعدة بيانات Supabase PostgreSQL جاهزة (انظر database-production.md)
• أن يكون OPENAI_API_KEY جاهزًا لديك

الخطوة 1: تأكد من جاهزية Dockerfile.prod

يُفترض أن يكون ملف Dockerfile الإنتاجي موجودًا بالفعل في backend/Dockerfile.prod من قسم إعداد Docker. فإن لم يكن موجودًا فأنشئه:

FROM python:3.13-slim

WORKDIR /app

COPY app/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt gunicorn

COPY app/ ./app/
COPY wsgi.py .

EXPOSE 8000

CMD ["gunicorn", "wsgi:app", "--bind", "0.0.0.0:8000"]

كما يُفترض أن تكون نقطة الدخول wsgi.py موجودة في backend/wsgi.py:

from app import create_app

app = create_app()

الخطوة 2: أنشئ ملف README.md لمساحتك

تتطلب Hugging Face Spaces وجود ملف README.md في جذر مستودع المساحة. أنشئ backend/README.md:

---
title: AI Project Backend
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
---

# AI Project Backend

Flask chat backend for the Agentic Chat project.

تُخبر كتلة البيانات الوصفية (---) منصة Hugging Face بأن هذه مساحة Docker.

الخطوة 3: أنشئ مساحة Hugging Face

1. انتقل إلى https://huggingface.co/new-space
2. اضبط Space Name على aiproject-backend
3. ضمن Space SDK، اختر Docker
4. اختر Dockerfile (وليس قالبًا جاهزًا)
5. اضبط Visibility على Public (يمكنك تغييرها إلى Private لاحقًا)
6. انقر Create Space

تعطيك Hugging Face رابط مستودع git مثل:

https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend

الخطوة 4: ادفع كود الواجهة الخلفية إلى المساحة

بما أن كود الواجهة الخلفية موجود في مجلد فرعي (backend/)، فاستخدم git subtree لدفع ذلك المجلد وحده:

cd aiproject

# أضف مساحة Hugging Face بوصفها remote
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend

# ادفع مجلد الواجهة الخلفية ليكون جذر مستودع المساحة
git subtree push --prefix backend space main

أدخل اسم المستخدم وكلمة المرور الخاصين بك على Hugging Face (أو write token من https://huggingface.co/settings/tokens) عند المطالبة بذلك.

في المرة الأولى فقط: سيطلب Git بيانات الاعتماد. استخدم رمز كتابة (write token) من Hugging Face (أنشئ واحدًا من Settings → Access Tokens) بدلًا من كلمة المرور.

بديل: الرفع اليدوي

إذا وجدت git subtree مربكًا، فيمكنك أن: 1. تستنسخ مستودع مساحتك: git clone https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend 2. تنسخ ملفات الواجهة الخلفية إليه: cp -r aiproject/backend/* aiproject-backend/ 3. تنشئ commit وتدفعه

الخطوة 5: اضبط أسرار البيئة

تحتاج Hugging Face إلى مفاتيح API ورابط قاعدة البيانات الخاصة بك. ويجب ألا تكون هذه القيم في الكود أبدًا.

1. انتقل إلى مساحتك: https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend
2. انقر علامة التبويب Settings
3. مرّر لأسفل حتى تصل إلى Repository Secrets (وليست Variables — فالأسرار مشفّرة)
4. أضف هذه الأسرار:

مهم: لا تكون الأسرار متاحة أثناء مرحلة البناء — بل في وقت التشغيل فقط. وهذا أمر لا مشكلة فيه بالنسبة إلى إعدادنا، لأن Gunicorn يقرأها عند بدء التشغيل.

الخطوة 6: راقب البناء

1. انتقل إلى علامة التبويب Builder في مساحتك
2. سترى سجلات بناء Docker
3. يستغرق البناء الأول من 2 إلى 5 دقائق (تنزيل python:3.13-slim وتثبيت التبعيات)
4. عند اكتماله، تعرض الحالة "Running"

الخطوة 7: احصل على رابط الإنتاج

بعد النشر، تكون مساحتك متاحة على:

https://YOUR_USERNAME-aiproject-backend.hf.space

اختبره:

curl https://YOUR_USERNAME-aiproject-backend.hf.space/api/status
# → {"status":"ok"}

إذا ظهرت لك {"status":"ok"}، فالواجهة الخلفية لديك أصبحت تعمل!

الخطوة 8: حدّث تطبيق الجوال

في mobile/App.tsx، حدّث رابط API ليشير إلى الواجهة الخلفية في الإنتاج:

const API_BASE_URL = "https://YOUR_USERNAME-aiproject-backend.hf.space";

أعد بناء تطبيق الجوال أو أعد نشره باستخدام EAS Build (انظر mobile-production.md).

حل المشكلات

قائمة التحقق قبل النشر

قبل أن تدفع إلى Hugging Face Spaces، نفّذ قائمة التحقق هذه:

# 1. شغّل أداة الفحص على الكود
ruff check backend/

# 2. شغّل جميع الاختبارات
cd backend && python -m pytest tests/ -v

# 3. ابنِ صورة Docker الإنتاجية محليًا
docker build -f Dockerfile.prod -t aiproject-prod .

# 4. ابحث عن أي مراجع .env ينبغي أن تكون أسرارًا
grep -r "os.getenv" app/

إذا نجحت الخطوات الأربع كلها، فأنت جاهز للنشر. أما خط أنابيب CI/CD (انظر deployment/ci-cd.md) فينفّذ الخطوتين 1 و2 تلقائيًا عند كل push.

الخطوات التالية

• أضف قاعدة بيانات — انظر database-production.md لربط Supabase PostgreSQL
• أعدّ نطاقًا مخصصًا — تدعم Hugging Face Spaces النطاقات المخصصة (Settings → Custom Domain)
• رقِّ مساحتك — لمزيد من الموارد، انظر أسعار Hugging Face (لكن الخطة المجانية سخية بما يكفي لهذا المشروع)