Erste Schritte
Der empfohlene Weg zur organisationsweiten Einführung von Axelix: geeignete Anfangsumgebungen, Installationsreihenfolge und sicherer Übergang in die Produktion. Jeder Schritt enthält konkrete Befehle, minimale Konfiguration und Links zur vollständigen Referenz.
Die Beispiele auf dieser Seite verwenden die Version 1.3.1. Prüfen Sie auf der Releases-Seite den neuesten veröffentlichten Tag und setzen Sie ihn in Ihren Befehlen ein.
Axelix und Ihre Umgebungen
Ein typischer Softwareentwicklungszyklus umfasst mehrere Umgebungen. Unabhängig von ihren Namen — Dev, Sandbox, QA, UAT, Staging — gehört jede zu einer von zwei Kategorien: Produktion oder Nichtproduktion.
Teams fragen daher oft zuerst: Soll Axelix Master in der Produktion laufen? Ja. Master ist hinsichtlich Leistung, Sicherheit und Fehlertoleranz für Produktions- und Testumgebungen ausgelegt. Der Produktionseinsatz ist eine etablierte Praxis.
Wir empfehlen jedoch dringend, die Axelix-Bereitstellung für die Produktion von derjenigen für Testumgebungen zu trennen. Ein einzelner Master sollte also nicht alle Umgebungen verwalten. Die Gründe:
- Unterschiedliche Zugriffskontrolle. Die RBAC-Konfiguration einer Testumgebung unterscheidet sich fast immer von der Produktion. Der Kreis der Personen, die dort Log-Level ändern, Caches umschalten oder Heap-Dumps erstellen dürfen, ist deutlich kleiner als auf Staging. Siehe Rollen und Berechtigungen.
- Unterschiedliche Netzwerkregeln. Der Zugriff auf Master-UI und Master-MCP-Server ist in Produktion üblicherweise erheblich strenger geregelt als in Testumgebungen.
- Unterschiedliche Richtlinien. Auch die derzeit entwickelten Axelix-Enterprise-Richtlinien werden voraussichtlich umgebungsspezifisch sein.
Jede Master-Bereitstellung kann ihre Umgebung über axelix.master.environment angeben, etwa production oder staging. Derzeit wird diese Kennzeichnung nur für strukturiertes Logging verwendet. Wenn Sie sie von Anfang an setzen, bleiben Ihre Bereitstellungen eindeutig beschrieben.
Mit dieser Trennung beginnt die Einführung in Testumgebungen. Bis Axelix die Produktion erreicht, haben sich Konfiguration und Arbeitsweise des Teams bereits bewährt.
Schritt 1 — Datenbank vorbereiten
Master benötigt eine relationale Datenbank. Es enthält eingebettetes SQLite mit der Standard-URL jdbc:sqlite:axelix.db. Für den ersten Start ist daher keine Datenbankkonfiguration erforderlich. Dieser Standard ermöglicht einen schnellen Einstieg.
Wenn Sie über das Ausprobieren hinausgehen und die Installation produktiv nutzen möchten, wählen Sie eine unterstützte Engine: PostgreSQL, MySQL oder SQLite. Für alles über einen Test mit einem einzelnen Knoten hinaus wählen Sie PostgreSQL oder MySQL. SQLite speichert Daten lokal in einer Datei; ohne eingebundenes Volume übersteht diese keine Container-Neustarts und kann nicht mehrere Master-Replikate versorgen. Weitere Engines sind für künftige Releases geplant.
Stellen Sie die Datenbank und einen Benutzer mit Rechten für Schemamigrationen bereit. Master wendet sein Schema selbst an: Liquibase läuft bei jedem Start; manuelle Migrationen sind nie nötig. Siehe Datenbankmigrationen. Die Verbindung wird über drei Eigenschaften aus dem Abschnitt Datenbank konfiguriert.
Sobald die Datenbank bereitsteht, fahren Sie fort.
Schritt 2 — Master in einer Testumgebung installieren
Installieren Sie Master zunächst in einer Testumgebung, oder in mehreren, wenn Sie separate Axelix-Bereitstellungen je Testumgebung verwenden. Wählen Sie die zu Ihrer Infrastruktur passende Form: JAR, Docker, Docker Compose oder Kubernetes mit offiziellem Helm-Chart. Die minimalen Startbefehle:
Das Image wird in der GitHub Container Registry veröffentlicht. Die folgenden Befehle verwenden das neueste Release 1.3.1. Ändern Sie den Tag für eine andere Version:
docker run --rm -p 2935:2935 ghcr.io/axelixlabs/axelix:1.3.1Ohne JWT-Eigenschaften verwendet Master den integrierten Signaturschlüssel. Nutzen Sie dies nur für einen lokalen Test. Siehe Ohne Signaturschlüssel starten.
Zur Datenbankverbindung und weiteren Konfiguration siehe Mit Docker ausführen; zur Compose-Variante siehe Mit Docker Compose ausführen.
Master ist anschließend unter http://localhost:2935 erreichbar, auf Kubernetes hinter Ihrem Ingress. Melden Sie sich mit dem Super-admin-Konto an.
2935 ist seit Axelix 1.2.0 der Standardport. Zuvor lauschte Master auf 8080. Die Gründe und die Rückkehr zum alten Port erläutert Allgemeines.
Konfigurieren Sie Master anschließend. Es akzeptiert viele Quellen: Umgebungsvariablen, externe Konfigurationsdateien, Spring Cloud Config Server oder HashiCorp Vault. Damit lässt es sich in bestehende Konfigurationsabläufe integrieren. Siehe Eigenschaften bereitstellen.
Die zwei JWT-Werte in den Startbeispielen sind axelix.master.auth.jwt.algorithm und axelix.master.auth.jwt.signing-key. Siehe Authentifizierung — JWT. Behandeln Sie den Signaturschlüssel von Anfang an sorgsam: Er ist das gemeinsame Geheimnis, das später jeder verwaltete Dienst gegenüber Master verwendet. Erzeugen Sie einen langen Zufallswert und speichern Sie ihn im Secret-Manager statt in einer versionierten Datei.
Ab Axelix 1.2.0
Beide JWT-Werte sind optional. Ohne sie verwenden Master und Dienste einen integrierten Signaturschlüssel, sodass Sie Axelix lokal ohne Schlüsselerzeugung ausprobieren können. Dieser Schlüssel ist öffentlich bekannt. Jeder kann damit eine Anmeldung an Master und Aufrufe der Axelix-Endpunkte Ihrer Dienste signieren. Verwenden Sie ihn nur für lokale Tests und setzen Sie überall sonst einen eigenen Schlüssel. Siehe Ohne Signaturschlüssel starten.
Neben Datenbankverbindung und Signaturschlüssel sollten Sie jetzt zwei Entscheidungen bewusst treffen:
- Erkennungsmodus. Bei automatischer Erkennung durchsucht Master seine Kubernetes-Umgebung und prüft gefundene Dienste. Bei Selbstregistrierung sendet stattdessen jeder Dienst Heartbeats an Master. Beide Modi lassen sich kombinieren, etwa automatische Erkennung im Cluster und Selbstregistrierung für nicht durchsuchbare Dienste. Das Verhalten erläutert So funktioniert die Erkennung.
- Anmeldung und RBAC. Für kleine Teams reichen vermutlich lokale Benutzer, deren Konten Master in seiner Datenbank speichert. Für große Organisationen ist meist OAuth2 / OIDC mit Ihrem Identitätsanbieter geeigneter. In beiden Fällen ermöglicht das anfängliche Super-admin-Konto den ersten UI-Zugriff.
Schritt 3 — Starter und Build-Plugin zu Ihren Diensten hinzufügen
Ergänzen Sie nun schrittweise die clientseitigen Komponenten in den Diensten, die Master verwalten soll. Beide sind erforderlich: der zur Spring-Boot-Hauptversion passende Axelix Spring Boot Starter und das Axelix-Build-Plugin für Maven oder Gradle. Beide sind auf Maven Central verfügbar; es genügt eine normale Abhängigkeitsänderung ohne private Repositories. Axelix verwendet eine gemeinsame Versionierung. Verwenden Sie daher dieselbe Axelix-Version für Master, Starter und Build-Plugin. Die Zuordnung zu Spring Boot und die genauen Regeln für Versionsabweichungen erläutert Kompatibilität und Versionierung.
Für einen Spring-Boot-4-Dienst sehen die Build-Änderungen so aus. Ersetzen Sie 4 passend zur Boot-Hauptversion durch 2 oder 3:
plugins {
id("com.axelixlabs.axelix") version "1.3.1"
}
dependencies {
implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.3.1")
}Da das Plugin noch nicht im Gradle Plugin Portal verfügbar ist, fügen Sie mavenCentral() zu pluginManagement in Ihrer settings.gradle.kts hinzu. Siehe Build-Plugin konfigurieren.
Die Abhängigkeiten allein reichen nicht. Jeder Dienst benötigt zusätzlich zwei Konfigurationsbestandteile, die auf der Starter-Konfigurationsseite ausführlich beschrieben sind. Ab Axelix 1.2.0 benötigen die Actuator-Endpunkte selbst keine Konfiguration: Der Starter ergänzt sie automatisch in management.endpoints.web.exposure.include. Siehe Actuator-Endpunkte. Bei älteren Versionen ist ihre Freigabe ein dritter zwingender Bestandteil; siehe den Hinweis unter den Beispielen.
- Gemeinsamen JWT-Signaturschlüssel setzen: Verwenden Sie den Schlüssel aus Schritt 2 unter
axelix.sbs.auth.jwt.*. Abweichende Schlüssel zwischen Master und Dienst sind die häufigste Ursache für401-Antworten. Siehe JWT-Signaturschlüssel mit Master teilen und Fehlerbehebung. Ab Axelix 1.2.0 können Sie dies für einen lokalen Test auslassen; der Dienst verwendet dann den integrierten Schlüssel. Siehe Ohne Signaturschlüssel starten. - Erkennung konfigurieren — nur bei Selbstregistrierung. Verweisen Sie mit
axelix.sbs.discovery.*auf Ihren Master, wie unter Instanz von Master finden lassen gezeigt. Bei automatischer Erkennung auf Master-Seite benötigt der Dienst keine zusätzliche Konfiguration.
Zusammen ergibt sich folgende minimale Dienstkonfiguration:
axelix:
sbs:
auth:
jwt:
algorithm: HMAC512
signing-key: ${AXELIX_JWT_SIGNING_KEY}Axelix vor 1.2.0
Starter vor 1.2.0 ergänzen ihre Endpunkte nicht selbst in management.endpoints.web.exposure.include. Bei diesen Versionen gehört die Endpunktliste daher ebenfalls zur Mindestkonfiguration. Master prüft axelix-metadata, um die Instanz zu erkennen. Ohne diesen Endpunkt erscheint der Dienst unabhängig vom Erkennungsmodus nie:
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-dumpDiese Starter-Versionen stellen auch den alten Endpunkt axelix-feign bereit. Er fehlt hier absichtlich: Master liest ihn nie, und ab Axelix 1.3.0 ist er entfernt. Siehe Der Endpunkt axelix-feign wurde entfernt.
Führen Sie dies Dienst für Dienst ein. Sobald ein Dienst erneut in einer Testumgebung bereitgestellt wird, erscheint er im Test-Master. Das Team kann sofort UI und MCP dafür verwenden.
Planen Sie dabei einen Produktionsaspekt ein: Dienste übernehmen meist dasselbe Artefakt von Test bis Produktion. Der Starter erreicht die Produktion dann früher als Master. Bei aktivierter Selbstregistrierung versucht er fortlaufend, sich bei einem noch nicht vorhandenen Master zu registrieren. Setzen Sie für solche Dienste axelix.sbs.enabled=false in der Produktionskonfiguration, um den Starter ruhen zu lassen. Siehe Starter deaktivieren.
Schritt 4 — Master in der Produktion installieren
Wenn sich die Einführung im Test bewährt hat, bringen Sie Axelix in die Produktion. Wiederholen Sie Schritte 1 und 2 als separate Bereitstellung: eigene Datenbank, produktionsgerechtes RBAC und strengere Netzwerkzugriffsregeln für UI und MCP-Server.
Sobald der Produktions-Master läuft, entfernen Sie vorübergehende axelix.sbs.enabled=false-Überschreibungen aus Schritt 3, damit die Produktionsinstanzen sich registrieren und sichtbar werden.
Weiterführende Informationen
- Was ist Master? — Aufgaben von Master für verwaltete Dienste.
- Master konfigurieren — alle Master-Eigenschaften, Bereitstellungsformen und Konfigurationsquellen.
- Spring Boot Starter konfigurieren — Dienste im Detail anbinden.
- Build-Plugin konfigurieren — die zweite erforderliche clientseitige Komponente.
- Authentifizierung — Anmeldeverfahren, Rollen und Berechtigungen.
- Kompatibilität und Versionierung — Zuordnung der Starter zu Spring Boot und Java sowie Versionskompatibilität der Komponenten.
- Fehlerbehebung — häufige Installationsprobleme (
401, falsches Starter-Modul, fehlende Registrierung) und deren Lösungen.
So funktioniert die Diensterkennung
Wie Axelix Master vorhandene Spring-Boot-Instanzen ermittelt und ihren Zustand aktuell hält: durch automatische Erkennung in Kubernetes oder durch Selbstregistrierung der Instanzen.
Mit KI installieren
Axelix in einen Spring-Boot-Dienst integrieren: Axelix Spring Boot Starter, Axelix-Build-Plugin und für einen lokalen Test auch Axelix Master. Verwenden, wenn der Benutzer Axelix installieren, hinzufügen, einrichten, ausprobieren oder verbinden möchte.