🛡️ تثبيت Zitadel — منصة الهوية وإدارة الوصول والمصادقة الموحدة (IAM) على Docker

نشر منصة Zitadel على Ubuntu باستخدام Docker — نظام إدارة الهوية والمصادقة مفتوح المصدر الرائد وبديل Auth0 مع دعم OIDC وSAML ومفاتيح المرور Passkeys على المنفذ 8171.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت مؤتمت — أمر واحد ينشر Zitadel على المنفذ 8171 مع قاعدة بيانات PostgreSQL ومفتاح التشفير الرئيسي 32-character ولوحة التحكم جاهزة.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/security/zitadel/zitadel-ubuntu.sh
chmod +x zitadel-ubuntu.sh
sudo bash zitadel-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/security/zitadel/zitadel-ubuntu.sh

2 منح صلاحية التنفيذ

chmod +x zitadel-ubuntu.sh

3 تشغيل المثبت

يقوم السكريبت بتثبيت Docker وتجهيز مجلد قاعدة البيانات (`./postgres-data`) وتوليد مفتاح التشفير الرئيسي (Master Key) وتشغيل منصة Zitadel على المنفذ 8171 (المحول من 8080 الداخلي).

sudo bash zitadel-ubuntu.sh

4 تسجيل الدخول وتهيئة التطبيقات

افتح متصفحك على الرابط http://ip-سيرفرك:8171. سجل الدخول ببيانات المشرف المولدة، واضبط هوية مؤسستك، وأنشئ أول عميل تطبيق يدعم بروتوكول OpenID Connect (OIDC) أو SAML.

http://<your-server-ip>:8171

المنافذ المستخدمة

المنفذالغرض
8171Web console + OIDC/SAML (host → container 8080) — ⚠️ TLS disabled
internalPostgreSQL 16 (zitadel-db, not published)
masterkey32 characters, generated — encrypts the database; back it up

نظرة عامة

تعد Zitadel منصة ونظام إدارة هوية ووصول (Identity & Access Management - IAM) ومصادقة مستخدمين عصرية وسحابية الأصل ومفتوحة المصدر تم بناؤها بلغة Go وقاعدة بيانات PostgreSQL بنمط تدفق الأحداث (Event Sourcing). تعمل المنصة عبر المنفذ 8171 (المحول من منفذ 8080 الداخلي) كبديل متطور لمنصات Auth0 وKeycloak. وتوفر مصادقة متكاملة ببروتوكولات OpenID Connect (OIDC) وOAuth 2.0 وSAML 2.0، مع دعم أصلي للمصادقة بدون كلمة مرور، ومفاتيح المرور البيومترية Passkeys (FIDO2/WebAuthn)، وتعدد المستأجرين (Multi-Tenancy) لتطبيقات الـ SaaS.

لماذا تستخدمه

تفرض منصات الهوية السحابية التجارية (مثل Auth0 وOkta وClerk) اشتراكات شهرية متزايدة تُحسب بعدد المستخدمين النشطين (MAU)، وتخزن بيانات مستخدميك في سحابات مغلقة، بينما تستهلك الأنظمة القديمة كـ Keycloak الكثير من موارد الرام. تمنحك Zitadel منصة هوية فائقة السرعة مبرمجة بلغة Go: إدارة عدد غير محدود من المستخدمين بدون أي رسوم تراخيص، وتفعيل مفاتيح المرور البيومترية الحديثة، وعزل عملاء الشركات في بيئات مستقلة، وسيادة كاملة لبياناتك بسيرفرك الخاص.

متى تحتاجه

  • تبني تطبيقات ويب أو موبايل وتحتاج لنظام تسجيل دخول ومصادقة آمن وجاهز (OIDC وOAuth2 وSAML)
  • تبحث عن بديل مفتوح المصدر ومستضاف ذاتياً لمنصات Auth0 وClerk وOkta بدون أي رسوم تُحسب بعدد المستخدمين
  • تريد تفعيل الدخول بدون كلمة مرور باستخدام مفاتيح المرور الحديثة Passkeys (FIDO2 / WebAuthn) والبصمة
  • تطور تطبيق SaaS موجه للشركات (B2B) يتطلب عزلاً للمستأجرين (Multi-Tenancy) وإمكانية ربط كل شركة بدليل مستخدميها
  • تحتاج لنظام هوية خفيف وسريع بلغة Go يستهلك ذاكرة RAM أقل بكثير من الأنظمة المعتمدة على جافا كـ Keycloak

من يحتاجه

  • مطورو الويب والتطبيقات لإضافة ميزات تسجيل الدخول والتسجيل وإدارة الجلسات لتطبيقاتهم البرمجية
  • فرق منتجات الـ SaaS لبناء منصات شركات متعددة المستأجرين مع ميزات تسجيل الدخول الموحد (SSO)
  • مهندسو الأمان والـ DevOps لتوحيد إدارة هويات المستخدمين والصلاحيات عبر الخدمات المستضافة ذاتياً
  • مديرو تقنية المعلومات بالمؤسسات لإدارة الدخول الموحد وسياسات الأمان والمصادقة متعددة العوامل (MFA)
  • أصحاب السيرفرات المنزلية لحماية خدماتهم بسيرفر هوية مركزي يعتمد على معايير OIDC الحديثة

حالات الاستخدام الشائعة

  • حماية تطبيق Next.js أو React بتسجيل دخول OIDC آمن والتحقق من الرموز المميزة (JWT) والصلاحيات
  • تفعيل تسجيل الدخول ببصمة الإصبع أو الوجه (TouchID / FaceID) ومفاتيح YubiKey للأمان المطلق
  • إنشاء منظمات مستقلة لعملاء الـ SaaS تمكنهم من ربط خوادم Active Directory أو Okta الخاصة بهم
  • ربط خدمات السيرفر المنزلي (Nextcloud وWiki.js وGrafana وPortainer) بمصادقة Zitadel الموحدة
  • تدقيق سجلات تسجيل الدخول وتغيير الصلاحيات عبر سجل الأحداث التراكمي المقاوم للتلاعب في Zitadel

الميزات الرئيسية

  • لوحة إدارة هوية عصرية على المنفذ 8171: واجهة بصرية لإدارة المستخدمين والمنظمات والمشاريع والتطبيقات
  • دعم كامل لـ OIDC وOAuth 2.0 وSAML 2.0: بروتوكولات قياسية متوافقة مع كافة لغات البرمجة وأطر العمل
  • مفاتيح المرور Passkeys (FIDO2/WebAuthn): دعم مدمج لتسجيل الدخول البيومتري ومفاتيح الأمان الفيزيائية
  • تعدد المستأجرين المدمج (B2B Multi-Tenancy): عزل تام لدلائل المستخدمين والنطاقات المخصصة لكل شركة عميلة
  • معمارية قائمة على تدفق الأحداث (Event Sourcing): سجل تدقيق شامل وغير قابل للتعديل لكافة التغييرات الأمنية
  • تحكم هرمي دقيق بالصلاحيات (RBAC): تحديد الأدوار والنطاقات وصلاحيات الوصول لكل مشروع
  • أداء فائق واستجابة لحظية بلغة Go: استهلاك ضئيل للذاكرة (~150 ميجابايت) وتحقق لحظي من صحة الرموز
  • معمارية Docker Compose تجمع خادم Zitadel بلغة Go مع قاعدة بيانات PostgreSQL 16

كيفية الاستخدام بعد التثبيت

  • افتح المتصفح وانتقل إلى الرابط http://ip-سيرفرك:8171
  • سجل الدخول بحساب المشرف وكلمة المرور المولدة بواسطة سكريبت التثبيت
  • احفظ المفتاح الرئيسي (Master Key) المكون من 32 حرفاً في مدير كلمات مرور مشفر (لا يمكن استرجاعه في حال فقدانه)
  • انتقل إلى Projects ← أنشئ مشروعاً جديداً وسجل عميل تطبيق OpenID Connect (OIDC)
  • انسخ مفاتيح Client ID وClient Secret إلى كود تطبيقك البرمجي لإتمام الربط
  • ضع Zitadel خلف وكيل عكسي مشفر بـ HTTPS (مثل Nginx) مع شهادة SSL صالحة
  • أعد سكريبت نسخ احتياطي دوري لمجلد قاعدة بيانات PostgreSQL (`./postgres-data`)

أفضل ممارسات الأمان

  • تنبيه أمني حاسم: احتفظ بنسخة من المفتاح الرئيسي (Master Key)؛ فبدونه لا يمكن فك تشفير قاعدة البيانات عند الترقية
  • استخدم تشفير HTTPS دائماً؛ حيث تتطلب بروتوكولات OIDC ومفاتيح Passkeys تشفيراً آمناً لتعمل بالمتصفح
  • فعل المصادقة الثنائية (MFA) أو مفاتيح Passkeys لكافة حسابات المشرفين
  • أبقِ منفذ قاعدة البيانات الداخلي PostgreSQL 5432 معزولاً عن الإنترنت العام
  • احمِ مجلد البيانات `./postgres-data` بصلاحيات نظام صارمة بالسيرفر (`chmod 700`)
  • حدّث صورة الحاوية دورياً للحصول على التحديثات الأمنية وإصلاحات الاستقرار

المنافذ وإعدادات جدار الحماية

يقدم Zitadel لوحة التحكم وواجهات OIDC/SAML عبر منفذ TCP 8171 (المحول من منفذ 8080 الداخلي). اسمح بالمنفذ 8171 للشبكة المحلية (`ufw allow 8171/tcp`). وفي الإنتاج، وجه حركة المرور عبر وكيل عكسي مشفر بـ SSL على المنفذ 443 ووجهه لمنفذ 8171، مع إبقاء المنفذ 8171 مغلقاً خارجياً وقاعدة البيانات معزولة.

النسخ الاحتياطي والصيانة

  • احتفظ بنسخة من سلسلة المفتاح الرئيسي (Master Key) المكون من 32 حرفاً في خزينة كلمات مرور آمنة
  • انسخ مجلد `./postgres-data` احتياطياً، والذي يحتوي على كامل قاعدة بيانات PostgreSQL بكافة المستخدمين والمشاريع
  • استخرج نسخة احتياطية يومية لقاعدة البيانات عبر pg_dump: `docker exec zitadel-db pg_dump -U zitadel zitadel > zitadel_backup.sql`
  • احتفظ بنسخة من ملف `docker-compose.yml` وملف المتغيرات `.env`
  • أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync

الأخطاء الشائعة

  • فقدان المفتاح الرئيسي (Master Key) مما يؤدي لفقدان الوصول الدائم للبيانات المشفرة عند إعادة تشغيل الحاوية
  • تشغيل Zitadel عبر HTTP غير المشفر في الإنتاج (حيث تحظر المتصفحات تقنية Passkeys على النطاقات غير المشفرة)
  • كتابة رابط النطاق الخارجي بشكل غير صحيح مما يعطل نقاط الاكتشاف التلقائي (`.well-known/openid-configuration`)
  • عدم ربط مجلد التخزين الدائم لقاعدة البيانات، مما يسبب مسح كافة المستخدمين عند تحديث الحاوية
  • نسيان ضبط نطاقات الـ CORS المسموح بها لتطبيقات الويب مثل React وNext.js

استكشاف الأخطاء وإصلاحها

  • ظهور خطأ 502 Bad Gateway بالواجهة — انتظر دقيقة لاكتمال إعداد الميجريشنز بقاعدة البيانات: `docker logs zitadel -f`
  • فشل تسجيل مفاتيح Passkeys / WebAuthn — تأكد من الدخول عبر نطاق مشفر بشهادة HTTPS (حيث تحظر المتصفحات الميزة على HTTP)
  • نقطة OIDC discovery تعيد عنوان IP داخلي — عدل متغير `ZITADEL_EXTERNALDOMAIN` في ملف `.env` ليطابق نطاقك العام
  • خطأ Invalid Master Key عند الإقلاع — تأكد من كتابة المفتاح المكون من 32 حرفاً بدقة كما تم استخدامه عند التثبيت الأول
  • فشل الاتصال بقاعدة البيانات — تأكد من صحة وعمل حاوية `zitadel-db` وتطابق البيانات بملف `.env`

البدائل

منصة Keycloak الرائدة والمعتمدة على جافا. منصة Authentik لإدارة الهوية والمسارات البصرية. منصة Authelia للتوثيق الثنائي وحماية المواقع. منصة Ory Kratos للمطورين. منصات Auth0 وClerk السحابية التجارية.

متى لا تستخدمه

تجنب استخدام Zitadel إذا كنت تبحث فقط عن بوابة توثيق ثنائية بسيطة جداً لوضع شاشة دخول أمام موقع ويب ثابت (حيث صُممت Authelia أو Authentik كبوابات توثيق أمامية). وإذا كانت بنيتك التحتية تعتمد على إضافات وتكاملات معقدة مبنية بلغة جافا، فإن Keycloak توفر قابلية تخصيص واسعة ببيئة جافا.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما هي منصة Zitadel وما الفرق بينها وبين Keycloak؟

منصة Zitadel هي نظام إدارة هوية حديث ومبني بلغة Go. على عكس Keycloak (المبني بلغة جافا والذي يستهلك موارد ضخمة)، يتميز Zitadel بخفة فائقة (~150 ميجابايت رام)، وسرعة إقلاع بالثواني، ودعم مدمج لتعدد المستأجرين (B2B Multi-Tenancy)، وسجل أحداث غير قابل للتلاعب.

ما هو المفتاح الرئيسي (Master Key) ولماذا هو بالغ الأهمية؟

المفتاح الرئيسي هو رمز تشفيري سري مكون من 32 حرفاً يُستخدم لتشفير بيانات المستخدمين والرموز في قاعدة بيانات PostgreSQL. يجب حفظ هذا المفتاح بأمان؛ فبدونه لا يمكن فك تشفير البيانات أو تشغيل المنصة.

هل يدعم Zitadel مفاتيح المرور البيومترية (Passkeys)؟

نعم! يدعم Zitadel بشكل أصلي ومباشر تسجيل الدخول بدون كلمة مرور باستخدام مفاتيح المرور Passkeys (مثل بصمة الإصبع، وبصمة الوجه، ومفاتيح الأمان الفيزيائية YubiKey).

هل يمكن استخدام Zitadel لتطبيقات الـ SaaS الموجهة للشركات؟

نعم! صُمم Zitadel خصيصاً لتطبيقات الـ B2B SaaS متعددة المستأجرين. حيث يمكنك إنشاء منظمات مستقلة لكل عميل تجاري ليدير مستخدميه وصلاحياته ويربط خوادم المصادقة الخاصة بشركته.

كم يستهلك نظام Zitadel من الذاكرة العشوائية (RAM)؟

تستهلك منظومة Zitadel الكاملة (خادم Go مع قاعدة PostgreSQL) عادة ما بين 150 إلى 350 ميجابايت فقط من الرام داخل Docker، مما يجعلها أخف بكثير من البدائل المعتمدة على جافا.