Часто встречающиеся проблемы

На этой странице описаны наиболее часто встречающиеся проблемы, возникающие при установке и настройке Axelix.

1. Ошибка аутентификации (401) при обращении к эндпоинтам Axelix

Симптом

На стороне Master при обращении к управляемому сервису возникает ошибка 401, несмотря на то, что на стороне управляемого сервиса открыт доступ к эндпоинтам Axelix в application.yaml и корректно сконфигурирован Spring Security.

Наиболее вероятная причина

На практике actuator-эндпоинты управляемого сервиса (микросервиса, который включает в себя Axelix Spring Boot Starter и плагин) почти никогда не остаются открытыми. Очень часто — и, как правило, это рекомендуемая практика — их защищают тем или иным механизмом аутентификации: HTTP Basic, OIDC/OAuth2 resource server или любой другой схемой, настроенной в конфигурации Spring Security приложения.

В то же время Axelix поставляется с собственной системой управления доступом (IAM). При обращении Master к управляемому сервису он вызывает кастомные actuator-эндпоинты Axelix (те, что начинаются с /actuator/axelix-**, но учтите, что префикс actuator может отличаться — он настраиваемый) и передаёт в заголовке Authorization собственный bearer-токен, выпущенный Axelix. Этот токен предназначен для компонентов Axelix на стороне управляемого сервиса, а не для его собственного стека безопасности.

Кастомный префикс actuator

Часть /actuator — это базовый путь actuator, который настраивается через management.endpoints.web.base-path (по умолчанию /actuator). Если ваш управляемый сервис переопределяет это свойство, эндпоинты Axelix будут доступны по настроенному базовому пути — например, при базовом пути /manage они доступны по /manage/axelix-**. Учитывайте это для request matcher в решении ниже.

Ошибка 401 возникает именно из-за столкновения этих двух независимых систем аутентификации: фильтр безопасности управляемого сервиса перехватывает запрос ещё до того, как он достигнет компонентов Axelix, видит bearer-токен и пытается провалидировать его на собственном IAM управляемого сервиса, где токен Axelix неизвестен и потому отклоняется.

Решение

Решение состоит в том, чтобы исключить кастомные actuator-эндпоинты Axelix (т. е. те, что имеют префикс /actuator/axelix-**, снова с учётом возможности настроить кастомный префикс для actuator-эндпоинтов) из IAM приложения и довериться IAM в Axelix:

@Bean
public WebSecurityCustomizer webSecurityCustomizer() {
  return (web) -> web.ignoring().requestMatchers("/actuator/axelix-**");
}

2. Не тот модуль стартера для вашей версии Spring Boot

Симптом

Приложение падает при старте сразу после добавления зависимости Axelix Spring Boot Starter с ошибкой NoClassDefFoundError или ClassNotFoundException, указывающей на класс javax.servlet.* или jakarta.servlet.* - например, javax/servlet/FilterChain в проекте на Spring Boot 4.x, или jakarta/servlet/FilterChain в проекте на Spring Boot 2.x.

Наиболее вероятная причина

Axelix предоставляет отдельный артефакт стартера под каждую мажорную версию Spring Boot:

axelix-spring-boot-2-starter для Spring Boot 2
axelix-spring-boot-3-starter для Spring Boot 3
axelix-spring-boot-4-starter для Spring Boot 4

Это разные Maven-артефакты, поставляемые отдельно (хотя все они следуют одной схеме версионирования). Поэтому при добавлении Spring Boot стартера нужно убедиться, что вы добавляете стартер под соответствующую мажорную версию Spring Boot.

Решение

Подберите стартер под мажорную версию Spring Boot вашего приложения - см. Отдельный стартер под каждую мажорную версию Spring Boot и точные координаты в разделе Настройка Spring Boot Starter.

3. Локально запущенный сервис не регистрируется в локально запущенном Master

Симптом

Вы запускаете Axelix Master локально, добавляете стартер в своё приложение и запускаете его из IDE. Приложение стартует без ошибок, но так и не появляется в Master - ни ошибки на одной из сторон, ни записи в сайдбаре.

Наиболее вероятная причина

Не выполненено предварительное условие, кнопка "Run" в IDE по умолчанию просто компилирует код и запускает главный класс.

Build-плагин не отработал. У Axelix есть build-плагины для Maven и Gradle. Эти плагины генерируют META-INF/axelix-info.properties (который содержит groupId/artifactId/ version сервиса) в результат сборки, и этот файл нужен стартеру, чтобы идентифицировать сервис перед Master.

Например, в случае Maven цель, которая выполняет эту работу (т. е. axelix-generate-project-info), привязана к фазе prepare-package - обычный "скомпилировать и запустить" в IDE до неё не доходит. Gradle-таск специально привязан к processResources, чтобы запуски из IDE тоже его подхватывали, но это срабатывает только если IDE реально вызывает этот таск, а для этого нужно делегировать запуск/сборку на Gradle, а не использовать собственный инкрементальный компилятор IDE.

Master не может найти инстанс сам. Автообнаружению Master на основе Kubernetes локально попросту нечего сканировать, поэтому сервис должен саморегистрироваться.

Решение

Хотя бы раз выполните сборку перед тем, как полагаться на кнопку Run в IDE - mvn package (или mvn install), либо ./gradlew build. См. Что такое build-плагин Axelix? - что именно генерирует плагин и почему он обязателен.

Дальше направьте стартер на ваш локальный Master через механизм саморегистрации и пропишите JWT-ключ подписи с обеих сторон - одно и то же значение должно быть на Master и на каждом инстансе, поскольку это симметричный HMAC-алгоритм:

server.port=9444
axelix.sbs.auth.jwt.algorithm=HMAC256
axelix.sbs.auth.jwt.signing-key=8DrZJSOJ8vkbxdjUB3sSsyeiG4Xidf1sDNmJq1Slkkn
axelix.sbs.discovery.self-registration=true
axelix.sbs.discovery.instance-name=your-application-name
axelix.sbs.discovery.instance-actuator-url=http://localhost:9444/actuator
axelix.sbs.discovery.master-url=http://localhost:8080/api/internal/service/register

На версиях Axelix ниже 1.2.0 (не включительно) нужно ещё одно свойство — старые стартеры не открывают свои эндпоинты самостоятельно, а без axelix-metadata Master не сможет опросить инстанс:

management.endpoints.web.exposure.include=axelix-metadata

Наконец, запустите сам Master как JAR с тем же алгоритмом и ключом подписи:

java \
  -Daxelix.master.auth.jwt.algorithm=HMAC256 \
  -Daxelix.master.auth.jwt.signing-key=8DrZJSOJ8vkbxdjUB3sSsyeiG4Xidf1sDNmJq1Slkkn \
  -jar master.jar

При несовпадении ключа heartbeat отклоняется с 401 вместо регистрации. Полный справочник по саморегистрации - в разделе Настройка Spring Boot Starter, а про сторону Master - в разделе Запуск как JAR.

Никогда не используйте ключ подписи выше, как и любой другой пример-ключ с этой страницы, в реальном развёртывании.

4. Некоторые разделы сайдбара остаются пустыми после регистрации

Если вы используете Axelix 1.2.0 или новее, ничего из этого не требуется: стартер сам регистрирует свои actuator-эндпоинты, а эндпоинты health/info Axelix больше не требуются — он отлично работает и без них. Никакая настройка здесь не нужна.

Симптом

Инстанс появляется в Master, и его статус выглядит здоровым, но некоторые разделы сайдбара - Beans, Caches, Loggers и подобные - остаются пустыми или не загружаются.

раздел сайдбара падает с неожиданной серверной ошибкой Выбран раздел сайдбара (Details), но вместо данных показывается "No data" и тост "Unexpected server error"

Наиболее вероятная причина

Spring Boot по умолчанию скрывает кастомные actuator-эндпоинты от веб-доступа, а каждый раздел UI Axelix читает свой собственный выделенный эндпоинт (axelix-beans, axelix-caches, axelix-loggers и так далее). Обязателен только axelix-metadata - чтобы инстанс вообще появился в Master, а все остальные эндпоинты опциональны, поэтому у раздела без соответствующего эндпоинта в management.endpoints.web.exposure.include просто нет источника данных.

Решение

Добавьте недостающие ID эндпоинтов в management.endpoints.web.exposure.include на стороне управляемого сервиса - полный список см. в разделе Что открывает стартер.