eco Начальный Туториал

Установка ZITADEL на VPS: self-hosted IAM, PostgreSQL, SSL, SMTP и резервное копирование

Мы получаем комиссию, когда вы покупаете по ссылкам на этой странице.

calendar_month Nov 02, 2026 schedule 19 мин. чтения visibility 607 просмотров
Установка ZITADEL на VPS: self-hosted IAM, PostgreSQL, SSL, SMTP и резервное копирование
dns Нет сервера под эту инструкцию? Vultr, DigitalOcean, Contabo sellАкция WebHosting UK: −10% на управляемые VPS до 30.11 Получить →

Установка ZITADEL на VPS: self-hosted IAM, PostgreSQL, SSL, SMTP и резервное копирование

TL;DR

ZITADEL можно развернуть на собственном VPS как единый сервис управления идентификацией и доступом: с PostgreSQL, HTTPS, SMTP, MFA, организациями, проектами и OAuth 2.0/OpenID Connect. Ниже используется Docker Compose, PostgreSQL 16, Caddy для автоматического TLS и restic для шифрованных резервных копий.

  • Для небольшой production-инсталляции достаточно 2 vCPU, 4 ГБ RAM и SSD от 40 ГБ.
  • ZITADEL запускается в Docker, а PostgreSQL хранит пользователей, организации, проекты и настройки.
  • Домен направляется на VPS, Caddy автоматически получает сертификат Let’s Encrypt.
  • SMTP нужен для приглашений, восстановления паролей, уведомлений и MFA-кодов.
  • В резервную копию входят PostgreSQL, конфигурация Compose, секреты и master key ZITADEL.

1. TL;DR

ZITADEL — self-hosted IAM-платформа для централизованной аутентификации пользователей, сервисов и администраторов. Она поддерживает OpenID Connect, OAuth 2.0, SAML, WebAuthn, MFA, организации и проектную модель доступа. В этой инструкции сервис размещается на Ubuntu Server 24.04 LTS, PostgreSQL работает в отдельном контейнере, а внешний доступ проходит через Caddy.

Команды рассчитаны на чистый сервер с публичным IPv4 и доменом auth.example.com. Перед выполнением замените этот домен, пароли, адрес электронной почты и значения S3 на собственные.

  • Система: Ubuntu Server 24.04 LTS, Docker Engine 28.x или новее, Docker Compose v2.
  • Приложение: ZITADEL 4.x, образ фиксируется конкретным тегом, а не latest.
  • База данных: PostgreSQL 16.x в Docker Compose.
  • Прокси: Caddy 2.10.x с автоматическим сертификатом Let’s Encrypt.
  • Резервное копирование: pg_dump и restic в совместимое с S3 объектное хранилище.

dnsСервер под эту инструкцию

Подходящие тарифы проверенных провайдеров, цены обновляются каждый день.

sell WebHosting UK: −10% на управляемые VPS · до 30.11 Получить →

Сравнить:Vultr vs DigitalOceanVultr vs ContaboВсе VPS по цене

Партнёрские ссылки: при покупке мы можем получить комиссию, цена для вас не меняется.

2. Содержание

Статья построена как рабочий сценарий: сначала выбирается сервер, затем выполняется базовое укрепление системы, после этого запускаются контейнеры и настраиваются домен, TLS, SMTP и резервное копирование.

  1. Проверка задачи и архитектуры.
  2. Расчёт ресурсов VPS или dedicated-сервера.
  3. Создание отдельного администратора и настройка SSH.
  4. Установка Docker и подготовка каталогов.
  5. Запуск PostgreSQL и ZITADEL.
  6. Настройка Caddy, HTTPS и SMTP.
  7. Проверка OAuth/OIDC, healthcheck и журналов.
  8. Автоматические бэкапы, восстановление и обновления.

3. Что мы настраиваем и зачем

Схема: 3. Что мы настраиваем и зачем
Схема: 3. Что мы настраиваем и зачем

Роль ZITADEL в инфраструктуре

Без IAM каждая веб-служба обычно хранит собственных пользователей, пароли, роли и сессии. Это приводит к нескольким базам аккаунтов, разным правилам MFA и сложному удалению доступа сотрудника. ZITADEL выносит аутентификацию в отдельный сервис: приложение перенаправляет пользователя на страницу входа, получает подписанный токен и проверяет его права.

Практический результат — единый вход для внутренних панелей, SaaS-приложений, Mattermost, Git-сервисов, VPN-портала и собственных API. Для интеграций используется стандартный OpenID Connect, поэтому приложение не обязано знать пароль пользователя или самостоятельно реализовывать восстановление доступа.

Архитектура этого руководства

Компонент Назначение Публичный доступ
Caddy HTTPS, reverse proxy, автоматическое продление сертификата TCP 80 и 443
ZITADEL IAM, OIDC, OAuth 2.0, административный интерфейс Только через Caddy
PostgreSQL 16 Хранение состояния ZITADEL Только внутренняя Docker-сеть
restic Шифрование и отправка резервных копий Исходящие соединения к S3

Что будет готово после выполнения

  • Адрес административной консоли: https://auth.example.com/ui/console.
  • PostgreSQL без открытого порта в Интернет.
  • HTTPS с валидным сертификатом и автоматическим продлением.
  • SMTP для приглашений и восстановления учётных записей.
  • OIDC-совместимый IAM для нескольких приложений.
  • Ежедневный зашифрованный бэкап базы и конфигурации.

Self-hosted или cloud-managed

Облачный IAM уменьшает операционную нагрузку: провайдер отвечает за обновления, резервирование, доступность и часть защиты. Это удобно, если IAM не является критичным контролем инфраструктуры или команда не готова самостоятельно реагировать на сбои.

Self-hosted ZITADEL на VPS подходит, когда важны контроль над данными, предсказуемая стоимость, собственный домен и возможность изолировать IAM в выбранной юрисдикции. Обратная сторона — ответственность владельца за патчи, мониторинг, секреты, SMTP, резервные копии и восстановление. IAM нельзя считать надёжным только потому, что контейнер запущен: необходимо регулярно проверять процедуру восстановления.

Ограничения

ZITADEL не заменяет LDAP для всех старых приложений, хотя отдельные сценарии интеграции возможны. Также он не является системой управления секретами для серверов. Пароли баз данных, master key и ключи restic нужно хранить отдельно от исходного кода и желательно в менеджере секретов.

4. Какой VPS-конфиг нужен под эту задачу

Схема: 4. Какой VPS-конфиг нужен под эту задачу
Схема: 4. Какой VPS-конфиг нужен под эту задачу

Минимальная конфигурация

Для тестовой среды и небольшой команды из нескольких десятков пользователей подойдёт 2 vCPU, 4 ГБ RAM и 40 ГБ SSD. Минимум в 2 ГБ RAM возможен, но при одновременной работе PostgreSQL, ZITADEL, Caddy, Docker и процесса бэкапа запас практически отсутствует.

Сценарий CPU RAM Диск Сеть
Тестирование 1–2 vCPU 2–4 ГБ 30–40 ГБ SSD 100 Мбит/с
Небольшая production-команда 2–4 vCPU 4–8 ГБ 60–100 ГБ NVMe 100–1000 Мбит/с
Много организаций и приложений 4–8 vCPU 8–16 ГБ 100+ ГБ NVMe 1 Гбит/с

Для типовой установки можно взять VPS с такими характеристиками: 2–4 vCPU, 4–8 ГБ RAM, SSD/NVMe от 60 ГБ, публичный IPv4 и возможность открыть TCP 80 и 443. Диск должен учитывать не только базу: логи, обновления Docker-образов и временные файлы дампа могут занять несколько гигабайт.

Когда нужен dedicated

Отдельный физический сервер обычно не требуется для одного ZITADEL. Dedicated оправдан, если IAM работает вместе с большим числом сервисов, база содержит десятки или сотни тысяч объектов, нужны гарантированные ресурсы без соседей, либо политика безопасности запрещает виртуализацию на общем узле.

Для высокой доступности одного dedicated также недостаточно: при отказе диска или питания сервис всё равно остановится. Важнее два независимых узла, репликация PostgreSQL, внешний балансировщик и проверенное восстановление. Для большинства небольших инсталляций лучше начать с VPS и отдельно хранить бэкапы.

Локация и сеть

Выбирайте регион ближе к пользователям и приложениям. Расстояние влияет на задержку OIDC-перенаправлений, скорость загрузки консоли и время ответа API. Если приложения находятся в нескольких регионах, размещайте IAM там, где находится большинство пользователей, либо используйте CDN и отдельную высокодоступную архитектуру.

Нужен публичный IPv4, корректная PTR-запись желательно для почтовой инфраструктуры и возможность настроить DNS-записи. Для Caddy домен должен указывать на VPS до запуска прокси, иначе выпуск сертификата Let’s Encrypt завершится ошибкой.

5. Подготовка сервера

Вход и обновление Ubuntu

Подключитесь к серверу под временным пользователем, выданным провайдером. Все команды ниже выполняются от пользователя с правами sudo. В примере используется Ubuntu 24.04 LTS с системной архитектурой amd64 или arm64.

# Проверяем версию системы и обновляем пакеты
cat /etc/os-release
sudo apt update && sudo apt full-upgrade -y

# Устанавливаем базовые инструменты
sudo apt install -y ca-certificates curl gnupg lsb-release \
  git jq unzip vim ufw fail2ban unattended-upgrades

После обновления ядра проверьте необходимость перезагрузки. Если ядро или критичные системные библиотеки изменились, перезапустите сервер в согласованное окно обслуживания.

# Показываем, требуется ли перезагрузка
if [ -f /var/run/reboot-required ]; then echo "Требуется reboot"; fi

# После согласования окна обслуживания
sudo reboot

Отдельный пользователь и SSH-ключи

Не используйте root для повседневной работы. Создайте администратора, добавьте публичный ключ и только после проверки нового входа отключайте парольную аутентификацию. Не закрывайте текущую SSH-сессию, пока новая сессия не подтверждена.

# Создаём отдельного администратора
sudo adduser deploy
sudo usermod -aG sudo deploy

# Создаём каталог SSH и добавляем ваш публичный ключ
sudo install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
sudo nano /home/deploy/.ssh/authorized_keys
sudo chown deploy:deploy /home/deploy/.ssh/authorized_keys
sudo chmod 600 /home/deploy/.ssh/authorized_keys

В файл authorized_keys вставьте одну строку с ключом ssh-ed25519. После проверки подключения измените SSH-конфигурацию.

# Отключаем root-вход и пароли после проверки ключевого доступа
sudo tee /etc/ssh/sshd_config.d/10-hardening.conf > /dev/null <<'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
MaxAuthTries 4
EOF

# Проверяем синтаксис и перечитываем конфигурацию SSH
sudo sshd -t && sudo systemctl reload ssh

Firewall и fail2ban

Откройте SSH, HTTP и HTTPS. Если SSH работает на нестандартном порту, замените значение в правиле. Порт PostgreSQL наружу не открывайте: контейнеры будут общаться через внутреннюю сеть Docker.

# Разрешаем только необходимые входящие соединения
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment 'SSH'
sudo ufw allow 80/tcp comment 'HTTP for ACME'
sudo ufw allow 443/tcp comment 'HTTPS'
sudo ufw --force enable
sudo ufw status verbose

# Запускаем защиту от перебора SSH
sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

Docker публикует порты через собственные правила iptables/nftables. Поэтому не следует публиковать PostgreSQL через Compose даже при включённом UFW. Проверяйте список слушающих портов после запуска сервисов.

6. Установка ПО — пошагово

Схема: 6. Установка ПО — пошагово
Схема: 6. Установка ПО — пошагово

Установка Docker Engine и Compose

Используйте официальный репозиторий Docker, а не устаревшие пакеты из случайных скриптов. В 2026 году для этого руководства достаточно Docker Engine 28.x и Docker Compose v2. Установка не должна выполняться через непроверенный curl-скрипт с неизвестным источником.

# Добавляем официальный ключ репозитория Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий Docker для текущего релиза Ubuntu
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Устанавливаем Engine, CLI, Buildx и Compose plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Проверяем версии и включаем автозапуск
sudo docker version
sudo docker compose version
sudo systemctl enable --now docker

Добавление пользователя в группу docker позволяет запускать Docker без sudo, но фактически даёт права root. На production-сервере можно оставить команды через sudo; это уменьшает риск случайного запуска опасного контейнера от обычной shell-сессии.

Создание каталогов проекта

# Создаём отдельные каталоги конфигурации, данных и бэкапов
sudo install -d -m 750 /opt/zitadel
sudo install -d -m 750 /opt/zitadel/caddy
sudo install -d -m 750 /opt/zitadel/postgres
sudo install -d -m 750 /opt/zitadel/backups
sudo chown -R deploy:deploy /opt/zitadel

# Переходим в каталог приложения
cd /opt/zitadel

В Compose ниже используется PostgreSQL 16 и ZITADEL 4.x. Зафиксируйте конкретный проверенный тег образа, например ghcr.io/zitadel/zitadel:v4.0.0, если этот тег доступен в официальном реестре на момент установки. Перед production-развёртыванием сверьте актуальный стабильный релиз и migration notes в официальной документации ZITADEL.

Подготовка файла секретов

Секреты не должны попадать в Git, публичные логи и команды, сохранённые в shell history. Создайте файл .env, ограничьте его права и добавьте его в исключения Git. Master key необходимо сохранить в отдельном защищённом месте: без него восстановленная база ZITADEL может оказаться непригодной для запуска.

# Генерируем случайные значения и создаём защищённый .env
cd /opt/zitadel
umask 077
POSTGRES_PASSWORD="$(openssl rand -base64 36 | tr -dc 'A-Za-z0-9' | head -c 32)"
MASTER_KEY="$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 32)"
RESTIC_PASSWORD="$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 40)"

cat > .env <<EOF
ZITADEL_DOMAIN=auth.example.com
ZITADEL_IMAGE=ghcr.io/zitadel/zitadel:v4.0.0
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
ZITADEL_MASTERKEY=${MASTER_KEY}
RESTIC_PASSWORD=${RESTIC_PASSWORD}
EOF

chmod 600 .env
grep -v 'PASSWORD\|MASTERKEY' .env

Docker Compose

Создайте файл compose.yaml. У PostgreSQL нет секции ports, поэтому база доступна только контейнеру ZITADEL в сети iam. Политика restart: unless-stopped перезапускает сервис после сбоя, но не заменяет мониторинг.

name: zitadel

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: zitadel
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: zitadel
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U zitadel -d zitadel"]
      interval: 10s
      timeout: 5s
      retries: 10
    networks:
      - iam

  zitadel:
    image: ${ZITADEL_IMAGE}
    restart: unless-stopped
    command: start-from-init --masterkeyfile /run/secrets/zitadel_masterkey
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      ZITADEL_DATABASE_POSTGRES_HOST: postgres
      ZITADEL_DATABASE_POSTGRES_PORT: "5432"
      ZITADEL_DATABASE_POSTGRES_DATABASE: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_USERNAME: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: ${POSTGRES_PASSWORD}
      ZITADEL_EXTERNALDOMAIN: ${ZITADEL_DOMAIN}
      ZITADEL_EXTERNALSECURE: "true"
      ZITADEL_TLS_ENABLED: "false"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: admin
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL: [email protected]
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: CHANGE_THIS_FIRST_PASSWORD
    secrets:
      - zitadel_masterkey
    expose:
      - "8080"
    networks:
      - iam

  caddy:
    image: caddy:2.10-alpine
    restart: unless-stopped
    depends_on:
      - zitadel
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - iam

secrets:
  zitadel_masterkey:
    file: ./secrets/masterkey

volumes:
  postgres_data:
  caddy_data:
  caddy_config:

networks:
  iam:
    driver: bridge

Пароль первого администратора в примере нужно заменить до запуска. Для production используйте длинный случайный пароль, а после первого входа включите MFA и создайте отдельную администраторскую учётную запись. Не оставляйте значение CHANGE_THIS_FIRST_PASSWORD.

# Создаём master key-файл, совпадающий со значением в .env
set -a
. /opt/zitadel/.env
set +a
sudo install -d -m 700 /opt/zitadel/secrets
printf '%s' "$ZITADEL_MASTERKEY" | sudo tee /opt/zitadel/secrets/masterkey > /dev/null
sudo chmod 600 /opt/zitadel/secrets/masterkey
sudo chown -R deploy:deploy /opt/zitadel/secrets

# Проверяем конфигурацию Compose без запуска контейнеров
docker compose config

# Загружаем образы
docker compose pull

# Запускаем PostgreSQL и ZITADEL в фоне
docker compose up -d postgres zitadel

# Просматриваем состояние и последние логи
docker compose ps
docker compose logs --tail=100 zitadel

На первом запуске ZITADEL инициализирует схему базы. Это может занять несколько минут. Если контейнер завершился, сначала изучите логи, а не запускайте повторно случайные команды миграции. Ошибка в master key или подключении к PostgreSQL должна быть исправлена в конфигурации.

7. Конфигурация

Схема: 7. Конфигурация
Схема: 7. Конфигурация

Домен и DNS

Создайте A-запись auth.example.com на публичный IPv4 VPS. Если используется IPv6, добавьте AAAA только после проверки, что веб-сервер действительно доступен по IPv6. Неправильная AAAA-запись часто приводит к тому, что часть пользователей не может открыть сайт.

# Проверяем DNS с сервера или локального компьютера
dig +short A auth.example.com
dig +short AAAA auth.example.com

# Проверяем, что имя разрешается в ожидаемый адрес
getent ahosts auth.example.com

Caddy и HTTPS

Caddy получает сертификат автоматически, если DNS уже указывает на сервер, порты 80 и 443 открыты, а домен доступен из Интернета. ZITADEL внутри слушает HTTP на порту 8080, но внешняя схема задаётся как HTTPS через ZITADEL_EXTERNALSECURE=true.

auth.example.com {
    encode gzip zstd

    reverse_proxy zitadel:8080 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-For {remote_host}
    }

    log {
        output file /var/log/caddy/zitadel-access.log
        format json
    }
}

Создайте каталог и запустите Caddy после проверки файла.

# Проверяем конфигурацию Caddy внутри временного контейнера
docker run --rm -v /opt/zitadel/caddy/Caddyfile:/etc/caddy/Caddyfile:ro \
  caddy:2.10-alpine caddy validate --config /etc/caddy/Caddyfile

# Запускаем reverse proxy и смотрим выпуск сертификата
cd /opt/zitadel
docker compose up -d caddy
docker compose logs -f caddy

Проверка HTTPS и healthcheck

Ожидаемый результат первого запроса — HTTP 200, 301 или ответ приложения без ошибки TLS. Health endpoint может отличаться между версиями, поэтому проверяйте его по документации установленного релиза. Основной признак работоспособности — успешный запуск контейнера, доступность UI и отсутствие ошибок подключения к базе.

# Проверяем TLS, заголовки и конечный HTTP-ответ
curl -I https://auth.example.com
curl -fsS https://auth.example.com/debug/healthz || true

# Проверяем контейнеры, порты и ошибки приложения
docker compose ps
docker compose logs --since=10m zitadel | grep -Ei 'error|fatal|panic' || true
sudo ss -tulpn | grep -E ':80|:443|:5432'

Порт 5432 в выводе не должен слушать публичный интерфейс. Если он появился, проверьте Compose и удалите секцию ports у PostgreSQL. Не публикуйте административную консоль напрямую через IP: используйте домен и HTTPS.

Первый вход и MFA

Откройте https://auth.example.com/ui/console и войдите под пользователем, заданным переменными первого экземпляра. Немедленно смените временный пароль, подтвердите адрес электронной почты после настройки SMTP и включите MFA через TOTP или WebAuthn.

Для ежедневной работы создайте отдельную административную учётную запись, а первоначальный аккаунт оставьте как аварийный. Минимизируйте роли: разработчику приложения не нужна роль глобального администратора IAM. Включите журналирование административных событий и регулярно просматривайте неизвестные входы.

SMTP

SMTP используется для приглашений, восстановления доступа, уведомлений и некоторых сценариев MFA. Лучше использовать отдельный почтовый ящик или транзакционный SMTP-сервис с ограниченным назначением. Не запускайте почтовый сервер на том же VPS без необходимости: это усложнит SPF, DKIM, DMARC и репутацию IP.

SMTP можно настроить через консоль ZITADEL в параметрах экземпляра. Укажите hostname SMTP-провайдера, порт 587 с STARTTLS, имя пользователя, пароль, адрес отправителя и отображаемое имя. Типовой набор переменных при автоматизации имеет следующий вид; точные имена нужно сверить с документацией версии ZITADEL, потому что параметры экземпляра меняются между релизами.

# Фрагмент environment для SMTP; пароль храните только в .env или secret store
environment:
  ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST: smtp.example.net
  ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_PORT: "587"
  ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_USER: ${SMTP_USER}
  ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_PASSWORD: ${SMTP_PASSWORD}
  ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_FROM: "IAM <[email protected]>"
  ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_TLS: "true"

После сохранения отправьте тестовое письмо из интерфейса. Проверьте папки spam, DNS-записи домена отправителя и логи приложения. Для домена отправителя настройте SPF и DKIM по инструкции почтового провайдера, а DMARC начните с политики мониторинга, например p=none, затем ужесточайте её после анализа отчётов.

OIDC-приложение

Для подключения приложения создайте в консоли проект и приложение типа Web или API. Для веб-приложения укажите точные redirect URI, например https://app.example.com/oauth/callback. Не используйте wildcard в production, если это не требуется архитектурой.

Для проверки discovery-документа запросите стандартный URL:

# Выводит OpenID Connect discovery-документ
curl -fsS https://auth.example.com/.well-known/openid-configuration | jq .

# Проверяет наличие основных endpoint
curl -fsS https://auth.example.com/.well-known/openid-configuration | \
  jq '{issuer,authorization_endpoint,token_endpoint,jwks_uri}'

Приложение должно проверять issuer, подпись JWT по JWKS, срок действия токена, audience и scopes. Нельзя считать любой JWT с внешним видом токена доверенным без проверки этих полей.

8. Бэкапы и обслуживание

Что необходимо сохранять

  • Дамп PostgreSQL или физическую копию базы.
  • Файл compose.yaml, .env, Caddyfile и master key.
  • Docker volume PostgreSQL, если выбран физический способ восстановления.
  • Конфигурацию мониторинга и список DNS-записей.
  • Ключ restic и пароль репозитория в отдельном защищённом хранилище.

Копирование только каталога PostgreSQL без согласованного состояния базы рискованно. Для ежедневного логического бэкапа используйте pg_dump. Перед созданием дампа база продолжает работать, но восстановление нужно регулярно проверять на отдельном временном экземпляре.

Установка restic и настройка S3

Резервные копии на том же VPS не защищают от потери диска, удаления проекта или компрометации сервера. Храните их в отдельном S3-совместимом объектном хранилище, желательно в другом регионе. Restic шифрует содержимое до отправки, поэтому S3-провайдер не видит данные базы.

# Устанавливаем restic из репозитория Ubuntu
sudo apt update
sudo apt install -y restic postgresql-client

# Создаём каталог для скрипта и ограничиваем права
sudo install -d -m 750 /usr/local/sbin
sudo touch /etc/restic-zitadel.env
sudo chmod 600 /etc/restic-zitadel.env

Заполните /etc/restic-zitadel.env. Значения AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY должны иметь только права на нужный bucket, без административного доступа к аккаунту.

sudo tee /etc/restic-zitadel.env > /dev/null <<'EOF'
export RESTIC_REPOSITORY="s3:https://s3.example.net/iam-backups"
export RESTIC_PASSWORD="replace-with-long-restic-password"
export AWS_ACCESS_KEY_ID="replace-with-limited-access-key"
export AWS_SECRET_ACCESS_KEY="replace-with-secret-key"
export PGUSER="zitadel"
export PGPASSWORD="replace-with-postgres-password"
EOF
sudo chmod 600 /etc/restic-zitadel.env

Инициализируйте репозиторий один раз. Пароль restic нельзя восстановить через S3: если он потерян, зашифрованные данные становятся недоступны.

# Инициализируем зашифрованный репозиторий
sudo bash -c '. /etc/restic-zitadel.env; restic init'

# Проверяем доступ к репозиторию
sudo bash -c '. /etc/restic-zitadel.env; restic snapshots'

Скрипт ежедневного бэкапа

Скрипт сначала создаёт дамп PostgreSQL, затем архивирует конфигурацию и master key, после чего отправляет каталог в restic. Временный каталог удаляется через trap, даже если одна из команд завершится ошибкой.

sudo tee /usr/local/sbin/backup-zitadel.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -Eeuo pipefail

source /etc/restic-zitadel.env
BASE=/opt/zitadel
TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT

mkdir -p "$TMP/db" "$TMP/config"

# Делаем согласованный логический дамп PostgreSQL
docker exec -e PGPASSWORD="$PGPASSWORD" zitadel-postgres-1 \
  pg_dump -U "$PGUSER" -d zitadel --format=custom \
  > "$TMP/db/zitadel-$(date +%F).dump"

# Копируем Compose, env, Caddyfile и master key
cp "$BASE/compose.yaml" "$TMP/config/"
cp "$BASE/.env" "$TMP/config/"
cp "$BASE/caddy/Caddyfile" "$TMP/config/"
cp "$BASE/secrets/masterkey" "$TMP/config/"

# Отправляем файлы в зашифрованный restic-репозиторий
restic backup "$TMP" --tag zitadel --host "$(hostname -s)"

# Удаляем старые точки восстановления
restic forget --tag zitadel --keep-daily 14 --keep-weekly 8 \
  --keep-monthly 12 --prune

# Проверяем случайный набор данных в репозитории
restic check
EOF

sudo chmod 750 /usr/local/sbin/backup-zitadel.sh
sudo /usr/local/sbin/backup-zitadel.sh

Имя контейнера PostgreSQL может отличаться, если Compose использует другой project name. Проверьте его командой docker compose ps и замените zitadel-postgres-1 в скрипте. Более устойчивый вариант — выполнять дамп через docker compose exec -T postgres из каталога проекта.

Cron и проверка восстановления

Запускайте резервное копирование ночью, когда меньше интерактивных входов. Cron должен отправлять ошибку в системный журнал; для production дополнительно настройте внешний мониторинг, который проверяет свежесть последнего snapshot.

# Запускаем бэкап ежедневно в 03:20
sudo tee /etc/cron.d/zitadel-backup > /dev/null <<'EOF'
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
20 3    root /usr/local/sbin/backup-zitadel.sh > /var/log/zitadel-backup.log 2>&1
EOF
sudo chmod 644 /etc/cron.d/zitadel-backup

# Смотрим последние snapshot
sudo bash -c '. /etc/restic-zitadel.env; restic snapshots --tag zitadel'

Минимальная проверка восстановления: создать временную PostgreSQL 16, скачать последний dump, выполнить pg_restore --list, затем восстановить базу и проверить наличие таблиц. Полный disaster recovery-тест проводите минимум раз в квартал.

# Скачиваем последний бэкап во временный каталог
sudo mkdir -p /tmp/zitadel-restore
sudo bash -c '. /etc/restic-zitadel.env; restic restore latest --target /tmp/zitadel-restore'

# Проверяем структуру custom-format дампа
pg_restore --list /tmp/zitadel-restore/tmp/db/zitadel-.dump | head -30

Обновления ZITADEL и PostgreSQL

Не меняйте тег образа без чтения release notes. Перед обновлением сделайте свежий дамп, snapshot и копию master key. Для небольшой установки допустимо maintenance window на несколько минут: остановить приложение, заменить тег, выполнить docker compose pull и запустить контейнеры.

# Пример контролируемого обновления после проверки release notes
cd /opt/zitadel
sudo /usr/local/sbin/backup-zitadel.sh
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --since=10m zitadel

Rolling update возможен только при архитектуре с несколькими экземплярами, совместимой схемой миграций и отдельным балансировщиком. Один VPS с одним контейнером — это maintenance window, а не rolling deployment. PostgreSQL major upgrade с 16 на 17 выполняйте отдельно, после тестового восстановления и проверки совместимости ZITADEL.

9. Troubleshooting и FAQ

Почему Caddy не получает сертификат Let’s Encrypt?

Проверьте, что A-запись домена указывает на правильный IPv4, а AAAA-запись не ведёт на недоступный IPv6. Затем убедитесь, что TCP 80 и 443 разрешены в UFW и во внешнем firewall провайдера. Посмотрите docker compose logs caddy. Если на 80-м порту уже работает Nginx или Apache, остановите его либо перенесите Caddy на освободившийся порт.

ZITADEL отвечает ошибкой о внешнем домене или redirect URI

Сверьте ZITADEL_EXTERNALDOMAIN с фактическим hostname без протокола, а ZITADEL_EXTERNALSECURE установите в true, если пользователь подключается по HTTPS. В OIDC-клиенте redirect URI должен совпадать полностью: схема, домен, порт и путь учитываются при проверке. После изменения environment пересоздайте контейнер командой docker compose up -d --force-recreate zitadel.

Контейнер ZITADEL перезапускается и не подключается к PostgreSQL

Сначала выполните docker compose ps и проверьте healthcheck базы. Затем посмотрите docker compose logs postgres и docker compose logs zitadel. Наиболее частые причины — неправильный пароль, неверное имя сервиса, база ещё не прошла инициализацию или повреждённый volume. Не удаляйте volume PostgreSQL до проверки бэкапа: это уничтожит данные.

SMTP работает, но письма не доходят

Проверьте SMTP host, порт 587, STARTTLS, логин и пароль. Убедитесь, что адрес отправителя разрешён провайдером и домен имеет SPF/DKIM. В журналах ZITADEL ищите timeout, authentication failed и certificate verification error. Если письмо принято SMTP, но не пришло пользователю, проверяйте очередь и логи самого почтового сервиса, а также папку spam.

Какой VPS-конфиг минимально подойдёт?

Для лаборатории достаточно 1–2 vCPU, 2 ГБ RAM и 30–40 ГБ SSD, но такая конфигурация плохо переносит одновременные миграции, бэкап и другие сервисы. Для небольшой production-инсталляции разумный минимум — 2 vCPU, 4 ГБ RAM и 60 ГБ SSD/NVMe. Если на том же сервере работают приложения, прокси и мониторинг, выбирайте 4 vCPU и 8 ГБ RAM.

Что выбрать — VPS или dedicated для этой задачи?

Для одного ZITADEL и нескольких приложений обычно достаточно VPS: он дешевле, быстро масштабируется и не требует самостоятельного обслуживания физического оборудования. Dedicated имеет смысл при строгой изоляции ресурсов, большом количестве пользователей или совместном размещении тяжёлых сервисов. Однако dedicated не создаёт высокой доступности сам по себе; в обоих вариантах нужны внешние бэкапы и план восстановления.

Как проверить, что PostgreSQL не открыт в Интернет?

На сервере выполните sudo ss -tulpn | grep 5432. В Compose у PostgreSQL не должно быть секции ports, только внутренняя сеть и, при необходимости, expose. Дополнительно проверьте порт с внешней машины через nmap -Pn -p 5432 PUBLIC_IP. Если порт виден, удалите публикацию, пересоздайте контейнер и проверьте правила внешнего firewall.

Что делать после потери master key?

Master key нельзя безопасно заменить простым редактированием .env: он используется для работы с зашифрованными данными и должен соответствовать исходной установке. Найдите его в защищённой резервной копии или менеджере секретов. Если ключ утрачен вместе с оригинальным сервером, сначала создайте копию базы и обратитесь к документации конкретного релиза, не пытаясь удалять таблицы или выполнять неизвестные SQL-команды.

Почему discovery endpoint доступен, а вход не работает?

Проверьте время на сервере и клиенте, корректность issuer, redirect URI, client ID и secret. Неверное время ломает проверку сроков JWT и cookies. Также убедитесь, что приложение не использует старый issuer после смены домена. В браузере проверьте cookies и ошибки callback, а на стороне приложения включите безопасное логирование без записи access token и client secret.

10. Выводы и следующие шаги

Схема: 10. Выводы и следующие шаги
Схема: 10. Выводы и следующие шаги

На VPS развёрнут self-hosted ZITADEL с PostgreSQL 16, HTTPS через Caddy, SMTP для системных сообщений и зашифрованными резервными копиями. Доступ к базе закрыт, IAM доступен по домену, а OIDC discovery можно использовать для подключения приложений.

Дальше стоит подключить внешний мониторинг HTTPS и срока действия сертификата, регулярно тестировать восстановление в отдельной среде и обновлять ZITADEL только после проверки release notes. При росте нагрузки добавьте отдельный PostgreSQL, второй экземпляр IAM, балансировщик и отказоустойчивое хранилище; при росте команды — разделяйте организации, проекты и административные роли по принципу минимальных привилегий.

Партнёрские ссылки: при покупке мы можем получить комиссию, цена для вас не меняется.

Был ли этот гайд полезен?

Ваш отзыв помогает нам улучшать гайды.

Поделиться записью:

Отправьте гайд тому, кому он может пригодиться.

Telegram VKVK WhatsApp Facebook LinkedIn XX

установка zitadel на vps: self-hosted iam, postgresql, ssl, smtp и резервное копирование