ContiAI · دليل النشر

من الجهاز إلى الإنترنت — خطوة بخطوة

كل ما يلزم لتشغيل المنصة على نطاقك الخاص: قاعدة البيانات والهوية، ثم الخادم والعامل الخلفي، ثم الواجهة، ثم ربط الدومين. اتبع المراحل بالترتيب — كل مرحلة تحتاج مخرجات التي قبلها.

GitHub المستودع Supabase الهوية وقاعدة البيانات Qdrant فهرس المتجهات Render الـ API والعامل والطابور Vercel الواجهة Namecheap الدومين
٠٠

قبل أن تبدأ

خمسة حسابات وبطاقة واحدة. لا تبدأ قبل أن تكون كلها جاهزة، لأن كل مرحلة تُنتج قيمة تحتاجها المرحلة التالية.

الحسابات

  • GitHub — مجاني. المستودع الذي يقرأ منه Render و Vercel.
  • Supabase — الخطة المجانية تكفي للبداية.
  • Qdrant Cloud — عنقود مجاني بسعة ١ جيجابايت.
  • Render — يحتاج بطاقة. الخادم والعامل على خطة Starter بـ ٧ دولارات لكل منهما.
  • Vercel — خطة Hobby مجانية.

مفاتيح مزوّدي النماذج

  • OpenRouter — مفتاح واحد، وارفع حدّه إلى ٢٥ دولارًا على الأقل.
  • Serper — مفتاح أو أكثر للبحث. النظام يتنقّل بينها عند بلوغ الحد.
  • Mistral — لاستخراج النصوص من ملفات PDF.
المفاتيح لا تُكتب في أي ملف يُرفع

مكانها الوحيد هو متغيّرات البيئة داخل Render و Vercel. المستودع فيه .gitignore يمنع ذلك، وفحص في CI يرفض الدفعة إن تسلّل مفتاح. وإن سُرّب مفتاح يومًا فالخطوة الأولى إبطاله من لوحة المزوّد، لا حذفه من الملف.

٠١

GitHub — رفع المستودع

جذر المستودع هو مجلد platform نفسه، لا المجلد الذي يحويه. Render يقرأ render.yaml من الجذر، و Vercel يحتاج apps/web كمجلد جذر للمشروع.

أنشئ المستودع

  1. افتح github.com/new.
  2. الاسم contiai، واجعله Private.
  3. لا تضف README ولا .gitignore — موجودان بالفعل.

ارفع الملفات

terminal
cd C:\conti_ai\platform

git init
git branch -M main
git add -A
git commit -m "ContiAI platform"

# استبدل ALIEMAD باسم حسابك
git remote add origin https://github.com/ALIEMAD/contiai.git
git push -u origin main

افحص قبل أن تدفع

أمر واحد يشغّل كل ما سيفحصه CI: بحث عن المفاتيح، وحجم الشجرة، ووجود ملفات النشر، ثم ruff وpytest وبناء الواجهة.

terminal
cd C:\conti_ai\platform
apps\api\.venv\Scripts\python.exe scripts\preflight.py

ينتهي بـ ready to push أو بقائمة ما ينقص. العدد المتوقع حوالي ٤٥٠ ملفًا بحجم ٥ ميجابايت — لو ظهر رقم بالآلاف فالأرجح أن node_modules أو .venv تسلّل، فراجع .gitignore قبل أن تكمل.

شغّله قبل كل دفعة لاحقة أيضًا. CI يفحص نفس الأشياء، لكنه يفحصها بعد الدفع — وعلى هذا المستودع الدفعة نشرٌ إلى مزوّدَين.

٠٢

Supabase — الهوية وقاعدة البيانات

Supabase يؤدي دورين: قاعدة بيانات Postgres يكتب فيها النظام كل مشروع وتشغيلة وخطوة، ومزوّد هوية يصدر رموز الدخول التي يتحقق منها الخادم.

أنشئ المشروع

  1. من supabase.com/dashboard اضغط New project.
  2. الاسم contiai، والمنطقة Frankfurt (eu-central-1) — نفس منطقة Render، فكل مللي ثانية بين الاثنين تتكرر في كل استعلام.
  3. ولّد كلمة مرور قاعدة البيانات واحفظها الآن. لن تُعرض مرة أخرى، وستحتاجها بعد دقائق.

اجمع القيم الأربع

القيمةمن أينتُستخدم في
SUPABASE_URL Settings ← Data API ← Project URL Render و Vercel
SUPABASE_ANON_KEY Settings ← API Keys ← anon / publishable Render و Vercel
SUPABASE_SERVICE_ROLE_KEY Settings ← API Keys ← service_role Render وحده
SUPABASE_JWT_SECRET Settings ← API Keys ← JWT Keys ← Legacy secret Render وحده
مفتاحان مختلفان تمامًا

مفتاح anon عام ويُدفن داخل جافاسكربت الواجهة — هذا طبيعي. ومفتاح service_role يتجاوز كل سياسات الحماية؛ لو وصل إلى الواجهة فقد فتحت قاعدة بياناتك للجميع. لا تضعه في أي متغيّر يبدأ بـ VITE_ أبدًا.

ملاحظة على صيغة المفاتيح

هذا المشروع ما زال يستعمل مفاتيح JWT القديمة. الصيغة الجديدة sb_secret_… يرفضها الـ Data API برسالة UNAUTHORIZED_INVALID_API_KEY_TYPE، فالمطلوب هو مفتاح service_role بصيغة JWT الطويلة التي تبدأ بـ eyJ.

رابط قاعدة البيانات

من Connect في أعلى اللوحة، اختر Connection pooling ثم Transaction. الرابط يشبه:

من Supabase
postgresql://postgres.abcdefghijkl:PASSWORD@aws-0-eu-central-1.pooler.supabase.com:6543/postgres

حوّله إلى الصيغة التي يقبلها الخادم — أضف +asyncpg واحذف أي ?pgbouncer=true:

DATABASE_URL لـ Render
postgresql+asyncpg://postgres.abcdefghijkl:PASSWORD@aws-0-eu-central-1.pooler.supabase.com:6543/postgres
المنفذ ٦٥٤٣ لا ٥٤٣٢

الاتصال المباشر على ٥٤٣٢ محدود العدد، وخادم واحد على Render يستنفده ثم يبدأ برفض الطلبات برسالة too many connections. المُجمِّع على ٦٥٤٣ هو المقصود. وإن كانت كلمة المرور تحوي رمزًا مثل @ أو # فرمّزها بترميز النسبة المئوية.

إعدادات المصادقة

  1. Authentication ← Providers ← Email: فعّله. وإن أردت تجربة سريعة بلا بريد تأكيد، أطفئ Confirm email مؤقتًا.
  2. Authentication ← URL Configuration ← Site URL: ضع رابط Vercel أو دومينك النهائي.
  3. في Redirect URLs أضف نطاقك و http://localhost:5173 للتطوير.
  4. لتفعيل الدخول بجوجل: Providers ← Google، وضع Client ID و Secret من Google Cloud Console، ثم انسخ رابط الاستدعاء الذي يعرضه Supabase إلى إعدادات جوجل.

ملفّا SQL — بعد أول نشر ناجح

alembic upgrade head يعمل وحده عند إقلاع خادم Render وينشئ جداول المنصة كلها. يبقى ملفان يُشغَّلان بيدك في SQL Editor، وبهذا الترتيب، وبعد أن ينجح النشر الأول — لأن الثاني يبني على جداول لا توجد قبله:

  1. infra/sql/001_rag_documents.sql — الجداول الثلاثة التي يكتب فيها كود الاسترجاع المنقول: documents_raw وdocuments_metadata وchunks. هذه لا ينشئها alembic لأن ذلك الكود لا يمرّ بـ SQLAlchemy أصلًا؛ يكلّم Supabase مباشرة. كانت موجودة في المشروع القديم لأن أحدهم أنشأها بيده، وعلى مشروع جديد يفشل أول استيعاب لأول كتاب بـ relation "documents_raw" does not exist — بعد أن تكون قد دفعت ثمن البحث والتنزيل.
  2. infra/sql/002_rls.sql — سياسات الحماية. طبقة ثانية: الخادم يقيّد كل استعلام بالمالك أصلًا، وهذه تجعل قاعدة البيانات ترفض بنفسها لو أفلت استعلام غير مقيَّد.
  3. infra/sql/003_rls_remainder.sql — الجداول التي كُتب الملف الثاني قبل وجودها. منها uploads وprofiles، ولكلٍّ منهما مالك — أي أنهما كانا بلا أي حماية بينما المفتاح المنشور في متصفّح كل زائر.

كلاهما يُشغَّل مرتين بلا ضرر.

٠٣

Qdrant — فهرس المتجهات

هنا تُخزَّن مقاطع المصادر بعد تقطيعها، ومنها يسترجع الكاتب الأدلة التي يبني عليها كل محور.

  1. من cloud.qdrant.io أنشئ عنقودًا مجانيًا في Frankfurt.
  2. انسخ رابط العنقود. لا بد أن ينتهي بالمنفذ :6333 — واجهة REST تستمع هناك، ومن دونه يفشل كل استرجاع بخطأ اتصال غامض.
  3. من Data Access Control أنشئ مفتاحًا وانسخه فورًا.
القيمتان
QDRANT_URL=https://xxxxxxxx.eu-central-1-0.aws.cloud.qdrant.io:6333
QDRANT_API_KEY=…
٠٤

Render — الخادم والعامل والطابور

ثلاث خدمات يعرّفها render.yaml دفعة واحدة: الـ API الذي يستقبل الطلبات، والعامل الذي ينفّذ التشغيلات الطويلة، وطابور Redis بينهما.

لماذا عامل منفصل

كتابة كتاب تستغرق ساعة. لا يوجد طلب HTTP يعيش ساعة. فالـ API يضع المهمة في الطابور ويردّ فورًا، والعامل يلتقطها وينفّذها ويكتب تقدّمه في قاعدة البيانات. لهذا أيضًا يجب أن يكون العامل على خطة مدفوعة: الخدمة المجانية تنام عند الخمول، والنائم يترك الكتاب في منتصفه.

أنشئ الخدمات

  1. من لوحة Render: New ← Blueprint.
  2. اربط حساب GitHub واختر مستودع contiai.
  3. سيقرأ render.yaml ويعرض الخدمات الثلاث. اضغط Apply.
  4. سيتوقف عند المتغيّرات المعلَّمة sync: false ويطلبها منك — املأها من الجدول التالي.

متغيّرات البيئة

المتغيّرالقيمة
DATABASE_URLرابط المُجمِّع من المرحلة ٢، بصيغة +asyncpg
CORS_ORIGINSاتركه مؤقتًا https://contiai.vercel.app — ستصحّحه في المرحلة ٦
SUPABASE_URLمن المرحلة ٢
SUPABASE_SERVICE_ROLE_KEYمن المرحلة ٢
SUPABASE_ANON_KEYمن المرحلة ٢
SUPABASE_JWT_SECRETمن المرحلة ٢
QDRANT_URLمن المرحلة ٣ — بالمنفذ ٦٣٣٣
QDRANT_API_KEYمن المرحلة ٣
OPENROUTER_API_KEYمفتاحك
MISTRAL_API_KEYمفتاحك
SERPER_API_KEYSمفتاح أو أكثر مفصولة بفواصل — تأكد من رصيدها، فالبحث كله يتوقف بنفادها
BOOTSTRAP_ADMIN_EMAILSبريدك — اقرأ التحذير أسفله

وهذان اختياريان، افتراضهما true ولا تحتاج ضبطهما عند النشر الأول: BOOK_PLANNING_V2 وBOOK_COHESION_V2. وجودهما لسبب واحد: كتاب بدأ تشغيله على مخطِّط لا بد أن يُنهيه عليه، فإن احتجت العودة إلى الجيل الأول فاضبط أحدهما على false — ولتشغيلة جارية فحسب.

بدون بريد المسؤول لن تستطيع الدخول

كل حساب جديد يُنشأ بحالة «قيد الموافقة»، ولا يوافق عليه إلا مسؤول. وفي نظام جديد لا يوجد مسؤول. العناوين المكتوبة هنا تصل معتمَدة وبصلاحية مسؤول — وهي الطريقة الوحيدة لفتح الباب أول مرة.

تحقّق من النشر

أول بناء يستغرق من ٨ إلى ١٥ دقيقة — الحزم ثقيلة. راقب سجلّ contiai-api حتى تجد Uvicorn running، ثم:

terminal
curl https://contiai-api.onrender.com/health
# {"status":"ok","env":"production","version":"1.0.0"}

وافتح سجلّ contiai-worker وتأكد من ظهور arq: Starting worker. عامل صامت يعني أن التشغيلات ستُوضع في الطابور ولا يلتقطها أحد.

٠٥

Vercel — الواجهة

الواجهة ملفات ثابتة تُبنى مرة وتُوزَّع عالميًا. المهم أن تُوجَّه إلى المجلد الصحيح داخل المستودع.

  1. من vercel.com/new استورد مستودع contiai.
  2. Root Directory: اضغط Edit واختر apps/web. هذه أكثر خطوة يُخطأ فيها — بدونها يبحث Vercel عن package.json في الجذر ولا يجده.
  3. Framework سيُكتشف تلقائيًا كـ Vite، والبناء والمخرجات مضبوطان في vercel.json.

متغيّرات البيئة

المتغيّرالقيمة
VITE_API_URLhttps://contiai-api.onrender.com — بلا شرطة مائلة في آخره
VITE_SUPABASE_URLمن المرحلة ٢
VITE_SUPABASE_ANON_KEYمفتاح anon فقط
المتغيّرات تُحقن وقت البناء

Vite يدمج قيم VITE_* داخل الجافاسكربت المبني. تغيير أيٍّ منها لاحقًا لا يظهر حتى تعيد النشر — من Deployments اضغط Redeploy.

اضغط Deploy. بعد دقيقتين ستحصل على رابط مثل contiai.vercel.app.

٠٦

ربط الطرفين

الآن يعرف كلٌّ من الطرفين عنوان الآخر. تبقى خطوة واحدة يسهل نسيانها، وأعراض نسيانها مُضلِّلة.

  1. انسخ عنوان Vercel الحقيقي.
  2. في Render ← contiai-api ← Environment، اضبط CORS_ORIGINS عليه.
  3. احفظ. Render سيعيد النشر تلقائيًا.
CORS_ORIGINS
https://contiai.vercel.app,https://contiai.com,https://www.contiai.com
عرَض نسيان هذه الخطوة

الموقع يفتح، وشاشة الدخول تظهر، وكل طلب يفشل بصمت. في وحدة تحكم المتصفح ستجد blocked by CORS policy. الخادم يعمل تمامًا — هو فقط لا يعرف أن هذا الأصل مسموح له.

٠٧

الدومين من Namecheap

الواجهة على الجذر و www، والـ API على نطاق فرعي api. ثلاثة سجلات، ثم تصحيح قيمتين.

أولًا: سجّل النطاقات عند المزوّدين

  1. في Vercel ← المشروع ← Settings ← Domains: أضف contiai.com و www.contiai.com.
  2. في Render ← contiai-api ← Settings ← Custom Domains: أضف api.contiai.com.

سيعرض كلٌّ منهما السجلات المطلوبة. القيم أدناه هي المعتادة، لكن اعتمد ما يعرضه المزوّد نفسه إن اختلف.

ثانيًا: في Namecheap

  1. Domain List ← Manage بجوار نطاقك.
  2. تبويب Advanced DNS.
  3. تأكد أن Nameservers في التبويب الأول مضبوطة على Namecheap BasicDNS — وإلا فسجلاتك هنا لن تُقرأ أصلًا.
  4. احذف سجلات CNAME و URL Redirect الافتراضية التي ينشئها Namecheap للنطاق الجديد.
  5. أضف الثلاثة التالية.
TypeHostValueTTL
A Record@76.76.21.21Automatic
CNAMEwwwcname.vercel-dns.comAutomatic
CNAMEapicontiai-api.onrender.comAutomatic
الانتشار

عادة من ١٠ دقائق إلى ساعة، وقد يمتد إلى ٤٨. شهادات TLS تصدر تلقائيًا من الطرفين بعد أن يريا السجل. تحقّق بـ nslookup api.contiai.com.

ثالثًا: صحّح القيمتين

بعد أن يعمل النطاق، لم يعد رابط onrender.com هو العنوان المعلن:

  1. Vercel ← VITE_API_URL ← https://api.contiai.com، ثم Redeploy.
  2. Render ← CORS_ORIGINS ← أضف https://contiai.com و https://www.contiai.com.
  3. Supabase ← Authentication ← URL Configuration ← Site URL و Redirect URLs ← نطاقك الجديد.
٠٨

التحقق النهائي

بالترتيب. كل بند يعتمد على الذي قبله، فالتوقف عند أول فشل يوفّر وقتًا.

أول تشغيلة حقيقية

ابدأ بأصغر مُدخل ممكن — تصوّر بيوم واحد، أو كتاب بفصلين. الهدف إثبات المسار كاملًا لا إنتاج مادة. وراقب لوحة OpenRouter أثناءها لترى الصرف يتحرك فعلًا.

٠٩

إذا تعطّل شيء

الأعطال المتوقعة وأعراضها. الرسالة المعروضة نادرًا ما تشير إلى السبب.

العَرَضالسببالحل
الموقع يفتح وكل طلب يفشل CORS_ORIGINS لا يطابق الأصل حرفيًا انسخ الأصل من شريط العنوان بلا شرطة أخيرة، وأعد النشر
الـ API يفشل عند الإقلاع alembic upgrade head لم يتصل بالقاعدة راجع DATABASE_URL: المنفذ ٦٥٤٣، وبادئة +asyncpg، وكلمة مرور مرمّزة
too many connections الاتصال المباشر على ٥٤٣٢ بدل المُجمِّع بدّل إلى رابط Transaction pooling
تشغيلات تبقى «في الانتظار» العامل نائم أو متوقف تأكد أنه على خطة Starter وأن REDIS_URL وصله
الاسترجاع لا يجد شيئًا QDRANT_URL بلا منفذ ٦٣٣٣ أضف :6333
لا يمكن الدخول لأي حساب لا مسؤول في النظام اضبط BOOTSTRAP_ADMIN_EMAILS وأعد النشر ثم سجّل من جديد
خطأ 402 في منتصف تشغيلة رصيد OpenRouter نفد اشحن، ثم اضغط «استئناف» — الخطوات المكتملة محفوظة
Vercel: No package.json مجلد الجذر غير مضبوط Settings ← General ← Root Directory ← apps/web
الدومين لا يُحل Nameservers ليست BasicDNS بدّلها في تبويب Domain ثم انتظر الانتشار
تغيير متغيّر في Vercel بلا أثر VITE_* تُحقن وقت البناء Redeploy

أين تقرأ

  • Render ← Logs — أخطاء الخادم والعامل. ابدأ من هنا دائمًا.
  • Vercel ← Deployments ← Build Logs — فشل البناء.
  • وحدة تحكم المتصفح — كل ما يخص CORS والمصادقة.
  • Supabase ← Logs ← Auth — محاولات الدخول المرفوضة.
١٠

التكلفة والتشغيل اليومي

الاشتراكات

الخدمةالخطةشهريًا
Render — APIStarter$7
Render — العاملStandard — ٢ غيغابايت~$25
Render — Redisمجاني$0
VercelHobby$0
SupabaseFree$0
QdrantFree$0
الإجمالي~$32

يُضاف إليها استهلاك النماذج، وهو المتغيّر الحقيقي: كتاب مكتمل نحو دولار بعد ضبط الميزانية، وحقيبة خمسة أيام بين ٣ و٥ حسب عدد المحاور.

لماذا العامل على Standard لا Starter

العامل يحمّل نموذج التضمين، والنموذج هو معظمه. قياس فعلي لا تقدير: بايثون وحده ١٨ ميجابايت، ومع torch ١٩١، ومع sentence-transformers ٣٧٨، والنموذج مُحمَّلًا ٦٩٨، وبعد ترميز دفعة ٧٩٣ ميجابايت. وStarter يعطي ٥١٢.

لو تُرك عليها لقُتل العامل لحظة تحميل المُرمِّز — أي عند الفهرسة، بعد أن يكون البحث والتنزيل قد دُفع ثمنهما — ولما قال السجل غير Exited with status 137.

أمّا الخادم فيبقى على Starter: استيرادات الأجنتس فيه مؤجَّلة داخل الدوال عمدًا، والنموذج لا يُحمَّل فيه أصلًا.

النشر بعد التعديل

كل دفعة إلى main تُطلق نشرًا في Render و Vercel معًا، و CI يشتغل قبلهما. لو رسب الاختبار أو ضُبط مفتاح مسرَّب، عالج ذلك قبل أن تدفع مرة أخرى.

terminal
cd C:\conti_ai\platform
git add -A
git commit -m "وصف التعديل"
git push

قبل كل دفعة

terminal
cd C:\conti_ai\platform
apps\api\.venv\Scripts\python.exe scripts\preflight.py

الاحتياطي

Supabase يأخذ نسخة يومية في الخطة المجانية ويحتفظ بها سبعة أيام. قبل أي ترحيل كبير خذ نسخة يدوية من Database ← Backups. وما في Qdrant قابل لإعادة البناء من المستندات المرفوعة، لكن إعادته تكلّف وقتًا واستدعاءات.