Sorun giderme
Bu sayfa, Axelix kurulumu ve yapılandırması sırasında en sık karşılaşılan sorunları açıklar.
1. Axelix uç noktalarına erişirken kimlik doğrulama hatası (401)
Belirti
Yönetilen servis tarafında application.yaml içinde Axelix uç noktalarına erişim etkinleştirilmiş ve Spring Security doğru
yapılandırılmış olsa da Master tarafında yönetilen servisle iletişim kurulurken 401 hatası döner.
En olası neden
Uygulamada, yönetilen servisin (Axelix Spring Boot Starter ve eklenti içeren mikroservisin) sunduğu actuator uç noktaları neredeyse hiçbir zaman herkese açık bırakılmaz. Bunları HTTP Basic, OIDC/OAuth2 kaynak sunucusu veya uygulamanın Spring Security yapılandırmasına bağlı başka bir kimlik doğrulama yöntemiyle korumak çok yaygındır ve genellikle önerilir.
Axelix aynı zamanda kendi Kimlik ve Erişim Yönetimi (IAM) sistemiyle gelir. Master, 1.3 ve üzeri starter çağırırken özel Axelix
actuator uç noktalarını (genellikle yapılandırılabilir actuator ön ekiyle /actuator/axelix-*/**), Authorization başlığında
AXELIX.MASTER teknik bearer belirteciyle çağırır. 1.3'ten eski starter'lar için kullanıcının belirtecini eski yetki adlarıyla
yeniden düzenler. İlk keşif, Master'ı tanımlayan bir uyumluluk belirteci kullanır. Her durumda belirteç, uygulamanın kendi
güvenlik sistemine değil Axelix bileşenlerine yöneliktir.
Özel actuator ön eki
/actuator bölümü actuator temel yoludur; management.endpoints.web.base-path ile yapılandırılabilir (varsayılanı
/actuator). Yönetilen servisiniz bu özelliği değiştirirse Axelix uç noktaları yapılandırılan temel yol altında bulunur;
örneğin /manage temel yolu, uç noktaların /manage/axelix-*/** adresinden erişilebileceği anlamına gelir.
Aşağıdaki çözümün istek eşleştiricisinde bunu dikkate alın.
401, bu iki bağımsız kimlik doğrulama sisteminin çakışmasından kaynaklanır: yönetilen servisin güvenlik filtresi, istek Axelix bileşenlerine ulaşmadan önce araya girer, bearer belirtecini görür ve yönetilen servisin kendi IAM sistemiyle doğrulamaya çalışır. Axelix belirteci bu sistemde bilinmediğinden reddedilir.
Çözüm:
Çözüm, özel Axelix actuator uç noktalarını (yine actuator uç noktalarının özel ön ekini yapılandırma olasılığı dikkate
alınarak /actuator/axelix-*/** yoluyla eşleşenleri) uygulama IAM sisteminden hariç tutmak ve Axelix'in kendi IAM sistemine güvenmektir:
Bu kalıp hem uç nokta köklerini hem de önbellek temizleme gibi iç içe yolları kapsar.
@Bean
public WebSecurityCustomizer webSecurityCustomizer() {
return (web) -> web.ignoring().requestMatchers("/actuator/axelix-*/**");
}2. Spring Boot sürümünüz için yanlış starter modülü
Belirti
Axelix Spring Boot Starter bağımlılığını ekledikten hemen sonra uygulama, bir javax.servlet.* veya jakarta.servlet.*
sınıfını belirten NoClassDefFoundError ya da ClassNotFoundException ile başlayamaz. Örneğin Spring Boot 4.x projesinde
javax/servlet/FilterChain veya Spring Boot 2.x projesinde jakarta/servlet/FilterChain.
En olası neden
Axelix her Spring Boot ana sürümü için ayrı bir starter artifact'ı sunar:
- Spring Boot 2.7+ için
axelix-spring-boot-2-starter - Spring Boot 3 için
axelix-spring-boot-3-starter - Spring Boot 4 için
axelix-spring-boot-4-starter
Bunlar ayrı yayımlanan farklı Maven artifact'larıdır (tümü aynı sürümlendirme düzenini izlese de). Bu nedenle Spring Boot starter eklerken Spring Boot'un uygun ana sürümüne ait starter'ı eklediğinizden emin olmalısınız.
Çözüm:
Starter'ı uygulamanızın Spring Boot ana sürümüyle eşleştirin. Her Spring Boot ana sürümü için ayrı starter bölümüne ve tam koordinatlar için Spring Boot Starter yapılandırmasına bakın.
3. Yerelde başlatılan servis yerelde başlatılan Master'a kaydolmuyor
Belirti
Axelix Master'ı yerelde çalıştırır, kendi servisinize starter ekler ve servisi IDE'den başlatırsınız. Hatasız başlar, ancak Master'da hiç görünmez; iki tarafta da hata yoktur ve kenar çubuğunda kayıt bulunmaz.
En olası neden
İki ön koşul eksiktir. IDE'nin varsayılan “Run” düğmesi yalnızca ana sınıfı derleyip başlatıyorsa ikisini de atlamak kolaydır.
Derleme eklentisi hiç çalışmamıştır. Axelix'in Maven ve Gradle için derleme eklentileri vardır.
Bunlar derleme çıktısına, servisin groupId/artifactId/version bilgilerini içeren META-INF/axelix-info.properties
dosyasını ekler. Starter'ın servisi Master'a tanıtmak için bu dosyaya ihtiyacı vardır.
Maven'da bu işi yapan hedef (axelix-generate-project-info), prepare-package aşamasına bağlıdır; IDE'deki sıradan
“derle ve çalıştır” işlemi bu aşamaya ulaşmaz. Gradle görevi, IDE çalıştırmalarına da dahil olması için özellikle
processResources'a bağlanmıştır. Ancak bu yalnızca IDE gerçekten bu görevi çağırıyorsa gerçekleşir; bunun için IDE'nin
kendi artımlı derleyicisi yerine derleme/çalıştırma eylemlerini Gradle'a devretmek gerekir.
Master örneği kendi başına bulamaz. Master'ın Kubernetes tabanlı otomatik keşfinin yerel makinede tarayacağı bir şey yoktur; bu nedenle servis kendiliğinden kaydolmalıdır.
Çözüm:
IDE'nin Run düğmesine güvenmeden önce en az bir kez gerçek derleme çalıştırın: mvn package (veya mvn install) ya da
./gradlew build. Eklentinin ürettikleri ve neden gerekli olduğu için
Axelix derleme eklentisi nedir? sayfasına bakın.
Ardından starter'ı kendiliğinden kayıtla yerel Master'ınıza yönlendirin ve iki tarafta JWT imzalama anahtarını eşleştirin. Simetrik HMAC algoritması kullanıldığından Master'da ve her örnekte aynı değer olmalıdır:
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:2935/api/internal/service/register2935, Axelix 1.2.0 itibarıyla Master'ın varsayılan portudur. Önceki sürümlerde varsayılan 8080 olduğundan Master'ınız
daha eskiyse master-url içinde 8080 kullanın; Genel bölümüne bakın.
1.2.0'dan eski Axelix sürümlerinde bir özellik daha gerekir: eski starter'lar uç noktalarını kendileri sunmaz ve
axelix-metadata olmadan Master örneği yoklayamaz:
management.endpoints.web.exposure.include=axelix-metadataSon olarak Master'ı aynı algoritma ve imzalama anahtarıyla JAR olarak başlatın:
java \
-Daxelix.master.auth.jwt.algorithm=HMAC256 \
-Daxelix.master.auth.jwt.signing-key=8DrZJSOJ8vkbxdjUB3sSsyeiG4Xidf1sDNmJq1Slkkn \
-jar axelix-1.3.1.jarAnahtar uyuşmazlığı, yaşam sinyalini kaydetmek yerine 401 ile reddeder.
Tam kendiliğinden kayıt başvurusu için Spring Boot Starter yapılandırmasına,
Master tarafı için JAR olarak çalıştırma bölümüne bakın.
Yukarıdaki imzalama anahtarını veya bu sayfadaki herhangi bir örnek anahtarı gerçek dağıtımda asla kullanmayın.
4. Kayıttan sonra bazı kenar çubuğu bölümleri boş kalıyor
Axelix 1.2.0 veya üzerindeyseniz bunların hiçbiri gerekmez: starter özel actuator uç noktalarını kendisi kaydeder ve Axelix artık health/info uç noktalarının etkin olmasını gerektirmez; bunlar olmadan da sorunsuz çalışır. Burada yapılandırma gerekmez.
Belirti
Örnek Master'da görünür ve sağlıklı durumdadır, ancak Beans, Caches, Loggers gibi bazı kenar çubuğu bölümleri boş kalır veya yüklenemez.
Seçili kenar çubuğu bölümü (Details), gerçek veriler yerine “No data” ve “Unexpected server error” bildirimi gösteriyor
En olası neden
Spring Boot varsayılan olarak özel actuator uç noktalarını web erişimine açmaz. Her Axelix arayüz bölümü kendi özel uç
noktasını okur (axelix-beans, axelix-caches, axelix-loggers vb.). Örneğin Master'da görünmesi için yalnızca
axelix-metadata gerekir; diğer tüm uç noktalar isteğe bağlıdır. Dolayısıyla management.endpoints.web.exposure.include
içinde eşleşen uç noktası olmayan bir bölümün okuyabileceği kaynak yoktur.
Çözüm:
Yönetilen serviste eksik uç nokta kimliklerini management.endpoints.web.exposure.include içine ekleyin.
Tam liste için Starter'ın sundukları bölümüne bakın.