SIHub mit MariaDB betreiben

SIHub verwendet MariaDB für alle dauerhaft gespeicherten Plattformdaten: Benutzer, Arbeitsbereiche, Agenten, Einstellungen, Wissen, Gesprächsverläufe, Voice- und Verbrauchsdaten sowie die Benachrichtigungs-Outbox. Die Standarddatenbank heißt SIHub. DATABASE_URL ist Pflicht; ein fehlender oder ungültiger Wert schaltet nicht auf SQLite zurück. Apache bindet die App unter https://sihub.at ein und reicht Anfragen an 127.0.0.1:5090 weiter.

Datenhaltung und automatische Schemaaktualisierung

Alle Portal- und API-Schreibwege verwenden dieselbe konfigurierte MariaDB. Benutzerregistrierung, Teamverwaltung, Agentenanlage, Veröffentlichung und Änderungen an Einstellungen sind damit nach einem Neustart weiterhin vorhanden. Die Zuordnung der Daten ist:

MariaDB-Tabelle	Inhalt
workspaces	Arbeitsbereiche, Demokennzeichen und Arbeitsbereicheinstellungen als JSON in settings
users	Benutzer, Arbeitsbereichzuordnung, E-Mail, Passwort-Hash, Rolle und Aktivstatus
entities	Agenten, Wissen, Tools, Kanäle, Kontakte, Kampagnen, Aufgaben und Reviews; typabhängige Konfiguration als JSON in data
versions	Veröffentlichte Agentversionen mit vollständigem Konfigurationssnapshot
conversations, messages	Gespräche, Status, Zusammenfassungen, Ziele und Nachrichten/Transkripte
api_keys, audit, limits	Gehashte Plattform-API-Schlüssel, Berechtigungsbereiche, Änderungsprotokoll und Anfragezähler
outbox	Benachrichtigungsaufträge und deren Zustellstatus
voice_pending, voice_sessions, voice_events, voice_tool_calls	Voice-Lebenszyklus, Snapshots, Heartbeats und wiederholungssichere Ereignisse/Toolaufrufe
usage_ledger, voice_metrics	Verbrauchszähler, fixierte Preisstände, EUR-Schätzungen und Messwerte
_sihub_schema_migrations	Versionierter Schema- und Prüfstand des automatischen Abgleichs

JSON-Felder liegen ebenfalls in MariaDB; sie sind keine Dateien oder Browserablage. Betreiberzugänge zu KI-, Telefonie- und SMTP-Anbietern sowie Sitzungsschlüssel bleiben in der privaten Betreiberdatei. Redis koordiniert kurzlebige Gesprächskapazität; die dauerhaften Gespräche und Verbrauchsdaten liegen in MariaDB.

SIHub prüft das gesamte mitgelieferte Schema bei jedem Anwendungsstart. Der systemd-Dienst führt vor Gunicorn zusätzlich manage.py init-db aus. Der Abgleich verwendet eine datenbankspezifische MariaDB-Sperre, sodass mehrere startende Prozesse nicht gleichzeitig dieselbe Migration durchführen. Er ergänzt fehlende Tabellen, Spalten und Indizes und führt unterstützte, datenbewahrende Typvergrößerungen aus. Der Schema- und Prüfstand wird in MariaDB protokolliert; vorhandene Benutzer, Agenten und Einstellungen werden nicht neu angelegt oder überschrieben.

Ein Repository-Update mit anschließendem prepare beziehungsweise Dienstneustart genügt. Im Dockerbetrieb wird der neue Appstand gebaut und gestartet; dessen Start führt denselben Schemaabgleich aus. Es sind keine manuellen CREATE TABLE-Befehle für neue Funktionen nötig. Die MariaDB-Datenbank und das DB-Konto legt der Installer einmalig an; beim Start wird die vorhandene Verbindung verwendet. Für eine selbst verwaltete DB benötigt der SIHub-Benutzer neben den Datenrechten auch die Schemaänderungsrechte auf seiner eigenen Datenbank, insbesondere CREATE, ALTER und INDEX.

Der Abgleich löscht keine Tabellen oder Spalten und verkleinert keine Datentypen. Eine inkompatible Änderung, ein nicht sicher ergänzbares Pflichtfeld oder eine Indexkollision stoppt den Start mit einer Diagnose. Korrigiere in diesem Fall den beschriebenen Schema-/Datenkonflikt nach einer Sicherung; der Dienst arbeitet nicht mit einem ungeprüften Schema weiter. MariaDB kann DDL bereits vor einem Fehler dauerhaft übernehmen. Nach Behebung führt der nächste Abgleich die noch fehlenden Schritte idempotent aus.

Du kannst den Stand gezielt prüfen oder aktualisieren:

# Letzten Prüfbericht lesen, ohne Migration:
sudo bash apache2/install.sh manage schema-status
# Den vollständigen Schemaabgleich gezielt ausführen:
sudo bash apache2/install.sh manage init-db

schema-status verändert weder Schema noch Nutzdaten und gibt den zuletzt abgeschlossenen Prüfbericht sowie den erwarteten Codestand als JSON aus. Eine erneute vollständige Strukturprüfung führt init-db oder der Anwendungsstart aus. init-db meldet den Schemaabgleich und die ausgeführten Änderungen. Beide Befehle verwenden dieselben DB-Zugangsdaten wie der Dienst.

Apache-Schnellstart wie bei TattooHub

Der vollständige Ablauf steht im Repository unter apache2/README.md. Bringe den Checkout nach /var/www/SIHub; lege den DNS-A-Record auf deinen Server und stelle sicher, dass Port 80/443 erreichbar sind.

cd /var/www/SIHub
sudo apt update
sudo apt install -y apache2 certbot python3 python3-venv curl dnsutils mariadb-server mariadb-client
sudo systemctl enable --now mariadb
sudo mariadb -N -e 'SELECT VERSION();'
sudo bash apache2/install.sh prepare
sudo bash apache2/install.sh manage create-admin --email DEINE_ADMIN_EMAIL --workspace-name SIHub
curl --fail http://127.0.0.1:5090/health

Python 3.10+ und MariaDB 10.6+ sind erforderlich; die Vorlage für neue Datenbankserver wählt MariaDB 10.11. Das Setup installiert die Python-Abhängigkeiten unter /opt/sihub-venv, erstellt den Dienstbenutzer sihub und die private Betreiberdatei /etc/sihub/sihub.env. Es erzeugt sichere Sitzungs-/DB-Passwörter direkt in dieser Datei (Modus 0600). Über den lokalen MariaDB-Adminsocket erstellt es die Datenbank SIHub und ein eigenes sihub-DB-Konto, sofern beides noch nicht existiert. Eine funktionierende vorhandene MariaDB-Verbindung wird wiederverwendet; ein existierendes Konto oder eine existierende DB mit fehlerhaften Zugangsdaten wird nicht überschrieben.

Die Anwendung verwendet InnoDB mit UTF-8. /var/lib/sihub enthält private Arbeitsdateien und Sicherungen; dort wird keine SQLite-Datenbank angelegt. Das Setup installiert und startet sihub.service; Apache und Zertifikate richtest du nach Serveranleitung, Abschnitt 5 ein.

Eine alte .env, Quelldatenbank im Checkout oder ein fremder Listener auf Port 5090 führt bei der Erstinstallation zum Abbruch. Folge für vorhandene Konten der MariaDB-Übernahme. prepare --no-start bereitet den Dienst für einen Datenimport vor, ohne ihn zu starten.

Konfiguration und Verwaltungsbefehle

Der direkte Dienst und apache2/install.sh manage lesen dieselbe Datei /etc/sihub/sihub.env. Docker verwendet dagegen deploy/.env.production; lokale Entwicklung verwendet .env. Die technischen AIHUB_*-Variablennamen bleiben erhalten.

DATABASE_URL=mariadb+pymysql://sihub:URLENCODED_PASSWORT@127.0.0.1:3306/SIHub
AIHUB_ENV=production
AIHUB_LOAD_DOTENV=0
AIHUB_PUBLIC_URL=https://sihub.at
AIHUB_SECURE_COOKIES=1
AIHUB_TRUST_PROXY=1
AIHUB_LIVE_ENABLED=0

Trage Zugangsdaten im privaten Editor ein; Passwörter und DSNs gehören nicht als Argumente in die Shellhistorie. Sonderzeichen im DSN-Passwort müssen URL-kodiert sein. Der Generator verwendet sichere Hexwerte. API-/SMTP-/Telefoniekeys ergänzt du ebenfalls in der Betreiberdatei.

sudoedit /etc/sihub/sihub.env
sudo bash apache2/install.sh manage check-config
sudo systemctl restart sihub
sudo bash apache2/install.sh manage schema-status
sudo bash apache2/install.sh manage list-workspaces
sudo bash apache2/install.sh manage purge --dry-run

Die direkte Websiteeinrichtung startet noch keine Realtime-Voiceworker. Für den vollständigen Telefonie-Stack enthält Server-Setup den Dockerpfad mit MariaDB 10.11, Redis und getrennten LiveKit-Workern. Die DB und Redis erhalten keine öffentlichen Ports. Ein alter PostgreSQL-/SQLite-Betrieb gehört nicht zur neuen Produktionskonfiguration.

Sicherung und Updates

Die Sicherung verwendet mariadb-dump mit einer privaten temporären Clientdatei. Passwort und DSN erscheinen nicht als Prozessargumente. Die Ausgabe ist ein konsistenter SQL-Dump mit Schema und Daten; vorhandene Sicherungsdateien werden nicht überschrieben. Der direkte Helfer schreibt standardmäßig nach /var/lib/sihub/backups, der Dockerhelfer nach /var/backups/sihub.

# Direkter Apachebetrieb:
sudo bash apache2/backup-mariadb.sh
# Dockerbetrieb:
sudo bash deploy/backup-mariadb.sh

Sichere die Betreiberdatei und den freigegebenen Software-/Imagestand zusätzlich getrennt und verschlüsselt. Der Dump enthält personenbezogene Daten und Authentifizierungs-Hashes, aber keine Betreiberdatei oder Sitzungsschlüssel. Redis-AOF ersetzt keinen MariaDB-Dump. MariaDB-Dump-Dokumentation

Ein direktes Update erfolgt nach einer frischen Sicherung:

cd /var/www/SIHub
sudo systemctl stop sihub
sudo bash apache2/backup-mariadb.sh
sudo git pull --ff-only
sudo bash apache2/install.sh prepare
sudo bash apache2/install.sh manage schema-status
curl --fail https://sihub.at/health

Verwende git pull als Eigentümer des Checkouts. Beim erneuten Setup bleiben vorhandene Betreiberkeys und Datenbankzugangsdaten erhalten. prepare installiert die aktuelle Dienstvorlage, gleicht das Schema ab und startet SIHub. Bei unverändertem Python-/Dienstsetup genügt nach dem Codeupdate sudo systemctl restart sihub; auch dieser Start prüft und erweitert das Schema. Im Dockerbetrieb baust du nach einer Sicherung neue Images und startest sie mit up -d; docker compose down --volumes ist kein Updatebefehl, weil er Datenvolumes löscht.

Restore zuerst in einer separaten Datenbank prüfen

Ein Restoretest überschreibt keine laufende Datenbank. Ersetze DEIN_BACKUP.sql durch die konkrete Sicherung. Die Umleitung erfolgt in einer Rootshell, weil Dumps Modus 0600 haben. Eine existierende Prüf-DB lässt CREATE DATABASE scheitern; lösche sie nicht automatisch.

Für eine lokale MariaDB mit Adminzugriff über den Unixsocket:

sudo -i
mariadb -e 'CREATE DATABASE `SIHub_restore_check` CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;'
mariadb SIHub_restore_check < /var/lib/sihub/backups/DEIN_BACKUP.sql
mariadb SIHub_restore_check -e 'SELECT COUNT(*) FROM workspaces; SELECT COUNT(*) FROM users; SELECT COUNT(*) FROM conversations;'
exit

Für den Composecontainer verwendet das Rootpasswort nur die Umgebung des Kindprozesses:

sudo -i
cd /var/www/SIHub
docker compose --env-file deploy/.env.production -f deploy/compose.yml exec -T mariadb sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb --user=root -e "CREATE DATABASE SIHub_restore_check CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;"'
docker compose --env-file deploy/.env.production -f deploy/compose.yml exec -T mariadb sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb --user=root SIHub_restore_check' < /var/backups/sihub/DEIN_BACKUP.sql
docker compose --env-file deploy/.env.production -f deploy/compose.yml exec -T mariadb sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb --user=root SIHub_restore_check -e "SELECT COUNT(*) FROM workspaces; SELECT COUNT(*) FROM users; SELECT COUNT(*) FROM conversations;"'
exit

Vergleiche Zeilenzahlen mit dem Sicherungszeitpunkt. Prüfe anschließend Anmeldung, Wissen, Versionen, Gesprächsverläufe und Exporte in einer isolierten SIHub-Instanz mit ausgeschaltetem Livebetrieb. Für deren DB-Benutzer sind passende Rechte auf der Prüf-DB erforderlich. Der reine Zeilenvergleich beweist noch keine erfolgreiche Anmeldung.

Im echten Wiederherstellungsfall stoppe zuerst SIHub, eigene Voiceworker und Wartungstimer, sichere den aktuellen Stand und importiere in eine neue DB. Erteile dem vorhandenen SIHub-DB-Benutzer Rechte auf diese DB und ändere ausschließlich den Datenbanknamen in DATABASE_URL. Setze AIHUB_LIVE_ENABLED=0, prüfe Konfiguration/Schema und starte die App erst danach. Alte Datenbank und Sicherung bleiben erhalten; laufende Telefonräume werden durch einen Restore nicht wiederhergestellt.

Wartung und Diagnose

Retention löscht Daten erst nach Ausführung von manage.py purge; prüfe zuvor purge --dry-run. Die Compose-Wartungsdienste und Timer unter deploy/systemd/ verwenden dieselbe Betreiberumgebung wie die App. Notifications und Voice-Reaper werden erst nach Anbieter-/Arbeitsbereichfreigabe aktiviert; Details stehen in Server-Setup. Alte apache2/aihub-*-Timervorlagen benötigen für den direkten sihub-Dienst die passende Anpassung von Benutzer, Interpreter und Betreiberdatei.

sudo journalctl -u sihub -n 100 --no-pager
sudo apache2ctl -S
sudo tail -n 50 /var/log/apache2/sihub-error.log
curl --fail https://sihub.at/health

/health bestätigt Anwendungs-/Datenbank-Liveness. Die Liveprüfung von Telefonie, Providern und 20 parallelen Gesprächen erfolgt separat nach Kapazitätsabnahme.