Desplegar con Docker un servicio de listas de reproducción IPTV con actualización automática

2026-2-23

Una vez que la lista de reproducción supera unas decenas de canales, el mantenimiento manual deja de ser viable: cambiar el nombre de un canal requiere editar el archivo, y añadir un dispositivo nuevo obliga a reimportar. Ejecutar con Docker un servicio ligero de listas de reproducción permite que el NAS genere y exponga periódicamente una dirección fija, y que todos los reproductores de casa obtengan la lista desde esa única dirección.

Este artículo trata sobre el enfoque de despliegue y la forma de escribir el Compose; usa como fuentes aquellas que tengas derecho a usar (direcciones multicast entregadas por el operador, fuentes propias).

I. Enfoque general

Toma el inventario de fuentes (nombre del canal + dirección) como entrada y colócalo en un directorio del NAS;
usa un container para ejecutar periódicamente la «detección + generación de m3u»;
el m3u generado se expone a través de un port Web, y el reproductor rellena directamente esta URL;
el container también guarda en disco los resultados de la detección y los logs, para facilitar la trazabilidad.

II. Preparación de directorios

Primero crea la estructura de directorios en el NAS; el container monta tanto la entrada como la salida:

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

Formato del archivo de entradaDefínelo de la forma más simple posible, un canal por línea:

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

III. 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 点跑一次

Inicio:

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

IV. Verificación y uso

Accede desde el navegador a http://你的NAS_IP:50086/playlist.m3u, poder ver el contenido indica que el servicio funciona correctamente;
En el reproductor, «Añadir fuente → Importar desde URL», introduce la dirección anterior;
Tras modificar la lista de fuentes, reinicia el container una vez, o espera a que la tarea programada se genere automáticamente a su hora;
El m3u generado puede ser leído directamente por los plugins IPTV de Jellyfin / Emby / Plex; para la guía de programas basta con configurar aparte la dirección XMLTV.

V. Algunos puntos prácticos

No abuses de la concurrencia: iniciar conexiones a cientos de direcciones a la vez satura fácilmente el router doméstico, lo que provoca numerosos falsos positivos.
Versiona los resultados: conserva una copia diaria del archivo generado con la fecha, para poder comparar en caso de problema desde qué día empezó a cambiar.
Deja suficientes logs: los logs del container solo son útiles para diagnosticar; se recomienda volcarlos a archivo y limitar el tamaño por archivo para evitar llenar el NAS.
No expongas ports al exterior: este servicio es solo para uso doméstico; no mapees los ports a la red pública; si realmente necesitas acceso externo, vuelve por VPN, no lo expongas directamente.
Fija la IP de la red interna: asigna al NAS una dirección estática o una reserva DHCP; de lo contrario, si la IP cambia, todos los reproductores tendrán que modificarse.

VI. Preguntas frecuentes

El container arranca pero el m3u está vacío	Primero revisa en los logs si el archivo de entrada se está leyendo; luego confirma que el separador y la codificación de la lista de fuentes sean correctos.
Todos los resultados de detección fallan	Primero confirma si la red donde está el container puede acceder al multicast (la mayoría de las redes bridge por defecto no pueden), prueba cambiando al modo de red host.
El reproductor indica que la dirección no es válida	Lleva la URL a la computadora y ábrela con VLC para verificarla una vez, así distingues si es un problema del servicio o del reproductor.
La tarea programada no se activó	Revisa la configuración de zona horaria del container, CRON sigue la hora del container.

Resumen

Usar containers para encadenar «detección + generación + distribución» hace que el mantenimiento de la lista de reproducción pase de «editar archivos manualmente» a «cambiar una línea de la lista de fuentes y dejar el resto a las tareas programadas». El valor de este flujo está en que túsobre las fuentes que tienes derecho a usarhaces una gestión unificada — la cantidad de fuentes no es mucha, pero es controlable, mantenible y reversible, y eso es la clave para que funcione a largo plazo.