Implantar um serviço de lista de reprodução IPTV com atualização automática usando Docker

2026-2-23

Quando a lista de reprodução ultrapassa algumas dezenas de canais, a manutenção manual deixa de ser viável: alterar o nome de um canal exige editar o ficheiro, adicionar um novo dispositivo implica reimportar tudo. Correr um serviço leve de listas de reprodução em Docker permite que o NAS gere periodicamente e exponha um endereço fixo, a partir do qual todos os leitores de casa fazem o pull.

Este artigo aborda a lógica de implementação e a escrita do Compose, utilizando fontes sobre as quais tens direitos de uso (endereços multicast fornecidos pela operadora, fontes próprias).

I. Lógica geral

Colocar a lista de fontes (nome do canal + endereço) como entrada, num diretório do NAS;
Usar um container para executar periodicamente «deteção + geração de m3u»;
O m3u gerado é exposto através de um port Web, e os leitores preenchem diretamente esse URL;
O container também persiste os resultados da deteção e os logs em disco, para facilitar a consulta posterior.

II. Preparação de diretórios

Primeiro criar a estrutura de diretórios no NAS, e o container monta tanto a entrada como a saída:

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

Formato do ficheiro de entradaDefine-o de forma simples, um canal por linha:

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

Arranque:

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

IV. Verificação e utilização

Acesso pelo browser http://你的NAS_IP:50086/playlist.m3u, conseguir ver o conteúdo indica que o serviço está normal;
No player, «Adicionar fonte → Importar de URL», preencha o endereço acima;
Após alterar a lista de fontes, reinicie o container uma vez, ou aguarde a tarefa agendada gerar automaticamente na hora definida;
O m3u gerado pode ser lido diretamente pelo plugin IPTV do Jellyfin / Emby / Plex, basta configurar o endereço XMLTV separadamente para o guia de programação.

Cinco, alguns pontos práticos

Não abra concorrência demais: iniciar conexões para centenas de endereços de uma só vez sobrecarrega facilmente o router doméstico, causando muitas falsas detecções.
Versione os resultados: mantenha uma cópia do arquivo gerado diariamente com a data, para que em caso de problema seja possível comparar em que dia começou a mudar.
Guarde logs suficientes: os logs do container só são úteis durante a investigação; recomenda-se gravá-los em arquivo e limitar o tamanho por arquivo, evitando encher o NAS.
Não exponha portas à internet: este serviço é apenas para uso doméstico, não mapeie a port para a rede pública; se realmente precisar de acesso externo, volte via VPN, não exponha diretamente.
Fixe o IP da rede interna: configure um endereço estático ou reserva DHCP para o NAS, caso contrário, se o IP mudar, todos os players precisarão ser alterados.

VI. Perguntas frequentes

O container iniciou, mas o m3u está vazio	Primeiro verifique no log se o arquivo de entrada foi lido; depois confirme se o separador e a codificação da lista de fontes estão corretos.
Todos os resultados de detecção falharam	Primeiro confirme se a rede onde o container está consegue acessar multicast (a maioria das redes bridge padrão não consegue); tente usar o modo de rede host.
O player indica endereço inválido	Abra a URL no VLC em um computador para validar uma vez, distinguindo se é problema do serviço ou do player.
A tarefa agendada não foi disparada	Verifique a configuração de fuso horário do container; o CRON segue o horário do container.

Resumo

Usando containers para encadear "detecção + geração + distribuição", a manutenção da playlist deixa de ser "editar arquivos manualmente" e passa a ser "alterar uma linha da lista de fontes e deixar o resto com a tarefa agendada". O valor desse fluxo está em vocêpara as fontes que você tem direito de usarfazer gestão unificada — a quantidade de fontes não é grande, mas é controlável, mantenível e reversível, e isso é o ponto-chave para operar a longo prazo.