Files
rust-discovery/docs/development.md
T

19 KiB

Bauen und Bereitstellen in der Entwicklungsumgebung

Der Lieferplan nennt den nächsten Schritt. Für eine Entwicklungskorrektur reicht der direkte Weg zum betroffenen Dienst. Der Agent-Updater ist selbst ein Produktfeature und wird über den Releasekanal geprüft, wenn genau diese Funktion zur Abnahme steht.

Buildziel wählen

Die Befehle werden im Repository ausgeführt. Der Buildrunner verwendet den gewählten Git-Commit, die gepinnte Rust-Toolchain und die vorhandenen Docker-Builder. --plan zeigt Revision, Zielbinaries und Kommando an. --ref akzeptiert einen Commit oder Branch und verwendet standardmäßig HEAD. Bei absichtlich geänderten Quellen einen eigenen abgegrenzten Git-Stand wählen, damit fremder WIP im Arbeitsbaum bleiben kann. Der Cargo-Cache wird je Ziel wiederverwendet. Fehlen dem gepinnten Builder Pakete aus dem gewählten Lockfile, lädt der Runner sie einmalig mit cargo fetch --locked in den zielbezogenen Cache. Kompilierung und Buildskripte laufen weiterhin ohne Netzwerk.

Ziel Befehl Ergebnis
Linux-Client x86-64 python3 tools/build.py linux-x64 Agent, privilegierter Helper und stabiler Updater
Offizieller Windows-Client x86-64 python3 tools/build.py windows-gnu-x64 Windows-GNU-Agent, SYSTEM-Helper und stabiler Windows-Updater.
Server ARM64 vom Notebook python3 tools/build.py server-arm64 --ssh Überträgt den Runner und ausgewählte Quellen des Git-Commits per geprüftem SSH. Baut Server und Zeitbroker im separaten Bereich ~/rmm-dev-build/server-arm64/ auf dem nativen ARM64-Host. Ausgabe enthält Remote-Pfad und Hashes.
Server ARM64 direkt auf einem passenden Linux-Buildhost python3 tools/build.py server-arm64 Serverbinary für API/Gateway und Zeitbroker. Der lokale Modus erwartet Git-Checkout, gepinnten ARM64-Builder, Docker, Python 3, git, tar und rsync.
WebUI npm --prefix web run build TypeScript-Prüfung und Vite-Bundle in web/dist/. Im frischen Checkout zuerst npm --prefix web ci ausführen.
Windows-Binaries nativ mit MSVC Vorhandenen MSVC-Runner und Voraussetzungen verwenden. Geplant, nicht ausgeführt. Eigener Preflight und Build auf passendem Windows-Builder. Optionales zusätzliches Buildziel.

Der lokale Runner gibt den konkreten Artefaktordner aus. Unter devstate/build/<Ziel>/artifacts/<Commit>/<Manifesthash>/ liegen die Binaries und manifest.json mit Quellrevision, Zielarchitektur, Builder und SHA-256. Ausgelieferte Binärdateien immer am Hash identifizieren: Zwei Builds aus demselben Commit können unterschiedliche Bytes haben. Ein Build erstellt noch keinen signierten Produktrelease.

Server und WebUI aus einem geprüften Git-Stand aktivieren

python3 tools/build.py server-arm64 --ssh --ref REVISION erzeugt die Binärdatei auf dem Server. Anschließend baut python3 tools/dev_deploy_server.py --ref REVISION die passende WebUI, übernimmt die vorhandene Compose-Konfiguration und aktiviert API und Gateway. Der Runner vergleicht die tatsächlich angewendeten SQLx-Prüfsummen mit Git und liest die laufenden Binärhashes und die über TLS ausgelieferte Startseite zurück. Mit --overlay server.releases.compose.yaml überträgt und aktiviert der Runner die entsprechende Datei aus derselben Git-Revision. Deploymentrunner

Bei einer reinen WebUI-Änderung genügt python3 tools/dev_deploy_server.py --web-only --ref REVISION. Für ein schon gebautes Bundle aus dem Arbeitsbaum genügt python3 tools/dev_deploy_server.py --web-only --web-dist web/dist. Beide Wege stellen zuerst die Assets und zuletzt die Startseite per SSH bereit. Der Runner vergleicht die per TLS ausgelieferte Startseite mit den übergebenen Bytes. Die Ausgabe enthält den SHA-256 der Startseite und die ID des laufenden API-Containers.

Vorhandene Dateien direkt bereitstellen

dev_stage.py verwendet die vorhandenen gepinnten SSH-Zugänge für server, linux und windows. Der Befehl nimmt beliebig viele benannte Entwicklungsartefakte entgegen, darunter fertige Binaries oder bereits gebaute Webassets. Unter rmm-dev-stage/<SHA-256>/<Dateiname> im Profil des SSH-Benutzers verifiziert er die Datei und verwendet vorhandene identische Bytes wieder. Für das Prüfen der Zielpfade genügt --plan. Zugangsprofile und Hostpins

Beispiel für ein bereits gebautes Linux-Paar, geplant, nicht ausgeführt. ARTIFACT_DIR auf den vom Build ausgegebenen Ordner setzen:

python3 tools/dev_stage.py --plan linux "$ARTIFACT_DIR/rmm-agent" "$ARTIFACT_DIR/rmm-privileged-helper"
python3 tools/dev_stage.py linux "$ARTIFACT_DIR/rmm-agent" "$ARTIFACT_DIR/rmm-privileged-helper"

Aktivierung der bereitgestellten Entwicklungsversion

Nach dem Transfer die laufende Version und ihre Rückmeldung prüfen. Für den Server übernimmt das der Deploymentrunner. Die beiden Entwicklungsgeräte haben eigene Verfahren für den Wechsel einer laufenden Binärdatei.

  • Server. Den oben angegebenen Deploymentrunner verwenden. Er übernimmt die aktive Compose-Dateikette aus den Containerlabels, bestehende Volumes und Policy-Mounts. Deploymentaufbau
  • Linux. Beim Austausch der betroffenen Dienste ihre tatsächlich installierten Artefakte und Rechte feststellen, Ersatz vollständig bereitstellen und Konfiguration, Identität und Journal erhalten. Den Prozesshash, einen neuen Heartbeat und bei geänderter Jobruntime einen regulären Sync zurücklesen. Die früheren Linux-Wechsel enthalten wiederverwendbare Prüfungen und setzen konkrete Altfälle voraus.
  • Windows. Agent und Helper bei einem Paarwechsel koordiniert stoppen, Binärdateien und die an sie gebundenen Metadaten aus derselben Version einsetzen, ACLs und Geräteidentität erhalten und geordnet starten. Prozesshashes und Gerätepräsenz getrennt abfragen. Vorhandener Paarwechsel · Zugang und lesende Diensteprüfung

Der alte deploy/dev.py up richtet eine lokale Compose-Umgebung ein. Der Produktserver liegt auf dem dedizierten Internetserver. Fallbezogene Builder wie server_build_221.py sind über ihre damaligen Belege auffindbar.

Tatsächlich geprüft am 17. November 2026

  • linux-x64 und windows-gnu-x64 auf dem Entwicklungs-PC aus a576c10 gebaut, fünf Binaries und beide Manifeste per SHA-256 geprüft. Wiederholte Cargo-Builds aus dem Cache lagen jeweils unter einer Sekunde. Auf dem Windows-Gast liefen bei der Inventur die Hashes seines früheren Installationsbuilds aus demselben Commit.
  • python3 tools/build.py server-arm64 --ssh auf dem konfigurierten ARM64-Server tatsächlich ausgeführt. Server und Zeitbroker als ELF64/AArch64 nachgelesen, Manifest und Hashes bestätigt. Cargo benötigte beim ersten Lauf 7 min 6 s, beim zweiten 0,52 s. Beide Läufe lieferten identische Bytes. API, Gateway und Datenbank liefen währenddessen weiter.
  • WebUI mit den lokal vorhandenen Abhängigkeiten typgeprüft und in ein isoliertes Ausgabeverzeichnis gebaut. Ergebnis: index.html, CSS- und JavaScript-Bundle.
  • Auf Server, Cloud-Linux und Windows jeweils python3 tools/dev_stage.py ZIEL rust-toolchain.toml zweimal ausgeführt. Der erste Aufruf übertrug die Datei und prüfte den Zielhash, der zweite bestätigte die vorhandenen Bytes. Der Test veränderte nur den Stagingbereich. Es wurde kein Dienst aktiviert, Gerät neu aufgenommen oder Produktrelease veröffentlicht. Build- und Betriebsbelege

Die früheren Entwicklungsprotokolle einschließlich der alten Notebook-/Reverse-Tunnel-Topologie sind im Git-Stand a576c10:docs/development.md erhalten.

Entwicklungspakete im isolierten Entwicklungsprofil veröffentlichen

Der Buildordner enthält das in der Buildquittung gebundene Agent-/Helperpaar und den stabilen Bootstrap-Updater. Ein Linux-Build benötigt rmm-agent, rmm-privileged-helper und rmm-agent-updater. Auf Windows heißen die Dateien rmm-agent-windows.exe, rmm-helper-windows.exe und rmm-updater-windows.exe. Der GNU-Build enthält den stabilen Updater. Der Katalog führt Linux GNU, Windows MSVC und Windows GNU als getrennte Ziele. Für offizielle Windows-Pakete den eigenen Signierschlüssel verwenden.

python3 tools/dev_agent_release.py \
  --artifacts "$buildordner" --build-receipt "$buildordner/manifest.json" \
  --sequence 1 --version 0.1.0-mvp.1

Der Befehl prüft die Buildquittung und überträgt die drei Binärdateien über den gepinnten SSH-Zugang. Auf dem Server signiert ein separater Ed25519-Schlüssel je Plattform das exakte Agent-/Helperpaar. Der Aufruf lädt die Dateien über die authentisierte Management-API und veröffentlicht zuletzt den Envelope. Ein erneuter Aufruf mit derselben Sequenz und denselben Bytes verwendet die gespeicherte Signatur. Für eine geänderte Version die Sequenz erhöhen. Native MSVC-Builds verwenden ihre result.json als --build-receipt.

Beim ersten Serveraufbau den Befehl zunächst mit --prepare-only ausführen. Damit entstehen die Schlüssel, die öffentliche Konfiguration und der Objektspeicher unter /opt/rust-discovery/devstate/mvp-releases. Das Compose-Overlay deploy/server.releases.compose.yaml bindet nur Konfiguration und Objekte an die Rollen. Der private Schlüssel bleibt auf dem Server. Anschließend API und Gateway mit diesem Overlay aktivieren und den Veröffentlichungsbefehl ohne --prepare-only erneut ausführen. Der bei der Einrichtung gespeicherte SHA-256 ist der Ausgangswert für die unten beschriebene kontrollierte Rotation.

Neue Geräte und Selbstupdate

Im Releasekatalog der WebUI unter Neues Gerät aufnehmen einen Einmalcode erzeugen. Die WebUI zeigt die Installationsaufrufe für die veröffentlichten Plattformen. Den Code auf dem neuen Gerät im Prompt eingeben. Nach 15 Minuten oder beim erfolgreichen Enrollment verliert er seine Gültigkeit. Der öffentliche Bootstrap-Origin wird mit RMM_BOOTSTRAP_ORIGIN festgelegt. Die Geräteadresse stammt aus der geschützten plattformspezifischen Bootstrapkonfiguration.

Im aktuellen Windows-Entwicklungsmandanten den angebotenen Aufruf mit -Platform x86_64-pc-windows-gnu aus der WebUI übernehmen. Windows verwendet den LocalService-Agenten und den separaten Dienst RmmDiscoveryReleasePull für die periodische Prüfung.

Auf Linux startet rmm-discovery-agent.service als Systemkonto rmm-discovery mit eigenem Zustand in /var/lib/rmm-discovery. rmm-discovery-update.timer prüft nach dem Booten und anschließend alle fünf Minuten den Releasebestand. Die aktive Generation und ein bei fehlgeschlagener Aktivierung gespeicherter Fehler liegen unter /opt/rust-discovery-client. Der Lauf berücksichtigt belegte Jobs, verifiziert den signierten Inhalt, schaltet die Generation um und prüft die neue Geräteverbindung. Das Systemjournal von rmm-discovery-update.service enthält die Fehlermeldung. Der Linux-Produktinstaller startet den unprivilegierten Agenten. Für Root-Skripte aktiviert ein lokaler Administrator einmalig den an dieses Gerät gebundenen Helferdienst. Dazu den aus der WebUI geladenen Installer mit sudo sh linux.sh https://discovery.ease-technologies.de:8443 --enable-admin-scripts ausführen. Bei einem abweichenden Bootstrap-Origin die von der WebUI angezeigte HTTPS-Adresse einsetzen. Der Schalter funktioniert auch nach der Aufnahme mit der vorhandenen Geräteidentität. Ohne diesen Schalter bleibt ein bisheriges Dienstkonto-Gerät beim Dienstkonto. Die WebUI-Genehmigung des konkreten Skripts und die Berechtigungen auf dem Server gelten bei jedem Auftrag.

Der Helferdienst rmm-discovery-managed-script-helper.service verwendet den Helper aus demselben signierten Release wie der Agent. Der Installer übernimmt einen bereits ausdrücklich eingerichteten, dauerhaft aktivierten Skripthelfer nur mit übereinstimmender Gerätebindung und Skriptrichtlinie. Für diese Migration den aktuellen HTTPS-Installer auf dem eingeschriebenen Gerät erneut ausführen. Die nächste periodische Aktualisierung schaltet Agent, Helper und die zugehörigen Prüfdaten gemeinsam um. Bei fehlgeschlagener Aktivierung prüft der Updater die Rückkehr des vorherigen Paares. Eine bestehende lokale Deaktivierung, Maskierung oder abweichende Richtlinie bleibt wirksam.

Ein geänderter stabiler Bootstrap-Updater wird ausdrücklich je Mandant rotiert. Dazu beim Veröffentlichen des geprüften neuen Builds --rotate-bootstrap-from <bisheriger SHA-256> ergänzen. Für den Windows-GNU-Worker mit Skript-/Updatesperre verlangt der signierte Release zusätzlich --minimum-updater-version 2. Der Befehl lädt den neuen Worker zunächst über die Katalog-API hoch, vergleicht das gespeicherte Objekt und den bisherigen Mandantenpin und schaltet anschließend auf den neuen Hash um. Bereits ausgestellte Installer können den vorher erhaltenen Hash noch 15 Minuten lang abrufen. Weitere Releases desselben Workerstands verwenden nur --minimum-updater-version 2. Bestehende Geräte mit älterer stabiler Prüferdatei verwerfen ein Release, dessen signierte Mindestversion ihre eigene Prüferfähigkeit übersteigt.

Historischer manueller Linux-Helperwechsel

Für Systeme vor der Migration auf den aktuellen HTTPS-Installer gilt das frühere Verfahren. Auf der Entwicklungs-VM verwies die Unit rmm-discovery-managed-script-helper.service auf den absoluten Pfad der bisherigen signierten Releaseversion. Für den gemeinsamen Versionswechsel vor der Katalogveröffentlichung den aktiven Release aus /opt/rust-discovery-client/current erfassen, rmm-discovery-update.timer mit systemd stoppen und den Abschluss eines laufenden Update-Dienstes abwarten. Das neue Paar veröffentlichen, den regulären rmm-discovery-update.service einmal starten und seine erfolgreich aktivierte Release-ID prüfen.

Vom Entwicklungsrechner den Helperwechsel zuerst mit check und dann mit switch aufrufen. Beide Aufrufe erwarten --tenant UUID --asset UUID --agent UUID --previous ALTE_RELEASE_UUID --current NEUE_RELEASE_UUID. Der Befehl prüft beide signierten Paare, den vorhandenen Systemdienst, die lokale Gerätebindung und genau einen passenden bestehenden Serverscope. Unter der lokalen Auftrags- und Releasesperre aktualisiert er Helperprofil, Agentpin und Unit-Ziel. Ein neuer authentisierter Kontakt muss beide erwarteten Helperhashes und einen bereiten Abgleich melden. Erst dann ersetzt der Operator im vorhandenen Serverscope die beiden Hashwerte. Principals, erlaubte Aktionen, übrige Geräte und Kunden bleiben erhalten.

Nach erfolgreichem Rücklesen den Update-Timer wieder starten. Ein unterbrochener switch ist mit denselben Kennungen fortsetzbar. rollback stellt unter denselben Prüfungen den vorherigen Helper und dessen Pins wieder her und belässt den Agenten in der angegebenen aktuellen Releaseversion. Bei ausstehendem Abgleich bleibt der bestehende Serverscope wirksam. Der stabile Verifier unter /opt/rust-discovery-client/updater wird separat anhand seines Bootstrap-Pins ausgetauscht.

Stabilen Windows-Updater im Entwicklungsbetrieb ersetzen

Für den gezielten Austausch des stabilen Workers zuerst die fertige Datei mit tools/dev_stage.py windows DATEI übertragen. Replace-DevelopmentReleaseUpdater.ps1 erwartet -Candidate, die beiden exakten Hashes über -ExpectedPreviousSha256 und -ExpectedCandidateSha256, -AgentId und die zu prüfenden -VerifyReleaseIds. In einer administrativen Windows-PowerShell ausführen. Der Befehl verlangt einen laufenden Agenten und gestoppten Updater, prüft die signierten Releasepaare nativ, ersetzt den Worker atomar mit Sicherung und startet den Updatedienst mit SCM-Wiederanlauf. Bei standardmäßig Restricted geltender Skriptrichtlinie für die Entwicklungs-PowerShell Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned verwenden.

Dieser Weg wurde am 17. November für den Worker de75510b… ausgeführt. Der anschließende reguläre Abruf aktivierte Windows 0.1.3 auf derselben Geräteidentität. Nativer Beleg

Für die separate Veröffentlichung eines korrigierten stabilen Workers ohne neues Agentpaket verwendet der Entwicklungsrunner --rotate-worker-only --rotate-bootstrap-from SHA256 zusammen mit --artifacts und --build-receipt. Die Quittung muss die passende Plattform und den übertragenen Worker binden. Der Aufruf prüft den gespeicherten Worker und rotiert nur den Bootstrap-Pin des gewählten Mandanten. Veröffentlichungs- und Rotationsnachweis

Windows-Wartungsvorlage im Entwicklungsbetrieb nutzen

Der Operatorablauf beschreibt die Einrichtung der SYSTEM-Rechte auf dem aufgenommenen Testgerät. python3 tools/windows_update_scope.py inspect liest den Iststand. plan zeigt den vorgesehenen Eingriff. window --minutes 15 öffnet ein geräte- und releasegebundenes Fenster. Der Befehl bleibt während der Wartung aktiv und schließt das Fenster anschließend. Ein vorzeitiges close --case UUID entzieht die zentrale Richtlinie, wartet auf terminale Aufträge und baut den lokalen Helper zurück. Der feste Skriptauftrag wird in der WebUI geprüft und genehmigt.

Öffentliche Verwaltung

tools/dev_public_access.py provisioniert den lokalen Passwort-/TOTP-Zugang, startet die zusätzliche API intern und aktiviert den vorhandenen öffentlichen TLS-Ingress. Die tatsächlichen Befehle und die privaten Dateipfade stehen im Betriebsablauf. Der normale Deploymentrunner aktualisiert anschließend auch den öffentlichen API-Dienst.

Offizielle Windows-Veröffentlichung

  1. python3 tools/build.py windows-gnu-x64 --ref REVISION erzeugt das Agent-/Helperpaar, den stabilen Updater und die Buildquittung.
  2. python3 tools/dev_agent_release.py --official-windows --artifacts ORDNER --build-receipt ORDNER/manifest.json --sequence NUMMER --version VERSION --minimum-updater-version 2 --prepare-only bindet die Binärhashes an den separaten Schlüssel auf dem Signierhost. Die Sequenz muss größer als die letzte im Zielkatalog sein. Schlüssel und Konfiguration liegen in den getrennten Slots windows-gnu-official. Nur die öffentlichen Prüfmaterialien werden in die Serverprozesse eingebunden.
  3. Auf dem Entwicklungsserver denselben Aufruf ohne --prepare-only für Development A verwenden. Für weitere Kunden die signierten Artefakte über die reguläre Katalog-API mit der Berechtigung des Zielkunden veröffentlichen. tools/agent_release.py publish --help beschreibt den Login mit lokalem Konto und TOTP. Bei einer Workerrotation den bisherigen Hash angeben.
  4. python3 tools/dev_customer_starters.py --official-windows --tenant UUID --platform x86_64-pc-windows-gnu --release RELEASE_UUID veröffentlicht den gewählten Starter für neue Kunden. Befüllte Kataloge benötigen ihren eigenen Import. Bestehende Entwicklungsinstallationen besitzen einen anderen lokalen Schlüsselring. Die erstmalige Umstellung erfolgt über eine geprüfte Neuaufnahme oder eine separat autorisierte lokale Vertrauensmigration.