TVBox 单仓和多仓接口是什么？EPG 节目单怎么获取和自建

CHAPTER 8单仓与多仓

8.1一句话说清

单仓是一个配置文件，多仓是一个「配置文件的目录」。

它们都是 JSON，区别只在于最外层长得不一样。

8.2为什么要有多仓这种设计

说白了是血的教训换来的。

早期的玩法是单仓，一个地址给你一整套内容。问题是这类配置的制造者大多是个人，服务器是个人租的，域名可能没备案，还可能被人举报。今天能用，明天打不开，太正常了。用户每次都要重新找人要地址，体验极差。

多仓把这个问题分开处理了：「在哪找仓」和「仓里有什么」变成两件事。你拿到的多仓地址（俗称「仓源」）通常是一个稳定性较高、维护得比较好的入口，它本身只存一份很小的清单。真正的内容仓可能是几十个人各自维护的，挂一个不影响其他。你只需要在软件里切一下。

8.3接口地址这件事：我给不了你一份清单

你会反复听到几个名字——某某多仓、某某接口，都是同一类东西。它们有个共同特征：名字都是维护者的网名，不是技术名词。所以你听到的其实是人名，不是软件名。

这份文档里不会出现这些地址。三个理由，都是实操层面的。

• 列出来立刻就是废纸。这类入口的寿命按月算，短的按周。一份「常用接口大全」抄进文档的那一刻就开始过期，半年后照着试一圈，能打开的那一两个还是巧合。写一屏地址，等于给你一屏死链。
• 写「哪个好」就等于替它背书。我列不出一份推荐清单，因为推荐意味着我逐个审过。我没有这个能力，也不该做这个动作。
• 最要紧的一条：配置里的 spider 字段可以指向一个可执行的 jar 包。这是这类软件架构上最危险的设计——你把一个接口地址填进去，等于允许这台设备下载并运行一段别人写的代码。名字叫得再响的仓，也可能在某次更新里带上不该带的东西。

所以这件事的判断权应该留在你自己手上，而不是被一份「推荐清单」替代。下面讲怎么自己看。

8.4这些接口都叫什么名字

地址我不给，但名字你得认得。你迟早会在论坛、群聊、短视频评论区反复看到几个词：饭太硬、摸鱼、南风、王二小、欧歌、肥猫。它们既不是软件名，也不是技术名词，就是维护者的网名——一个人给自己那份配置起的签名。念起来像玩笑，背后是具体的人在维护。你听到一个名字，其实听到的是一个人。

还有一条规律要先讲清楚：一个名字通常不只一条地址。你去看任何一份接口清单，同一个名字底下会挂着好几条，写法五花八门——有的换成另一个域名，有的是一串看不出规律的短链，有的干脆写成「2 线」「3 线」「备用」。它们指向的是同一份配置，只是入口不同。域名被举报、被运营商拦下、被污染，维护者就再换一个壳挂上去。所以看到「饭太硬 5 线」，别以为是五个不同的东西，那是同一个人为了让你还能打开所做的备份。

下面这张表列的是国内这套圈子里被念得最多的名字。我按用途分了类，也标了各自该留意的点。名字之外的信息——谁在更、还有几条线、今天能不能打开——都要你自己去现场看，因为那部分每天都在变。

名单里还有一个细节值得停下来看一眼。这类备份清单上，有些文件名后面会直接跟两个字——「已死」。集多已死、小米以死、肥猫已死，都是这么写的。这不是骂人，是整理者在替你插碑：那条已经不用试了。圈子里管接口失效叫「死」，于是一份接口清单看得久了，会像一片墓碑。这件事本身就是这套玩法的底色：任何一份「最新接口大全」的有效期都很短。所以你手上这张表也一样，它的用处是让你认名字，不是让你照抄。名字能活很久，地址活不久。

真正要练的动作只有三个。第一，按名字去搜，别搜「TVBox 接口大全」这种标题——那种页面互相抄，谁也不知道是哪年的——直接搜名字加「接口」两个字，能翻到最近几天还在更新的备份清单。第二，看两个信号：清单上标的更新日期是不是这两天，同一个名字下面还挂着几条线，线路数量多说明维护者还在管。第三，至少准备三条互不重叠的，其中一条挂了不影响你看电视。至于那些让你发红包领接口、进群买「独家源」的，一律不用碰——这类接口本身就是免费的，收费的那一头只是二道贩子。

风险还是那句话，说在前面。接口里的内容大多是爬来的，版权上站不住，这也是这类聚合被一批批清理的原因。它们还可能夹带来路不明的弹窗、跳转和强制内置播放器，极端情况下甚至会带上可执行的规则文件——前面讲 spider 那一节说的就是这个。自己用、别传播、别拿去卖，是这个圈子里最起码的一条线。

8.5拿到一个接口，怎么判断值不值得配

接口就是一份 JSON，可读性很好。下载下来用记事本打开，看这几个地方就够了。

还有一条经验：接口文件本身很小，几十 KB，下载快、不占地。所以「多备几个轮着切」的成本极低。在一个接口上反复折腾，不如同时装上三四个。这也是多仓这种设计存在的意义。

8.6与其抄一个，不如自己拼一个

如果你的用法其实很简单——只看直播、不看点播——那你完全可以不用别人的仓。TVBox 的最小可用配置只有三个字段：

{
  "sites": [],
  "parses": [],
  "lives": [
    {
      "name": "我的直播",
      "type": 0,
      "url": "https://你的域名/mylive.m3u",
      "epg": "http://epg.51zmt.top:8000/e.xml"
    }
  ]
}

三个字段的意思分别是：sites 是点播站点，不看点播就留空数组；parses 是解析接口，没有点播同样不需要；lives 是直播源，这里的 url 可以直接指向你自己维护的一份 m3u，epg 就是节目单地址。

把这份 JSON 传到任意一个能被公网访问的地方——对象存储、GitHub Pages 都行——再把地址填进软件，你就得到了一个不依赖任何人维护的仓。它的寿命只取决于你自己的源能活多久。

CHAPTER 9EPG 节目单

9.1它解决的问题：你根本不知道现在在播什么

想象你打开电视，频道列表里写着「CCTV-5 体育」。你点进去，画面是乒乓球的中间一段，你不知道这是第几局，也不知道下一场什么时候开始。这就是没有 EPG 的世界。

EPG 全称 Electronic Program Guide，电子节目指南。它是一份独立于视频流的数据文件，内容就是「哪个台、什么时间、播什么、简介是什么」。有了它，软件才能画出那种电视报一样的节目表，把你正在看的节目名字标出来，甚至提醒你「30 分钟后有球赛」。

9.2EPG 文件的格式：XMLTV

主流格式叫 XMLTV，就是一个 XML 文件。为了省流量，通常还会 gzip 压缩一下，所以你会看到 .xml.gz 结尾的地址。结构很简单，只有两大块。

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="某EPG项目">

  <!-- 第一块：声明有哪些频道 -->
  <channel id="CCTV1.cn">
    <display-name lang="zh">CCTV-1</display-name>
    <icon src="https://.../cctv1.png"/>
  </channel>

  <!-- 第二块：声明每个频道在什么时间播什么 -->
  <programme start="20261002080000 +0800"
             stop="20261002090000 +0800"
             channel="CCTV1.cn">
    <title lang="zh">朝闻天下</title>
    <desc lang="zh">早间新闻资讯节目</desc>
  </programme>

</tv>

两个细节值得注意。

• 时间格式是 20261002080000 +0800，也就是「年月日时分秒 + 时区偏移」。时区那个 +0800 特别关键，写成别的值整个节目表就错位几小时。这也是为什么有的 EPG 看起来「时间对不上」。
• channel 里的 id 必须和 m3u 里的 tvg-id 一模一样，一个字母都不能差。差一个字符，匹配就失败，那一栏节目表就是空的。

9.3匹配是怎么发生的

9.4为什么 EPG 老是出问题

实际用下来，EPG 是整套系统里最不稳定的部分，原因有这么几个。

还有一点要说清楚：台标和 EPG 是两回事。台标（tvg-logo）指向的是一张图片，EPG 指向的是一份节目数据。有人把两者混为一谈，结果折腾半天台标出来了、节目单还是空的，因为这两件事根本走的不是一套数据。

9.5现成的 EPG 源：我把手上能试的都试了一遍

先给结论：国内台用 51zmt 一个基本就够；要看港澳台和境外，再加一个 epg.pw。其余的都是备胎。下面这份清单我在 2026 年 10 月逐条跑过，「实测」那一栏写的是真实结果，不是抄来的宣传语。

9.6别把这份清单当成永久地址

EPG 源是这套体系里寿命最短的一环，比直播源还不如。原因很简单：它跑在个人服务器上，没有收入，靠爱发电。维护者毕业了、服务器到期了、流量费超了，说停就停。

所以更实用的姿势不是「记住一个地址」，而是记住这一类的现状：能用的就那么几个，而且经常是整体性波动——某一年一批全挂，过一阵子又冒出来几个新的。碰上打不开，第一件事是换一个，而不是怀疑自己的软件坏了。

9.7没有现成 EPG 怎么办

老实说，能做的不多。EPG 这东西的价值在于「覆盖多少台、更新多勤」，这是靠人力维护出来的，个人很难自己造。常见做法是找个维护得好的公开 EPG 项目（社区里长期有人在更新这类项目），把地址填进配置里。如果你只关心几个台，也可以手工写一份小 XMLTV，把自己常看的十几个台排进去——工作量不大，但数据和你的频道列表能保证完全对齐，反而比大而全的源更准。

9.8一个被忽略的玩法：{date} 和 {name}

上面那个「手工写十几个台」的思路，其实可以机械化。TVBox 的 EPG 地址支持两个占位符，会在实际请求的时候自动替换成真实值。

你填进软件的是这个：
https://你的域名/epg/51zmt/{date}/{name}.json

正在看 CCTV1 的时候，TVBox 实际请求的是：
https://你的域名/epg/51zmt/2026-10-02/CCTV1.json

这一下就把事情说通了：EPG 不需要是一个「服务」，它可以只是一堆静态文件。你只要提前把每个频道、每天的数据拆成一个个小 JSON 放在能被访问到的地方，TVBox 就会自己去取对应的那一个。

之所以能这么干，是因为 TVBox 需要的 JSON 比 XMLTV 还简单——一个频道一份、按天分好：

{
  "channel": "CCTV1",
  "epg_data": [
    { "start": "06:00", "end": "06:30", "title": "朝闻天下" },
    { "start": "19:00", "end": "19:30", "title": "新闻联播" }
  ]
}

9.9零成本自己搭一套

顺着上面的思路，整件事可以全部自动化，不花一分钱，也不需要服务器：

1. 取数据。上游还是那几个公开的 XMLTV 源，挑一个更新勤的——老张的 EPG 按天重新生成，适合做数据源。
2. 拆文件。写个脚本把大 XML 按「日期 + 频道」拆成小 JSON，路径就照着 {date}/{name}.json 的规则来。
3. 扔出去。放进 Cloudflare Pages 这类静态托管。免费套餐没有流量和请求次数限制，不用续费，也不用管进程会不会挂。
4. 接上自动化。用 GitHub Actions 定时（比如每两小时）跑一遍上面的流程，重新生成、重新部署，数据就一直是新的。

已经有人把这套做成了开源项目，fork 一份、关联到自己的 Cloudflare Pages 就能用，不需要自己写代码。想完全掌控的话脚本本身也不复杂——本质就是「解析 XML、按规则写文件」两步。

9.10IPTV工具箱：把 EPG、直播源、台标放进同一个后台

上一节讲的是「怎么自己造一套 EPG」。但只要你手上的台不止几十个、或者有好几台设备都要用同一套节目单，自己写脚本就会开始撑不住——节目单对不上频道名要改、源换了要重新测、台标挂了一批要重找，三件事散在三个地方做，坚持不了几轮就放弃了。

这一节讲的项目，就是把这三件事收进一个后台。先说清楚它是什么，因为「IPTV工具箱」这个名字在圈里的歧义不小：它是一个开源的网页后台，GitHub 上的仓库是 taksssss/iptv-tool（中间那串 s 别数错），作者是恩山论坛的 TakSSS，2024 年 7 月发的第一版，到现在 star 一千一百多。它不是装到电视上的 App，而是跑在服务器上、用浏览器访问的一套东西。

部署就一行命令，改两个地方就能跑：

docker run -d --name php-epg \
  -p 5678:80 \
  -v $HOME/epg:/htdocs/data \
  -e PHP_MEMORY_LIMIT=512M \
  --restart unless-stopped \
  taksss/php-epg:latest

容器名还叫 php-epg、镜像名也是 taksss/php-epg，这是它早期叫「PHP-EPG-Docker-Server」时留下的名字，项目后来改了名，镜像名没跟着改——两个名字指的是同一个东西，不用怀疑自己找错了。拉不动可以换腾讯云的镜像地址，或者直接用作者的一键部署脚本（脚本、Gitee 镜像、jsDelivr 加速三种源都给备着了，这一点做得比多数国产项目厚道）。

跑起来之后，浏览器打开 http://服务器IP:5678/manage.php，首页就是这张：

9.10.1它到底管了哪三件事

第一件是 EPG。你可以同时填好几个 XMLTV 源，它按顺序拉、合并、去重，然后按你设的时间表定时更新。真正省事的是「频道别名」那一格：不同源的频道名写法天差地别——「CCTV1 综合」「CCTV-1」「CCTV1 高清」，写成一个名字，它才认得这是同一个台。别名支持正则表达式，一行规则就能把一堆变体收拢成一种写法。配好之后，它对外能同时吐出三种节目单格式（DIYP/百川、超级直播、标准 xmltv），还额外给了一个 tvbox 用的接口写法。同一套数据，不同的播放器各取各的格式，你不用为每个软件准备一份。

第二件是直播源。这块是后来长出来的，现在反而是最重的一块。你把本地 txt 或 m3u 文件传上去、或者贴一个网上的源地址，它能解析、聚合、按规则重排分组，然后给你一个带 token 的订阅地址——播放器里填这个地址，而不是填原源地址。它还带测速校验：批量跑一遍，能连上但拉不动的直接标掉、按响应速度排序，也可以设成测出无效就自动停用。源后面还能挂一长串参数，用 # 开头写在地址后面，比如 #UA= 换请求头、#PF= 加分组前缀、#FT= 做频道黑白名单、#PROXY= 走代理、#T2S=1 把繁体频道名转简体。这些选项的意义不在炫技，在于把「播放器端配置」搬到了「服务端配置」——见下一节那张图。

第三件是台标。它可以把在线台标整批转存到你自己服务器上，存成 /data/icon/频道名.png 这种路径，播放器直接从这个路径取图。这件事看起来小，实际解决的是个老大难：台标图床被墙、被防盗链、突然挂掉，都会让你列表里满屏白框。存到本地就一劳永逸了，顺便还能自己上传替换不满意的。

三件事之外还有几个零碎但顺手的东西：访问日志（哪个台被点得最多，一目了然）、IP 归属地、消息通知（接 Server 酱，抓取失败会推你一条）、以及容器层面的一堆开关——ENABLE_IPV6、ENABLE_HTTPS、ENABLE_FFMPEG（要测速就得开）、PHP_MEMORY_LIMIT。

9.10.2它真正改变了什么

上面那一堆功能，如果只理解成「功能多」，就白看了。它真正改的是一个结构问题：没有它的时候，源、节目单、台标这三样东西要在每一台设备上各配一遍；有了它，这三样只在服务端配一次，设备端只填一个地址。

9.10.3新版比老版强在哪

这个项目从 2024 年 7 月活到现在，两年多。把最近一年（2025 年底到 2026 年 8 月）的更新日志翻下来，真正影响使用体验的是这么几件事：

换掉了 Web 服务器。2025 年 11 月从 Apache 迁到 nginx。这是个典型的「用户看不见但能感觉到」的改动——同时打开管理页面和拉取数据的时候，老版本容易卡住甚至白屏，新版本基本没这个问题。

直播源管理从「能用」变成「主力」。测速校验、测速过滤、按速度排序、代理访问、直播源模板、分组别名、线路备注、以及「适应动态地址」（源地址天天在变时，只按分组加频道名记住你的修改，不被地址变化冲掉）。这几项凑齐之后，这个项目才算真的能承担「日常维护一份列表」这件事。

和酷9 做了深度对接。这一条对国内用户最实用：它能识别并解析源文件里带的酷9 配置（#EXTKU9OPT 那一串），还支持生成酷9 需要的二级分组。也就是说，你在第 7 章学的那个酷9，和这里管的源是能对上的，不是各玩各的。

几个容易被忽略但很提气的细节。IP 归属地本地化存储和显示（不用每次联网查）、访问日志与访问统计、消息通知接 Server 酱（抓取失败了手机能收到）、以及 ENABLE_IPV6 这类开关终于补齐。

至于「优点」，我给一句我自己的判断：它最大的优点不是功能多，而是它输出的是「地址」而不是「文件」。你改什么都在服务端改，改完域名后面那串地址还是那个地址，设备端一个字都不用动。同类的单机工具（比如第 2 章讲的那些测源工具箱）解决的是「我这台电脑上把源洗干净」；它解决的是「洗完之后的源，怎么让全家所有屏幕都吃到」。这是两个层次的问题，不冲突。

最后提醒一句同名问题。恩山和网上还飘着几个名字几乎一样的工具——比如另一位作者发的「IPTV 工具 v2.0」，那是个纯本地跑、自带 SQLite 数据库、连 Redis 和 MySQL 都不依赖的单机版；还有一类叫「IPTV 直播源全能工具箱」的 Windows 桌面软件，主做的是扫酒店源、扫组播、验代理。它们和你这一节看到的「网页后台 + Docker 镜像」是三种完全不同的东西，只是因为名字里都有「IPTV」和「工具箱」才撞在一起。看到界面和这张图长得不一样，那就不是它。