Data Sources

数据源

数据源是上位概念，包含两类相互独立的体系：

类别	说明	管理入口
点播源	Apple CMS 采集站 API，决定"能搜到什么"（本文主体）	设置 → 源管理 → 点播源
直播源	M3U 播放列表，用于 /live 页看电视	设置 → 源管理 → 直播源（见 Live-IPTV）

两者数据模型独立，但可以用一份订阅 JSON 同时下发（见数据源订阅 / 分享）。订阅地址同时兼容 LibreTV-SourceList JSON 与 TVBOX 配置，由服务端自动识别格式。

LibreTV 采用空壳设计：不内置任何采集站与频道源，由部署者/用户自行添加，避免内置源失效与合规风险。

首页的推荐源（豆瓣 / Bangumi / 影视榜单）是另一套独立配置，只决定首页展示什么，与点播源无关，见 Recommendations。

点播源有三种来源：

• 部署者预置：通过 DEFAULT_SOURCES 环境变量下发（JSON 数组），所有用户开箱即搜，详见配置文档；
• 用户自建：设置 → 源管理 → 点播源 → 「+ 添加 API」手动添加，保存在浏览器 localStorage；
• 订阅导入：设置 → 源管理 → 数据源订阅，一次可同时导入点播源与直播源（订阅地址兼容 LibreTV 源列表与 TVBOX 配置）。

支持的点播源类型

Apple CMS（苹果CMS）标准采集接口，即提供以下接口的资源站：

搜索：{api}?ac=videolist&wd={关键词}
详情：{api}?ac=videolist&ids={vod_id}

添加点播源

设置 → 源管理 → 点播源 → 「+ 添加 API」：

字段	必填	说明
名称	是	显示用名称
API 地址	是	形如 https://example.com/api.php/provide/vod，结尾 / 会自动去除
详情页地址	否	形如 https://example.com；部分源列表接口不返回播放地址，需要爬取详情页 HTML 提取 m3u8
成人标记	否	标记后受「成人内容过滤」开关控制

添加后默认自动勾选参与搜索。

详情页爬取（特殊源）

当标准详情接口拿不到播放地址时，服务端自动降级：

1. 请求 {detail}/index.php/vod/detail/id/{id}.html；
2. 通用正则提取 \$https://...m3u8；
3. 若无结果，尝试非凡影视特征路径模式（/日期/哈希/index.m3u8）；
4. 去重后作为剧集列表。

服务端聚合行为

• 所有勾选的源并行搜索；单页请求 8 秒超时，每个源另有 10 秒总死线（SEARCH_SOURCE_TIMEOUT_MS 可调），到点中断该源并标记「超时」；
• 首页搜索走流式接口：每个源结算后结果立即推送到前端渲染，健康源不必等坏源超时；服务端聚合完成后仍以统一结果为准；
• 任一源失败不影响整体，失败源在结果区顶部以名称列出，超时（⏱）与失败（✗）区分标识；
• 结果按「源内去重（sourceKey+vodId）→ 名称排序（zh-CN）」合并；
• 部分源站无结果时返回 list: null（而非空数组），服务端按空结果兼容处理；
• 成人过滤在服务端执行，关键词包括：伦理片、福利、里番动漫、无码、SWAG 等。

源可用性测试与自动停用

两层机制互不替代：

⚡ 手动探活（设置 → 源管理 → 点播源，每个源右侧）

• 以搜索 test 的完整往返衡量：返回响应耗时（ms）与结果条数；
• 结果以徽章内联展示（✓ 610ms 绿色 / ✗ 超时 红色）；探活结果同样写入健康度记录，与真实搜索共用同一份数据，因此会持久化、不会刷新即失；
• 批量测活：工具栏的「⚡ 测活」可一次测完当前筛选出的全部源，带实时进度与「取消」按钮；
• 探活请求与搜索一样经过 SSRF 校验，仅支持公网 http(s) 地址。

健康度记录与自动停用（随真实搜索自动进行，持久化保存）

• 每次搜索按源记录结果与耗时，设置 → 源管理 → 点播源中常驻显示（绿色 ✓ Xms = 上次搜索耗时）；

• 同一源连续 2 次失败或超时即暂停参与搜索，停用时长按「第几次被停用」逐级加重：

  第几次被停用	停用时长	恢复方式
  第 1 次	30 分钟	到期自动
  第 2 次	24 小时	到期自动
  第 3 次及以后	长期停用	需手动（设置中的「恢复」按钮）

• 每成功一次降一级（而非清零）：偶尔抽风的源会自行回落并停在 30 分钟档，只有从未成功过的源才会一路升到长期停用；

• 全程勾选状态保留——只是暂停参与搜索，不改动你的勾选意图；

• 停用期间首页结果区显示提示条，设置中该源显示琥珀色「已停用」徽章（长期停用为红色），可点「恢复」立即清除记录重新参与；

• 超过 7 天未再参与搜索的源，其健康度记录与惩罚等级一并作废，不会因陈旧记录被长期重罚；

• 目的：坏源不再拖慢每次搜索，也不必手动排查剔除。之所以做成阶梯而不是固定时长——固定 30 分钟时，一个彻底挂掉的源会每隔半小时被重新试一次，每次都要白等一轮超时。

数据源订阅 / 分享

一份订阅可同时下发点播源与直播源：导出为 JSON 文件 → 托管到任意公开 URL → 他人在「设置 → 源管理 → 数据源订阅」里填入该 URL 订阅。

订阅格式（LibreTV-SourceList JSON）

{
  "name": "我的源列表",
  "version": 2,
  "sources": [
    {
      "name": "示例点播源",
      "url": "https://bfzyapi.com/api.php/provide/vod",
      "detail": "https://bfzyapi.com",
      "isAdult": false
    }
  ],
  "liveSources": [
    {
      "name": "示例直播源",
      "url": "https://example.com/list.m3u",
      "epg": "https://example.com/epg.xml.gz"
    }
  ]
}

字段说明：

字段	位置	类型	必填	说明
name	顶层	string	否	列表名称，订阅后显示在订阅条目上；缺省时显示订阅地址主机名
version	顶层	number	否	格式版本，当前为 2（新增 liveSources）；导入端目前忽略该字段
sources	顶层	array	否	点播源数组，最多 100 个，超出部分截断
sources[].name	项	string	否	源显示名；缺省时使用 URL 主机名
sources[].url	项	string	是	Apple CMS 采集接口地址（公网 http/https），结尾 / 自动去除
sources[].detail	项	string	否	详情页根地址，用于列表接口拿不到播放地址的源
sources[].isAdult	项	boolean	否	成人内容标记，默认 false；受「成人内容过滤」开关控制
liveSources	顶层	array	否	直播源数组，最多 50 个，超出部分截断
liveSources[].name	项	string	否	源显示名；缺省时使用 URL 主机名
liveSources[].url	项	string	是	M3U 播放列表地址（http/https）
liveSources[].epg	项	string	否	XMLTV 节目单地址（xml / xml.gz），用于 /live 页展示节目单

兼容与限制：

• 只写 sources 的老订阅（含 version: 1）照常可用，等同于纯点播订阅；只写 liveSources 则为纯直播订阅；两者都缺时提示"订阅内容格式不正确"；
• 也接受裸数组格式 [{ "name": "...", "url": "..." }, ...]（视为点播源，列表名显示为主机名）；
• 按 url 去重（先到先得）；非 http(s) 地址会被过滤；点播源另需为公网地址（内网/回环/保留地址会被静默过滤），直播源在部署者设置 LIVE_ALLOW_PRIVATE=1 时可使用内网地址；
• 直播源的 EPG 地址同样按上述规则校验，非法时只丢弃该字段、保留整条源；
• 订阅由服务端拉取（拉取前经过 SSRF 校验），因此订阅地址无需配置 CORS，Gist、对象存储、任意静态托管均可。

兼容 TVBOX 配置

订阅地址也可以直接填 TVBOX 配置（形如 {"sites": [...], "lives": [...], "parses": [...], "spider": "..."}），服务端按内容结构自动识别格式，无需手动选择。

TVBOX 字段	是否导入	说明
sites[] 中 type: 1 的条目	✅	Apple CMS JSON 接口，转为点播源
sites[] 省略 type / 写成 0，但地址含 api.php/provide/vod	✅	共享配置常省略类型，按地址宽容识别（/at/xml 等 XML 通道除外）
sites[] 标记 searchable: 0	❌	站点自身不提供搜索，本站只有搜索入口
sites[] 的 type: 3 Spider（csp_* / .jar / .js / .py）	❌	需要 TVBOX 的 Spider 引擎，Node 侧无法运行
sites[] 的 XML 接口与普通外链 JSON	❌	本站只解析 Apple CMS JSON 接口
lives[] 中 type: 0（或省略）的 M3U 地址	✅	转为直播源，epg 字段一并导入
lives[] 的 txt 频道列表与单仓 JSON	❌	本站直播只支持 M3U
顶层 parses / spider / wallpaper 等	❌	与本站能力无关，忽略

• 导入结果会如实提示：如「已同步 8 个点播源、2 个直播源（TVBOX 配置）；跳过 96 个不可用条目（Spider 引擎 92、XML 接口 4）」——TVBOX 配置常含上百条站点且以 Spider 为主，只导入个位数到十几个属正常现象；
• 地址校验（点播源须为公网地址）、按 url 去重、数量上限（点播 100 / 直播 50）与 LibreTV-SourceList 完全一致，被服务端校验拦下的条目同样计入「跳过」；
• 格式容错：配置里的 // 注释、尾随逗号、字符串内未转义的换行会自动修正后再解析（共享配置中很常见，TVBOX 客户端用的 fastjson 同样容忍这些写法）；
• 订阅地址需直接返回 JSON：Base64 / 压缩包装的分享链接不支持；TVBOX「多仓」配置（顶层为 urls 数组）也不支持，请填单仓配置（sites / lives）。

订阅行为

• 导入：设置 → 源管理 → 数据源订阅 → 填入订阅地址 → 「订阅」；点播源自动勾选（成人过滤开启时跳过成人源）、直播源自动启用，两者都带「订阅」标识；订阅条目上显示「点播 N · 直播 M」计数与上次同步时间；
• 部署者预置订阅：通过 DEFAULT_SUBSCRIPTIONS 环境变量填入订阅链接，用户首次访问自动完成导入，超 24 小时静默刷新，失败保留旧数据下次重试，详见 Configuration · 预置数据源订阅；
• 手动同步：订阅条目上的 ⟳ 随时强制同步——整体替换该订阅名下的点播源与直播源（与订阅 URL 相同的手动源会被去重合并），结果以提示反馈（如"已同步 8 个点播源、3 个直播源"）；
• 整体启用 / 停用：每条订阅左侧的开关可临时停用它——停用后该订阅下的源不再参与搜索，但不改动任何源的勾选状态、也不删除数据，重新打开即完全恢复。停用期间该条目淡显并显示「已停用」徽章，点播源列表中它的源显示「订阅已停用」，搜索结果区也会说明有几个源因此未参与（不做静默过滤）；
• 订阅源的管理边界：订阅源以远端列表为准——单独编辑会在下次同步时被覆盖，单独移除会在重新同步时恢复；如需调整请修改远端列表后同步、或用上面的开关整体停用，或直接删除整个订阅；
• 删除订阅：点播源随订阅全部移除；直播源为多归属共享——同一 M3U 可被多个订阅引用（各订阅的「直播 N」计数按归属统计，名称/EPG 以首次导入为准），删除订阅只移除自己的引用，仅当不再被任何订阅引用时才移除该直播源（含启用状态与最近观看记录），收藏的频道始终保留；

分享（导出 / 发布链接）

两种方式，区别在于「你手里拿到什么」：

导出 JSON 文件：设置 → 源管理 → 数据源订阅 → 「导出数据源」，把当前全部点播源与直播源（部署者预置 + 手动添加 + 订阅导入，按 URL 去重）导出为上述格式的 JSON 文件（version: 2）。托管到任意公开 URL 即可被他人订阅。

一键发布为订阅链接：同一处的「发布为链接」，把当前仅已勾选启用的源（未勾选的、以及被自动停用的都排除）上传到公开粘贴板，直接返回一个可填入订阅框的 URL——不需要自己准备托管。须知：

• 上传走服务端代理（浏览器直连会被 CORS 拦住），目标域名固定为 paste.rs，失败时自动降级到 0x0.st；接口只透出白名单字段（名称/地址/EPG）并限制条数与体积，且需要登录会话；
• 内容是公开可读的——任何拿到链接的人都能看到你的源列表；
• 免费粘贴板可能随时清理或失效，且每次发布都会生成新链接（不支持覆盖更新），改完源需重新发布并替换订阅地址；
• 需要长期稳定请用「导出数据源」自行托管（Gist、对象存储、私有仓库 raw 均可）。

发布成功后会显示链接，可直接「复制」或点「直接订阅」（自动填入订阅框并立即同步）自测。

点播源配置的数据流

点播源配置只保存在用户浏览器（localStorage），服务端不存储。每次搜索/详情请求会把用到的源配置随请求上传，因此：

• 同一部署的不同用户可以有不同的点播源集合；
• 分享播放链接时 URL 会携带 sourceUrl 参数，接收者即使未配置同名的源也能播放（见 Player）。

常见问题

Q: 添加源后搜索无结果？ 用浏览器直接访问 {api}?ac=videolist&wd=test 验证是否返回 JSON。部分源校验 Referer/UA 或已停更。

Q: 搜索成功但详情提示"未找到播放资源"？ 该源的播放地址可能需要详情页爬取，请补填「详情页地址」；或该影片在源内本身无 m3u8 地址。

Q: 可以批量导入吗？ 可以：把点播源（必要时连同直播源）写成一份 LibreTV-SourceList JSON 并托管，在「设置 → 源管理 → 数据源订阅」中填入地址即可一次导入，之后还能一键同步。旧版逗号分隔 ?urls= 的入口未移植，也可用「导出/导入配置」整机迁移。

Q: 填入 TVBOX 配置后，为什么只导入了几个源？ TVBOX 配置里绝大多数站点是 type: 3 的 Spider（csp_* / jar / js / py），需要 TVBOX 自身的 Spider 引擎才能运行；本站只导入可直接访问的直连接口（type: 1 的 Apple CMS）与 M3U 直播源，其余条目会在导入结果中按原因计数提示，属预期行为。详见兼容 TVBOX 配置。