ترقية خدمات Supabase وKong

النطاق الحالي

تُثبت بيئة الإنتاج حالياً على الإصدارات والبصمات الموجودة في docker-compose.yml:

الخدمة	الإصدار
Kong Gateway	3.9.3
GoTrue	2.189.0
PostgREST	14.12
Realtime	2.102.3
Storage API	1.60.4
Postgres Meta	0.96.6
Studio	2026.08.03-sha-022b374
PostgreSQL	15.14.1.116

خطر

لا تغيّر PostgreSQL إلى 17 ضمن هذا الإجراء. ترقية major لها runbook منفصل، وبدء صورة PG17 على volume PG15 غير مدعوم وقد يمنع الإقلاع.

الأسرار المطلوبة

يجب أن يحتوي .env.prod على قيم مستقلة:

SECRET_KEY_BASE=<at-least-64-characters>
REALTIME_DB_ENC_KEY=<exactly-16-characters>
PG_META_CRYPTO_KEY=<at-least-32-characters>

تولّد مرة واحدة فقط وتحفظ في مدير الأسرار. لا تستخدم JWT_SECRET بديلاً عنها، ولا تطبع القيم في السجل.

بوابات ما قبل الترقية

1. تأكد أن كل الخدمات الحالية healthy أو running بلا إعادة تشغيل.
2. افحص المساحة والاتصالات وإصدار PostgreSQL وترميز قاعدة البيانات.
3. خذ نسخة pg_dump -Fc تحفظ المالكين والصلاحيات، ونسخة pg_dumpall --globals-only.
4. أرشف volume التخزين وملفات Compose وKong ونسخة .env.prod بصلاحية 0600.
5. تحقق من pg_restore -l وgzip -t وSHA-256 لكل artifact.
6. افحص الصور المرشحة بالبصمة الدقيقة:

SCAN_IMAGES=0 SCAN_INFRA_IMAGES=1 \
  ./infrastructure/scripts/security-scan.sh

النتائج المقبولة تخضع لملف ratchet في infrastructure/security/image-vulnerability-baseline.json. أي زيادة تفشل الفحص؛ انخفاض العدد لا يتطلب تعديل baseline فوراً.

اختبار clone الإلزامي

أنشئ قاعدة مؤقتة باسم واضح من نسخة الإنتاج، ولا تستخدم قاعدة postgres الحية:

docker exec shambus-db dropdb -U postgres --if-exists --force shambus_upgrade_canary
docker exec shambus-db createdb -U postgres -T template0 -O postgres shambus_upgrade_canary
docker exec -i shambus-db pg_restore -U postgres -d shambus_upgrade_canary \
  --exit-on-error < /path/to/postgres.dump

شغّل الصور المرشحة على شبكة داخلية منفصلة، بالترتيب:

1. GoTrue؛ تحقق من /health ومن بقاء عدد auth.users ثابتاً.
2. PostgREST؛ استخدم PGRST_DB_SCHEMAS=public وpostgrest --ready.
3. Realtime؛ تحقق من tenant health بعد اكتمال migrations.
4. Storage؛ تحقق من /status ومن عدم تغير عدد storage.objects.
5. Postgres Meta وStudio؛ تحقق من /health و/api/platform/profile.
6. Kong؛ اعرض config النهائي أولاً ثم شغّل kong config parse بالصورة نفسها.

في baseline المؤرخ 2026-08-09 انتقلت جداول migrations على clone من:

• Auth: 51 إلى 76
• Storage: 18 إلى 61
• Realtime: 15 إلى 31

هذه الأرقام ليست assertions دائمة للإنتاج؛ هي دليل تدقيق للترقية المذكورة. البوابة الدائمة هي نجاح migrations، الصحة، وثبات بيانات المستخدمين/الكائنات.

عقود البوابة

يجب أن تنجح قبل وبعد النشر:

الطلب	المتوقع
Auth health مع apikey	200
REST table مع apikey	200
REST table بلا apikey	401
/rest/v1/	404
/realtime/v1/api/tenants	404
/realtime/v1/api/openapi	404
Kong /metrics داخلياً	200

يُعطّل PostgREST OpenAPI عبر PGRST_OPENAPI_MODE=disabled، ويضيف Kong deny route مستقلاً كدفاع ثانٍ. لا تعرض schema storage من PostgREST؛ تمر عمليات الملفات عبر Storage API فقط.

النشر المرحلي

اعرض Kong أولاً؛ الملف الناتج يحتوي API keys ويجب أن يبقى 0640 وضمن مجموعة Kong:

./infrastructure/scripts/render-production-kong-config.sh

ثم استبدل خدمة واحدة أو مجموعة مترابطة في كل مرحلة مع --wait، ولا تستخدم down أو --remove-orphans:

docker compose --env-file .env.prod \
  -f docker-compose.yml -f docker-compose.prod.yml --profile prod \
  up -d --no-deps --wait meta studio

docker compose --env-file .env.prod \
  -f docker-compose.yml -f docker-compose.prod.yml --profile prod \
  up -d --no-deps --wait rest kong

docker compose --env-file .env.prod \
  -f docker-compose.yml -f docker-compose.prod.yml --profile prod \
  up -d --no-deps --wait auth realtime storage imgproxy

بعد كل مرحلة افحص الصحة، RestartCount=0، السجلات، وعقود API. إذا فشلت مرحلة، لا تكمل التالية.

التحقق والرجوع

بعد النجاح شغّل اختبارات الأدوار، تدفقات الحجز، صفحات الشركة/الإدارة، ومراقبة Prometheus. تحقق أن عدد المستخدمين والحجوزات وكائنات التخزين لم يتغير بسبب الترقية.

للرجوع:

1. أعد ملفات Compose/Kong السابقة.
2. أعد الصور القديمة بالبصمات المسجلة.
3. لا تستعد قاعدة البيانات تلقائياً إذا كانت migrations الجديدة متوافقة رجوعياً.
4. إذا لزم rollback للبيانات، أوقف الكتّاب، استعد dump وglobals وvolume التخزين كوحدة واحدة، ثم اختبر العدادات والعقود قبل فتح المرور.
5. احذف قاعدة وشبكة وحاويات canary بالاسم الدقيق فقط بعد اكتمال نافذة التحقق.