قبل أن تبدأ
خمسة حسابات وبطاقة واحدة. لا تبدأ قبل أن تكون كلها جاهزة، لأن كل مرحلة تُنتج قيمة تحتاجها المرحلة التالية.
الحسابات
- 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 كمجلد جذر للمشروع.
أنشئ المستودع
- افتح
github.com/new. - الاسم
contiai، واجعله Private. - لا تضف README ولا .gitignore — موجودان بالفعل.
ارفع الملفات
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 وبناء الواجهة.
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 يكتب فيها النظام كل مشروع وتشغيلة وخطوة، ومزوّد هوية يصدر رموز الدخول التي يتحقق منها الخادم.
أنشئ المشروع
- من
supabase.com/dashboardاضغط New project. - الاسم
contiai، والمنطقة Frankfurt (eu-central-1) — نفس منطقة Render، فكل مللي ثانية بين الاثنين تتكرر في كل استعلام. - ولّد كلمة مرور قاعدة البيانات واحفظها الآن. لن تُعرض مرة أخرى، وستحتاجها بعد دقائق.
اجمع القيم الأربع
| القيمة | من أين | تُستخدم في |
|---|---|---|
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. الرابط يشبه:
postgresql://postgres.abcdefghijkl:PASSWORD@aws-0-eu-central-1.pooler.supabase.com:6543/postgres
حوّله إلى الصيغة التي يقبلها الخادم — أضف +asyncpg واحذف أي ?pgbouncer=true:
postgresql+asyncpg://postgres.abcdefghijkl:PASSWORD@aws-0-eu-central-1.pooler.supabase.com:6543/postgres
الاتصال المباشر على ٥٤٣٢ محدود العدد، وخادم واحد على Render يستنفده
ثم يبدأ برفض الطلبات برسالة too many connections. المُجمِّع
على ٦٥٤٣ هو المقصود. وإن كانت كلمة المرور تحوي رمزًا مثل
@ أو # فرمّزها بترميز النسبة المئوية.
إعدادات المصادقة
- Authentication ← Providers ← Email: فعّله. وإن أردت تجربة سريعة بلا بريد تأكيد، أطفئ Confirm email مؤقتًا.
- Authentication ← URL Configuration ← Site URL: ضع رابط Vercel أو دومينك النهائي.
- في Redirect URLs أضف نطاقك و
http://localhost:5173للتطوير. - لتفعيل الدخول بجوجل: Providers ← Google، وضع Client ID و Secret من Google Cloud Console، ثم انسخ رابط الاستدعاء الذي يعرضه Supabase إلى إعدادات جوجل.
ملفّا SQL — بعد أول نشر ناجح
alembic upgrade head يعمل وحده عند إقلاع خادم Render
وينشئ جداول المنصة كلها. يبقى ملفان يُشغَّلان بيدك في
SQL Editor، وبهذا الترتيب، وبعد أن ينجح النشر الأول —
لأن الثاني يبني على جداول لا توجد قبله:
-
infra/sql/001_rag_documents.sql— الجداول الثلاثة التي يكتب فيها كود الاسترجاع المنقول:documents_rawوdocuments_metadataوchunks. هذه لا ينشئها alembic لأن ذلك الكود لا يمرّ بـ SQLAlchemy أصلًا؛ يكلّم Supabase مباشرة. كانت موجودة في المشروع القديم لأن أحدهم أنشأها بيده، وعلى مشروع جديد يفشل أول استيعاب لأول كتاب بـrelation "documents_raw" does not exist— بعد أن تكون قد دفعت ثمن البحث والتنزيل. -
infra/sql/002_rls.sql— سياسات الحماية. طبقة ثانية: الخادم يقيّد كل استعلام بالمالك أصلًا، وهذه تجعل قاعدة البيانات ترفض بنفسها لو أفلت استعلام غير مقيَّد. -
infra/sql/003_rls_remainder.sql— الجداول التي كُتب الملف الثاني قبل وجودها. منهاuploadsوprofiles، ولكلٍّ منهما مالك — أي أنهما كانا بلا أي حماية بينما المفتاح المنشور في متصفّح كل زائر.
كلاهما يُشغَّل مرتين بلا ضرر.
Qdrant — فهرس المتجهات
هنا تُخزَّن مقاطع المصادر بعد تقطيعها، ومنها يسترجع الكاتب الأدلة التي يبني عليها كل محور.
- من
cloud.qdrant.ioأنشئ عنقودًا مجانيًا في Frankfurt. - انسخ رابط العنقود. لا بد أن ينتهي بالمنفذ
:6333— واجهة REST تستمع هناك، ومن دونه يفشل كل استرجاع بخطأ اتصال غامض. - من 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 يضع المهمة في الطابور ويردّ فورًا، والعامل يلتقطها وينفّذها ويكتب تقدّمه في قاعدة البيانات. لهذا أيضًا يجب أن يكون العامل على خطة مدفوعة: الخدمة المجانية تنام عند الخمول، والنائم يترك الكتاب في منتصفه.
أنشئ الخدمات
- من لوحة Render: New ← Blueprint.
- اربط حساب GitHub واختر مستودع
contiai. - سيقرأ
render.yamlويعرض الخدمات الثلاث. اضغط Apply. - سيتوقف عند المتغيّرات المعلَّمة
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، ثم:
curl https://contiai-api.onrender.com/health
# {"status":"ok","env":"production","version":"1.0.0"}
وافتح سجلّ contiai-worker وتأكد من ظهور
arq: Starting worker. عامل صامت يعني أن التشغيلات ستُوضع
في الطابور ولا يلتقطها أحد.
Vercel — الواجهة
الواجهة ملفات ثابتة تُبنى مرة وتُوزَّع عالميًا. المهم أن تُوجَّه إلى المجلد الصحيح داخل المستودع.
- من
vercel.com/newاستورد مستودعcontiai. - Root Directory: اضغط Edit واختر
apps/web. هذه أكثر خطوة يُخطأ فيها — بدونها يبحث Vercel عنpackage.jsonفي الجذر ولا يجده. - Framework سيُكتشف تلقائيًا كـ Vite، والبناء والمخرجات مضبوطان في
vercel.json.
متغيّرات البيئة
| المتغيّر | القيمة |
|---|---|
VITE_API_URL | https://contiai-api.onrender.com — بلا شرطة مائلة في آخره |
VITE_SUPABASE_URL | من المرحلة ٢ |
VITE_SUPABASE_ANON_KEY | مفتاح anon فقط |
Vite يدمج قيم VITE_* داخل الجافاسكربت المبني. تغيير أيٍّ
منها لاحقًا لا يظهر حتى تعيد النشر — من Deployments اضغط
Redeploy.
اضغط Deploy. بعد دقيقتين ستحصل على رابط مثل contiai.vercel.app.
ربط الطرفين
الآن يعرف كلٌّ من الطرفين عنوان الآخر. تبقى خطوة واحدة يسهل نسيانها، وأعراض نسيانها مُضلِّلة.
- انسخ عنوان Vercel الحقيقي.
- في Render ←
contiai-api← Environment، اضبطCORS_ORIGINSعليه. - احفظ. Render سيعيد النشر تلقائيًا.
https://contiai.vercel.app,https://contiai.com,https://www.contiai.com
الموقع يفتح، وشاشة الدخول تظهر، وكل طلب يفشل بصمت. في وحدة تحكم
المتصفح ستجد blocked by CORS policy. الخادم يعمل تمامًا —
هو فقط لا يعرف أن هذا الأصل مسموح له.
الدومين من Namecheap
الواجهة على الجذر و www، والـ API على نطاق فرعي
api. ثلاثة سجلات، ثم تصحيح قيمتين.
أولًا: سجّل النطاقات عند المزوّدين
- في Vercel ← المشروع ← Settings ← Domains: أضف
contiai.comوwww.contiai.com. - في Render ←
contiai-api← Settings ← Custom Domains: أضفapi.contiai.com.
سيعرض كلٌّ منهما السجلات المطلوبة. القيم أدناه هي المعتادة، لكن اعتمد ما يعرضه المزوّد نفسه إن اختلف.
ثانيًا: في Namecheap
- Domain List ← Manage بجوار نطاقك.
- تبويب Advanced DNS.
- تأكد أن Nameservers في التبويب الأول مضبوطة على Namecheap BasicDNS — وإلا فسجلاتك هنا لن تُقرأ أصلًا.
- احذف سجلات
CNAMEوURL Redirectالافتراضية التي ينشئها Namecheap للنطاق الجديد. - أضف الثلاثة التالية.
| Type | Host | Value | TTL |
|---|---|---|---|
| A Record | @ | 76.76.21.21 | Automatic |
| CNAME | www | cname.vercel-dns.com | Automatic |
| CNAME | api | contiai-api.onrender.com | Automatic |
عادة من ١٠ دقائق إلى ساعة، وقد يمتد إلى ٤٨. شهادات TLS تصدر تلقائيًا
من الطرفين بعد أن يريا السجل. تحقّق بـ
nslookup api.contiai.com.
ثالثًا: صحّح القيمتين
بعد أن يعمل النطاق، لم يعد رابط onrender.com هو العنوان المعلن:
- Vercel ←
VITE_API_URL←https://api.contiai.com، ثم Redeploy. - Render ←
CORS_ORIGINS← أضفhttps://contiai.comوhttps://www.contiai.com. - 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 — API | Starter | $7 |
| Render — العامل | Standard — ٢ غيغابايت | ~$25 |
| Render — Redis | مجاني | $0 |
| Vercel | Hobby | $0 |
| Supabase | Free | $0 |
| Qdrant | Free | $0 |
| الإجمالي | ~$32 |
يُضاف إليها استهلاك النماذج، وهو المتغيّر الحقيقي: كتاب مكتمل نحو دولار بعد ضبط الميزانية، وحقيبة خمسة أيام بين ٣ و٥ حسب عدد المحاور.
العامل يحمّل نموذج التضمين، والنموذج هو معظمه. قياس فعلي لا تقدير:
بايثون وحده ١٨ ميجابايت، ومع torch ١٩١، ومع
sentence-transformers ٣٧٨، والنموذج مُحمَّلًا ٦٩٨،
وبعد ترميز دفعة ٧٩٣ ميجابايت. وStarter يعطي ٥١٢.
لو تُرك عليها لقُتل العامل لحظة تحميل المُرمِّز — أي عند الفهرسة،
بعد أن يكون البحث والتنزيل قد دُفع ثمنهما — ولما قال السجل غير
Exited with status 137.
أمّا الخادم فيبقى على Starter: استيرادات الأجنتس فيه مؤجَّلة داخل الدوال عمدًا، والنموذج لا يُحمَّل فيه أصلًا.
النشر بعد التعديل
كل دفعة إلى main تُطلق نشرًا في Render و Vercel معًا،
و CI يشتغل قبلهما. لو رسب الاختبار أو ضُبط مفتاح مسرَّب، عالج ذلك قبل
أن تدفع مرة أخرى.
cd C:\conti_ai\platform
git add -A
git commit -m "وصف التعديل"
git push
قبل كل دفعة
cd C:\conti_ai\platform
apps\api\.venv\Scripts\python.exe scripts\preflight.py
الاحتياطي
Supabase يأخذ نسخة يومية في الخطة المجانية ويحتفظ بها سبعة أيام. قبل أي ترحيل كبير خذ نسخة يدوية من Database ← Backups. وما في Qdrant قابل لإعادة البناء من المستندات المرفوعة، لكن إعادته تكلّف وقتًا واستدعاءات.