SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

نصب و اجرای Zitadel روی VPS با Docker

راهنمای self-host کردن Zitadel روی یک VPS با Docker؛ نیاز واقعی حدود 512 MB RAM است و تنظیم PostgreSQL، masterkey، TLS، SMTP، backup و اثر upgrade را توضیح می‌دهد.

پیش‌نیازهای میزبانی Zitadel روی یک VPS

برای میزبانی Zitadel روی یک VPS، به یک میزبان Docker، یک نام دامنه عمومی که به آن اشاره کند، PostgreSQL و منابع کافی CPU و RAM برای هر دو نیاز دارید. در راهنمای عملیاتی Zitadel، مصرف منابع خود برنامه حدود 512 مگابایت RAM و کمتر از یک هسته CPU برآورد شده است. دیتابیس و هش کردن رمز عبور بخش‌هایی هستند که با گذشت زمان رشد می‌کنند. Zitadel یک ارائه‌دهنده هویت (Identity Provider) است. این برنامه توکن‌ها را از طریق 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 نیاز دارد.

Zitadel به چه میزان VPS نیاز دارد؟

راهنمای شروع سریع (quickstart) در مستندات Zitadel، مقدار 2 GB رم را درخواست می‌کند. این عدد صرفاً برای شروع سریع است. راهنمای عملیاتی (production guide) 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 رم تخمین می‌زند و می‌گوید می‌تواند با کمتر از یک هسته CPU اجرا شود. هسته‌ها برای هش کردن رمز عبور هستند که به‌طور عمدی کند طراحی شده است، بنابراین هجوم ورود کاربران باعث جهش در مصرف CPU می‌شود و راهنما توصیه می‌کند 4 هسته CPU برای آن در دسترس باشد. PostgreSQL نیمه دیگر این هزینه است: همان راهنما حدود یک هسته به ازای هر 100 درخواست در ثانیه و 4 GB رم به ازای هر هسته را در نظر می‌گیرد.

دو ردیف بزرگ‌تر، اعداد مربوط به یک سرور واحد نیستند. برای یک پیکربندی حداقلی با قابلیت دسترسی بالا (high-availability)، راهنما یک کلاستر سه گره‌ای را توصیه می‌کند که هر کدام دارای 4 هسته و 16 GB رم هستند. همچنین ذکر می‌کند که اگر جمع‌آوری لاگ و متریک‌ها را حذف کنید، می‌توانید این مقادیر را به حدود 4 هسته و 8 GB رم به ازای هر گره کاهش دهید. هیچ اندازه‌ای برای یک گره واحد ذکر نشده است.

بنابراین، یک VPS با 2 GB رم این پشته (stack) را بالا می‌آورد، اما این مقدار بسیار کمتر از بودجه‌ای است که راهنما برای دیتابیس در زمان ورود ترافیک واقعی در نظر گرفته است. سرویس ورود (Login)، سرویسی است که سایر سرویس‌ها به آن وابسته‌اند. وقتی این سرویس از دسترس خارج شود، هیچ سرویس دیگری که به آن اعتماد دارد، به کسی اجازه ورود نمی‌دهد. تصمیم‌گیری در مورد اینکه بودجه دیتابیس و هشینگِ راهنما بیش از آن چیزی است که می‌خواهید برای احراز هویت هزینه کنید، یک تصمیم منطقی است و انجام این تصمیم در حال حاضر، بسیار ارزان‌تر از انجام آن پس از مهاجرت است. مقایسه 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 را اجرا نکنید. اولین اجرا، نمونه (instance) را ایجاد می‌کند و چندین تنظیم در ادامه وجود دارد که پس از آن بدون انجام کارهای اضافی قابل تغییر نیستند.

فایل .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 قرار می‌گیرد: نقاط پایانی لیست در APIهای 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 پیش‌فرض، Zitadel را با استفاده از کاربر superuser و رمز عبور postgres به PostgreSQL متصل می‌کند:

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

در مرحلهٔ ایمن‌سازی (hardening) یک تله وجود دارد. مستندات Zitadel به شما می‌گویند که POSTGRES_ZITADEL_PASSWORD را به .env اضافه کنید، اما docker-compose.yml پایه هرگز این متغیر را نمی‌خواند، بنابراین تنظیم آن هیچ تغییری ایجاد نمی‌کند. تغییر دادن POSTGRES_ADMIN_PASSWORD به تنهایی باعث قطع اتصال می‌شود، زیرا رمز عبور به‌صورت متنی (literal) درون رشتهٔ DSN (نام منبع داده) نیز نوشته شده است. DSN همان خطی است که نحوهٔ اتصال Zitadel را تعیین می‌کند.

توضیحات موجود در .env.example بقیهٔ ماجرا را به‌وضوح بیان می‌کنند: وقتی یک DSN پیکربندی می‌شود، Zitadel مستقیماً از همان کاربر استفاده می‌کند و یک کاربر با دسترسی محدود برای شما نمی‌سازد؛ بنابراین نقش (role) باید پیش از اولین اجرا وجود داشته باشد. یک رمز عبور برای این نقش تولید کنید، POSTGRES_ADMIN_PASSWORD را پیش از شروع Postgres در .env روی یک رمز عبور تصادفی مجزا تنظیم کنید، سپس 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 درون کانتینر و از طریق سوکت محلی آن اجرا می‌شوند که ایمیج رسمی Postgres به آن اعتماد دارد، بنابراین نیازی به وارد کردن رمز عبور نیست. مالکیت (Ownership) بخش مهم ماجراست. مرحلهٔ init در Zitadel، اسکیماهای مخصوص خود (eventstore، projections، system) و جداول را می‌سازد. مالکیت دیتابیس به این نقش، دسترسی CREATE لازم برای راه‌اندازی (bootstrap) آن اسکیماها را می‌دهد. تغییر 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 رمزنگاری‌نشده باقی می‌گذارد؛ پورت آن هرگز روی میزبان (host) منتشر نمی‌شود. راهنمای دیتابیس Zitadel برای اتصالات دیتابیس در محیط production، استفاده از TLS را توصیه می‌کند. پس از اولین اجرای کامل، بررسی کنید که آیا نقش واقعاً مالک داده‌های خود است یا خیر:

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

این دستور باید یک اسکیمای eventstore، یک اسکیمای projections و یک اسکیمای system را فهرست کند. اگر این اسکیماها وجود ندارند، مرحلهٔ init به آنجا نرسیده است و لاگ کانتینر API دلیل آن را مشخص خواهد کرد.

کلید اصلی (masterkey) و هزینهٔ از دست دادن آن

Zitadel پیش از ذخیره‌سازی اسرار، آن‌ها را رمزنگاری می‌کند: اعتبارنامه‌های identity provider، رمز عبور SMTP، سیدهای one-time-password و کلیدهای ماشین. کلید اصلی (masterkey) قفل تمام این موارد را باز می‌کند. طول این کلید دقیقاً 32 بایت است و مستندات به‌صراحت دربارهٔ پیامد آن هشدار می‌دهند: این کلید قابل تغییر نیست و در صورت تغییر، دسترسی به داده‌های رمزنگاری‌شده از بین می‌رود.

یک کلید تولید کنید و آن را جایگزین خط جای‌گذار در .env کنید:

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

به‌جای افزودن یک خط دوم، خط ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters را ویرایش کنید. ابزار Compose آخرین تعریف از یک کلید تکراری را در نظر می‌گیرد، بنابراین افزودن خط جدید کار می‌کند، اما فایلی که شامل دو خط masterkey باشد، برای نفر بعدی که آن را می‌خواند، یک تله محسوب می‌شود.

اکنون به محل نگهداری این کلید فکر کنید. فایل compose کانتینر API را به این صورت اجرا می‌کند:

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

بنابراین masterkey روی خط فرمان کانتینر قرار می‌گیرد، جایی که docker inspect آن را به هر کسی که به Docker socket دسترسی داشته باشد، نشان می‌دهد. در یک VPS با یک مدیر واحد، این یک معاملهٔ قابل‌قبول است و حالت (mode) در .env همان چیزی است که از آن روی دیسک محافظت می‌کند. اگر این روش قابل‌قبول نیست، کلید را به‌عنوان یک فایل mount کنید و به‌جای آن از --masterkeyFile /run/secrets/zitadel-masterkey استفاده کنید که مقدار را از آرگومان‌های پردازش دور نگه می‌دارد.

پیش از اولین اجرا، masterkey را در مدیریت رمز عبور (password manager) خود کپی کنید. این کلید در dump پایگاه داده ظاهر نمی‌شود، بنابراین اگر dump را تحت یک masterkey متفاوت بازیابی کنید، نمونه‌ای ایجاد می‌شود که قادر به خواندن اسرار خود نیست. آن را در جایی غیر از آرشیوی که dump را نگه می‌دارد ذخیره کنید تا یک نسخهٔ پشتیبان سرقت‌شده، هم شامل داده‌های رمزنگاری‌شده و هم کلید دسترسی به آن‌ها نباشد.

تنظیم دامنه خارجی پیش از اولین اجرا

ZITADEL_DOMAIN در .env مقدار ZITADEL_EXTERNALDOMAIN را در کانتینر تغذیه می‌کند و این همان نامی است که کاربران شما تایپ می‌کنند. Zitadel از این مقدار برای تعیین issuer در OIDC، آدرس پایه رابط کاربری ورود، endpointهای SAML و نام کاربری اولین مدیر سیستم استفاده می‌کند؛ بنابراین این یک تنظیم ظاهری نیست.

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

Zitadel تشخیص می‌دهد که شما با کدام instance در حال تعامل هستید، زیرا از هدر Host استفاده می‌کند. اگر این هدر با دامنه‌ای که Zitadel می‌شناسد مطابقت نداشته باشد، تمام درخواست‌ها پاسخ یکسانی دریافت می‌کنند:

ID=QUERY-1kIjX Message=Instance not found

هنگامی که این خطا را مشاهده کردید، دو مورد را بررسی کنید. یا ZITADEL_DOMAIN نامی نیست که در مرورگر وارد کرده‌اید، یا یک پروکسی در لایه جلوتر، مقدار Host را به آدرس upstream بازنویسی می‌کند. وارد کردن آدرس IP سرور در مرورگر به جای نام دامنه نیز باعث بروز همین خطا می‌شود.

شما می‌توانید این مقادیر را بعداً تغییر دهید. Zitadel برای اعمال تغییرات باید مرحله setup خود را دوباره اجرا کند و تمام برنامه‌هایی که قبلاً ثبت کرده‌اید، همچنان URIهای تغییر مسیر (redirect URI) قدیمی خود را حفظ خواهند کرد. انتخاب نام نهایی در همین مرحله، بسیار کم‌هزینه‌تر از تغییر آن در آینده است.

پایان‌دهی TLS با استفاده از overlay مربوط به Let's Encrypt

برای یک دامنه عمومی، overlay مربوط به 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

این overlay همچنین ZITADEL_EXTERNALPORT: 443 و ZITADEL_EXTERNALSECURE: true را روی کانتینر API تنظیم می‌کند؛ به همین دلیل است که URL عمومی و URLهایی که Zitadel برای خود می‌سازد، با هم مطابقت دارند. رکورد A باید پیش از شروع کار resolve شود، زیرا چالش HTTP بدون آن با شکست مواجه می‌شود.

اگر در حال حاضر TLS را روی nginx یا یک load balancer پایان می‌دهید، از docker-compose.mode-external-tls.yml استفاده کنید و TRAEFIK_TRUSTED_IPS را روی محدوده‌هایی تنظیم کنید که پروکسی شما از آن‌ها ارسال می‌کند. Traefik فقط هدرهای X-Forwarded-* را از آدرس‌های موجود در آن لیست می‌پذیرد. این overlay به‌طور صریح URL خارجی و URLهای ورود به سیستم Zitadel را روی HTTPS تنظیم می‌کند.

یک پروکسی بالادستی (upstream) دو وظیفه دارد که Zitadel در مورد آن‌ها سخت‌گیر است. پروکسی باید با backend به صورت HTTP/2 صحبت کند، زیرا API از نوع gRPC است. همچنین باید Host را به همراه X-Forwarded-Proto: https بدون تغییر عبور دهد. با این stack در 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;
    }
}

جای‌نگهدار‌های (placeholders) بالادستی را با آدرس‌هایی که nginx به آن‌ها دسترسی دارد جایگزین کنید. اگر Zitadel را روی پورتی غیر از 443 ارائه می‌دهید، از grpc_set_header Host $host:$server_port; استفاده کنید تا شماره پورت همراه با هدر منتقل شود. باقی موارد یک virtual host معمولی است و بررسی خط‌به‌خط پیکربندی reverse proxy در nginx بخش‌هایی را که مختص Zitadel نیستند، پوشش می‌دهد.

نخستین مدیر و اجباری‌کردن تغییر گذرواژه

نخستین راه‌اندازی، یک instance، یک organisation و یک مدیر انسانی ایجاد می‌کند. نام ورود برابر است با zitadel-admin@ به‌اضافه zitadel. و دامنهٔ خارجی شما؛ بنابراین، با ZITADEL_DOMAIN=auth.example.com به این صورت خواهد بود:

zitadel-admin@zitadel.auth.example.com

گذرواژه Password1! است، مگر آن‌که گذرواژهٔ دلخواه خود را تنظیم کرده باشید. مقدار پیش‌فرض upstream در Zitadel، اجبار به تغییر گذرواژه در نخستین ورود است، اما فایل compose ارائه‌شده این مقدار پیش‌فرض را بازنویسی می‌کند:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

این خط در docker-compose.yml به‌صورت hardcode قرار دارد و از .env خوانده نمی‌شود؛ بنابراین مقادیر دلخواه خود را در یک overlay کوچک و اختصاصی قرار دهید. نام آن را 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 را به‌طور خودکار بارگذاری می‌کند که آن را بدون flag به نام -f اجرا کنید؛ اما تمام فرمان‌های راهنمای Zitadel، -f را ارسال می‌کنند و این رفتار را غیرفعال می‌سازند. به‌جای تکرار فهرست رو‌به‌رشد flagها، فهرست فایل‌ها را در .env ثابت کنید:

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

اکنون آن را راه‌اندازی کنید:

docker compose pull
docker compose up -d --wait

--wait فرمان را تا زمانی نگه می‌دارد که healthcheckها موفق شوند. اگر container مربوط به API هرگز به این مرحله نرسد، Compose با dependency failed to start: container zitadel-zitadel-api-1 is unhealthy متوقف می‌شود و docker compose logs zitadel-api علت را نشان می‌دهد. نام container بر اساس پروژه تعیین می‌شود و فایل compose ارائه‌شده این مقدار را با name: zitadel در سطح بالا خودش تنظیم می‌کند؛ بنابراین نام directory در آن ظاهر نمی‌شود. در نخستین راه‌اندازی، علت معمولاً طول masterkey یا DSN پایگاه داده است.

در https://auth.example.com/ui/console وارد شوید، گذرواژه را تغییر دهید و سپس پیش از ایجاد هر مورد دیگری، یک عامل دوم را برای آن حساب فعال کنید. هر مقدار ZITADEL_FIRSTINSTANCE_* فقط هنگام ایجاد نخستین instance اعمال می‌شود. پس از ایجاد instance، ویرایش آن‌ها هیچ اثری ندارد.

چرا بازنشانی رمز عبور تا زمانی که SMTP کار نکند، بی‌اثر است

یک ارائه‌دهنده هویت (Identity Provider) که قادر به ارسال ایمیل نیست، دچار نقصی است که ممکن است هفته‌ها پنهان بماند. Zitadel برای دعوت از کاربران، تأیید آدرس، لینک‌های بازنشانی رمز عبور، کدهای یک‌بارمصرف و اعلان‌های ادعای دامنه، ایمیل ارسال می‌کند. بدون پیکربندی یک ارائه‌دهنده SMTP، کنسول همچنان عملیات را به‌عنوان «انجام‌شده» گزارش می‌دهد، اما پیام به بخش پردازش اعلان‌ها می‌رود و جایی برای ارسال آن وجود ندارد. در نسخه 4.20.0، اعلان‌ها به‌صورت پیش‌فرض از حالت legacy استفاده می‌کنند (LegacyEnabled: true) که تنظیمات MaxAttempts: 3 و MaxTtl: 5m مربوط به worker موازی را نادیده می‌گیرد. این مقادیر رفتار پیش‌فرض بازتلاش (retry) اعلان‌ها را توصیف نمی‌کنند. هیچ پیامی به کاربری که منتظر لینک است، ارسال نمی‌شود.

آن را در کنسول، در بخش تنظیمات instance در https://auth.example.com/ui/console/settings پیکربندی کنید. فرم ارائه‌دهنده SMTP از شما آدرس ایمیل فرستنده، نام فرستنده، host و port، نام کاربری، رمز عبور SMTP و گزینه فعال‌سازی TLS را می‌خواهد. پیش از ذخیره، از دکمه تست در همان فرم استفاده کنید، زیرا یک پیام واقعی ارسال می‌کند: یا پیام می‌رسد یا نمی‌رسد. ارائه‌دهنده را فعال کنید تا Zitadel از آن برای ارسال ایمیل استفاده کند.

مجموعه‌ای از متغیرهای محیطی متناظر، یعنی ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST و موارد مشابه آن وجود دارند. این متغیرها هنگام ایجاد یک instance اعمال می‌شوند. در پشته‌ای (stack) که از قبل در حال اجراست، این متغیرها تأثیری ندارند، بنابراین کنسول بهترین مکان برای پیکربندی یک instance موجود است.

دو نکته درباره ارسال ایمیل از یک VPS وجود دارد، زیرا معمولاً مشکل از همین‌جا ناشی می‌شود. پیش از انتخاب یک relay، سیاست خروجی SMTP ارائه‌دهنده خود را بررسی کنید: DigitalOcean به‌صورت پیش‌فرض پورت‌های 25، 465 و 587 را روی Dropletها مسدود می‌کند، بنابراین پورت 587 یک راهکار همگانی نیست. از یک relay احراز هویت‌شده روی پورتی استفاده کنید که ارائه‌دهنده شما اجازه می‌دهد. همچنین رکوردهای SPF (چارچوب سیاست فرستنده) و DKIM (ایمیل شناسایی‌شده با کلید دامنه) را برای دامنه فرستنده منتشر کنید، در غیر این صورت لینک بازنشانی به پوشه اسپم می‌رود که برای کاربر دقیقاً به معنای ارسال نشدن ایمیل است.

در نسخه 4.20.0، اتصالات خروجی SMTP TLS زنجیره‌های گواهی صادرشده توسط CAهای میانی eMudhra که دچار نقض امنیتی شده‌اند را رد می‌کنند. یک relay تحت تأثیر باید گواهی خود را جایگزین کند.

پیش از دعوت هر کسی، آن را تست کنید. یک کاربر موقت بسازید، درخواست بازنشانی رمز عبور بدهید و رسیدن پیام را بررسی کنید. اگر پیام نرسید، docker compose logs -f zitadel-api علت شکست SMTP را مشخص می‌کند. رمز عبور SMTP به‌صورت رمزنگاری‌شده در دیتابیس ذخیره می‌شود، که این یکی دیگر از مواردی است که masterkey از آن محافظت می‌کند.

پشتیبان‌گیری جداگانه از Postgres و masterkey

هر آنچه Zitadel می‌داند در PostgreSQL ذخیره شده است. ابزاری که این داده‌ها را رمزگشایی می‌کند، masterkey است. از این دو در دو مکان متفاوت پشتیبان تهیه کنید.

ابتدا dump را بگیرید:

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 به خارج از سایت منتقل کنید، که داده‌ها را رمزنگاری و deduplicate می‌کند:

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 فقط یک‌بار و در روز اول اجرا می‌شود. dump و دو دستور آخر را در /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 به این معنی است که dump واقعی است. خطایی مبنی بر عدم وجود طرحواره به این معنی است که dump معتبر نیست، و شما این موضوع را در روزی متوجه شده‌اید که هزینه‌ای برایتان ندارد. الگوی کلی برای پشتیبان‌گیری و ارتقای یک استک Compose تقریباً بدون تغییر در اینجا صدق می‌کند و نگهداری masterkey خارج از همان آرشیو، تنها بخش اختصاصی مربوط به Zitadel است.

ارتقای Zitadel بدون از دست دادن نمونه

ارتقا شامل تغییر نسخه در .env و سپس اجرای دو دستور است:

docker compose pull
docker compose up -d --wait

پیش از اجرای دستور دوم روی سرویسی که کاربران به آن وارد می‌شوند، عملکرد آن را درک کنید. دستور کانتینر start-from-init است که مراحل init و setup را پیش از شروع سرویس‌دهی اجرا می‌کند و مرحله setup همان مهاجرت‌های دیتابیس است. بنابراین تغییر نسخه باعث اجرای مهاجرت‌های طرح‌واره (schema migrations) روی دیتابیس زنده شما در هنگام شروع کانتینر می‌شود، بدون نظارت، در حالی که --wait منتظر بررسی سلامت (healthcheck) می‌ماند. به همین دلیل است که تست بازیابی (restore test) در بالا اختیاری نیست.

بلافاصله پیش از ارتقا، یک dump تازه بگیرید. dump دیشب موضوع متفاوتی است.

برای v4.20.3، ورودهای در حال انجام از طریق ارائه‌دهنده هویت خارجی باید دوباره شروع شوند و کدهای تایید نشده Login V1 برای یک بار رد می‌شوند. رابط‌های کاربری ورود سفارشی برای تکمیل درخواست‌های OIDC یا SAML به مجوز session.link نیاز دارند؛ پیش از ارتقا، این نقش را به کاربر سرویس آن‌ها (service user) اختصاص دهید، برای مثال با استفاده از IAM_LOGIN_CLIENT. کاربر سرویس Login V2 که به‌صورت پیش‌فرض ارائه شده، از قبل این نقش را دارد. بررسی رمز عبور در Session API اکنون سیاست ورود سازمان کاربر را اعمال می‌کند، بنابراین سازمان‌هایی که ورود با نام کاربری/رمز عبور را غیرفعال کرده‌اند، باید کاربران را به ارائه‌دهنده هویت خود هدایت کنند.

از یک نسخه اصلی (major version) نپرید. پیش از انتقال از v3 به v4، ابتدا به v3.4.1 یا جدیدتر بروید. نسخه v4 استفاده از کلیدهای وب OIDC را اجباری کرده و مسیر امضای قدیمی را حذف می‌کند، بنابراین اگر نمونه v3 شما هرگز کلیدهای وب را فعال نکرده باشد، توکن‌های امضا شده با کلیدهای قدیمی پس از ارتقا دیگر قابل تایید نخواهند بود. توصیه فنی A-10017 Zitadel می‌گوید که توکن‌های دسترسی JWT و توکن‌های ID موجود ممکن است بلافاصله نامعتبر شوند و کاربران مجبور به ورود مجدد شوند. راه حل آن، عبور از نسخه v3.4.1 یا جدیدتر و اجازه دادن به توکن‌ها و نشست‌های قدیمی برای انقضا پیش از ارتقا، یا پذیرش یک بازه زمانی برای ورود مجدد برنامه‌ریزی‌شده است. اگر از قبل v3.4.1 یا جدیدتر را اجرا می‌کنید و از زمان فعال‌سازی کلیدهای وب صبر کرده‌اید، طبق توصیه فنی نیازی به اقدام خاصی نیست.

مرحله setup را با docker compose logs -f zitadel-api زیر نظر بگیرید. مهاجرت‌ها در یک eventstore بزرگ دقایقی طول می‌کشد و Traefik تا زمانی که بررسی سلامت تایید نشود، ترافیک را به API هدایت نمی‌کند، بنابراین سایت در آن بازه زمانی از دسترس خارج می‌شود. این کار را برنامه‌ریزی کنید تا غافلگیر نشوید.

بازگشت به نسخه قبل (Rollback) صرفاً با بازگرداندن تگ قدیمی انجام نمی‌شود. هنگامی که مهاجرت‌ها اجرا شدند، باینری قدیمی طرح‌واره‌ای را که پیدا می‌کند نمی‌شناسد، بنابراین بازگشت به نسخه قبل به معنای بازیابی dump است. هنگامی که نمونه شما دارای کاربران واقعی است، به سراغ docker-compose.prodlike.yml بروید؛ این لایه، مراحل init و setup را به عنوان گام‌های جدا از شروع اجرا می‌کند، بنابراین مهاجرت چیزی است که شما آن را فعال و نظارت می‌کنید، نه یک اثر جانبی از راه‌اندازی مجدد کانتینر.

چه چیزی را باید به ارائه‌دهنده هویت جدید خود معرفی کنید

در Console، یک پروژه ایجاد کنید و سپس یک application درون آن بسازید. برای هر سرویس مدرنی گزینه OIDC را انتخاب کنید؛ Zitadel به شما یک client ID، یک client secret و یک discovery document در https://auth.example.com/.well-known/openid-configuration ارائه می‌دهد. اکثر نرم‌افزارهای self-hosted که از single sign-on پشتیبانی می‌کنند، دقیقاً به همین موارد نیاز دارند.

بسیاری از نرم‌افزارها از این قابلیت پشتیبانی نمی‌کنند یا آن را فقط در نسخه پولی ارائه می‌دهند. برای حالت اول، استفاده از oauth2-proxy در مقابل برنامه هر سرویس HTTP را به چیزی تبدیل می‌کند که Zitadel می‌تواند از آن محافظت کند. برای حالت دوم، خواندن مطلب هزینه SSO در برنامه‌های self-hosted پیش از آنکه مهاجرت خود را حول قابلیتی که برای آن پولی پرداخت نکرده‌اید برنامه‌ریزی کنید، ارزشمند است.

FAQ

Zitadel خودمیزبان به چه مقدار RAM و CPU نیاز دارد؟

راهنمای تولید Zitadel بیان می‌کند که خود Zitadel به حدود 0.5 گیگابایت RAM نیاز دارد و می‌تواند با کمتر از یک هسته CPU اجرا شود، اما برای هش کردن رمز عبور، داشتن 4 هسته توصیه می‌شود. منابع PostgreSQL به‌صورت جداگانه محاسبه می‌شود؛ تقریباً یک هسته برای هر 100 درخواست در ثانیه و 4 گیگابایت RAM به ازای هر هسته. ارقام بزرگ‌تر در راهنما مربوط به هر گره در یک کلاستر با دسترس‌پذیری بالا (High-Availability) با سه گره است: 4 هسته و 16 گیگابایت برای هر گره، یا حدود 4 هسته و 8 گیگابایت بدون در نظر گرفتن جمع‌آوری لاگ و متریک‌ها. نسخه سریع Docker Compose حداقل 2 گیگابایت RAM درخواست می‌کند که برای تست کافی است، اما فضای کمی برای پایگاه‌داده‌ای که سایر سرویس‌های سیستم به آن وابسته‌اند، باقی می‌گذارد.

اگر کلید اصلی (masterkey) Zitadel را گم کنم چه می‌شود؟

هر چیزی که با آن رمزنگاری شده است، رمزنگاری‌شده باقی می‌ماند. اعتبارنامه‌های ارائه‌دهنده هویت (Identity Provider)، رمز عبور SMTP و بذرهای رمز یک‌بارمصرف (OTP) قابل رمزگشایی نیستند و کلید نیز پس از آنکه موضوعیت پیدا کرد، قابل تغییر نیست. یک فایل dump از پایگاه‌داده به‌تنهایی برای بازیابی یک نمونه فعال کافی نیست، زیرا dump حاوی متن رمزنگاری‌شده است و کلیدی در آن وجود ندارد. کلید اصلی را در یک مدیریت‌کننده رمز عبور و در مکانی جدا از نسخه پشتیبانی که حاوی dump است، نگهداری کنید. اگر هر دو از بین بروند، تنها راه باقی‌مانده، بازسازی نمونه از صفر است.

چرا ایمیل‌های بازنشانی رمز عبور Zitadel هرگز نمی‌رسند؟

زیرا هیچ ارائه‌دهنده SMTP پیکربندی نشده است یا ارائه‌دهنده پیکربندی‌شده قادر به ارسال نیست. Zitadel نسخه 4.20.0 به‌صورت پیش‌فرض از پردازش اعلان‌های قدیمی (legacy) استفاده می‌کند، بنابراین تنظیمات سه تلاش و پنج دقیقه برای worker موازی نادیده گرفته می‌شوند. ارائه‌دهنده SMTP را در تنظیمات نمونه (instance settings) پیکربندی کنید و از دکمه تست در همان فرم استفاده کنید که یک پیام واقعی ارسال می‌کند. ارائه‌دهنده را فعال کنید، از یک relay احراز هویت‌شده روی پورتی که ارائه‌دهنده VPS شما مجاز می‌داند استفاده کنید و رکوردهای SPF و DKIM را برای دامنه فرستنده منتشر کنید تا ایمیل به‌عنوان اسپم فیلتر نشود.

آیا می‌توانم دامنه خارجی Zitadel را پس از نصب تغییر دهم؟

بله، اما نه فقط با ویرایش .env. مقادیر ZITADEL_EXTERNALDOMAIN، ZITADEL_EXTERNALPORT و ZITADEL_EXTERNALSECURE را تغییر دهید و سپس اجازه دهید Zitadel مرحله راه‌اندازی (setup) خود را دوباره اجرا کند تا تغییرات را اعمال کند. برنامه‌هایی که قبلاً ثبت کرده‌اید، URIهای تغییر مسیر (redirect URI) قدیمی خود را حفظ می‌کنند و باید به‌صورت دستی به‌روزرسانی شوند؛ همچنین هر درخواستی که هدر Host آن با دامنه‌ای که Zitadel می‌شناسد مطابقت نداشته باشد، پاسخ Instance not found دریافت می‌کند. انتخاب نام نهایی پیش از اولین اجرا، از تمام این موارد جلوگیری می‌کند.

آیا این مقاله مفید بود؟