Bereitstellung eines automatisch aktualisierten IPTV-Playlist-Dienstes mit Docker

2026-2-23

Sobald eine Playlist mehr als einige Dutzend Kanäle umfasst, ist manuelle Pflege nicht mehr realistisch: Eine Kanalnamensänderung erfordert das Bearbeiten einer Datei, ein neu hinzugefügtes Gerät erneut den Import. Mit einem leichten Playlist-Dienst in Docker kann das NAS die Playlist zeitgesteuert generieren und unter einer festen Adresse bereitstellen; alle Player im Haus beziehen sie von dieser einen Adresse.

Dieser Beitrag beschreibt das Deployment-Konzept und die Compose-Schreibweise; verwende als Quellen diejenigen, für die du selbst Nutzungsrechte hast (vom Betreiber bereitgestellte Multicast-Adressen, selbst betriebene Quellen).

1. Gesamtkonzept

Die Quellenliste (Kanalname + Adresse) als Eingabe in einem Verzeichnis auf dem NAS ablegen;
Mit einem Container zeitgesteuert „Prüfen + m3u generieren“ ausführen;
Die generierte m3u über einen Web-Port bereitstellen; Player tragen diese URL direkt ein;
Der Container schreibt Prüfergebnisse und Logs ebenfalls auf die Festplatte, um die Rückverfolgung zu erleichtern.

2. Verzeichnisvorbereitung

Zuerst die Verzeichnisstruktur auf dem NAS anlegen; der Container mountet Eingabe und Ausgabe hinein:

docker/
└── iptv/
    ├── data/          # 输出：生成的 m3u、日志
    │   └── playlist.m3u
    ├── source.txt     # 输入：你自己的频道清单
    └── docker-compose.yml

Format der EingabedateiEinfach selbst festlegen, ein Kanal pro Zeile:

CCTV-1 综合|udp://@239.x.x.x:1234
湖南卫视|rtp://239.x.x.x:5678

3. docker-compose.yml

services:
  iptv:
    image: <你选用的镜像>
    container_name: iptv
    restart: unless-stopped
    ports:
      - "50086:50086"
    volumes:
      - ./data:/app/data
      - ./source.txt:/app/source.txt:ro
    environment:
      - TZ=Asia/Shanghai
      - CHECK_TIMEOUT=5          # 单个地址检测超时（秒）
      - CHECK_CONCURRENCY=8      # 并发数，别设太大
      - CRON=0 4 * * *           # 每天凌晨 4 点跑一次

Starten:

docker compose up -d
docker compose logs -f      # 观察首次生成的输出

4. Validierung und Nutzung

Zugriff über den Browser http://你的NAS_IP:50086/playlist.m3uWenn Inhalte sichtbar sind, bedeutet das, dass der Dienst normal läuft;
Im Player „Quelle hinzufügen → Von URL importieren“ auswählen und die oben genannte Adresse eintragen;
Nach Änderungen an der Quellenliste den Container einmal neu starten oder warten, bis der zeitgesteuerte Job die Generierung zur festgelegten Zeit automatisch ausführt;
Die erzeugte m3u kann direkt von den IPTV-Plugins von Jellyfin / Emby / Plex gelesen werden; für das EPG genügt eine separat konfigurierte XMLTV-Adresse.

5. Einige praktische Hinweise

Parallelität nicht zu hoch einstellenWenn gleichzeitig Verbindungen zu mehr als hundert Adressen aufgebaut werden, ist ein Heimrouter schnell überlastet, was wiederum zu vielen Fehlurteilen führt.
Ergebnisse versionierenVon den täglich erzeugten Dateien jeweils eine datierte Kopie aufbewahren, damit bei Problemen verglichen werden kann, an welchem Tag die Änderung begonnen hat.
Genügend Logs vorhaltenContainer-Logs sind nur bei der Fehlersuche nützlich; es wird empfohlen, sie in Dateien auszugeben und die Größe einzelner Dateien zu begrenzen, um zu vermeiden, dass das NAS vollgeschrieben wird.
Keine Ports für das Internet öffnenDieser Dienst ist nur für den Heimgebrauch gedacht; Ports nicht ins öffentliche Netz weiterleiten; wenn externer Zugriff wirklich erforderlich ist, über VPN zurück ins Heimnetz verbinden und den Dienst nicht direkt exponieren.
Feste LAN-IPDem NAS eine statische Adresse oder eine DHCP-Reservierung zuweisen; andernfalls müssen bei einer IP-Änderung alle Player angepasst werden.

6. Häufige Fragen

Der Container ist gestartet, aber die m3u ist leer.	Prüfe zuerst in den Logs, ob die Eingabedatei gelesen wird; vergewissere dich dann, dass Trennzeichen und Kodierung der Quellenliste stimmen.
Alle Prüfergebnisse sind Fehlschläge.	Prüfe zuerst, ob das Netzwerk des Containers Multicast erreichen kann (die meisten Standard-Bridge-Netzwerke können das nicht), und teste dann den host-Netzwerkmodus.
Der Player meldet eine ungültige Adresse.	Öffne die URL einmal auf einem Computer mit VLC, um sie zu verifizieren, und unterscheide so, ob das Problem beim Dienst oder beim Player liegt.
Die geplante Aufgabe wurde nicht ausgelöst.	Prüfe die Zeitzoneneinstellung des Containers; CRON richtet sich nach der Zeit des Containers.

Zusammenfassung

Mit Containern lässt sich „Prüfen + Erzeugen + Verteilen“ zu einer Kette verbinden; die Pflege der Playlist wandelt sich dadurch von „Dateien manuell bearbeiten“ zu „eine Zeile in der Quellenliste ändern und den Rest zeitgesteuerten Aufgaben überlassen“. Der Wert dieses Ablaufs besteht darin, dass dudie Quellen, für die du das Nutzungsrecht hast,einheitlich verwaltest – die Anzahl der Quellen ist nicht groß, aber sie sind kontrollierbar, wartbar und rollback-fähig; das ist der Schlüssel für den langfristigen Betrieb.