sendnrw/glpi-ai-knowledgebase
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e5bc62ebf226b6095a14923203c7dfc1546750dc
glpi-ai-knowledgebase/README.md
jbergner e5bc62ebf2
All checks were successful
release-tag / release-image (push) Successful in 1m35s
Details
init
2026-07-28 23:11:40 +02:00

10 KiB
Raw Blame History

KB Helpdesk – Editor & Google-Modus

Ein einziges Go-/Docker-Image für zwei Rollen auf derselben JSON-Wissensbasis:

  1. Editor-Modus – vollständiger Einzel- und Masseneditor mit Backups.
  2. Google-Modus – moderne, schreibgeschützte interne Helpdesk-Suche mit Artikel-Viewer.

Der Betriebsmodus wird ausschließlich über APP_MODE gewählt. Es ist kein zweiter Build und kein anderes Image nötig.

Modi

APP_MODE=editor

Der bekannte Administrationsmodus:

  • Volltextsuche über ID, Titel, Text, Antwort, Keywords, Kategorien, Quelle und Pfad
  • Filter für auto_reply, Sprache, Kommunikationsstil und Quelle
  • Pagination für große Bestände mit 10.000+ Dateien
  • Einzelbearbeitung als Formular
  • vollständiger Raw-JSON-Editor
  • Massenbearbeitung für Auswahl oder alle aktuellen Treffer
  • Bulk-Setzen von auto_reply, min_score, language, communication_style, source, source_uri
  • Keywords/Kategorien hinzufügen oder entfernen
  • Suchen & Ersetzen in title, text und answer, optional per Regex
  • Dry-Run/Vorschau vor Massenänderungen
  • automatische Backups
  • atomisches Schreiben per Temp-Datei + Rename
  • Schutz vor extern veränderten Dateien

APP_MODE=google

Reiner Helpdesk-/Viewer-Modus:

  • große, reduzierte Suchoberfläche im Stil einer internen Suchmaschine
  • Relevanzranking statt alphabetischer Trefferreihenfolge
  • Gewichtung von ID/Fehlercode, Titel, Keywords, Kategorien, Problemtext und Antwort
  • hervorgehobene Suchbegriffe
  • Treffer-Auszüge aus Problem bzw. Lösung
  • dynamische Schnellzugriffe aus den häufigsten Kategorien
  • Pagination und URL-basierte Suchanfragen
  • lesefreundlicher Artikel-Viewer
  • Problem und Lösung visuell getrennt
  • Antwort direkt in die Zwischenablage kopieren
  • dauerhafter Link zu einem geöffneten Wissensartikel
  • Quellenlink, sofern source_uri vorhanden ist
  • responsive Oberfläche für Desktop, Tablet und Smartphone
  • automatisches Neu-Einlesen des Dateiindex (standardmäßig alle 60 Sekunden)
  • keine Bearbeitungsoberfläche
  • PUT-/Bulk-/Reload-Endpunkte werden serverseitig mit HTTP 403 gesperrt

viewer und search werden zusätzlich als Alias für google akzeptiert. Für Deployments sollte aus Gründen der Eindeutigkeit editor oder google verwendet werden.

Schnellstart

cp .env.example .env
docker compose up --build -d

Danach:

http://localhost:8080

Editor-Deployment

.env:

APP_MODE=editor
APP_TITLE=Knowledge Base Editor
APP_SUBTITLE=JSON · Massenbearbeitung · Docker

KB_DATA_PATH=../glpi-ai-agent-kb-microsoft-errorcodes-kompendium/knowledge
KB_DATA_MOUNT_MODE=rw
KB_BACKUP_PATH=./backups
KB_EDITOR_PORT=8080

BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=ein-langes-zufaelliges-passwort

Wichtig: Der Editor benötigt für das Knowledge-Verzeichnis rw.

Google-/Helpdesk-Deployment

Dasselbe Image, nur andere ENV-Werte:

APP_MODE=google
APP_TITLE=IT Helpdesk Wissen
APP_SUBTITLE=Interne Lösungsdatenbank für Support und Service Desk
AUTO_RELOAD_INTERVAL=60s

KB_DATA_PATH=../glpi-ai-agent-kb-microsoft-errorcodes-kompendium/knowledge
KB_DATA_MOUNT_MODE=ro
KB_BACKUP_PATH=./backups
KB_EDITOR_PORT=8081

BASIC_AUTH_USER=helpdesk
BASIC_AUTH_PASSWORD=ein-langes-zufaelliges-passwort

Für den Google-Modus wird KB_DATA_MOUNT_MODE=ro empfohlen. Damit existieren zwei Schutzschichten:

  1. Die Go-Anwendung stellt keine schreibende Funktion bereit und blockiert die schreibenden API-Endpunkte.
  2. Docker mountet die JSON-Dateien zusätzlich read-only.

Der Backup-Pfad wird im Google-Modus nicht benutzt; er bleibt nur Teil derselben Compose-Konfiguration.

Ein Image, zwei Container

Als fertiges Beispiel liegt docker-compose.dual.yml bei. Es startet denselben Build gleichzeitig als Editor auf Port 8080 und als read-only Helpdesk-Suche auf Port 8081:

docker compose -f docker-compose.dual.yml up --build -d

Alternativ kann ein gebautes Image manuell zweimal gestartet werden:

docker build -t kb-helpdesk:local .

Editor:

docker run -d \
  --name kb-editor \
  -p 8080:8080 \
  -e APP_MODE=editor \
  -e APP_TITLE="KB Administration" \
  -v /srv/kb/knowledge:/data/knowledge:rw \
  -v /srv/kb/backups:/data/backups:rw \
  kb-helpdesk:local

Helpdesk-Suche:

docker run -d \
  --name kb-search \
  -p 8081:8080 \
  -e APP_MODE=google \
  -e APP_TITLE="IT Helpdesk Wissen" \
  -e APP_SUBTITLE="Interne Lösungsdatenbank" \
  -v /srv/kb/knowledge:/data/knowledge:ro \
  kb-helpdesk:local

Beide Container lesen damit denselben Bestand. Im Google-Modus wird der Dateiindex standardmäßig alle 60 Sekunden automatisch neu aufgebaut, sodass Änderungen aus dem Editor ohne Container-Neustart sichtbar werden. Mit AUTO_RELOAD_INTERVAL=0 kann das deaktiviert werden. Der Editor besitzt zusätzlich einen manuellen Reload-Button.

Konfiguration

Variable Standard Bedeutung
APP_MODE editor editor oder google; zusätzlich Aliase viewer/search
APP_TITLE modusabhängig Name in Browser und Kopfzeile
APP_SUBTITLE modusabhängig Untertitel/Helpdesk-Beschreibung
AUTO_RELOAD_INTERVAL Google: 60s, Editor: aus Dateiindex regelmäßig neu aufbauen; 0/off deaktiviert
DATA_DIR ./data/knowledge Wurzelverzeichnis der JSON-Dateien
BACKUP_DIR .kb-editor-backups neben dem Datenordner Backup-Ziel im Editor-Modus
LISTEN_ADDR :8080 HTTP Listen-Adresse
BASIC_AUTH_USER leer Optionaler Basic-Auth-Benutzer
BASIC_AUTH_PASSWORD leer Optionales Basic-Auth-Passwort
KB_DATA_PATH ./knowledge Hostpfad für Docker Compose
KB_DATA_MOUNT_MODE rw rw für Editor, empfohlen ro für Google-Modus
KB_BACKUP_PATH ./backups Hostpfad für Backups
KB_EDITOR_PORT 8080 veröffentlichter Host-Port

Suche und Ranking im Google-Modus

Eine Suche muss alle eingegebenen Suchbegriffe im indexierten Dokument finden. Anschließend werden die Treffer gewichtet. Besonders hoch bewertet werden:

  1. exakte ID-/Fehlercode-Treffer,
  2. Titel,
  3. Keywords,
  4. Kategorien,
  5. Problem-/Erkennungstext,
  6. Antwort/Lösung,
  7. Quelle.

Dadurch steht beispielsweise ein Artikel mit 0x80070005 direkt in ID/Titel vor einem Artikel, der denselben Code nur beiläufig im Lösungstext erwähnt.

Die Such-URL ist teilbar:

/?q=0x80070005

Ein geöffneter Artikel erhält zusätzlich doc=<interner-key> und kann so intern direkt verlinkt werden.

Tastatur

Im Google-Modus fokussiert / von überall die Suche.

Im Editor gelten zusätzlich die bereits vorhandenen Tastaturfunktionen, unter anderem Ctrl+S/Cmd+S zum Speichern.

JSON-Verhalten

Die Anwendung arbeitet direkt mit .json-Dateien. Für Suche und Navigation liegt ein Index im RAM. Unbekannte zusätzliche JSON-Felder bleiben beim Bearbeiten erhalten.

Das bekannte Schema kann beispielsweise enthalten:

{
  "id": "KB-MSERR-...",
  "title": "...",
  "text": "...",
  "answer": "...",
  "auto_reply": true,
  "min_score": 0.78,
  "categories": ["Windows"],
  "keywords": ["0x80070005"],
  "source": "Microsoft Learn",
  "source_uri": "https://learn.microsoft.com/...",
  "language": "de-DE",
  "communication_style": "formal"
}

Backups im Editor-Modus

Bei einem normalen Speichern entsteht ein Zeitstempelverzeichnis, zum Beispiel:

backups/
└── 20260728-153012.123456789/
    └── KB-MSERR-ACT-00001.json

Bei einer Massenänderung werden alle Originaldateien desselben Vorgangs gemeinsam gesichert. Die relative Unterverzeichnisstruktur bleibt erhalten.

Backups werden nicht automatisch gelöscht.

Externe Dateiänderungen

Der Editor erkennt beim Speichern, wenn die betreffende Datei seit dem Indexieren außerhalb der Anwendung verändert wurde. In diesem Fall wird das Überschreiben verweigert.

Der Index wird beim Prozessstart aufgebaut. Im Google-Modus wird er standardmäßig alle 60 Sekunden erneut aus den Dateien aufgebaut. Das Intervall lässt sich mit AUTO_RELOAD_INTERVAL ändern (30s, 2m usw.); Werte unter fünf Sekunden werden abgelehnt. Im Editor erfolgt kein automatischer Reload, damit laufende Bearbeitungen nicht überraschend überlagert werden; dort steht „Neu einlesen“ zur Verfügung.

API

Lesend in beiden Modi:

  • GET /api/health
  • GET /api/config
  • GET /api/items?q=...&page=1&page_size=60
  • GET /api/search?q=...&page=1&page_size=20
  • GET /api/facets?limit=10
  • GET /api/items/{key}

Nur im Editor-Modus:

  • PUT /api/items/{key}
  • POST /api/bulk
  • POST /api/reload

Im Google-Modus antworten diese drei Endpunkte mit HTTP 403 Forbidden.

Sicherheit

Für interne Remote-Nutzung sollte mindestens Basic Auth aktiviert und die Anwendung hinter einem Reverse Proxy mit TLS veröffentlicht werden.

Das Compose-Setup:

  • startet das Container-Root-Filesystem read-only,
  • entfernt Linux-Capabilities,
  • setzt no-new-privileges,
  • verwendet /tmp als kleines tmpfs,
  • kann den Knowledge-Mount im Google-Modus zusätzlich read-only einbinden.

Die Oberfläche hat keine externen CDN-/JavaScript-Abhängigkeiten.

Ohne Docker

Voraussetzung: Go 1.23 oder neuer.

Editor:

APP_MODE=editor go run ./cmd/server -data /pfad/zum/knowledge

Google-Modus:

APP_MODE=google \
APP_TITLE="IT Helpdesk Wissen" \
APP_SUBTITLE="Interne Wissenssuche" \
go run ./cmd/server -data /pfad/zum/knowledge

Tests/Build:

go test ./...
go vet ./...
go build -o kb-helpdesk ./cmd/server

Projektstruktur

.
├── cmd/server/
│   ├── app.go
│   ├── main.go
│   ├── web/              # Editor-Oberfläche
│   │   ├── index.html
│   │   ├── app.js
│   │   └── style.css
│   └── viewer/           # Google-/Helpdesk-Oberfläche
│       ├── index.html
│       ├── app.js
│       └── style.css
├── internal/store/
│   ├── store.go
│   └── store_test.go
├── knowledge/
├── backups/
├── Dockerfile
├── docker-compose.yml
├── docker-compose.dual.yml
├── .env.example
├── Makefile
└── go.mod
Reference in New Issue View Git Blame Copy Permalink