---
title: "SiYuan mit Docker installieren: Privacy-first Wissensmanagement lokal betreiben"
date: 2026-08-20T09:37:23+02:00
modified: 2026-11-08T20:48:46+01:00
category: docker
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/siyuan-docker-wissensmanagement
reading_time: 9
personalize_url: "https://s-edv.com/anleitungen/siyuan-docker-wissensmanagement#host_ip={host_ip}"
variables:
  - name: host_ip
    label: "Host ip"
    default: "HOST-IP"
---

# SiYuan mit Docker installieren: Privacy-first Wissensmanagement lokal betreiben

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{host_ip}}` | Host ip | `HOST-IP` |

Link mit eigenen Werten: https://s-edv.com/anleitungen/siyuan-docker-wissensmanagement#host_ip=HOST-IP

Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben.

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

**Kurzfassung:** Projektordner anlegen, `.env` mit starkem Auth-Code befüllen, `compose.yaml` hineinkopieren, Workspace-Verzeichnis mit korrektem Besitzer anlegen, dann `docker compose up -d`. Wichtig: Ab Version 3.8 muss `command` den Unterbefehl `serve` enthalten, sonst startet der Container in einer Neustartschleife. SiYuan ist danach im Browser unter Port 6806 erreichbar und wird per Autorisierungscode geschützt. Alle Daten liegen im gemounteten Workspace-Verzeichnis. Für den Betrieb im Internet unbedingt einen Reverse Proxy mit HTTPS vorschalten und den `/ws`-WebSocket-Endpunkt weiterleiten.

## 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage).
- [ ] 1 CPU-Kern, x86-64 oder ARM64. Mindestens **1 GB freier RAM**: Beim ersten Start belegt der Container 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.

```bash
$ 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:

```bash
$ id $USER
```

```bash
# 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):

```bash
$ 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`.

> **Prüfen:** `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:

Datei: `compose.yaml`

```ini
# /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:

```bash
$ 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.

> **Prüfen:** `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.

Datei: `compose.yaml`

```yaml
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.

> **Prüfen:** `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:

```bash
$ 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:

```bash
$ docker compose ps
```

Erwartete Ausgabe (nach ca. 20 Sekunden):

Ausgabe:

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

Logs auf Fehler prüfen:

```bash
$ docker compose logs siyuan
```

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

> **Prüfen:** ```bash
> $ curl -s http://localhost:6806/api/system/version
> ```
>
> ```bash
> # 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.

1. Geben Sie den in der `.env` gesetzten `SIYUAN_ACCESS_AUTH_CODE` ein und bestätigen Sie.
2. Nach erfolgreichem Login erscheint der SiYuan-Workspace. Beim ersten Aufruf ist er leer. Legen Sie Ihr erstes Notizbuch über „Notizbuch erstellen“ an.
3. 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 |

> **Prüfen:** 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](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung); für nginx-basierte Setups hilft die [nginx-Reverse-Proxy-Anleitung](https://s-edv.com/anleitungen/nginx-reverse-proxy-tls-einrichten).

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.

```bash
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.

> **Prüfen:** 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:

```bash
$ 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](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-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](https://s-edv.com/anleitungen/restic-backup-linux-windows-automatisieren-cron).

> **Prüfen:** 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

1. `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`.
2. **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.
3. **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`).
4. **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`.
5. **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).
6. **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.
7. **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.
8. **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.
9. **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](https://s-edv.com/anleitungen/sso-authentik-authelia-traefik-forward-auth). 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 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

1. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
2. [Docker Compose absichern: Secrets, Healthchecks und Non-Root für den Produktivbetrieb](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)
3. [AppFlowy mit Docker installieren: Open-Source-Notion-Alternative](https://s-edv.com/anleitungen/appflowy-docker-workspace)
4. [Restic Backup auf Linux und Windows einrichten und automatisieren](https://s-edv.com/anleitungen/restic-backup-linux-windows-automatisieren-cron)

Offizielle Quellen: [SiYuan GitHub Repository](https://github.com/siyuan-note/siyuan) (README, Changelog, Issues) und [SiYuan auf Docker Hub](https://hub.docker.com/r/b3log/siyuan) (Image-Tags, Multi-Arch-Details).
