Docker로 자동 업데이트되는 IPTV 재생목록 서비스를 배포하기

2026-2-23

재생 목록이 수십 개 채널을 넘어가면 수작업 유지보수는 현실적이지 않다: 채널 이름 하나를 바꾸려면 파일을 편집해야 하고, 새 장비를 추가하려면 다시 가져와야 한다. Docker로 가벼운 재생 목록 서비스를 실행하면 NAS가 정기적으로 생성하여 고정 주소로 외부에 제공할 수 있고, 집 안의 모든 플레이어가 이 하나의 주소에서 가져온다.

이 글은 배포思路와 Compose 작성법을 다루며, 소스는 자신이 사용할 권리가 있는 것들(통신사가 제공하는 멀티캐스트 주소, 자체 구축 소스)을 사용한다.

一、전체思路

소스 목록(채널 이름 + 주소)을 입력으로 하여 NAS의 한 디렉터리에 둔다;
container로 정기적으로 「검사 + m3u 생성」을 실행한다;
생성된 m3u는 Web port를 통해 외부에 제공되며, 플레이어는 이 URL을 직접 입력한다;
container는 검사 결과와 로그도 디스크에 기록하여 추적을 용이하게 한다.

二、디렉터리 준비

먼저 NAS에 디렉터리 구조를 만들고, container가 입력과 출력을 모두 mount한다:

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

입력 파일 형식간단하게 직접 정하면 되며, 한 줄에 채널 하나:

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

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

시작:

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

四、검증 및 사용

브라우저에서 접속 http://你的NAS_IP:50086/playlist.m3u내용이 보이면 서비스가 정상이라는 뜻입니다;
플레이어에서 「소스 추가 → URL에서 가져오기」를 선택하고 위 주소를 입력하세요;
소스 목록을 수정한 후 container를 한 번 재시작하거나, 예약 작업이 시간에 맞춰 자동 생성될 때까지 기다리세요;
생성된 m3u는 Jellyfin / Emby / Plex의 IPTV 플러그인에서 바로 읽을 수 있으며, 편성표는 XMLTV 주소를 별도로 설정하면 됩니다.

5. 몇 가지 실전 요점

동시 연결을 크게 열지 마세요: 한 번에 수백 개 주소로 연결을 시도하면 가정용 router가 쉽게 포화되어 오히려 대량 오판이 발생합니다.
결과는 버전 관리하세요: 매일 생성되는 파일을 날짜별로 한 부씩 보관하면 문제 발생 시 어느 날부터 바뀌었는지 비교할 수 있습니다.
로그를 충분히 남기세요: container 로그는 문제排查 시에만 유용하므로 파일로 출력하고 단일 파일 크기를 제한해 NAS가 가득 차지 않도록 하세요.
외부 네트워크에 port를 개방하지 마세요: 이 서비스는 집에서만 사용하므로 port를 공인망에 매핑하지 마세요; 외부 접근이 꼭 필요할 때는 VPN으로 접속하고 직접 노출하지 마세요.
내부 네트워크 IP를 고정하세요: NAS에 정적 주소 또는 DHCP 예약을 설정하세요. 그렇지 않으면 IP가 바뀔 때 모든 플레이어를 수정해야 합니다.

六、자주 묻는 질문

container는 올라왔는데 m3u가 비어 있음	먼저 로그에서 입력 파일이 읽혔는지 확인하고, 그다음 소스 목록의 구분자와 인코딩에 문제가 없는지 확인한다.
검사 결과가 전부 실패	먼저 container가 있는 네트워크에서 멀티캐스트에 접근할 수 있는지 확인한다(대부분 기본 bridge 네트워크에서는 안 됨). host 네트워크 모드로 바꿔서 시도해 본다.
플레이어에서 주소가 유효하지 않다고 표시됨	URL을 컴퓨터에서 VLC로 열어 한 번 검증하여 서비스 문제인지 플레이어 문제인지 구분한다.
예약 작업이 실행되지 않음	container 시간대 설정을 확인한다. CRON은 container 시간 기준으로 동작한다.

소결

container로 「검사 + 생성 + 배포」를 연결하면 재생 목록 유지 관리가 「파일을 수동으로 편집」에서 「소스 목록 한 줄만 수정하고 나머지는 예약 작업에 맡김」으로 바뀐다. 이 흐름의 가치는 당신이자신이 사용할 권리가 있는 소스에 대해통합 관리한다는 데 있다 — 소스 수는 많지 않지만 통제 가능하고 유지보수 가능하며 롤백 가능해야 오래 운영할 수 있다는 것이 핵심이다.