fetchbridge ist ein leichtgewichtiger, Docker-basierter Hintergrunddienst zur automatisierten Überwachung von Verzeichnissen und zum Verarbeiten/Verschieben von Videodateien via inotify.
Er dient als intelligentes Bindeglied in Automated-Media-Pipelines – beispielsweise zwischen einem Stream-Recorder (tw-recorder) und einem Upload-Service (yt-upload).
Eine Übersicht der internen Architektur (Module, Datenfluss, Diagramm) findet sich in ARCHITECTURE.md.
- Echtzeit-Überwachung: Reagiert ohne Verzögerung auf Dateisystem-Events (
IN_MOVED_TO,IN_CLOSE_WRITE) mittelsinotify- über einen eigenen, abhängigkeitsfreien ctypes-Wrapper (inotify_tree.py), der neben Linux auch für FreeBSD ≥ 14.5 ausgelegt ist. - Intelligente RW/RO-Erkennung:
- Read-Write (RW): Verschiebt Dateien direkt ins Zielverzeichnis und räumt leere Quellordner automatisch auf.
- Read-Only (RO): Kopiert Dateien sicher, falls das Quellverzeichnis schreibgeschützt gemountet ist.
- Initialer Scan: Verarbeitet beim Start automatisch alle bereits im Quellordner vorhandenen Videos.
- Filter-Mechanismus: Ignoriert temporäre Downloads (
.part,.ytdl,.tmp), versteckte Dateien sowie ununterstützte Formate. - Kollisionsschutz: Benennt Zieldateien bei Namensgleichheit automatisch um (
video_1.mp4). - Hot-Reloading der Konfiguration: Überwacht die Konfigurationsdatei und übernimmt Änderungen automatisch im laufenden Betrieb (außer
source_dir, das einen Neustart erfordert). - Minimales Docker-Image: Drei Varianten (Debian, Alpine, reines Python-Image) zur Auswahl.
Der Container arbeitet intern mit zwei primären Datenpfaden:
| Pfad im Container | Funktion | Standard-Format |
|---|---|---|
/srv/media-pipeline/recordings |
Quellverzeichnis (Eingang für fetchbridge, geteilt mit tw-recorders STORAGE_DIR) |
.mkv, .mp4, .mov, .webm |
/srv/media-pipeline/incoming |
Zielverzeichnis (Ausgang für Folge-Tools, geteilt mit yt-uploads IN_DIR) |
.mkv, .mp4, .mov, .webm |
/log |
Log-Dateien (Optional, siehe unten) | Logs / App-Output |
Hier ist ein Beispiel für die Integration in eine bestehende docker-compose.yml:
services:
fetchbridge:
image: ghcr.io/chaos7x/fetchbridge:latest
container_name: fetchbridge
hostname: fetchbridge
user: "11107:11108"
restart: unless-stopped
environment:
- TZ=Europe/Berlin
- PYTHONUNBUFFERED=1
- LOG_LEVEL=INFO
volumes:
# EIN gemeinsamer Bind-Mount für recordings/ UND incoming/ statt zwei
# getrennter Mounts - siehe "Warum ein einzelner Mount?" unten.
- /srv/media-pipeline:/srv/media-pipeline:rwZwei getrennte Bind-Mounts (recordings und incoming je einzeln eingebunden) sehen im Container zwar wie normale Unterordner desselben Baums aus, sind für den Kernel aber unterschiedliche Mount-Instanzen - os.rename() (der von mover.py bevorzugte atomare Pfad) scheitert dann mit EXDEV und fällt auf das langsamere Kopieren+Löschen zurück, selbst wenn beide Host-Verzeichnisse zufällig auf derselben Partition liegen. Das gilt für jede Art von getrennten Mounts gleichermaßen - egal ob zwei Docker-Volumes, zwei einzelne -v-Bind-Mounts oder zwei separate NFS-Exports. Ein einzelner Mount über den gemeinsamen Elternordner (wie oben) vermeidet das vollständig.
user: "11107:11108" oben ist nur ein Platzhalter. Der Mount oben nutzt bereits denselben Host-Pfad /srv/media-pipeline, den auch die Bare-Metal-/.deb-Installationen von tw-recorder/yt-upload nutzen - Container und Bare-Metal teilen sich den Baum also ohne weitere Anpassung.
Der Ordner gehört dort root:media-pipeline mit Modus 2775 (setgid, bewusst ohne Sticky-Bit) - Schreib-/Löschrecht hängt also rein an der Gruppe, nicht an der UID oder dem Datei-Owner. Die GID im user:-Feld muss deshalb mit der echten Host-Gruppe übereinstimmen, sonst gibt's Permission denied:
getent group media-pipeline # z.B. media-pipeline:x:998:Die zweite Zahl in user: "<uid>:<gid>" durch diese echte GID ersetzen (z.B. user: "11107:998") - die UID (erste Zahl) ist frei wählbar, da sie für die Zugriffsrechte auf diese Verzeichnisse keine Rolle spielt.
fetchbridge läuft auch direkt auf dem Host. Es hat keine Python-Abhängigkeiten außer der Standardbibliothek (inotify wird per ctypes direkt aus der libc angesprochen) - pip installiert nur das eigene Package:
apt install python3-pip python3-setuptools
cd /pfad/zu/fetchbridge
pip install --break-system-packages --no-deps .Danach steht der Befehl fetchbridge systemweit zur Verfügung (fetchbridge --version zum Testen).
Die Logdatei landet je nach Umgebung automatisch am sinnvollsten Ort (/var/log/fetchbridge/, sofern beschreibbar und ein klassischer Syslog-Daemon läuft, sonst nur auf stdout/journald) - siehe log_file-Konfigurationsoption, falls ein fester Pfad gewünscht ist. Läuft ein Syslog-Daemon, rotiert die App die Datei bewusst nicht selbst (kein RotatingFileHandler) - das übernimmt das mitgelieferte /etc/logrotate.d/fetchbridge (nur im .deb-Paket enthalten; bei einer reinen pip-Installation ohne .deb selbst einrichten, falls gewünscht). Nur bei explizit gesetztem log_file oder einem gemounteten Docker-/log-Volume rotiert die App eigenständig, da dort sonst niemand rotieren würde.
Jedes GitHub Release enthält zusätzlich ein fetchbridge_<version>_all.deb als Anhang - keine manuelle pip-Installation nötig:
wget https://github.com/chaos7x/fetchbridge/releases/latest/download/fetchbridge_<version>_all.deb
apt install ./fetchbridge_<version>_all.debDas Paket legt einen dedizierten Systemuser (fetchbridge) an und startet den Dienst bewusst nicht automatisch - erst /etc/fetchbridge/fetchbridge.conf (bzw. conf.d/) anpassen, dann:
systemctl enable --now fetchbridgeDevuan / Debian ohne systemd (sysvinit-core, OpenRC): Das Paket bringt zusätzlich ein klassisches /etc/init.d/fetchbridge-Skript mit, das postinst automatisch anstelle des systemd-Service registriert, wenn kein systemd läuft - ebenfalls deaktiviert (update-rc.d … defaults-disabled, kein Start beim Booten). Die mitgelieferte .service-Datei unter /usr/lib/systemd/system/ bleibt dort einfach ungenutzt liegen, wie bei Debian-Paketen üblich. Aktivieren und starten:
update-rc.d fetchbridge enable
service fetchbridge startJedes Release enthält neben den .deb-Dateien auch FreeBSD-Pakete, je eines für FreeBSD 14 und 15 (…-freebsd14.pkg / …-freebsd15.pkg, gebaut von freebsd/build-pkg.py). Sie hängen fest an Python 3.11 (python311), damit Interpreter und Python-Abhängigkeiten zusammenpassen:
pkg install python311
pkg add fetchbridge-<version>-freebsd14.pkgDas Paket legt /etc/fetchbridge/fetchbridge.conf aus der Vorlage an (falls noch keine existiert), dazu den Dienstuser, die Gruppe media-pipeline und die Verzeichnisse unter /srv/media-pipeline, genau wie das Debian-Paket. Der Dienst wird dabei bewusst nicht aktiviert, die nötigen sysrc/service-Befehle zeigt pkg nach der Installation an. Noch nicht auf einem echten FreeBSD-System getestet.
Für FreeBSD ≥ 14.5 (native inotify in der libc) liegt unter freebsd/rc.d/fetchbridge ein rc.d-Skript bei, das Pendant zum systemd-Service aus debian/. Ohne das fertige Paket geht die Einrichtung auch von Hand und aktiviert den Dienst ebenfalls nicht von selbst. Bisher nur gegen die Doku geschrieben, noch nicht auf einem echten FreeBSD-System getestet.
# Abhängigkeiten (py311 an die installierte Python-Version anpassen)
pkg install python3 py311-pip
cd /pfad/zu/fetchbridge
pip install --no-deps .
# Dienstuser und gemeinsame Pipeline-Gruppe (wie debian/postinst)
pw groupshow media-pipeline >/dev/null 2>&1 || pw groupadd media-pipeline
pw usershow fetchbridge >/dev/null 2>&1 || pw useradd fetchbridge -d /nonexistent -s /usr/sbin/nologin -G media-pipeline
install -d -o root -g media-pipeline -m 2775 /srv/media-pipeline /srv/media-pipeline/recordings /srv/media-pipeline/incoming
install -d /etc/fetchbridge
# rc.d-Skript installieren und aktivieren
install -m 755 freebsd/rc.d/fetchbridge /usr/local/etc/rc.d/fetchbridge
sysrc fetchbridge_enable=YES
service fetchbridge startVor dem service fetchbridge start wie unter Linux /etc/fetchbridge/fetchbridge.conf anlegen (Vorlage: fetchbridge.conf.example).
Das Skript startet fetchbridge -D über daemon(8) (Neustart bei Absturz, Userwechsel inkl. media-pipeline-Zusatzgruppe) und leitet die Ausgabe an syslog weiter (Tag fetchbridge, landet standardmäßig in /var/log/messages). Weitere Einstellungen (fetchbridge_runas, fetchbridge_args, fetchbridge_env) stehen im Kopf des Skripts.
./build-pyz.sh baut aus src/ ein einziges, selbst-enthaltenes fetchbridge.pyz - läuft auf jedem System mit einem nackten python3, ganz ohne vorherige pip install/apt install:
./build-pyz.sh
./fetchbridge.pyz --version| Dockerfile | Basis | Installationsweg |
|---|---|---|
Dockerfile (Standard) |
debian:trixie-slim |
apt für python3, pip install --no-deps . für fetchbridge selbst |
Dockerfile.alpine |
alpine:3 |
Wie oben, aber apk statt apt |
Dockerfile.pyimg |
python:3-slim |
Ein einziger pip install . |
Die Hauptkonfiguration erfolgt über /etc/fetchbridge/fetchbridge.conf (bzw. fetchbridge.conf.example als Vorlage). Zusätzlich wird /etc/fetchbridge/conf.d/*.conf eingelesen (alphabetisch, spätere Dateien überschreiben frühere Werte). Änderungen werden im laufenden Betrieb automatisch erkannt (Hash-Prüfung alle CONFIG_CHECK_INTERVAL Sekunden) - außer bei source_dir, das einen Neustart erfordert (InotifyTree ist fest an den Startpfad gebunden).
[general]
# Log-Level: DEBUG, INFO, WARNING, ERROR
# log_level = INFO
# Alternative dazu: die Umgebungsvariable DEBUG=true/yes/1 (wie bei
# tw-recorder/yt-upload) - siehe Umgebungsvariablen-Abschnitt, keine Config-Option.
# Fester Pfad für die Logdatei (bei explizitem log_file oder gemountetem
# /log-Docker-Volume rotierend, max. 10 MB, 5 Backups - läuft stattdessen ein
# klassischer Syslog-Daemon, übernimmt logrotate die Rotation, siehe README).
# Ohne diese Angabe wird automatisch geloggt, sobald /log tatsächlich als
# Docker-Volume gemountet ist (reines Vorhandensein des Verzeichnisses
# reicht nicht, siehe unten) oder ein klassischer Syslog-Daemon läuft -
# sonst nur nach stdout (journald/docker logs erfassen das bereits).
# log_file = /log/fetchbridge.log
# Quellverzeichnis, das überwacht wird (Änderung erfordert Neustart)
# source_dir = /srv/media-pipeline/recordings
# Zielverzeichnis, in das fertige Dateien verschoben/kopiert werden
# target_dir = /srv/media-pipeline/incoming
[mover]
# Kommagetrennte Liste erlaubter Datei-Endungen
# allowed_extensions = .mkv,.mp4,.mov,.webm
# Kommagetrennte Liste von Endungen, die als "noch nicht fertig" gelten
# temp_extensions = .part,.ytdl,.tmp,.temp
# Leere Quell-Unterordner nach dem Verschieben automatisch entfernen (true/false)
# cleanup_empty_dirs = falsefetchbridge [-h] [-D] [--healthcheck] [-v]
-D,--daemon— Dämon-Modus: Dauerhafte Ordnerüberwachung (Standardmodus im Container, sieheentrypoint.sh)--healthcheck— Prüft die Heartbeat-Datei, Exit-Code 0 (healthy) oder 1 (unhealthy). Für DockerHEALTHCHECKgedacht, läuft unabhängig vom Dämon-Prozess.-v,--version— Versionsnummer anzeigen
CONFIG_FILE— Standard/etc/fetchbridge/fetchbridge.confCONF_D_DIR— Standard/etc/fetchbridge/conf.dSOURCE_DIR/TARGET_DIR— Fallback, falls nicht in der Config gesetzt. Standard/srv/media-pipeline/recordings(dasselbe Verzeichnis wietw-recordersSTORAGE_DIR) bzw./srv/media-pipeline/incoming(dasselbe Verzeichnis wieyt-uploadsIN_DIR), einheitlich für Docker und Bare-Metal. Das.deb-Postinst legt beide mit einer gemeinsamen Gruppe (media-pipeline) an, damit alle drei Dienste darauf zugreifen können.ALLOWED_EXTENSIONS/TEMP_EXTENSIONS— Fallback, falls nicht in der Config gesetztLOG_LEVEL— StandardINFODEBUG— Standard0. Auftrue/1setzen für erweiterte Log-Ausgaben; Alias fürLOG_LEVEL=DEBUG(dieselbe Variable wie beitw-recorder/yt-upload), eine explizit gesetztelog_level/LOG_LEVELhat aber immer Vorrang.LOG_FILE— Fallback, falls nicht in der Config gesetzt; siehe[general]-Sektion obenCONFIG_CHECK_INTERVAL— Standard15(Sekunden zwischen Hash-Prüfungen der Config-Dateien)HEARTBEAT_FILE— Standard/var/run/fetchbridge/fetchbridge.heartbeat, falls das Verzeichnis existiert (legen systemd-Unit, init.d- und rc.d-Skript an), sonst/tmp/fetchbridge.heartbeatHEARTBEAT_MAX_AGE— Standard60(Sekunden, bevor--healthcheckals "unhealthy" gilt)
Reguläre Releases folgen vX.Y.Z (SemVer) und entstehen manuell zusammen mit einer echten Code-Änderung.
Zusätzlich prüft ein monatlicher Workflow (os-patch-release.yml, 1. jeden Monats), ob das Debian-/Alpine-Basis-Image ungenutzte Security-Patches hat, die docker-refresh.yml's wöchentliches latest-Update zwar schon mitnimmt, die aber an den fixen vX.Y.Z-Tags vorbeilaufen (die frieren für immer auf ihrem Build-Zeitpunkt ein). Findet der Workflow etwas, hängt er eine vierte Versionsstelle an, die ausschließlich für solche reinen OS-Patch-Releases reserviert ist: v1.3.1 → v1.3.1.1 → v1.3.1.2 (jeweils ohne Code-Änderung, nur aktualisierte System-Pakete). Bleibt die vierte Stelle bei Nichts-zu-patchen-Läufen einfach aus, gibt es auch keinen neuen Tag - kein Rauschen in der Release-Historie.
Der nächste echte Code-Release setzt diese vierte Stelle nicht fort, sondern lässt sie weg: auf v1.3.1.2 folgt bei einer echten Änderung v1.3.2, nicht v1.3.2.0 oder v1.3.1.3.
Ein lokales Image kann über das Build-Skript kompiliert werden:
./build.sh # Nutzt Name & Version aus pyproject.toml, Standard-Dockerfile
./build.sh 2.0.0 # Explizite Version, Standard-Dockerfile
./build.sh alpine # Version aus pyproject.toml, Dockerfile.alpine
./build.sh 2.0.0 pyimg # Explizite Version, Dockerfile.pyimgName und Standard-Version werden automatisch aus pyproject.toml gelesen - ein explizit übergebenes Versions-Argument überschreibt das.
apt install python3-pytest # oder: pip install -r requirements-test.txt
pytest -v
ruff check src/fetchbridge/Dieses Projekt steht unter der GNU General Public License v3.0 (GPLv3).