Başlarken
Bu sayfa Axelix'i bir kuruluşta kullanıma almanın önerilen yolunu açıklar: hangi ortamlardan başlanacağı, bileşenlerin hangi sırayla kurulacağı ve üretime nasıl güvenle geçileceği. Her adım somut komutlar, minimum yapılandırma ve tam başvuru için ayrıntılı yapılandırma sayfasına bağlantılar sunar.
Bu sayfadaki örnekler gösterim amacıyla 1.3.1 sürümünü sabitler.
En son yayımlanan etiket için Sürümler sayfasını kontrol edin ve kendi
komutlarınızda bu değeri kullanın.
Axelix ve ortamlarınız
Tipik yazılım geliştirme yaşam döngüsü birkaç ortamı kapsar. Bunlara tam olarak ne ad verirseniz verin (dev, sandbox, QA, UAT, staging), her ortam iki sınıftan birine girer: üretim ve üretim dışı.
Ekiplerin ilk sorusu genellikle şudur: Axelix Master üretimde mi çalışmalıdır? Evet. Master performans, güvenlik ve hata toleransı açısından hem üretimde hem test ortamlarında çalışmak için tasarlanmıştır. Master'ı üretimde çalıştırmak, amacına uygun ve yerleşmiş bir kullanım biçimidir.
Ancak Axelix'in üretim dağıtımını, test ortamlarınızı yöneten dağıtımdan ayrı tutmanızı kesinlikle öneririz. Başka bir deyişle tüm ortamları yöneten tek Master çalıştırmayın. Nedenleri:
- Erişim denetimi farklıdır. Test ortamındaki RBAC yapılandırması neredeyse kesinlikle üretimle aynı değildir. Üretimde günlük düzeyini değiştirebilen, önbellekleri açıp kapatabilen veya heap dökümü alabilen kişilerin listesi hazırlık ortamından çok daha kısadır. Roller ve yetkiler bölümüne bakın.
- Ağ kuralları farklıdır. Master arayüzüne ve Master MCP sunucusuna kimlerin erişebileceğini belirleyen kurallar üretimde genellikle test ortamlarından çok daha sıkıdır.
- Politikalar farklı olacaktır. Şu anda geliştirilmekte olan Axelix Enterprise politikalarının da ortama özgü olması beklenmektedir.
Her Master dağıtımı, axelix.master.environment özelliğiyle hangi ortama hizmet ettiğini belirtebilir
(örneğin production veya staging). Bugün bu etiket yalnızca
yapılandırılmış günlük kaydını
besler; ancak ilk günden ayarlamak dağıtımlarınızın kendini tanımlamasını sağlar.
Bu ayrımla benimseme süreci önce testten geçer. Böylece Axelix üretime ulaştığında hem yapılandırma hem de ekibinizin alışkanlıkları doğrulanmış olur.
Adım 1 — Veritabanını hazırlayın
Master ilişkisel veritabanına ihtiyaç duyar. Yerleşik SQLite ve varsayılan
jdbc:sqlite:axelix.db URL'siyle sunulduğundan ilk çalıştırmada hiç veritabanı yapılandırması gerekmez.
Bu varsayılan hızla çalışmaya başlamanızı sağlar.
Deneme aşamasını geçtiyseniz ve kurulumdan gerçek değer istiyorsanız desteklenen listeden bir motor seçin: PostgreSQL, MySQL veya SQLite. Tek düğümlü denemenin ötesinde PostgreSQL veya MySQL seçin. SQLite veriyi yerel dosyada saklar; bağlı bir birim olmadan kapsayıcı yeniden başlatmalarında korunmaz ve birden fazla Master kopyasının arkasında kullanılamaz. Desteklenen motor listesini gelecekte genişletmeyi planlıyoruz.
Master şemasını kendisi uyguladığından veritabanını ve şema geçiş yetkilerine sahip kullanıcıyı hazırlayın: Liquibase her başlangıçta çalışır, geçişleri asla elle çalıştırmazsınız; Veritabanı geçişleri sayfasına bakın. Bağlantı, Veritabanı bölümünde açıklanan üç özellikle yapılandırılır.
Veritabanı hazır olduğunda devam edin.
Adım 2 — Master'ı test ortamına kurun
Önce Master'ı bir test ortamına kurun (her test ortamına ayrı Axelix dağıtımı yapıyorsanız birkaçına). Her paketleme biçimi uygundur; altyapınıza uyanı seçin: düz JAR, Docker, Docker Compose veya resmî Helm chart ile Kubernetes. Her biri için minimum başlatma:
İmaj GitHub Container Registry'de yayımlanır. Aşağıdaki komutlar en son sürüm 1.3.1 kullanır;
farklı sürüm çalıştırmak için etiketi değiştirin:
docker run --rm -p 2935:2935 ghcr.io/axelixlabs/axelix:1.3.1JWT özellikleri ayarlanmadığında Master yerleşik imzalama anahtarını kullanır. Bunu yalnızca yerel denemede kullanın; İmzalama anahtarı olmadan çalıştırma bölümüne bakın.
Veritabanı bağlantısını ve diğer yapılandırmayı sağlamak için Docker ile çalıştırma, Compose seçeneği için Docker Compose ile çalıştırma bölümüne bakın.
Master'a artık http://localhost:2935 adresinden (Kubernetes'te Ingress üzerinden) erişilebilir.
Super-admin hesabıyla oturum açın.
2935, Axelix 1.2.0 itibarıyla varsayılan porttur. Önceki sürümde Master 8080 dinliyordu.
Gerekçesi ve eski porta dönmek için Genel bölümüne bakın.
Ardından yapılandırın. Master birçok kaynaktan yapılandırma kabul eder: ortam değişkenleri, haricî yapılandırma dosyası, Spring Cloud Config Server veya HashiCorp Vault. Bu nedenle mevcut yapılandırma sürecinize uydurmak zor olmamalıdır. Özellikleri sağlama bölümüne bakın.
Yukarıdaki başlatma örneklerindeki iki JWT değeri, axelix.master.auth.jwt.algorithm ve
axelix.master.auth.jwt.signing-key değerleridir; Kimlik doğrulama — JWT
bölümüne bakın. İlk günden imzalama anahtarına özen gösterin: her yönetilen servisin daha sonra Master'a sunacağı paylaşılan
sır budur. Uzun rastgele bir değer üretin ve sürüm kontrolüne alınmış dosyada değil sır yöneticinizde tutun.
Axelix 1.2.0 ve üzerinde
Her iki JWT değeri de isteğe bağlıdır. Bunlar olmadan Master ve servisleriniz yerleşik imzalama anahtarına döner; böylece anahtar üretmeden Axelix'i yerelde deneyebilirsiniz. Bu anahtar herkesçe bilinir; dolayısıyla herkes onu Master'da oturum açmak ve servislerinizin Axelix uç noktalarını çağırmak için kullanabilir. Yalnızca yerel denemede kullanın, diğer her yerde kendi anahtarınızı ayarlayın. İmzalama anahtarı olmadan çalıştırma bölümüne bakın.
Veritabanı bağlantısı ve imzalama anahtarı dışında bu aşamada bilinçli verilmesi gereken iki karar vardır:
- Keşif yöntemi. Otomatik keşifte Master Kubernetes ortamını tarar ve bulduğu servisleri yoklar. Kendiliğinden kayıtta her servis Master'a yaşam sinyalleri gönderir. İki yöntem birleştirilebilir; örneğin küme içi servislerde otomatik keşif, Master'ın tarayamadığı servislerde kendiliğinden kayıt. Davranışları için Keşif nasıl çalışır? sayfasına bakın.
- Oturum açma ve RBAC. Master'ın hesapları kendi veritabanında sakladığı yerel kullanıcılar küçük ekipler için muhtemelen yeterlidir. Büyük kuruluşlarda kimlik sağlayıcınızla OAuth2 / OIDC genellikle daha iyi seçenektir. Her iki durumda da başlangıç super-admin hesabı ilk günden arayüze girmenizi sağlar.
Adım 3 — Servislerinize starter ve derleme eklentisini ekleyin
Ardından Master'ın yönetmesini istediğiniz servislere istemci bileşenlerini kademeli ekleyin. İki bileşen vardır ve ikisi de gereklidir: servisin Spring Boot ana sürümüne uygun Axelix Spring Boot starter ve Maven veya Gradle için Axelix derleme eklentisi. İkisi de Maven Central'da yayımlanır; eklemek sıradan bir bağımlılık değişikliğidir, özel depo gerekmez. Axelix birlikte sürümlendirilir; Master, starter'lar ve derleme eklentisi için aynı Axelix sürümünü kullanın. Starter-Boot eşlemesi ve tam sürüm farkı kuralları için Uyumluluk ve sürümlendirme sayfasına bakın.
Spring Boot 4 servisi için derleme değişiklikleri şöyledir (servisin Boot ana sürümüne göre 4 yerine 2 veya 3 kullanın):
plugins {
id("com.axelixlabs.axelix") version "1.3.1"
}
dependencies {
implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.3.1")
}Eklenti henüz Gradle Plugin Portal'da olmadığından settings.gradle.kts içindeki pluginManagement'a mavenCentral()
ekleyin; Derleme eklentisi yapılandırmasına bakın.
Yalnızca bağımlılıkları eklemek yetmez. Her servis ayrıca starter yapılandırma sayfasında
ayrıntılı açıklanan iki yapılandırmaya ihtiyaç duyar. Axelix 1.2.0 ve üzerinde actuator uç noktaları için burada bir şey
gerekmez: starter bunları management.endpoints.web.exposure.include içine otomatik ekler;
Actuator uç noktaları bölümüne bakın.
Eski sürümlerde bunları erişime açmak üçüncü zorunlu yapılandırmadır; örneklerin altındaki nota bakın.
- 2. adımdaki paylaşılan JWT imzalama anahtarını
axelix.sbs.auth.jwt.*altında ayarlayın. Master ve servis arasındaki anahtar uyuşmazlığı401yanıtlarının en yaygın nedenidir; JWT imzalama anahtarını Master ile paylaşın ve Sorun giderme bölümlerine bakın. Axelix 1.2.0 ve üzerinde yerel denemede bunu atlayabilirsiniz; servis yerleşik anahtarı kullanır. İmzalama anahtarı olmadan çalıştırma bölümüne bakın. - Keşfi yapılandırın; yalnızca kendiliğinden kaydı seçtiyseniz.
Master'ın örneği bulmasını sağlayın bölümünde
gösterildiği gibi
axelix.sbs.discovery.*özelliklerini Master'ınıza yönlendirin. Master tarafında otomatik keşifte serviste ek yapılandırma yoktur.
Bir araya getirildiğinde minimum servis yapılandırması:
axelix:
sbs:
auth:
jwt:
algorithm: HMAC512
signing-key: ${AXELIX_JWT_SIGNING_KEY}1.2.0'dan eski Axelix sürümlerinde
1.2.0'dan eski starter'lar uç noktalarını management.endpoints.web.exposure.include içine kendileri eklemez;
bu sürümlerde uç nokta listesi de minimum yapılandırmanın parçasıdır. axelix-metadata, Master'ın örneği tespit etmek için
yokladığı uç noktadır; bu nedenle keşif yönteminden bağımsız olarak onsuz servis hiç görünmez:
management:
endpoints:
web:
exposure:
include:
- axelix-metadata
- axelix-beans
- axelix-caches
- axelix-conditions
- axelix-configprops
- axelix-details
- axelix-env
- axelix-gc
- axelix-heap-dump
- axelix-loggers
- axelix-metrics
- axelix-scheduled-tasks
- axelix-thread-dumpBu starter sürümleri eski axelix-feign uç noktasını da ekler. Bilinçli olarak listede yoktur: Master onu asla okumaz ve
uç nokta Axelix 1.3.0'da kaldırılmıştır;
axelix-feign uç noktası kaldırıldı bölümüne bakın.
Servisleri tek tek kullanıma alın. Her servis test ortamına yeniden dağıtıldığında test Master'ında görünür ve ekip arayüzü ve MCP'yi hemen kullanmaya başlayabilir.
Üretimle ilgili bir ayrıntıyı planlamak gerekir. Servisler genellikle aynı artifact'ı testten üretime taşır;
bu nedenle starter üretime Master'dan önce ulaşır. Böyle bir serviste kendiliğinden kayıt etkinse starter henüz
var olmayan Master'a kaydolmayı denemeye devam eder. Bu servislerde starter'ı pasif tutmak için üretim yapılandırmasında
axelix.sbs.enabled=false ayarlayın;
Starter'ı devre dışı bırakma bölümüne bakın.
Adım 4 — Master'ı üretime kurun
Son olarak test kullanımı kendini kanıtladığında Axelix'i üretime taşıyın. Bu, 1. ve 2. adımların ayrı bir dağıtım olarak tekrarıdır: kendi veritabanı, üretim düzeyinde RBAC ve üretimin gerektirdiği daha sıkı arayüz ve MCP sunucusu ağ erişim kuralları.
Üretim Master'ı açıldığında 3. adımdaki geçici axelix.sbs.enabled=false ayarlarını kaldırın;
böylece üretim örnekleri kaydolur ve görünür olur.
İlgili sayfalar
- Master nedir?: Master'ın yönettiği servislerle yaptıkları hakkında arka plan.
- Master yapılandırması: tüm Master özellikleri, paketleme seçenekleri ve yapılandırma kaynakları.
- Spring Boot Starter yapılandırması: servisi bağlamanın ayrıntıları.
- Derleme eklentisi yapılandırması: ikinci zorunlu istemci bileşeni.
- Kimlik doğrulama: oturum açma seçenekleri, roller ve yetkiler.
- Uyumluluk ve sürümlendirme: hangi starter'ın hangi Spring Boot ve Java sürümüne uyduğu ve bileşen sürümlerinin birbirleriyle uyumlu kaldığı.
- Sorun giderme: en yaygın kurulum sorunları (
401yanıtları, yanlış starter modülü, hiç kaydolmayan servis) ve çözümleri.
Keşif nasıl çalışır?
Axelix Master'ın Spring Boot örneklerini Kubernetes'te kendisi bularak veya örneklerin kendilerini kaydetmesine izin vererek nasıl öğrendiği ve durumlarını nasıl güncel tuttuğu.
Yapay zekâ ile kurulum
Axelix'i bir Spring Boot servisine kurun: Axelix Spring Boot starter, Axelix derleme eklentisi ve yerel deneme için Axelix Master. Kullanıcı Axelix'i kurmak, eklemek, ayarlamak, denemek veya bağlamak istediğinde kullanın.