159 lines
8.8 KiB
Markdown
159 lines
8.8 KiB
Markdown
# 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).
|
||
|
||
Die [Webverwaltung für Integrationsschlüssel](integration-keys.md) ergänzt die
|
||
env-basierte Maschinenanmeldung. Ihre SQLite und separate Schlüsseldatei müssen
|
||
ebenfalls gesichert werden; beide liegen standardmäßig unter der Fallablage.
|
||
|
||
## 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.
|