Installation im Air-Gap-Netzwerk

In Netzwerken ohne Internetzugang wird mit einem Bundle installiert. Auf der Seite mit Internetzugang wird das Bundle bezogen (oder gebrannt), die Signatur verifiziert, dann auf ein Medium übertragen und im Air-Gap-Netzwerk entpackt und eingespielt.

Legen Sie zuerst die Architektur fest

Es gibt zwei Bundle-Varianten — arm64 (GB10-Serie) · amd64 (AWS g7e usw.). Prüfen Sie auf dem Zielserver uname -m und wählen Sie entsprechend (aarch64 → arm64, x86_64 → amd64). Ein Bundle der falschen Architektur startet die Images nicht. Das Einspiel-Skript gleicht die in MANIFEST.txt des Bundles vermerkte Architektur mit diesem Host vor der Docker-Installation ab und bricht bei Abweichung ab.

Das Bundle ist groß — ca. 25 GB

Der Großteil entfällt auf das vLLM-Image. Prüfen Sie vorab den Platz auf dem Übertragungsmedium und das Zielplattenkontingent.

Schritt 1 — Bundle beziehen (auf der Internetseite)

Vom Verteilserver werden Hauptdatei und vier Sidecar-Dateien, insgesamt fünf Dateien, bezogen.

ARCH=arm64   # 또는 amd64
B=plantpulse-ai-images-latest-$ARCH.tar.gz
for f in "$B" "$B.sha256" "$B.sha256.sig" "$B.pub" "$B.cosign.sha256"; do
  curl -fL -C - --retry 10 --retry-delay 5 --retry-all-errors \
    -O "https://product.kopens.io/plantpulse-ai/$f"
done

Datei	Was
`<번들>.tar.gz`	Hauptdatei
`.sha256`	Prüfsumme der Hauptdatei
`.sha256.sig`	cosign-Signatur zu dieser Prüfsumme — die Signatur hängt nicht an der mehrzig GB großen Hauptdatei, sondern an der Prüfsummendatei
`.pub`	öffentlicher Schlüssel zur Verifikation
`.cosign.sha256`	sha256 der im Bundle enthaltenen cosign-Ausführungsdatei (siehe unten „cosign im Bundle")

Bei Abbruch denselben Befehl erneut ausführen

-C - setzt fort, --retry-all-errors wiederholt. Große Dateien brechen gelegentlich durch CDN-seitige Fehler ab — ein erneuter Lauf setzt dort fort, wo die Übertragung endete.

Schritt 2 — Signatur verifizieren

Ein nicht verifiziertes Bundle wird nicht verwendet. Legen Sie die fünf bezogenen Dateien in ein Verzeichnis und verifizieren Sie dort.

sudo -i
mkdir -p /opt/kopens && tar -xzf "$B" -C /opt/kopens
bash /opt/kopens/plantpulse-ai-images/repo/bin/verify-bundle.sh "$B"

verify-bundle.sh prüft der Reihe nach Folgendes. Bei jeder Abweichung wird dort abgebrochen.

Ist cosign ausführbar — Reihenfolge COSIGN_BIN → cosign im PATH → tools/cosign-linux-<arch> im Bundle
Liegen die Sidecar-Dateien (.sha256 · .sha256.sig · öffentlicher Schlüssel) neben dem Bundle. Falls der öffentliche Schlüssel aus dem Repository und der bezogene .pub beide vorhanden sind, müssen sie bis auf das Byte übereinstimmen
Ist die Signatur gegenüber der Prüfsummendatei gültig
Entspricht der in der Prüfsummendatei vermerkte Name dem Namen dieses Bundles
Stimmen die Bytes des Bundles mit der signierten Prüfsumme überein

Exit-Code	Bedeutung
`0`	verifiziert
`1`	Verifikation fehlgeschlagen — Bundle nicht verwenden
`2`	konnte nicht verifiziert werden (Tool oder Sidecar fehlt) — kein Bestehen

cosign im Bundle und die Grenzen des Vertrauens

Im Air-Gap-Netzwerk fehlt cosign, daher führt das Bundle ein versionsfixiertes tools/cosign-linux-<arch> mit. Allerdings ist das cosign im Bundle nicht durch die Bundle-Signatur abgesichert — schließlich ist genau dieses Tool dasjenige, das die Signatur prüft. Deshalb wird dessen sha256 an drei Stellen hinterlegt.

Wo	Eigenschaft
Zeile `tools-cosign` der Bundle-Datei `MANIFEST.txt`	von uns erstellte Kopie
`<번들>.cosign.sha256` auf dem CDN	von uns erstellte Kopie. Liegt sie neben dem Bundle, gleicht `verify-bundle.sh` automatisch ab und schlägt bei Abweichung fehl
`cosign_checksums.txt` im Upstream-Sigstore	der einzige unabhängige Abgleich

Die ersten beiden bieten keinen Schutz gegen einen Angreifer, der Bundle und CDN gemeinsam verändern kann. Gleichen Sie auf der Internetseite einmal mit der Upstream-Prüfsumme ab, bevor Sie einspielen. Haben Sie ein separat vertrautes cosign, übergeben Sie es über COSIGN_BIN=/경로/cosign.

Schritt 3 — Ins Air-Gap-Netzwerk übertragen und einspielen

Übertragen Sie Hauptdatei und Sidecar-Dateien gemeinsam — das Einspiel-Skript verifiziert vor dem Laden erneut.

sudo -i
mkdir -p /opt/kopens && tar -xzf "$B" -C /opt/kopens
cd /opt/kopens/plantpulse-ai-images/repo/bin
BUNDLE_TARBALL="/경로/$B" ./airgap-import.sh

Entpackt sieht es so aus. Da die beiden zugehörigen Repositories gemeinsam im Bundle enthalten sind, müssen Sie nichts separat vorbereiten (welcher Commit es ist, steht in Zeile sibling von MANIFEST.txt).

/opt/kopens/plantpulse-ai-images/
├── repo/                                  ← 설치 본체 (bin · compose)
├── plantpulse-ai-inference-server/        ← 형제 저장소
├── plantpulse-timeseries-insight-server/  ← 형제 저장소
├── images/                                ← 이미지마다 docker save 한 파일 하나씩
├── pkgs/{rpm,deb}/                        ← Docker CE 오프라인 설치 패키지
├── tools/cosign-linux-<arch>
└── MANIFEST.txt

airgap-import.sh arbeitet die Schritte der Reihe nach ab. Schlägt ein Schritt fehl, bricht der Vorgang dort ab.

Schritt	Tätigkeit
0	Architekturabgleich · Verifikation der Bundle-Signatur (`verify-bundle.sh`)
1	Docker-Offline-Installation — nur wenn Docker fehlt. Ist es bereits vorhanden, bleiben Repository und Konfiguration unverändert, ohne Neustart (mit `ALLOW_DOCKER_RECONFIGURE=1` erlaubbar)
2	Image-Laden — nachdem alle `docker load` wurden, wird geprüft, ob sämtliche Image-Referenzen des Bundles über ihren Namen auflösbar sind
3	`install.sh`-Aufruf — `SKIP_LOGIN=1`. Keine Anbindung an eine Registry, Image-Pull und automatischer Modellbezug werden ebenfalls übersprungen

Bei nicht gefundenem Bundle wird abgebrochen

Da die Signatur über die Sidecar-Dateien neben dem Bundle geprüft wird, muss die tar.gz beim Einspielen vorhanden sein. Es wird eine im übergeordneten Verzeichnis (/opt/kopens) des entpackten Ordners gesucht; fehlt sie oder gibt es mehrere, wird mit BUNDLE_TARBALL zur expliziten Angabe aufgefordert und abgebrochen. Es gibt ALLOW_UNVERIFIED=1, das ohne Verifikation fortfährt, doch verwenden Sie es nicht — es ist ein Schalter, der ein unverifiziertes Bundle lädt.

Standard ist «bis zur Bereitschaft»

install.sh legt /etc/kopens/plantpulse-ai.env an und hält dort an. Soll der Start in einem Zug erfolgen, führen Sie zuerst export START=1 aus und dann airgap-import.sh. Wurde nur die Bereitschaft hergestellt, folgen Sie unten der „Startreihenfolge nach dem Einspielen" — das Installationsprogramm gibt am Ende dieselbe Reihenfolge aus.

Ab 2026.10 kommen zu den auszufüllenden Werten die Konfiguration zum Bezug der Plattform-Zugangsdaten (PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY) sowie der Plattform-Vertrauensanker /etc/kopens/ca/root.crt hinzu. Auch innerhalb des Air-Gap-Netzwerks muss der KI-Host :4950 des Plattform-Hosts erreichen können → Installationsübersicht

Startreihenfolge nach dem Einspielen

Verbliebene Platzhalter füllen. Die Ausgabe des Einspielvorgangs listet die noch als CHANGE_ME_* markierten Schlüssel (Admin- · Neo4j-Passwort, Plattform-Token, Plattform-Zugangsdatenschlüssel usw.). Korrigieren Sie /etc/kopens/plantpulse-ai.env mit sudo und belassen Sie die Berechtigungen bei 0600.
vLLM-Modelle ablegen — siehe unten „Modelle sind nicht im Bundle enthalten".
Mit bin/up.sh starten.

cd /opt/kopens/plantpulse-ai-images/repo
sudo bin/up.sh

Bleibt auch nur ein Platzhalter übrig, startet bin/up.sh nicht (2026.10)

Frühere Versionen verhinderten Platzhalter nur im Pfad von START=1 und berücksichtigten nicht den Weg über compose-up.sh im Nachhinein, wie im Air-Gap-Netzwerk üblich. Dadurch konnten Admin-Konsole und Neo4j mit den im öffentlichen Template vermerkten Passwörtern über LAN-Ports erreichbar sein. Jetzt listet bin/up.sh ebenfalls verbliebene Schlüsselnamen und verweigert den Start.

Verwenden Sie bin/update.sh nicht — es versucht, das Image zuerst zu beziehen, und schlägt daher im Air-Gap-Netzwerk ohne Registry fehl.

Host-weite Einstellungen folgen HOST_TUNING

install.sh ändert Locale · Zeitzone (PP_TZ) · Swap · chrony · limits · sysctl · tmpfiles · Firewall. Läuft auf dem Host bereits ein Container eines anderen Dienstes, ist der Standard plan, sodass nur Änderungen ausgegeben werden. Prüfen Sie die Ausgabe und führen Sie bei Bedarf erneut mit HOST_TUNING=apply aus → Installationsübersicht

Modelle sind nicht im Bundle enthalten

🔴 vLLM-Modelle (LLM · Embedding · Reranker, zusammen über 20 GB) sind nicht im Bundle enthalten. Die Online-Installation bezieht die Modelle bei START=1 automatisch, das Einspielen im Air-Gap-Netzwerk überspringt diesen Schritt.

vLLM-Modelle — auf einem Gerät mit Internetzugang über bin/fetch-models.sh beziehen. Es handelt sich um dieselben Release-Gewichte (model.kopens.ai), die auch die Online-Installation bezieht; nach Abgleich mit SHA256SUMS entpacken (zstd wird benötigt). Zielort MODEL_BASE, Name MODELS.
```
MODEL_BASE=/mnt/usb/models MODELS="Aura-Lite-NVFP4 Aura-Embedding-4B Aura-Reranker-0.6B" \
    bash /opt/kopens/plantpulse-ai-images/repo/bin/fetch-models.sh
```
Über ein Medium übertragen und auf dem Gerät im Air-Gap-Netzwerk unter /opt/kopens/models als gleichnamiges Verzeichnis ablegen (bei abweichendem Ort LLM_MODEL_PATH · EMB_MODEL_PATH · RERANK_MODEL_PATH in der Host-Umgebung setzen).
Zeitreihen-Inferenzmodell — nichts einzuspielen. Es ist bereits im plantpulse-timeseries-insight-server-Image enthalten.
Transkriptionsmodell (Aura-ASR-Turbo, ca. 1,5 GB) — nur einspielen, wenn Video-/Audio-Erfassung und Sprachabfrage genutzt werden sollen. Das Transkriptions-Image (plantpulse-asr-audio, Transkriptions-vLLM ist dasselbe Image wie das generative vLLM) ist stets im Bundle enthalten, nur das Modell muss übertragen werden. Auf einem internetfähigen Gerät wird es bei gesetztem Schalter in der Shell-Umgebung zusammen mit den vLLM-Modellen bezogen (bereits am Zielort vorhandene werden übersprungen).
```
PI_MEDIA_ENABLED=true MODEL_BASE=/mnt/usb/models \
    bash /opt/kopens/plantpulse-ai-images/repo/bin/fetch-models.sh
```
Über ein Medium übertragen und auf dem Gerät im Air-Gap-Netzwerk unter /opt/kopens/models/Aura-ASR-Turbo ablegen, dann PI_MEDIA_ENABLED=true in der Host-Umgebung setzen und starten → Video-/Audio-Erfassung. Soll nur der Name bezogen werden, genügt MODELS="Aura-ASR-Turbo". Auch ein Lauf mit COMPOSE_PROFILES=media gemäß früherer Anleitung bezieht weiterhin dieses Modell.

Nicht über download-model.sh beziehen

tools/download-model.sh im Repository des Inferenzservers bezieht die Upstream-Originalgewichte und versieht sie nur mit dem Namen Aura-*. Da der Name identisch ist, erkennt keine Prüfung den Unterschied, doch es handelt sich nicht um die Release-Gewichte. Verwenden Sie unbedingt bin/fetch-models.sh.

Startet der Stack ohne Modelle, erscheint er grün und nur das LLM bleibt aus. Prüfen Sie vor dem Start, ob die Modelle an Ort und Stelle sind.

Bundle selbst brennen

Nur erforderlich, wenn intern gebrannt werden muss statt das Bundle vom Verteilserver zu nutzen. Dies wird auf einem Gerät derselben Architektur wie das Ziel ausgeführt — es gibt keinen Cross-Build.

cd /opt/kopens/plantpulse-ai-docker/bin
./airgap-export.sh

Umgebungsvariable	Standardwert	Bedeutung
`ARCH`	dieser Host	`arm64` · `amd64`. Wird mit dem Host abgeglichen, bei Abweichung Abbruch
`OS_TARGET`	folgt der Architektur — `arm64` → `deb`, `amd64` → `rpm`	`rpm` · `deb` · `both` — das einzubettende Docker-Offline-Paket
`EXPORT_TAG`	heutiges Datum	nur für den Namen des Artefakts
`OUT_DIR`	`<저장소>/dist`	Ablageort des Artefakts

Die Artefakte sind dist/plantpulse-ai-images-<태그>-<아키텍처>.tar.gz und .sha256. Die Image-Liste wird über docker compose config --images ermittelt, daher wird sie nicht von Hand gepflegt — auch bei einem Modellwechsel oder einem vLLM-Versionsupgrade muss das Skript nicht angepasst werden. Die beiden zugehörigen Repositories werden ebenfalls genau in dem für das Brennen verwendeten Checkout-Stand mitgeliefert.

Selbst gebrannte Bundles sind unsigniert

Die Signatur (.sha256.sig) wird von der Release-Pipeline angebracht; beim manuellen Brennen wird der Signaturschritt übersprungen (im Log erscheint „Signatur übersprungen"). Unsignierte Bundles bestehen die Verifikation in Schritt 0 des Einspielens nicht, verwenden Sie daher ohne besonderen Grund das Bundle des Verteilservers.

Nach der Installation

Reihenfolge	Tätigkeit	Befehl · Dokumentation
1	Standardpasswort ändern	Erstes Passwort ändern
2	Prüfen, ob der Stack läuft	`bin/status.sh` · `bin/health.sh`
3	Engstellen identifizieren	`bin/doctor.sh`

Häufige Fallstricke

Symptom	Ursache	Maßnahme
`verify-bundle.sh` endet mit Exit-Code 2	cosign fehlt oder Sidecar-Dateien fehlen	Kein Bestehen. Sidecar-Dateien neben das Bundle legen und erneut verifizieren
Einspielen bricht mit „Bundle nicht gefunden" ab	tar.gz wurde nicht übertragen oder liegt woanders	mit `BUNDLE_TARBALL=/경로/<번들>.tar.gz` explizit angeben
Einspielen bricht wegen Architekturabweichung ab	Bundle falscher Architektur	zur `uname -m` passendes Bundle beziehen
Nach dem Laden Abbruch mit „Image nicht über Namen auflösbar"	Bundle-Defekt	dieses Bundle nicht verwenden, neues Bundle beziehen
Stack grün, nur LLM funktioniert nicht	Modelle wurden nicht eingespielt	siehe oben „Modelle sind nicht im Bundle enthalten"
Mit `PI_MEDIA_ENABLED=true` gestartet, aber nur `plantpulse-asr` startet nicht	Transkriptionsmodell (`Aura-ASR-Turbo`) wurde nicht eingespielt	siehe oben „Modelle sind nicht im Bundle enthalten", Abschnitt Transkriptionsmodell
Stack wird nur bereitgestellt, startet nicht	`START=1` wurde nicht angegeben	normales Verhalten. Werte gemäß oben „Startreihenfolge nach dem Einspielen" füllen und mit `bin/up.sh` starten
`bin/up.sh` bricht mit «still has template placeholders» ab	Platzhalter (`CHANGE_ME_*`) verblieben	ausgegebene Schlüssel füllen und erneut starten
`bin/update.sh` schlägt beim Image-Pull fehl	im Air-Gap-Netzwerk gibt es keine Registry	`bin/up.sh` verwenden
Host-Einstellungen wurden nicht geändert	Host, auf dem bereits andere Container laufen, war daher `HOST_TUNING=plan`	Ausgabe prüfen und bei Bedarf mit `HOST_TUNING=apply` erneut ausführen

Schritt 1 — Bundle beziehen (auf der Internetseite)​

Schritt 2 — Signatur verifizieren​

cosign im Bundle und die Grenzen des Vertrauens​

Schritt 3 — Ins Air-Gap-Netzwerk übertragen und einspielen​

Startreihenfolge nach dem Einspielen​

Modelle sind nicht im Bundle enthalten​

Bundle selbst brennen​

Nach der Installation​

Häufige Fallstricke​

Verwandte Dokumente​