Wiki.js 2026 selbst hosten: Datenbank-Setup, TLS und Restore-Tests

Die meisten Installationsanleitungen für Wiki.js enden beim ersten Seitenaufruf. Das ist zu früh: DB_HOST zeigt innerhalb des Containers auf localhost oder Header des TLS-Proxy fehlen. Ein sinnvoller Produktionstest ist anspruchsvoller — Setup abschließen, eine Seite erstellen und bearbeiten, Medien hochladen, danach suchen und den Versionsverlauf nach einem Neustart prüfen.

Die Rolle von Wiki.js ist klar umrissen: ein Markdown-Wiki mit Versionierung und modernem Editor. Die betriebliche Umgebung umfasst jedoch mehr als nur den Webprozess. Deshalb müssen Abhängigkeit, persistenter Zustand und öffentlicher Zugriffspunkt vor dem Eintreffen echter Daten ausdrücklich benannt werden.

Die Laufzeitgrenze von Wiki.js festlegen

Die kleinste verantwortungsvoll betriebene Wiki.js-Topologie umfasst einen privaten Listener auf Port 3000, eine Ingress-Route und eine dokumentierte Zustandsgrenze. Der Netzwerkvertrag für Wiki.js besteht aus einer erreichbaren Postgres-, MySQL-, MariaDB-, MSSQL- oder SQLite-Datenbank. Halte private Endpunkte im internen DNS, erlaube nur erforderliche ausgehende Verbindungen und gib Wiki.js ein Servicekonto mit begrenzten Berechtigungen.

Validiere die Topologie, indem du einen sauberen Client das Setup abschließen, eine Seite erstellen und bearbeiten, Medien hochladen, danach suchen und den Versionsverlauf nach einem Neustart prüfen lässt. Beobachte dabei die Antwortzeit der Datenbank, die Suchindexierung, den Medienspeicher und die Latenz des Authentifizierungsproviders. Das Ergebnis zeigt, ob die nächste Verbesserung den Speicher, den Storage, das Netzwerk oder einen separaten Worker betrifft, anstatt zu einer beliebigen Dimensionierung des Containers zu verleiten.

Den Wiki.js-Restore vor dem Start planen

Im Standard-Image von Wiki.js wird kein beschreibbarer Anwendungszustand erwartet. Bewahre neben der Datenbank auch lokale Uploads und benutzerdefinierte Assets auf — einschließlich des festgelegten Digests und der geprüften Routenkonfiguration — statt ein leeres Container-Dateisystem zu sichern.

Setze Wiki.js auf einem anderen Host von Grund auf neu auf und verifiziere, dass Seiten, Verlauf, Benutzer, Gruppen, Medien und Navigation wieder vorhanden sind und eine bekannte Seite weiterhin gefunden werden kann. Wenn eine separate Datenbank, ein Room-Server oder eine Authentifizierungsschicht hinzugefügt wird, gib dieser Komponente einen eigenen, ausdrücklich benannten Verantwortlichen für die Wiederherstellung. Der Leitfaden von Git zur Produktion zeigt, wie ein reproduzierbares Artefakt ein Container-Backup ersetzt.

Dokumentiere den Rebuild-Befehl und den Test mit den erwarteten Ergebnissen zusammen mit dem Release. Ein zustandsloser Wiederherstellungsplan ist erfolgreich, wenn er das Verhalten aus vertrauenswürdigen Eingaben reproduziert; er sollte nicht davon abhängen, einen undurchsichtigen laufenden Container zu kopieren.

Die Vertrauensgrenze von Wiki.js festlegen

Eine sichere Wiki.js-Bereitstellung beginnt damit, Berechtigungen zu reduzieren. Lass den Setup-Bildschirm nicht öffentlich erreichbar, sobald der erste Administrator angelegt wurde. Entferne stattdessen den öffentlichen Zugriff auf das Setup, beschränke die Administration und gib der Wiki-Datenbank eigene Zugangsdaten.

Behandle DB_PASS entsprechend seiner Rolle in Wiki.js: Halte vertrauliche Werte aus Git heraus, dokumentiere die Auswirkungen einer Rotation und ersetze in der Produktion niemals ein öffentliches Beispiel. Beschränke administrative Routen, verwende private DNS-Namen für Abhängigkeiten und prüfe jeden Bind-Mount. Wenn Logs zentral weitergeleitet werden, filtere Geheimnisse und private Inhalte, bevor sie den Server verlassen.

Was vor dem Eintreffen echter Wiki.js-Daten erfolgreich sein muss

Ein Produktions-Gate für Wiki.js sollte von jemandem ausführbar sein, der die Bereitstellung nicht selbst erstellt hat. Gib dieser Person die festgelegte Version, ein nicht sensibles Testkonto und diese Aufgabe: Setup abschließen, eine Seite erstellen und bearbeiten, Medien hochladen, danach suchen und den Versionsverlauf nach einem Neustart prüfen. Wenn die Anleitung undokumentierten Shell-Zugriff erfordert, ist der Service operativ noch nicht bereit.

Wiederhole das Gate, nachdem du ausschließlich den Container ersetzt hast. Stelle anschließend die Datenbank sowie lokale Uploads und benutzerdefinierte Assets in einer leeren Infrastruktur wieder her und beweise, dass Seiten, Verlauf, Benutzer, Gruppen, Medien und Navigation wieder vorhanden sind und eine bekannte Seite weiterhin gefunden werden kann. Miss während beider erfolgreichen Durchläufe die Antwortzeit der Datenbank, die Suchindexierung, den Medienspeicher und die Latenz des Authentifizierungsproviders. Unerwartete Unterschiede weisen häufig auf einen fehlenden Cache, Index, Worker oder Daten-Mount hin.

Füge eine Fehlerübung hinzu: Verweigere der Testidentität vorübergehend den Zugriff auf eine erreichbare Postgres-, MySQL-, MariaDB-, MSSQL- oder SQLite-Datenbank. Wiki.js sollte einen hilfreichen Fehler ausgeben, den vorhandenen Zustand bewahren und sich erholen, sobald die gültige Bedingung wiederhergestellt ist. Speichere die Zeitstempel und relevanten Logzeilen mit redigierten Geheimnissen. Diese Nachweise dienen als Referenz für das nächste Image oder die nächste Konfigurationsänderung.

Wiki.js starten, ohne die beweglichen Teile zu verbergen

Halte den anfänglichen Wiki.js-Aufruf so reproduzierbar, dass er in einem Pull Request geprüft werden kann.

docker run -d \
  --name wiki-js \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -e DB_PASS=replace-with-a-long-random-value \
  -e DB_TYPE=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_PORT=5432 \
  -e DB_USER=wiki \
  -e DB_NAME=wiki \
  ghcr.io/requarks/wiki:2

Verlasse dich nicht auf latest, sobald echte Daten vorhanden sind. Erfasse den funktionierenden Digest, den Container-Benutzer und die Eigentumsverhältnisse der Mounts. Verfolge das Anwendungslog durch einen vollständigen Test — Setup abschließen, eine Seite erstellen und bearbeiten, Medien hochladen, danach suchen und den Versionsverlauf nach einem Neustart prüfen — und notiere alle Migrationen, bevor du die Route für den Produktionsverkehr freigibst.

Interne und externe URLs sauber trennen

Behandle die externe Wiki.js-URL als Konfiguration, die Redeployments übersteht. Konfiguriere zuerst die Site-URL, nachdem du den Service über HTTPS geroutet hast. Leite anschließend den Hostnamen mit unverändertem ursprünglichem Host und Schema an Port 3000 weiter.

Die Checkliste zur Erreichbarkeit einer Bereitstellung kann nachweisen, dass Anfragen den Container erreichen. Danach sollte der bekannte Fehler — DB_HOST zeigt innerhalb des Containers auf localhost oder Header des TLS-Proxy fehlen — in Wiki.js, dessen Zustand oder dessen Workload untersucht werden und nicht in der Zertifikatsautomatisierung.

Die Workload beobachten, nicht nur den Container

Baue Dashboards rund um die Antwortzeit der Datenbank, die Suchindexierung, den Medienspeicher und die Latenz des Authentifizierungsproviders. Ein CPU-Graph ohne diesen Workload-Kontext kann nicht erklären, warum Wiki.js langsam ist. Ergänze eine synthetische oder geplante Prüfung, die mit ungefährlichen Testdaten versucht, das Setup abzuschließen, eine Seite zu erstellen und zu bearbeiten, Medien hochzuladen, danach zu suchen und den Versionsverlauf nach einem Neustart zu prüfen.

Berücksichtige vor einem Upgrade dieses anwendungsspezifische Risiko: Datenbankmigrationen und Authentifizierungsmodule von Wiki.js sollten vor dem Wechsel auf eine andere Release-Linie in einer Staging-Umgebung geprüft werden. Stelle ein aktuelles Backup in einer isolierten Bereitstellung wieder her, führe dort die Migrationen aus und vergleiche das Verhalten. Wenn DB_HOST innerhalb des Containers auf localhost zeigt oder Header des TLS-Proxy fehlen, untersuche zuerst die betroffene Grenze — öffentliche Origin, Storage oder Abhängigkeit — bevor du nicht zusammenhängende Einstellungen änderst.

Wiki.js explizit halten, während Dockup das Routing übernimmt

Routing, Zertifikate, der Austausch von Services und angebundener Storage sind sinnvolle Ziele für Automatisierung. Dockup übernimmt diese Aufgaben für Wiki.js und kann die zugehörige verwaltete Datenbank bereitstellen oder Verbindungen zu Services auf dem eigenen Server eines Kunden herstellen.

Was Dockup nicht erfinden sollte, ist die Vertrauensrichtlinie von Wiki.js. Konfiguriere nach der Bereitstellung die Site-URL, nachdem du den Service über HTTPS geroutet hast. Erzwinge diese Grenze — entferne den öffentlichen Zugriff auf das Setup, beschränke die Administration und gib der Wiki-Datenbank eigene Zugangsdaten — und überprüfe das Ergebnis dieses Szenarios: Setup abschließen, eine Seite erstellen und bearbeiten, Medien hochladen, danach suchen und den Versionsverlauf nach einem Neustart prüfen. Das Ergebnis ist eine Infrastruktur mit One-Click-Bereitstellung und einem anwendungsspezifischen Abnahmetest.

Häufig gestellte Fragen

Was benötigt Wiki.js für eine Produktionsbereitstellung?

Leite den Wiki.js-Container auf Port 3000 über eine einzige HTTPS-Origin. Die unterstützende Netzwerkanforderung ist eine erreichbare Postgres-, MySQL-, MariaDB-, MSSQL- oder SQLite-Datenbank. Betrachte Wiki.js erst dann als bereit, wenn du das Setup abschließen, eine Seite erstellen und bearbeiten, Medien hochladen, danach suchen und den Versionsverlauf nach einem Neustart prüfen kannst.

Welche Wiki.js-Daten gehören in ein Backup?

Das Standard-Image von Wiki.js besitzt keinen erforderlichen Mount für Anwendungsdaten. Bewahre die Bereitstellungskonfiguration auf und sichere jeden verbundenen Zustand separat. Die Wiederherstellung ist erfolgreich, wenn Seiten, Verlauf, Benutzer, Gruppen, Medien und Navigation wieder vorhanden sind und eine bekannte Seite weiterhin gefunden werden kann.

Benötigt Wiki.js HTTPS hinter einem Reverse Proxy?

Verwende HTTPS für die öffentliche Wiki.js-Origin und halte Port 3000 auf der internen Route. Wende die Wiki.js-Einstellung korrekt an: Konfiguriere die Site-URL, nachdem du den Service über HTTPS geroutet hast. Bei Wiki.js schützt HTTPS Zugangsdaten oder Benutzerinhalte während der Übertragung und sorgt dafür, dass vom Origin abhängiges Client-Verhalten konsistent bleibt.

Wie sollte ein Wiki.js-Upgrade getestet werden?

Stelle den aktuellen Wiki.js-Zustand in einer isolierten Bereitstellung wieder her, spiele die Kandidatenversion ein und wiederhole die Abnahmetransaktion. Gehe besonders sorgfältig vor, da Datenbankmigrationen und Authentifizierungsmodule von Wiki.js vor dem Wechsel auf eine andere Release-Linie in einer Staging-Umgebung geprüft werden sollten. Bewahre das vorherige Wiki.js-Image auf, bis die Grenzen für Datenmigration und Rollback verstanden sind.