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.

Die Webverwaltung für Integrationsschlüssel 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:

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:

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.
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.
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.
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.
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:

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. 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:

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 beschrieben.

Vor dem ersten Start auf dem Linux-Zielsystem prüfen:

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.

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.

8.8 KiB Raw Blame History Unescape Escape