استضافة Supabase ذاتياً على VPS باستخدام Docker
شغّل حزمة Supabase الرسمية على خادمك: بدّل الأسرار التجريبية، وافهم وظائف الخدمات الإحدى عشرة، وتحقّق من RAM والنسخ الاحتياطية والتحديثات.
ما ستبنيه
تعني استضافة Supabase ذاتياً تشغيل حزمة Docker Compose الرسمية على خادمك: Postgres، وREST API أمامه، وخدمة مصادقة، وتخزين ملفات، وwebsockets للبيانات الفورية، ولوحة Studio. تستنسخ مستودعاً واحداً، وتعدّل ملف .env واحداً، ثم تشغّل إحدى عشرة حاوية تعمل معاً مثل مشروع Supabase تتحكم فيه.
التثبيت قصير. أما الجزء الذي يسبب المشكلات فهو ملف .env. يأتي هذا الملف بأسرار تجريبية منشورة في المستودع، وتكون الحزمة التي تبدأ بهذه القيم الافتراضية مفتوحة لأي شخص يعثر عليها. يشرح هذا الدليل الأسرار التي يجب استبدالها، والغرض من كل خدمة، وحجم الذاكرة الذي تحتاج إليه الحزمة فعلياً، وكيفية تحديثها دون حذف قاعدة بياناتك.
إذا كانت Compose جديدة عليك، فاقرأ أولاً أساسيات Docker Compose على VPS. تفترض جميع الخطوات أدناه أن الأمر docker compose version يعرض إصداراً بالفعل.
ما الذي يتكوّن منه المكدس فعلياً
Supabase ليس برنامجاً واحداً. يبدأ ملف Compose مجموعة من الخدمات المنفصلة على شبكة واحدة. ومعرفة وظيفة كل خدمة تحوّل قائمة أسماء الحاويات الطويلة إلى مكوّنات يمكنك تصحيح أخطائها.
dbهو PostgreSQL مع تحميل إضافات Supabase. تتصل به جميع الخدمات الأخرى. إذا كانت هذه الحاوية غير سليمة، تفشل جميع الخدمات الأخرى أيضاً.api-gwهو بوابة API. منذ إصدار August 2026، يشغّل Envoy. وقبل ذلك، كان يشغّل خدمة تُسمىkong، بينما لا يزال Kong متاحاً كتجاوز اختياري. يستمع على المنفذ 8000 ويوجّه/rest/v1/و/auth/v1/و/storage/v1/إلى الواجهة الخلفية المناسبة. هذه هي الحاوية الوحيدة التي ينبغي أن تعرّضها للإنترنت.restهو PostgREST. يقرأ مخطط Postgres ويقدّمه كواجهة REST API. لذلك يصبح الجدول الجديد نقطة نهاية جديدة دون كتابة أي كود.authهو GoTrue. يُصدر رموز الويب JSON (JWT) التي تحدد هوية المستخدمين.storageوimgproxyيتوليان تحميل الملفات وتغيير حجم الصور.realtimeيبث تغييرات قاعدة البيانات عبر websockets.studioوmetaهما لوحة المعلومات وواجهة الإدارة API التي تقف خلفها.functionsهو بيئة التشغيل الطرفية التي تعتمد على Deno، وsupavisorهو مجمّع اتصالات Postgres.
غادرت السجلات والتحليلات (Logflare وvector) ملف Compose الافتراضي في June 2026. وأصبحا الآن في ملف تجاوز اختياري تفعّله باستخدام sh run.sh config add logs، وفق طبقات ملفات Compose نفسها الموضحة في تشغيل مكدس واحد من عدة ملفات Compose.
لهذا السبب تكون أرقام الموارد أدناه على ما هي عليه. أنت لا تشغّل قاعدة بيانات فقط. أنت تشغّل قاعدة بيانات بالإضافة إلى عشر خدمات مساندة.
اختيار الموارد: خطّط لـ 8 GB من RAM
استهلكت الحزمة نحو 2.5 إلى 3 GB من الذاكرة المقيمة وهي في حالة خمول بعد تثبيت جديد في يوليو 2026، وذلك قبل إضافة بياناتك أو حركة الشبكة. وكانَت خدمة التحليلات وعملية Studio في Node.js أكبر مستهلكين منفردين للذاكرة في ذلك القياس. لم تعد التحليلات جزءاً من الحزمة الافتراضية، لذلك لن تستهلك الذاكرة إلا إذا فعّلت تجاوز إعدادات السجلات. سيبدأ خادم بسعة 2 GB الحاويات، ثم يوقف kernel إحداها بسبب نفاد الذاكرة. وتظهر المشكلة في بقاء حاوية في حالة إعادة تشغيل مع exit code 137. تذكر وثائق Supabase الخاصة بالاستضافة الذاتية، التي فُحصت في أكتوبر 2026، أن الحد الأدنى هو 4 GB من RAM ونواتا CPU و40 GB من SSD، وأن الموارد الموصى بها هي 8 GB و4 أنوية و80 GB.
خصص 8 GB من RAM و4 vCPU لأي شيء تعتمد عليه. تكفي 4 GB لبيئة تطوير فردية إذا قبلت بأن يكون الاستعلام الثقيل وجلسة Studio في الوقت نفسه بطيئين. وتهم مساحة القرص أيضاً، لأن Postgres ووحدة التخزين وبيانات السجلات، إذا فعّلت السجلات، توجد كلها ضمن دليل المشروع. ابدأ بـ40 GB وراقب الاستخدام. يُعدّ حصر الخدمات قبل اختيار الخطة عادة مفيدة لأي برنامج تستضيفه ذاتياً، لأن PhotoPrism وImmich لهما أيضاً حد أدنى فعلي من RAM: تطلب صفحة البدء السريع لـImmich، التي فُحصت في أكتوبر 2026، ما لا يقل عن 6 GB من RAM ونواتي CPU. إذا كان ذلك يتطلب خادماً أكبر من حاجة مشروعك حالياً، فقارنه بـما تتضمنه فعلياً خطة Supabase السحابية المجانية، لأن تطبيقاً صغيراً يظل استخدامه أقل من 500 MB ولا يبقى خاملاً لمدة أسبوع قد يعمل هناك دون تكلفة.
التثبيت: استنسخ المستودع الرسمي
ينسخ المسار المدعوم دليل docker من المستودع الرئيسي إلى دليل مشروع تملكه. هذا الفصل مهم، لأنه يمنع git pull لاحقاً من الكتابة فوق .env.
git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pullينزّل docker compose pull عدة غيغابايت من الصور. يجب أن ينتهي مع وضع علامة Pulled على كل خدمة. يعني خطأ manifest unknown هنا أن وسم الصورة المثبّت أُزيل من المستودع الأصلي، والحل هو سحب نسخة أحدث من المستودع بدلاً من تعديل الوسوم يدوياً.
الأسرار التي يجب تغييرها قبل التشغيل الأول
نفّذ ذلك قبل بدء الـstack، وليس بعده. تُكتب عدة قيم من هذه القيم في البيانات عند التشغيل الأول، لذا يعني تغييرها لاحقاً إعادة ضبط قاعدة البيانات.
يحتوي المستودع على مولّد يُنشئ كل قيمة بطريقة صحيحة، بما في ذلك مفتاحَي API اللذين يجب توقيعهما باستخدام JWT secret الجديد.
sh utils/generate-keys.sh --update-envيكتب ذلك السكربت قيماً جديدة لـJWT_SECRET وANON_KEY وSERVICE_ROLE_KEY وSECRET_KEY_BASE وREALTIME_DB_ENC_KEY وVAULT_ENC_KEY وPG_META_CRYPTO_KEY، ورموز Logflare، ومفاتيح بروتوكول S3، وMINIO_ROOT_PASSWORD داخل .env. واعتباراً من October 2026، يكتب أيضاً قيماً عشوائية لـPOSTGRES_PASSWORD وDASHBOARD_PASSWORD. يحتاج السكربت إلى openssl، وهو موجود في أي Ubuntu image عادية. وبما أنه يعيد الآن كتابة كلمة مرور قاعدة البيانات أيضاً، شغّله باستخدام --update-env قبل التشغيل الأول فقط، ولا تشغّله مطلقاً على stack يحتوي على بيانات.
ما زال من المفيد التحقق يدوياً من قيمتين في .env:
POSTGRES_PASSWORD. يملؤه السكربت بقيمة hex عشوائية، وهذا آمن. إذا استبدلته بقيمتك الخاصة، فاستخدم الأحرف والأرقام فقط. تؤدي علامات الترقيم هنا إلى كسر connection strings التي تنشئها عدة خدمات بضم السلاسل، ويبدو الفشل كأنه خطأ مصادقة بدلاً من خطأ تحليل، ما يوجّه البحث إلى المكان الخطأ.DASHBOARD_USERNAMEوDASHBOARD_PASSWORD. هاتان هما بيانات اعتماد basic authentication الخاصة بـStudio. يعيّن السكربت كلمة مرور عشوائية، لكنه يترك اسم المستخدم على القيمة الافتراضيةsupabase. كلمة المرور الافتراضية المضمّنة هي حرفياًthis_password_is_insecure_and_should_be_updated، لذا غيّرها الآن إذا تخطيت تشغيل السكربت.
افهم سبب عدم إمكانية اختراع ANON_KEY وSERVICE_ROLE_KEY. كلاهما JWT موقّع باستخدام JWT_SECRET. لا يقبل الـgateway إلا المفتاحين المطابقين تماماً في .env، وتتحقق الخدمات الموجودة خلفه من التوقيع مقابل JWT_SECRET، لذلك يُرفض أي مفتاح غير مطابق مع HTTP 401. يعيد Envoy gateway الافتراضي 401 Unauthorized، وكذلك Kong override الحالي، الذي يشغّل Kong 3.9 ويعيد {"message":"Unauthorized"}. كانت عمليات التثبيت السابقة لـMarch 2026 تشغّل Kong 2.8، الذي يعيد {"message":"Invalid authentication credentials"}. هذا هو أكثر أسباب فشل الاستضافة الذاتية شيوعاً: غيّر المشغّل JWT_SECRET، لكنه أبقى مفاتيح العرض التجريبي. أنشئ القيم الثلاث معاً دائماً.
تعامل مع SERVICE_ROLE_KEY كما تتعامل مع كلمة مرور root. فهي تتجاوز row level security بالكامل. يجب أن تبقى في server side code فقط، ولا تضعها في أي مكان آخر.
عيّن SITE_URL إلى عنوان تطبيقك، وAPI_EXTERNAL_URL إلى العنوان العام للـAPI مع إضافة /auth/v1 في نهايته، مثل https://supabase.example.com/auth/v1. عيّن SUPABASE_PUBLIC_URL إلى العنوان العام نفسه من دون المسار. ينشئ Auth روابط تأكيد البريد الإلكتروني وروابط OAuth callback من هذه القيم، لذا فإن تركها على القيم الافتراضية localhost يرسل كل مستخدميك إلى أجهزتهم هم.
ثم تحقّق من القيم التي لديك:
sh run.sh secretsشغّله وتحقّق من سلامته
sh run.sh start
docker compose psيغلّف run.sh start الأمر docker compose up -d --wait، لذلك لا يعيد التحكم حتى تنجح فحوصات السلامة. يجب أن تعرض كل خدمة الحالة running (healthy) أو running. تستغرق عملية الإقلاع الأولى من دقيقتين إلى 4 دقائق، لأن Postgres يشغّل نصوص التهيئة قبل أن يتمكن أي مكوّن آخر من الاتصال.
إذا كانت إحدى الحاويات تعيد التشغيل، فاقرأ سجلاتها باستخدام اسم الخدمة:
docker compose logs db
docker compose logs authيعمل Studio بعد ذلك على المنفذ 8000، وسيطلب اسم مستخدم لوحة التحكم وكلمة المرور اللذين عيّنتهما.
لا تضع المنفذ 8000 على الإنترنت العام
تستخدم البوابة على المنفذ 8000 بروتوكول HTTP غير المشفّر. يعبر كل مفتاح API وكل كلمة مرور للمستخدم الشبكة بنص واضح، كما أن بيانات اعتماد Studio تستخدم المصادقة الأساسية، وهي ترميز base64 وليست تشفيراً.
ضع Reverse Proxy أمامها، وأنهِ TLS (أمان طبقة النقل) عنده، واربط البوابة بعنوان loopback حتى لا يتمكن أي طرف آخر من الوصول إليها. في docker-compose.yml يصبح سطر المنفذ الموجود ضمن خدمة api-gw هو 127.0.0.1:${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000/tcp، ثم يوجّه الـproxy الطلبات إلى ذلك المنفذ. في التثبيتات التي أُجريت قبل التحول إلى Envoy في August 2026، يوجد سطر المنفذ نفسه ضمن خدمة تُسمى kong بدلاً من ذلك. يشرح Traefik أمام عدة تطبيقات Compose جانب الشهادات. وينتهي الأمر بأن يضع ذلك الـproxy كل شيء آخر على الخادم أمامه أيضاً، بدءاً من هذه الحزمة ووصولاً إلى شيء غير جاد مثل مكتبة Jellyfin أُعيد بناؤها كمتجر فيديو من حقبة التسعينيات، إذ يحتاج كل منها إلى اسم مضيف بدلاً من منفذ مفتوح إضافي. إذا كانت لوحة المعلومات مخصصة لك وحدك دائماً، فتجاوز الـproxy ووصل إلى منفذ loopback عبر نفق SSH بدلاً من ذلك، وهو النهج نفسه الذي يستخدمه self-hosted open-kritt لإبقاء واجهة الفحص الخاصة به خارج الإنترنت العام بالكامل.
أغلق المنافذ المتبقية في جدار الحماية أيضاً، لأن Docker ينشر المنافذ عبر كتابة قواعد iptables الخاصة به، ولا ترى إعدادات ufw الساذجة هذه القواعد مطلقاً. يشرح سبب تجاهل حاويات Docker لقواعد ufw هذا الفخ.
أنشئ نسخة احتياطية من قاعدة البيانات، وليس من الدليل
توجد بيانات Postgres في bind mount ضمن ./volumes/db/data. يؤدي نسخ هذا الدليل أثناء تشغيل الحاوية إلى إنشاء نسخة غير متسقة، لأن Postgres يخزّن عمليات الكتابة مؤقتاً، ولا تكون الملفات على القرص متسقة إلا عند إنشاء checkpoint. وعادةً ما تنجح استعادة هذه النسخة، لكنها قد تفقد بصمت آخر المعاملات أحياناً. وهذا أسوأ نمط فشل ممكن في النسخ الاحتياطي.
استخدم dump بدلاً من ذلك. يعمل pg_dumpall داخل الحاوية وينشئ لقطة متسقة:
docker exec -t supabase-db pg_dumpall -U postgres > supabase-$(date +%F).sqlتحقق من أن الملف غير فارغ قبل الوثوق به. ثم انقل ملفات dump هذه خارج الخادم وفق جدول زمني. وهذا هو الغرض من النسخ الاحتياطية المشفّرة خارج الموقع باستخدام restic. لا يمكن تمييز عملية dump مجدولة تفشل بصمت عن عدم وجود نسخة احتياطية إطلاقاً. لذلك اجعل مهمة cron أو systemd ترسل تنبيهاً إلى هاتفك عند خروجها برمز غير صفري. أنشئ نسخة احتياطية من .env في الوقت نفسه. يعني فقدان JWT_SECRET أن كل token مُصدَر سيصبح غير صالح، وأن كل secret مشفّر مخزّن سيصبح غير قابل للقراءة.
توجد الملفات المُحمّلة في ./volumes/storage. وهذه ملفات عادية، لذلك يكفي نسخها بالطريقة المعتادة.
التحديث من دون فقدان البيانات
تثبّت Supabase إصدارات الصور في docker-compose.yml، لذلك لا يتغير شيء حتى تغيّره أنت. يستحق تثبيت الإصدارات النسخَ في أي مكدس تنشئه يدوياً. لذلك يثبّت مرحل RustDesk مستضافاً ذاتياً صورتي الخادم بدلاً من اتباع وسم متغير. يجب أن يكون التحديث خطوة تختار تنفيذها في صباح يتوفر لديك فيه الوقت. أنشئ تفريغاً للبيانات أولاً، في كل مرة.
docker compose pull
sh run.sh recreateيوقف recreate المكدس ثم يعيد تشغيله باستخدام الصور الجديدة. تبقى بياناتك محفوظة لأنها توجد في نقاط الربط على المضيف، لا داخل الحاويات. اقرأ CHANGELOG.md في المستودع قبل الانتقال بين الإصدارات الرئيسية، لأن ترقية Postgres الرئيسية خطوة منفصلة لا ينفذها recreate. أصبح Postgres 17 هو الإصدار الافتراضي منذ June 2026، ويمكن نقل تثبيت موجود على Postgres 15 إليه باستخدام sudo bash utils/upgrade-pg17.sh. يستخدم هذا الأمر pg_upgrade لترحيل البيانات في مكانها، ويطلب التأكيد عند كل خطوة رئيسية. يتطلب تشغيل جميع الحاويات ومساحة قرص حرة لا تقل عن ضعف حجم قاعدة بياناتك مضافاً إليه 5 GB. وما زالت Supabase توصي بإنشاء نسخة احتياطية مستقلة خاصة بك قبل البدء.
لتطبيق التغييرات على ملف Compose نفسه، شغّل sh update.sh من دليل المشروع، أو استخدم sh update.sh --dry-run لعرض التغييرات المتوقعة أولاً. يدمج هذا الأمر الملفات الأصلية مع تعديلاتك، ولا يستبدل القيم الموجودة في .env أبداً؛ بل يضيف المفاتيح الجديدة فقط. كما يؤرشف إعداداتك ضمن backups/ قبل الكتابة، لكنه لا يؤرشف قاعدة البيانات. يحتاج التثبيت الذي لا يحتوي على ملف .supabase-version إلى --from والإصدار الذي بدأ منه. وهذا مهم خصوصاً لإصدار August 2026، الذي استبدل خدمة kong بخدمة api-gw ويتطلب تحديث docker-compose.yml. وما زال الأسلوب اليدوي يعمل أيضاً: استنسخ المستودع الأصلي مرة أخرى، وانسخ دليل docker منه إلى مشروعك، مع الحرص على عدم استبدال .env.
إعادة الضبط الكاملة، التي تدمر كل شيء بما في ذلك قاعدة البيانات وتعيد .env إلى القيم الافتراضية، مع الاحتفاظ بالإعداد القديم باسم .env.old، هي برنامج نصي منفصل ويطلب التأكيد:
sh reset.shFAQ
لماذا تُرجع استدعاءات API لدي الرسالة "Invalid authentication credentials"؟
تأتي هذه الرسالة حرفياً من Kong 2.8، وهو الـgateway المضمّن في الـstack عند التثبيتات التي سبقت March 2026. أما الـgateway الافتراضي Envoy وتهيئة Kong الحالية، التي تشغّل Kong 3.9، فيبلّغان عن المشكلة نفسها بصيغة 401 عادي Unauthorized. في كلتا الحالتين، لا يتطابق المفتاح الذي أرسلته مع ANON_KEY أو SERVICE_ROLE_KEY في .env، أو لم تُوقَّع هذه المفاتيح باستخدام JWT_SECRET الموجود حالياً في .env. إذا كان الـstack لم يحتفظ ببيانات من قبل، فأعد إنشاء القيم الثلاث معاً باستخدام sh utils/generate-keys.sh --update-env. أما إذا كان الـstack قيد التشغيل، فشغّل البرنامج النصي من دون هذا الخيار وأجب بـ no، حتى يطبع القيم الجديدة فقط. انسخ JWT_SECRET وANON_KEY وSERVICE_ROLE_KEY يدوياً إلى .env، واترك POSTGRES_PASSWORD من دون تغيير. ثم شغّل sh run.sh recreate لكي تقرأ الخدمات القيم الجديدة.
هل يمكنني تشغيل Supabase مستضاف ذاتياً على VPS بسعة 2 GB؟
ليس بشكل موثوق. تذكر وثائق Supabase الخاصة بالاستضافة الذاتية أن الحد الأدنى هو 4 GB من RAM اعتباراً من October 2026. كما استهلك الـstack نحو 3 GB عند الخمول اعتباراً من July 2026، وفق قياس شمل خدمات التسجيل، وهي خدمات أصبحت اختيارية الآن. يفقد خادم بسعة 2 GB حاويات بسبب out of memory killer، وسترى exit code 137 في docker compose ps. استخدم 8 GB في بيئة الإنتاج، واعتبر 4 GB الحد الأدنى للتطوير الفردي.
هل يتضمن Supabase المستضاف ذاتياً edge functions؟
نعم. يتضمن ملف Compose runtime للوظائف يستند إلى Deno، ويخدم كل ما تضعه ضمن ./volumes/functions. لكنه لا يتضمن شبكة النشر العالمية الخاصة بالمنصة المستضافة، لذلك تعمل وظائفك على خادمك الواحد وفي موقع واحد.
كيف أتصل بقاعدة بيانات Postgres مباشرة؟
استخدم docker exec -it supabase-db psql -U postgres لفتح shell تفاعلي على الخادم نفسه. للاتصال من عميل خارجي، اتصل عبر Supavisor على المنفذ 5432 باستخدام المستخدم postgres.<POOLER_TENANT_ID> وPOSTGRES_PASSWORD الخاص بك. لا تفتح هذا المنفذ أمام الإنترنت. اتصل به عبر VPN أو نفق SSH.
لماذا كانت رسائل تأكيد المصادقة لدي تتضمن روابط إلى localhost؟
تُركت SITE_URL وAPI_EXTERNAL_URL في .env على قيمهما الافتراضية. تنشئ خدمة المصادقة كل رابط لتأكيد الحساب وإعادة تعيين كلمة المرور من هاتين القيمتين، لذلك ترسل العنوان المحدد فيهما. اضبط القيمتين على عنوان URL العام الحقيقي لديك، ثم أعد إنشاء الـstack.