SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

Как разместить Zitadel на VPS с Docker

Zitadel требует около 512 MB RAM. Настройте PostgreSQL, masterkey, TLS, SMTP и резервное копирование на одном VPS, включая нюансы обновления базы данных.

Что нужно для самостоятельного размещения Zitadel на VPS

Для самостоятельного размещения Zitadel на VPS вам потребуются хост с Docker, указывающее на него публичное DNS-имя, PostgreSQL, а также достаточный объем CPU и RAM для обоих компонентов. Согласно руководству по эксплуатации Zitadel, самому приложению требуется около 512 MB RAM и менее одного ядра CPU. Потребление ресурсов растёт за счёт базы данных и хеширования паролей. Zitadel — это провайдер идентификации. Он выпускает токены по протоколам OIDC (OpenID Connect) и SAML (Security Assertion Markup Language), чтобы другие ваши сервисы не хранили собственные списки пользователей. Установка состоит из curl и docker compose up. Критически важные компоненты, от которых зависит работоспособность системы: мастер-ключ, пользователь базы данных, SMTP (Simple Mail Transfer Protocol), резервная копия и первое обновление.

Всё, что описано ниже, предполагает использование Ubuntu 24.04, Docker Engine 24 или новее с плагином Compose версии 2.24.4 или новее, а также наличие доменного имени, например auth.example.com, которое уже разрешается в IP-адрес сервера. Оверлеи TLS используют !override, что требует указанной версии Compose.

Сколько ресурсов VPS требуется Zitadel?

В quickstart на базе Compose в документации Zitadel требуется 2 GB RAM. Это значение относится к quickstart. В руководстве по эксплуатации Zitadel в production указаны другие значения.

График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 core. CPU cores нужны для хеширования паролей. Эта операция намеренно выполняется медленно, поэтому всплеск входов в систему вызывает скачок нагрузки на CPU. Для Zitadel руководство рекомендует держать доступными 4 CPU cores. PostgreSQL составляет вторую часть требований: в том же руководстве заложен примерно один core на 100 запросов в секунду и 4 GB RAM на core.

Две нижние строки не относятся к одному серверу. Для минимальной конфигурации высокой доступности руководство рекомендует cluster из three nodes, каждый с 4 cores и 16 GB RAM. Если не собирать логи и метрики, эти значения можно уменьшить примерно до 4 cores и 8 GB RAM на node. Требования для single node не указаны.

Таким образом, на VPS с 2 GB RAM этот stack запустится, но при появлении реального трафика его ресурсов будет значительно меньше, чем требуется руководству только для базы данных. Сервис входа в систему нужен всем остальным сервисам. Если он недоступен, ни один сервис, который ему доверяет, не впустит пользователей. Если вы решите, что заложенные в руководстве ресурсы для базы данных и хеширования слишком велики для аутентификации, это обоснованное решение. Принять его сейчас намного дешевле, чем после миграции. В сравнении Keycloak, Authentik и Zitadel рассмотрены затраты каждого решения по памяти и операционной работе, а self-hosted сервер 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 (Transport Layer Security). 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 года, является первым, который подпадает под техническое уведомление Zitadel A-10018: затронутые эндпоинты списков в 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. Интерфейс входа использует его для подписи сессионных cookie, и в примечаниях к релизу v4.19.5 содержится явное предупреждение о недопустимости использования примера значения.

Назначьте Postgres отдельного пользователя и задайте надёжный пароль

Поставляемый .env подключает Zitadel к PostgreSQL от имени суперпользователя с паролем 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 напрямую использует указанного в нём пользователя и не создаёт непривилегированного пользователя автоматически. Поэтому роль должна существовать до первого запуска. Сгенерируйте пароль для роли, задайте в .env отдельный случайный пароль для POSTGRES_ADMIN_PASSWORD до запуска 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 выполняются внутри контейнера через его локальный сокет. Официальный образ Postgres доверяет таким подключениям, поэтому пароль не запрашивается. Важна именно принадлежность объектов. На этапе инициализации Zitadel создаёт собственные схемы (eventstore, projections, system) и таблицы. Владение базой данных даёт роли право CREATE, необходимое для создания этих схем. Изменение прав CREATE на схему public в PostgreSQL 15 относится к отдельной проблеме и не означает, что инициализация схем 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 по работе с базой данных для production-подключений рекомендуется TLS. После первого полного запуска проверьте, что роль действительно владеет своими данными:

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

В выводе должны присутствовать схема eventstore, схема projections и схема system. Если этих схем нет, этап инициализации не дошёл до этого места. Причину покажет журнал контейнера API.

Мастер-ключ и последствия его утраты

Zitadel шифрует секреты перед сохранением: учётные данные провайдера идентификации, пароль SMTP, seed-значения для одноразовых паролей и машинные ключи. Мастер-ключ открывает доступ ко всем этим данным. Его длина составляет ровно 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}"

Поэтому мастер-ключ находится в командной строке контейнера. docker inspect показывает его всем, кто может получить доступ к Docker socket. На VPS с одним администратором это допустимый компромисс. Права доступа в .env защищают ключ на диске. Если такой вариант неприемлем, подключите ключ как файл и используйте --masterkeyFile /run/secrets/zitadel-masterkey. Это исключает значение из аргументов процесса.

Скопируйте мастер-ключ в менеджер паролей до первого запуска. В дампе базы данных он не сохраняется. Поэтому дамп, восстановленный с другим мастер-ключом, создаёт экземпляр, который не может прочитать собственные секреты. Храните ключ отдельно от архива с дампом. Тогда одна украденная резервная копия не будет содержать одновременно зашифрованные данные и ключ для их расшифровки.

Укажите внешний домен до первого запуска

ZITADEL_DOMAIN в .env передаёт ZITADEL_EXTERNALDOMAIN в контейнер, и это имя вводят пользователи. Zitadel использует его для формирования issuer OIDC, базового URI интерфейса входа, конечных точек SAML и имени входа первого администратора. Это не формальный параметр.

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

Zitadel определяет, с каким экземпляром вы работаете, по заголовку Host. Если этот заголовок не соответствует известному домену, каждый запрос получает один и тот же ответ:

ID=QUERY-1kIjX Message=Instance not found

При появлении этой ошибки проверьте два момента. Возможно, ZITADEL_DOMAIN не совпадает с именем, по которому вы открываете сайт. Либо прокси перед Zitadel изменяет Host на адрес upstream. Та же ошибка возникает, если открыть сервер по IP-адресу вместо имени.

Позже эти значения можно изменить. Чтобы применить изменение, Zitadel должен повторно выполнить этап настройки. Все уже зарегистрированные приложения сохранят старые redirect URI. Указать окончательное имя сейчас значительно проще, чем менять его позже.

Завершение TLS с помощью overlay для Let's Encrypt

Для публичного домена добавьте overlay Let's Encrypt для Zitadel. Он переключает Traefik на HTTP challenge 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-запись должна разрешаться до запуска. Без неё HTTP challenge завершается ошибкой.

Если TLS уже завершается в nginx или на load balancer, используйте docker-compose.mode-external-tls.yml и задайте в TRAEFIK_TRUSTED_IPS диапазоны адресов, с которых ваш proxy отправляет запросы. Traefik учитывает заголовки X-Forwarded-* только от адресов из этого списка. Overlay явно задаёт внешний URL Zitadel и URL входа по HTTPS.

Upstream proxy должен выполнять две задачи, к которым Zitadel предъявляет строгие требования. Он должен использовать HTTP/2 при подключении к backend, поскольку API работает по gRPC. Кроме того, он должен передавать Host без изменений вместе с X-Forwarded-Proto: https. В этом Compose stack конфигурация 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 upstream на адреса, доступные nginx. Если Zitadel обслуживается на порту, отличном от 443, используйте grpc_set_header Host $host:$server_port;, чтобы порт передавался вместе с заголовком. Остальная конфигурация представляет собой обычный virtual host. В статье конфигурация reverse proxy для 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. Поэтому укажите собственные значения в небольшом отдельном 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 только при запуске без флага -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 удерживает команду до успешного прохождения healthcheck. Если контейнер 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

Identity provider, который не может отправлять почту, может неделями оставаться неисправным незаметно. Zitadel отправляет письма с приглашениями пользователей, ссылками для подтверждения адреса, ссылками для сброса пароля, одноразовыми кодами и уведомлениями о подтверждении домена. Если SMTP-провайдер не настроен, Console всё равно сообщает, что действие выполнено, а сообщение попадает в обработку уведомлений, но отправлять его некуда. В v4.20.0 уведомления по умолчанию используют legacy mode (LegacyEnabled: true), который игнорирует параметры MaxAttempts: 3 и MaxTtl: 5m параллельного worker. Эти значения не описывают поведение повторных попыток отправки уведомлений по умолчанию. Пользователь, ожидающий ссылку, не получает никакого уведомления.

Настройте SMTP в Console в параметрах instance по адресу https://auth.example.com/ui/console/settings. Форма SMTP provider запрашивает адрес отправителя, имя отправителя, host и port, имя пользователя, SMTP password и переключатель TLS. Перед сохранением используйте кнопку тестирования в этой форме: она отправляет реальное сообщение. Оно либо поступит, либо нет. Активируйте provider, чтобы Zitadel использовал его для отправки почты.

Также есть соответствующий набор переменных окружения, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST и связанные с ней переменные. Они применяются при создании instance. В уже работающем stack они не влияют на конфигурацию, поэтому для существующего instance используйте Console.

При отправке почты с VPS нужно учитывать два момента, поскольку именно здесь чаще всего возникают ошибки. Перед выбором relay проверьте политику провайдера в отношении исходящего SMTP-трафика: DigitalOcean по умолчанию блокирует порты 25, 465 и 587 на Droplet, поэтому порт 587 не является универсальным решением. Используйте relay с аутентификацией на порту, который разрешён вашим провайдером. Опубликуйте записи SPF (sender policy framework) и DKIM (domainkeys identified mail) для домена отправителя. Иначе ссылка для сброса пароля попадёт в спам, что для пользователя выглядит точно так же, как если бы письмо вообще не было отправлено.

В v4.20.0 исходящие SMTP TLS-соединения отклоняют цепочки сертификатов через скомпрометированные промежуточные CA eMudhra. Для затронутого relay требуется заменить сертификат.

Проверьте отправку до того, как приглашать пользователей. Создайте временного пользователя, запросите сброс пароля и убедитесь, что сообщение поступило. Если оно не поступило, docker compose logs -f zitadel-api указывает причину ошибки SMTP. SMTP password хранится в базе данных в зашифрованном виде. Это ещё одна конфиденциальная настройка, которую защищает masterkey.

Раздельное резервное копирование PostgreSQL и 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 применим здесь почти без изменений, а хранение masterkey отдельно от архива — единственный нюанс, специфичный для Zitadel.

Обновление Zitadel без потери экземпляра

Обновление — это изменение версии в .env, за которым следуют две команды:

docker compose pull
docker compose up -d --wait

Поймите, что делает вторая команда, прежде чем запускать её в среде, где работают пользователи. Команда контейнера — start-from-init, которая выполняет этапы инициализации и настройки перед началом обслуживания запросов, а этап настройки — это миграции базы данных. Таким образом, изменение версии запускает миграции схемы в вашей рабочей базе данных при старте контейнера в автоматическом режиме, пока --wait ожидает прохождения проверки работоспособности (healthcheck). Именно поэтому тест восстановления, упомянутый выше, не является опциональным.

Сделайте свежий дамп непосредственно перед обновлением. Дамп, сделанный вчера вечером, — это уже не то.

Для версии v4.20.3 входы через внешних провайдеров идентификации, находящиеся в процессе, должны быть перезапущены, а неиспользованные коды авторизации Login V1 отклоняются один раз. Пользовательские интерфейсы входа требуют разрешения session.link для завершения запросов OIDC или SAML; предоставьте его сервисному пользователю IAM_LOGIN_CLIENT перед обновлением. Поставляемый сервисный пользователь Login V2 уже имеет эту роль. Проверки паролей через Session API теперь соблюдают политику входа организации пользователя, поэтому организации, отключившие вход по имени пользователя/паролю, должны перенаправлять пользователей к их провайдеру идентификации.

Не перепрыгивайте через мажорные версии. Перед переходом с v3 на v4 сначала обновитесь до v3.4.1 или новее. В v4 веб-ключи OIDC становятся обязательными и удаляется старый путь подписи, поэтому, если в вашем экземпляре v3 никогда не были включены веб-ключи, токены, подписанные старыми ключами, после обновления перестанут быть проверяемыми. Техническое уведомление Zitadel A-10017 гласит, что существующие JWT access-токены и ID-токены могут стать недействительными немедленно, и пользователям, возможно, придётся войти в систему снова. Решение заключается в промежуточном обновлении до v3.4.1 или новее и ожидании истечения срока действия токенов и сессий, подписанных старыми ключами, либо в принятии запланированного окна повторного входа. Если вы уже используете v3.4.1 или новее и выждали время с момента включения веб-ключей, уведомление гласит, что никаких действий не требуется.

Контролируйте этап настройки с помощью docker compose logs -f zitadel-api. Миграции в большом хранилище событий (eventstore) занимают минуты, и Traefik не будет направлять трафик к API, пока не пройдёт проверка работоспособности, поэтому сайт будет недоступен в течение этого времени. Планируйте это заранее, а не обнаруживайте по факту.

Откат — это не просто возврат старого тега. Как только миграции выполнены, старый бинарный файл не понимает структуру базы данных, которую он обнаруживает, поэтому откат означает восстановление из дампа. Как только в экземпляре появятся реальные пользователи, переходите на docker-compose.prodlike.yml — оверлей, который выполняет инициализацию и настройку как отдельные шаги, не связанные с запуском. Таким образом, миграция становится процессом, который вы запускаете и контролируете, а не побочным эффектом перезапуска контейнера.

Что указывать для нового поставщика идентификации

В консоли создайте проект, а затем приложение внутри него. Для любых современных решений выбирайте OIDC, и Zitadel предоставит вам client ID, client secret и документ обнаружения (discovery document) по адресу https://auth.example.com/.well-known/openid-configuration. Большинству self-hosted программ, поддерживающих единый вход (SSO), требуются именно эти данные.

Многие программы не поддерживают этот протокол или предоставляют его только в платных версиях. В первом случае oauth2-proxy перед приложением превращает любой HTTP-сервис в ресурс, который может защищать Zitadel. Во втором случае стоит прочитать статью налог на SSO в self-hosted приложениях, прежде чем планировать миграцию вокруг функциональности, за которую вы не заплатили.

FAQ

Сколько RAM и CPU требуется для self-hosted Zitadel?

В руководстве Zitadel для production указано, что самому Zitadel требуется около 0.5 GB RAM и достаточно менее одного ядра CPU. При этом рекомендуется выделить 4 ядра для хеширования паролей. Ресурсы для PostgreSQL рассчитываются отдельно: примерно одно ядро на 100 запросов в секунду и 4 GB RAM на каждое ядро. Большие значения в руководстве указаны из расчёта на один узел в кластере высокой доступности из трёх узлов: 4 ядер и 16 GB на каждый узел либо около 4 ядер и 8 GB без сбора логов и метрик. В quickstart для Compose требуется как минимум 2 GB. Этого достаточно для проверки, но для базы данных, которая потребуется системе и другим сервисам, останется мало ресурсов.

Что произойдёт, если я потеряю masterkey Zitadel?

Всё зашифрованное с его помощью останется зашифрованным. Учётные данные identity provider, пароль SMTP и seeds одноразовых паролей расшифровать нельзя. Изменить ключ после этого также нельзя. Сам по себе дамп базы данных не восстановит работоспособный экземпляр, поскольку содержит ciphertext, но не ключ. Храните masterkey в password manager и отдельно от резервной копии с дампом. Если потеряны оба объекта, единственный вариант — полностью пересоздать экземпляр.

Почему письма Zitadel для сброса пароля никогда не приходят?

Потому что SMTP provider не настроен либо настроенный provider не может доставлять сообщения. В Zitadel v4.20.0 по умолчанию используется legacy notification processing, поэтому настройки parallel worker: три попытки и интервал в пять минут — игнорируются. Настройте SMTP provider в instance settings и воспользуйтесь кнопкой тестирования в этой форме. Она отправляет настоящее сообщение. Активируйте provider, используйте relay с аутентификацией на порту, который разрешает ваш VPS provider, и опубликуйте записи SPF и DKIM для домена отправителя, чтобы сообщения не фильтровались как spam.

Можно ли изменить внешний домен Zitadel после установки?

Да, но не только изменив .env. Измените ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT и ZITADEL_EXTERNALSECURE, затем разрешите Zitadel повторно выполнить фазу настройки, чтобы применить изменение. Уже зарегистрированные приложения сохранят старые redirect URIs, поэтому их нужно обновить вручную. Любой запрос, у которого заголовок Host не соответствует известному Zitadel домену, получит ответ Instance not found. Если выбрать окончательное имя до первого запуска, всех этих проблем можно избежать.

Была ли эта статья полезной?