lsiodev/tvheadend

linuxserver/tvheadend

Tvheadend 是一款运行于Linux、FreeBSD和Android系统的TV流媒体服务器和录制器，支持DVB-S、DVB-S2、DVB-C、DVB-T、ATSC、ISDB-T、IPTV、SAT>IP和HDHomeRun作为输入源，提供HTTP（VLC、MPlayer）、HTSP（Kodi、Movian）和SAT>IP流媒体服务，并支持多种EPG源（包括空中DVB和ATSC、XMLTV、PyXML等）。

!https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/tvheadend-big.png

支持的架构

该镜像利用Docker manifest实现多平台支持，拉取 lscr.io/linuxserver/tvheadend:latest 即可自动获取对应架构的镜像，也可通过标签指定特定架构：

应用设置

设置步骤取决于使用稳定版标签还是latest标签。latest版本包含设置向导，使用更简单。

Stable版本

1. 进入Configuration --> DVB Inputs --> TV adapters，添加LNB/开关信息。
2. 在Networks标签创建新网络，设置正确的预定义多路复用器和轨道位置。
3. 返回TV adapters标签，在通用LNB下添加新创建的网络。
4. 返回Networks标签，选中创建的网络并点击Force Scan，Tvheadend将扫描服务。
5. 扫描完成后，进入Services标签，选择要作为频道的服务，标记并点击map services，频道将显示在Configuration --> Channel/EPG中。

Latest版本

首次登录时会自动弹出设置向导，若未弹出，可在Configuration --> General --> Base中点击Start Wizard，按照向导完成基本设置。

配置XMLTV抓取器

1. 在Configuration --> Channel/EPG --> EPG Grabber Modules中检查抓取器是否列出。
2. 找到抓取器路径字段，提取以 tv_grab_ 开头的部分，替换以下命令中的 for_you_to_fill_out：

   bash
   docker exec -it -u abc tvheadend /usr/bin/for_you_to_fill_out --configure
   

3. 按照屏幕提示完成配置（缓存选项接受默认值），配置后启用抓取器。
4. 若已有配置文件，可放入 /config 卷映射的 .xmltv 文件夹（不存在则创建）。

Comskip设置

容器内置Comskip用于录制内容的广告标记，需在Tvheadend录制配置中添加：

1. 进入Configuration --> Recording，将右上角视图级别设为advanced。
2. 在Post-processor command字段添加：

   bash
   /usr/bin/comskip --ini=/config/comskip/comskip.ini "%f"
   

3. 录制完成后Comskip将自动运行，配置文件 comskip.ini 位于 /config/comskip 目录，可参考 Comskip 官网调整参数。

FFmpeg

FFmpeg已安装在 /usr/bin/，可用于管道处理。

EPG XML文件

若有XML格式的EPG数据，可放入 /config 卷映射的 data 文件夹（不存在则创建），文件需命名为 guide.xml。在Configuration --> Channel/EPG --> EPG Grabber Modules中选择相应的XML文件抓取器（如WebGrab+Plus则选择WebGrab+Plus XML文件抓取器）。

Picons

容器内置 https://github.com/picons/picons 图标集，路径为 /picons。在Configuration --> General --> Base中设置Channel icon path即可启用，需将视图级别设为至少advanced。

高级设置详见 Tvheadend官方文档。

额外运行参数

可通过 RUN_OPTS 环境变量添加额外启动参数（如调试或反向代理webroot设置），需确保参数正确，错误参数可能导致容器无法启动。

使用方法

docker-compose（推荐）

yaml
---
version: "2.1"
services:
  tvheadend:
    image: lscr.io/linuxserver/tvheadend:latest
    container_name: tvheadend
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - RUN_OPTS= #可选
    volumes:
      - /path/to/data:/config
      - /path/to/recordings:/recordings
    ports:
      - 9981:9981
      - 9982:9982
    devices:
      - /dev/dri:/dev/dri #可选，用于硬件加速
      - /dev/dvb:/dev/dvb #可选，用于DVB卡直通
    restart: unless-stopped

docker cli

bash
docker run -d \
  --name=tvheadend \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e RUN_OPTS= `#可选` \
  -p 9981:9981 \
  -p 9982:9982 \
  -v /path/to/data:/config \
  -v /path/to/recordings:/recordings \
  --device /dev/dri:/dev/dri `#可选` \
  --device /dev/dvb:/dev/dvb `#可选` \
  --restart unless-stopped \
  lscr.io/linuxserver/tvheadend:latest

Host与Bridge网络模式

若使用IPTV、SAT>IP或HDHomeRun，需使用 --net=host 创建容器并移除 -p 端口映射，因为这些服务需要多播地址 239.255.255.250 和UDP端口 1900，目前Docker bridge模式不支持。若主机存在其他多播服务（如SSDP/DLNA/Emby），可能需通过macvlan为Tvheadend分配独立IP解决稳定性问题。

参数说明

环境变量文件（Docker secrets）

可通过 FILE__ 前缀从文件中设置环境变量，例如：

bash
-e FILE__MYVAR=/run/secrets/mysecretvariable

将从 /run/secrets/mysecretvariable 文件内容设置 MYVAR 环境变量。

应用Umask设置

可通过 -e UMASK=022 覆盖容器内服务的默认umask设置，umask通过减法调整权限，详见 umask说明。

用户/组标识符

使用卷映射时，可通过 PUID 和 PGID 避免主机与容器间的权限问题。确保主机卷目录所有者与指定的 PUID/PGID 一致。通过 id your_user 命令获取当前用户的ID：

bash
id your_user

示例输出：

text
uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

Docker Mods

https://img.shields.io/badge/dynamic/yaml?color=94398d&labelColor=555555&logoColor=ffffff&style=for-the-badge&label=tvheadend&query=%24.mods%5B%27tvheadend%27%5D.mod_count&url=https%3A%2F%2Fraw.githubusercontent.com%2Flinuxserver%2Fdocker-mods%2Fmaster%2Fmod-list.yml]([] https://img.shields.io/badge/dynamic/yaml?color=94398d&labelColor=555555&logoColor=ffffff&style=for-the-badge&label=universal&query=%24.mods%5B%27universal%27%5D.mod_count&url=https%3A%2F%2Fraw.githubusercontent.com%2Flinuxserver%2Fdocker-mods%2Fmaster%2Fmod-list.yml]([]

通过 https://github.com/linuxserver/docker-mods 扩展容器功能，上述徽章链接可查看可用Mods。

支持信息

• 容器运行中进入shell：

  bash
  docker exec -it tvheadend /bin/bash
  

• 实时查看容器日志：

  bash
  docker logs -f tvheadend
  

• 查看容器版本：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' tvheadend
  

• 查看镜像版本：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/tvheadend:latest
  

更新信息

通过Docker Compose

• 更新镜像：

  bash
  # 所有镜像
  docker-compose pull
  # 单个镜像
  docker-compose pull tvheadend
  

• 更新容器：

  bash
  # 所有容器
  docker-compose up -d
  # 单个容器
  docker-compose up -d tvheadend
  

• 清理旧镜像：

  bash
  docker image prune
  

通过Docker Run

• 更新镜像：

  bash
  docker pull lscr.io/linuxserver/tvheadend:latest
  

• 停止并删除容器：

  bash
  docker stop tvheadend
  docker rm tvheadend
  

• 使用原参数重新创建容器（配置文件通过卷映射保留）
• 清理旧镜像：

  bash
  docker image prune
  

通过Watchtower自动更新（仅推荐用于忘记原始参数时）

bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once tvheadend

清理旧镜像：docker image prune

警告：不建议使用Watchtower作为容器自动更新工具，长期推荐使用 Docker Compose。

镜像更新通知 - Diun

推荐使用 Diun 接收更新通知，不建议使用自动更新容器的工具。

本地构建

bash
git clone https://github.com/linuxserver/docker-tvheadend.git
cd docker-tvheadend
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/tvheadend:latest .

在x86_64硬件上构建ARM变体需使用 multiarch/qemu-user-static：

bash
docker run --rm --privileged multiarch/qemu-user-static:register --reset

然后使用 -f Dockerfile.aarch64 指定架构Dockerfile。

版本历史

• 20.09.23: 添加perl-json-xs包
• 18.05.23: 从Alpine仓库安装XMLTV
• 18.05.23: 基于Alpine 3.18重建
• 17.03.23: 构建时提取picons而非初始化时
• 23.02.23: 基于Alpine 3.17重建，迁移至s6v3，移除armhf支持
• 31.08.22: 更新示例环境变量和RUN_OPTS处理方式
• 19.08.22: 切换到新的picons构建器
• 16.04.22: 添加URL XMLTV抓取器
• 05.01.22: 基于Alpine 3.15重建，禁用execinfo修复构建，更新xmltv
• 11.05.21: 添加Intel iHD驱动支持
• 02.06.20: 更新至Alpine 3.12
• 27.12.19: 添加requests和perl-json-xs包
• 27.12.19: 更新至Alpine 3.11
• 02.10.19: 改进render和dvb设备权限修复
• 18.08.19: 添加AMD驱动
• 02.08.19: 尝试自动修复/dev/dri和/dev/dvb权限
• 28.06.19: 基于Alpine 3.10重建
• 27.03.19: 基于Alpine 3.9重建，修复初始化逻辑仅执行一次chown
• 23.03.19: 切换到新基础镜像，迁移至arm32v7标签
• 01.03.19: 升级xmltv至0.6.1
• 28.02.19: 添加perl-lwp-useragent-determined
• 17.02.19: 升级xmltv至5.70，通过克隆tvheadend确保版本标签工作
• 14.02.19: 添加picons路径到配置
• 15.01.19: 添加流水线逻辑和多架构支持
• 12.09.18: 基于Alpine 3.8重建，使用buildstage类型构建
• 21.04.18: 添加JSON::XS Perl包用于grab_tv_huro
• 24.03.18: 添加dvbcsa包
• 04.03.18: 使用sourceforge master而非镜像获取xmltv
• 22.02.18: 添加丢失的libva-intel-driver
• 21.02.18: 修复错误的iconv版本
• 18.02.18: 添加vaapi支持，清理并移除已弃用选项
• 04.01.18: 弃用cpu_core例程（缺乏扩展性）
• 11.12.17: 基于Alpine 3.7重建，修复代码规范
• 02.09.17: 添加编解码器依赖
• 13.07.17: 提高所有架构的一致性
• 08.07.17: 更新README中的comskip完整路径
• 02.07.17: 所有4.2版本使用一个分支
• 27.05.17: 基于Alpine 3.6重建
• 01.05.17: 更新至tvheadend 4.2.1稳定版
• 18.04.17: 使用仓库版本的gnu-libiconv而非编译
• 09.04.17: 合并cpanm安装为一个块并使用--installdeps
• 09.02.17: Perl更改，添加picons文件到gitignore，更新XMLTV至0.5.69
• 07.02.17: 添加变量以支持额外运行参数
• 05.02.17: 更新至Alpine 3.5，修改dvb-apps仅编译所需库
• 14.11.16: 从picons.xyz添加picons到/picons文件夹并更新README
• 22.09.16: 修复损坏的tv_grab_wg，添加xmltv依赖，更新README
• 18.09.16: 更新XMLTV至0.5.68并更新README
• 10.09.16: 添加图层徽章到