Настройка Spring Boot Starter

На этой странице показано, как подключить Axelix Spring Boot Starter к сервису на Spring Boot, чтобы Axelix Master мог обнаруживать его, считывать его состояние и взаимодействовать с ним — как через пользовательский интерфейс, так и через встроенный в Master сервер MCP (Model Context Protocol), который предоставляет те же данные агентам искусственного интеллекта. Выберите модуль стартера, соответствующий мажорной версии Boot, предоставьте доступ к Axelix actuator-эндпоинтам (начиная с Axelix 1.2.0 это происходит автоматически), поделитесь с Master ключом для подписи JWT и укажите Master, где найти сервис.

Прежде чем вы начнёте

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

• Три модуля стартера, по одному для каждой мажорной версии Spring Boot. Выберите тот, который соответствует версии Boot, которую уже использует ваш сервис:
  • com.axelixlabs:axelix-spring-boot-2-starter — Spring Boot 2.x (собран и протестирован с использованием 2.7.18, Spring Cloud 2021.0.9, минимальная версия JDK 11).
  • com.axelixlabs:axelix-spring-boot-3-starter — Spring Boot 3.x (собран и протестирован с использованием 3.0.13, Spring Cloud 2022.0.4, минимальная версия JDK 17).
  • com.axelixlabs:axelix-spring-boot-4-starter — Spring Boot 4.x (собран и протестирован с использованием 4.0.6, Spring Cloud 2025.1.0, минимальная версия JDK 17).
• Что добавляет стартер: набор Axelix-специфичных actuator-эндпоинтов (axelix-metadata, axelix-beans, axelix-loggers, …), JWT-фильтр авторизации, который ограничивает доступ к ним, и опциональный компонент саморегистрации, который объявляет сервис в Master.
• Плагин сборки Axelix также обязателен: помимо зависимости стартера, подключите Gradle- или Maven-плагин сборки Axelix. Он записывает координаты сборки (groupId/artifactId/version) в артефакт, а Master идентифицирует каждое приложение именно по этим координатам — сервис, собранный без плагина, не сможет зарегистрироваться. См. Что такое плагин сборки Axelix? и Настройка плагина сборки.
• Два потребителя одних и тех же данных: Master отдаёт пользовательский интерфейс Axelix по адресу / и сервер MCP по адресу /api/mcp (управляется axelix.master.mcp-server.enabled, по умолчанию включён). Оба считывают данные с тех же actuator-эндпоинтов, которые публикует стартер, — поэтому подключение стартера делает сервис видимым и для пользователей UI, и для MCP-клиентов без дополнительной настройки на стороне стартера.
• Что нужно Master для взаимодействия с сервисом: HTTP-доступность к базовому пути актуатора сервиса (по умолчанию /actuator), Axelix-эндпоинты, открытые через management.endpoints.web.exposure.include, и ключ для подписи JWT, идентичный тому, который настроен на Master — см. Аутентификация — JWT на стороне Master.
• Master может найти сервис двумя способами:
  • Автоматическое обнаружение на стороне Master — Master сканирует свою среду (в настоящее время — Kubernetes Services) и проверяет actuator-эндпоинт каждого из них. Стартеру нужно только предоставить доступ к эндпоинтам, ничего дополнительно настраивать не нужно.
  • Самостоятельная регистрация — стартер отправляет в Master heartbeat через фиксированный интервал. Используйте этот метод, если Master не может просканировать среду сервиса (другая сеть, отсутствие интеграции с платформой, обычные виртуальные машины).

Добавьте зависимость

Укажите координату стартера, соответствующую мажорной версии Boot.

dependencies {
    implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.0.0")
}

Стартер также зависит от Spring Boot Actuator. Если в вашем сервисе ещё нет spring-boot-starter-actuator, добавьте его рядом.

Actuator-эндпоинты

Начиная с Axelix 1.2.0 ничего настраивать вручную не нужно: стартер сам добавляет свои actuator-эндпоинты в management.endpoints.web.exposure.include при старте приложения, поэтому Master получает к ним доступ «из коробки». На более старых версиях стартер этого не делает, и эндпоинты нужно перечислить вручную — см. Открытие эндпоинтов на Axelix ниже 1.2.0.

Что открывает стартер

Стартер выставляет следующие эндпоинты:

Эндпоинты, неприменимые к вашему сервису, остаются неактивными — стартер активирует каждый только при выполнении его предусловий (например, axelix-feign без Feign в classpath или axelix-caches без CacheManager не поднимаются).

Начиная с Axelix 1.2.0 стандартные эндпоинты health и info больше не требуются, поэтому стартер сам их не открывает (до 1.2.0 Axelix зависел от них, и стартер принудительно открывал оба). Открытыми будут только эндпоинты, перечисленные вами в management.endpoints.web.exposure.include, плюс эндпоинты Axelix — добавьте health и info в список сами, когда они вам нужны, в том числе health, который Spring Boot иначе открыл бы по умолчанию.

Добавление собственных эндпоинтов

Если вам нужны свои actuator-эндпоинты, просто перечислите только их — стартер смёржит ваш список со своим, а не заменит его.

management:
  endpoints:
    web:
      exposure:
        include:
          - prometheus

В результате будет выставлен prometheus и все эндпоинты Axelix.

Значение * тоже поддерживается — тогда открывается всё, и стартер список не трогает.

Открытие эндпоинтов на Axelix ниже 1.2.0

Стартеры старше 1.2.0 не добавляют свои эндпоинты в список открытых самостоятельно, поэтому каждый эндпоинт Axelix, который должен читать Master, нужно перечислить в management.endpoints.web.exposure.include вручную. Как минимум откройте axelix-metadata — без него инстанс никогда не появится в Master, — а на практике весь набор, чтобы у каждого раздела UI были данные. Эндпоинты health и info эти версии стартера открывают принудительно сами, так что их перечислять не нужно:

management:
  endpoints:
    web:
      exposure:
        include:
          - axelix-metadata
          - axelix-beans
          - axelix-caches
          - axelix-conditions
          - axelix-configprops
          - axelix-details
          - axelix-env
          - axelix-feign
          - axelix-gc
          - axelix-heap-dump
          - axelix-loggers
          - axelix-metrics
          - axelix-scheduled-tasks
          - axelix-thread-dump

Экспорт метрик Axelix через Micrometer

Actuator-эндпоинт axelix-metrics нужен для пользовательского интерфейса Axelix. Кроме того, Axelix Spring Boot Starter может публиковать небольшой набор Axelix-специфичных метрик в MeterRegistry вашего приложения.

Этот путь экспорта включается автоматически, когда в приложении есть бин MeterRegistry. Отдельного свойства Axelix для включения данного функционала нет. Стартер регистрирует такие метрики:

Эти метрики дополняют UI-ориентированные actuator-эндпоинты, а не заменяют их. Пользовательский интерфейс по-прежнему читает axelix-metrics, axelix-caches и axelix-transactions-monitoring.

Поделитесь JWT-ключом подписи с Master

Каждый Axelix actuator-эндпоинт контролируется JwtAuthorizationFilter. Фильтр ожидает токен HS256, HS384 или HS512, подписанный тем же ключом, который использует Master, поэтому обе стороны должны согласовать алгоритм и секретный ключ. Используйте то же значение, которое вы указали для axelix.master.auth.jwt.signing-key на Master.

axelix:
  sbs:
    auth:
      jwt:
        algorithm: HMAC512
        signing-key: ${AXELIX_JWT_SIGNING_KEY}
        duration: 5m

algorithm и signing-key обязательны — старт сервиса упадёт с понятным сообщением, если любого из них не хватает. duration определяет, как долго действителен выпущенный стартером токен для heartbeat-сигналов саморегистрации, по умолчанию он равен пяти минутам, после чего стартер автоматически его ротирует.

Дайте Master найти сервис

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

Вариант A — автоматическое обнаружение на стороне Master

Если Master работает в кластере Kubernetes вместе с вашими сервисами, проще всего настроить его так, чтобы он сканировал namespace в поисках Services и опрашивал /actuator/axelix-metadata каждого из них. На стороне стартера не требуется никакой дополнительной настройки, помимо открытия actuator-эндпоинтов и общего JWT-ключа подписи. Настройте сканирование на стороне Master через axelix.master.discovery.auto.* — см. Обнаружение — автообнаружение на странице Master.

Вариант B — Саморегистрация

Если Master не может просканировать среду сервиса — другой кластер, обычная виртуальная машина, изолированная сеть — включите саморегистрацию в стартере. Сервис тогда отправляет в Master heartbeat со своим actuator URL через фиксированный интервал. Master принимает запрос по адресу POST /api/internal/service/register — это же значение указывается в axelix.sbs.discovery.master-url.

axelix:
  sbs:
    discovery:
      self-registration: true
      master-url: http://master.internal:8080/api/internal/service/register
      instance-actuator-url: http://my-app.internal:8080/actuator
      instance-name: orders-service
      heartbeat-interval: 15s

Несколько деталей, на которых люди спотыкаются:

• instance-actuator-url — это базовый URL-адрес сервиса, поскольку Master будет обращаться к нему из своей собственной сети — только по имени хоста и порту.
• master-url — это полный URL-адрес, включая /api/internal/service/register. Стартер отправляет его без изменений.
• instance-name — это имя, которое Master показывает для этого сервиса в пользовательском интерфейсе и в MCP-ответах. Выбирайте имя, которое переживает рестарты и реплики, — как правило, имя сервиса, а не имя пода.
• Саморегистрация принимается Master из коробки (axelix.master.discovery.self-registration.enabled по умолчанию true), установите её в false, если хотите отказаться от heartbeat-сигналов. Master выселяет сервис после axelix.master.discovery.self-registration.eviction.heartbeat-timeout молчания (по умолчанию 45s), поэтому держите heartbeat-interval с запасом меньше этого значения.

Маскирование чувствительных значений свойств

Эндпоинты Axelix axelix-env и axelix-configprops возвращают значения свойств в Master. Чтобы секреты не утекали при обычных просмотрах, стартер маскирует значения, которые он возвращает вызывающим без соответствующего полномочия. Механизм одинаков для обоих эндпоинтов и управляется одним свойством стартера:

axelix.sbs.endpoints.config.sanitized-properties

• Пустой список (по умолчанию) — каждое значение, возвращаемое axelix-env и axelix-configprops, заменяется на ****** для вызывающих без соответствующего полномочия. По умолчанию выбран намеренно консервативный вариант: чтобы быть в безопасности, ничего включать не нужно.
• Непустой список — маскируются только перечисленные ключи, всё остальное возвращается вызывающему без изменений. Используйте этот режим, если консервативное поведение по умолчанию слишком агрессивное и вы хотите маскировать только конкретные ключи (пароли, токены, ключи подписи).

Полномочие проверяется по каждому эндпоинту отдельно:

• axelix-env — полномочие ENV_VALUES_READ позволяет вызывающему видеть исходные значения.
• axelix-configprops — полномочие CONFIG_PROPS_VALUES_READ позволяет вызывающему видеть исходные значения.

Оба полномочия выдаются встроенными в Master ролями ADMIN и SUPER_ADMIN. VIEWER и EDITOR всегда проходят через функцию маскирования. Полную матрицу см. в Роли и полномочия.

axelix:
  sbs:
    endpoints:
      config:
        sanitized-properties:
          - database.password
          - spring.datasource.password
          - jwt.signing-key

Справочник по конфигурации

Все свойства стартера живут в пространстве имён axelix.sbs.*.

Отключение стартера

axelix.sbs.enabled — глобальный переключатель всего стартера. По умолчанию он равен true, то есть достаточно добавить зависимость, чтобы активировать всё описанное на этой странице. Установите его в false — и каждая автоконфигурация Axelix отключится: не будет ни Axelix actuator-эндпоинтов, ни фильтра JWT-авторизации, ни heartbeat-сигналов саморегистрации, ни метрик Micrometer, ни мониторинга транзакций. Приложение запустится так, как будто стартера нет в classpath, при этом сама зависимость остаётся в сборке.

Этот переключатель пригодится, когда нужно выключить Axelix в конкретном окружении — например, локально или в тестовом профиле — не поддерживая отдельный набор зависимостей. Кроме того, это быстрый способ исключить стартер из подозреваемых при диагностике проблем на старте приложения.

axelix:
  sbs:
    enabled: false

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

Аутентификация — JWT

Саморегистрация

Саморегистрация выключена по умолчанию (axelix.sbs.discovery.self-registration=false) — оставьте всё как есть, если Master может найти сервис через автообнаружение на стороне Master.

Когда axelix.sbs.discovery.self-registration=true, следующие свойства становятся обязательными:

• axelix.sbs.discovery.master-url
• axelix.sbs.discovery.instance-actuator-url
• axelix.sbs.discovery.instance-name

Приёмник этих heartbeat-сигналов на стороне Master — эндпоинт, таймаут выселения, расписание подметания выселений — описан на странице Master в Обнаружение — саморегистрация. JWT-ключ подписи, заданный в axelix.sbs.auth.jwt.signing-key, должен совпадать с axelix.master.auth.jwt.signing-key на Master, иначе heartbeat-сигналы будут отклоняться с 401.

Маскирование значений в эндпоинтах

Мониторинг транзакций

Мониторинг транзакций — это то, что обеспечивает работу страницы «Мониторинг транзакций» и связанных метрик. Под капотом стартер оборачивает ваши @Transactional методы (путем обычного проксирования) с целью сбора различного рода инсайтов, случившихся в транзакции. Собранные инсайты передаются в Master внутри метаданных регистрации сервиса (которые отправляются либо в момент heartbeat в случае саморегистрации, либо сканируются Master-ом в момент автоматического обнаружения), поэтому отдельный actuator-эндпоинт для этого не требуется.

Эта функция включена по умолчанию, как только стартер оказывается в classpath.

Несмотря на то, что overhead от этого проксирования крайне небольшой, если вдруг вы захотите отключить этот функционал - это можно сделать. Установите значение свойства axelix.sbs.transaction.monitoring.enabled в false, чтобы полностью её отключить — без bean post-processor'ов, без проксирования источника данных, без фильтра очистки и без интегратора Hibernate.

axelix:
  sbs:
    transaction:
      monitoring:
        enabled: false

Обнаружение in-memory pagination

Обнаруживает случаи применения in-memory pagination, выполняемые Hibernate при использовании методов setFirstResult/setMaxResults совместно с выборкой коллекций через fetch.

По умолчанию мониторинг транзакций регистрирует appender, который перехватывает предупреждения Hibernate (HHH000104 в Hibernate 5.x и HHH90003004 в Hibernate 6.x–7.3.x). Стартер выбирает appender в соответствии с активной системой логирования приложения, поэтому обнаружение работает как на Logback, так и на Log4j2:

• Logback — стартер регистрирует com.axelixlabs.axelix.sbs.spring.core.persistence.hibernate.pagination.LogbackInMemoryPaginationAppender. Так происходит в стандартной конфигурации Spring Boot, где системой логирования является Logback.
• Log4j2 — если приложение использует Log4j2 (обычно после добавления spring-boot-starter-log4j2 и исключения стандартного стартера Logback), стартер регистрирует com.axelixlabs.axelix.sbs.spring.core.persistence.hibernate.pagination.Log4j2InMemoryPaginationAppender.

Выбирать между ними не нужно — стартер сам определяет активную систему логирования и регистрирует подходящий appender.

Установите значение свойства axelix.sbs.transaction.monitoring.in-memory-pagination-detection.enabled в false, если хотите отключить регистрацию любого из этих appender-ов.

axelix:
  sbs:
    transaction:
      monitoring:
        in-memory-pagination-detection:
          enabled: false

См. также

• Настройка плагина сборки — вторая половина подключения сервиса; обязательна для регистрации сервиса.
• Настройка Master — где задаются ключ подписи, таймаут выселения и сканирование Kubernetes.
• Что такое Master? — фон того, как Master использует данные, которые публикует стартер.
• Аутентификация — углублённый взгляд на JWT и резолюцию полномочий с обеих сторон.