Add Linux deployment installer, supervised services and readiness checks
This commit is contained in:
Nico committed
1 parent
203e765992
commit
ca4ab48fdc
15 files changed
+578
-4
No files matched your search
@@ -0,0 +1,154 @@
|
||||
# Linux-Betrieb
|
||||
|
||||
API und Analyseworker laufen als getrennte systemd-Dienste. Ein Auftragseingang
|
||||
weckt keinen neuen Prozess: Der dauerhaft laufende Worker übernimmt Inbox-Aufträge.
|
||||
Die Weboberfläche ist eine alternative Bedienung desselben Arbeitsablaufs.
|
||||
Die Installation startet keine Dienste und führt keine Modellanfrage aus.
|
||||
|
||||
## Voraussetzungen und Verzeichnisse
|
||||
|
||||
Linux mit systemd, Python 3.11 oder neuer inklusive venv/pip, Git und Nginx.
|
||||
Diese Programme über die Paketverwaltung des Servers installieren. Die aktuelle
|
||||
Projektvorlage ist für WoW/Vcore eingerichtet; sie ist kein allgemeiner Adapter.
|
||||
|
||||
| Pfad | Zweck und Rechte |
|
||||
| --- | --- |
|
||||
| `/opt/viano-bug-analysis` | Root-eigener Checkout und virtuelle Python-Umgebung; Dienst darf nur lesen |
|
||||
| `/etc/viano-bug-analysis` | Root-eigene Konfiguration, Gruppe `buganalysis`, Verzeichnis 0750, Dateien 0640 |
|
||||
| `/etc/viano-bug-analysis/*.env` | Zugangsdaten, root:buganalysis 0600; systemd liest sie vor dem Benutzerwechsel |
|
||||
| `/etc/viano-bug-analysis/auth/users.sqlite3` | Root-verwaltete Nutzer, Gruppe `buganalysis` darf lesen |
|
||||
| `/var/lib/viano-bug-analysis` | Dienst-eigene Fallakten, Laufzeitdaten und Websessions |
|
||||
| `/srv/viano-bug-analysis/viano-core` | Root-eigener Source-Checkout, Dienst hat Leserechte |
|
||||
|
||||
Die env-Dateien sind durch Betriebssystemrechte geschützte Klartextdateien, kein
|
||||
verschlüsselter Tresor. Sie gehören nicht ins Repository oder in Diagnosepakete.
|
||||
API und Worker erhalten unterschiedliche Dateien: Nur der Worker erhält Cloud-
|
||||
und DB-Zugangsdaten. Die Diensthärtung und EnvironmentFile-Nutzung folgen der
|
||||
[systemd-Dokumentation](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html).
|
||||
|
||||
## Installation
|
||||
|
||||
Den vertrauenswürdigen BugAnalysis-Checkout als root unter
|
||||
`/opt/viano-bug-analysis` ablegen. Code und Unterverzeichnisse dürfen nicht für
|
||||
andere Benutzer schreibbar sein. Dann:
|
||||
|
||||
```sh
|
||||
cd /opt/viano-bug-analysis
|
||||
python3 deploy/install.py --dry-run
|
||||
sudo python3 deploy/install.py
|
||||
```
|
||||
|
||||
Der Installer legt den Dienstbenutzer `buganalysis`, Konfigurationen, venv und
|
||||
Units an. Er installiert die Python-Abhängigkeiten und lädt systemd neu.
|
||||
Bestehende Zielkonfigurationen und Units werden erhalten. Updates an bereits
|
||||
installierten Units daher bewusst mit den versionierten Vorlagen abgleichen.
|
||||
Bei Installationsfehlern bleiben vorhandene Dateien erhalten; erneutes Ausführen
|
||||
setzt die Einrichtung fort. Der Installer verändert keine bestehende Datenbank.
|
||||
|
||||
## Einmalige Konfiguration
|
||||
|
||||
Mit `sudoedit` die Dateien unter `/etc/viano-bug-analysis` bearbeiten:
|
||||
|
||||
1. `project.toml`: DB-Adresse/Port, Datenbank und nur lesenden Benutzer einstellen,
|
||||
tatsächliche Snapshotkennung und vollständigen Source-Commit eintragen.
|
||||
Die ausgelieferten Null-Commit- und `CONFIGURE_ME`-Werte sind Platzhalter.
|
||||
2. Den Vcore-Checkout als root unter `/srv/viano-bug-analysis/viano-core` anlegen;
|
||||
der konfigurierte Commit muss lokal vorhanden und für `buganalysis` lesbar sein.
|
||||
Der Dienst lädt keine Commits nach. `gitconfig` vertraut ausschließlich diesem
|
||||
konkreten Root-Checkout, nicht beliebigen Repositories.
|
||||
3. `worker.env`: `GEMINI_API_KEY=...` und `VIANO_DB_PASSWORD=...` eintragen.
|
||||
Keine `export`-Anweisungen verwenden. Für Sonderzeichen gelten die
|
||||
EnvironmentFile-Quotingregeln von systemd. Werte nicht als Shellargumente übergeben.
|
||||
4. `api.env`: `VBA_INTAKE_TOKEN=...` für den Erfassungsworker setzen
|
||||
(32–256 Zeichen aus Buchstaben, Ziffern, `_` und `-`). Dies ist ein separater
|
||||
Integrationsschlüssel, kein Gemini-Key. Wird keine externe API-Integration
|
||||
benötigt, den zugehörigen `[[clients]]`-Block aus `api.toml` entfernen.
|
||||
5. `llm.toml`: gewünschtes Modell, Anbieter und Cacheeinstellungen kontrollieren.
|
||||
Investigation-, Budget- und Telemetrie-Dateien sind separat konfigurierbar.
|
||||
|
||||
Die DB-Verbindung benötigt einen Benutzer mit ausschließlich passenden
|
||||
SELECT-Rechten auf die freigegebenen World-Tabellen. Diese Rechte legt der
|
||||
DB-Administrator an; BugAnalysis vergibt keine Grants. Der Readiness-Test belegt
|
||||
Lesbarkeit, nicht die Abwesenheit zusätzlicher Schreibrechte. Für entfernte DBs
|
||||
einen geschützten Netzwerkweg verwenden: Der aktuelle DB-Provider konfiguriert
|
||||
selbst kein TLS. Zugang zu Produktionsdaten ist für die lokale Entwicklung
|
||||
weiterhin nicht erforderlich.
|
||||
|
||||
Webnutzer anlegen; das Passwort wird verdeckt abgefragt:
|
||||
|
||||
```sh
|
||||
sudo /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.api create_user NAME --config /etc/viano-bug-analysis/api.toml --service-group buganalysis
|
||||
```
|
||||
|
||||
Nutzerverwaltung bleibt root vorbehalten. Siehe [Nutzerverwaltung](user-accounts.md).
|
||||
Keine Nutzer werden automatisch angelegt. Nach der Installation besitzen die
|
||||
env-Dateien Modus 0600; diese Rechte nach manuellen Änderungen erhalten.
|
||||
|
||||
## Kostenfreie Bereitschaftsprüfung
|
||||
|
||||
Die Prüfung unter der tatsächlichen Dienstidentität samt env-Datei ausführen:
|
||||
|
||||
```sh
|
||||
sudo systemd-run --wait --pipe --collect --property=User=buganalysis --property=Group=buganalysis --property=EnvironmentFile=/etc/viano-bug-analysis/api.env /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check --role api --config /etc/viano-bug-analysis/api.toml
|
||||
sudo systemd-run --wait --pipe --collect --property=User=buganalysis --property=Group=buganalysis --property=EnvironmentFile=/etc/viano-bug-analysis/worker.env --setenv=GIT_CONFIG_GLOBAL=/etc/viano-bug-analysis/gitconfig /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check --role worker --config /etc/viano-bug-analysis/worker.toml
|
||||
```
|
||||
|
||||
Erwartet: `READY`, `model_requests: 0`. Geprüft werden Konfiguration,
|
||||
Zugangsdaten-Präsenz, Speicherreserve, Schreibbarkeit der Laufzeitablage,
|
||||
Webnutzer/Sessions beziehungsweise Git-Objekte und die freigegebenen DB-Schemata.
|
||||
Cloud-Key-Gültigkeit und Modellverfügbarkeit sind damit noch nicht getestet.
|
||||
`--offline` überspringt Git-/DB-Zugriffe und meldet nur `CONFIG_READY`.
|
||||
Fehlerausgaben enthalten kontrollierte Fehlercodes statt Zugangsdaten.
|
||||
|
||||
## HTTPS und Start
|
||||
|
||||
Die API bleibt auf `127.0.0.1:8080`. `nginx.conf.example` enthält eine
|
||||
Reverse-Proxy-Vorlage: Domain und Zertifikatpfade anpassen, gültiges Zertifikat
|
||||
bereitstellen und als Nginx-Site installieren. Die Vorlage übernimmt die
|
||||
Forwarded-Header kontrolliert; die API vertraut ihnen ausschließlich vom
|
||||
Loopback-Proxy. So verwenden Anmeldung und Cookies das öffentliche HTTPS-Schema.
|
||||
Die Proxyparameter sind in der
|
||||
[Nginx-Dokumentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) beschrieben.
|
||||
|
||||
Vor dem ersten Start auf dem Linux-Zielsystem prüfen:
|
||||
|
||||
```sh
|
||||
sudo systemd-analyze verify /etc/systemd/system/viano-bug-analysis-api.service /etc/systemd/system/viano-bug-analysis-worker.service
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
sudo systemctl enable --now viano-bug-analysis-api.service viano-bug-analysis-worker.service
|
||||
sudo systemctl status viano-bug-analysis-api.service viano-bug-analysis-worker.service
|
||||
```
|
||||
|
||||
Sobald der Worker aktiviert ist, kann er vorhandene Aufträge verarbeiten und
|
||||
kostenpflichtige Modellaufrufe senden. Erst mit leerem Eingang starten, dann einen
|
||||
kontrollierten Feldtest über die Übergabe-API oder Weboberfläche übergeben.
|
||||
Anmeldung, Auftragsannahme, Fortschritt, menschliche Testanfrage und Outbox dabei
|
||||
gemeinsam prüfen. Die automatisierte Einrichtung ersetzt diesen Feldtest nicht.
|
||||
|
||||
## Laufender Betrieb
|
||||
|
||||
Die Dienste starten beim Booten und nach unerwartetem Prozessende erneut.
|
||||
Fehlende Startvoraussetzungen werden nach zehn Sekunden erneut geprüft.
|
||||
Externe DB und Sourcebereitstellung werden nicht von diesen Units installiert.
|
||||
API und Worker können unabhängig voneinander laufen.
|
||||
|
||||
```sh
|
||||
sudo journalctl -u viano-bug-analysis-api -u viano-bug-analysis-worker -f
|
||||
sudo systemctl stop viano-bug-analysis-worker
|
||||
```
|
||||
|
||||
Der Worker beendet beim Stoppen den aktuellen Dispatch kontrolliert; seine Unit
|
||||
setzt dafür kein hartes Stop-Zeitlimit. Ein Stop kann daher während einer
|
||||
langlaufenden Anfrage dauern. Für Code-/Profiländerungen den Worker zuerst
|
||||
anhalten. Profilbindungen laufender Fälle nicht beiläufig ändern: Unterschiede
|
||||
werden als Aufmerksamkeit erfordernder Zustand behandelt, Budgets nicht erneuert.
|
||||
Codeänderungen danach in die root-eigene venv installieren und Dienste neu starten.
|
||||
|
||||
Backups umfassen die Fallablage, Konfiguration einschließlich geschützter Secrets
|
||||
und Nutzer-SQLite. Für eine einfache konsistente Dateisicherung beide Dienste
|
||||
anhalten. Sessions sind keine dauerhaft nötigen Fachdaten. Produktive Fallaufbewahrung
|
||||
separat festlegen; das 20-GB-Entwicklungslimit ist kein Produktionslimit.
|
||||
|
||||
Unter Windows bleibt die vorhandene PowerShell-Umgebungsvariable für Entwicklung
|
||||
unterstützt. Dort installiert dieser Installer keine Dienste; `--dry-run` ist möglich.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Linux-Betriebspaket – lokale Prüfung 2026-10-22
|
||||
|
||||
Ziel: getrennte API-/Worker-Dienste, persistente geschützte Zugangsdaten,
|
||||
Installation ohne automatische Aktivierung und Bereitschaftsprüfung ohne LLM.
|
||||
|
||||
Änderungen: `deploy/install.py`, Linux-Konfigurationsvorlagen, beide systemd-Units,
|
||||
`viano_bug_analysis.deployment` sowie explizite Loopback-Proxy-Vertrauensgrenze
|
||||
beim API-Start. Anleitung: `docs/linux-deployment.md`.
|
||||
|
||||
Validierung auf Windows mit Python aus `.venv`:
|
||||
|
||||
```text
|
||||
python -m pytest tests/test_deployment.py tests/test_web_auth.py tests/test_worker.py tests/profiles/vcore/test_worker_intake.py -q
|
||||
31 passed, 1 dependency deprecation warning
|
||||
git diff --check: keine Whitespacefehler
|
||||
```
|
||||
|
||||
Prüfumfang: Installer-Dry-Run ohne Seiteneffekte, TOML-Vorlagen und Dateiverweise,
|
||||
getrennte env-Dateien und Unit-Härtung, API-Start mit/ohne erforderliche
|
||||
Zugangsdaten, Worker-Leseprüfung mit kontrollierten Git-/DB-Testdoubles,
|
||||
Offline-Modus, keine Modellanfrage, sichere Fehlerausgabe, HTTPS-Login-Cookie
|
||||
über Uvicorns Proxy-Middleware, bestehende Nutzer-/Worker-/Intake-Tests.
|
||||
|
||||
Vor den Tests: Trial-Workspaces 16.939.129.428 Bytes, kuratiertes Fehlerkorpus
|
||||
2.471.041 Bytes. Nur kleine synthetische Tempdateien; keine Paketkopien oder neuen
|
||||
LLM-Trials. Das Entwicklungsbudget von 20 GB bleibt eingehalten.
|
||||
|
||||
Keine Cloud-/DB-Zugangsdaten im Bericht. Keine realen LLM-Aufrufe oder neuen
|
||||
Abrechnungskosten. Keine Installation, Dienstaktivierung oder Serveränderung.
|
||||
Native systemd-/Nginx-Prüfung und produktiver End-to-End-Test stehen aus:
|
||||
Auf dieser Windows-Umgebung ist kein nutzbares Linux/systemd vorhanden.
|
||||
Reference in new issue
Block a user