Für Notizen, Recherchen und eine Wissensdatenbank unter eigener Kontrolle eignet sich SiYuan (思源笔记). Das unter AGPL-3.0 veröffentlichte Personal Knowledge Management System verbindet einen echten block-basierten Editor mit über 20 Blockelement-Typen, bidirektionalen Verlinkungen, Datenbank-Blöcken mit Relationen und Rollups sowie Karteikarten nach dem FSRS-Spaced-Repetition-Algorithmus – alles ohne Pflicht-Cloud, ohne Telemetrie und ohne monatliche Abo-Kosten. Mit regelmäßigen Releases (Stand September 2026: v3.8.6) ist es eines der aktivsten PKM-Projekte im Self-Hosting-Bereich. Die Anleitung richtet SiYuan mit Docker Compose auf einem Linux-Host oder NAS ein.

Voraussetzungen

Docker Engine ≥ 20.10 und das Docker Compose Plugin v2 (docker compose-Syntax) auf einem Linux-Host (Ubuntu 22.04+, Debian 12+ oder beliebige Docker-fähige Plattform). Falls Docker noch nicht installiert ist, folgen Sie der Docker- und Compose-Grundlage.
1 CPU-Kern, x86-64 oder ARM64. Mindestens 1 GB freier RAM: Im Test belegte der Container beim ersten Start kurzzeitig rund 570 MB, im Leerlauf rund 70 MB.
Ein persistentes Verzeichnis auf dem Host für den Workspace (empfohlen: mindestens 1 GB, je nach Notizumfang).
curl für die Schritt-Verifikation.
Optional: ein Reverse Proxy (nginx, Traefik oder Caddy) mit TLS-Zertifikat für den öffentlichen Zugriff. Ohne HTTPS werden Passwörter und Notizen unverschlüsselt übertragen.

Schritt 1: Projektordner anlegen

Legen Sie einen eigenen Ordner für den SiYuan-Stack an. Alle weiteren Dateien werden dort abgelegt.

mkdir -p /opt/siyuan
cd /opt/siyuan

Das Workspace-Verzeichnis, das später in den Container gemountet wird, muss vor dem ersten Start mit dem richtigen Besitzer angelegt werden. Prüfen Sie zunächst Ihre UID und GID auf dem Host:

id $USER
# Ausgabe-Beispiel: uid=1000(ubuntu) gid=1000(ubuntu) groups=…

Dann das Workspace-Verzeichnis anlegen und den Besitzer setzen – hier für den Standardfall UID/GID 1000:

mkdir -p /opt/siyuan/workspace
chown -R 1000:1000 /opt/siyuan/workspace

Hat Ihr Host-Benutzer eine abweichende UID (z. B. 1001), passen Sie den chown-Befehl und später die .env-Werte an. Das Einstiegsskript des Images setzt den Besitzer beim Start zusätzlich auf PUID:PGID.

Verifizieren: ls -la /opt/siyuan/ – das Verzeichnis workspace/ muss Ihrem Host-Benutzer gehören (Spalten „Besitzer“ und „Gruppe“ zeigen UID/GID 1000 oder Ihren Benutzernamen).

Schritt 2: .env-Datei mit Zugangsdaten anlegen

Die .env-Datei hält alle Secrets und umgebungsspezifischen Werte aus der compose.yaml heraus. Erstellen Sie sie im Projektordner:

# /opt/siyuan/.env

# Zugriffsschutz – PFLICHT: starkes Passwort wählen!
SIYUAN_ACCESS_AUTH_CODE=MeinSicheresPasswort2026!

# Host-User, unter dem der Container-Prozess laufen soll
PUID=1000
PGID=1000

# Zeitzone
TZ=Europe/Berlin

# Port auf dem Host (Standard: 6806)
SIYUAN_PORT=6806

# Workspace-Verzeichnis auf dem Host
SIYUAN_WORKSPACE_HOST=/opt/siyuan/workspace

Setzen Sie restriktive Dateiberechtigungen, damit der Auth-Code nicht für andere Nutzer lesbar ist:

chmod 600 /opt/siyuan/.env

Wichtig: Ohne einen gesetzten SIYUAN_ACCESS_AUTH_CODE kann jeder, der Port 6806 erreicht, sämtliche Notizen lesen und verändern. Wählen Sie ein starkes, einzigartiges Passwort.

Verifizieren: cat /opt/siyuan/.env – alle Variablen müssen gesetzt sein. ls -la /opt/siyuan/.env zeigt Berechtigungen -rw-------.

Schritt 3: compose.yaml anlegen

Erstellen Sie die compose.yaml im Projektordner. Die Anleitung legt den Image-Tag auf v3.8.6 fest (Pinning), damit ein Update keine ungeprüften Änderungen einspielt.

services:
  siyuan:
    image: b3log/siyuan:v3.8.6
    container_name: siyuan
    restart: unless-stopped
    ports:
      - "${SIYUAN_PORT:-6806}:6806"
    volumes:
      - ${SIYUAN_WORKSPACE_HOST:-/opt/siyuan/workspace}:/siyuan/workspace
    environment:
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - TZ=${TZ:-Europe/Berlin}
      - SIYUAN_ACCESS_AUTH_CODE=${SIYUAN_ACCESS_AUTH_CODE}
    command:
      - "serve"
      - "--workspace=/siyuan/workspace/"
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:6806/api/system/version"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

Hinweise zur Konfiguration: Seit Version 3.8 ist der Kernel ein Kommandozeilenwerkzeug mit Unterbefehlen. Wer command setzt, überschreibt den Standardbefehl kernel serve und muss serve daher selbst angeben. Fehlt es, gibt der Kernel nur seine Hilfe aus, beendet sich und wird von restart: unless-stopped endlos neu gestartet. Der Parameter --workspace hat Vorrang vor der Umgebungsvariable SIYUAN_WORKSPACE_PATH. Das interne Programmverzeichnis /opt/siyuan/ im Container wird absichtlich nicht gemountet – nur der Workspace unter /siyuan/workspace ist relevant. Der Healthcheck verwendet wget, weil das Image kein curl enthält, und fragt den Endpunkt /api/system/version ab, der ohne Anmeldung antwortet.

Verifizieren: docker compose config im Projektordner ausführen – Docker gibt die aufgelöste Konfiguration ohne Fehler aus.

Schritt 4: Container starten

Starten Sie SiYuan im Hintergrund:

docker compose up -d

Beim ersten Start lädt Docker das Image herunter (ca. 100 MB). Danach initialisiert SiYuan den Workspace – das dauert einige Sekunden.

Status prüfen:

docker compose ps

Erwartete Ausgabe (nach ca. 20 Sekunden):

NAME      IMAGE                  SERVICE   STATUS
siyuan    b3log/siyuan:v3.8.6    siyuan    Up (healthy)

Logs auf Fehler prüfen:

docker compose logs siyuan

Ein sauberer Start zeigt Starting SiYuan with UID:1000 … und danach kernel booted, ohne permission denied- oder Port-Konflikt-Fehler.

Verifizieren:

curl -s http://localhost:6806/api/system/version
# Erwartete Ausgabe: {"code":0,"msg":"","data":"3.8.6"}

Schritt 5: Ersteinrichtung im Browser

Öffnen Sie http://<HOST-IP>:6806 in einem aktuellen Browser. SiYuan leitet zunächst auf die Eingabemaske für den Autorisierungscode.

Geben Sie den in der .env gesetzten SIYUAN_ACCESS_AUTH_CODE ein und bestätigen Sie.
Nach erfolgreichem Login erscheint der SiYuan-Workspace. Beim ersten Aufruf ist er leer – legen Sie Ihr erstes Notizbuch über „Notizbuch erstellen“ an.
Die Kernfunktionen: Blöcke per /-Befehl einfügen, bidirektionale Links mit [[ anlegen, Datenbank-Blöcke für strukturierte Inhalte nutzen.

Eigenschaft	Wert
Docker-Image	b3log/siyuan:v3.8.6 (Docker Hub)
Aktuelle stabile Version	v3.8.6 (September 2026)
Image-Größe	ca. 100 MB
Architekturen	linux/amd64, linux/arm64
Port	6806 (Web-UI, REST-API, WebSocket /ws)
Datenbank	Eingebettetes SQLite – kein externer DB-Dienst nötig
Lizenz	AGPL-3.0
Workspace-Pfad (Container)	/siyuan/workspace

Verifizieren: Im Browser erscheint nach der Anmeldung der SiYuan-Editor-Workspace ohne Fehlermeldungen. Legen Sie testweise einen Block an und laden Sie die Seite neu. Der Inhalt muss erhalten bleiben. Prüfen Sie parallel auf der Kommandozeile: ls -la /opt/siyuan/workspace/ – SiYuan hat die Unterverzeichnisse conf/, data/ und temp/ angelegt.

Schritt 6: Reverse Proxy und HTTPS einrichten (empfohlen)

Ohne HTTPS überträgt SiYuan Passwort und Notizen im Klartext. Für den Betrieb im lokalen Netz ohne eigene Domain reicht HTTP über Port 6806; sobald der Dienst von außen erreichbar sein soll, ist ein Reverse Proxy mit TLS-Terminierung Pflicht. Eine vollständige Caddy-Anleitung finden Sie unter Caddy als Reverse Proxy mit automatischem HTTPS; für nginx-basierte Setups hilft die nginx-Reverse-Proxy-Anleitung.

Beim nginx-Einsatz muss der /ws-WebSocket-Endpunkt explizit weitergeleitet werden. Den Host-Header übergeben Sie mit $http_host, damit ein abweichender Port erhalten bleibt. Mit $host scheitert die Origin-Prüfung bei Nicht-Standard-Ports: Die Seite bleibt beim Logo hängen, die API antwortet mit 401.

location / {
    proxy_pass http://siyuan:6806;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
}

location /ws {
    proxy_pass http://siyuan:6806;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
}

Wichtig: Kein URL-Rewriting verwenden (also kein /siyuan/ auf / umschreiben). SiYuan verträgt keine Pfad-Umschreibungen und reagiert mit Authentifizierungs-Fehlerschleifen. Am sichersten ist eine eigene Sub-Domain (notes.example.com), die direkt auf Port 6806 zeigt.

Verifizieren: Nach dem Reverse-Proxy-Setup: curl -I https://notes.example.com gibt HTTP/2 200 zurück. Im Browser erscheint keine Zertifikatswarnung, und der WebSocket-Status in den Browser-Entwicklerwerkzeugen (Netzwerk-Tab → WS) zeigt eine aktive Verbindung zu /ws.

Schritt 7: Updates und Backup

SiYuan hat zwar eine eingebaute Update-Funktion in der UI, im Docker-Betrieb sollte das Update jedoch immer über das Image erfolgen – nicht über den UI-Updater:

cd /opt/siyuan
docker compose pull
docker compose up -d

Für ein Update tragen Sie in der compose.yaml den neuen Tag ein (z. B. b3log/siyuan:v3.8.7), nachdem Sie die Release Notes geprüft haben. Welche Tools dabei helfen, neue Image-Tags zu erkennen, zeigt die Anleitung zu Docker-Container-Updates mit Diun und WUD.

Zum Backup: Alle Daten – Notizbücher, Anhänge, Konfiguration und die SQLite-Datenbank – liegen ausschließlich unter /opt/siyuan/workspace/. Sichern Sie dieses Verzeichnis regelmäßig, idealerweise bei gestopptem Container, damit die SQLite-Datenbank konsistent ist. Für automatisierte, verschlüsselte Off-Site-Backups empfiehlt sich Restic mit automatisierter cron-Ausführung.

Verifizieren: Nach dem Update: docker compose ps zeigt Status Up (healthy), docker compose logs siyuan | head -20 zeigt die neue Versionszeile ohne Fehler. Nach dem Backup: ls -lh /opt/siyuan/workspace/data/ – alle Notizbücher sind vorhanden.

Troubleshooting / Typische Fehler

permission denied beim Containerstart: Das häufigste Problem. Ursache: /opt/siyuan/workspace gehört root oder einem anderen Nutzer. Fix: chown -R 1000:1000 /opt/siyuan/workspace (mit der tatsächlichen UID/GID Ihres Host-Benutzers). Anschließend docker compose down && docker compose up -d.
Auth-Code-Eingabe erscheint nicht / Seite bleibt leer: Prüfen Sie, ob der Container läuft: docker compose ps und docker compose logs siyuan. Läuft er, aber die Seite ist leer, deutet es oft auf einen Proxy mit URL-Rewriting hin.
WebSocket-Verbindung bricht ab (Echtzeit-Updates fehlen): nginx ohne proxy_set_header Upgrade-Block für /ws. Ergänzen Sie den WebSocket-Abschnitt wie in Schritt 6 und laden Sie die nginx-Konfiguration neu (nginx -s reload).
PUID/PGID stimmt nicht mit Host-User überein: Wenn nachträglich Dateien im Workspace entstehen, die einem anderen Nutzer gehören, prüfen Sie mit id $USER die tatsächliche UID und setzen Sie PUID und PGID in der .env entsprechend. Danach docker compose up -d.
Desktop- oder Mobile-App verbindet sich nicht: Keine Störung, sondern eine Einschränkung: Docker-Instanzen unterstützen nur den Browser (siehe Häufige Fragen).
Export (PDF, HTML, Word) fehlt: Diese Export-Funktionen sind im Browser-Modus (Docker) laut Projekt-README nicht verfügbar, ebenso der Import von Markdown-Dateien. Dafür benötigen Sie die Desktop-App.
Port 6806 bereits belegt: Ändern Sie in der .env den Wert von SIYUAN_PORT auf einen freien Port (z. B. 6807) und starten Sie den Container neu.
Container startet ständig neu, Log zeigt nur die Hilfe „Available Commands“: In command fehlt der Unterbefehl serve. Ergänzen Sie ihn wie in Schritt 3 und führen Sie docker compose up -d aus.
Status bleibt unhealthy: Der Healthcheck ruft ein Programm auf, das im Image fehlt (z. B. curl). Verwenden Sie wget wie in Schritt 3.

Häufige Fragen

Kann ich SiYuan mit meiner Desktop-App verbinden?

Nein. Die Docker-Instanz ist rein browser-basiert. Die nativen Desktop- und Mobile-Apps von SiYuan kommunizieren nicht mit einem selbst gehosteten Docker-Server. Wer Geräte synchronisieren möchte, hat zwei Optionen: das kostenpflichtige SiYuan Cloud Sync oder ein gemeinsam gemountetes Verzeichnis (z. B. per WebDAV oder Syncthing).

Brauche ich PostgreSQL oder Redis?

Nein. SiYuan verwendet eine eingebettete SQLite-Datenbank. Es ist kein externer Datenbankdienst erforderlich . Das hält das Setup schlank.

Wie setze ich den Auth-Code zurück, wenn ich ihn vergessen habe?

Öffnen Sie die .env-Datei, tragen Sie einen neuen Wert für SIYUAN_ACCESS_AUTH_CODE ein und führen Sie docker compose up -d aus. Der Container liest die Variable beim Neustart und akzeptiert ab sofort den neuen Code. Alternativ können Sie in der Datei /opt/siyuan/workspace/conf/conf.json das Feld accessAuthCode direkt anpassen, wenn der Container gestoppt ist.

Was ist mit Ende-zu-Ende-verschlüsselter Sync?

SiYuan bietet optionale E2E-verschlüsselte Synchronisierung über den SiYuan Cloud Sync-Dienst. Das ist ein kostenpflichtiges Add-on; die Docker-Instanz selbst ist kostenlos, alle Daten bleiben lokal.

Wie sichere ich die Instanz über den Auth-Code hinaus ab?

Pflicht ist ein starker SIYUAN_ACCESS_AUTH_CODE. Empfohlen ist ein Reverse Proxy mit HTTPS. Optional lässt sich eine zusätzliche Authentifizierungsschicht vorschalten, etwa mit Authentik oder Authelia als SSO-Layer. Port 6806 sollte niemals direkt ohne Auth ans öffentliche Internet exponiert werden.

Fazit

SiYuan eignet sich als selbst gehostete PKM-Lösung: kein externer Datenbankdienst, ein einzelnes Docker-Image von rund 100 MB, ein echter block-basierter Editor mit bidirektionalen Links und eine solide Zugriffssicherung per Auth-Code. Die Einrichtung dauert rund 10 Minuten. Die häufigsten Stolpersteine sind falsche Rechte am Workspace-Verzeichnis und ein fehlendes serve in command. Wer Desktop-Funktionen wie PDF-Export oder Markdown-Import benötigt, ist im Browser-Modus eingeschränkt. Als serverseitiger Wissensspeicher für den Browser-Zugriff erfüllt SiYuan seinen Zweck.

Im Test (30.09.2026, b3log/siyuan:v3.8.6, 1 CPU, 3 GB RAM) lief der Stack aus Schritt 1 bis 4 mit serve und wget-Healthcheck: Status healthy, Versions-Endpunkt 3.8.6, Anmeldung per Auth-Code, falscher Code abgewiesen, Notizbuch blieb nach Neustart erhalten.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: SiYuan GitHub Repository (README, Changelog, Issues) und SiYuan auf Docker Hub (Image-Tags, Multi-Arch-Details).