Claude Fable 5
6945cd0724
Some checks failed
CD / Deploy to Test (push) Blocked by required conditions
CD / Smoke tests against Test (push) Blocked by required conditions
CD / Promote to Int (push) Blocked by required conditions
CI / Auth e2e pack (push) Blocked by required conditions
CI / Import/export fidelity gate (push) Blocked by required conditions
CI / Build container images (push) Blocked by required conditions
CI / Lint, typecheck, test (push) Has been cancelled
CD / Build and push images (push) Has been cancelled
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0155v2aT8AG1kZDQEZiCLBWC
169 lines
7.2 KiB
Markdown
169 lines
7.2 KiB
Markdown
# Site-Admin-Handbuch
|
|
|
|
_Englisches Original: [docs/manual/site-admin-guide.md](../../manual/site-admin-guide.md)_
|
|
|
|
Wie du eine Dorfteich-Instanz aus dem Browser verwaltest. Installation,
|
|
Updates und Betrieb auf Host-Ebene behandelt das
|
|
[Self-Hosting-Handbuch](../../self-hosting/README.md) (englisch); hier
|
|
geht es um die beiden Admin-Seiten: **Admin → Einstellungen** (`/admin`)
|
|
und **Admin → System** (`/admin/system`).
|
|
|
|
Ein Site-Admin sieht und darf alles — nutze für die tägliche Arbeit ein
|
|
normales Konto.
|
|
|
|
## Erster Kontakt: der Einrichtungsassistent
|
|
|
|
Eine frische Instanz begrüßt dich mit einem Assistenten in sechs
|
|
Schritten: Sprache → das Site-Admin-Konto → Instanzname und
|
|
Standardsprache → SMTP-Relay (mit Live-Testmail; überspringbar) →
|
|
Registrierungsmodus → fertig. Bis er abgeschlossen ist, antwortet die
|
|
Instanz auf alles mit `503 setup_required`. Unbeaufsichtigte
|
|
Installationen befüllen den Assistenten vorab über
|
|
`SETUP_ADMIN_*`-Umgebungsvariablen.
|
|
|
|
## Admin → Einstellungen
|
|
|
|
### Instanz
|
|
|
|
- **Name** (erscheint in der Kopfleiste und in Mails) und
|
|
**Standardsprache** (gilt für anonyme Besucher und server-gerenderte
|
|
Seiten).
|
|
- **Registrierungsmodus**: `open` (jeder darf sich registrieren, mit
|
|
E-Mail-Bestätigung) oder `closed` (nur bestehende Konten melden sich
|
|
an).
|
|
|
|
### Kontingente
|
|
|
|
Instanzweite Standardwerte: Bearbeiter/Leser pro Teich, zusätzliche
|
|
geteilte Teiche pro Person (Standard 0 — erhöhe ihn oder vergib
|
|
Pro-Person-Overrides, damit Leute gemeinsame Teiche anlegen können),
|
|
Speicher pro Teich, maximale Dateigröße. Der **Kontingent-Manager**
|
|
darunter setzt Overrides pro Person/Teich, die die Standardwerte
|
|
überstimmen.
|
|
|
|
### Uploads
|
|
|
|
Die Allow-Liste der Nicht-Bild-Dateiendungen, die Nutzer anhängen
|
|
dürfen, und die SVG-Richtlinie (`sanitize` entfernt Skripte aus
|
|
hochgeladenen SVGs, `reject` lehnt sie ab).
|
|
|
|
### Öffentliche API und MCP
|
|
|
|
Zwei unabhängige Hauptschalter, beide **standardmäßig aus**:
|
|
|
|
- **Öffentliche REST-API**: erlaubt Nutzern, persönliche API-Tokens
|
|
anzulegen und `/api/public/v1` zu verwenden (siehe das
|
|
[API-Handbuch](api-guide.md)).
|
|
- **Eingebauter MCP-Endpoint**: stellt `/api/mcp` für KI-Assistenten
|
|
bereit ([MCP-Handbuch](mcp-guide.md)).
|
|
|
|
Keiner der Schalter wirkt allein pro Teich — jeder Teich stimmt
|
|
zusätzlich über seine Teich-Einstellungen zu. Aus heißt: Die Endpoints
|
|
antworten mit 404.
|
|
|
|
### Rechtsseiten
|
|
|
|
Impressum und Datenschutzerklärung als Markdown, veröffentlicht unter
|
|
`/legal/imprint` und `/legal/privacy` und aus jeder Fußzeile verlinkt.
|
|
Eine Vorlage mit Prüf-Checkliste liegt in
|
|
[`docs/self-hosting/legal-template.md`](../../self-hosting/legal-template.md).
|
|
Bis sie konfiguriert sind, zeigen die Seiten einen Hinweis (und dir ein
|
|
Warnbanner).
|
|
|
|
### Backups
|
|
|
|
Siehe **Admin → System → Backups** unten.
|
|
|
|
### Plugins
|
|
|
|
Installiere Plugins per ZIP-Upload (alternativ: das ZIP in den
|
|
`_dropzone/`-Ordner auf dem Plugins-Volume legen — ein Watcher
|
|
installiert es binnen Sekunden und verschiebt abgelehnte Pakete mit
|
|
Begründung nach `_quarantine/`).
|
|
|
|
Jedes installierte Plugin hat einen **Instanz-Modus**:
|
|
|
|
| Modus | Bedeutung |
|
|
| ---------- | ---------------------------------------------------- |
|
|
| `disabled` | überall inaktiv (der Standard nach dem Installieren) |
|
|
| `optional` | Teich-Admins entscheiden pro Teich |
|
|
| `required` | in jedem Teich aktiv, kein Opt-out |
|
|
|
|
Jedes Plugin hat eine gesandboxte **Vorschau**-Seite zum Ausprobieren
|
|
vor dem Aktivieren. Deinstallieren ist blockiert, solange ein Plugin
|
|
`required` ist; Dokumente behalten ihre Plugin-Blöcke in jedem Fall und
|
|
zeigen den Fallback-Text des Plugins, wenn es fehlt.
|
|
|
|
Mitgelieferte Referenz-Plugins: `toc` (Inhaltsverzeichnis),
|
|
`page-index` (label-gefilterte Seitenliste), `mermaid`
|
|
(Diagramm-Blöcke), `drawio` (vollwertiges draw.io-Bearbeiten),
|
|
`section-styles-basic` (farbige Hinweiskästen).
|
|
|
|
**Woher kommen die ZIPs der Referenz-Plugins?** Sie liegen den
|
|
Server-Images nicht bei — sie werden aus dem Repository gebaut (Node 22
|
|
|
|
- pnpm, einmalig `pnpm install` im Repo-Wurzelverzeichnis):
|
|
|
|
```sh
|
|
cd packages/plugins/<name> # toc | page-index | mermaid | drawio | section-styles-basic
|
|
pnpm build # → dist/<id>-<version>.zip — diese Datei hochladen
|
|
```
|
|
|
|
Der `drawio`-Build lädt beim ersten Lauf sein gepinntes Editor-Bundle
|
|
von GitHub und packt ein ~27-MiB-ZIP (innerhalb des 64-MiB-Limits für
|
|
Plugin-Uploads); die anderen vier bauen offline in Sekunden.
|
|
|
|
**Typischer Ablauf:** ZIP hochladen, die abgeschottete Vorschau prüfen,
|
|
den Instanz-Modus auf `optional` stellen und das Plugin dann je Teich
|
|
aktivieren (Teich-Einstellungen → **Plugins** — in persönlichen Teichen
|
|
macht das der Eigentümer selbst).
|
|
|
|
### Personen
|
|
|
|
Die Personenverwaltung: Konten suchen, deaktivieren/aktivieren,
|
|
Bestätigungsmails erneut senden, Site-Admins ernennen/absetzen und
|
|
Konten löschen. Die Löschung bietet **Pseudonymisierung** an: Das Konto
|
|
und seine persönlichen Daten verschwinden, aber geteilte Inhalte
|
|
überleben, einem neutralen Platzhalter zugeschrieben. Schutzmechanismen
|
|
verhindern, dich selbst zu deaktivieren oder den letzten Site-Admin zu
|
|
entfernen.
|
|
|
|
## Admin → System
|
|
|
|
Der Blick des Betreibers auf einen Schirm:
|
|
|
|
- **Wartungsjobs**: jeder Wartungsjob (Papierkorb-Bereinigung,
|
|
Versions-Ausdünnung, Seiten-Kompaktierung, Datenexport-Bereinigung,
|
|
Benachrichtigungs-Digests) mit Takt, letztem Lauf, Dauer und Ergebnis
|
|
— plus manuellem **Ausführen**-Knopf (selbst audit-geloggt).
|
|
- **Backups**: Die Status-Karte spiegelt den letzten Lauf des Sidecars
|
|
und sein Frische-Urteil, mit einem **Jetzt sichern**-Knopf. Darunter:
|
|
- **Backup-Einstellungen**: lokale Aufbewahrung (überstimmt den
|
|
Container-Standard) und das **Nextcloud-Ziel** — Server-Adresse,
|
|
Benutzername, App-Passwort (liegt im dateibasierten Secret-Store auf
|
|
dem Secrets-Volume, nie in der Datenbank), Ordner, Upload-Zeitplan
|
|
(nach jedem Backup / wöchentlich / manuell), entfernte Aufbewahrung
|
|
und ein **Verbindung testen**-Knopf, der die Zugangsdaten prüft und
|
|
den Ordner anlegt.
|
|
- **Wiederherstellung**: listet lokale und Nextcloud-Sets; beim
|
|
Wiederherstellen tippst du die Backup-ID zur Bestätigung ein, dann
|
|
geht die Instanz in den Wartungsmodus, stellt sich wieder her und
|
|
startet neu. Alles Weitere zu Backups (Spiegel auf einen privaten
|
|
Host, Disaster Recovery) steht im
|
|
[Self-Hosting-Handbuch](../../self-hosting/README.md#backups--restore)
|
|
und im [Restore-Runbook](../../operations/restore-runbook.md)
|
|
(beide englisch).
|
|
- **Audit-Log**: administrative und Auth-Ereignisse (Zugriffsregeln,
|
|
Mitglieder, Personenverwaltung, Kontingente, Plugins, Einstellungen,
|
|
Einrichtung, Tokens, API-Schreibzugriffe, Backup-Aktionen) mit
|
|
Filtern nach Akteur/Aktion/Zeit, 50 pro Seite.
|
|
- **Speicher**: die zwanzig größten Teiche und die Instanz-Summe.
|
|
|
|
## Health, Monitoring, Go-Live
|
|
|
|
- `GET /api/v1/readyz` ist die Eigendiagnose der Instanz; überwache sie
|
|
(Down-vs.-Degraded-Semantik und ein fertiges Monitor-Set:
|
|
[`deploy/monitoring.md`](../../../deploy/monitoring.md)).
|
|
- Go-Live-Checkliste für eine frische Produktionsinstanz:
|
|
[`deploy/go-live.md`](../../../deploy/go-live.md).
|