SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor · آخر تحديث في 2026-11-16

استضافة Zitadel ذاتيًا على VPS باستخدام Docker

يحتاج Zitadel نفسه إلى نحو 512 MB من RAM. تعلّم إعداد PostgreSQL وmasterkey وTLS وSMTP والنسخ الاحتياطية على VPS واحد، وما تفعله الترقية بقاعدة البيانات.

متطلبات استضافة Zitadel ذاتياً على خادم افتراضي خاص (VPS)

لاستضافة Zitadel ذاتياً على خادم افتراضي خاص، تحتاج إلى مضيف Docker، واسم نطاق عام يشير إليه، وقاعدة بيانات PostgreSQL، وموارد كافية من المعالج والذاكرة لكليهما. يقدّر دليل الإنتاج الخاص بـ Zitadel استهلاك التطبيق نفسه بحوالي 512 ميجابايت من الذاكرة ونواة معالج واحدة. يزداد هذا الاستهلاك مع نمو قاعدة البيانات وعمليات تشفير كلمات المرور. يعمل Zitadel كمزود هوية؛ فهو يصدر رموزاً عبر بروتوكولي OIDC (OpenID Connect) وSAML (Security Assertion Markup Language)، مما يغني خدماتك الأخرى عن الاحتفاظ بقوائم مستخدمين خاصة بها. يتكون التثبيت من curl وdocker compose up. العناصر الحاسمة لاستمرارية الخدمة هي المفتاح الرئيسي (masterkey)، ومستخدم قاعدة البيانات، وSMTP (بروتوكول نقل البريد البسيط)، والنسخ الاحتياطي، والترقية الأولى.

يفترض كل ما يلي استخدام Ubuntu 24.04، وDocker Engine 24 أو أحدث مع إضافة Compose بالإصدار 2.24.4 أو أحدث، واسم نطاق مثل auth.example.com يشير بالفعل إلى الخادم. تستخدم طبقات TLS الإضافية !override، والتي تتطلب إصدار Compose المذكور.

ما مقدار موارد VPS التي يحتاج إليها Zitadel؟

يطلب البدء السريع باستخدام Compose في وثائق Zitadel ذاكرة RAM بسعة 2 GB. هذا الرقم مخصص للبدء السريع. وينشر دليل Zitadel للإنتاج أرقاماً مختلفة.

رسم بيانيZitadel's own published sizing guidance, October 2026
البيانات وراء هذا الرسم البياني
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

هذه توصيات منشورة وليست قياسات من خادم قيد التشغيل. تعامل معها باعتبارها تصوراً لحجم المشكلة. عملية Zitadel نفسها صغيرة؛ إذ يقدّر الدليل حاجتها إلى نحو 0.5 GB من ذاكرة RAM، ويذكر أنها يمكن أن تعمل بأقل من نواة CPU واحدة. وتُستخدم الأنوية في تجزئة كلمات المرور، وهي عملية بطيئة عمداً. لذلك تصل دفعة من عمليات تسجيل الدخول على شكل ارتفاع مفاجئ في استخدام CPU، ويوصي الدليل بإتاحة 4 أنوية CPU لها. أما PostgreSQL فهو الجزء الآخر من المتطلبات: يخصص الدليل نفسه نحو نواة واحدة لكل 100 طلب في الثانية، و4 GB من ذاكرة RAM لكل نواة.

الصفّان الأعلى من حيث المتطلبات لا يصفان خادماً واحداً. لإعداد عالٍ للتوافر بالحد الأدنى، يوصي الدليل بعنقود من ثلاث عقد، لكل منها 4 أنوية و16 GB، ويذكر أنه يمكنك خفض ذلك إلى نحو 4 أنوية و8 GB لكل عقدة إذا استبعدت جمع السجلات والمقاييس. ولا يحدد الدليل متطلبات لعقدة واحدة.

لذلك سيشغّل VPS بسعة 2 GB هذه الحزمة، لكنه أقل بكثير من المتطلبات التي يخصصها الدليل لقاعدة البيانات وحدها عند وصول حركة مرور فعلية. تسجيل الدخول هو الخدمة التي تعتمد عليها كل الخدمات الأخرى. وعندما تتوقف، لا تسمح أي خدمة تثق بها بدخول أي مستخدم. من المعقول أن تقرر أن ميزانية قاعدة البيانات وتجزئة كلمات المرور في الدليل تتجاوز ما تريد إنفاقه على المصادقة، ومن الأرخص بكثير اتخاذ هذا القرار الآن بدلاً من اتخاذه بعد عملية ترحيل. يغطي مقارنة Keycloak وAuthentik وZitadel تكلفة كل منها من حيث الذاكرة والجهد التشغيلي، ويُعد خادم Authentik مستضافاً ذاتياً الإجابة المعتادة على خادم أصغر.

الحصول على الحزمة وتثبيت الإصدار

mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .env

يحدد هذا الملف أربع خدمات ستشغلها فعلياً. يعمل Traefik كوكيل عكسي (reverse proxy): فهو يوجّه الطلبات حسب المسار، وينهي اتصال TLS (أمن طبقة النقل) باستخدام الطبقة الإضافية المذكورة أدناه. zitadel-api هو ملف Go الثنائي على المنفذ 8080. zitadel-login هي واجهة تسجيل الدخول التي يتم تقديمها في /ui/v2/login. postgres يحتوي على كل شيء. يوجد ذاكرة تخزين مؤقت Redis وجامع OpenTelemetry في نفس الملف خلف ملفات تعريف Compose، ويظلان متوقفين حتى تطلبهما.

لا تشغل docker compose up بعد. التشغيل الأول ينشئ المثيل، وهناك إعدادات عديدة أدناه لا يمكن تغييرها لاحقاً دون عمل إضافي.

يقوم .env الذي نسخته بتثبيت وسوم الصور الخاصة به:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

الإصدار الحالي v4 هو v4.20.3، الذي صدر في 13 نوفمبر 2026، وهو يسبق الإصدار المثبت في الملف المرفق بأربعة إصدارات فرعية. الإصدار الذي يسبق v4.20.0، وهو v4.19.5 الصادر في 15 أكتوبر 2026، هو أول إصدار تغطيه الاستشارة التقنية A-10018 من Zitadel: أصبحت نقاط نهاية القوائم في واجهات برمجة تطبيقات v1 وv2 تطبق حدوداً افتراضية وقصوى، لذا فإن العميل الذي يطلب قائمة دون تحديد حد لن يحصل على كل النتائج بعد الآن وسيتعين عليه استخدام الترقيم، كما يتم رفض الطلب الذي يطلب أكثر من الحد الأقصى. يحمل كل إصدار لاحق، بما في ذلك v4.20.0، هذا التغيير. اضبط ZITADEL_VERSION على الإصدار الذي تنوي تشغيله، والتزم بخط إصدارات v4 بدلاً من تتبع كل ما هو جديد. تخطَّ v4.18.0 إذا اخترت إصداراً يدوياً: تشير ملاحظات إصداره إلى أن خطوة الإعداد تفشل في ذلك الإصدار، وتوصي باستخدام v4.19.0 بدلاً منه. يقوم curl المذكور أعلاه بسحب docker-compose.yml من فرع main، وهو غير مثبت على إصدار معين، لذا احفظ نسختك من كلا الملفين في مستودع git. بخلاف ذلك، سيؤدي تنفيذ نفس الأمر على خادم جديد الشهر المقبل إلى الحصول على ملف مختلف ولن تعرف ما الذي تغير.

استبدل LOGIN_SESSION_COOKIE_SECRET في .env بقيمة عشوائية يتم إنشاؤها بواسطة openssl rand -base64 32. تستخدم واجهة تسجيل الدخول هذه القيمة لتوقيع ملفات تعريف ارتباط الجلسة، وتحذر ملاحظات إصدار v4.19.5 صراحةً من الاحتفاظ بالقيمة الافتراضية.

امنح Postgres مستخدماً خاصاً وكلمة مرور فعلية

يتصل .env المرفق بـPostgreSQL باستخدام حساب superuser، مع كلمة المرور postgres:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

توجد هنا نقطة مهمة في خطوة التحصين. توصي وثائق Zitadel بإضافة POSTGRES_ZITADEL_PASSWORD إلى .env، لكن docker-compose.yml الأساسي لا يقرأ هذا المتغير مطلقاً، لذلك لا يؤدي ضبطه إلى أي تغيير. أما تغيير POSTGRES_ADMIN_PASSWORD وحده فيؤدي إلى فشل الاتصال، لأن كلمة المرور مكتوبة أيضاً حرفياً داخل سلسلة DSN (اسم مصدر البيانات). وسلسلة DSN هي التي تحدد كيفية اتصال Zitadel.

توضح التعليقات في .env.example بقية الأمر بوضوح: عند ضبط DSN، يستخدم Zitadel ذلك المستخدم مباشرةً ولا ينشئ مستخدماً غير مميّز نيابةً عنك، لذلك يجب أن يكون الدور موجوداً قبل التشغيل الأول. أنشئ كلمة مرور للدور، واضبط POSTGRES_ADMIN_PASSWORD على كلمة مرور عشوائية مستقلة في .env قبل بدء Postgres، ثم ابدأ Postgres وحده وأنشئ الدور. تطبّق صورة Postgres كلمة مرور المسؤول هذه فقط عند تهيئة دليل بيانات فارغ؛ أما تغيير .env لاحقاً فلا يغيّر كلمة مرور قاعدة بيانات موجودة.

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

تُنفَّذ استدعاءات psql داخل الحاوية عبر socket المحلي لها. وتثق صورة Postgres الرسمية بهذا الاتصال، لذلك لا تطلب كلمة مرور. الملكية هي الجزء المهم. تنشئ مرحلة التهيئة في Zitadel مخططاتها الخاصة (eventstore وprojections وsystem) وجداولها. تمنح ملكية قاعدة البيانات الدور صلاحية CREATE اللازمة لتهيئة هذه المخططات. ويُعد تغيير PostgreSQL 15 لصلاحيات CREATE على مخطط public أمراً منفصلاً، ولا يعني أن تهيئة مخططات Zitadel ستفشل.

وجّه DSN الآن إلى الدور الجديد، واحتفظ بكلمة مرور المسؤول التي ضبطتها قبل بدء Postgres:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

يُبقي sslmode=disable اتصال قاعدة البيانات غير مشفّر على شبكة Compose الخاصة، ولا يُنشر منفذها إلى المضيف مطلقاً. يوصي دليل قواعد بيانات Zitadel باستخدام TLS لاتصالات قواعد البيانات في بيئة الإنتاج. بعد اكتمال التشغيل الأول، تحقّق من أن الدور يملك بياناته فعلاً:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

يجب أن يعرض ذلك مخطط eventstore ومخطط projections ومخطط system. إذا كانت هذه المخططات مفقودة، فهذا يعني أن مرحلة التهيئة لم تصل إلى هذه النقطة، وسيذكر سجل حاوية API السبب.

المفتاح الرئيسي، وتكلفة فقدانه

يشفّر Zitadel الأسرار قبل تخزينها: بيانات اعتماد موفّر الهوية، وكلمة مرور SMTP، وبذور كلمات المرور لمرة واحدة، ومفاتيح الآلات. يفتح المفتاح الرئيسي هذه البيانات كلها. يبلغ طوله 32 بايت بالضبط، وتوضح الوثائق تبعات ذلك صراحةً: لا يمكن تغييره من دون فقدان الوصول إلى البيانات المشفّرة.

أنشئ مفتاحاً واستبدل سطر العنصر النائب في .env:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

حرّر سطر ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters بدلاً من إلحاق سطر ثانٍ. يستخدم Compose التعريف الأخير للمفتاح المتكرر، لذلك ينجح الإلحاق فعلياً، لكن وجود سطرين للمفتاح الرئيسي في الملف قد يسبب خطأً لمن يقرأه لاحقاً.

فكّر الآن في مكان وجود هذا المفتاح. يبدأ ملف Compose حاوية API كما يلي:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

لذلك يوجد المفتاح الرئيسي في سطر أوامر الحاوية، حيث يعرضه docker inspect لأي شخص يستطيع الوصول إلى Docker socket. في VPS يديره مسؤول واحد، تُعد هذه مقايضة مقبولة، كما أن الوضع في .env هو ما يحمي المفتاح على القرص. إذا لم تكن هذه المقايضة مقبولة، فحمّل المفتاح كملف واستخدم --masterkeyFile /run/secrets/zitadel-masterkey بدلاً من ذلك، إذ يحفظ القيمة خارج وسائط العملية.

انسخ المفتاح الرئيسي إلى مدير كلمات المرور قبل التشغيل الأول. لا يظهر المفتاح في تفريغ قاعدة البيانات، لذلك يؤدي استرداد تفريغ باستخدام مفتاح رئيسي مختلف إلى إنشاء مثيل لا يستطيع قراءة أسراره بنفسه. احتفظ به في مكان مختلف عن الأرشيف الذي يحتوي على التفريغ، حتى لا تتضمن نسخة احتياطية مسروقة كلاً من البيانات المشفّرة والمفتاح اللازم لفتحها.

حدّد النطاق الخارجي قبل التشغيل الأول

ZITADEL_DOMAIN في .env يمرّر البيانات إلى ZITADEL_EXTERNALDOMAIN داخل الحاوية، وهو الاسم الذي يكتبه المستخدمون. يشتق Zitadel منه مُصدِر OIDC، والعنوان الأساسي لواجهة تسجيل الدخول، ونقاط نهاية SAML، واسم تسجيل الدخول للمسؤول الأول، لذلك فهو ليس شكلياً.

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

يحدّد Zitadel المثيل الذي تتواصل معه استناداً إلى ترويسة Host. إذا لم تطابق هذه الترويسة نطاقاً معروفاً لديه، فستحصل كل طلباتك على النتيجة نفسها:

ID=QUERY-1kIjX Message=Instance not found

تحقّق من أمرين عند ظهور هذا الخطأ. إما أن ZITADEL_DOMAIN ليس الاسم الذي تتصفّح إليه، أو أن Proxy أمام الخادم يعيد كتابة Host إلى عنوان الخادم المَصْدَري. ويؤدي التصفّح إلى عنوان IP الخاص بالخادم بدلاً من الاسم إلى النتيجة نفسها.

يمكنك تغيير هذه القيم لاحقاً. يجب أن يعيد Zitadel تشغيل مرحلة الإعداد ليتعرف على التغيير، بينما تحتفظ كل التطبيقات التي سجّلتها مسبقاً بعناوين URI القديمة لإعادة التوجيه. اختيار الاسم النهائي الآن أقل كلفة بكثير من نقله لاحقاً.

إنهاء TLS باستخدام طبقة Let's Encrypt

بالنسبة إلى نطاق عام، أضف طبقة Let's Encrypt الخاصة بـZitadel. فهي تحوّل Traefik لاستخدام تحدي HTTP في ACME (بيئة إدارة الشهادات التلقائية)، وتستبدل المنافذ المنشورة بالمنفذين 80 و443، لذلك يجب ألا تشغل أي خدمة أخرى أيّاً منهما على الخادم.

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

تضبط الطبقة أيضاً ZITADEL_EXTERNALPORT: 443 وZITADEL_EXTERNALSECURE: true على حاوية API، ولذلك يتطابق عنوان URL العام مع عناوين URL التي ينشئها Zitadel لنفسه. يجب أن يُحل سجل A قبل البدء، لأن تحدي HTTP يفشل بدونه.

إذا كنت تنهي TLS مسبقاً على nginx أو على موازن تحميل، فاستخدم docker-compose.mode-external-tls.yml بدلاً من ذلك، واضبط TRAEFIK_TRUSTED_IPS على النطاقات التي يرسل منها الوكيل الطلبات. لا يعتمد Traefik ترويسات X-Forwarded-* إلا إذا جاءت من عناوين موجودة في تلك القائمة. وتضبط الطبقة صراحةً عنوان URL الخارجي وعناوين URL لتسجيل الدخول في Zitadel على HTTPS.

للوكيل الوسيط مهمتان يفرضهما Zitadel بدقة. يجب أن يستخدم HTTP/2 مع الواجهة الخلفية، لأن API تستخدم gRPC. ويجب أن يمرر Host دون تغيير، إلى جانب X-Forwarded-Proto: https. مع مكدس Compose هذا، يكون إعداد nginx على النحو التالي:

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

استبدل العناصر النائبة الخاصة بالواجهة الخلفية بعناوين يمكن لـnginx الوصول إليها. إذا كنت تقدّم Zitadel على منفذ غير 443، فاستخدم grpc_set_header Host $host:$server_port; لكي يُرسل المنفذ مع الترويسة. أما الباقي فهو مضيف افتراضي عادي، ويشرح إعداد reverse proxy في nginx سطراً بعد سطر الأجزاء الخاصة بـnginx وليست خاصة بـZitadel.

المسؤول الأول وفرض تغيير كلمة المرور

ينشئ التشغيل الأول مثيلاً واحداً، ومؤسسة واحدة، وحساب مسؤول بشري واحداً. يتكوّن اسم تسجيل الدخول من zitadel-admin@ ثم zitadel. ثم نطاقك الخارجي، ولذلك يكون مع ZITADEL_DOMAIN=auth.example.com كما يلي:

zitadel-admin@zitadel.auth.example.com

كلمة المرور هي Password1! ما لم تعيّن كلمة مرور خاصة بك. الإعداد الافتراضي المورّد من Zitadel يفرض تغيير كلمة المرور عند تسجيل الدخول الأول، لكن ملف Compose المورّد يتجاوز هذا الإعداد:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

هذا السطر مُضمَّن مباشرةً في docker-compose.yml ولا يُقرأ من .env، لذلك ضع قيمك الخاصة في تجاوز صغير تنشئه بنفسك. سمّه docker-compose.local.yml:

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

لا يحمّل Compose الملف docker-compose.override.yml تلقائياً إلا عند تشغيله من دون الخيار -f، بينما تمرّر كل الأوامر الواردة في دليل Zitadel الخيار -f، ما يعطّل هذا السلوك. بدلاً من تكرار قائمة متزايدة من الخيارات، ثبّت قائمة الملفات في .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

شغّله الآن:

docker compose pull
docker compose up -d --wait

يحتفظ --wait بالأمر قيد الانتظار حتى تجتاز فحوصات الصحة. عندما لا تصل حاوية API إلى هذه الحالة، يتوقف Compose مع dependency failed to start: container zitadel-zitadel-api-1 is unhealthy، ويحتوي docker compose logs zitadel-api على السبب. تُسمّى الحاوية باسم المشروع، ويحدّد ملف Compose المورّد ذلك بنفسه باستخدام name: zitadel على المستوى الأعلى، ولذلك لا يظهر اسم الدليل. في التشغيل الأول، يكون السبب عادةً طول masterkey أو DSN قاعدة البيانات.

سجّل الدخول إلى https://auth.example.com/ui/console، وغيّر كلمة المرور، ثم فعّل عاملاً ثانياً لهذا الحساب قبل أن تنشئ أي شيء آخر. تُطبَّق كل قيمة من ZITADEL_FIRSTINSTANCE_* فقط أثناء إنشاء المثيل الأول. بعد إنشاء المثيل، لا يؤدي تعديلها إلى أي تغيير.

لماذا لا يفعل طلب إعادة تعيين كلمة المرور شيئاً قبل عمل SMTP

يكون موفّر الهوية الذي لا يستطيع إرسال البريد معطلاً بطريقة قد تظل مخفية لأسابيع. يرسل Zitadel البريد الإلكتروني لدعوات المستخدمين، والتحقق من العناوين، وروابط إعادة تعيين كلمة المرور، والرموز المستخدمة مرة واحدة، وإشعارات المطالبة بالنطاق. عند عدم إعداد موفّر SMTP، تظل Console تعرض الإجراء على أنه اكتمل، وتنتقل الرسالة إلى معالجة الإشعارات من دون وجهة لإرسالها إليها. في v4.20.0، تستخدم الإشعارات الوضع القديم افتراضياً (LegacyEnabled: true)، الذي يتجاهل إعدادَي MaxAttempts: 3 وMaxTtl: 5m للعامل الموازي. لا تصف هذه القيم سلوك إعادة المحاولة الافتراضي للإشعارات. ولا يظهر أي شيء للشخص الذي ينتظر الرابط.

اضبطه في Console، ضمن إعدادات المثيل على https://auth.example.com/ui/console/settings. يطلب نموذج موفّر SMTP عنوان بريد المرسل، واسم المرسل، والمضيف والمنفذ، واسم المستخدم، وكلمة مرور SMTP، وخيار TLS. استخدم زر الاختبار في النموذج قبل الحفظ، لأنه يرسل رسالة فعلية: فإما أن تصل أو لا تصل. فعّل الموفّر لكي يستخدمه Zitadel لإرسال البريد.

توجد مجموعة مطابقة من متغيرات البيئة، وهي ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST وأخواتها. تُطبَّق هذه المتغيرات عند إنشاء المثيل. أما في مكدس قيد التشغيل بالفعل، فلا تأثير لها، ولذلك تكون Console هي المكان الصحيح للمثيل الموجود.

هناك نقطتان بشأن الإرسال من VPS، لأن الفشل يحدث عادةً هنا. تحقّق من سياسة SMTP الصادر لدى موفّرك قبل اختيار مرحّل: تحظر DigitalOcean المنافذ 25 و465 و587 في Droplets افتراضياً، ولذلك لا يُعد المنفذ 587 حلاً عاماً. استخدم مرحّلاً موثّقاً على منفذ يسمح به موفّرك. وانشر سجلات SPF (إطار سياسة المرسل) وDKIM (البريد المحدد بمفاتيح النطاق) لنطاق الإرسال، وإلا فقد تصل وصلة إعادة التعيين إلى البريد العشوائي، وهو ما يبدو للمستخدم تماماً كما لو أن الرسالة لم تُرسل قط.

في v4.20.0، ترفض اتصالات TLS الصادرة عبر SMTP سلاسل الشهادات التي تمر عبر سلطات التصديق الوسيطة المخترقة من eMudhra. يحتاج المرحّل المتأثر إلى شهادة بديلة.

تحقق من ذلك قبل دعوة أي شخص. أنشئ مستخدماً مؤقتاً، واطلب إعادة تعيين كلمة المرور، وراقب وصول الرسالة. إذا لم تصل، يحدّد docker compose logs -f zitadel-api فشل SMTP. تُخزَّن كلمة مرور SMTP مشفّرة في قاعدة البيانات، وهذا أمر إضافي يتولى masterkey حمايته نيابةً عنك.

انسخ Postgres وmasterkey احتياطياً وبشكل منفصل

كل ما يعرفه Zitadel موجود في PostgreSQL. ويفك masterkey تشفير هذه البيانات. خزّنهما في موقعين مختلفين.

ابدأ بإنشاء النسخة المفرغة:

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

الخيار -Fc هو التنسيق المخصص. يضغط البيانات أثناء الإخراج، ويمكن لـpg_restore قراءتها بشكل انتقائي. أما exec -T فيلغي استخدام الطرفية، وهذا مهم لأن الأمر سيعمل من cron دون طرفية متصلة.

بعد ذلك، ادفع هذا المجلد إلى موقع خارجي باستخدام restic، الذي يشفّر البيانات ويزيل التكرار:

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

يُشغَّل restic init مرة واحدة فقط، في اليوم الأول. ضع النسخة المفرغة والأمرين الأخيرين في /usr/local/bin/zitadel-backup.sh، وشغّلها كل ليلة:

0 3 * * * /usr/local/bin/zitadel-backup.sh

انسخ .env وكل ملفات compose التي تستخدمها احتياطياً داخل git. أما masterkey فهو الاستثناء من كل ذلك. خزّنه في مدير كلمات المرور وفي موقع ثانٍ لا يكون مستودع restic هذا، لأن الأرشيف الذي يحتوي على قاعدة البيانات ومفتاح فك تشفيرها معاً لا يعود نسخة احتياطية لنظام مشفّر.

النسخة الاحتياطية التي لم تستعدها ليست سوى تخمين. استعدها في قاعدة بيانات مؤقتة على الخادم نفسه وافحصها:

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

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

ترقية Zitadel دون فقدان المثيل

الترقية هي رفع رقم الإصدار في .env متبوعاً بأمرين:

docker compose pull
docker compose up -d --wait

افهم ما يفعله الأمر الثاني قبل تشغيله على خدمة يستخدمها أشخاص فعليون. أمر الحاوية هو start-from-init، الذي ينفذ مراحل التهيئة والإعداد قبل البدء في تقديم الخدمة، ومرحلة الإعداد هي عبارة عن ترحيلات قاعدة البيانات (database migrations). لذا، فإن رفع رقم الإصدار يؤدي إلى تشغيل ترحيلات المخطط على قاعدة بياناتك الحية عند بدء الحاوية، دون تدخل، بينما ينتظر --wait اكتمال فحص السلامة. هذا هو السبب الكامل لكون اختبار الاستعادة المذكور أعلاه ليس اختيارياً.

خذ نسخة احتياطية (dump) حديثة مباشرة قبل الترقية. النسخة الاحتياطية التي أخذتها الليلة الماضية شيء مختلف.

بالنسبة لـ v4.20.3، يجب إعادة تشغيل عمليات تسجيل الدخول الجارية عبر مزودي الهوية الخارجيين، وسيتم رفض رموز تفويض Login V1 غير المستخدمة لمرة واحدة. تحتاج واجهات تسجيل الدخول المخصصة إلى إذن session.link لإكمال طلبات OIDC أو SAML؛ امنح مستخدم الخدمة الخاص بها IAM_LOGIN_CLIENT قبل الترقية. يمتلك مستخدم خدمة Login V2 المرفق هذا الدور بالفعل. أصبحت فحوصات كلمة المرور في واجهة برمجة تطبيقات الجلسة تفرض سياسة تسجيل دخول المؤسسة الخاصة بالمستخدم، لذا يجب على المؤسسات التي تعطل تسجيل الدخول باسم المستخدم/كلمة المرور توجيه المستخدمين إلى مزود الهوية الخاص بهم.

لا تقفز بين الإصدارات الرئيسية. قبل الانتقال من v3 إلى v4، انتقل إلى v3.4.1 أو أحدث أولاً. يجعل v4 مفاتيح الويب OIDC إلزامية ويزيل مسار التوقيع القديم، لذا إذا لم يسبق لمثيل v3 الخاص بك تفعيل مفاتيح الويب، فلن تكون الرموز الموقعة بالمفاتيح القديمة قابلة للتحقق بعد الترقية. تشير الاستشارة التقنية A-10017 من Zitadel إلى أن رموز الوصول JWT ورموز الهوية الحالية قد تصبح غير صالحة فوراً وقد يضطر المستخدمون لتسجيل الدخول مرة أخرى. الحل هو الانتقال عبر v3.4.1 أو أحدث وترك الرموز والجلسات الموقعة بالطريقة القديمة تنتهي صلاحيتها قبل الترقية، أو قبول فترة إعادة تسجيل دخول مخططة. إذا كنت تشغل v3.4.1 أو أحدث بالفعل وانتظرت منذ تفعيل مفاتيح الويب، فتقول الاستشارة إنه لا يلزم اتخاذ أي إجراء.

راقب مرحلة الإعداد باستخدام docker compose logs -f zitadel-api. تستغرق الترحيلات في مخزن أحداث (eventstore) كبير دقائق، ولن يقوم Traefik بالتوجيه إلى واجهة برمجة التطبيقات حتى يجتاز فحص السلامة، لذا سيكون الموقع متوقفاً خلال تلك الفترة. خطط للأمر بدلاً من اكتشافه صدفة.

التراجع (rollback) ليس مجرد إعادة الوسم القديم. بمجرد تشغيل الترحيلات، لا يفهم الملف الثنائي القديم المخطط الذي يجده، لذا يعني التراجع استعادة النسخة الاحتياطية. بمجرد أن يحتوي المثيل على مستخدمين حقيقيين، انتقل إلى docker-compose.prodlike.yml، وهي الطبقة الإضافية التي تشغل التهيئة والإعداد كخطوات منفصلة عن البدء، بحيث تصبح الترحيلات عملية تقوم بتشغيلها ومراقبتها بدلاً من كونها أثراً جانبياً لإعادة تشغيل الحاوية.

ما الذي تشير إليه إلى مزود الهوية الجديد

في Console، أنشئ مشروعاً ثم أنشئ تطبيقاً داخله. اختر OIDC لأي تكامل حديث، وسيمنحك Zitadel معرّف عميل وسر عميل ووثيقة اكتشاف على https://auth.example.com/.well-known/openid-configuration. تطلب معظم البرامج ذاتية الاستضافة التي تدعم تسجيل الدخول الأحادي هذه القيم تحديداً.

لا يدعم كثير من البرامج ذلك، أو لا يدعمه إلا ضمن فئة مدفوعة. في الحالة الأولى، يحوّل oauth2-proxy أمام التطبيق أي خدمة HTTP إلى خدمة يمكن لـZitadel حمايتها. وفي الحالة الثانية، تجدر قراءة كلفة SSO في التطبيقات ذاتية الاستضافة قبل أن تخطط لعملية ترحيل تعتمد على ميزة لم تدفع مقابلها.

FAQ

ما مقدار RAM ووحدة المعالجة المركزية التي يحتاج إليها Zitadel المستضاف ذاتياً؟

يوضح دليل الإنتاج الخاص بـZitadel أن Zitadel نفسه يحتاج إلى نحو 0.5 GB من RAM، ويمكنه العمل بأقل من نواة CPU واحدة. ويوصي الدليل بإتاحة 4 أنوية لتجزئة كلمات المرور. تُحتسب متطلبات PostgreSQL بشكل منفصل، بمعدل نواة واحدة تقريباً لكل 100 طلب في الثانية، و4 GB من RAM لكل نواة. الأرقام الأكبر الواردة في الدليل مخصصة لكل عقدة في عنقود عالي التوافر مكوّن من ثلاث عقد: 4 أنوية و16 GB لكل عقدة، أو نحو 4 أنوية و8 GB من دون جمع السجلات والمقاييس. تتطلب بداية التشغيل السريعة باستخدام Compose ما لا يقل عن 2 GB، وهذا يكفي لتجربته لكنه لا يترك إلا مساحة محدودة لقاعدة البيانات التي ستحتاج إليها الخدمات الأخرى في النظام.

ماذا يحدث إذا فقدت masterkey الخاصة بـZitadel؟

يبقى كل ما شُفّر بها مشفّراً. لا يمكن فك تشفير بيانات اعتماد موفّري الهوية، وكلمة مرور SMTP، وبذور كلمات المرور لمرة واحدة، ولا يمكن تغيير المفتاح بعد ذلك. لا تكفي نسخة من قاعدة البيانات وحدها لاستعادة نسخة عاملة، لأن النسخة تحتوي على النص المشفّر ولا تحتوي على المفتاح. خزّن masterkey في مدير كلمات مرور، وفي مكان منفصل عن النسخة الاحتياطية التي تحتوي على تفريغ قاعدة البيانات. إذا فُقد الاثنان، فإن إعادة إنشاء النسخة من الصفر هي الخيار الوحيد المتبقي.

لماذا لا تصل رسائل إعادة تعيين كلمة مرور Zitadel مطلقاً؟

لأنه لم يتم إعداد موفّر SMTP، أو لأن الموفّر المُعدّ لا يستطيع التسليم. يستخدم Zitadel v4.20.0 معالجة الإشعارات القديمة افتراضياً، لذلك يتم تجاهل إعدادات العامل المتوازي الخاصة بثلاث محاولات وفاصل خمس دقائق. أعد إعداد موفّر SMTP ضمن إعدادات المثيل، واستخدم زر الاختبار في ذلك النموذج، فهو يرسل رسالة فعلية. فعّل الموفّر، واستخدم relay موثّقاً على منفذ يسمح به موفّر VPS، وانشر سجلات SPF وDKIM لنطاق الإرسال حتى لا تُصنّف الرسائل كبريد عشوائي.

هل يمكنني تغيير النطاق الخارجي لـZitadel بعد التثبيت؟

نعم، لكن ليس بتعديل .env وحده. غيّر ZITADEL_EXTERNALDOMAIN وZITADEL_EXTERNALPORT وZITADEL_EXTERNALSECURE، ثم اترك Zitadel يعيد تشغيل مرحلة الإعداد حتى يلتقط التغيير. تحتفظ التطبيقات التي سجّلتها سابقاً بعناوين URI القديمة لإعادة التوجيه، ويجب تحديثها يدوياً. كما سيُعاد Instance not found لأي طلب لا يتطابق رأس Host فيه مع نطاق يعرفه Zitadel. يؤدي اختيار الاسم النهائي قبل أول تشغيل إلى تجنّب كل ذلك.

هل كان هذا المقال مفيدًا؟