РАЗБОР #06
Keycloak часто впервые запускают примерно так:
bin/kc.sh start-dev
Через минуту открывается Admin Console, создаётся realm, клиент — и возникает ощущение: осталось только оформить это как сервис. Но между:
Keycloak запустился
и:
Keycloak готов к production
довольно большое расстояние. Особенно если мы устанавливаем его непосредственно на виртуальную или физическую Linux-систему, без контейнерной обвязки. Здесь администратору самому нужно решить:
- — какой Java runtime использовать;
- — где размещать Keycloak;
- — от какого пользователя его запускать;
- — где хранить конфигурацию и secrets;
- — какую базу данных использовать;
- — какой URL будет видеть пользователь;
- — где завершается TLS;
- — нужен ли reverse proxy;
- — что публиковать наружу;
- — как запускать сервер через systemd;
- — как контролировать его состояние;
- — как обновлять и восстанавливать систему.
Поэтому нормальная установка начинается не со скачивания архива. А с архитектуры.
1. Сначала определяем роль Keycloak
Keycloak — это не просто веб-приложение с формой входа. В инфраструктуре он становится центральным компонентом аутентификации:
users ↓ applications ↓ Keycloak ↓ identity sources
Через него могут проходить:
- — OIDC;
- — OAuth 2.0;
- — SAML;
- — федерация с LDAP / Active Directory / FreeIPA;
- — внешние Identity Providers;
- — восстановление паролей;
- — MFA;
- — административный доступ.
Поэтому отказ Keycloak может означать: пользователи не могут войти сразу в несколько систем. Первый вопрос перед установкой: насколько критичным сервисом он станет? От ответа зависит всё остальное:
single instance? HA? external database? backup? monitoring? reverse proxy? network isolation?
2. start-dev — это не способ запуска production-сервера
Команда:
bin/kc.sh start-dev
специально предназначена для быстрого знакомства и разработки. Она использует удобные, но не production-ориентированные настройки. Например:
- — HTTP включён;
- — строгая проверка hostname отключена;
- — используется локальный cache;
- — некоторые механизмы кэширования шаблонов отключены.
То есть:
start-dev ≠ упрощённый production mode
Это другой режим работы. Для production используется:
bin/kc.sh start
И здесь Keycloak уже ожидает, что важные архитектурные решения приняты заранее.
3. Начинаем с Java
Keycloak работает на JVM. Для актуальной ветки Keycloak поддерживаются несколько LTS-версий OpenJDK, поэтому перед установкой нужно проверить совместимую матрицу именно для выбранной версии Keycloak. На момент подготовки материала актуальная ветка поддерживает:
OpenJDK 17 OpenJDK 21 OpenJDK 25
Причём для новых установок имеет смысл рассматривать последнюю поддерживаемую LTS-версию, если этому не мешают расширения или другие требования. Проверка:
java -version
Но здесь важно другое. Java становится частью эксплуатационного контура:
Linux ↓ JDK ↓ Keycloak
Значит, обновления JVM тоже нужно учитывать при сопровождении системы.
4. Продумайте структуру каталогов до распаковки
Конечно, можно просто сделать:
/home/admin/keycloak-26.x/
и запускать Keycloak оттуда. Для лаборатории — нормально. Для постоянного сервера лучше заранее определить структуру. Например:
/opt/keycloak/
для установленного приложения. Если хочется облегчить обновления, можно использовать версионные каталоги:
/opt/keycloak/ ├── keycloak-26.8.0/ └── current -> keycloak-26.8.0/
Тогда новая версия устанавливается рядом:
keycloak-26.8.0 keycloak-26.9.0
а не поверх существующей. Это упрощает:
- — сравнение конфигурации;
- — rollback;
- — автоматизацию обновления;
- — понимание того, какая версия реально запущена.