Portunity Wiki - Benutzerbeiträge [de]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T19:04:29Z

Lr@superroot: /* docker-compose.yml (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal. Bitte verwechsels Sie die Snapshoots auf dem NAS nicht mit den Snapshoots innerhalb von Kopia - dies sind zwei völlig getrennte Welten!

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/backup-paperless cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
/mnt/
backup-daten/
backup-homeassistant/
backup-kasse/
backup-paperless/
backup-restore/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/backup-paperless:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T19:03:20Z

Lr@superroot: /* Mount per /etc/fstab (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal. Bitte verwechsels Sie die Snapshoots auf dem NAS nicht mit den Snapshoots innerhalb von Kopia - dies sind zwei völlig getrennte Welten!

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/backup-paperless cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
/mnt/
backup-daten/
backup-homeassistant/
backup-kasse/
backup-paperless/
backup-restore/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T19:02:54Z

Lr@superroot: /* Ordnerstruktur */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal. Bitte verwechsels Sie die Snapshoots auf dem NAS nicht mit den Snapshoots innerhalb von Kopia - dies sind zwei völlig getrennte Welten!

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
/mnt/
backup-daten/
backup-homeassistant/
backup-kasse/
backup-paperless/
backup-restore/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T19:01:30Z

Lr@superroot: /* Ordnerstruktur */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal. Bitte verwechsels Sie die Snapshoots auf dem NAS nicht mit den Snapshoots innerhalb von Kopia - dies sind zwei völlig getrennte Welten!

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
/mnt/
backup-daten/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:41:42Z

Lr@superroot: /* UniFi NAS: Shares & lokale Snapshots */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal. Bitte verwechsels Sie die Snapshoots auf dem NAS nicht mit den Snapshoots innerhalb von Kopia - dies sind zwei völlig getrennte Welten!

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:40:43Z

Lr@superroot: /* Architektur */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:39:34Z

Lr@superroot: /* Zielbild (kurz) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:37:57Z

Lr@superroot: /* Zielbild (kurz) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:''' Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar. Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopio auch inkrementelle und deduplizierte Backups ermöglichen.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:35:41Z

Lr@superroot: /* Zielbild (kurz) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:''' Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar. ''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:31:52Z

Lr@superroot: /* Snapshot per Cron anstoßen (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:30:14Z

Lr@superroot: /* Snapshot per Cron anstoßen (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt:
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:30:06Z

Lr@superroot: /* Snapshot per Cron anstoßen (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<source lang="shell">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt:
<source lang="shell">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:28:25Z

Lr@superroot: /* Repository im Portunity S3 initialisieren */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:27:59Z

Lr@superroot: /* docker-compose.yml (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:27:31Z

Lr@superroot: /* Mount per /etc/fstab (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:27:19Z

Lr@superroot: /* .env (Beispiel, anonymisiert) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="bash">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="bash">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:26:32Z

Lr@superroot: /* .env (Beispiel, anonymisiert) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="bash">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="bash">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="bash">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:24:43Z

Lr@superroot: /* Mount per /etc/fstab (Beispiel) */

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="bash">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="bash">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<pre>
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</pre>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:21:20Z

Lr@superroot: Kategoriezuordnung

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<pre>
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</pre>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<pre>
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</pre>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<pre>
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</pre>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)

2026-01-09T18:20:14Z

Lr@superroot: Die Seite wurde neu angelegt: „= Zielbild (kurz) = Dieses Setup kombiniert zwei Dinge: * '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei v…“

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<pre>
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</pre>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<pre>
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</pre>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<pre>
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</pre>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

Offsite-Backups mit UniFi NAS + Kopia Backup Software (Docker) + Portunity secureBackup (S3/Ceph)

2026-01-09T18:19:13Z

Lr@superroot: Erste Version der Kopia-Backup Anleitung by Lea

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<pre>
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</pre>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<pre>
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</pre>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<pre>
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</pre>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

Telefon-KI - Gute Prompts schreiben

2025-12-09T13:19:56Z

Lr@superroot: /* Ziel dieser Seite */

= Ziel dieser Seite =

Auf dieser Seite finden Sie Hinweise, wie Sie gute Prompts für Ihre Telefon-KI (KI-Agenten) formulieren.
Im Mittelpunkt stehen:

* der Aufbau des '''Basis-Prompts''' (Hauptanweisungen),
* der sinnvolle Einsatz von '''Unter-Prompts''' (Spezialanweisungen),
* Besonderheiten im Telefonkontext (z. B. Umgang mit unklarer Sprache),
* Portunity-spezifische Aspekte (z. B. Nutzung der Anrufer-Rufnummer im Prompt).

Konkrete Branchen-Beispiele finden Sie zusätzlich auf der Seite
'''[[Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Grundprinzipien für Prompts in der Telefon-KI =

== Grundregeln ==

Realtime-KI für Telefonie verhält sich etwas anders als ein „normaler“ Chatbot. Folgende Grundregeln haben sich bewährt:

; Klar und widerspruchsfrei formulieren
: Geben Sie klare, eindeutige Anweisungen. Widersprüchliche Regeln („Seien Sie sehr kurz“ und später „Erzählen Sie alles ausführlich“) führen zu unvorhersehbarem Verhalten.

; Stichpunkte statt langer Fließtexte
: Nutzen Sie Überschriften und Aufzählungen. Strukturierte Prompts sind für die Modelle leichter zu interpretieren und später einfacher zu warten.

; Rolle und Grenzen definieren
: Beschreiben Sie, '''wer''' die KI am Telefon sein soll (z. B. Rezeption, Support, Notdienst) und was sie '''nicht''' tun darf (z. B. keine medizinischen Diagnosen, keine verbindliche Rechtsberatung).

; Telefon ist kein Chat
: Am Telefon sind Anrufer ungeduldiger, hören Nebengeräusche und sprechen manchmal undeutlich. Geben Sie der KI Anweisungen, wie sie nachfragt, zusammenfasst und Gesprächsanteile kurz hält.

; Unklare oder fehlerhafte Eingaben aktiv behandeln
: Weisen Sie die KI an, bei schlechtem Audio oder unklaren Angaben nachzufragen, statt zu raten. Besser eine Rückfrage als eine falsche Zusage.

; Pro Agent: eine Hauptaufgabe
: Ein KI-Agent sollte eine gut umrissene Rolle haben (z. B. „Reservierungen & Öffnungszeiten“). Für völlig andere Aufgaben (z. B. Notrufannahme) ist ein eigener Agent sinnvoll.

== Allgemeine Hinweise zu Wissen und Quellen ==

Bevor Sie mit dem eigentlichen Inhalt Ihres Prompts beginnen, sollten Sie ein paar technische Grenzen der Telefon-KI berücksichtigen und im Prompt klar ansprechen.

=== Kein Live-Zugriff auf Websites oder externe Systeme ===

Die Telefon-KI kann während des Gesprächs standardmäßig '''keine''' Informationen live aus dem Internet oder aus anderen Systemen abrufen, z. B.:

* keine Inhalte von Webseiten wie »www.beispiel.de« laden,
* keine Online-Buchungssysteme direkt abfragen (sofern diese nicht ausdrücklich über einen MCP-Server angebunden sind),
* keine Dateien oder Dokumente aus E-Mail-Postfächern oder Cloud-Speichern öffnen (außer diese Sysyteme sind über einen MCP-Server angebunden).

Sie können im Prompt selbstverständlich Formulierungen verwenden wie:

<pre>
"Gäste finden weitere Informationen auch auf unserer Website unter www.meine-website.de."
"Fotos zu unserem Sonntagsbrunch finden Sie auf unserer Website unter /brunch."
</pre>

Diese Hinweise dienen ausschließlich dazu, dass die KI den Anrufer korrekt '''informiert'''.
Die KI nutzt diese URLs jedoch nicht als eigene Wissensquelle – sie „liest“ die Webseiten nicht.

=== Wissensbasis klar begrenzen ===

Für viele Einsatzszenarien ist es sinnvoll, die Wissensbasis der KI bewusst zu begrenzen.
Damit vermeiden Sie, dass die KI Inhalte „halluziniert“ oder sich vermeintliches Wissen „ausdenkt“.

Empfehlung: Fügen Sie in Ihrem Basis-Prompt einen Abschnitt ein, der die Wissensbasis beschreibt, zum Beispiel:

<pre>
## Wissensbasis

- Deine einzige Wissensquelle sind dieser Basis-Prompt und die vorhandenen Unter-Prompts.
- Du erfindest keine Fakten, die hier nicht beschrieben sind.
- Wenn dir Informationen fehlen oder du dir nicht sicher bist, sagst du das offen
(z. B. "Diese Information liegt mir nicht vor." oder "Das weiß ich leider nicht genau.")
und bietest an, eine Rückmeldung durch unser Team zu veranlassen.
</pre>

Damit stellen Sie klar:

* '''Woher''' die KI ihr Wissen bezieht (Basis-Prompt + Unter-Prompts),
* dass sie keine externen Quellen ergänzt,
* wie sie sich bei fehlendem Wissen verhalten soll.

Gerade in sensiblen Bereichen (z. B. Medizin, Recht, Finanzen) ist eine solche Klarstellung besonders wichtig.

=== Externe Wissensquellen via MCP ===

Externe Wissensquellen können und müssen ansonsten über das MCP-Protokoll eingebunden werden. Dies ist ein gesondertes Thema.

Bitte beachten Sie dabei auch, dass der Abruf von externen Informationen, z.B. das Durchsuchen eines Dokumentensystems, oft nicht in Echtzeit funktioniert. Bereits eine Gesprächsstille von 2-3 Sekunden kann Anfurfer verunsichern. Die Ein- und Anbindung von externen MCP-Systemen ist deshalb sorgfältig zu planen (und zu testen).

Für verbindliche Reservierungen am Telefon ist die Einbindung der Reservierungssysteme u.a. via MCP jedoch ein Muss-Kriterium. Nur so können Sie nachsehen ob und welche Termine frei sind und verbindliche Reservierungen an das System melden.

= Markdown – Formatierung im Prompt =

Im Prompt-Feld unserer Oberfläche wird eine einfache '''Markdown-Formatierung''' verwendet.
Damit können Sie den Text für die KI übersichtlich strukturieren. Das hilft sowohl der KI als auch Ihnen selbst bei Pflege und Erweiterung.

Wichtig: Die hier beschriebene Markdown-Syntax gilt für den '''Prompt-Text''' in der KI-Oberfläche – nicht für dieses Wiki (hier verwenden wir MediaWiki-Syntax).

== Überschriften ==

Überschriften werden mit vorangestellten Rautenzeichen (`#`) definiert:

<pre>
# Hauptüberschrift (Ebene 1)

## Abschnitt (Ebene 2)

### Unterabschnitt (Ebene 3)
</pre>

Empfehlung:

* Verwenden Sie maximal 2–3 Ebenen (z. B. `#`, `##`, `###`).
* Nutzen Sie Überschriften für größere Abschnitte wie „Rolle und Ziel“, „Gesprächsführung“, „Grenzen und Sicherheit“.

== Aufzählungen (Bullet-Points) ==

Einfache Aufzählungen erstellen Sie mit `-` oder `*` am Zeilenanfang:

<pre>
## Öffnungszeiten

- Montag bis Freitag: 09:00–18:00 Uhr
- Samstag: 10:00–14:00 Uhr
- Sonntag: geschlossen
</pre>

Verschachtelte Aufzählungen (Unterpunkte) erstellen Sie durch Einrückung mit Leerzeichen:

<pre>
## Arten von Anrufen

- Reservierungen
- neue Reservierungen
- Änderungen bestehender Reservierungen
- Stornierungen
- Allgemeine Fragen
- Öffnungszeiten
- Anfahrt
- Reklamationen
</pre>

Achten Sie darauf, für Unterpunkte mindestens zwei Leerzeichen vor das `-` zu setzen.
So bleibt die Struktur für die KI gut erkennbar.

== Nummerierte Listen ==

Nummerierte Listen helfen bei klaren Abläufen oder Schritt-für-Schritt-Anweisungen:

<pre>
## Gesprächsablauf

1. Begrüße den Anrufer freundlich und nenne den Namen des Unternehmens.
2. Bitte den Anrufer, in einem Satz zu sagen, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis kurz zusammen und verabschiede dich höflich.
</pre>

== Hervorhebungen (fett) ==

Wichtige Begriffe oder Regeln können Sie fett hervorheben:

<pre>
- Gib **keine medizinischen Diagnosen**.
- Triff **keine verbindlichen Rechtszusagen**.
- Wenn du dir unsicher bist, sage **ehrlich**, dass du es nicht weißt.
</pre>

Technisch wird Fett-Schrift in Markdown mit zwei Sternchen vor und nach dem Text geschrieben: `**wichtiger Text**`.

Sie können bei Bedarf auch kursiv arbeiten (z. B. `_Beispiel_`), in der Praxis reicht aber meist Fett für die wichtigsten Punkte.

== Warum Markdown im Prompt sinnvoll ist ==

Markdown hat zwei Vorteile:

* Für die KI: Eine klar strukturierte Gliederung macht es einfacher, Regeln und Informationen zu „sortieren“.
* Für Sie: Längere Prompts bleiben übersichtlich und sind leichter zu pflegen, weil Sie Abschnitte schneller finden.

Wo möglich, sollten Sie:

* größere Themenblöcke mit Überschriften trennen,
* Regeln und Beispiele in Bullet-Points packen,
* Abläufe mit nummerierten Listen beschreiben.

= Aufbau des Basis-Prompts (Hauptanweisungen) =

Der Basis-Prompt ist das „Handbuch“ Ihrer Telefon-KI. Er wird bei jedem Gespräch mitgeladen und sollte:

* die Rolle und den Tonfall festlegen,
* das verfügbare Wissen beschreiben,
* typische Abläufe und Entscheidungsregeln enthalten,
* Grenzen und Eskalationswege definieren.

== Empfohlene Grundstruktur ==

Eine bewährte Struktur im Markdown-Format könnte z. B. so aussehen:

<pre>
# Rolle und Ziel
Beschreiben Sie hier kurz, wer die KI ist und was ihr Hauptziel ist.

## Begrüßung und Vorstellung
- Wie soll sich die KI melden?
- Wie stellt sie sich vor?
- Wie erklärt sie kurz ihre Funktion als Telefonassistenz?

## Informationen über das Unternehmen / die Organisation
- Name des Unternehmens / der Praxis / Kanzlei
- Art der Leistungen / Angebote
- Wichtige Rahmenbedingungen (z. B. Öffnungszeiten, Sprache, besondere Regeln)

## Gesprächsführung
- In welcher Reihenfolge sollen Fragen gestellt werden?
- Wie kurz oder wie ausführlich sollen Antworten sein?
- Wie soll bei Rückfragen des Anrufers reagiert werden?

## Entscheidungsregeln
- Wie werden Anrufe kategorisiert (z. B. Reservierung, Reklamation, allgemeine Anfrage)?
- Wann soll an eine reale Person weitergeleitet werden?
- Was passiert bei Notfällen oder kritischen Situationen?

## Umgang mit Daten und Zusammenfassungen
- Welche Informationen dürfen erfragt werden?
- Wie sollen Gesprächsergebnisse zusammengefasst werden (für E-Mail / Webhook)?
- Welche Formulierungen sind zu vermeiden?

## Grenzen und Sicherheit
- Was darf die KI nicht tun oder versprechen?
- Wie verhält sie sich bei unsicheren Sachverhalten?
</pre>

Sie können einzelne Abschnitte natürlich anpassen, ergänzen oder weglassen – wichtig ist, dass der Aufbau für Sie nachvollziehbar bleibt.

== Rollenbeschreibung und Tonfall ==

Beschreiben Sie möglichst konkret:

* Wie die KI sich am Telefon vorstellen soll (Name, Funktion).
* Ob sie eher locker, neutral oder sehr formell sprechen soll.
* Ob sie „Sie“ oder „du“ verwendet sowie ob sie inklusiv und respektvoll formulieren soll.

Beispiel (Ausschnitt):

<pre>
# Rolle und Ziel
Du bist die Telefonassistenz der Praxis Dr. Beispiel.
Dein Ziel ist es, Anrufer freundlich zu begrüßen, kurz das Anliegen zu klären und je nach Thema:
- einen Terminwunsch zu erfassen,
- einfache organisatorische Fragen zu beantworten,
- in medizinischen Fragen an das Praxisteam zu verweisen.
</pre>

(„Du“ in diesem Beispiel bezieht sich auf die KI – die Ansprache der Anrufer bleibt „Sie“.)

== Wissen und Grenzen beschreiben ==

Stellen Sie in kurzen Stichpunkten zusammen:

* Welche Informationen die KI sicher weiß (z. B. Öffnungszeiten, Adresse, grundlegende Abläufe).
* Wo die Grenzen liegen (z. B. keine verbindlichen Angebote, keine individuellen Diagnosen).
* Wie mit Wissen umgegangen werden soll, das sich ändern kann (z. B. Preisliste, Aktionen).

Beispiel (Ausschnitt):

<pre>
## Informationen über das Unternehmen
- Du kennst die aktuellen Öffnungszeiten: Diese sind wie folgt ….
- Du kennst die Adresse und Anfahrtshinweise: Unsere Adresse ist …. Gäste sollten bei der
Anfahrt mit dem PKW beachten ….. und bei der Anreise mit Bus und Bahn wie folgt ….
- Du weißt, welche Arten von Terminen grundsätzlich angeboten werden: Diese sind
1. // 2. // 3. usw.

## Grenzen
- Du gibst keine medizinischen Diagnosen.
- Du triffst keine verbindlichen rechtlichen Zusagen.
- Wenn du dir nicht sicher bist, ob eine Auskunft korrekt ist, sagst du das offen
und bietest an, eine Rückmeldung durch das Team zu veranlassen.
</pre>

= Gesprächsführung und Rückfragen =

Definieren Sie, wie die KI systematisch vorgehen soll, z. B.:

* Begrüßung → Anliegen klären → ggf. Details abfragen → Lösung / nächster Schritt → Verabschiedung.
* Rückfragen bei unklaren oder widersprüchlichen Angaben.
* Zusammenfassung vor Gesprächsende („Habe ich das richtig verstanden…?“).

Beispiel (Ausschnitt):

<pre>
## Gesprächsführung

1. Begrüße den Anrufer kurz und freundlich.
2. Bitte ihn in einem Satz zu beschreiben, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen klar verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis am Ende kurz zusammen und frage, ob noch etwas offen ist.
6. Verabschiede dich höflich.
</pre>

= Unter-Prompts (Spezialanweisungen und zusätzliche Regeln) =

Unter-Prompts („Spezialanweisungen“) erlauben es, bestimmte Themenbereiche aus dem Basis-Prompt auszulagern. Sie eignen sich u. a. für:

* Reservierungen / Buchungen (falls dort kein MCP-Server bereitsteht),
* Reklamationen und Beschwerden,
* Anfragen von Lieferanten,
* Notdienst- oder Bereitschaftsregelungen.
* Beschreibungen spezieller Angebote (z.B. bei einer Gastronomie weitere Infors zur Kegelbahn, Brunch, Kaffeetrinken, Grillabende, …. Für jedes Thema ein Unterprompt !)

== Wann Unter-Prompts sinnvoll sind ==

Unter-Prompts lohnen sich vor allem, wenn:

* ein Themenbereich deutlich umfangreicher ist als der Rest,
* eine andere Entscheidungslogik angewendet werden soll,
* Sie bestimmte Informationen später getrennt pflegen möchten.

In unserem Webinterface können Sie für jeden Unter-Prompt Stichworte festlegen. Wenn die KI diese Stichworte erkennt, wird der betreffende Unter-Prompt zusätzlich herangezogen.

== Basis-Prompt und Unter-Prompts aufeinander abstimmen ==

Damit das zuverlässig funktioniert, sollten Sie im Basis-Prompt kurz auf die Unter-Prompts verweisen. Zum Beispiel:

<pre>
## Umgang mit Reservierungen

Wenn ein Anruf erkennbar eine Reservierung betrifft (z. B. Begriffe wie
"Reservierung", "Tisch bestellen", "für heute Abend reservieren"):

- Nutze die Regeln und Informationen aus dem Unter-Prompt "Reservierungen".
- Halte dich an die dort beschriebenen Abläufe und Fragen.
</pre>

Im Unter-Prompt „Reservierungen“ beschreiben Sie dann die Details (z. B. wie Name, Personenanzahl, Datum, Uhrzeit und besondere Wünsche abgefragt werden sollen).

= Besondere Aspekte der Telefon-KI von Portunity =

== Telefonkontext und Gesprächslänge ==

Da Gespräche in Echtzeit stattfinden, sollten Sie im Prompt festlegen:

* Wie viele Sätze die KI am Stück sprechen soll (z. B. kurz und prägnant).
* Wie sie reagieren soll, wenn der Anrufer zwischenruft oder abschweift.
* Dass sie bewusst Pausen lässt, damit der Anrufer zu Wort kommt.

Beispiel (Ausschnitt):

<pre>
## Stil am Telefon

- Sprich in kurzen Sätzen (maximal 2–3 Sätze am Stück).
- Mache kurze Pausen, damit der Anrufer reagieren kann.
- Stelle gezielte Fragen statt langer Monologe.
- Wenn der Anrufer dich unterbricht, hör sofort auf zu reden und gehe auf ihn ein.
</pre>

== Nutzung der Anrufer-Rufnummer im Prompt ==

Über die technische Plattform erhält die Telefon-KI Meta-Informationen zum Anruf, u. a. die anrufende Rufnummer. Sie können im Basis-Prompt festlegen, wie mit dieser Information umgegangen werden soll, zum Beispiel:

* Soll die KI die Rufnummer am Telefon wiederholen oder nicht?
* Darf sie aus der Rufnummer schließen, dass es sich um einen bekannten Kunden handeln könnte?
* Wie soll sie reagieren, wenn keine oder eine unterdrückte Rufnummer übermittelt wird?

Beispiel für entsprechende Anweisungen:

<pre>
## Umgang mit der Rufnummer des Anrufers

- Du kennst die von unserer Telefonanlage übermittelte Rufnummer des Anrufers.
Diese lautet XXXX
- Wiederhole die Rufnummer am Telefon nur dann vollständig, wenn der Anrufer
dich ausdrücklich darum bittet.
- Nutze die Rufnummer ggf. intern, um bekannte Anrufer wieder zu erkennen
(z. B. durch Kennzeichnung in der Zusammenfassung),
ohne am Telefon detaillierte Rückschlüsse offenzulegen.
- Wenn keine Rufnummer übermittelt wird oder sie unvollständig ist, weise nicht
darauf hin, sondern fahre normal fort.
</pre>

Die konkrete technische Verarbeitung der Rufnummer erfolgt im Hintergrund. Im Prompt beschreiben Sie lediglich, wie die KI sich im Gespräch dazu verhalten soll.

== Typische Muster, die sich bewährt haben ==

Die folgenden Muster können Sie in Ihren Prompts immer wieder verwenden:

; Anliegen zuerst klären
: Zuerst kurz und gezielt herausfinden, warum der Anrufer anruft. Danach erst in Details einsteigen.

; Zusammenfassung vor dem Abschluss
: Am Ende kurz wiederholen, was vereinbart wurde. So lassen sich Missverständnisse reduzieren.

; Ehrlichkeit bei Unsicherheit
: Wenn die KI etwas nicht sicher weiß, sollte sie das offen sagen und eine Rückmeldung durch das Team anbieten, statt zu raten.

; Eskalation statt „Halluzination“
: Besser an eine reale Person weiterleiten oder eine Rückrufbitte notieren, als falsche Zusagen zu machen.

Ausformulierte Beispiel-Prompts für typische Branchen finden Sie auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Testen, testen und testen =

Gehen Sie iterativ vor. Also erstmal nur mit einem kleinen Prompt
* der die Begrüßung regelt
* den Namen des Agents und wie er sich verhalten soll (Du oder Sie-Anrede, ob er höflich oder ausführlich sein soll usw.)
* die Öffungszeiten kennt
* und weiß was ihr Unternehmen in 2-3 Sätzen macht

Dies testen Sie dann. Danach fügen Sie Absatz für Absatz weitere Informationen zu. Und testen wieder.

Überlegen Sie, was Ihre Anrufer in der Regel wissen wollen, was sie fragen usw. Versuchen Sie dabei nicht 100% der Fälle sofort ab zu bilden, sondern erst mal das wichtigste. Und dies testen Sie dann.

Für den ersten Agent können schnell ein dutzend Test-Anrufe und ein ganzer Nachmittag an Zeiteinsatz fällig werden. Wenn Sie einen Menschen als Mitarbeiter für das Telefon einstellen, dann müssten Sie diesem ja auch erstmal alles erklären wie er sich am Telefon verhalten soll. Sie müssten ihm das nötige Wissen geben zu Ihren Produkten, Angeboten usw. Genau dies müssen Sie Ihrem KI-Agent auch bei bringen.

Wenn Sie vom ersten Testen müde sind, schlafen Sie eine Nacht drüber - am nächsten Tag kommen neue Ideen. Geben Sie Ihren Kollegen die Gelegenheit den Agent zu testen bevor sie ihn „live schalten“. Ihre Kollegen haben vielleicht ganz andere Dinge wo sie mit Kunden, Interessenten, Lieferanten usw. Telefonieren als Sie vor Augen haben. Erweitern Sie die Prompts entsprechend.

Wenn Sie viel getestet haben schalten Sie live. Und nutzen Sie die Möglichkeiten via Mail oder Webhook die Anruf-Transscriptionen zu erhalten. Aus diesem können Sie in den ersten Wochen viel lernen was gut läuft und vor allem was weniger gut läuft, wo Wissenslücklen sind - und diese gezielt in den Prompts auffüllen.

Vergessen Sie vor dem Live-Schalten nicht das dicke Brett „Datenschutz“, also entsprechende Ansagen vorweg zu schalten, alles zu dokumentieren, alles mit Ihrem Datenschutzbeauftragten / spezialisierten Rechtsanwalt abzustimmen usw.

Telefon-KI - Gute Prompts schreiben

2025-12-09T13:18:42Z

Lr@superroot: /* Nutzung der Anrufer-Rufnummer im Prompt */

= Ziel dieser Seite =

Auf dieser Seite finden Sie Hinweise, wie Sie gute Prompts für Ihre Telefon-KI (KI-Agenten) formulieren.
Im Mittelpunkt stehen:

* der Aufbau des '''Basis-Prompts''' (Hauptanweisungen),
* der sinnvolle Einsatz von '''Unter-Prompts''' (Spezialanweisungen),
* Besonderheiten im Telefonkontext (z. B. Umgang mit unklarer Sprache),
* Portunity-spezifische Aspekte (z. B. Nutzung der Anrufer-Rufnummer im Prompt).

Konkrete Branchen-Beispiele finden Sie zusätzlich auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Grundprinzipien für Prompts in der Telefon-KI =

== Grundregeln ==

Realtime-KI für Telefonie verhält sich etwas anders als ein „normaler“ Chatbot. Folgende Grundregeln haben sich bewährt:

; Klar und widerspruchsfrei formulieren
: Geben Sie klare, eindeutige Anweisungen. Widersprüchliche Regeln („Seien Sie sehr kurz“ und später „Erzählen Sie alles ausführlich“) führen zu unvorhersehbarem Verhalten.

; Stichpunkte statt langer Fließtexte
: Nutzen Sie Überschriften und Aufzählungen. Strukturierte Prompts sind für die Modelle leichter zu interpretieren und später einfacher zu warten.

; Rolle und Grenzen definieren
: Beschreiben Sie, '''wer''' die KI am Telefon sein soll (z. B. Rezeption, Support, Notdienst) und was sie '''nicht''' tun darf (z. B. keine medizinischen Diagnosen, keine verbindliche Rechtsberatung).

; Telefon ist kein Chat
: Am Telefon sind Anrufer ungeduldiger, hören Nebengeräusche und sprechen manchmal undeutlich. Geben Sie der KI Anweisungen, wie sie nachfragt, zusammenfasst und Gesprächsanteile kurz hält.

; Unklare oder fehlerhafte Eingaben aktiv behandeln
: Weisen Sie die KI an, bei schlechtem Audio oder unklaren Angaben nachzufragen, statt zu raten. Besser eine Rückfrage als eine falsche Zusage.

; Pro Agent: eine Hauptaufgabe
: Ein KI-Agent sollte eine gut umrissene Rolle haben (z. B. „Reservierungen & Öffnungszeiten“). Für völlig andere Aufgaben (z. B. Notrufannahme) ist ein eigener Agent sinnvoll.

== Allgemeine Hinweise zu Wissen und Quellen ==

Bevor Sie mit dem eigentlichen Inhalt Ihres Prompts beginnen, sollten Sie ein paar technische Grenzen der Telefon-KI berücksichtigen und im Prompt klar ansprechen.

=== Kein Live-Zugriff auf Websites oder externe Systeme ===

Die Telefon-KI kann während des Gesprächs standardmäßig '''keine''' Informationen live aus dem Internet oder aus anderen Systemen abrufen, z. B.:

* keine Inhalte von Webseiten wie »www.beispiel.de« laden,
* keine Online-Buchungssysteme direkt abfragen (sofern diese nicht ausdrücklich über einen MCP-Server angebunden sind),
* keine Dateien oder Dokumente aus E-Mail-Postfächern oder Cloud-Speichern öffnen (außer diese Sysyteme sind über einen MCP-Server angebunden).

Sie können im Prompt selbstverständlich Formulierungen verwenden wie:

<pre>
"Gäste finden weitere Informationen auch auf unserer Website unter www.meine-website.de."
"Fotos zu unserem Sonntagsbrunch finden Sie auf unserer Website unter /brunch."
</pre>

Diese Hinweise dienen ausschließlich dazu, dass die KI den Anrufer korrekt '''informiert'''.
Die KI nutzt diese URLs jedoch nicht als eigene Wissensquelle – sie „liest“ die Webseiten nicht.

=== Wissensbasis klar begrenzen ===

Für viele Einsatzszenarien ist es sinnvoll, die Wissensbasis der KI bewusst zu begrenzen.
Damit vermeiden Sie, dass die KI Inhalte „halluziniert“ oder sich vermeintliches Wissen „ausdenkt“.

Empfehlung: Fügen Sie in Ihrem Basis-Prompt einen Abschnitt ein, der die Wissensbasis beschreibt, zum Beispiel:

<pre>
## Wissensbasis

- Deine einzige Wissensquelle sind dieser Basis-Prompt und die vorhandenen Unter-Prompts.
- Du erfindest keine Fakten, die hier nicht beschrieben sind.
- Wenn dir Informationen fehlen oder du dir nicht sicher bist, sagst du das offen
(z. B. "Diese Information liegt mir nicht vor." oder "Das weiß ich leider nicht genau.")
und bietest an, eine Rückmeldung durch unser Team zu veranlassen.
</pre>

Damit stellen Sie klar:

* '''Woher''' die KI ihr Wissen bezieht (Basis-Prompt + Unter-Prompts),
* dass sie keine externen Quellen ergänzt,
* wie sie sich bei fehlendem Wissen verhalten soll.

Gerade in sensiblen Bereichen (z. B. Medizin, Recht, Finanzen) ist eine solche Klarstellung besonders wichtig.

=== Externe Wissensquellen via MCP ===

Externe Wissensquellen können und müssen ansonsten über das MCP-Protokoll eingebunden werden. Dies ist ein gesondertes Thema.

Bitte beachten Sie dabei auch, dass der Abruf von externen Informationen, z.B. das Durchsuchen eines Dokumentensystems, oft nicht in Echtzeit funktioniert. Bereits eine Gesprächsstille von 2-3 Sekunden kann Anfurfer verunsichern. Die Ein- und Anbindung von externen MCP-Systemen ist deshalb sorgfältig zu planen (und zu testen).

Für verbindliche Reservierungen am Telefon ist die Einbindung der Reservierungssysteme u.a. via MCP jedoch ein Muss-Kriterium. Nur so können Sie nachsehen ob und welche Termine frei sind und verbindliche Reservierungen an das System melden.

= Markdown – Formatierung im Prompt =

Im Prompt-Feld unserer Oberfläche wird eine einfache '''Markdown-Formatierung''' verwendet.
Damit können Sie den Text für die KI übersichtlich strukturieren. Das hilft sowohl der KI als auch Ihnen selbst bei Pflege und Erweiterung.

Wichtig: Die hier beschriebene Markdown-Syntax gilt für den '''Prompt-Text''' in der KI-Oberfläche – nicht für dieses Wiki (hier verwenden wir MediaWiki-Syntax).

== Überschriften ==

Überschriften werden mit vorangestellten Rautenzeichen (`#`) definiert:

<pre>
# Hauptüberschrift (Ebene 1)

## Abschnitt (Ebene 2)

### Unterabschnitt (Ebene 3)
</pre>

Empfehlung:

* Verwenden Sie maximal 2–3 Ebenen (z. B. `#`, `##`, `###`).
* Nutzen Sie Überschriften für größere Abschnitte wie „Rolle und Ziel“, „Gesprächsführung“, „Grenzen und Sicherheit“.

== Aufzählungen (Bullet-Points) ==

Einfache Aufzählungen erstellen Sie mit `-` oder `*` am Zeilenanfang:

<pre>
## Öffnungszeiten

- Montag bis Freitag: 09:00–18:00 Uhr
- Samstag: 10:00–14:00 Uhr
- Sonntag: geschlossen
</pre>

Verschachtelte Aufzählungen (Unterpunkte) erstellen Sie durch Einrückung mit Leerzeichen:

<pre>
## Arten von Anrufen

- Reservierungen
- neue Reservierungen
- Änderungen bestehender Reservierungen
- Stornierungen
- Allgemeine Fragen
- Öffnungszeiten
- Anfahrt
- Reklamationen
</pre>

Achten Sie darauf, für Unterpunkte mindestens zwei Leerzeichen vor das `-` zu setzen.
So bleibt die Struktur für die KI gut erkennbar.

== Nummerierte Listen ==

Nummerierte Listen helfen bei klaren Abläufen oder Schritt-für-Schritt-Anweisungen:

<pre>
## Gesprächsablauf

1. Begrüße den Anrufer freundlich und nenne den Namen des Unternehmens.
2. Bitte den Anrufer, in einem Satz zu sagen, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis kurz zusammen und verabschiede dich höflich.
</pre>

== Hervorhebungen (fett) ==

Wichtige Begriffe oder Regeln können Sie fett hervorheben:

<pre>
- Gib **keine medizinischen Diagnosen**.
- Triff **keine verbindlichen Rechtszusagen**.
- Wenn du dir unsicher bist, sage **ehrlich**, dass du es nicht weißt.
</pre>

Technisch wird Fett-Schrift in Markdown mit zwei Sternchen vor und nach dem Text geschrieben: `**wichtiger Text**`.

Sie können bei Bedarf auch kursiv arbeiten (z. B. `_Beispiel_`), in der Praxis reicht aber meist Fett für die wichtigsten Punkte.

== Warum Markdown im Prompt sinnvoll ist ==

Markdown hat zwei Vorteile:

* Für die KI: Eine klar strukturierte Gliederung macht es einfacher, Regeln und Informationen zu „sortieren“.
* Für Sie: Längere Prompts bleiben übersichtlich und sind leichter zu pflegen, weil Sie Abschnitte schneller finden.

Wo möglich, sollten Sie:

* größere Themenblöcke mit Überschriften trennen,
* Regeln und Beispiele in Bullet-Points packen,
* Abläufe mit nummerierten Listen beschreiben.

= Aufbau des Basis-Prompts (Hauptanweisungen) =

Der Basis-Prompt ist das „Handbuch“ Ihrer Telefon-KI. Er wird bei jedem Gespräch mitgeladen und sollte:

* die Rolle und den Tonfall festlegen,
* das verfügbare Wissen beschreiben,
* typische Abläufe und Entscheidungsregeln enthalten,
* Grenzen und Eskalationswege definieren.

== Empfohlene Grundstruktur ==

Eine bewährte Struktur im Markdown-Format könnte z. B. so aussehen:

<pre>
# Rolle und Ziel
Beschreiben Sie hier kurz, wer die KI ist und was ihr Hauptziel ist.

## Begrüßung und Vorstellung
- Wie soll sich die KI melden?
- Wie stellt sie sich vor?
- Wie erklärt sie kurz ihre Funktion als Telefonassistenz?

## Informationen über das Unternehmen / die Organisation
- Name des Unternehmens / der Praxis / Kanzlei
- Art der Leistungen / Angebote
- Wichtige Rahmenbedingungen (z. B. Öffnungszeiten, Sprache, besondere Regeln)

## Gesprächsführung
- In welcher Reihenfolge sollen Fragen gestellt werden?
- Wie kurz oder wie ausführlich sollen Antworten sein?
- Wie soll bei Rückfragen des Anrufers reagiert werden?

## Entscheidungsregeln
- Wie werden Anrufe kategorisiert (z. B. Reservierung, Reklamation, allgemeine Anfrage)?
- Wann soll an eine reale Person weitergeleitet werden?
- Was passiert bei Notfällen oder kritischen Situationen?

## Umgang mit Daten und Zusammenfassungen
- Welche Informationen dürfen erfragt werden?
- Wie sollen Gesprächsergebnisse zusammengefasst werden (für E-Mail / Webhook)?
- Welche Formulierungen sind zu vermeiden?

## Grenzen und Sicherheit
- Was darf die KI nicht tun oder versprechen?
- Wie verhält sie sich bei unsicheren Sachverhalten?
</pre>

Sie können einzelne Abschnitte natürlich anpassen, ergänzen oder weglassen – wichtig ist, dass der Aufbau für Sie nachvollziehbar bleibt.

== Rollenbeschreibung und Tonfall ==

Beschreiben Sie möglichst konkret:

* Wie die KI sich am Telefon vorstellen soll (Name, Funktion).
* Ob sie eher locker, neutral oder sehr formell sprechen soll.
* Ob sie „Sie“ oder „du“ verwendet sowie ob sie inklusiv und respektvoll formulieren soll.

Beispiel (Ausschnitt):

<pre>
# Rolle und Ziel
Du bist die Telefonassistenz der Praxis Dr. Beispiel.
Dein Ziel ist es, Anrufer freundlich zu begrüßen, kurz das Anliegen zu klären und je nach Thema:
- einen Terminwunsch zu erfassen,
- einfache organisatorische Fragen zu beantworten,
- in medizinischen Fragen an das Praxisteam zu verweisen.
</pre>

(„Du“ in diesem Beispiel bezieht sich auf die KI – die Ansprache der Anrufer bleibt „Sie“.)

== Wissen und Grenzen beschreiben ==

Stellen Sie in kurzen Stichpunkten zusammen:

* Welche Informationen die KI sicher weiß (z. B. Öffnungszeiten, Adresse, grundlegende Abläufe).
* Wo die Grenzen liegen (z. B. keine verbindlichen Angebote, keine individuellen Diagnosen).
* Wie mit Wissen umgegangen werden soll, das sich ändern kann (z. B. Preisliste, Aktionen).

Beispiel (Ausschnitt):

<pre>
## Informationen über das Unternehmen
- Du kennst die aktuellen Öffnungszeiten: Diese sind wie folgt ….
- Du kennst die Adresse und Anfahrtshinweise: Unsere Adresse ist …. Gäste sollten bei der
Anfahrt mit dem PKW beachten ….. und bei der Anreise mit Bus und Bahn wie folgt ….
- Du weißt, welche Arten von Terminen grundsätzlich angeboten werden: Diese sind
1. // 2. // 3. usw.

## Grenzen
- Du gibst keine medizinischen Diagnosen.
- Du triffst keine verbindlichen rechtlichen Zusagen.
- Wenn du dir nicht sicher bist, ob eine Auskunft korrekt ist, sagst du das offen
und bietest an, eine Rückmeldung durch das Team zu veranlassen.
</pre>

= Gesprächsführung und Rückfragen =

Definieren Sie, wie die KI systematisch vorgehen soll, z. B.:

* Begrüßung → Anliegen klären → ggf. Details abfragen → Lösung / nächster Schritt → Verabschiedung.
* Rückfragen bei unklaren oder widersprüchlichen Angaben.
* Zusammenfassung vor Gesprächsende („Habe ich das richtig verstanden…?“).

Beispiel (Ausschnitt):

<pre>
## Gesprächsführung

1. Begrüße den Anrufer kurz und freundlich.
2. Bitte ihn in einem Satz zu beschreiben, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen klar verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis am Ende kurz zusammen und frage, ob noch etwas offen ist.
6. Verabschiede dich höflich.
</pre>

= Unter-Prompts (Spezialanweisungen und zusätzliche Regeln) =

Unter-Prompts („Spezialanweisungen“) erlauben es, bestimmte Themenbereiche aus dem Basis-Prompt auszulagern. Sie eignen sich u. a. für:

* Reservierungen / Buchungen (falls dort kein MCP-Server bereitsteht),
* Reklamationen und Beschwerden,
* Anfragen von Lieferanten,
* Notdienst- oder Bereitschaftsregelungen.
* Beschreibungen spezieller Angebote (z.B. bei einer Gastronomie weitere Infors zur Kegelbahn, Brunch, Kaffeetrinken, Grillabende, …. Für jedes Thema ein Unterprompt !)

== Wann Unter-Prompts sinnvoll sind ==

Unter-Prompts lohnen sich vor allem, wenn:

* ein Themenbereich deutlich umfangreicher ist als der Rest,
* eine andere Entscheidungslogik angewendet werden soll,
* Sie bestimmte Informationen später getrennt pflegen möchten.

In unserem Webinterface können Sie für jeden Unter-Prompt Stichworte festlegen. Wenn die KI diese Stichworte erkennt, wird der betreffende Unter-Prompt zusätzlich herangezogen.

== Basis-Prompt und Unter-Prompts aufeinander abstimmen ==

Damit das zuverlässig funktioniert, sollten Sie im Basis-Prompt kurz auf die Unter-Prompts verweisen. Zum Beispiel:

<pre>
## Umgang mit Reservierungen

Wenn ein Anruf erkennbar eine Reservierung betrifft (z. B. Begriffe wie
"Reservierung", "Tisch bestellen", "für heute Abend reservieren"):

- Nutze die Regeln und Informationen aus dem Unter-Prompt "Reservierungen".
- Halte dich an die dort beschriebenen Abläufe und Fragen.
</pre>

Im Unter-Prompt „Reservierungen“ beschreiben Sie dann die Details (z. B. wie Name, Personenanzahl, Datum, Uhrzeit und besondere Wünsche abgefragt werden sollen).

= Besondere Aspekte der Telefon-KI von Portunity =

== Telefonkontext und Gesprächslänge ==

Da Gespräche in Echtzeit stattfinden, sollten Sie im Prompt festlegen:

* Wie viele Sätze die KI am Stück sprechen soll (z. B. kurz und prägnant).
* Wie sie reagieren soll, wenn der Anrufer zwischenruft oder abschweift.
* Dass sie bewusst Pausen lässt, damit der Anrufer zu Wort kommt.

Beispiel (Ausschnitt):

<pre>
## Stil am Telefon

- Sprich in kurzen Sätzen (maximal 2–3 Sätze am Stück).
- Mache kurze Pausen, damit der Anrufer reagieren kann.
- Stelle gezielte Fragen statt langer Monologe.
- Wenn der Anrufer dich unterbricht, hör sofort auf zu reden und gehe auf ihn ein.
</pre>

== Nutzung der Anrufer-Rufnummer im Prompt ==

Über die technische Plattform erhält die Telefon-KI Meta-Informationen zum Anruf, u. a. die anrufende Rufnummer. Sie können im Basis-Prompt festlegen, wie mit dieser Information umgegangen werden soll, zum Beispiel:

* Soll die KI die Rufnummer am Telefon wiederholen oder nicht?
* Darf sie aus der Rufnummer schließen, dass es sich um einen bekannten Kunden handeln könnte?
* Wie soll sie reagieren, wenn keine oder eine unterdrückte Rufnummer übermittelt wird?

Beispiel für entsprechende Anweisungen:

<pre>
## Umgang mit der Rufnummer des Anrufers

- Du kennst die von unserer Telefonanlage übermittelte Rufnummer des Anrufers.
Diese lautet XXXX
- Wiederhole die Rufnummer am Telefon nur dann vollständig, wenn der Anrufer
dich ausdrücklich darum bittet.
- Nutze die Rufnummer ggf. intern, um bekannte Anrufer wieder zu erkennen
(z. B. durch Kennzeichnung in der Zusammenfassung),
ohne am Telefon detaillierte Rückschlüsse offenzulegen.
- Wenn keine Rufnummer übermittelt wird oder sie unvollständig ist, weise nicht
darauf hin, sondern fahre normal fort.
</pre>

Die konkrete technische Verarbeitung der Rufnummer erfolgt im Hintergrund. Im Prompt beschreiben Sie lediglich, wie die KI sich im Gespräch dazu verhalten soll.

== Typische Muster, die sich bewährt haben ==

Die folgenden Muster können Sie in Ihren Prompts immer wieder verwenden:

; Anliegen zuerst klären
: Zuerst kurz und gezielt herausfinden, warum der Anrufer anruft. Danach erst in Details einsteigen.

; Zusammenfassung vor dem Abschluss
: Am Ende kurz wiederholen, was vereinbart wurde. So lassen sich Missverständnisse reduzieren.

; Ehrlichkeit bei Unsicherheit
: Wenn die KI etwas nicht sicher weiß, sollte sie das offen sagen und eine Rückmeldung durch das Team anbieten, statt zu raten.

; Eskalation statt „Halluzination“
: Besser an eine reale Person weiterleiten oder eine Rückrufbitte notieren, als falsche Zusagen zu machen.

Ausformulierte Beispiel-Prompts für typische Branchen finden Sie auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Testen, testen und testen =

Gehen Sie iterativ vor. Also erstmal nur mit einem kleinen Prompt
* der die Begrüßung regelt
* den Namen des Agents und wie er sich verhalten soll (Du oder Sie-Anrede, ob er höflich oder ausführlich sein soll usw.)
* die Öffungszeiten kennt
* und weiß was ihr Unternehmen in 2-3 Sätzen macht

Dies testen Sie dann. Danach fügen Sie Absatz für Absatz weitere Informationen zu. Und testen wieder.

Überlegen Sie, was Ihre Anrufer in der Regel wissen wollen, was sie fragen usw. Versuchen Sie dabei nicht 100% der Fälle sofort ab zu bilden, sondern erst mal das wichtigste. Und dies testen Sie dann.

Für den ersten Agent können schnell ein dutzend Test-Anrufe und ein ganzer Nachmittag an Zeiteinsatz fällig werden. Wenn Sie einen Menschen als Mitarbeiter für das Telefon einstellen, dann müssten Sie diesem ja auch erstmal alles erklären wie er sich am Telefon verhalten soll. Sie müssten ihm das nötige Wissen geben zu Ihren Produkten, Angeboten usw. Genau dies müssen Sie Ihrem KI-Agent auch bei bringen.

Wenn Sie vom ersten Testen müde sind, schlafen Sie eine Nacht drüber - am nächsten Tag kommen neue Ideen. Geben Sie Ihren Kollegen die Gelegenheit den Agent zu testen bevor sie ihn „live schalten“. Ihre Kollegen haben vielleicht ganz andere Dinge wo sie mit Kunden, Interessenten, Lieferanten usw. Telefonieren als Sie vor Augen haben. Erweitern Sie die Prompts entsprechend.

Wenn Sie viel getestet haben schalten Sie live. Und nutzen Sie die Möglichkeiten via Mail oder Webhook die Anruf-Transscriptionen zu erhalten. Aus diesem können Sie in den ersten Wochen viel lernen was gut läuft und vor allem was weniger gut läuft, wo Wissenslücklen sind - und diese gezielt in den Prompts auffüllen.

Vergessen Sie vor dem Live-Schalten nicht das dicke Brett „Datenschutz“, also entsprechende Ansagen vorweg zu schalten, alles zu dokumentieren, alles mit Ihrem Datenschutzbeauftragten / spezialisierten Rechtsanwalt abzustimmen usw.

Telefon-KI - Gute Prompts schreiben

2025-12-09T13:17:43Z

Lr@superroot: /* Wissen und Grenzen beschreiben */

= Ziel dieser Seite =

Auf dieser Seite finden Sie Hinweise, wie Sie gute Prompts für Ihre Telefon-KI (KI-Agenten) formulieren.
Im Mittelpunkt stehen:

* der Aufbau des '''Basis-Prompts''' (Hauptanweisungen),
* der sinnvolle Einsatz von '''Unter-Prompts''' (Spezialanweisungen),
* Besonderheiten im Telefonkontext (z. B. Umgang mit unklarer Sprache),
* Portunity-spezifische Aspekte (z. B. Nutzung der Anrufer-Rufnummer im Prompt).

Konkrete Branchen-Beispiele finden Sie zusätzlich auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Grundprinzipien für Prompts in der Telefon-KI =

== Grundregeln ==

Realtime-KI für Telefonie verhält sich etwas anders als ein „normaler“ Chatbot. Folgende Grundregeln haben sich bewährt:

; Klar und widerspruchsfrei formulieren
: Geben Sie klare, eindeutige Anweisungen. Widersprüchliche Regeln („Seien Sie sehr kurz“ und später „Erzählen Sie alles ausführlich“) führen zu unvorhersehbarem Verhalten.

; Stichpunkte statt langer Fließtexte
: Nutzen Sie Überschriften und Aufzählungen. Strukturierte Prompts sind für die Modelle leichter zu interpretieren und später einfacher zu warten.

; Rolle und Grenzen definieren
: Beschreiben Sie, '''wer''' die KI am Telefon sein soll (z. B. Rezeption, Support, Notdienst) und was sie '''nicht''' tun darf (z. B. keine medizinischen Diagnosen, keine verbindliche Rechtsberatung).

; Telefon ist kein Chat
: Am Telefon sind Anrufer ungeduldiger, hören Nebengeräusche und sprechen manchmal undeutlich. Geben Sie der KI Anweisungen, wie sie nachfragt, zusammenfasst und Gesprächsanteile kurz hält.

; Unklare oder fehlerhafte Eingaben aktiv behandeln
: Weisen Sie die KI an, bei schlechtem Audio oder unklaren Angaben nachzufragen, statt zu raten. Besser eine Rückfrage als eine falsche Zusage.

; Pro Agent: eine Hauptaufgabe
: Ein KI-Agent sollte eine gut umrissene Rolle haben (z. B. „Reservierungen & Öffnungszeiten“). Für völlig andere Aufgaben (z. B. Notrufannahme) ist ein eigener Agent sinnvoll.

== Allgemeine Hinweise zu Wissen und Quellen ==

Bevor Sie mit dem eigentlichen Inhalt Ihres Prompts beginnen, sollten Sie ein paar technische Grenzen der Telefon-KI berücksichtigen und im Prompt klar ansprechen.

=== Kein Live-Zugriff auf Websites oder externe Systeme ===

Die Telefon-KI kann während des Gesprächs standardmäßig '''keine''' Informationen live aus dem Internet oder aus anderen Systemen abrufen, z. B.:

* keine Inhalte von Webseiten wie »www.beispiel.de« laden,
* keine Online-Buchungssysteme direkt abfragen (sofern diese nicht ausdrücklich über einen MCP-Server angebunden sind),
* keine Dateien oder Dokumente aus E-Mail-Postfächern oder Cloud-Speichern öffnen (außer diese Sysyteme sind über einen MCP-Server angebunden).

Sie können im Prompt selbstverständlich Formulierungen verwenden wie:

<pre>
"Gäste finden weitere Informationen auch auf unserer Website unter www.meine-website.de."
"Fotos zu unserem Sonntagsbrunch finden Sie auf unserer Website unter /brunch."
</pre>

Diese Hinweise dienen ausschließlich dazu, dass die KI den Anrufer korrekt '''informiert'''.
Die KI nutzt diese URLs jedoch nicht als eigene Wissensquelle – sie „liest“ die Webseiten nicht.

=== Wissensbasis klar begrenzen ===

Für viele Einsatzszenarien ist es sinnvoll, die Wissensbasis der KI bewusst zu begrenzen.
Damit vermeiden Sie, dass die KI Inhalte „halluziniert“ oder sich vermeintliches Wissen „ausdenkt“.

Empfehlung: Fügen Sie in Ihrem Basis-Prompt einen Abschnitt ein, der die Wissensbasis beschreibt, zum Beispiel:

<pre>
## Wissensbasis

- Deine einzige Wissensquelle sind dieser Basis-Prompt und die vorhandenen Unter-Prompts.
- Du erfindest keine Fakten, die hier nicht beschrieben sind.
- Wenn dir Informationen fehlen oder du dir nicht sicher bist, sagst du das offen
(z. B. "Diese Information liegt mir nicht vor." oder "Das weiß ich leider nicht genau.")
und bietest an, eine Rückmeldung durch unser Team zu veranlassen.
</pre>

Damit stellen Sie klar:

* '''Woher''' die KI ihr Wissen bezieht (Basis-Prompt + Unter-Prompts),
* dass sie keine externen Quellen ergänzt,
* wie sie sich bei fehlendem Wissen verhalten soll.

Gerade in sensiblen Bereichen (z. B. Medizin, Recht, Finanzen) ist eine solche Klarstellung besonders wichtig.

=== Externe Wissensquellen via MCP ===

Externe Wissensquellen können und müssen ansonsten über das MCP-Protokoll eingebunden werden. Dies ist ein gesondertes Thema.

Bitte beachten Sie dabei auch, dass der Abruf von externen Informationen, z.B. das Durchsuchen eines Dokumentensystems, oft nicht in Echtzeit funktioniert. Bereits eine Gesprächsstille von 2-3 Sekunden kann Anfurfer verunsichern. Die Ein- und Anbindung von externen MCP-Systemen ist deshalb sorgfältig zu planen (und zu testen).

Für verbindliche Reservierungen am Telefon ist die Einbindung der Reservierungssysteme u.a. via MCP jedoch ein Muss-Kriterium. Nur so können Sie nachsehen ob und welche Termine frei sind und verbindliche Reservierungen an das System melden.

= Markdown – Formatierung im Prompt =

Im Prompt-Feld unserer Oberfläche wird eine einfache '''Markdown-Formatierung''' verwendet.
Damit können Sie den Text für die KI übersichtlich strukturieren. Das hilft sowohl der KI als auch Ihnen selbst bei Pflege und Erweiterung.

Wichtig: Die hier beschriebene Markdown-Syntax gilt für den '''Prompt-Text''' in der KI-Oberfläche – nicht für dieses Wiki (hier verwenden wir MediaWiki-Syntax).

== Überschriften ==

Überschriften werden mit vorangestellten Rautenzeichen (`#`) definiert:

<pre>
# Hauptüberschrift (Ebene 1)

## Abschnitt (Ebene 2)

### Unterabschnitt (Ebene 3)
</pre>

Empfehlung:

* Verwenden Sie maximal 2–3 Ebenen (z. B. `#`, `##`, `###`).
* Nutzen Sie Überschriften für größere Abschnitte wie „Rolle und Ziel“, „Gesprächsführung“, „Grenzen und Sicherheit“.

== Aufzählungen (Bullet-Points) ==

Einfache Aufzählungen erstellen Sie mit `-` oder `*` am Zeilenanfang:

<pre>
## Öffnungszeiten

- Montag bis Freitag: 09:00–18:00 Uhr
- Samstag: 10:00–14:00 Uhr
- Sonntag: geschlossen
</pre>

Verschachtelte Aufzählungen (Unterpunkte) erstellen Sie durch Einrückung mit Leerzeichen:

<pre>
## Arten von Anrufen

- Reservierungen
- neue Reservierungen
- Änderungen bestehender Reservierungen
- Stornierungen
- Allgemeine Fragen
- Öffnungszeiten
- Anfahrt
- Reklamationen
</pre>

Achten Sie darauf, für Unterpunkte mindestens zwei Leerzeichen vor das `-` zu setzen.
So bleibt die Struktur für die KI gut erkennbar.

== Nummerierte Listen ==

Nummerierte Listen helfen bei klaren Abläufen oder Schritt-für-Schritt-Anweisungen:

<pre>
## Gesprächsablauf

1. Begrüße den Anrufer freundlich und nenne den Namen des Unternehmens.
2. Bitte den Anrufer, in einem Satz zu sagen, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis kurz zusammen und verabschiede dich höflich.
</pre>

== Hervorhebungen (fett) ==

Wichtige Begriffe oder Regeln können Sie fett hervorheben:

<pre>
- Gib **keine medizinischen Diagnosen**.
- Triff **keine verbindlichen Rechtszusagen**.
- Wenn du dir unsicher bist, sage **ehrlich**, dass du es nicht weißt.
</pre>

Technisch wird Fett-Schrift in Markdown mit zwei Sternchen vor und nach dem Text geschrieben: `**wichtiger Text**`.

Sie können bei Bedarf auch kursiv arbeiten (z. B. `_Beispiel_`), in der Praxis reicht aber meist Fett für die wichtigsten Punkte.

== Warum Markdown im Prompt sinnvoll ist ==

Markdown hat zwei Vorteile:

* Für die KI: Eine klar strukturierte Gliederung macht es einfacher, Regeln und Informationen zu „sortieren“.
* Für Sie: Längere Prompts bleiben übersichtlich und sind leichter zu pflegen, weil Sie Abschnitte schneller finden.

Wo möglich, sollten Sie:

* größere Themenblöcke mit Überschriften trennen,
* Regeln und Beispiele in Bullet-Points packen,
* Abläufe mit nummerierten Listen beschreiben.

= Aufbau des Basis-Prompts (Hauptanweisungen) =

Der Basis-Prompt ist das „Handbuch“ Ihrer Telefon-KI. Er wird bei jedem Gespräch mitgeladen und sollte:

* die Rolle und den Tonfall festlegen,
* das verfügbare Wissen beschreiben,
* typische Abläufe und Entscheidungsregeln enthalten,
* Grenzen und Eskalationswege definieren.

== Empfohlene Grundstruktur ==

Eine bewährte Struktur im Markdown-Format könnte z. B. so aussehen:

<pre>
# Rolle und Ziel
Beschreiben Sie hier kurz, wer die KI ist und was ihr Hauptziel ist.

## Begrüßung und Vorstellung
- Wie soll sich die KI melden?
- Wie stellt sie sich vor?
- Wie erklärt sie kurz ihre Funktion als Telefonassistenz?

## Informationen über das Unternehmen / die Organisation
- Name des Unternehmens / der Praxis / Kanzlei
- Art der Leistungen / Angebote
- Wichtige Rahmenbedingungen (z. B. Öffnungszeiten, Sprache, besondere Regeln)

## Gesprächsführung
- In welcher Reihenfolge sollen Fragen gestellt werden?
- Wie kurz oder wie ausführlich sollen Antworten sein?
- Wie soll bei Rückfragen des Anrufers reagiert werden?

## Entscheidungsregeln
- Wie werden Anrufe kategorisiert (z. B. Reservierung, Reklamation, allgemeine Anfrage)?
- Wann soll an eine reale Person weitergeleitet werden?
- Was passiert bei Notfällen oder kritischen Situationen?

## Umgang mit Daten und Zusammenfassungen
- Welche Informationen dürfen erfragt werden?
- Wie sollen Gesprächsergebnisse zusammengefasst werden (für E-Mail / Webhook)?
- Welche Formulierungen sind zu vermeiden?

## Grenzen und Sicherheit
- Was darf die KI nicht tun oder versprechen?
- Wie verhält sie sich bei unsicheren Sachverhalten?
</pre>

Sie können einzelne Abschnitte natürlich anpassen, ergänzen oder weglassen – wichtig ist, dass der Aufbau für Sie nachvollziehbar bleibt.

== Rollenbeschreibung und Tonfall ==

Beschreiben Sie möglichst konkret:

* Wie die KI sich am Telefon vorstellen soll (Name, Funktion).
* Ob sie eher locker, neutral oder sehr formell sprechen soll.
* Ob sie „Sie“ oder „du“ verwendet sowie ob sie inklusiv und respektvoll formulieren soll.

Beispiel (Ausschnitt):

<pre>
# Rolle und Ziel
Du bist die Telefonassistenz der Praxis Dr. Beispiel.
Dein Ziel ist es, Anrufer freundlich zu begrüßen, kurz das Anliegen zu klären und je nach Thema:
- einen Terminwunsch zu erfassen,
- einfache organisatorische Fragen zu beantworten,
- in medizinischen Fragen an das Praxisteam zu verweisen.
</pre>

(„Du“ in diesem Beispiel bezieht sich auf die KI – die Ansprache der Anrufer bleibt „Sie“.)

== Wissen und Grenzen beschreiben ==

Stellen Sie in kurzen Stichpunkten zusammen:

* Welche Informationen die KI sicher weiß (z. B. Öffnungszeiten, Adresse, grundlegende Abläufe).
* Wo die Grenzen liegen (z. B. keine verbindlichen Angebote, keine individuellen Diagnosen).
* Wie mit Wissen umgegangen werden soll, das sich ändern kann (z. B. Preisliste, Aktionen).

Beispiel (Ausschnitt):

<pre>
## Informationen über das Unternehmen
- Du kennst die aktuellen Öffnungszeiten: Diese sind wie folgt ….
- Du kennst die Adresse und Anfahrtshinweise: Unsere Adresse ist …. Gäste sollten bei der
Anfahrt mit dem PKW beachten ….. und bei der Anreise mit Bus und Bahn wie folgt ….
- Du weißt, welche Arten von Terminen grundsätzlich angeboten werden: Diese sind
1. // 2. // 3. usw.

## Grenzen
- Du gibst keine medizinischen Diagnosen.
- Du triffst keine verbindlichen rechtlichen Zusagen.
- Wenn du dir nicht sicher bist, ob eine Auskunft korrekt ist, sagst du das offen
und bietest an, eine Rückmeldung durch das Team zu veranlassen.
</pre>

= Gesprächsführung und Rückfragen =

Definieren Sie, wie die KI systematisch vorgehen soll, z. B.:

* Begrüßung → Anliegen klären → ggf. Details abfragen → Lösung / nächster Schritt → Verabschiedung.
* Rückfragen bei unklaren oder widersprüchlichen Angaben.
* Zusammenfassung vor Gesprächsende („Habe ich das richtig verstanden…?“).

Beispiel (Ausschnitt):

<pre>
## Gesprächsführung

1. Begrüße den Anrufer kurz und freundlich.
2. Bitte ihn in einem Satz zu beschreiben, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen klar verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis am Ende kurz zusammen und frage, ob noch etwas offen ist.
6. Verabschiede dich höflich.
</pre>

= Unter-Prompts (Spezialanweisungen und zusätzliche Regeln) =

Unter-Prompts („Spezialanweisungen“) erlauben es, bestimmte Themenbereiche aus dem Basis-Prompt auszulagern. Sie eignen sich u. a. für:

* Reservierungen / Buchungen (falls dort kein MCP-Server bereitsteht),
* Reklamationen und Beschwerden,
* Anfragen von Lieferanten,
* Notdienst- oder Bereitschaftsregelungen.
* Beschreibungen spezieller Angebote (z.B. bei einer Gastronomie weitere Infors zur Kegelbahn, Brunch, Kaffeetrinken, Grillabende, …. Für jedes Thema ein Unterprompt !)

== Wann Unter-Prompts sinnvoll sind ==

Unter-Prompts lohnen sich vor allem, wenn:

* ein Themenbereich deutlich umfangreicher ist als der Rest,
* eine andere Entscheidungslogik angewendet werden soll,
* Sie bestimmte Informationen später getrennt pflegen möchten.

In unserem Webinterface können Sie für jeden Unter-Prompt Stichworte festlegen. Wenn die KI diese Stichworte erkennt, wird der betreffende Unter-Prompt zusätzlich herangezogen.

== Basis-Prompt und Unter-Prompts aufeinander abstimmen ==

Damit das zuverlässig funktioniert, sollten Sie im Basis-Prompt kurz auf die Unter-Prompts verweisen. Zum Beispiel:

<pre>
## Umgang mit Reservierungen

Wenn ein Anruf erkennbar eine Reservierung betrifft (z. B. Begriffe wie
"Reservierung", "Tisch bestellen", "für heute Abend reservieren"):

- Nutze die Regeln und Informationen aus dem Unter-Prompt "Reservierungen".
- Halte dich an die dort beschriebenen Abläufe und Fragen.
</pre>

Im Unter-Prompt „Reservierungen“ beschreiben Sie dann die Details (z. B. wie Name, Personenanzahl, Datum, Uhrzeit und besondere Wünsche abgefragt werden sollen).

= Besondere Aspekte der Telefon-KI von Portunity =

== Telefonkontext und Gesprächslänge ==

Da Gespräche in Echtzeit stattfinden, sollten Sie im Prompt festlegen:

* Wie viele Sätze die KI am Stück sprechen soll (z. B. kurz und prägnant).
* Wie sie reagieren soll, wenn der Anrufer zwischenruft oder abschweift.
* Dass sie bewusst Pausen lässt, damit der Anrufer zu Wort kommt.

Beispiel (Ausschnitt):

<pre>
## Stil am Telefon

- Sprich in kurzen Sätzen (maximal 2–3 Sätze am Stück).
- Mache kurze Pausen, damit der Anrufer reagieren kann.
- Stelle gezielte Fragen statt langer Monologe.
- Wenn der Anrufer dich unterbricht, hör sofort auf zu reden und gehe auf ihn ein.
</pre>

== Nutzung der Anrufer-Rufnummer im Prompt ==

Über die technische Plattform erhält die Telefon-KI Meta-Informationen zum Anruf, u. a. die anrufende Rufnummer. Sie können im Basis-Prompt festlegen, wie mit dieser Information umgegangen werden soll, zum Beispiel:

* Soll die KI die Rufnummer am Telefon wiederholen oder nicht?
* Darf sie aus der Rufnummer schließen, dass es sich um einen bekannten Kunden handeln könnte?
* Wie soll sie reagieren, wenn keine oder eine unterdrückte Rufnummer übermittelt wird?

Beispiel für entsprechende Anweisungen:

<pre>
## Umgang mit der Rufnummer des Anrufers

- Du kennst die von unserer Telefonanlage übermittelte Rufnummer des Anrufers. Diese lautet XXXX
- Wiederhole die Rufnummer am Telefon nur dann vollständig, wenn der Anrufer dich ausdrücklich darum bittet.
- Nutze die Rufnummer ggf. intern, um bekannte Anrufer wiederzuerkennen (z. B. durch Kennzeichnung in der Zusammenfassung),
ohne am Telefon detaillierte Rückschlüsse offenzulegen.
- Wenn keine Rufnummer übermittelt wird oder sie unvollständig ist, weise nicht darauf hin, sondern fahre normal fort.
</pre>

Die konkrete technische Verarbeitung der Rufnummer erfolgt im Hintergrund. Im Prompt beschreiben Sie lediglich, wie die KI sich im Gespräch dazu verhalten soll.

== Typische Muster, die sich bewährt haben ==

Die folgenden Muster können Sie in Ihren Prompts immer wieder verwenden:

; Anliegen zuerst klären
: Zuerst kurz und gezielt herausfinden, warum der Anrufer anruft. Danach erst in Details einsteigen.

; Zusammenfassung vor dem Abschluss
: Am Ende kurz wiederholen, was vereinbart wurde. So lassen sich Missverständnisse reduzieren.

; Ehrlichkeit bei Unsicherheit
: Wenn die KI etwas nicht sicher weiß, sollte sie das offen sagen und eine Rückmeldung durch das Team anbieten, statt zu raten.

; Eskalation statt „Halluzination“
: Besser an eine reale Person weiterleiten oder eine Rückrufbitte notieren, als falsche Zusagen zu machen.

Ausformulierte Beispiel-Prompts für typische Branchen finden Sie auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Testen, testen und testen =

Gehen Sie iterativ vor. Also erstmal nur mit einem kleinen Prompt
* der die Begrüßung regelt
* den Namen des Agents und wie er sich verhalten soll (Du oder Sie-Anrede, ob er höflich oder ausführlich sein soll usw.)
* die Öffungszeiten kennt
* und weiß was ihr Unternehmen in 2-3 Sätzen macht

Dies testen Sie dann. Danach fügen Sie Absatz für Absatz weitere Informationen zu. Und testen wieder.

Überlegen Sie, was Ihre Anrufer in der Regel wissen wollen, was sie fragen usw. Versuchen Sie dabei nicht 100% der Fälle sofort ab zu bilden, sondern erst mal das wichtigste. Und dies testen Sie dann.

Für den ersten Agent können schnell ein dutzend Test-Anrufe und ein ganzer Nachmittag an Zeiteinsatz fällig werden. Wenn Sie einen Menschen als Mitarbeiter für das Telefon einstellen, dann müssten Sie diesem ja auch erstmal alles erklären wie er sich am Telefon verhalten soll. Sie müssten ihm das nötige Wissen geben zu Ihren Produkten, Angeboten usw. Genau dies müssen Sie Ihrem KI-Agent auch bei bringen.

Wenn Sie vom ersten Testen müde sind, schlafen Sie eine Nacht drüber - am nächsten Tag kommen neue Ideen. Geben Sie Ihren Kollegen die Gelegenheit den Agent zu testen bevor sie ihn „live schalten“. Ihre Kollegen haben vielleicht ganz andere Dinge wo sie mit Kunden, Interessenten, Lieferanten usw. Telefonieren als Sie vor Augen haben. Erweitern Sie die Prompts entsprechend.

Wenn Sie viel getestet haben schalten Sie live. Und nutzen Sie die Möglichkeiten via Mail oder Webhook die Anruf-Transscriptionen zu erhalten. Aus diesem können Sie in den ersten Wochen viel lernen was gut läuft und vor allem was weniger gut läuft, wo Wissenslücklen sind - und diese gezielt in den Prompts auffüllen.

Vergessen Sie vor dem Live-Schalten nicht das dicke Brett „Datenschutz“, also entsprechende Ansagen vorweg zu schalten, alles zu dokumentieren, alles mit Ihrem Datenschutzbeauftragten / spezialisierten Rechtsanwalt abzustimmen usw.

KI-Telefonie – Hinweise

2025-11-25T15:17:55Z

Lr@superroot: /* Was Sie mindestens beachten sollten (Kurz-Checkliste) */

= KI-Telefonie – Hinweise & Support=

==Worum geht es hier?==

Mit der Telefon-KI können eingehende Anrufe automatisch von einer KI-gestützten Telefonassistenz (einem sogenannten KI-Agenten) angenommen, ausgewertet und beantwortet werden. In unseren VoIP-Tarifen sind diese Funktionen, je nach Tarif mit unterschiedlichen Limitierungen und Preisen, technisch enthalten.

'''Diese Seiten erklären Ihnen:'''

* welche rechtlichen Punkte Sie als Betreiber beachten sollten,
* wie Sie die Telefon-KI in deinem VoIP-Tarif einrichten,
* wie Sie gute Prompts schreiben,
* und bieten Ihnen praxisnahe Beispiel-Prompts für typische Einsatzszenarien.

==Für wen ist diese Dokumentation gedacht?==

* Inhaber:innen und Verantwortliche von VoIP-Accounts und Rufnummern (z. B. Unternehmen, Praxen, Kanzleien, Handwerker, KMUs …),
* Administrator:innen, die VoIP-Tarife und KI-Agenten konfigurieren,
* Reseller, die die Telefon-KI an eigene Kund:innen weitergeben.

== Was Sie mindestens beachten sollten (Kurz-Checkliste)==

'''Diese Liste ersetzt keine Rechtsberatung''', hilft Ihnen aber bei der Orientierung - genau wie alle Text hier bei uns zum Thema Recht. Wir lösen die technischen Probleme für Sie, bei den rechtlichen können wir nur erste Ideen geben, keine Beratung. Dafür gibt es Ihren Datenschutz-Beauftragten und spezialisierte Rechtsanwälte:

* [ ] Sie wissen, '''wofür''' Sie die Telefon-KI einsetzen wollen (z. B. Vorqualifizierung, Reservierungen, Infotelefon).
* [ ] Sie haben geprüft, '''welche Daten''' dabei verarbeitet werden (Rufnummer, Gesprächsinhalt, Mitschnitt, Transkript).
* [ ] Sie informieren deine Anrufer:innen '''zu Beginn des Gesprächs''', dass eine KI eingesetzt wird.
* [ ] Sie holen für die Verarbeitung von Ihren Anrufer:innen zu Beginn des Gesprächs '''eine Einwilligung''', z.B. per abgestuften Verfahren.
* [ ] Falls Sie '''Mitschnitte oder Transkripte''' aktivieren und weiter verarbeiten, haben Sie Ihre Datenschutzhinweise entsprechend angepasst und – falls nötig – eine Einwilligungslösung umgesetzt.
* [ ] Sie haben festgelegt, '''wie lange''' Sie Mitschnitte/Transkripte aufbewahrst und wer darauf zugreifen darf.
* [ ] Sie haben die Telefon-KI mit einem Probeanruf '''umfassend getestet''', bevor Sie sie produktiv einsetzen.

== Die Detail-Seiten zur Telefon-KI bei uns im Wiki==

Da alle Infos eine Wiki-Seite sprengen würden, haben wir die Themen auf einzelne Wiki-Seiten verteilt:

* '''[[Telefon-KI - Rechtliche Orientierung & Datenschutz |Rechtliche Orientierung & Datenschutz]]:''' Grundlagen zu DSGVO, AI-Act, Informations- und Einwilligungspflichten und welche Punkte Sie prüfen sollten.

* '''[[Telefon-KI - einrichten und konfigurieren|Telefon-KI einrichten und konfigurieren - Schritt für Schritt]]''': Von der Tarifauswahl über das Anlegen eines KI-Agenten bis zum Routing und der vorgeschalteten Ansage.

* '''[[Telefon-KI - Gute Prompts schreiben|Gute Prompts schreiben]]''': Aufbau eines guten Basis-Prompts, Einsatz von Unter-Prompts (Spezialanweisungen) und typische Stolperfallen.

* '''[[Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]''': Fertige Beispiel-Prompts für typische Branchen (z. B. Gastronomie, Handwerk, Arztpraxis, Kanzlei) sowie Best Practices aus der Praxis.

KI-Telefonie – Hinweise

2025-11-25T15:17:35Z

Lr@superroot: /* KI-Telefonie – Hinweise & Support */

= KI-Telefonie – Hinweise & Support=

==Worum geht es hier?==

Mit der Telefon-KI können eingehende Anrufe automatisch von einer KI-gestützten Telefonassistenz (einem sogenannten KI-Agenten) angenommen, ausgewertet und beantwortet werden. In unseren VoIP-Tarifen sind diese Funktionen, je nach Tarif mit unterschiedlichen Limitierungen und Preisen, technisch enthalten.

'''Diese Seiten erklären Ihnen:'''

* welche rechtlichen Punkte Sie als Betreiber beachten sollten,
* wie Sie die Telefon-KI in deinem VoIP-Tarif einrichten,
* wie Sie gute Prompts schreiben,
* und bieten Ihnen praxisnahe Beispiel-Prompts für typische Einsatzszenarien.

==Für wen ist diese Dokumentation gedacht?==

* Inhaber:innen und Verantwortliche von VoIP-Accounts und Rufnummern (z. B. Unternehmen, Praxen, Kanzleien, Handwerker, KMUs …),
* Administrator:innen, die VoIP-Tarife und KI-Agenten konfigurieren,
* Reseller, die die Telefon-KI an eigene Kund:innen weitergeben.

== Was Sie mindestens beachten sollten (Kurz-Checkliste)==

'''Diese Liste ersetzt keine Rechtsberatung''', hilft Ihnen aber bei der Orientierung - genau wie alle Text hier bei uns zum Thema Recht. Wir lösen die technischen Probleme für Sie, bei den rechtlichen können wir nur erste Ideen geben, keine Beratung. Dafür gibt es Ihren Datenschutz-Beauftragten und spezialisierte Rechtsanwälte:

* [ ] Sie wissen, '''wofür''' du die Telefon-KI einsetzen willst (z. B. Vorqualifizierung, Reservierungen, Infotelefon).
* [ ] Sie haben geprüft, '''welche Daten''' dabei verarbeitet werden (Rufnummer, Gesprächsinhalt, Mitschnitt, Transkript).
* [ ] Sie informieren deine Anrufer:innen '''zu Beginn des Gesprächs''', dass eine KI eingesetzt wird.
* [ ] Sie holen für die Verarbeitung von Ihren Anrufer:innen zu Beginn des Gesprächs '''eine Einwilligung''', z.B. per abgestuften Verfahren.
* [ ] Falls Sie '''Mitschnitte oder Transkripte''' aktivieren und weiter verarbeiten, haben Sie Ihre Datenschutzhinweise entsprechend angepasst und – falls nötig – eine Einwilligungslösung umgesetzt.
* [ ] Sie haben festgelegt, '''wie lange''' Sie Mitschnitte/Transkripte aufbewahrst und wer darauf zugreifen darf.
* [ ] Sie haben die Telefon-KI mit einem Probeanruf '''umfassend getestet''', bevor Sie sie produktiv einsetzen.

== Die Detail-Seiten zur Telefon-KI bei uns im Wiki==

Da alle Infos eine Wiki-Seite sprengen würden, haben wir die Themen auf einzelne Wiki-Seiten verteilt:

* '''[[Telefon-KI - Rechtliche Orientierung & Datenschutz |Rechtliche Orientierung & Datenschutz]]:''' Grundlagen zu DSGVO, AI-Act, Informations- und Einwilligungspflichten und welche Punkte Sie prüfen sollten.

* '''[[Telefon-KI - einrichten und konfigurieren|Telefon-KI einrichten und konfigurieren - Schritt für Schritt]]''': Von der Tarifauswahl über das Anlegen eines KI-Agenten bis zum Routing und der vorgeschalteten Ansage.

* '''[[Telefon-KI - Gute Prompts schreiben|Gute Prompts schreiben]]''': Aufbau eines guten Basis-Prompts, Einsatz von Unter-Prompts (Spezialanweisungen) und typische Stolperfallen.

* '''[[Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]''': Fertige Beispiel-Prompts für typische Branchen (z. B. Gastronomie, Handwerk, Arztpraxis, Kanzlei) sowie Best Practices aus der Praxis.

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T14:41:52Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T14:39:13Z

Lr@superroot:

KI-Telefonie – Hinweise

2025-11-25T14:20:45Z

Lr@superroot: /* Die Detail-Seiten zur Telefon-KI bei uns im Wiki */

= KI-Telefonie – Hinweise & Support=

==Worum geht es hier?==

Mit der Telefon-KI können eingehende Anrufe automatisch von einer KI-gestützten Telefonassistenz (einem sogenannten KI-Agenten) angenommen, ausgewertet und beantwortet werden. In unseren VoIP-Tarifen sind diese Funktionen, je nach Tarif mit unterschiedlichen Limitierungen und Preisen, technisch enthalten.

'''Diese Seiten erklären dir:'''

* welche rechtlichen Punkte du als Betreiber beachten solltest,
* wie du die Telefon-KI in deinem VoIP-Tarif einrichtest,
* wie du gute Prompts schreibst,
* und bieten dir praxisnahe Beispiel-Prompts für typische Einsatzszenarien.

==Für wen ist diese Dokumentation gedacht?==

* Inhaber:innen und Verantwortliche von VoIP-Accounts und Rufnummern (z. B. Unternehmen, Praxen, Kanzleien, Handwerker, KMUs …),
* Administrator:innen, die VoIP-Tarife und KI-Agenten konfigurieren,
* Reseller, die die Telefon-KI an eigene Kund:innen weitergeben.

== Was du mindestens beachten solltest (Kurz-Checkliste)==

'''Diese Liste ersetzt keine Rechtsberatung''', hilft dir aber bei der Orientierung - genau wie alle Text hier bei uns zum Thema Recht. Wir lösen die technischen Probleme für Sie, bei den rechtlichen können wir nur erste Ideen geben, keine Beratung. Dafür gibt es Ihren Datenschutz-Beauftragten und spezialisierte Rechtsanwälte:

* [ ] Du weißt, '''wofür''' du die Telefon-KI einsetzen willst (z. B. Vorqualifizierung, Reservierungen, Infotelefon).
* [ ] Du hast geprüft, '''welche Daten''' dabei verarbeitet werden (Rufnummer, Gesprächsinhalt, Mitschnitt, Transkript).
* [ ] Du informierst deine Anrufer:innen '''zu Beginn des Gesprächs''', dass eine KI eingesetzt wird.
* [ ] Du holst Dir für die Verarbeitung von deinen Anrufer:innen zu Beginn des Gesprächs '''eine Einwilligung''', z.B. per abgestuften Verfahren.
* [ ] Falls du '''Mitschnitte oder Transkripte''' aktivierst und weiter verarbeitest, hast du deine Datenschutzhinweise entsprechend angepasst und – falls nötig – eine Einwilligungslösung umgesetzt.
* [ ] Du hast festgelegt, '''wie lange''' du Mitschnitte/Transkripte aufbewahrst und wer darauf zugreifen darf.
* [ ] Du hast die Telefon-KI mit einem Probeanruf '''umfassend getestet''', bevor du sie produktiv einsetzt.

== Die Detail-Seiten zur Telefon-KI bei uns im Wiki==

Da alle Infos eine Wiki-Seite sprengen würden, haben wir die Themen auf einzelne Wiki-Seiten verteilt:

* '''[[Telefon-KI - Rechtliche Orientierung & Datenschutz |Rechtliche Orientierung & Datenschutz]]:''' Grundlagen zu DSGVO, AI-Act, Informations- und Einwilligungspflichten und welche Punkte du prüfen solltest.

* '''[[Telefon-KI - einrichten und konfigurieren|Telefon-KI einrichten und konfigurieren - Schritt für Schritt]]''': Von der Tarifauswahl über das Anlegen eines KI-Agenten bis zum Routing und der vorgeschalteten Ansage.

* '''[[Telefon-KI - Gute Prompts schreiben|Gute Prompts schreiben]]''': Aufbau eines guten Basis-Prompts, Einsatz von Unter-Prompts (Spezialanweisungen) und typische Stolperfallen.

* '''[[Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]''': Fertige Beispiel-Prompts für typische Branchen (z. B. Gastronomie, Handwerk, Arztpraxis, Kanzlei) sowie Best Practices aus der Praxis.

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T14:09:02Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T14:08:15Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T14:01:35Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T13:51:34Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T13:38:20Z

Lr@superroot: /* Unter-Prompt „Brunch“ (Platzhalter) */

= Wichtiger Hinweis vorab (bitte lesen) =

Diese Seite stellt '''Beispiel-Prompts''' für die Telefon-KI zur Verfügung und zeigt, wie konkrete Konfigurationen aussehen können.
Sie soll Ihnen helfen, eigene Ideen zu entwickeln und die Möglichkeiten der Telefon-KI besser einschätzen zu können.

'''Wichtig:'''

* Wir sind technischer Dienstleister, '''keine Rechts- oder Datenschutzkanzlei'''.
* Wir können und dürfen '''keine Rechtsberatung''' leisten.
* Alle Beispiel-Prompts auf dieser Seite sind:
** '''unverbindliche Denkanstöße''',
** '''nicht''' geprüft im Hinblick auf Ihre konkrete Rechtslage,
** '''nicht''' als 1:1 kopierbare Muster gedacht.

Wenn Sie einen der hier vorgestellten Prompts (oder Teile davon) für Ihren Betrieb nutzen möchten, müssen Sie:

* Inhalte, Formulierungen und Abläufe immer an Ihren konkreten Anwendungsfall anpassen,
* die Texte mit Ihrem Datenschutzbeauftragten bzw. Ihrer Rechtsberatung abstimmen,
* selbst prüfen (lassen), ob die Umsetzung rechtlich zulässig ist.

= Wie Sie diese Beispiele verwenden sollten =

Die Beispiele auf dieser Seite sollen Ihnen helfen,

* die Struktur eines gut aufgebauten Basis-Prompts zu verstehen,
* typische Bausteine (Rolle, Gesprächsführung, Wissensbasis, Grenzen) zu erkennen,
* ein Gefühl für sinnvolle Länge und Detailtiefe zu bekommen,
* Ideen für eigene Branchen-Prompts zu entwickeln.

Bitte beachten Sie dabei:

* Passen Sie immer:
** Namen des Unternehmens / der Praxis / Kanzlei,
** Öffnungszeiten und Kontaktdaten,
** konkrete Angebote und Abläufe,
** Hinweise zu Datenschutz und Einwilligung
an Ihre Situation an.

* Übernehmen Sie '''nie''' Formulierungen blind, wenn rechtliche Aspekte berührt sind (z. B. Datenschutzansagen, Einwilligungstexte).

Weitere Hinweise zum Aufbau und zur Struktur finden Sie auf der Seite
'''[[Telefon-KI - Gute Prompts schreiben|Telefon-KI – Gute Prompts schreiben]]'''.

= Beispiel 1: Kreativer Mittelerde-Agent als Demo (Fantasy-Welt / „Mittelerde“-inspiriert) =

Dieses Beispiel zeigt einen '''kompakten, voll funktionsfähigen Prompt''' für eine rein '''kreative Demo-Telefon-KI'''.
Die Idee: Eine Fantasy-Hotline, die Anrufer:innen humorvoll in eine fantastische Welt mit Elben, Zwergen, Orks, Zauberern usw. mitnimmt. Außerdem soll die Demo zeigen, wie das antrainierte Wissen der eingersetzten KI in einer Telefon-KI wirkt. In eigenen Firmen-Telefon-KIs möchte man genau dies eigentlich nicht - sondern dass Wissen auf eine eigene Wissensdatenbank limitieren. Dieses Beispiel zeigt dafür, gerade aufgrund einer fehlender eigenen Wissensdatenbank, einige der restlichen Prompt-Beispiele anschaulich.

'''Hinweis zu Marken- und Urheberrechten:'''

* Dieses Beispiel kann sich in Tonalität und Begriffen an bekannten Fantasy-Welten (z. B. Mittelerde) orientieren.
* Alle erwähnten Namen und Begriffe gehören den jeweiligen Rechteinhabern.
* Das Beispiel dient ausschließlich dazu, die technischen Möglichkeiten und das Prompt-Design zu illustrieren.
* Es stellt '''kein offizielles oder lizenziertes Angebot''' zu diesen Werken dar.
* Bitte nutzen Sie dieses Beispiel nur als '''Demo''' und passen Sie es an, wenn Sie es produktiv einsetzen möchten.

== Prompt-Beispiel für eine Mittelerde-Hotline (Basis-Prompt als Fantasy-Demo) ==

<pre>
# Rolle und Ziel

Du bist eine KI-gestützter Wirt einer Schenke in der Welt Mittelerdes. Dein Ziel ist
es, Anruferinnen und Anrufer mit humorvollen Witzen, kurzen Geschichten und kleinen
Dialogen aus Mittelerde zu unterhalten.

## Wissensbasis

- Du nutzt dein antrainiertes Wissen über J. R. R. Tolkiens Welt Mittelerde,
einschließlich typischer Orte, Völker, Figuren und Sprachen.
- Du darfst bekannte Figuren wie z. B. Gandalf, Frodo, Sam, Legolas, Gimli,
Aragorn, Arwen, Galadriel, Elrond, Bilbo, Sauron oder Gollum erwähnen.
- Du zitierst keine längeren Textstellen wörtlich aus Büchern, Filmen oder
anderen Originalwerken.
- Du fasst keine kompletten Buch- oder Filmhandlungen im Detail nach, sondern
bleibst bei kurzen Anspielungen, Witzen und Anekdoten.
- Zusätzlich hältst du dich an alle Regeln und Hinweise aus diesem Prompt
(z. B. Gesprächslänge, Tonfall, Grenzen).
- Du verwendest keine Live-Informationen aus dem Internet oder aus anderen
externen Systemen.

## Begrüßung

Melde dich immer mit exakt folgendem Satz, bevor du etwas anderes sagst:

"Aiya, meldor! Willkommen in meiner Schenke voller schräger Geschichten
aus Mittelerde. Möchten Sie etwas Spezielles hören – oder soll ich einfach
mal loslegen?"

## Gesprächsführung

- Halte deine Antworten kurz und pointiert, als würdest du mündlich
erzählen (maximal 3–4 Sätze pro Witz oder Anekdote).
- Erzähle nur Witze, Anekdoten oder kleine Szenen mit klarem Bezug
zu Mittelerde und seinen Völkern (Elben, Zwerge, Menschen, Hobbits,
Orks, Ents, Zauberer usw.).
- Du darfst nicht in andere fiktive Welten oder die Realität abdriften
- Du darfst normale Witze „umfrisieren“, indem du sie in Mittelerde
ansiedelst (z. B. statt „Kellner“ ein Hobbit-Wirt, statt „Chef“
ein Zauberer).
- Bleibe familienfreundlich: keine explizite Gewalt, keine
sexualisierten Inhalte, keine Beleidigungen.
- Verwende gelegentlich kurze elbische Wörter, Ausdrücke oder
Sätze (z. B. in Quenya ) und erkläre auf Deutsch in einem Halbsatz,
was sie bedeuten.

## Auf Wünsche eingehen

- Wenn der Anrufer einen Wunsch äußert (z. B. „Erzählen Sie etwas
mit Zwergen“, „Mache einen Witz über Orks“), passt du den nächsten
Witz entsprechend an.
- Wenn der Anrufer sagt, dass ihm der Witz nicht gefallen hat,
entschuldigst du dich kurz und versuchst einen anderen Stil oder ein
anderes Volk (z. B. statt Orks → Hobbits).
- Falls keine Vorgaben gemacht werden, erzähle spontan und
abwechslungsreich: kurze Flachwitze, längere Anekdoten oder
Wortwitze – gemischt mit typischen Sprüchen und Redewendungen aus
Mittelerde.
- Nach jedem Witz oder jeder Anekdote lade den Anrufer aktiv ein,
weiterzumachen**. Stelle dafür immer eine kurze, offene Frage, z. B.:
- "Willst du noch einen Ork-Flachwitz hören, oder lieber eine
epische Geschichte mit Gandalf?"
- "Möchtest du diesmal etwas auf Quenya, oder soll ich dir einen
Hobbit-Witz erzählen?"
- "Soll ich die Schenke mit einem weiteren Witz füllen – oder reicht
das Abenteuer für heute?"

## Gesprächsende

Beende das Gespräch immer höflich mit einem kurzen Satz, z. B.:

"Vielen Dank für Ihren Besuch in unserer kleinen Schenke Mittelerdes.
Mögen Ihre Wege hell sein – und Ihre Abenteuer voller guter Geschichten!"

## Hinweise für die Sprachausgabe (Realtime API)

- Sprich mit lebendiger, erzählerischer Stimme.
- Bei Pointen: etwas schneller und mit heller Betonung.
- Bei Beschreibungen: langsamer, tiefer, erzählerisch.
- Nutze kurze Pausen mit "…" oder "–", um Spannung aufzubauen.
- Wenn du unterschiedliche Figuren nachahmst, kannst du im Text
interne Hinweise wie [tiefe Stimme], [flüsternd], [grummelnd]
verwenden, um die Stimmung zu kennzeichnen.
</pre>

== Erläuterungen zum Fantasy-Beispiel ==

Dieses Beispiel ist bewusst als '''Spielwiese''' gedacht: Es soll zeigen, wie sich das antrainierte Wissen der eingesetzten KI anfühlt, wenn man es nicht auf eine eigene Wissensdatenbank begrenzt. Für produktive Firmen-Agents empfehlen wir in der Regel genau das Gegenteil – also eine stärkere Eingrenzung der Wissensbasis (siehe '''[[Telefon-KI - Gute Prompts schreiben|Gute Prompts schreiben]]''').

Die Mittelerde-Hotline eignet sich deshalb gut als erstes Testobjekt:

* der Prompt ist relativ kurz und übersichtlich,
* Änderungen lassen sich schnell ausprobieren,
* gleichzeitig ist die Welt der Geschichten für viele Anrufende sofort „greifbar“.

=== Struktur des Fantasy-Prompts ===

Der Prompt folgt – in verkleinerter Form – der Struktur, die wir auch für produktive Agents empfehlen:

; '''Rolle und Ziel'''
: Hier wird festgelegt, '''wer''' die KI sein soll und was ihr Hauptzweck ist.
: Im Beispiel: Eine erzählende Telefonassistenz, die Anrufer:innen mit Witzen und Anekdoten aus Mittelerde unterhält.
: Das verhindert, dass die KI in andere Rollen „abrutscht“ (z. B. Support, Beratung, Smalltalk ohne Bezug zur Fantasy-Welt).

; '''Wissensbasis'''
: In produktiven Szenarien empfehlen wir meist, die Wissensbasis auf den Prompt und Unter-Prompts zu begrenzen.
: In diesem Demo-Prompt machen wir aber ganz bewusst das Gegenteil:
: Die KI soll ihr antrainiertes Wissen zu Mittelerde nutzen – gleichzeitig begrenzen wir Risiken:
:* keine langen wörtlichen Zitate,
:* keine detailgetreue Nacherzählung kompletter Buch- oder Filmhandlungen,
:* kein Zugriff auf Live-Informationen aus dem Internet,
:* Einhaltung der weiteren Regeln im Prompt (familienfreundliche Witze, Tonfall usw.).
: So lässt sich gut beobachten, was das Modell „von sich aus“ über Mittelerde weiß und wie sich dieses Wissen am Telefon anfühlt.

; '''Begrüßung'''
: Die Begrüßung ist als '''fixer Satz''' vorgegeben.
: Das hat zwei Effekte:
:* Wiedererkennungswert für Anrufer:innen („CI“ der Demo-Hotline),
:* die KI „kommt gar nicht erst auf die Idee“, sich anders vorzustellen.
: In produktiven Szenarien können Sie hier z. B. Ihren Firmennamen, Ihre Marke oder eine kurze Rollenbeschreibung unterbringen.

; '''Gesprächsführung'''
: Dieser Abschnitt steuert die eigentliche Art, wie die KI spricht:
:* kurze Antworten (3–4 Sätze) statt Monologe,
:* klare Vorgabe: Witze und Anekdoten mit Bezug zu Mittelerde,
:* Umformung „normaler“ Witze in das Mittelerde-Setting,
:* familienfreundliche Inhalte,
:* gelegentliche elbische Wörter mit kurzer Erklärung.
: Aus technischer Sicht ist das genau das, was auch bei einer „seriösen“ Hotline wichtig wäre – nur eben mit anderem Inhalt (z. B. Reservierungen statt Witze).

; '''Auf Wünsche eingehen'''
: Hier wird beschrieben, wie die KI mit Nutzerwünschen umgeht:
:* Themenwünsche (z. B. „etwas mit Zwergen“) beeinflussen den nächsten Witz,
:* Kritik („der Witz war nicht gut“) führt zu einem Stilwechsel.
: Für produktive Agents könnte an dieser Stelle z. B. stehen:
: „Wenn der Anrufer einen Reservierungswunsch äußert, verwende die Regeln aus dem Unter-Prompt ‚Reservierungen‘ …“ – das Muster bleibt dasselbe.

; '''Gesprächsende'''
: Viele KIs beenden Gespräche sonst eher abrupt.
: Ein definierter Abschluss-Satz sorgt dafür, dass das Gespräch für Anrufer:innen „rund“ wirkt und nicht wie ein Abbruch mitten im Satz.
: Im Produktivbetrieb könnten hier z. B. Rückrufzusagen oder Hinweise auf Öffnungszeiten verankert werden.

; '''Hinweise für die Sprachausgabe'''
: Dieser Block verbindet Text-Prompt und Sprachausgabe:
:* erzählerischer Stil,
:* unterschiedliche Sprechweisen für Pointen vs. Beschreibungen,
:* kurze Pausen zur Dramaturgie,
:* optionale Hinweis-Tags wie [tiefe Stimme], [flüsternd], [grummelnd].
: Solche Hinweise sind insbesondere in Realtime-Szenarien hilfreich, wenn Sie bestimmten Stellen im Gespräch mehr Gewicht geben möchten.

=== Was Sie aus diesem Beispiel für produktive Agents mitnehmen können ===

Auch wenn dieses Beispiel rein spielerisch ist, lassen sich eine Reihe von Konzepten direkt auf „ernste“ Einsätze übertragen:

* Eine klar definierte '''Rolle''' verhindert, dass die KI in unerwünschte Aufgaben „hineinrutscht“.
* Eine explizit formulierte '''Wissensbasis''' und sichtbare Grenzen (was sie nicht tun darf) reduzieren unerwartete Antworten.
* Eine feste '''Begrüßung''' und ein definierter '''Abschluss''' sorgen für einen konsistenten Eindruck bei Anrufer:innen.
* Die Regeln zur '''Gesprächsführung''' (kurz, strukturiert, auf das Anliegen fokussiert) sind für alle Branchen gültig.
* Der Umgang mit '''Wünschen und Feedback''' der Anrufenden (Themenwünsche, „das gefällt mir / gefällt mir nicht“) ähnelt dem Umgang mit verschiedenen Anliegen in realen Hotlines.
* Hinweise zur '''Sprachausgabe''' helfen, dass sich die KI weniger „roboterhaft“ anhört.

Gleichzeitig zeigt das Beispiel sehr deutlich:

* wie sich das antrainierte Weltwissen der KI im Telefonkontext anfühlt,
* warum Sie dieses Wissen in produktiven Szenarien meist stärker begrenzen möchten,
* und wie viel Kontrolle Sie allein über einen gut strukturierten Prompt gewinnen können.

Für reale Unternehmens-Agents (z. B. Gastronomie, Handwerk, Arztpraxis) sollten Sie die Wissensbasis deutlich stärker auf Ihre eigenen Inhalte fokussieren und rechtliche Vorgaben (insbesondere Datenschutz) berücksichtigen – siehe dazu insbesondere
'''[[Telefon-KI - Rechtliche Orientierung & Datenschutz|Telefon-KI – Rechtliche Orientierung & Datenschutz]]'''.

= Beispiel 2: Prompt für ein Restaurant / Gastronomie (mit umfangreicherer Wissensbasis) =

Dieses Beispiel basiert auf einer realen Gastronomie-Konfiguration (Landgasthof / Restaurant) mit einer sehr umfangreichen Wissensbasis.
Für diese Wiki-Seite wird der Inhalt anonymisiert und auf zentrale Teile reduziert.

Ziele dieses Beispiels:

* Zeigen, wie ein '''größerer Basis-Prompt''' für ein Restaurant aufgebaut sein kann.
* Veranschaulichen, welche Inhalte sich für '''Unter-Prompts''' anbieten (z. B. Brunch, Kegelbahn, Grillabende).
* Aufzeigen, warum es sinnvoll ist, große Wissensblöcke in Unter-Prompts auszulagern.
* Das Beispiel ist zunächst ohne eine Anbindung an ein Reservierungssystem via MCP um die Komplexität nicht zu erhöhren. Reservierungen werden aufgenommen und über das enthaltene Mail-Versand nach dem Gespräch an ein Gäste-Anfragen-System geschickt - wo sie dann im Posteingang zur weiteren Bearbeitung bereit liegen.
* Das Beispiel enthält auch keine Verknüpfung zu einem Dokumentensystem als erweiterte Wissensdatenbank, wo z.B. Tageskarten liegen könnten - auch sowas könnte via MCP angebunden werden - ist hier im Beispiel aber nicht berücksichtigt. Bei einer Implementierung wäre eine vollumfängliche Auskunft zur Speisekarte technisch machbar.

== Prompt-Beispiel (Basis-Prompt – Gastronomie, gekürzte Variante) ==

<pre>
# Rolle und Ziel

Du bist eine KI-gestützte Telefonassistenz mit dem Namen Mira.
Du arbeitest für ein familiengeführtes Restaurant mit Biergarten
("Landgasthof am Wald"). Deine Hauptaufgabe ist es, Anrufe freundlich
anzunehmen, Anliegen der Gäste zu strukturieren und – wo möglich –
direkt zu beantworten.

Du übernimmst insbesondere:
- Anfragen zu Öffnungszeiten, Angeboten und Veranstaltungen,
- Tischreservierungen,
- strukturierte Annahme von Anliegen von Lieferanten.

Du bist höflich, warm und professionell, sprichst, wenn deutsch, in
klarem Hochdeutsch und bleibst immer geduldig – auch dann, wenn
Anrufer gestresst sind oder undeutlich sprechen. Wenn Gäste nicht
deutsch sprechen kannst du auch auf nicht-deutsch antworten.

## Begrüßung und Gesprächsführung

Melde dich bei jedem Anruf immer mit einem der folgenden Sätze
(abwechsle ruhig ein wenig):

- "Guten Tag, hier ist Mira vom Landgasthofs am Wald. Wie kann ich
Ihnen helfen?"
- "Herzlich willkommen im Landgasthof am Wald, hier spricht Mira,
Was kann ich für Sie tun?"

Wenn der Anrufer deinen Namen nicht verstanden hat, wiederhole ihn
langsam und deutlich.

Halte deine Antworten kurz, vermeide lange Ausführungen und Band
wurmsätze.

## Gesprächsende

Beende das Gespräch immer höflich mit einem kurzen Satz, z. B.:

"Vielen Dank für Ihren Anruf. Wir freuen uns Sie bald persönlich in
unserem Haus willkommen heissen zu dürfen und wünschen Ihnen bis
dahin alles Gute."

Variere diesen Satz bei jedem Anruf etwas ohne inhaltlich
abzuweichen.

# Typische Anrufer und wie du damit umgehst

## Gäste

- Behandle Gäste immer besonders freundlich und wertschätzend.

### Gäste und Reservierungen

- Wir nehmen nur Reservierungen im Innenbereich an, nicht für
den Biergarten (Aussen-Terasse) - weil dies wettertechnisch
nie 100%ig planbar ist. Die Gäste können dann vor Ort schauen.
- Frage bei Reservierungswünschen strukturiert nach:
- Datum und Uhrzeit
- Anzahl der Personen,
- Name der reservierenden Person,
- Rückrufnummer - kannst du die übermittelte Rufnummer verwenden
(nenne die letzten 4 Ziffern) oder eine andere für die
Reservierung genommen werden soll
- besondere Wünsche (z. B. Kinderstuhl, Hunde, barrierefreier Platz).
- Wenn der Wunsch außerhalb der Öffnungszeiten liegt oder knapp an
einer Schließzeit, erkläre das kurz und schlage eine passende,
alternative Uhrzeit vor.
- Bestätige am Ende in einem Satz, was du notiert hast, z. B.:
"Ich habe für Sie notiert: Tischreservierung am Samstag, 19 Uhr,
für vier Personen auf den Namen Müller mit Rückrufnummer 01234…"
- Du kann Reservierungen bis 6 Gästen verbindlich bestätigen,
für größere Gruppen sagst du, dass du alles aufnimmst und es vom
Service bestätigt wird.
- Auch bei größere Feiern kannst du nur alles aufnehmen und es
meldet sich dann jemand zurück.

### Lieferanten

- Wenn sich Lieferanten melden (z. B. Getränkehändler, Lebensmittel,
Technikdienstleister), notierst du:
- Namen des Unternehmens,
- Namen der Kontaktperson,
- Rückrufnummer,
- das konkrete Anliegen.
- Fasse das Anliegen am Ende kurz zusammen und versichere, dass das
Team die Nachricht erhält und sich bei Bedarf meldet.

### Werbeanrufe und Spam

- Wenn Anrufer offensichtlich nur etwas verkaufen möchten (z. B. neue
Energieverträge, Werbedienstleistungen), bleibe höflich, aber
deutlich:
- bedanke dich kurz,
- erkläre, dass solche Angebote ausschließlich per E-Mail an die
allgemeine Adresse angenommen werden,
- nenne eine neutrale E-Mail-Adresse wie "info@beispiel-restaurant.de".
- Sorge dafür, dass solche Anrufer nicht unnötig verbunden werden.

### Geschäftsleitung / besondere Fälle

- Wenn ausdrücklich nach der Geschäftsleitung oder namentlich nach
"Max Mustermann" oder "Susi Musterfrau" gefragt wird, nimmst du
Name, Rückrufnummer und Grund des Anrufs auf. Meistens handelt es
sich aber hierbei auch um Werbeamnrufe / spammige Anrufe. Wenn
beim Grund sich eine Werbeanruf rauskristalisiert, verweise auf
die Mailadresse.
- Erkläre, dass du keinen direkten Durchstell-Service bieten kannst,
das Anliegen aber weiterleitest.

# Wissensbasis

- Deine Wissensquelle sind dieser Basis-Prompt und die vorhandenen
Unter-Prompts (z. B. "Brunch", "Kegelbahn", "Grillabende").
- Du nutzt keine Live-Informationen aus dem Internet oder anderen
externen Systemen, außer ausdrücklich angegebene Tools.
- Du erfindest keine Fakten, die hier nicht beschrieben sind.
- Wenn dir Informationen fehlen oder du dir unsicher bist, sagst du das
offen (z. B. "Diese Information liegt mir nicht vor, unser Team meldet
sich dazu gerne bei Ihnen.") und bietest an, dass jemand aus dem Team
zurückruft.

## Informationen zum Restaurant

### Weitere Kontaktdaten

- EMail: info@meine-muster-domain.de

### Öffnungszeiten (Beispielwerte, bitte anpassen)

- Dienstag bis Freitag: 12:00–14:30 Uhr und 17:30–22:00 Uhr
- Samstag: 12:00–22:00 Uhr (durchgehend warme Küche)
- Sonntag: 10:30–18:00 Uhr (mit Brunch und Nachmittagsangebot)
- Montag: Ruhetag

Restaurant bleibt geschlossen für den Urlaub:
- Januar vom 2.1.2026 bis 16.1.2026
- August vom 1.8. bis 14.8.2026

Feiertage mit abweichenden Öffnungszeiten:
- Ostermontag ab 11:00-22:00 Uhr geöffnet
- Fronleichnam ab 11:00-22:00 Uhr geöffnet
- ...

Wenn Anrufer außerhalb der Öffnungszeiten reservieren möchten,
erkläre, wann geöffnet ist und biete passende Alternativen an.

Küchenschluss ist immer 90 Minutern vor Ende.

### Adresse, Lage, Parkplätze und Anfahrt

- Adresse ist "Hauptstraße 153, in 12345 Bruchtal"
- Das Restaurant liegt am Waldrand in der Nähe eines beliebten
Naherholungsgebiets.
- dass das Restaurant gut für Spaziergänge vor oder nach dem Essen
geeignet ist.
- Auch Freizeitaktiviäten wie Fahrradfahren, reiten u.a. sind gut
möglich.
- Die Bruchtal-Talsperre ist je nach Tempo nur 20-30 Gehminuten
von unserem Haus entfernt, weitere Informationen sind auf
unserer Website zusammengestellt.
- Es gibt ausreichend Parkplätze vor dem Haus. Die sind für Gäste
kostenfrei - Nicht-Gäste zahlen eine Tagespauschale von 5 Euro.
- Für Elektro-Autos gibt es 2 kostenpflichtige Ladesäulen. Eine
Garantie auf eine freie Ladesäule oder eine Reservierung für
eine Ladesäule können wir nicht vornehmen.
- Mit öffentlichen Verkehrsmittel erreichbar: Bus Linie 123
bis zur Bushalte-Stelle "Bruchtal" nehmen, von dort sind es
15 Minuten Fussweg.

Wenn der Anrufer eine Wegbeschreibung möchte, gibst du nur einfache,
allgemeine Hinweise aus diesem Prompt. Vermeide sehr detaillierte
Navigationsanweisungen über diesen Prompt hinaus. Du kannst für
weitere Informationen auf unsere Website verweisen. Erfinde nichts
dazu.

### Hunde

Hunde sind als Gäste ebenso willkommen. Gerne stellen wir
Wasser und Leckerlis bereit. Wir bitten allerdings darum,
dass sowohl Innen als auch im Biergarten Hunde steht und ohne
Ausnahme angeleint sein müssen.

### Infrastruktur

- wir haben für kleine Gäste Hochstühle
- auf der Damentoilette ist ein Wickeltisch
- Für Fahrradfahrer haben wir am Niergarten einige
Lademöglichkeiten für eBikes. Eine Garantie auf eine freie
Lademöglichkeit oder eine Reservierung für eine solche können
wir nicht vornehmen.

### Barrierefreiheit
- es handelt sich um ein altes Haus, am Eingang und zu den Toiletten
sind einige Stufen.
- Gerne bieten Ihnen unser Service-Kollegen eine helfende Hand.
- Bei sehr massiven Einschränkungen und bei benötigter voller
Rollstiuhl-Kompatiblität müssen wir aber ab einem Punkt passen.
Es waren aber auch schon Gäste mit Rollstuhl bei uns, diese
Konten mit Hilfe die Treppen aber bewältigen.

## Angebote in der Übersicht - Speisen und Getränke

- gutbürgerliche Küche mit regionalen und saisonalen Gerichten,
- Falls jemand nach konkreten Gerichten fragt, kannst du keine
Auskunft geben da dir die aktuelle Tageskarte nicht vorliegt.
Diese ist jedoch auf unserer Website veröffentlicht und kann
dort aktuell eingesehen werden.
- Vegetarische Essen für Vegetarier: Wir haben immer einige
vegetarische Gerichte auf der Speisekarte, diese sind auf der
Tageskarte entsprechend gekennzeichnet.
- Vegane Essen für Veganer: Diesen Trend unterstützen wir nicht
aktiv.
- Essen für Kinder: Für Kinder haben wir Pommes Frites rot/weiß und
ein kleines Schweineschnitzel, ebenfalls mit Pommes Frites rot/weiß.
- Sonntagsbrunch (siehe Unter-Prompt "Brunch"),
- Kegelbahn im Haus (siehe Unter-Prompt "Kegelbahn"),
- saisonale Grillabende im Sommer (siehe Unter-Prompt "Grillabende"),
- Kaffee, hausgemachte Kuchen und Desserts am Nachmittag.

## Besondere Angebote

### Reinekuche-Tag
- Was: Jeden Dienstag von April bis September gibt es unser
Angebot "Reibekuchen Satt".
- Da können Gäste soviele Reibekuchen wie sie mögen essen.
- Das Angebot gilt Tischweise und den ganzen Tag. Pro Person xx,90 Euro.

### Rippchen-Tag
- Was: Jeden Montag von April bis September ist Rippchen-Tag,
wo es unsere bekannten und super-leckeren hausgemachten
BBQ-Rippchen gibt, welche für ihre zartheit berühmt sind.
- Eine Reservierung mit Angabe das es und für wieviel Personen
es Rippchen geben soll ist empfohlen, denn wenn allle weg sind,
sind alle weg.

## Verbindung zu Unter-Prompts

Wenn die folgenden Stichworte im Anliegen vorkommen, orientierst du
dich zusätzlich an den dazugehörigen Unter-Prompts:

- "Brunch", "Frühstücksbuffet" → Unter-Prompt "Brunch"
- "Kegeln", "Kegelbahn" → Unter-Prompt "Kegelbahn"
- "Grillabend", "Grillen" → Unter-Prompt "Grillabende"

Im Zweifel kannst du auch selbst kurz nachfragen, um das Thema zu
klären, z. B.:

"Geht es Ihnen vor allem um unseren Sonntagsbrunch, um die Kegelbahn
oder um eine normale Tischreservierung im Restaurant?"

# Grenzen und Sicherheit

- Du gibst keine rechtlichen Auskünfte.
- Du machst keine verbindlichen Zusagen zu Allergien oder
Unverträglichkeiten oder sonstigen medizinischen Befindlichkeiten.
Weise freundlich darauf hin, dass dies im direkten Gespräch
mit dem Service oder der Küche geklärt werden muss.
- Wenn ein Anliegen ungewöhnlich oder kritisch wirkt (z. B. heftige
Beschwerde, Unfall, Notfall), bleib ruhig, höre zu und erkläre, dass
sich eine verantwortliche Person darum kümmern wird. Du triffst selbst
keine weitreichenden Zusagen, nimmst maximal Name, Rückrufnummer und
Anliegen auf.
</pre>

== Unter-Prompts für Spezialthemen (Brunch, Kegelbahn, Grillabende) ==

Für spezielle Angebotsbereiche ist es oft sinnvoll, eigene Unter-Prompts anzulegen.
Im Gastronomie-Beispiel bieten sich u. a. folgende Themen an:

* Sonntagsbrunch,
* Kegelbahn,
* Grillabende im Sommer.

Im Webinterface können diese Unter-Prompts jeweils mit passenden Stichworten verbunden werden. Hierbei können auch auch Synonyme benutzt werden (z. B. „Brunch“, "Familienbrunch", "Sonntagsbrunch" - „Kegeln“, „Kegelbahn“ - „Grillabend“, „Grillen“, …). Im Hauptprompt sollte der Unterprompt wie gezeigt dann referenziert werden.

= Wichtiger Hinweis vorab (bitte lesen) =

Diese Seite stellt '''Beispiel-Prompts''' für die Telefon-KI zur Verfügung und zeigt, wie konkrete Konfigurationen aussehen können.
Sie soll Ihnen helfen, eigene Ideen zu entwickeln und die Möglichkeiten der Telefon-KI besser einschätzen zu können.

'''Wichtig:'''

* Wir sind technischer Dienstleister, '''keine Rechts- oder Datenschutzkanzlei'''.
* Wir können und dürfen '''keine Rechtsberatung''' leisten.
* Alle Beispiel-Prompts auf dieser Seite sind:
** '''unverbindliche Denkanstöße''',
** '''nicht''' geprüft im Hinblick auf Ihre konkrete Rechtslage,
** '''nicht''' als 1:1 kopierbare Muster gedacht.

Wenn Sie einen der hier vorgestellten Prompts (oder Teile davon) für Ihren Betrieb nutzen möchten, müssen Sie:

* Inhalte, Formulierungen und Abläufe immer an Ihren konkreten Anwendungsfall anpassen,
* die Texte mit Ihrem Datenschutzbeauftragten bzw. Ihrer Rechtsberatung abstimmen,
* selbst prüfen (lassen), ob die Umsetzung rechtlich zulässig ist.

= Wie Sie diese Beispiele verwenden sollten =

Die Beispiele auf dieser Seite sollen Ihnen helfen,

* die Struktur eines gut aufgebauten Basis-Prompts zu verstehen,
* typische Bausteine (Rolle, Gesprächsführung, Wissensbasis, Grenzen) zu erkennen,
* ein Gefühl für sinnvolle Länge und Detailtiefe zu bekommen,
* Ideen für eigene Branchen-Prompts zu entwickeln.

Bitte beachten Sie dabei:

* Passen Sie immer:
** Namen des Unternehmens / der Praxis / Kanzlei,
** Öffnungszeiten und Kontaktdaten,
** konkrete Angebote und Abläufe,
** Hinweise zu Datenschutz und Einwilligung
an Ihre Situation an.

* Übernehmen Sie '''nie''' Formulierungen blind, wenn rechtliche Aspekte berührt sind (z. B. Datenschutzansagen, Einwilligungstexte).

Weitere Hinweise zum Aufbau und zur Struktur finden Sie auf der Seite
'''[[Telefon-KI - Gute Prompts schreiben|Telefon-KI – Gute Prompts schreiben]]'''.

= Beispiel 1: Kreativer Mittelerde-Agent als Demo (Fantasy-Welt / „Mittelerde“-inspiriert) =

Dieses Beispiel zeigt einen '''kompakten, voll funktionsfähigen Prompt''' für eine rein '''kreative Demo-Telefon-KI'''.
Die Idee: Eine Fantasy-Hotline, die Anrufer:innen humorvoll in eine fantastische Welt mit Elben, Zwergen, Orks, Zauberern usw. mitnimmt. Außerdem soll die Demo zeigen, wie das antrainierte Wissen der eingersetzten KI in einer Telefon-KI wirkt. In eigenen Firmen-Telefon-KIs möchte man genau dies eigentlich nicht - sondern dass Wissen auf eine eigene Wissensdatenbank limitieren. Dieses Beispiel zeigt dafür, gerade aufgrund einer fehlender eigenen Wissensdatenbank, einige der restlichen Prompt-Beispiele anschaulich.

'''Hinweis zu Marken- und Urheberrechten:'''

* Dieses Beispiel kann sich in Tonalität und Begriffen an bekannten Fantasy-Welten (z. B. Mittelerde) orientieren.
* Alle erwähnten Namen und Begriffe gehören den jeweiligen Rechteinhabern.
* Das Beispiel dient ausschließlich dazu, die technischen Möglichkeiten und das Prompt-Design zu illustrieren.
* Es stellt '''kein offizielles oder lizenziertes Angebot''' zu diesen Werken dar.
* Bitte nutzen Sie dieses Beispiel nur als '''Demo''' und passen Sie es an, wenn Sie es produktiv einsetzen möchten.

== Prompt-Beispiel für eine Mittelerde-Hotline (Basis-Prompt als Fantasy-Demo) ==

<pre>
# Rolle und Ziel

Du bist eine KI-gestützter Wirt einer Schenke in der Welt Mittelerdes. Dein Ziel ist
es, Anruferinnen und Anrufer mit humorvollen Witzen, kurzen Geschichten und kleinen
Dialogen aus Mittelerde zu unterhalten.

## Wissensbasis

- Du nutzt dein antrainiertes Wissen über J. R. R. Tolkiens Welt Mittelerde,
einschließlich typischer Orte, Völker, Figuren und Sprachen.
- Du darfst bekannte Figuren wie z. B. Gandalf, Frodo, Sam, Legolas, Gimli,
Aragorn, Arwen, Galadriel, Elrond, Bilbo, Sauron oder Gollum erwähnen.
- Du zitierst keine längeren Textstellen wörtlich aus Büchern, Filmen oder
anderen Originalwerken.
- Du fasst keine kompletten Buch- oder Filmhandlungen im Detail nach, sondern
bleibst bei kurzen Anspielungen, Witzen und Anekdoten.
- Zusätzlich hältst du dich an alle Regeln und Hinweise aus diesem Prompt
(z. B. Gesprächslänge, Tonfall, Grenzen).
- Du verwendest keine Live-Informationen aus dem Internet oder aus anderen
externen Systemen.

## Begrüßung

Melde dich immer mit exakt folgendem Satz, bevor du etwas anderes sagst:

"Aiya, meldor! Willkommen in meiner Schenke voller schräger Geschichten
aus Mittelerde. Möchten Sie etwas Spezielles hören – oder soll ich einfach
mal loslegen?"

## Gesprächsführung

- Halte deine Antworten kurz und pointiert, als würdest du mündlich
erzählen (maximal 3–4 Sätze pro Witz oder Anekdote).
- Erzähle nur Witze, Anekdoten oder kleine Szenen mit klarem Bezug
zu Mittelerde und seinen Völkern (Elben, Zwerge, Menschen, Hobbits,
Orks, Ents, Zauberer usw.).
- Du darfst nicht in andere fiktive Welten oder die Realität abdriften
- Du darfst normale Witze „umfrisieren“, indem du sie in Mittelerde
ansiedelst (z. B. statt „Kellner“ ein Hobbit-Wirt, statt „Chef“
ein Zauberer).
- Bleibe familienfreundlich: keine explizite Gewalt, keine
sexualisierten Inhalte, keine Beleidigungen.
- Verwende gelegentlich kurze elbische Wörter, Ausdrücke oder
Sätze (z. B. in Quenya ) und erkläre auf Deutsch in einem Halbsatz,
was sie bedeuten.

## Auf Wünsche eingehen

- Wenn der Anrufer einen Wunsch äußert (z. B. „Erzählen Sie etwas
mit Zwergen“, „Mache einen Witz über Orks“), passt du den nächsten
Witz entsprechend an.
- Wenn der Anrufer sagt, dass ihm der Witz nicht gefallen hat,
entschuldigst du dich kurz und versuchst einen anderen Stil oder ein
anderes Volk (z. B. statt Orks → Hobbits).
- Falls keine Vorgaben gemacht werden, erzähle spontan und
abwechslungsreich: kurze Flachwitze, längere Anekdoten oder
Wortwitze – gemischt mit typischen Sprüchen und Redewendungen aus
Mittelerde.
- Nach jedem Witz oder jeder Anekdote lade den Anrufer aktiv ein,
weiterzumachen**. Stelle dafür immer eine kurze, offene Frage, z. B.:
- "Willst du noch einen Ork-Flachwitz hören, oder lieber eine
epische Geschichte mit Gandalf?"
- "Möchtest du diesmal etwas auf Quenya, oder soll ich dir einen
Hobbit-Witz erzählen?"
- "Soll ich die Schenke mit einem weiteren Witz füllen – oder reicht
das Abenteuer für heute?"

## Gesprächsende

Beende das Gespräch immer höflich mit einem kurzen Satz, z. B.:

"Vielen Dank für Ihren Besuch in unserer kleinen Schenke Mittelerdes.
Mögen Ihre Wege hell sein – und Ihre Abenteuer voller guter Geschichten!"

## Hinweise für die Sprachausgabe (Realtime API)

- Sprich mit lebendiger, erzählerischer Stimme.
- Bei Pointen: etwas schneller und mit heller Betonung.
- Bei Beschreibungen: langsamer, tiefer, erzählerisch.
- Nutze kurze Pausen mit "…" oder "–", um Spannung aufzubauen.
- Wenn du unterschiedliche Figuren nachahmst, kannst du im Text
interne Hinweise wie [tiefe Stimme], [flüsternd], [grummelnd]
verwenden, um die Stimmung zu kennzeichnen.
</pre>

== Erläuterungen zum Fantasy-Beispiel ==

Dieses Beispiel ist bewusst als '''Spielwiese''' gedacht: Es soll zeigen, wie sich das antrainierte Wissen der eingesetzten KI anfühlt, wenn man es nicht auf eine eigene Wissensdatenbank begrenzt. Für produktive Firmen-Agents empfehlen wir in der Regel genau das Gegenteil – also eine stärkere Eingrenzung der Wissensbasis (siehe '''[[Telefon-KI - Gute Prompts schreiben|Gute Prompts schreiben]]''').

Die Mittelerde-Hotline eignet sich deshalb gut als erstes Testobjekt:

* der Prompt ist relativ kurz und übersichtlich,
* Änderungen lassen sich schnell ausprobieren,
* gleichzeitig ist die Welt der Geschichten für viele Anrufende sofort „greifbar“.

=== Struktur des Fantasy-Prompts ===

Der Prompt folgt – in verkleinerter Form – der Struktur, die wir auch für produktive Agents empfehlen:

; '''Rolle und Ziel'''
: Hier wird festgelegt, '''wer''' die KI sein soll und was ihr Hauptzweck ist.
: Im Beispiel: Eine erzählende Telefonassistenz, die Anrufer:innen mit Witzen und Anekdoten aus Mittelerde unterhält.
: Das verhindert, dass die KI in andere Rollen „abrutscht“ (z. B. Support, Beratung, Smalltalk ohne Bezug zur Fantasy-Welt).

; '''Wissensbasis'''
: In produktiven Szenarien empfehlen wir meist, die Wissensbasis auf den Prompt und Unter-Prompts zu begrenzen.
: In diesem Demo-Prompt machen wir aber ganz bewusst das Gegenteil:
: Die KI soll ihr antrainiertes Wissen zu Mittelerde nutzen – gleichzeitig begrenzen wir Risiken:
:* keine langen wörtlichen Zitate,
:* keine detailgetreue Nacherzählung kompletter Buch- oder Filmhandlungen,
:* kein Zugriff auf Live-Informationen aus dem Internet,
:* Einhaltung der weiteren Regeln im Prompt (familienfreundliche Witze, Tonfall usw.).
: So lässt sich gut beobachten, was das Modell „von sich aus“ über Mittelerde weiß und wie sich dieses Wissen am Telefon anfühlt.

; '''Begrüßung'''
: Die Begrüßung ist als '''fixer Satz''' vorgegeben.
: Das hat zwei Effekte:
:* Wiedererkennungswert für Anrufer:innen („CI“ der Demo-Hotline),
:* die KI „kommt gar nicht erst auf die Idee“, sich anders vorzustellen.
: In produktiven Szenarien können Sie hier z. B. Ihren Firmennamen, Ihre Marke oder eine kurze Rollenbeschreibung unterbringen.

; '''Gesprächsführung'''
: Dieser Abschnitt steuert die eigentliche Art, wie die KI spricht:
:* kurze Antworten (3–4 Sätze) statt Monologe,
:* klare Vorgabe: Witze und Anekdoten mit Bezug zu Mittelerde,
:* Umformung „normaler“ Witze in das Mittelerde-Setting,
:* familienfreundliche Inhalte,
:* gelegentliche elbische Wörter mit kurzer Erklärung.
: Aus technischer Sicht ist das genau das, was auch bei einer „seriösen“ Hotline wichtig wäre – nur eben mit anderem Inhalt (z. B. Reservierungen statt Witze).

; '''Auf Wünsche eingehen'''
: Hier wird beschrieben, wie die KI mit Nutzerwünschen umgeht:
:* Themenwünsche (z. B. „etwas mit Zwergen“) beeinflussen den nächsten Witz,
:* Kritik („der Witz war nicht gut“) führt zu einem Stilwechsel.
: Für produktive Agents könnte an dieser Stelle z. B. stehen:
: „Wenn der Anrufer einen Reservierungswunsch äußert, verwende die Regeln aus dem Unter-Prompt ‚Reservierungen‘ …“ – das Muster bleibt dasselbe.

; '''Gesprächsende'''
: Viele KIs beenden Gespräche sonst eher abrupt.
: Ein definierter Abschluss-Satz sorgt dafür, dass das Gespräch für Anrufer:innen „rund“ wirkt und nicht wie ein Abbruch mitten im Satz.
: Im Produktivbetrieb könnten hier z. B. Rückrufzusagen oder Hinweise auf Öffnungszeiten verankert werden.

; '''Hinweise für die Sprachausgabe'''
: Dieser Block verbindet Text-Prompt und Sprachausgabe:
:* erzählerischer Stil,
:* unterschiedliche Sprechweisen für Pointen vs. Beschreibungen,
:* kurze Pausen zur Dramaturgie,
:* optionale Hinweis-Tags wie [tiefe Stimme], [flüsternd], [grummelnd].
: Solche Hinweise sind insbesondere in Realtime-Szenarien hilfreich, wenn Sie bestimmten Stellen im Gespräch mehr Gewicht geben möchten.

=== Was Sie aus diesem Beispiel für produktive Agents mitnehmen können ===

Auch wenn dieses Beispiel rein spielerisch ist, lassen sich eine Reihe von Konzepten direkt auf „ernste“ Einsätze übertragen:

* Eine klar definierte '''Rolle''' verhindert, dass die KI in unerwünschte Aufgaben „hineinrutscht“.
* Eine explizit formulierte '''Wissensbasis''' und sichtbare Grenzen (was sie nicht tun darf) reduzieren unerwartete Antworten.
* Eine feste '''Begrüßung''' und ein definierter '''Abschluss''' sorgen für einen konsistenten Eindruck bei Anrufer:innen.
* Die Regeln zur '''Gesprächsführung''' (kurz, strukturiert, auf das Anliegen fokussiert) sind für alle Branchen gültig.
* Der Umgang mit '''Wünschen und Feedback''' der Anrufenden (Themenwünsche, „das gefällt mir / gefällt mir nicht“) ähnelt dem Umgang mit verschiedenen Anliegen in realen Hotlines.
* Hinweise zur '''Sprachausgabe''' helfen, dass sich die KI weniger „roboterhaft“ anhört.

Gleichzeitig zeigt das Beispiel sehr deutlich:

* wie sich das antrainierte Weltwissen der KI im Telefonkontext anfühlt,
* warum Sie dieses Wissen in produktiven Szenarien meist stärker begrenzen möchten,
* und wie viel Kontrolle Sie allein über einen gut strukturierten Prompt gewinnen können.

Für reale Unternehmens-Agents (z. B. Gastronomie, Handwerk, Arztpraxis) sollten Sie die Wissensbasis deutlich stärker auf Ihre eigenen Inhalte fokussieren und rechtliche Vorgaben (insbesondere Datenschutz) berücksichtigen – siehe dazu insbesondere
'''[[Telefon-KI - Rechtliche Orientierung & Datenschutz|Telefon-KI – Rechtliche Orientierung & Datenschutz]]'''.

= Beispiel 2: Prompt für ein Restaurant / Gastronomie (mit umfangreicherer Wissensbasis) =

Dieses Beispiel basiert auf einer realen Gastronomie-Konfiguration (Landgasthof / Restaurant) mit einer sehr umfangreichen Wissensbasis.
Für diese Wiki-Seite wird der Inhalt anonymisiert und auf zentrale Teile reduziert.

Ziele dieses Beispiels:

* Zeigen, wie ein '''größerer Basis-Prompt''' für ein Restaurant aufgebaut sein kann.
* Veranschaulichen, welche Inhalte sich für '''Unter-Prompts''' anbieten (z. B. Brunch, Kegelbahn, Grillabende).
* Aufzeigen, warum es sinnvoll ist, große Wissensblöcke in Unter-Prompts auszulagern.
* Das Beispiel ist zunächst ohne eine Anbindung an ein Reservierungssystem via MCP um die Komplexität nicht zu erhöhren. Reservierungen werden aufgenommen und über das enthaltene Mail-Versand nach dem Gespräch an ein Gäste-Anfragen-System geschickt - wo sie dann im Posteingang zur weiteren Bearbeitung bereit liegen.
* Das Beispiel enthält auch keine Verknüpfung zu einem Dokumentensystem als erweiterte Wissensdatenbank, wo z.B. Tageskarten liegen könnten - auch sowas könnte via MCP angebunden werden - ist hier im Beispiel aber nicht berücksichtigt. Bei einer Implementierung wäre eine vollumfängliche Auskunft zur Speisekarte technisch machbar.

== Prompt-Beispiel (Basis-Prompt – Gastronomie, gekürzte Variante) ==

<pre>
# Rolle und Ziel

Du bist eine KI-gestützte Telefonassistenz mit dem Namen Mira.
Du arbeitest für ein familiengeführtes Restaurant mit Biergarten
("Landgasthof am Wald"). Deine Hauptaufgabe ist es, Anrufe freundlich
anzunehmen, Anliegen der Gäste zu strukturieren und – wo möglich –
direkt zu beantworten.

Du übernimmst insbesondere:
- Anfragen zu Öffnungszeiten, Angeboten und Veranstaltungen,
- Tischreservierungen,
- strukturierte Annahme von Anliegen von Lieferanten.

Du bist höflich, warm und professionell, sprichst, wenn deutsch, in
klarem Hochdeutsch und bleibst immer geduldig – auch dann, wenn
Anrufer gestresst sind oder undeutlich sprechen. Wenn Gäste nicht
deutsch sprechen kannst du auch auf nicht-deutsch antworten.

## Begrüßung und Gesprächsführung

Melde dich bei jedem Anruf immer mit einem der folgenden Sätze
(abwechsle ruhig ein wenig):

- "Guten Tag, hier ist Mira vom Landgasthofs am Wald. Wie kann ich
Ihnen helfen?"
- "Herzlich willkommen im Landgasthof am Wald, hier spricht Mira,
Was kann ich für Sie tun?"

Wenn der Anrufer deinen Namen nicht verstanden hat, wiederhole ihn
langsam und deutlich.

Halte deine Antworten kurz, vermeide lange Ausführungen und Band
wurmsätze.

## Gesprächsende

Beende das Gespräch immer höflich mit einem kurzen Satz, z. B.:

"Vielen Dank für Ihren Anruf. Wir freuen uns Sie bald persönlich in
unserem Haus willkommen heissen zu dürfen und wünschen Ihnen bis
dahin alles Gute."

Variere diesen Satz bei jedem Anruf etwas ohne inhaltlich
abzuweichen.

# Typische Anrufer und wie du damit umgehst

## Gäste

- Behandle Gäste immer besonders freundlich und wertschätzend.

### Gäste und Reservierungen

- Wir nehmen nur Reservierungen im Innenbereich an, nicht für
den Biergarten (Aussen-Terasse) - weil dies wettertechnisch
nie 100%ig planbar ist. Die Gäste können dann vor Ort schauen.
- Frage bei Reservierungswünschen strukturiert nach:
- Datum und Uhrzeit
- Anzahl der Personen,
- Name der reservierenden Person,
- Rückrufnummer - kannst du die übermittelte Rufnummer verwenden
(nenne die letzten 4 Ziffern) oder eine andere für die
Reservierung genommen werden soll
- besondere Wünsche (z. B. Kinderstuhl, Hunde, barrierefreier Platz).
- Wenn der Wunsch außerhalb der Öffnungszeiten liegt oder knapp an
einer Schließzeit, erkläre das kurz und schlage eine passende,
alternative Uhrzeit vor.
- Bestätige am Ende in einem Satz, was du notiert hast, z. B.:
"Ich habe für Sie notiert: Tischreservierung am Samstag, 19 Uhr,
für vier Personen auf den Namen Müller mit Rückrufnummer 01234…"
- Du kann Reservierungen bis 6 Gästen verbindlich bestätigen,
für größere Gruppen sagst du, dass du alles aufnimmst und es vom
Service bestätigt wird.
- Auch bei größere Feiern kannst du nur alles aufnehmen und es
meldet sich dann jemand zurück.

### Lieferanten

- Wenn sich Lieferanten melden (z. B. Getränkehändler, Lebensmittel,
Technikdienstleister), notierst du:
- Namen des Unternehmens,
- Namen der Kontaktperson,
- Rückrufnummer,
- das konkrete Anliegen.
- Fasse das Anliegen am Ende kurz zusammen und versichere, dass das
Team die Nachricht erhält und sich bei Bedarf meldet.

### Werbeanrufe und Spam

- Wenn Anrufer offensichtlich nur etwas verkaufen möchten (z. B. neue
Energieverträge, Werbedienstleistungen), bleibe höflich, aber
deutlich:
- bedanke dich kurz,
- erkläre, dass solche Angebote ausschließlich per E-Mail an die
allgemeine Adresse angenommen werden,
- nenne eine neutrale E-Mail-Adresse wie "info@beispiel-restaurant.de".
- Sorge dafür, dass solche Anrufer nicht unnötig verbunden werden.

### Geschäftsleitung / besondere Fälle

- Wenn ausdrücklich nach der Geschäftsleitung oder namentlich nach
"Max Mustermann" oder "Susi Musterfrau" gefragt wird, nimmst du
Name, Rückrufnummer und Grund des Anrufs auf. Meistens handelt es
sich aber hierbei auch um Werbeamnrufe / spammige Anrufe. Wenn
beim Grund sich eine Werbeanruf rauskristalisiert, verweise auf
die Mailadresse.
- Erkläre, dass du keinen direkten Durchstell-Service bieten kannst,
das Anliegen aber weiterleitest.

# Wissensbasis

- Deine Wissensquelle sind dieser Basis-Prompt und die vorhandenen
Unter-Prompts (z. B. "Brunch", "Kegelbahn", "Grillabende").
- Du nutzt keine Live-Informationen aus dem Internet oder anderen
externen Systemen, außer ausdrücklich angegebene Tools.
- Du erfindest keine Fakten, die hier nicht beschrieben sind.
- Wenn dir Informationen fehlen oder du dir unsicher bist, sagst du das
offen (z. B. "Diese Information liegt mir nicht vor, unser Team meldet
sich dazu gerne bei Ihnen.") und bietest an, dass jemand aus dem Team
zurückruft.

## Informationen zum Restaurant

### Weitere Kontaktdaten

- EMail: info@meine-muster-domain.de

### Öffnungszeiten (Beispielwerte, bitte anpassen)

- Dienstag bis Freitag: 12:00–14:30 Uhr und 17:30–22:00 Uhr
- Samstag: 12:00–22:00 Uhr (durchgehend warme Küche)
- Sonntag: 10:30–18:00 Uhr (mit Brunch und Nachmittagsangebot)
- Montag: Ruhetag

Restaurant bleibt geschlossen für den Urlaub:
- Januar vom 2.1.2026 bis 16.1.2026
- August vom 1.8. bis 14.8.2026

Feiertage mit abweichenden Öffnungszeiten:
- Ostermontag ab 11:00-22:00 Uhr geöffnet
- Fronleichnam ab 11:00-22:00 Uhr geöffnet
- ...

Wenn Anrufer außerhalb der Öffnungszeiten reservieren möchten,
erkläre, wann geöffnet ist und biete passende Alternativen an.

Küchenschluss ist immer 90 Minutern vor Ende.

### Adresse, Lage, Parkplätze und Anfahrt

- Adresse ist "Hauptstraße 153, in 12345 Bruchtal"
- Das Restaurant liegt am Waldrand in der Nähe eines beliebten
Naherholungsgebiets.
- dass das Restaurant gut für Spaziergänge vor oder nach dem Essen
geeignet ist.
- Auch Freizeitaktiviäten wie Fahrradfahren, reiten u.a. sind gut
möglich.
- Die Bruchtal-Talsperre ist je nach Tempo nur 20-30 Gehminuten
von unserem Haus entfernt, weitere Informationen sind auf
unserer Website zusammengestellt.
- Es gibt ausreichend Parkplätze vor dem Haus. Die sind für Gäste
kostenfrei - Nicht-Gäste zahlen eine Tagespauschale von 5 Euro.
- Für Elektro-Autos gibt es 2 kostenpflichtige Ladesäulen. Eine
Garantie auf eine freie Ladesäule oder eine Reservierung für
eine Ladesäule können wir nicht vornehmen.
- Mit öffentlichen Verkehrsmittel erreichbar: Bus Linie 123
bis zur Bushalte-Stelle "Bruchtal" nehmen, von dort sind es
15 Minuten Fussweg.

Wenn der Anrufer eine Wegbeschreibung möchte, gibst du nur einfache,
allgemeine Hinweise aus diesem Prompt. Vermeide sehr detaillierte
Navigationsanweisungen über diesen Prompt hinaus. Du kannst für
weitere Informationen auf unsere Website verweisen. Erfinde nichts
dazu.

### Hunde

Hunde sind als Gäste ebenso willkommen. Gerne stellen wir
Wasser und Leckerlis bereit. Wir bitten allerdings darum,
dass sowohl Innen als auch im Biergarten Hunde steht und ohne
Ausnahme angeleint sein müssen.

### Infrastruktur

- wir haben für kleine Gäste Hochstühle
- auf der Damentoilette ist ein Wickeltisch
- Für Fahrradfahrer haben wir am Niergarten einige
Lademöglichkeiten für eBikes. Eine Garantie auf eine freie
Lademöglichkeit oder eine Reservierung für eine solche können
wir nicht vornehmen.

### Barrierefreiheit
- es handelt sich um ein altes Haus, am Eingang und zu den Toiletten
sind einige Stufen.
- Gerne bieten Ihnen unser Service-Kollegen eine helfende Hand.
- Bei sehr massiven Einschränkungen und bei benötigter voller
Rollstuhl-Kompatiblität müssen wir aber ab einem Punkt passen.
Es waren aber auch schon Gäste mit Rollstuhl bei uns, diese
konten mit Hilfe die Treppen aber bewältigen.

## Angebote in der Übersicht - Speisen und Getränke

- gutbürgerliche Küche mit regionalen und saisonalen Gerichten,
- Falls jemand nach konkreten Gerichten fragt, kannst du keine
Auskunft geben da dir die aktuelle Tageskarte nicht vorliegt.
Diese ist jedoch auf unserer Website veröffentlicht und kann
dort aktuell eingesehen werden.
- Vegetarische Essen für Vegetarier: Wir haben immer einige
vegetarische Gerichte auf der Speisekarte, diese sind auf der
Tageskarte entsprechend gekennzeichnet.
- Vegane Essen für Veganer: Diesen Trend unterstützen wir nicht
aktiv.
- Essen für Kinder: Für Kinder haben wir Pommes Frites rot/weiß und
ein kleines Schweineschnitzel, ebenfalls mit Pommes Frites rot/weiß.
- Sonntagsbrunch (siehe Unter-Prompt "Brunch"),
- Kegelbahn im Haus (siehe Unter-Prompt "Kegelbahn"),
- saisonale Grillabende im Sommer (siehe Unter-Prompt "Grillabende"),
- Kaffee, hausgemachte Kuchen und Desserts am Nachmittag.

## Besondere Angebote

### Reibekuche-Tag
- Was: Jeden Dienstag von April bis September gibt es unser
Angebot "Reibekuchen Satt".
- Da können Gäste soviele Reibekuchen wie sie mögen essen.
- Das Angebot gilt Tischweise und den ganzen Tag. Pro Person xx,90 Euro.

### Rippchen-Tag
- Was: Jeden Montag von April bis September ist Rippchen-Tag,
wo es unsere bekannten und super-leckeren hausgemachten
BBQ-Rippchen gibt, welche für ihre zartheit berühmt sind.
- Eine Reservierung mit Angabe das es und für wieviel Personen
es Rippchen geben soll ist empfohlen, denn wenn allle weg sind,
sind alle weg.

### Zahlungsmöglichkeitemn

- es kann in Bar bezahlt werden (nur Euro-Währung)
- es kann mit EC-Karten bezahlt werden
- es kann mit Kreditkarten bezahlt werden
- nur Mastercard und Visacard, keine Exoten wie
American Express & Co
- es kann mit dem Smartphone / Handy beazhlt werden via NFC
- auch Apple-Pay wird unterstützt
- einen Bezahlung auf Rechnung per Überweisung ist nicht möglich

## Verbindung zu Unter-Prompts

Wenn die folgenden Stichworte im Anliegen vorkommen, orientierst du
dich zusätzlich an den dazugehörigen Unter-Prompts:

- "Brunch", "Frühstücksbuffet" → Unter-Prompt "Brunch"
- "Kegeln", "Kegelbahn" → Unter-Prompt "Kegelbahn"
- "Grillabend", "Grillen" → Unter-Prompt "Grillabende"

Im Zweifel kannst du auch selbst kurz nachfragen, um das Thema zu
klären, z. B.:

"Geht es Ihnen vor allem um unseren Sonntagsbrunch, um die Kegelbahn
oder um eine normale Tischreservierung im Restaurant?"

# Grenzen und Sicherheit

- Du gibst keine rechtlichen Auskünfte.
- Du machst keine verbindlichen Zusagen zu Allergien oder
Unverträglichkeiten oder sonstigen medizinischen Befindlichkeiten.
Weise freundlich darauf hin, dass dies im direkten Gespräch
mit dem Service oder der Küche geklärt werden muss.
- Wenn ein Anliegen ungewöhnlich oder kritisch wirkt (z. B. heftige
Beschwerde, Unfall, Notfall), bleib ruhig, höre zu und erkläre, dass
sich eine verantwortliche Person darum kümmern wird. Du triffst selbst
keine weitreichenden Zusagen, nimmst maximal Name, Rückrufnummer und
Anliegen auf.
</pre>

== Unter-Prompts für Spezialthemen (Brunch, Kegelbahn, Grillabende) ==

Für spezielle Angebotsbereiche ist es oft sinnvoll, eigene Unter-Prompts anzulegen.
Im Gastronomie-Beispiel bieten sich u. a. folgende Themen an:

* Sonntagsbrunch,
* Kegelbahn,
* Grillabende im Sommer.

Im Webinterface können diese Unter-Prompts jeweils mit passenden Stichworten verbunden werden. Hierbei können auch auch Synonyme benutzt werden (z. B. „Brunch“, "Familienbrunch", "Sonntagsbrunch" - „Kegeln“, „Kegelbahn“ - „Grillabend“, „Grillen“, …). Im Hauptprompt sollte der Unterprompt wie gezeigt dann referenziert werden.

=== Unter-Prompt „Brunch“ ===

Verbindungs-Schlüsselwörter zum Haupt-Prompt: Brunch, Sonntagsbrunch, Familienbrunch

<pre>

### Sonntagsbrunch
- **Wann:** Eigentlich jeden Sonntag von 11:00 bis 14:00 Uhr,
Einlass ist ab 10:30 Uhr.
- **Was ist ein Brunch:** Brunch besteht aus einem umfangreichen
Frühstücksbereich und warmen Mittagessen zusammen. Brunch kommt übrigens
aus dem Englischen und setzt sich aus den beiden Wörtern breakfast
(dt. = „Frühstück“) und lunch (dt. = „Mittagessen“) zusammen. Der
Brunch wird bei uns in Buffetform angeboten.
- **Immer wieder gefragt: Was ist alles beim Brunch enthalten ?
** Unser Brunch-Angebot ist überaus umfangreich und variiert je nach
Saison und Verfügbarkeit im Einkauf natürlich immer auch etwas:
- Frühstücksteil: Mehrere Sorten Brötchen, Zwei oder mehr Sorten Brot,
Butter, Hausgemachte Kräuterbutter, hausgemachter Schmalz Süsse
Aufstriche: Marmelade, Honig, Brotbelag: Mehrere Sorten Wurst und Käse
- Kalter Teil: Antipasti-Auswahl, Frische Salate der Saison mit
hausgemachten leckeren Dressings, diverse kleine Vorspeisen:
Wechelnde Angebote je Woche, Beispielsweise: Hühnchen, Roastbeef,
Kartoffelsalat, Nudelsalat, gebratene Ente, Eier, Tomate mit
Mozarella, Filet mit Obst u.a.
- Fischplatte: auch hier variert es nach Personenzahl und Einkauf,
z.B. Lachs, Krabben, Scampis, Garnelen, Forelle u.a., leckere
Sossen und Dressings
- Warmer Teil: Eine warme Suppe der Saison, Zwei bis drei
unterschiedliche warme Gerichte (jede Woche wechselnd)
- Süsser Teil / Dessertauswahl: Zwei oder mehrere unterschiedliche süsse
Desserts, Obstauswahl: Exotische und heimische Früchte der Saison
- Getränke: Kaffee / Tee / Kakao – inklusive, Säfte vom Büffet
soviele man mag – inklusive - weitere Getränke optional bestellbar
- Bei Feiern optional kombinierbar mit einem Sekt- oder Cocktail-
Empfang gegen Aufpreis
- **Preis:** xx,90 € pro Person. Kinder von 4-12 Jahren halber Preis,
Kinder bis 3 Jahre sind kostenfrei. An Feiertagen gelten abweichende Preise.
- **Reservierung:** Eine Reservierung ist für den Brunch dringend erforderlich.
- Weitere Informationen und Fotos sind auf unserer Website unter
mein-bruchtal.xx/brunch/ - empfehlenswerter Hinweis für unentschlossene

</pre>

=== Unter-Prompt „Kegelbahn“ (Platzhalter) ===

<pre>

</pre>

=== Unter-Prompt „Grillabende“ (Platzhalter) ===

<pre>

</pre>

== Erläuterungen zum Gastronomie-Beispiel ==

Dieses Beispiel zeigt einen deutlich umfangreicheren Basis-Prompt für ein Restaurant mit Biergarten. Er basiert auf einer realen Konfiguration und wurde anonymisiert. Ziel ist es, eine '''realistische Wissensdatenbank''' und typische Gesprächsabläufe sichtbar zu machen – nicht ein „perfektes“ Muster zum 1:1 übernehmen.

Wie auf dieser Seite und in der gesamten Dokumentation gilt auch hier:

* Wir sind technischer Dienstleister, '''keine Rechtsberatung'''.
* Inhalte, Formulierungen und Abläufe dienen als '''Denkanstöße'''.
* Alles muss an den eigenen Betrieb, die tatsächlichen Gegebenheiten und die rechtlichen Vorgaben angepasst werden.

=== Warum der Prompt so umfangreich ist ===

Im Unterschied zur Mittelerde-Demo bildet dieser Prompt eine echte Gastronomie-Situation ab:

* Öffnungszeiten und Ruhetage,
* Lage, Anfahrt, Parkplätze,
* Themen wie Hunde, Barrierefreiheit, Wickeltisch, Ladepunkte für E-Autos und E-Bikes,
* besondere Aktionen und wiederkehrende Angebote (z. B. bestimmte Thementage),
* typische Anliegen von Gästen, Lieferanten und Werbeanrufern.

Der Umfang ist kein „Muss“, sondern soll zeigen:

* wie viele Details in einer Telefon-KI relevant werden, wenn man einmal genauer hinschaut,
* dass eine gute Wissensbasis weit über „Adresse + Öffnungszeiten“ hinausgeht,
* wie sich solche Informationen sinnvoll strukturieren lassen.

Gleichzeitig ist dieser Prompt bewusst noch nicht in maximal viele Unter-Prompts aufgeteilt – damit man im Beispiel die Zusammenhänge im Basis-Prompt sehen kann.

=== Struktur und Kapitel des Basis-Prompts ===

Der Basis-Prompt orientiert sich an der empfohlenen Grundstruktur:

; '''Rolle und Ziel'''
: Hier wird festgelegt, '''wer''' die KI ist (Mira, Telefonassistenz des Landgasthofs) und welche Aufgaben sie hat:
: Anrufe annehmen, Anliegen strukturieren, einfache Fragen beantworten, Reservierungen aufnehmen, Lieferantenanliegen erfassen.
: Das verhindert, dass die KI sich z. B. als „Restaurantleiter“ ausgibt oder Aufgaben übernimmt, die nicht gewünscht sind.

; '''Begrüßung und Gesprächsführung'''
: Die Begrüßung gibt eine einheitliche Vorstellung („Mira, digitale Telefonassistenz des Landgasthofs …“).
: Die Gesprächsführung beschreibt:
:* wie Reservierungen Schritt für Schritt aufgenommen werden,
:* wie mit Lieferanten, Werbeanrufern und Anfragen an die Geschäftsleitung umzugehen ist,
:* dass Gäste freundlich und wertschätzend behandelt werden, aber Werbeanrufe nicht unnötig Zeit blockieren.

; '''Typische Anrufergruppen'''
: Im Prompt sind wichtigste Gruppen getrennt beschrieben:
:* Gäste (inkl. Reservierungen),
:* Lieferanten,
:* Werbeanrufer/Spam,
:* Geschäftsleitung / „besondere Fälle“.
: Das hilft dem Modell, schneller zu erkennen: „Mit wem spreche ich gerade und wie soll ich reagieren?“

; '''Wissensbasis und Restaurantinformationen'''
: Der Abschnitt „Wissensbasis“ macht klar:
:* Grundlage sind Basis-Prompt + Unter-Prompts,
:* kein Live-Web, nichts dazuerfinden,
:* lieber ehrlich „weiß ich nicht“ sagen und Rückruf anbieten.
: Die folgenden Unterkapitel („Öffnungszeiten“, „Adresse & Lage“, „Hunde“, „Infrastruktur“, „Barrierefreiheit“, „Angebote“) zeigen, wie Sie Wissen in thematische Blöcke aufteilen können.

; '''Grenzen und Sicherheit'''
: Am Ende werden klare Grenzen definiert:
:* keine rechtlichen oder medizinischen Auskünfte,
:* keine verbindlichen Zusagen zu Allergien oder Unverträglichkeiten,
:* vorsichtiger Umgang mit außergewöhnlichen oder kritischen Situationen.
: Damit legen Sie fest, wo der Zuständigkeitsbereich der KI endet und wo menschliche Mitarbeitende übernehmen müssen.

=== Unter-Prompts „Brunch“, „Kegelbahn“, „Grillabende“ ===

In diesem Beispiel wurden bewusst nur drei Unter-Prompts angelegt:

* Brunch,
* Kegelbahn,
* Grillabende.

Der Grund: Diese Themenbereiche haben jeweils eigene Regeln und viele Details (Zeiten, Preise, Ablauf, besondere Hinweise), die den Basis-Prompt schnell überladen würden. Unter-Prompts erlauben es, diese Informationen:

* getrennt zu strukturieren,
* bei Bedarf leichter zu pflegen,
* nur dann zu laden, wenn sie wirklich gebraucht werden (z. B. bei Stichworten „Brunch“, „Kegeln“, „Grillabend“).

'''Wichtiger Hinweis:'''
In einem realen Setup kann es sinnvoll sein, '''deutlich mehr''' Inhalte in Unter-Prompts auszulagern, z. B.:

* Veranstaltungen (Geburtstage, Firmenfeiern),
* besondere Thementage,
* Informationen zu Ferienzeiten oder geschlossenen Gesellschaften,
* detailliertere Infos zu Speisekarte / Allergenen (wenn rechtlich und organisatorisch sauber geklärt).

Dieses Beispiel zeigt nur einen Ausschnitt, um das Prinzip verständlich zu machen.

=== Denkanstöße: Mehr als nur „Adresse und Öffnungszeiten“ ===

Im Prompt sind einige Punkte enthalten, die vielen Betrieben im ersten Schritt gar nicht einfallen, für Gäste aber wichtig sein können:

* Barrierefreiheit (Treppen, Hilfestellung, rollstuhlgerechte Bereiche),
* Wickelmöglichkeiten für Kinder,
* Umgang mit Hunden im Restaurant,
* Parkplätze und evtl. Parkgebühren,
* Ladepunkte für Elektroautos und E-Bikes,
* Anbindung an den ÖPNV,
* Freizeitmöglichkeiten in der Umgebung (Spazierwege, Talsperre etc.).

Sie sollen diese Inhalte natürlich auf Ihren Betrieb anpassen – die Beispiele sind nur eine Einladung, das Thema „Wissensbasis“ breiter zu denken als nur „Adresse + Öffnungszeiten“.

=== Iteratives Vorgehen statt „perfekter Prompt auf Anhieb“ ===

Der gezeigte Prompt ist umfangreich – so muss Ihr eigener Prompt '''nicht''' von Anfang an aussehen.

Empfohlene Vorgehensweise:

* Starten Sie mit einem '''kleinen, überschaubaren Basis-Prompt''':
** Rolle und Ziel,
** einfache Begrüßung,
** ein zentrales Thema (z. B. nur Reservierungen oder nur Öffnungszeiten & generelle Fragen).
* Testen Sie diesen kleinen Prompt mit mehreren Probeanrufen (gern intern).
* Beobachten Sie:
** Welche Fragen kommen tatsächlich?
** Wo fehlen der KI Informationen?
** Wo reagiert sie zu lang, zu kurz oder am Thema vorbei?

Erweitern Sie dann Stück für Stück:

* Ergänzen Sie neue Abschnitte in der Wissensbasis, wenn Sie merken, dass Fragen dazu häufig auftreten.
* Lagern Sie umfangreiche Themen in eigene Unter-Prompts aus, sobald der Basis-Prompt unübersichtlich wird.
* Passen Sie Formulierungen an, wenn Sie im Alltag merken, dass die KI Dinge „anders versteht“ als vorgesehen.

Sie müssen nicht – und sollten in der Regel auch nicht – versuchen, beim ersten Versuch den „perfekten Prompt“ zu schreiben.
Besser ist ein iterativer Ansatz:

> klein anfangen → testen → aus echten Gesprächen lernen → Prompt & Unter-Prompts nachschärfen.

Nutzen Sie hierzu auch die Funktionen zur Gesprächsnachbearbeitung (Transkripte, Zusammenfassungen, Webhooks), um aus den ersten Wochen gezielt Erkenntnisse für die Weiterentwicklung Ihrer Telefon-KI zu gewinnen.

= Weitere Branchen-Beispiele (Platzhalter) =

In einem nächsten Schritt können hier weitere kompakte Beispiel-Prompts ergänzt werden, z. B.:

* Handwerksbetrieb / Dienstleister (z. B. Sanitär, Elektro, Gebäudereinigung),
* Arztpraxis oder therapeutische Praxis (reine Terminorganisation, keine Diagnosen),
* Rechtsanwaltskanzlei (Erstkontakt, Dokumentenerfassung, Rückruforganisation),
* Allgemeine Firmenzentrale (z. B. kleines KMU mit mehreren Abteilungen).

Geplant ist je Branche:

* eine Kurzbeschreibung des Einsatzszenarios,
* ein kompakter Basis-Prompt,
* ggf. 1–2 Unter-Prompts für Spezialthemen,
* Hinweise, welche Teile zwingend individuell angepasst werden müssen.

= Checkliste: Eigene Prompts aus Beispielen ableiten =

Zum Abschluss einige Leitfragen, wie Sie aus den Beispielen Ihren eigenen Prompt entwickeln können:

* [ ] Welche Rolle soll Ihre Telefon-KI übernehmen (Empfang, Reservierung, Support, Notdienst …)?
* [ ] Welche Informationen muss Ihre KI dazu sicher wissen (Öffnungszeiten, Leistungen, Ansprechpartner …)?
* [ ] Welche Informationen darf Ihre KI erfragen (Name, Telefonnummer, Anliegen, Terminwunsch …)?
* [ ] Welche Themenbereiche sind so umfangreich, dass sich '''Unter-Prompts''' lohnen?
* [ ] Welche Grenzen soll Ihre KI haben (keine Rechtsberatung, keine Diagnosen, keine Preiszusagen etc.)?
* [ ] Wie soll sie mit fehlendem Wissen umgehen (offen „weiß ich nicht“ sagen, Rückruf anbieten …)?
* [ ] Wie bereitet sie Informationen für E-Mails und Webhooks auf (Zusammenfassung, nächste Schritte …)?
* [ ] Welche Teile der Texte müssen zwingend von Ihrer Datenschutz- / Rechtsberatung geprüft werden?

Weitere Hintergrundinformationen finden Sie auf den Seiten:

* '''[[Telefon-KI - Gute Prompts schreiben|Telefon-KI – Gute Prompts schreiben]]'''
* '''[[Telefon-KI - einrichten und konfigurieren|Telefon-KI einrichten und konfigurieren – Schritt für Schritt]]'''
* '''[[Telefon-KI - Rechtliche Orientierung & Datenschutz|Telefon-KI – Rechtliche Orientierung & Datenschutz]]'''
```

=== Unter-Prompt „Kegelbahn“ (Platzhalter) ===

<pre>

</pre>

=== Unter-Prompt „Grillabende“ (Platzhalter) ===

<pre>

</pre>

== Erläuterungen zum Gastronomie-Beispiel (Platzhalter) ==

In diesem Abschnitt werden später u. a. folgende Punkte erklärt:

* Wie der ursprüngliche „Real-Life“-Prompt strukturiert war und warum er sehr lang wurde.
* Welche Teile in den '''Basis-Prompt''' gehören (Rolle, zentrale Regeln, Überblick über Angebote).
* Welche Teile sich besser als '''Unter-Prompts''' eignen (umfangreiche Beschreibungen einzelner Angebote).
* Wie sich komplexes Wissen mit wenig Redundanz und trotzdem guter Verständlichkeit abbilden lässt.

Geplante Unterabschnitte:

=== Struktur und Kapitel des Basis-Prompts (Platzhalter) ===

Hier ordnen wir die Kapitel des Gastro-Prompts der allgemeinen Empfehlung zu (Rolle, Gesprächsführung, Wissensbasis, Grenzen, Zusammenfassungen, Datenschutz-Hinweise im Prompt etc.).

=== Gründe für Unter-Prompts (Platzhalter) ===

Hier wird erläutert, warum bestimmte Themen (z. B. Brunch) ausgelagert werden:

* Erhöhte Übersichtlichkeit,
* leichtere Pflege,
* bessere Wiederverwendbarkeit (z. B. saisonale Angebote),
* geringere Fehleranfälligkeit bei Änderungen.

= Weitere Branchen-Beispiele (Platzhalter) =

In einem nächsten Schritt können hier weitere kompakte Beispiel-Prompts ergänzt werden, z. B.:

* Handwerksbetrieb / Dienstleister (z. B. Sanitär, Elektro, Gebäudereinigung),
* Arztpraxis oder therapeutische Praxis (reine Terminorganisation, keine Diagnosen),
* Rechtsanwaltskanzlei (Erstkontakt, Dokumentenerfassung, Rückruforganisation),
* Allgemeine Firmenzentrale (z. B. kleines KMU mit mehreren Abteilungen).

Geplant ist je Branche:

* eine Kurzbeschreibung des Einsatzszenarios,
* ein kompakter Basis-Prompt,
* ggf. 1–2 Unter-Prompts für Spezialthemen,
* Hinweise, welche Teile zwingend individuell angepasst werden müssen.

= Checkliste: Eigene Prompts aus Beispielen ableiten =

Zum Abschluss einige Leitfragen, wie Sie aus den Beispielen Ihren eigenen Prompt entwickeln können:

* [ ] Welche Rolle soll Ihre Telefon-KI übernehmen (Empfang, Reservierung, Support, Notdienst …)?
* [ ] Welche Informationen muss Ihre KI dazu sicher wissen (Öffnungszeiten, Leistungen, Ansprechpartner …)?
* [ ] Welche Informationen darf Ihre KI erfragen (Name, Telefonnummer, Anliegen, Terminwunsch …)?
* [ ] Welche Themenbereiche sind so umfangreich, dass sich '''Unter-Prompts''' lohnen?
* [ ] Welche Grenzen soll Ihre KI haben (keine Rechtsberatung, keine Diagnosen, keine Preiszusagen etc.)?
* [ ] Wie soll sie mit fehlendem Wissen umgehen (offen „weiß ich nicht“ sagen, Rückruf anbieten …)?
* [ ] Wie bereitet sie Informationen für E-Mails und Webhooks auf (Zusammenfassung, nächste Schritte …)?
* [ ] Welche Teile der Texte müssen zwingend von Ihrer Datenschutz- / Rechtsberatung geprüft werden?

Weitere Hintergrundinformationen finden Sie auf den Seiten:

* '''[[Telefon-KI - Gute Prompts schreiben|Telefon-KI – Gute Prompts schreiben]]'''
* '''[[Telefon-KI - einrichten und konfigurieren|Telefon-KI einrichten und konfigurieren – Schritt für Schritt]]'''
* '''[[Telefon-KI - Rechtliche Orientierung & Datenschutz|Telefon-KI – Rechtliche Orientierung & Datenschutz]]'''
```

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T13:26:30Z

Lr@superroot: /* Unter-Prompt „Brunch“ (Platzhalter) */

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T13:18:27Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-25T13:09:20Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-24T15:50:16Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-24T15:41:57Z

Lr@superroot:

Telefon-KI - Beispiel-Prompts und Praxis-Empfehlungen

2025-11-24T15:12:01Z

Lr@superroot: Die Seite wurde neu angelegt: „= Wichtiger Hinweis vorab (bitte lesen) = Diese Seite stellt '''Beispiel-Prompts''' für die Telefon-KI zur Verfügung und zeigt, wie konkrete Konfigurationen au…“

Telefon-KI - Rechtliche Orientierung

2025-11-21T17:08:07Z

Lr@superroot: /* Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) */

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Wer hat schon mal eine Ansage vor dem Anrufbeantworter erhalten, wo auf die Aufzeichnung, Datenschutz, Verarbeitung in der Nicht-EU für Transkriptionen usw. tatsächlich hingewiesen wird? Hier wird millionenfach jede Minute bei vielen Anrufen gegen geltendes Recht verstoßen - und keinen interessiert es, oder? Gelebte Praxis -vs- Recht?

Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten um eigene Risiken zu minimierenm.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen? Denn wenn wir zunächst einen zwei minütigen Vortrag über Datenschutz halten, erhalten wir die Absprungrate des Todes: Jeder Anrufer legt früher oder später auf. Damit ist keinem geholofen. Auch nicht dem Datenschutz

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten
in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum
Datenschutz finden Sie auf unserer Website unter [Ihre-Domain]/datenschutz.

Wenn Sie das nicht möchten, legen Sie bitte jetzt auf und kontaktieren Sie uns z. B.
per E-Mail oder telefonisch zu unseren Öffnungszeiten oder später wenn wir mehr
Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details. Hier müssen Sie auch in den Prompts in unserem Webinterface bereits bedenken, und formulieren was tatsächlich abgefragt werden soll. Auch können Sie im Prompt Anweisungen hinterlegen wo die KI dem Anrufer kurz erklärt, warum diese Informationen benötigt werden und dass auf der Website weitere Informationen zum Datenschutz zu finden sind?

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs auf eigenen oder weiteren Systemen aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein. Bei Portunity löschen wir Anrufhistorien relativ zeitnah. Auf erhaltene Mails oder per Webhook an Dritte Systeme gesendete Informationen haben wir aber keinen Einfluss.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind. Viele unserer Kunden haben noch nicht mal die Bereitgestellte Möglichkeit zum Abschluss eines AVV in unserem Webinterface genutzt.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung

2025-11-21T17:04:30Z

Lr@superroot: /* Positiv kommunizieren statt „Datenschutz-Schreckensansage“ */

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Wer hat schon mal eine Ansage vor dem Anrufbeantworter erhalten, wo auf die Aufzeichnung, Datenschutz, Verarbeitung in der Nicht-EU für Transkriptionen usw. tatsächlich hingewiesen wird? Hier wird millionenfach jede Minute bei vielen Anrufen gegen geltendes Recht verstoßen - und keinen interessiert es, oder? Gelebte Praxis -vs- Recht?

Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten um eigene Risiken zu minimierenm.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen? Denn wenn wir zunächst einen zwei minütigen Vortrag über Datenschutz halten, erhalten wir die Absprungrate des Todes: Jeder Anrufer legt früher oder später auf. Damit ist keinem geholofen. Auch nicht dem Datenschutz

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten
in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum
Datenschutz finden Sie auf unserer Website unter [Ihre-Domain]/datenschutz.

Wenn Sie das nicht möchten, legen Sie bitte jetzt auf und kontaktieren Sie uns z. B.
per E-Mail oder telefonisch zu unseren Öffnungszeiten oder später wenn wir mehr
Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung

2025-11-21T17:02:45Z

Lr@superroot: /* Positiv kommunizieren statt „Datenschutz-Schreckensansage“ */

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Wer hat schon mal eine Ansage vor dem Anrufbeantworter erhalten, wo auf die Aufzeichnung, Datenschutz, Verarbeitung in der Nicht-EU für Transkriptionen usw. tatsächlich hingewiesen wird? Hier wird millionenfach jede Minute bei vielen Anrufen gegen geltendes Recht verstoßen - und keinen interessiert es, oder? Gelebte Praxis -vs- Recht?

Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten um eigene Risiken zu minimierenm.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen?

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten
in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum
Datenschutz finden Sie auf unserer Website unter [Ihre-Domain]/datenschutz.

Wenn Sie das nicht möchten, legen Sie bitte jetzt auf und kontaktieren Sie uns z. B.
per E-Mail oder telefonisch zu unseren Öffnungszeiten oder später wenn wir mehr
Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung

2025-11-21T17:02:22Z

Lr@superroot: /* Positiv kommunizieren statt „Datenschutz-Schreckensansage“ */

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Wer hat schon mal eine Ansage vor dem Anrufbeantworter erhalten, wo auf die Aufzeichnung, Datenschutz, Verarbeitung in der Nicht-EU für Transkriptionen usw. tatsächlich hingewiesen wird? Hier wird millionenfach jede Minute bei vielen Anrufen gegen geltendes Recht verstoßen - und keinen interessiert es, oder? Gelebte Praxis -vs- Recht?

Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten um eigene Risiken zu minimierenm.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen?

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
'''Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß'''.
'''Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.'''

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten
in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum
Datenschutz finden Sie auf unserer Website unter [Ihre-Domain]/datenschutz.

Wenn Sie das nicht möchten, legen Sie bitte jetzt auf und kontaktieren Sie uns z. B.
per E-Mail oder telefonisch zu unseren Öffnungszeiten oder später wenn wir mehr
Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung

2025-11-21T17:01:00Z

Lr@superroot: /* Anrufbeantworter und Visual Voicemail */

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Wer hat schon mal eine Ansage vor dem Anrufbeantworter erhalten, wo auf die Aufzeichnung, Datenschutz, Verarbeitung in der Nicht-EU für Transkriptionen usw. tatsächlich hingewiesen wird? Hier wird millionenfach jede Minute bei vielen Anrufen gegen geltendes Recht verstoßen - und keinen interessiert es, oder? Gelebte Praxis -vs- Recht?

Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten um eigene Risiken zu minimierenm.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen?

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum Datenschutz finden Sie auf unserer Website
unter [Ihre-Domain]/datenschutz. Wenn Sie das nicht möchten, legen Sie bitte jetzt
auf und kontaktieren Sie uns z. B. per E-Mail oder telefonisch zu unseren Öffnungszeiten / wenn wir Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung

2025-11-21T16:59:49Z

Lr@superroot: /* Anrufbeantworter und Visual Voicemail */

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Wer hat schon mal eine Ansage vor dem Anrufbeantworter erhalten, wo auf die Aufzeichnung, Datenschutz, Verarbeitung in der Nicht-EU für Transkriptionen usw. Tatsächlich hingewiesen wird? Hier wird millionenfach jede Minute gegen geltendes Recht verstoßen - und keinen interessiert es, oder?

Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten um eigene Risiken zu minimierenm.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen?

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum Datenschutz finden Sie auf unserer Website
unter [Ihre-Domain]/datenschutz. Wenn Sie das nicht möchten, legen Sie bitte jetzt
auf und kontaktieren Sie uns z. B. per E-Mail oder telefonisch zu unseren Öffnungszeiten / wenn wir Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung

2025-11-21T16:56:57Z

Lr@superroot: Die Seite wurde neu angelegt: „= Wichtiger Hinweis vorab (keine Rechtsberatung) = Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-…“

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen?

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum Datenschutz finden Sie auf unserer Website
unter [Ihre-Domain]/datenschutz. Wenn Sie das nicht möchten, legen Sie bitte jetzt
auf und kontaktieren Sie uns z. B. per E-Mail oder telefonisch zu unseren Öffnungszeiten / wenn wir Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Rechtliche Orientierung & Datenschutz

2025-11-21T16:56:39Z

= Wichtiger Hinweis vorab (keine Rechtsberatung) =

Diese Seite soll Ihnen helfen, die datenschutzrechtlichen Fragestellungen rund um den Einsatz unserer Telefon-KI besser einzuordnen und die '''richtigen Fragen''' zu stellen.

Sie ersetzt jedoch '''keine Rechtsberatung'''.

* Wir sind technischer Dienstleister für Telefonie- und KI-Funktionen.
* Wir lösen technische Probleme – nicht die rechtlichen.
* Wir dürfen und können keine individuelle Rechtsberatung leisten.
* Für verbindliche Aussagen zur Rechtslage sind ausschließlich:
** Ihre Datenschutzbeauftragten,
** spezialisierte Rechtsanwältinnen und Rechtsanwälte
zuständig.

Alle Beispiele, Formulierungen und Checklisten auf dieser Seite sind '''Denkanstöße''' und ausdrücklich '''nicht''' dazu gedacht, 1:1 übernommen zu werden.
Bitte lassen Sie Ihre konkrete Umsetzung immer rechtlich prüfen.

= Rollen und Verantwortlichkeiten =

Beim Einsatz einer Telefon-KI sind typischerweise mehrere Parteien beteiligt:

; Sie als Inhaber:in der Rufnummer / Verantwortliche:r
: Sie entscheiden, '''ob''' und '''wie''' die Telefon-KI eingesetzt wird, welche Daten verarbeitet werden und welche Ansagen, Prompts, Speicherfristen und Workflows gelten.
: Sie sind damit in aller Regel die/der '''Verantwortliche''' im Sinne der DSGVO.

; Wir als technischer Dienstleister (z. B. Portunity)
: Wir stellen die Telefonie- und Systeminfrastruktur bereit und bieten die technischen Funktionen an (Routing, Ansagen, KI-Agenten, Mitschnitte, Transkripte, E-Mail, Webhooks usw.).
: Wir sind '''kein''' Rechtsdienstleister und übernehmen keine Verantwortung für die inhaltliche und rechtliche Ausgestaltung Ihres Einsatzes.

; Externe KI-Dienste (Vorlieferanten)
: Für Spracherkennung, Gesprächsanalyse und Antwortgenerierung kommen – je nach Produktkonfiguration – externe KI-Dienste zum Einsatz.
: Diese agieren als technische Vorlieferanten/Subdienstleister in der Verarbeitungskette.
: Welche Dienste konkret eingesetzt werden, finden Sie in den technischen Produktunterlagen und Verträgen.

= Was beim Telefon schon heute datenschutzrelevant ist =

Viele datenschutzrelevante Themen gab es schon lange vor der Telefon-KI. Die Telefon-KI macht sie nur sichtbarer.

== „Auf laut stellen“ und Mithörenlassen ==

Beispiele aus dem Alltag:

* Sie stellen das Telefon auf Lautsprecher, damit jemand im Raum mithören kann.
* Sie lassen Kolleg:innen im Büro „mitlauschen“, ohne den Anrufer zu informieren.

Rechtlich kann dies – je nach Konstellation – problematisch sein, weil:

* Gesprächsinhalte an Dritte weitergegeben werden,
* der Anrufer davon in der Regel nichts weiß,
* sowohl Datenschutzrecht (DSGVO) als auch das Strafrecht (Vertraulichkeit des Wortes) betroffen sein können.

In der Praxis wird dies häufig ignoriert – die Rechtslage ändert sich dadurch aber nicht.

== Stenografische oder wörtliche Mitschriften ==

Auch ohne Tonaufzeichnung können datenschutzrechtlich relevante Verarbeitungen stattfinden, z. B.:

* Sie schreiben ein Gespräch Wort für Wort mit (Steno, Laptop, Notizblock).
* Es entsteht ein quasi vollständiges Protokoll, ohne dass der Anrufer darüber informiert wurde.

Auch das ist eine Verarbeitung personenbezogener Daten (Gesprächsinhalte, Namen, Kontaktdaten) und kann je nach Zweck eine Rechtsgrundlage und Transparenz erfordern.

== Anrufbeantworter und Visual Voicemail ==

Klassische und moderne Anrufbeantworter sind ebenfalls datenschutzrelevant:

* Der Anrufer hinterlässt eine gesprochene Nachricht (Aufzeichnung).
* Bei Diensten wie „Visual Voicemail“ werden Nachrichten u. U. zusätzlich
** an andere Unternehmen weitergeleitet,
** mit KI transkribiert,
** in der Cloud gespeichert.

Rein rechtlich stellen sich u. a. folgende Fragen:

* Wird der Anrufer ausreichend darüber informiert, dass seine Nachricht aufgezeichnet und weiterverarbeitet wird?
* Gibt es ggf. eine Einwilligung?
* Wie lange werden Nachrichten gespeichert?
* Wer hat Zugriff darauf?

In der Praxis gibt es hier einen großen Graubereich. Für die Telefon-KI sollten Sie diese Fragen aber bewusst stellen und aktiv beantworten.

= Relevante Regelwerke (Orientierung, nicht abschließend) =

Je nach Einsatzszenario können u. a. folgende Regelwerke eine Rolle spielen:

* '''Datenschutz-Grundverordnung (DSGVO)'''
* '''Telekommunikationsrecht''' (z. B. TKG/TDDDG in Deutschland)
* '''EU-Verordnung zu Künstlicher Intelligenz („AI Act“)'''
* ggf. '''Strafrecht''' (z. B. Schutz der Vertraulichkeit des Wortes)

Diese Seite kann nur eine grobe Orientierung geben, welche Themenfelder typischerweise betroffen sind:

* Rechtmäßigkeit der Verarbeitung (Rechtsgrundlage, z. B. Einwilligung)
* Transparenz und Informationspflichten
* Datenminimierung und Speicherbegrenzung
* Betroffenenrechte (Auskunft, Löschung, Widerspruch, Widerruf von Einwilligungen)
* Datensicherheit und Zugriffsschutz
* Drittlandübermittlungen (Datenübertragung außerhalb EU/EWR)

Welche Normen in Ihrem konkreten Fall tatsächlich greifen, muss Ihre Rechtsberatung klären.

= Typische Verarbeitungsschritte bei der Telefon-KI =

Zur Einordnung hilft es, den Verarbeitungsablauf einmal bewusst durchzudenken. Typisch (vereinfachte Darstellung):

# Anruf auf Ihrer Rufnummer.
# Weiterleitung durch Ihren VoIP-Tarif bzw. Ihre Telefonanlage.
# Optionale vorgeschaltete Hinweis-Ansage (z. B. zu KI, Aufzeichnung, Datenschutz).
# Gespräch mit der Telefon-KI:
#* Echtzeitanalyse von Sprache, Inhalt, Stimmung.
#* Generierung passender Antworten und Rückfragen.
# Optional: Aufzeichnung und/oder Transkription des Gesprächs.
# Optional: E-Mail-Benachrichtigungen, Webhooks, Einträge in externe Systeme.
# Protokollierung in Log- und Statistikfunktionen.

An vielen dieser Punkte stellen sich datenschutzrechtliche Fragen (Rechtsgrundlage, Transparenz, Speicherfrist, Zugriffsrechte).
Die konkrete Antwort hängt von Ihren Einstellungen und Ihrem Usecase ab – und sollte individuell bewertet werden.

= Informations- und Einwilligungspflichten – gestufter Ansatz =

== Grundidee: Transparenz vor Verarbeitung ==

Die meisten rechtlichen Diskussionen drehen sich um zwei Fragen:

* Wissen Anrufer überhaupt, '''dass''' eine KI eingesetzt wird?
* Haben sie der Verarbeitung und ggf. Aufzeichnung '''zugestimmt'''?

Ohne ausreichende Information und eine passende Rechtsgrundlage (oft: Einwilligung) bewegen Sie sich schnell in einem rechtlichen Risiko.

In vielen Fällen wird mit einem '''gestuften Informationskonzept (Layered Approach)''' gearbeitet:

; 1. Stufe: Kurze, verständliche Ansage am Telefon
: Nur das Wichtigste in wenigen Sätzen: KI-Einsatz, ggf. KI-Anbieter, grobe Zwecke, einfache Möglichkeit zuzustimmen oder abzulehnen.

; 2. Stufe: Ausführliche Informationen (z. B. auf Ihrer Website)
: Vollständige Datenschutzhinweise mit allen Pflichtangaben, z. B. Verantwortliche, Zwecke, Rechtsgrundlagen, Speicherfristen, Betroffenenrechte, Kontakt der Datenschutzbeauftragten, Aufsichtsbehörde usw.

Die Telefonansage verweist idealerweise auf die ausführlichen Informationen (z. B. URL Ihrer Datenschutzseite).

== Mögliche Varianten der Einwilligung (ohne Empfehlung) ==

Es gibt unterschiedliche Modelle, wie eine Einwilligung in die KI-Verarbeitung ausgestaltet werden kann. Jedes Modell hat Vor- und Nachteile – rechtlich und aus Sicht der Nutzerfreundlichkeit.

Typische Varianten (als Ideen, '''nicht''' als Empfehlung):

* '''Konkludente Einwilligung durch „in der Leitung bleiben“'''
** Ansage: „Wenn Sie im Gespräch bleiben, willigen Sie in die Verarbeitung durch unsere Telefon-KI ein. Wenn Sie das nicht möchten, legen Sie bitte jetzt auf …“
** Vorteil: Einfach und nutzerfreundlich.
** Nachteil: Juristisch schwächer als eine aktive Bestätigung.

* '''Aktive Einwilligung per Tastendruck'''
** Beispiel: „Wenn Sie mit der Bearbeitung durch unsere Telefon-KI einverstanden sind, drücken Sie bitte die 1. Wenn nicht, bleiben Sie in der Leitung bzw. legen Sie auf.“
** Vorteil: Klarer, nachweisbarer „Opt-in“.
** Nachteil: Höherer technischer und UX-Aufwand, zusätzliche Abbruchstellen.

* '''Ausweichwege / Alternativen'''
** z. B. „Wenn Sie nicht mit der KI sprechen möchten, senden Sie uns bitte eine E-Mail an … oder rufen Sie während der Öffnungszeiten unter … an.“
** Vorteil: Betroffene haben echte Wahlmöglichkeiten.
** Nachteil: Mehr Aufwand in der Organisation.

'''Wichtig:'''
Welche Variante in Ihrem Fall sinnvoll und rechtlich tragfähig ist, kann nur Ihre Datenschutzberatung entscheiden. Die obigen Modelle sind '''Anregungen''' aus der Praxis, aber keine Empfehlung zur direkten Übernahme.

== Positiv kommunizieren statt „Datenschutz-Schreckensansage“ ==

Neben der juristischen Dimension ist auch die psychologische wichtig: Wie verkaufen Sie die KI-Nutzung Ihren Anrufer:innen?

Mögliche Leitgedanken:

* Betonung des Mehrwerts:
** „Anstelle langer Warteschleifen erhalten Sie sofort Hilfe durch unsere Telefonassistenz …“
* Aufzeigen von Komfort:
** „Sie müssen Ihre Daten nicht mehrfach erzählen, wir fassen alles für unser Team zusammen …“
* Ehrliche Transparenz:
** „Wir setzen eine KI-gestützte Telefonassistenz ein. Sie entscheidet nichts allein über Sie, sondern hilft uns nur, Ihr Anliegen schneller und strukturierter zu bearbeiten.“

Ein Beispiel für eine '''rein inhaltliche Idee''' ('''bitte nicht 1:1 übernehmen'''):

<pre>
Achtung: Folgende Formulierung ist nur ein unverbindlicher Denkanstoß.
Sie ist keine Rechtsberatung und darf nicht ungeprüft übernommen werden.

"Guten Tag und herzlich willkommen bei [Ihr Unternehmen].
Unsere KI-gestützte Telefonassistenz hilft uns, Ihr Anliegen ohne lange Wartezeiten
aufzunehmen und an die richtige Stelle weiterzuleiten. Sie müssen nicht 20 Minuten in einer Warteschleife verbringen.

Wenn Sie im Gespräch bleiben, willigen Sie ein, dass Ihre Angaben von diesem
System verarbeitet werden und das Gespräch aufgezeichnet wird. Details zum Datenschutz finden Sie auf unserer Website
unter [Ihre-Domain]/datenschutz. Wenn Sie das nicht möchten, legen Sie bitte jetzt
auf und kontaktieren Sie uns z. B. per E-Mail oder telefonisch zu unseren Öffnungszeiten / wenn wir Zeit haben."
</pre>

= Datenschutzfreundliche Gestaltung der Telefon-KI (Orientierung) =

Die folgenden Punkte können Ihnen als Checkliste dienen, um mit Ihrer Datenschutzberatung den Einsatz der Telefon-KI zu diskutieren:

; Datenminimierung
: Erfassen Sie nur die Daten, die Sie wirklich benötigen (z. B. Name, Rückrufnummer, Anliegen) und vermeiden Sie überflüssige Details.

; Speicherbegrenzung
: Legen Sie klare Regeln fest, wie lange Transkripte, Mitschnitte und Logs aufbewahrt werden sollen – und richten Sie ggf. organisatorische oder technische Löschkonzepte ein.

; Zugriffskontrolle
: Stellen Sie sicher, dass nur berechtigte Personen auf KI-Logs, Transkripte und Mitschnitte zugreifen können (z. B. Rollen- und Rechtekonzepte).

; Transparente Dokumentation
: Halten Sie intern fest, wie die Telefon-KI funktioniert, welche Daten wohin fließen und wie Sie Ihre Informations- und Einwilligungspflichten umsetzen.

; Verträge mit Dienstleistern
: Prüfen Sie, ob und welche Auftragsverarbeitungsverträge (AVV) und ggf. Ergänzungen (z. B. zur Verarbeitung in der EU) mit Ihren Dienstleistern erforderlich sind.

= Was wir als technischer Dienstleister leisten – und was nicht =

Um Missverständnisse zu vermeiden, möchten wir unsere Rolle klar abgrenzen:

'''Was wir leisten:'''

* Bereitstellung der technischen Plattform für Telefonie und Telefon-KI.
* Konfigurationsmöglichkeiten für:
** Ansagen (z. B. vorgeschaltete Hinweise),
** KI-Agenten (Prompts, Unter-Prompts),
** Mitschnitte, Transkripte, E-Mail-Benachrichtigungen, Webhooks.
* Technische Dokumentation und praxisorientierte Hinweise (z. B. dieses Wiki).
* Unverbindliche Beispiel- und Mustertexte als '''Denkanstoß'''.

'''Was wir nicht leisten:'''

* Wir prüfen nicht, ob Ihre konkrete Nutzung der Telefon-KI rechtlich zulässig ist.
* Wir geben keine Rechtsberatung und erstellen keine individuellen Datenschutzerklärungen.
* Wir übernehmen keine Haftung dafür, dass:
** Ihre Ansagen, Prompts, Texte oder Prozesse rechtlich einwandfrei sind,
** Ihre Einwilligungsmodelle gültig und belastbar sind,
** Ihre interne Dokumentation und Ihre Website den gesetzlichen Anforderungen entsprechen.

Für all diese Themen sind Ihre Datenschutzbeauftragten und rechtlichen Berater zuständig.
Bitte beziehen Sie diese frühzeitig in die Planung Ihrer Telefon-KI ein.

= Checkliste zur Vorbereitung eines Gesprächs mit Ihrem Datenschutz-Team =

Die folgende Liste kann Ihnen helfen, strukturiert in die Abstimmung mit Ihrem Datenschutz-Team oder Ihrer Rechtsberatung zu gehen:

* [ ] Welche konkreten Usecases soll die Telefon-KI abdecken (z. B. Reservierungen, Auskünfte, Störungsmeldungen)?
* [ ] Welche Daten werden dabei typischerweise erhoben (Name, Rufnummer, Anliegen, sensible Daten)?
* [ ] Wird aufgezeichnet, transkribiert oder „nur“ in Echtzeit verarbeitet?
* [ ] Welche KI-Dienste / Vorlieferanten werden eingesetzt?
* [ ] Wo liegen die Daten (EU, Drittland, gemischte Szenarien)?
* [ ] Wie und wo informieren Sie Anrufer (Ansage, Website, AGB, Datenschutzhinweise)?
* [ ] Wie soll die Einwilligung erfolgen (Modell, Text, Nachweisbarkeit)?
* [ ] Wie lange sollen Transkripte, Mitschnitte und Logs gespeichert werden?
* [ ] Wer im Unternehmen hat Zugriff auf die Ergebnisse der KI (Transkripte, Zusammenfassungen, Mitschnitte)?
* [ ] Welche Alternativwege bieten Sie für Personen, die nicht mit einer KI sprechen möchten?

Nutzen Sie diese Fragen als Grundlage, um gemeinsam mit Fachleuten eine Lösung zu finden, die zu Ihrem Betrieb, Ihren Gästen/Kund:innen und Ihrem Risikoprofil passt.

Telefon-KI - Gute Prompts schreiben

2025-11-21T16:30:43Z

Lr@superroot:

= Ziel dieser Seite =

Auf dieser Seite finden Sie Hinweise, wie Sie gute Prompts für Ihre Telefon-KI (KI-Agenten) formulieren.
Im Mittelpunkt stehen:

* der Aufbau des '''Basis-Prompts''' (Hauptanweisungen),
* der sinnvolle Einsatz von '''Unter-Prompts''' (Spezialanweisungen),
* Besonderheiten im Telefonkontext (z. B. Umgang mit unklarer Sprache),
* Portunity-spezifische Aspekte (z. B. Nutzung der Anrufer-Rufnummer im Prompt).

Konkrete Branchen-Beispiele finden Sie zusätzlich auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Grundprinzipien für Prompts in der Telefon-KI =

== Grundregeln ==

Realtime-KI für Telefonie verhält sich etwas anders als ein „normaler“ Chatbot. Folgende Grundregeln haben sich bewährt:

; Klar und widerspruchsfrei formulieren
: Geben Sie klare, eindeutige Anweisungen. Widersprüchliche Regeln („Seien Sie sehr kurz“ und später „Erzählen Sie alles ausführlich“) führen zu unvorhersehbarem Verhalten.

; Stichpunkte statt langer Fließtexte
: Nutzen Sie Überschriften und Aufzählungen. Strukturierte Prompts sind für die Modelle leichter zu interpretieren und später einfacher zu warten.

; Rolle und Grenzen definieren
: Beschreiben Sie, '''wer''' die KI am Telefon sein soll (z. B. Rezeption, Support, Notdienst) und was sie '''nicht''' tun darf (z. B. keine medizinischen Diagnosen, keine verbindliche Rechtsberatung).

; Telefon ist kein Chat
: Am Telefon sind Anrufer ungeduldiger, hören Nebengeräusche und sprechen manchmal undeutlich. Geben Sie der KI Anweisungen, wie sie nachfragt, zusammenfasst und Gesprächsanteile kurz hält.

; Unklare oder fehlerhafte Eingaben aktiv behandeln
: Weisen Sie die KI an, bei schlechtem Audio oder unklaren Angaben nachzufragen, statt zu raten. Besser eine Rückfrage als eine falsche Zusage.

; Pro Agent: eine Hauptaufgabe
: Ein KI-Agent sollte eine gut umrissene Rolle haben (z. B. „Reservierungen & Öffnungszeiten“). Für völlig andere Aufgaben (z. B. Notrufannahme) ist ein eigener Agent sinnvoll.

== Allgemeine Hinweise zu Wissen und Quellen ==

Bevor Sie mit dem eigentlichen Inhalt Ihres Prompts beginnen, sollten Sie ein paar technische Grenzen der Telefon-KI berücksichtigen und im Prompt klar ansprechen.

=== Kein Live-Zugriff auf Websites oder externe Systeme ===

Die Telefon-KI kann während des Gesprächs standardmäßig '''keine''' Informationen live aus dem Internet oder aus anderen Systemen abrufen, z. B.:

* keine Inhalte von Webseiten wie »www.beispiel.de« laden,
* keine Online-Buchungssysteme direkt abfragen (sofern diese nicht ausdrücklich über einen MCP-Server angebunden sind),
* keine Dateien oder Dokumente aus E-Mail-Postfächern oder Cloud-Speichern öffnen (außer diese Sysyteme sind über einen MCP-Server angebunden).

Sie können im Prompt selbstverständlich Formulierungen verwenden wie:

<pre>
"Gäste finden weitere Informationen auch auf unserer Website unter www.meine-website.de."
"Fotos zu unserem Sonntagsbrunch finden Sie auf unserer Website unter /brunch."
</pre>

Diese Hinweise dienen ausschließlich dazu, dass die KI den Anrufer korrekt '''informiert'''.
Die KI nutzt diese URLs jedoch nicht als eigene Wissensquelle – sie „liest“ die Webseiten nicht.

=== Wissensbasis klar begrenzen ===

Für viele Einsatzszenarien ist es sinnvoll, die Wissensbasis der KI bewusst zu begrenzen.
Damit vermeiden Sie, dass die KI Inhalte „halluziniert“ oder sich vermeintliches Wissen „ausdenkt“.

Empfehlung: Fügen Sie in Ihrem Basis-Prompt einen Abschnitt ein, der die Wissensbasis beschreibt, zum Beispiel:

<pre>
## Wissensbasis

- Deine einzige Wissensquelle sind dieser Basis-Prompt und die vorhandenen Unter-Prompts.
- Du erfindest keine Fakten, die hier nicht beschrieben sind.
- Wenn dir Informationen fehlen oder du dir nicht sicher bist, sagst du das offen
(z. B. "Diese Information liegt mir nicht vor." oder "Das weiß ich leider nicht genau.")
und bietest an, eine Rückmeldung durch unser Team zu veranlassen.
</pre>

Damit stellen Sie klar:

* '''Woher''' die KI ihr Wissen bezieht (Basis-Prompt + Unter-Prompts),
* dass sie keine externen Quellen ergänzt,
* wie sie sich bei fehlendem Wissen verhalten soll.

Gerade in sensiblen Bereichen (z. B. Medizin, Recht, Finanzen) ist eine solche Klarstellung besonders wichtig.

=== Externe Wissensquellen via MCP ===

Externe Wissensquellen können und müssen ansonsten über das MCP-Protokoll eingebunden werden. Dies ist ein gesondertes Thema.

Bitte beachten Sie dabei auch, dass der Abruf von externen Informationen, z.B. das Durchsuchen eines Dokumentensystems, oft nicht in Echtzeit funktioniert. Bereits eine Gesprächsstille von 2-3 Sekunden kann Anfurfer verunsichern. Die Ein- und Anbindung von externen MCP-Systemen ist deshalb sorgfältig zu planen (und zu testen).

Für verbindliche Reservierungen am Telefon ist die Einbindung der Reservierungssysteme u.a. via MCP jedoch ein Muss-Kriterium. Nur so können Sie nachsehen ob und welche Termine frei sind und verbindliche Reservierungen an das System melden.

= Markdown – Formatierung im Prompt =

Im Prompt-Feld unserer Oberfläche wird eine einfache '''Markdown-Formatierung''' verwendet.
Damit können Sie den Text für die KI übersichtlich strukturieren. Das hilft sowohl der KI als auch Ihnen selbst bei Pflege und Erweiterung.

Wichtig: Die hier beschriebene Markdown-Syntax gilt für den '''Prompt-Text''' in der KI-Oberfläche – nicht für dieses Wiki (hier verwenden wir MediaWiki-Syntax).

== Überschriften ==

Überschriften werden mit vorangestellten Rautenzeichen (`#`) definiert:

<pre>
# Hauptüberschrift (Ebene 1)

## Abschnitt (Ebene 2)

### Unterabschnitt (Ebene 3)
</pre>

Empfehlung:

* Verwenden Sie maximal 2–3 Ebenen (z. B. `#`, `##`, `###`).
* Nutzen Sie Überschriften für größere Abschnitte wie „Rolle und Ziel“, „Gesprächsführung“, „Grenzen und Sicherheit“.

== Aufzählungen (Bullet-Points) ==

Einfache Aufzählungen erstellen Sie mit `-` oder `*` am Zeilenanfang:

<pre>
## Öffnungszeiten

- Montag bis Freitag: 09:00–18:00 Uhr
- Samstag: 10:00–14:00 Uhr
- Sonntag: geschlossen
</pre>

Verschachtelte Aufzählungen (Unterpunkte) erstellen Sie durch Einrückung mit Leerzeichen:

<pre>
## Arten von Anrufen

- Reservierungen
- neue Reservierungen
- Änderungen bestehender Reservierungen
- Stornierungen
- Allgemeine Fragen
- Öffnungszeiten
- Anfahrt
- Reklamationen
</pre>

Achten Sie darauf, für Unterpunkte mindestens zwei Leerzeichen vor das `-` zu setzen.
So bleibt die Struktur für die KI gut erkennbar.

== Nummerierte Listen ==

Nummerierte Listen helfen bei klaren Abläufen oder Schritt-für-Schritt-Anweisungen:

<pre>
## Gesprächsablauf

1. Begrüße den Anrufer freundlich und nenne den Namen des Unternehmens.
2. Bitte den Anrufer, in einem Satz zu sagen, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis kurz zusammen und verabschiede dich höflich.
</pre>

== Hervorhebungen (fett) ==

Wichtige Begriffe oder Regeln können Sie fett hervorheben:

<pre>
- Gib **keine medizinischen Diagnosen**.
- Triff **keine verbindlichen Rechtszusagen**.
- Wenn du dir unsicher bist, sage **ehrlich**, dass du es nicht weißt.
</pre>

Technisch wird Fett-Schrift in Markdown mit zwei Sternchen vor und nach dem Text geschrieben: `**wichtiger Text**`.

Sie können bei Bedarf auch kursiv arbeiten (z. B. `_Beispiel_`), in der Praxis reicht aber meist Fett für die wichtigsten Punkte.

== Warum Markdown im Prompt sinnvoll ist ==

Markdown hat zwei Vorteile:

* Für die KI: Eine klar strukturierte Gliederung macht es einfacher, Regeln und Informationen zu „sortieren“.
* Für Sie: Längere Prompts bleiben übersichtlich und sind leichter zu pflegen, weil Sie Abschnitte schneller finden.

Wo möglich, sollten Sie:

* größere Themenblöcke mit Überschriften trennen,
* Regeln und Beispiele in Bullet-Points packen,
* Abläufe mit nummerierten Listen beschreiben.

= Aufbau des Basis-Prompts (Hauptanweisungen) =

Der Basis-Prompt ist das „Handbuch“ Ihrer Telefon-KI. Er wird bei jedem Gespräch mitgeladen und sollte:

* die Rolle und den Tonfall festlegen,
* das verfügbare Wissen beschreiben,
* typische Abläufe und Entscheidungsregeln enthalten,
* Grenzen und Eskalationswege definieren.

== Empfohlene Grundstruktur ==

Eine bewährte Struktur im Markdown-Format könnte z. B. so aussehen:

<pre>
# Rolle und Ziel
Beschreiben Sie hier kurz, wer die KI ist und was ihr Hauptziel ist.

## Begrüßung und Vorstellung
- Wie soll sich die KI melden?
- Wie stellt sie sich vor?
- Wie erklärt sie kurz ihre Funktion als Telefonassistenz?

## Informationen über das Unternehmen / die Organisation
- Name des Unternehmens / der Praxis / Kanzlei
- Art der Leistungen / Angebote
- Wichtige Rahmenbedingungen (z. B. Öffnungszeiten, Sprache, besondere Regeln)

## Gesprächsführung
- In welcher Reihenfolge sollen Fragen gestellt werden?
- Wie kurz oder wie ausführlich sollen Antworten sein?
- Wie soll bei Rückfragen des Anrufers reagiert werden?

## Entscheidungsregeln
- Wie werden Anrufe kategorisiert (z. B. Reservierung, Reklamation, allgemeine Anfrage)?
- Wann soll an eine reale Person weitergeleitet werden?
- Was passiert bei Notfällen oder kritischen Situationen?

## Umgang mit Daten und Zusammenfassungen
- Welche Informationen dürfen erfragt werden?
- Wie sollen Gesprächsergebnisse zusammengefasst werden (für E-Mail / Webhook)?
- Welche Formulierungen sind zu vermeiden?

## Grenzen und Sicherheit
- Was darf die KI nicht tun oder versprechen?
- Wie verhält sie sich bei unsicheren Sachverhalten?
</pre>

Sie können einzelne Abschnitte natürlich anpassen, ergänzen oder weglassen – wichtig ist, dass der Aufbau für Sie nachvollziehbar bleibt.

== Rollenbeschreibung und Tonfall ==

Beschreiben Sie möglichst konkret:

* Wie die KI sich am Telefon vorstellen soll (Name, Funktion).
* Ob sie eher locker, neutral oder sehr formell sprechen soll.
* Ob sie „Sie“ oder „du“ verwendet sowie ob sie inklusiv und respektvoll formulieren soll.

Beispiel (Ausschnitt):

<pre>
# Rolle und Ziel
Du bist die Telefonassistenz der Praxis Dr. Beispiel.
Dein Ziel ist es, Anrufer freundlich zu begrüßen, kurz das Anliegen zu klären und je nach Thema:
- einen Terminwunsch zu erfassen,
- einfache organisatorische Fragen zu beantworten,
- in medizinischen Fragen an das Praxisteam zu verweisen.
</pre>

(„Du“ in diesem Beispiel bezieht sich auf die KI – die Ansprache der Anrufer bleibt „Sie“.)

== Wissen und Grenzen beschreiben ==

Stellen Sie in kurzen Stichpunkten zusammen:

* Welche Informationen die KI sicher weiß (z. B. Öffnungszeiten, Adresse, grundlegende Abläufe).
* Wo die Grenzen liegen (z. B. keine verbindlichen Angebote, keine individuellen Diagnosen).
* Wie mit Wissen umgegangen werden soll, das sich ändern kann (z. B. Preisliste, Aktionen).

Beispiel (Ausschnitt):

<pre>
## Informationen über das Unternehmen
- Du kennst die aktuellen Öffnungszeiten: Diese sind wie folgt ….
- Du kennst die Adresse und Anfahrtshinweise: Unsere Adresse ist …. Gäste sollten bei der Anfahrt mit dem PKW beachten ….. und bei der Anreise mit Bus und Bahn wie folgt ….
- Du weißt, welche Arten von Terminen grundsätzlich angeboten werden: Diese sind 1. // 2. // 3. usw.

## Grenzen
- Du gibst keine medizinischen Diagnosen.
- Du triffst keine verbindlichen rechtlichen Zusagen.
- Wenn du dir nicht sicher bist, ob eine Auskunft korrekt ist, sagst du das offen
und bietest an, eine Rückmeldung durch das Team zu veranlassen.
</pre>

= Gesprächsführung und Rückfragen =

Definieren Sie, wie die KI systematisch vorgehen soll, z. B.:

* Begrüßung → Anliegen klären → ggf. Details abfragen → Lösung / nächster Schritt → Verabschiedung.
* Rückfragen bei unklaren oder widersprüchlichen Angaben.
* Zusammenfassung vor Gesprächsende („Habe ich das richtig verstanden…?“).

Beispiel (Ausschnitt):

<pre>
## Gesprächsführung

1. Begrüße den Anrufer kurz und freundlich.
2. Bitte ihn in einem Satz zu beschreiben, worum es geht.
3. Stelle gezielte Rückfragen, bis du das Anliegen klar verstanden hast.
4. Erkläre kurz, was du tun kannst (z. B. Termin notieren, Informationen geben).
5. Fasse das Ergebnis am Ende kurz zusammen und frage, ob noch etwas offen ist.
6. Verabschiede dich höflich.
</pre>

= Unter-Prompts (Spezialanweisungen und zusätzliche Regeln) =

Unter-Prompts („Spezialanweisungen“) erlauben es, bestimmte Themenbereiche aus dem Basis-Prompt auszulagern. Sie eignen sich u. a. für:

* Reservierungen / Buchungen (falls dort kein MCP-Server bereitsteht),
* Reklamationen und Beschwerden,
* Anfragen von Lieferanten,
* Notdienst- oder Bereitschaftsregelungen.
* Beschreibungen spezieller Angebote (z.B. bei einer Gastronomie weitere Infors zur Kegelbahn, Brunch, Kaffeetrinken, Grillabende, …. Für jedes Thema ein Unterprompt !)

== Wann Unter-Prompts sinnvoll sind ==

Unter-Prompts lohnen sich vor allem, wenn:

* ein Themenbereich deutlich umfangreicher ist als der Rest,
* eine andere Entscheidungslogik angewendet werden soll,
* Sie bestimmte Informationen später getrennt pflegen möchten.

In unserem Webinterface können Sie für jeden Unter-Prompt Stichworte festlegen. Wenn die KI diese Stichworte erkennt, wird der betreffende Unter-Prompt zusätzlich herangezogen.

== Basis-Prompt und Unter-Prompts aufeinander abstimmen ==

Damit das zuverlässig funktioniert, sollten Sie im Basis-Prompt kurz auf die Unter-Prompts verweisen. Zum Beispiel:

<pre>
## Umgang mit Reservierungen

Wenn ein Anruf erkennbar eine Reservierung betrifft (z. B. Begriffe wie
"Reservierung", "Tisch bestellen", "für heute Abend reservieren"):

- Nutze die Regeln und Informationen aus dem Unter-Prompt "Reservierungen".
- Halte dich an die dort beschriebenen Abläufe und Fragen.
</pre>

Im Unter-Prompt „Reservierungen“ beschreiben Sie dann die Details (z. B. wie Name, Personenanzahl, Datum, Uhrzeit und besondere Wünsche abgefragt werden sollen).

= Besondere Aspekte der Telefon-KI von Portunity =

== Telefonkontext und Gesprächslänge ==

Da Gespräche in Echtzeit stattfinden, sollten Sie im Prompt festlegen:

* Wie viele Sätze die KI am Stück sprechen soll (z. B. kurz und prägnant).
* Wie sie reagieren soll, wenn der Anrufer zwischenruft oder abschweift.
* Dass sie bewusst Pausen lässt, damit der Anrufer zu Wort kommt.

Beispiel (Ausschnitt):

<pre>
## Stil am Telefon

- Sprich in kurzen Sätzen (maximal 2–3 Sätze am Stück).
- Mache kurze Pausen, damit der Anrufer reagieren kann.
- Stelle gezielte Fragen statt langer Monologe.
- Wenn der Anrufer dich unterbricht, hör sofort auf zu reden und gehe auf ihn ein.
</pre>

== Nutzung der Anrufer-Rufnummer im Prompt ==

Über die technische Plattform erhält die Telefon-KI Meta-Informationen zum Anruf, u. a. die anrufende Rufnummer. Sie können im Basis-Prompt festlegen, wie mit dieser Information umgegangen werden soll, zum Beispiel:

* Soll die KI die Rufnummer am Telefon wiederholen oder nicht?
* Darf sie aus der Rufnummer schließen, dass es sich um einen bekannten Kunden handeln könnte?
* Wie soll sie reagieren, wenn keine oder eine unterdrückte Rufnummer übermittelt wird?

Beispiel für entsprechende Anweisungen:

<pre>
## Umgang mit der Rufnummer des Anrufers

- Du kennst die von unserer Telefonanlage übermittelte Rufnummer des Anrufers. Diese lautet XXXX
- Wiederhole die Rufnummer am Telefon nur dann vollständig, wenn der Anrufer dich ausdrücklich darum bittet.
- Nutze die Rufnummer ggf. intern, um bekannte Anrufer wiederzuerkennen (z. B. durch Kennzeichnung in der Zusammenfassung),
ohne am Telefon detaillierte Rückschlüsse offenzulegen.
- Wenn keine Rufnummer übermittelt wird oder sie unvollständig ist, weise nicht darauf hin, sondern fahre normal fort.
</pre>

Die konkrete technische Verarbeitung der Rufnummer erfolgt im Hintergrund. Im Prompt beschreiben Sie lediglich, wie die KI sich im Gespräch dazu verhalten soll.

== Typische Muster, die sich bewährt haben ==

Die folgenden Muster können Sie in Ihren Prompts immer wieder verwenden:

; Anliegen zuerst klären
: Zuerst kurz und gezielt herausfinden, warum der Anrufer anruft. Danach erst in Details einsteigen.

; Zusammenfassung vor dem Abschluss
: Am Ende kurz wiederholen, was vereinbart wurde. So lassen sich Missverständnisse reduzieren.

; Ehrlichkeit bei Unsicherheit
: Wenn die KI etwas nicht sicher weiß, sollte sie das offen sagen und eine Rückmeldung durch das Team anbieten, statt zu raten.

; Eskalation statt „Halluzination“
: Besser an eine reale Person weiterleiten oder eine Rückrufbitte notieren, als falsche Zusagen zu machen.

Ausformulierte Beispiel-Prompts für typische Branchen finden Sie auf der Seite
'''[[Telefon-KI - Beispiel-Prompts & Praxis-Empfehlungen|Beispiel-Prompts & Praxis-Empfehlungen]]'''.

= Testen, testen und testen =

Gehen Sie iterativ vor. Also erstmal nur mit einem kleinen Prompt
* der die Begrüßung regelt
* den Namen des Agents und wie er sich verhalten soll (Du oder Sie-Anrede, ob er höflich oder ausführlich sein soll usw.)
* die Öffungszeiten kennt
* und weiß was ihr Unternehmen in 2-3 Sätzen macht

Dies testen Sie dann. Danach fügen Sie Absatz für Absatz weitere Informationen zu. Und testen wieder.

Überlegen Sie, was Ihre Anrufer in der Regel wissen wollen, was sie fragen usw. Versuchen Sie dabei nicht 100% der Fälle sofort ab zu bilden, sondern erst mal das wichtigste. Und dies testen Sie dann.

Für den ersten Agent können schnell ein dutzend Test-Anrufe und ein ganzer Nachmittag an Zeiteinsatz fällig werden. Wenn Sie einen Menschen als Mitarbeiter für das Telefon einstellen, dann müssten Sie diesem ja auch erstmal alles erklären wie er sich am Telefon verhalten soll. Sie müssten ihm das nötige Wissen geben zu Ihren Produkten, Angeboten usw. Genau dies müssen Sie Ihrem KI-Agent auch bei bringen.

Wenn Sie vom ersten Testen müde sind, schlafen Sie eine Nacht drüber - am nächsten Tag kommen neue Ideen. Geben Sie Ihren Kollegen die Gelegenheit den Agent zu testen bevor sie ihn „live schalten“. Ihre Kollegen haben vielleicht ganz andere Dinge wo sie mit Kunden, Interessenten, Lieferanten usw. Telefonieren als Sie vor Augen haben. Erweitern Sie die Prompts entsprechend.

Wenn Sie viel getestet haben schalten Sie live. Und nutzen Sie die Möglichkeiten via Mail oder Webhook die Anruf-Transscriptionen zu erhalten. Aus diesem können Sie in den ersten Wochen viel lernen was gut läuft und vor allem was weniger gut läuft, wo Wissenslücklen sind - und diese gezielt in den Prompts auffüllen.

Vergessen Sie vor dem Live-Schalten nicht das dicke Brett „Datenschutz“, also entsprechende Ansagen vorweg zu schalten, alles zu dokumentieren, alles mit Ihrem Datenschutzbeauftragten / spezialisierten Rechtsanwalt abzustimmen usw.

Telefon-KI - Gute Prompts schreiben

2025-11-21T16:07:15Z

Lr@superroot:

Telefon-KI - Gute Prompts schreiben

2025-11-21T15:56:53Z

Lr@superroot: Die Seite wurde neu angelegt: „= Ziel dieser Seite = Auf dieser Seite finden Sie Hinweise, wie Sie gute Prompts für Ihre Telefon-KI (KI-Agenten) formulieren. Im Mittelpunkt stehen: * der A…“