Установка Keycloak на VPS: Полный гайд по настройке SSO и IAM

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

В современном мире, где каждое приложение требует аутентификации, управление учетными записями может стать настоящей головной болью. Keycloak решает эту проблему, предоставляя мощную платформу для управления идентификацией и доступом (IAM) с поддержкой единого входа (SSO).

Keycloak — это open-source решение, которое позволяет централизованно управлять пользователями, ролями, группами и предоставлять им доступ к вашим приложениям. Он поддерживает стандартные протоколы, такие как OpenID Connect, OAuth 2.0 и SAML 2.0, что делает его совместимым практически с любым современным веб-приложением или сервисом. С помощью Keycloak вы можете:

• Реализовать единый вход (SSO): Пользователям достаточно один раз авторизоваться, чтобы получить доступ ко всем подключенным приложениям без повторного ввода учетных данных.
• Управлять пользователями и ролями: Централизованное создание, редактирование и удаление пользователей, назначение им ролей и групп.
• Использовать социальную авторизацию: Легко интегрировать вход через Google, GitHub, Facebook и другие популярные провайдеры.
• Применять многофакторную аутентификацию (MFA): Повысить безопасность учетных записей.
• Настраивать федерацию идентификации: Подключать внешние провайдеры, такие как LDAP или Active Directory.

В итоге, читатель получит полностью настроенный и готовый к работе сервер Keycloak, который будет служить центральной точкой аутентификации для его проектов. Это значительно упростит разработку новых приложений, повысит безопасность и улучшит пользовательский опыт.

Альтернативы: Cloud-managed vs Self-hosted

Существуют коммерческие облачные сервисы IAM/SSO, такие как Auth0, Okta, Amazon Cognito, Google Identity Platform. Они предлагают удобство "под ключ", снятие бремени обслуживания и масштабирования. Однако у них есть свои недостатки:

• Стоимость: По мере роста числа пользователей или функций затраты могут быстро стать значительными.
• Контроль данных: Ваши данные аутентификации хранятся у стороннего провайдера, что может быть неприемлемо по соображениям безопасности, конфиденциальности или регуляторным требованиям.
• Гибкость: Хотя облачные сервисы гибки, они все же имеют ограничения по кастомизации и интеграции, которые могут быть присущи open-source решению.

Self-hosted Keycloak на VPS предлагает полный контроль над вашей системой аутентификации. Это идеальный выбор для разработчиков, solo-фаундеров SaaS, компаний, которым требуется высокая степень кастомизации, или тех, кто хочет минимизировать эксплуатационные расходы в долгосрочной перспективе. Вы управляете всеми аспектами безопасности, производительности и данных, что дает максимальную свободу и независимость.

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

Keycloak, будучи Java-приложением, требует достаточных ресурсов, особенно оперативной памяти. Выбор оптимального VPS-конфига зависит от предполагаемой нагрузки: количества пользователей, частоты аутентификаций и количества подключенных приложений.

Минимальные требования для небольшой инсталляции (до 500 активных пользователей)

• CPU: 2 vCPU (виртуальных ядра). Этого будет достаточно для обработки большинства запросов.
• RAM: 4 GB. Keycloak сам по себе может потреблять 1.5-2 GB RAM, плюс PostgreSQL и операционная система.
• Диск: 50 GB SSD. SSD критически важен для производительности базы данных и быстрой загрузки Keycloak. 50 GB хватит для ОС, Keycloak и умеренного объема данных БД.
• Сеть: 100 Mbps. Для большинства задач этого более чем достаточно.

Рекомендуемый VPS-план для среднего проекта (до 5000 активных пользователей)

Для более серьезных нагрузок или если вы планируете активно использовать Keycloak с несколькими приложениями и большим количеством пользователей, рекомендуется рассмотреть следующий конфиг:

• CPU: 4 vCPU. Обеспечит лучшую отзывчивость при пиковых нагрузках.
• RAM: 8 GB. Позволит Keycloak и PostgreSQL более эффективно кешировать данные и обрабатывать больше одновременных запросов.
• Диск: 100-200 GB SSD. Больший объем диска обеспечит пространство для логов, бэкапов и роста базы данных.
• Сеть: 1 Gbps. Для высоконагруженных приложений.

Для аренды VPS с указанными характеристиками можно взять VPS с 4 vCPU, 8 GB RAM и 100 GB SSD.

Когда нужен dedicated сервер, а не VPS

Dedicated сервер становится необходим, когда:

• Очень высокая нагрузка: Тысячи одновременных запросов, десятки тысяч активных пользователей.
• Требования к производительности: Нужна гарантированная производительность без "соседства" с другими пользователями на одном физическом сервере.
• Специфичные аппаратные требования: Например, аппаратные модули безопасности (HSM) или очень большой объем RAM/диска.
• Строгие нормы соответствия: Некоторые регуляторные требования могут предписывать использование физически изолированного оборудования.

Для таких случаев, когда требуется максимальная производительность и изоляция, можно рассмотреть подходящий dedicated сервер.

Локация: на что влияет

Выбор локации VPS важен по нескольким причинам:

• Задержка (Latency): Чем ближе сервер к вашим пользователям и приложениям, тем меньше задержка. Это критично для интерактивных сервисов.
• Законодательство о данных: В зависимости от того, где находятся ваши пользователи и где вы ведете бизнес, могут действовать различные законы о хранении и обработке персональных данных (например, GDPR в Европе). Выбор локации сервера, соответствующей этим законам, является обязательным.
• Доступность: Размещение серверов в разных географических точках может повысить отказоустойчивость вашей инфраструктуры.

Всегда выбирайте локацию, которая находится максимально близко к основной аудитории ваших приложений.

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

Перед установкой Keycloak необходимо выполнить базовую настройку нового VPS для обеспечения безопасности и стабильности. Мы будем использовать Ubuntu Server 24.04 LTS как операционную систему.

1. Обновление системы

Первым делом обновите все пакеты до актуальных версий.

sudo apt update && sudo apt upgrade -y

Эта команда обновляет список доступных пакетов и затем обновляет установленные пакеты до последних версий.

2. Создание нового пользователя и настройка SSH-доступа

Для повышения безопасности не рекомендуется работать под учетной записью root. Создадим нового пользователя и предоставим ему права sudo.

# Создаем нового пользователя (замените 'youruser' на желаемое имя)
sudo adduser youruser
# Добавляем пользователя в группу sudo
sudo usermod -aG sudo youruser

Теперь скопируйте ваш публичный SSH-ключ для нового пользователя. С локальной машины:

ssh-copy-id youruser@your_vps_ip

После этого выйдите из root-сессии и войдите под новым пользователем.

exit
ssh youruser@your_vps_ip

3. Настройка SSH-сервера

Отключите вход по паролю и вход для root-пользователя, оставив только аутентификацию по ключу.

sudo nano /etc/ssh/sshd_config

Найдите и измените следующие строки:

# Запретить вход для root-пользователя
PermitRootLogin no
# Запретить вход по паролю
PasswordAuthentication no
# Разрешить только аутентификацию по ключу
PubkeyAuthentication yes

Сохраните изменения (Ctrl+O, Enter) и выйдите (Ctrl+X). Перезапустите SSH-сервер:

sudo systemctl restart sshd

Важно: Убедитесь, что вы можете войти под новым пользователем с SSH-ключом, прежде чем закрывать текущую сессию!

4. Настройка файрвола (UFW)

Uncomplicated Firewall (UFW) — это простой в использовании интерфейс для iptables. Настроим его, чтобы разрешить только необходимые порты.

# Разрешаем SSH (порт 22, если вы его не меняли)
sudo ufw allow OpenSSH
# Разрешаем HTTP (порт 80)
sudo ufw allow http
# Разрешаем HTTPS (порт 443)
sudo ufw allow https
# Включаем файрвол
sudo ufw enable
# Проверяем статус файрвола
sudo ufw status

Вывод sudo ufw status должен показать, что SSH, HTTP и HTTPS разрешены.

5. Установка Fail2ban

Fail2ban сканирует логи и блокирует IP-адреса, показывающие признаки вредоносной активности (например, многократные неудачные попытки входа по SSH).

# Устанавливаем Fail2ban
sudo apt install fail2ban -y
# Копируем файл конфигурации по умолчанию
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
# Запускаем и включаем Fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
# Проверяем статус
sudo systemctl status fail2ban

Fail2ban по умолчанию защищает SSH. Вы можете настроить его для защиты других сервисов, отредактировав /etc/fail2ban/jail.local.

6. Установка базовых утилит

Установим несколько полезных утилит, которые пригодятся в процессе настройки и мониторинга.

sudo apt install curl wget git htop net-tools -y

Теперь ваш сервер готов к установке основного ПО.

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

Для удобства развертывания и управления мы будем использовать Docker и Docker Compose. Это позволит изолировать Keycloak и PostgreSQL, упростить их обновление и конфигурацию. Все версии актуальны для 2026 года.

1. Установка Docker

Установим Docker Engine на Ubuntu.

# Удаляем старые версии Docker, если есть
for pkg in docker.io docker-doc docker-compose docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; do sudo apt remove $pkg; done

# Устанавливаем необходимые пакеты
sudo apt install ca-certificates curl gnupg lsb-release -y

# Добавляем официальный GPG ключ 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 в APT
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

# Обновляем список пакетов и устанавливаем Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Добавляем текущего пользователя в группу docker для работы без sudo
sudo usermod -aG docker youruser

Выйдите из текущей SSH-сессии и войдите заново, чтобы изменения в группах вступили в силу. Проверьте установку Docker:

docker run hello-world

Если вы видите приветственное сообщение от Docker, установка прошла успешно.

2. Установка Caddy (обратный прокси и TLS)

Caddy — это мощный, простой в настройке веб-сервер, который автоматически получает и продлевает TLS-сертификаты с Let's Encrypt. Это значительно упрощает настройку HTTPS.

# Устанавливаем необходимые пакеты
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# Добавляем официальный GPG ключ Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Добавляем репозиторий Caddy в APT
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Обновляем список пакетов и устанавливаем Caddy
sudo apt update
sudo apt install caddy -y

# Проверяем статус Caddy
sudo systemctl status caddy

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

3. Создание Docker Compose файла для Keycloak и PostgreSQL

Создадим директорию для проекта Keycloak и файл docker-compose.yml.

mkdir keycloak-sso
cd keycloak-sso
nano docker-compose.yml

Вставьте следующее содержимое. Используем Keycloak 25.0.0 и PostgreSQL 17.

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:25.0.0 # Актуальная версия Keycloak
    container_name: keycloak
    environment:
      KEYCLOAK_ADMIN: admin # Имя администратора Keycloak
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD} # Пароль администратора (будет взят из .env)
      KC_DB: postgres # Используем PostgreSQL
      KC_DB_URL: jdbc:postgresql://db:5432/keycloak # URL базы данных
      KC_DB_USERNAME: keycloak # Пользователь БД
      KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD} # Пароль БД (будет взят из .env)
      KC_HOSTNAME: ${KEYCLOAK_HOSTNAME} # Доменное имя Keycloak (будет взято из .env)
      KC_PROXY: edge # Важно для работы через обратный прокси
      KC_HTTP_ENABLED: 'true' # Keycloak будет слушать HTTP для прокси
      KC_HTTP_PORT: 8080 # Порт, на котором Keycloak слушает HTTP
      KC_HEALTH_ENABLED: 'true' # Включаем Health Check
      KC_METRICS_ENABLED: 'true' # Включаем метрики
      JAVA_OPTS_APPEND: -Dquarkus.log.level=INFO -Dquarkus.log.category."org.keycloak".level=INFO # Настройки логирования
    ports:
      - "8080:8080" # Внутренний порт Keycloak, проксируется Caddy
    volumes:
      - ./keycloak-data:/opt/keycloak/data # Персистентное хранение данных Keycloak
    command: start --optimized --hostname-strict=false # Запуск Keycloak в оптимизированном режиме
    depends_on:
      db:
        condition: service_healthy
    restart: always

  db:
    image: postgres:17-alpine # Актуальная версия PostgreSQL
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak # Имя базы данных
      POSTGRES_USER: keycloak # Пользователь базы данных
      POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD} # Пароль базы данных (будет взят из .env)
    volumes:
      - ./postgres-data:/var/lib/postgresql/data # Персистентное хранение данных БД
    healthcheck: # Проверка работоспособности БД
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: always

Сохраните файл (Ctrl+O, Enter) и выйдите (Ctrl+X).

4. Создание файла .env

Для хранения секретных данных и доменного имени создадим файл .env.

nano .env

Вставьте следующее содержимое, заменив заполнители на ваши реальные значения:

KEYCLOAK_ADMIN_PASSWORD=YourStrongAdminPassword123! # Смените на сложный пароль
KEYCLOAK_DB_PASSWORD=YourStrongDBPassword456! # Смените на сложный пароль для БД
KEYCLOAK_HOSTNAME=auth.yourdomain.com # Замените на ваш домен для Keycloak (например, keycloak.example.com)

Важно: Убедитесь, что вы используете очень надежные пароли и что доменное имя auth.yourdomain.com (или любое другое, которое вы выбрали) уже указывает на IP-адрес вашего VPS в DNS-записях.

5. Запуск Keycloak и PostgreSQL

Теперь можно запустить контейнеры с помощью Docker Compose.

docker compose up -d

Эта команда запустит Keycloak и PostgreSQL в фоновом режиме. Docker Compose сначала создаст сети и тома, затем запустит контейнер PostgreSQL, дождется его готовности (healthcheck), а затем запустит Keycloak.

Проверьте статус контейнеров:

docker compose ps

Оба контейнера должны быть в состоянии "running".

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

После запуска контейнеров Keycloak и PostgreSQL, необходимо настроить обратный прокси Caddy для обеспечения HTTPS и корректной работы Keycloak с внешним доступом.

1. Настройка Caddy для Keycloak

Отредактируйте конфигурационный файл Caddy. По умолчанию он находится в /etc/caddy/Caddyfile.

sudo nano /etc/caddy/Caddyfile

Удалите все содержимое по умолчанию и вставьте следующее. Замените auth.yourdomain.com на ваш домен Keycloak.

auth.yourdomain.com {
    # Включить автоматическое HTTPS с Let's Encrypt
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN} # Если вы используете Cloudflare для DNS, укажите токен API
        # Если не используете Cloudflare DNS, просто оставьте tls
    }

    # Настройки для проксирования запросов к Keycloak
    reverse_proxy keycloak:8080 {
        # Передаем важные заголовки для корректной работы Keycloak за прокси
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
    }

    # Настройки для безопасности
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        # Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" # Настройте при необходимости
    }

    # Логирование
    log {
        output file /var/log/caddy/keycloak_access.log
        format json
    }
}

Примечание по tls: Если вы используете DNS-провайдера, отличного от Cloudflare, или не хотите использовать DNS-челлендж, вы можете просто оставить строку tls. Caddy попытается использовать HTTP-01 челлендж, который требует, чтобы порт 80 был доступен извне. Если вы используете Cloudflare, как в примере, то вам нужно будет создать файл /etc/caddy/Caddyfile.env:

sudo nano /etc/caddy/Caddyfile.env

И добавьте туда ваш Cloudflare API Token:

CLOUDFLARE_API_TOKEN=YOUR_CLOUDFLARE_API_TOKEN

Убедитесь, что этот токен имеет права на управление DNS-записями для вашего домена.

Сохраните файл(ы). Проверьте конфигурацию Caddy и перезапустите его:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Если валидация прошла успешно, Caddy перезапустится и попытается получить TLS-сертификат.

2. Проверка работоспособности

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

Проверка контейнеров

Убедитесь, что оба контейнера работают:

docker compose ps

Вывод должен показать State: Up для обоих сервисов.

Проверка доступности Keycloak через домен

Откройте в браузере адрес https://auth.yourdomain.com/admin (замените на ваш домен). Вы должны увидеть страницу входа в административную консоль Keycloak.

Введите логин admin и пароль, который вы указали в .env файле (KEYCLOAK_ADMIN_PASSWORD).

Проверка OpenID Connect конфигурации

Вы можете проверить, что Keycloak корректно отдает свою конфигурацию OpenID Connect:

curl -k https://auth.yourdomain.com/realms/master/.well-known/openid-configuration

Вы должны получить JSON-ответ с метаданными OpenID Connect для стандартного realm master.

Если все шаги выполнены правильно, Keycloak полностью установлен и сконфигурирован для работы с HTTPS и базой данных PostgreSQL.

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

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

1. Что бэкапить

• База данных PostgreSQL: Это самый важный компонент, так как он содержит всю информацию о пользователях, realm'ах, клиентах, ролях и сессиях Keycloak.
• Конфигурация Keycloak: В нашем случае с Docker Compose, основные настройки Keycloak заданы в docker-compose.yml и .env файлах. Однако, если вы делали какие-либо специфические изменения внутри контейнера (что не рекомендуется для Dockerized приложений), их тоже нужно бэкапить. Также полезно сохранять тома keycloak-data и postgres-data.
• Конфигурация Caddy: Файл /etc/caddy/Caddyfile и, возможно, /etc/caddy/Caddyfile.env.
• Логи: Для отладки и аудита. Хотя они не критичны для восстановления, они полезны.

2. Простой скрипт автобэкапа

Создадим простой bash-скрипт, который будет выполнять дамп базы данных и архивировать важные файлы.

Создайте директорию для бэкапов и сам скрипт:

sudo mkdir -p /var/backups/keycloak
sudo nano /usr/local/bin/keycloak_backup.sh

Вставьте следующее содержимое. Замените keycloak-sso на имя вашей директории с Docker Compose файлами, если оно отличается.

#!/bin/bash

# Путь к директории с Docker Compose файлами
DOCKER_COMPOSE_DIR="/home/youruser/keycloak-sso" # Укажите полный путь до вашей директории keycloak-sso
# Директория для хранения бэкапов
BACKUP_DIR="/var/backups/keycloak"
# Имя файла .env
ENV_FILE="${DOCKER_COMPOSE_DIR}/.env"

# Загружаем переменные окружения из .env
if [ -f "$ENV_FILE" ]; then
    export $(grep -v '^#' "$ENV_FILE" | xargs)
else
    echo "Ошибка: Файл .env не найден по пути $ENV_FILE"
    exit 1
fi

DATE=$(date +%Y%m%d%H%M%S)
BACKUP_FILENAME="${BACKUP_DIR}/keycloak_backup_${DATE}.tar.gz"
DB_DUMP_FILE="${BACKUP_DIR}/keycloak_db_dump_${DATE}.sql"

echo "Начинаем бэкап Keycloak..."

# 1. Бэкап базы данных PostgreSQL
echo "Создание дампа базы данных PostgreSQL..."
docker compose -f "${DOCKER_COMPOSE_DIR}/docker-compose.yml" exec -T db pg_dump -U keycloak -d keycloak > "$DB_DUMP_FILE"
if [ $? -eq 0 ]; then
    echo "Дамп БД успешно создан: $DB_DUMP_FILE"
else
    echo "Ошибка при создании дампа БД."
    exit 1
fi

# 2. Архивирование важных файлов и данных
echo "Архивирование конфигурационных файлов и данных..."
tar -czf "$BACKUP_FILENAME" \
    --absolute-names \
    "${DOCKER_COMPOSE_DIR}/docker-compose.yml" \
    "${DOCKER_COMPOSE_DIR}/.env" \
    "$DB_DUMP_FILE" \
    "/etc/caddy/Caddyfile" \
    "/etc/caddy/Caddyfile.env" \
    "${DOCKER_COMPOSE_DIR}/keycloak-data" \
    "${DOCKER_COMPOSE_DIR}/postgres-data" # Добавляем персистентные тома

if [ $? -eq 0 ]; then
    echo "Архив бэкапа успешно создан: $BACKUP_FILENAME"
else
    echo "Ошибка при создании архива бэкапа."
    exit 1
fi

# 3. Удаление временного дампа БД
rm "$DB_DUMP_FILE"

# 4. Удаление старых бэкапов (оставляем последние 7 дней)
echo "Удаление старых бэкапов (старше 7 дней)..."
find "$BACKUP_DIR" -type f -name "keycloak_backup_.tar.gz" -mtime +7 -delete

echo "Бэкап Keycloak завершен."

sudo chmod +x /usr/local/bin/keycloak_backup.sh

sudo crontab -e

0 3    /usr/local/bin/keycloak_backup.sh >> /var/log/keycloak_backup.log 2>&1

Эта строка будет запускать скрипт каждый день в 3:00 ночи, а вывод будет перенаправляться в файл логов /var/log/keycloak_backup.log.

4. Куда складывать бэкапы (внешнее хранилище)

Хранение бэкапов на том же сервере, что и основной сервис, является рискованным. В случае выхода из строя сервера вы потеряете и данные, и бэкапы. Рекомендуется использовать внешнее хранилище:

• Облачное хранилище объектов (S3-совместимое): Amazon S3, DigitalOcean Spaces, Backblaze B2. Это экономичное и надежное решение. Вы можете использовать утилиты вроде s3cmd или rclone для автоматической загрузки бэкапов.
• Отдельный VPS: Если у вас есть другой VPS, вы можете настроить rsync или scp для копирования бэкапов на него.
• Специализированные решения: BorgBackup или Restic для дедуплицированных, зашифрованных бэкапов.

Например, для загрузки в S3 с помощью rclone, вы бы добавили в скрипт строку после создания архива:

# rclone copy "$BACKUP_FILENAME" "remote_s3_storage:keycloak-backups/"

Предварительно настроив rclone с вашими S3-учетными данными.

5. Обновления: rolling vs maintenance window

• Обновление ОС и Docker: Регулярно обновляйте операционную систему и Docker. Для Ubuntu это sudo apt update && sudo apt upgrade -y. Делайте это в плановое время, так как иногда требуется перезагрузка сервера.
• Обновление Keycloak: Для Keycloak в Docker Compose, это сводится к изменению версии образа в docker-compose.yml (например, с 25.0.0 на 25.0.1) и последующему выполнению docker compose pull keycloak && docker compose up -d. Перед обновлением всегда читайте заметки к релизу, так как могут быть изменения в конфигурации или миграции БД.
• Обновление PostgreSQL: Обновление мажорных версий PostgreSQL (например, с 16 на 17) требует более сложной процедуры миграции данных. Это всегда должно выполняться в рамках запланированного "окна обслуживания" (maintenance window) с предварительным бэкапом. Минорные обновления (например, 17.0 на 17.1) обычно безопасны и не требуют миграции.

Для production-систем всегда рекомендуется иметь тестовую среду, где вы можете сначала проверить обновления, прежде чем применять их на основном сервере.

Troubleshooting + FAQ

В этом разделе мы рассмотрим типичные проблемы, которые могут возникнуть при установке и настройке Keycloak, а также ответим на часто задаваемые вопросы.

Keycloak не запускается / Ошибка подключения к БД

Проблема: Контейнер Keycloak постоянно перезапускается или выдает ошибки подключения к базе данных в логах. Что проверить:

1. Логи Keycloak: docker compose logs keycloak. Ищите сообщения об ошибках подключения к PostgreSQL.
2. Логи PostgreSQL: docker compose logs db. Убедитесь, что PostgreSQL успешно запущен и слушает соединения.
3. Переменные окружения: Проверьте правильность KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD в docker-compose.yml и .env. Убедитесь, что пароли совпадают.
4. Healthcheck PostgreSQL: Убедитесь, что healthcheck для контейнера db проходит успешно (docker compose ps). Keycloak не запустится, пока БД не будет готова.

Не могу получить доступ к админке Keycloak через домен

Проблема: При попытке открыть https://auth.yourdomain.com/admin браузер показывает ошибку "Connection refused" или "ERR_CONNECTION_CLOSED". Что проверить:

1. DNS-запись: Убедитесь, что ваш домен (например, auth.yourdomain.com) корректно указывает на IP-адрес вашего VPS. Используйте dig auth.yourdomain.com.
2. Файрвол (UFW): Проверьте, что порты 80 и 443 открыты: sudo ufw status.
3. Caddy: Проверьте статус Caddy: sudo systemctl status caddy. Убедитесь, что он запущен и нет ошибок в его логах: sudo journalctl -u caddy.
4. Конфигурация Caddyfile: Проверьте, что домен в Caddyfile совпадает с вашим, и что reverse_proxy правильно указывает на контейнер Keycloak (keycloak:8080).
5. Переменная KC_PROXY: Убедитесь, что в docker-compose.yml для Keycloak установлена переменная KC_PROXY: edge.

Проблемы с HTTPS / Caddy не получает сертификат

Проблема: Caddy не может получить TLS-сертификат от Let's Encrypt, и сайт доступен только по HTTP (или вообще недоступен). Что проверить:

1. Логи Caddy: sudo journalctl -u caddy --no-pager. Ищите ошибки, связанные с tls или Let's Encrypt.
2. Доступность порта 80/443: Убедитесь, что никакие другие сервисы не занимают порты 80 или 443. (sudo lsof -i :80, sudo lsof -i :443).
3. DNS-запись: Убедитесь, что ваш домен правильно указывает на ваш VPS. Let's Encrypt проверяет владение доменом.
4. Конфигурация DNS-челленджа (если используется): Если вы используете tls { dns ... }, проверьте, что переменная окружения с API-токеном корректно установлена и сам токен имеет нужные права.

Как сбросить пароль администратора Keycloak?

Проблема: Вы забыли пароль администратора Keycloak. Что проверить: Пароль администратора устанавливается переменной KEYCLOAK_ADMIN_PASSWORD в файле .env. Как фиксить:

1. Отредактируйте файл .env и измените значение KEYCLOAK_ADMIN_PASSWORD на новый, надежный пароль.
2. Перезапустите контейнер Keycloak, чтобы изменения вступили в силу: docker compose restart keycloak.
3. Теперь вы сможете войти в админ-консоль с новым паролем.

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

Минимально подходящий VPS-конфиг для установки Keycloak для небольшого проекта (до 500 активных пользователей) включает 2 vCPU, 4 GB оперативной памяти и 50 GB SSD-диска. Этого должно быть достаточно для запуска операционной системы, Keycloak и его базы данных PostgreSQL. Важно, чтобы диск был SSD для обеспечения достаточной производительности базы данных. При увеличении нагрузки или количества пользователей потребуется масштабирование ресурсов.

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

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

Как масштабировать Keycloak?

Проблема: Ваша инсталляция Keycloak испытывает высокую нагрузку, и производительности текущего VPS недостаточно. Что проверить: Мониторинг CPU, RAM, I/O диска на вашем VPS. Логи Keycloak на предмет задержек или ошибок. Как фиксить:

1. Вертикальное масштабирование (Scale Up): Увеличьте ресурсы вашего текущего VPS (CPU, RAM, Disk). Это самый простой первый шаг.
2. Горизонтальное масштабирование (Scale Out): Разверните несколько экземпляров Keycloak за балансировщиком нагрузки. Это требует настройки Keycloak в кластерном режиме (с общей базой данных и кэшем).
3. Оптимизация базы данных: Убедитесь, что PostgreSQL имеет достаточно ресурсов и настроен для оптимальной производительности.
4. Оптимизация Keycloak: Настройте параметры JVM, кэширования и логирования для лучшей производительности.

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

Поздравляем! Вы успешно установили и настроили Keycloak на своем VPS, создав надежную платформу для управления идентификацией и доступом с функцией единого входа. Теперь у вас есть централизованное решение для аутентификации, которое повышает безопасность и упрощает управление пользователями для ваших приложений.

Следующие шаги для дальнейшего развития вашей системы:

• Интеграция приложений: Подключите ваши веб-приложения, API или микросервисы к Keycloak, используя доступные адаптеры или стандартные протоколы OpenID Connect/OAuth 2.0.
• Расширенная настройка: Исследуйте дополнительные возможности Keycloak, такие как настройка тем оформления, добавление многофакторной аутентификации (MFA), федерация с внешними провайдерами идентификации (LDAP, Active Directory, социальные сети).
• Мониторинг и отказоустойчивость: Настройте систему мониторинга (например, Prometheus + Grafana) для отслеживания производительности Keycloak. Для высоконагруженных production-сред рассмотрите возможность кластеризации Keycloak для обеспечения высокой доступности.