تشغيل Supabase ذاتياً على VPS باستخدام Docker

ما الذي ستبنيه

يعني تشغيل Supabase ذاتياً تشغيل حزمة Docker Compose الرسمية على خادمك: Postgres، وواجهة REST API أمامه، وخدمة المصادقة، وتخزين الملفات، وWebSockets للبيانات الفورية، ولوحة تحكم Studio. تستنسخ مستودعاً واحداً، وتعدّل ملف .env واحداً، وتشغّل نحو أربعة عشر container تعمل معاً مثل مشروع Supabase تتحكم فيه.

التثبيت قصير. لكن مصدر المشكلات هو ملف .env. يأتي هذا الملف مع أسرار تجريبية منشورة في المستودع، وتكون الحزمة التي تبدأ بهذه القيم الافتراضية مفتوحة أمام أي شخص يعثر عليها. يوضّح هذا الدليل الأسرار التي يجب استبدالها، ووظيفة كل خدمة، وحجم الذاكرة الذي تحتاج إليه الحزمة فعلياً، وكيفية تحديثها من دون حذف قاعدة البيانات.

إذا كان Compose جديداً عليك، فاقرأ أساسيات Docker Compose على VPS أولاً. يفترض كل ما يلي أن الأمر docker compose version يعرض إصداراً بالفعل.

ما الذي يتكوّن منه المكدس فعلياً

Supabase ليس برنامجاً واحداً. يشغّل ملف Compose مجموعة من الخدمات المنفصلة على شبكة واحدة. ومعرفة وظيفة كل خدمة تحوّل قائمة طويلة من أسماء الحاويات إلى مكوّنات يمكن تشخيصها.

• db هو PostgreSQL مع تحميل إضافات Supabase. تتصل به جميع الخدمات الأخرى. إذا كانت هذه الحاوية غير سليمة، تفشل جميع الخدمات الأخرى أيضاً.
• kong هو بوابة API. يستمع على المنفذ 8000 ويوجّه /rest/v1/ و/auth/v1/ و/storage/v1/ إلى الواجهة الخلفية المناسبة. هذه هي الحاوية الوحيدة التي ينبغي تعريضها للإنترنت.
• rest هو PostgREST. يقرأ مخطط Postgres ويقدّمه كواجهة REST API، لذلك يتحول الجدول الجديد إلى نقطة نهاية جديدة من دون كتابة تعليمات برمجية.
• auth هو GoTrue. يُصدر رموز الويب JSON (JWT) التي تحدد هوية المستخدمين.
• storage وimgproxy يتوليان رفع الملفات وتغيير حجم الصور.
• realtime يبث تغييرات قاعدة البيانات عبر WebSockets.
• studio وmeta هما لوحة التحكم وواجهة الإدارة التي تعمل خلفها.
• analytics (Logflare) وvector يجمعان السجلات، بينما supavisor هو مجمّع اتصالات Postgres.

لهذا السبب تظهر أرقام الموارد أدناه بهذه القيم. أنت لا تشغّل قاعدة بيانات فقط. أنت تشغّل قاعدة بيانات بالإضافة إلى 12 خدمة مساندة.

تحديد الموارد: خطّط لـ 8 GB من ذاكرة RAM

تستهلك الحزمة نحو 2.5 إلى 3 GB من الذاكرة المقيمة في وضع الخمول عند التثبيت الجديد، وذلك حتى يوليو 2026، قبل إضافة بياناتك أو حركة الشبكة الخاصة بك. تُعد خدمة التحليلات وعملية Studio في Node.js أكبر مستهلكين منفردين للموارد. سيشغّل خادم بسعة 2 GB الحاويات، ثم سيفقد إحداها بسبب قاتل نفاد الذاكرة في kernel، وعادةً ما تكون analytics أو db. ويتمثل العَرَض في بقاء حاوية عالقة في حلقة إعادة تشغيل مع رمز خروج 137.

خصص 8 GB من ذاكرة RAM و4 vCPU لأي خدمة تعتمد عليها. تكفي 4 GB لبيئة تطوير فردية إذا كنت تقبل أن يكون الاستعلام الثقيل وجلسة Studio في الوقت نفسه بطيئين. وتهم مساحة القرص أيضاً، لأن Postgres ووحدة التخزين وبيانات السجلات كلها موجودة ضمن مجلد المشروع. ابدأ بـ 40 GB وراقب الاستخدام. يُعد حصر الخدمات قبل اختيار الخطة عادةً مفيدة لأي برنامج تستضيفه ذاتياً، لأن PhotoPrism وImmich لهما حد أدنى فعلي من ذاكرة RAM أعلى بكثير مما توحي به صفحات البدء السريع الخاصة بهما.

التثبيت: استنسخ المستودع الرسمي

ينسخ المسار المدعوم دليل 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 الجديد.

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 المميّزة داخل .env. ويحتاج إلى openssl، وهو متوفر في أي صورة Ubuntu عادية.

لا يضبط البرنامج النصي قيمتين، ويجب عليك تعديلهما يدوياً في .env:

• POSTGRES_PASSWORD. استخدم الأحرف والأرقام فقط. تؤدي علامات الترقيم هنا إلى كسر سلاسل الاتصال التي تنشئها عدة خدمات عبر وصل السلاسل، ويظهر الفشل كأنه خطأ مصادقة بدلاً من خطأ تحليل، ما يدفعك إلى البحث في المكان الخطأ.
• DASHBOARD_USERNAME وDASHBOARD_PASSWORD. هاتان هما بيانات اعتماد المصادقة الأساسية لـStudio. كلمة المرور الافتراضية المضمّنة هي حرفياً this_password_is_insecure_and_should_be_updated.

افهم سبب عدم إمكانية اختراع ANON_KEY وSERVICE_ROLE_KEY. فكلاهما JWT موقّع باستخدام JWT_SECRET. تتحقق البوابة من هذه التوقيعات في كل طلب، لذلك يُرفض أي مفتاح لا يطابق سرك مع {"message":"Invalid authentication credentials"}. هذا هو أكثر أعطال الاستضافة الذاتية شيوعاً: غيّر المشغّل JWT_SECRET لكنه أبقى مفاتيح العرض التجريبي. أنشئ القيم الثلاث معاً دائماً.

تعامل مع SERVICE_ROLE_KEY كما تتعامل مع كلمة مرور root. فهو يتجاوز أمان مستوى الصف بالكامل. يجب أن يبقى في الشيفرة الموجودة على الخادم، ولا ينبغي وضعه في أي مكان آخر.

اضبط SITE_URL وAPI_EXTERNAL_URL على العنوان الذي سيصل إليه المستخدمون فعلياً، مثل https://supabase.example.com. ينشئ Auth روابط تأكيد البريد الإلكتروني وروابط callback الخاصة بـOAuth من هذه القيم، لذلك يؤدي إبقاؤها على http://localhost:8000 إلى توجيه كل مستخدميك إلى أجهزتهم هم.

ثم تحقّق من القيم التي لديك:

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 على الإنترنت العام

يتحدث Kong على المنفذ 8000 باستخدام HTTP عادي. تعبر كل مفاتيح API وكلمات مرور المستخدمين الشبكة بنص واضح، كما أن بيانات اعتماد Studio تستخدم المصادقة الأساسية، وهي ترميز base64 وليست تشفيراً.

ضع reverse proxy أمامه، وأنهِ TLS (أمان طبقة النقل) عنده، واربط Kong بعنوان loopback حتى لا يتمكن أي شيء آخر من الوصول إليه. في docker-compose.yml تصبح مواءمة المنافذ kong إلى 127.0.0.1:8000:8000، ثم يوجّه الـproxy الطلبات إلى ذلك المنفذ. يشرح استخدام Traefik أمام عدة تطبيقات Compose جانب الشهادات. وينتهي هذا الـproxy نفسه أمام كل شيء آخر على الخادم، بدءاً من هذه الحزمة ووصولاً إلى شيء غير جاد مثل مكتبة Jellyfin أُعيد بناؤها كمتجر فيديو من التسعينيات، وكل خدمة منها تحتاج إلى اسم مضيف بدلاً من فتح منفذ إضافي. إذا كانت لوحة المعلومات مخصصة لك وحدك، فتجاوز الـproxy ووصل إلى منفذ loopback عبر نفق SSH بدلاً من ذلك، وهي الطريقة نفسها التي يستخدمها 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 المكدس ويشغّله مجدداً باستخدام الصور الجديدة. تبقى بياناتك محفوظة لأنها موجودة في عمليات الربط mount على المضيف، وليست داخل الحاويات. اقرأ CHANGELOG.md في المستودع قبل الانتقال إلى إصدار رئيسي جديد، لأن ترقيات Postgres الرئيسية ليست تلقائية وتحتاج إلى تفريغ البيانات واستعادتها.

لتطبيق التغييرات على ملف Compose نفسه، استنسخ المستودع الأساسي مرة أخرى وانسخ دليل docker منه فوق مشروعك، مع الحرص على عدم الكتابة فوق .env.

إعادة الضبط الكاملة، التي تدمر كل شيء بما في ذلك قاعدة البيانات، موجودة في برنامج نصي منفصل ويطلب تأكيداً:

sh reset.sh

FAQ

لماذا تُرجع استدعاءات API لدي "بيانات اعتماد مصادقة غير صالحة"؟

لم يتم توقيع ANON_KEY أو SERVICE_ROLE_KEY باستخدام JWT_SECRET الموجود حالياً في .env. تتحقق البوابة من التوقيع في كل طلب وترفض أي عدم تطابق. أعد إنشاء القيم الثلاث معاً باستخدام sh utils/generate-keys.sh --update-env، ثم شغّل sh run.sh recreate لكي تقرأ الخدمات القيم الجديدة.

هل يمكنني تشغيل Supabase مستضافاً ذاتياً على VPS بسعة 2 GB؟

ليس بشكل موثوق. يستهلك المكدس نحو 3 GB عند الخمول اعتباراً من July 2026، لأنه يشغّل نحو fourteen خدمة. لذلك يفقد خادم بسعة 2 GB الحاويات بسبب قاتل نفاد الذاكرة، وتظهر لك exit code 137 في docker compose ps. استخدم 8 GB في بيئة الإنتاج، واعتبر 4 GB الحد الأدنى للتطوير الفردي.

هل يتضمن Supabase المستضاف ذاتياً edge functions؟

نعم. يتضمن ملف Compose بيئة تشغيل functions المبنية على Deno، ويخدم كل ما تضعه ضمن ./volumes/functions. لكنه لا يتضمن شبكة النشر العالمية للمنصة المستضافة، لذلك تعمل 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 العام الحقيقي، ثم أعد إنشاء المكدس.