配置

环境变量

旧版的 CORS_ORIGIN、CACHE_MAX_AGE、BLOCKED_HOSTS、BLOCKED_IP_PREFIXES、FILTERED_HEADERS 在重构版中已内化为安全默认值，不再需要配置。

预置采集站（DEFAULT_SOURCES）

部署者可通过环境变量为所有用户预置点播源，用户无需手动添加即可搜索：

DEFAULT_SOURCES=[{"name":"示例源","url":"https://example.com/api.php/provide/vod","detail":"https://example.com","isAdult":false}]

• 格式为 JSON 数组，每项支持 name（必填）、url（必填，http/https）、detail（可选详情页地址）、isAdult（可选成人标记）；
• 解析失败会在服务端日志告警并整体忽略，不影响站点运行，最多生效 50 个（与搜索接口上限一致）；
• 预置源由服务端经 /api/status 下发，展示在设置抽屉顶部并带「部署者预置」标记，用户可勾选/取消但不可编辑或删除；
• 预置源首次出现时自动勾选（开箱即搜）；用户取消勾选后刷新页面不会被反复勾回；
• 预置源不参与用户侧的配置导出（导出文件只含用户自建源），部署者变更环境变量即可全站生效。

预置直播源（DEFAULT_LIVE_SOURCES）

为所有用户预置直播（M3U 订阅）源，格式与行为对齐 DEFAULT_SOURCES：

DEFAULT_LIVE_SOURCES=[{"name":"示例直播源","url":"https://example.com/list.m3u","epg":"https://example.com/epg.xml.gz"}]

• 每项支持 name（必填）、url（必填，M3U 订阅地址）、epg（可选 XMLTV 节目单地址）；
• 经 /api/status 下发，展示在设置 → 源管理 → 直播源顶部并带「部署者预置」标记，用户可勾选启用/停用但不可编辑或删除；
• 首次出现时自动启用；用户停用后不会被反复勾回；
• 解析失败告警并整体忽略。功能详见 Live-IPTV。

预置数据源订阅（DEFAULT_SUBSCRIPTIONS）

部署者无需把源列表内联进环境变量，只填 LibreTV-SourceList JSON 链接即可，首次访问自动为所有用户导入点播源与直播源（也接受 TVBOX 配置地址，见 Data-Sources · 兼容 TVBOX 配置）：

DEFAULT_SUBSCRIPTIONS=["https://example.com/sources.json",{"url":"https://example.com/other.json","name":"备用清单"}]

• 数组元素为订阅 URL 字符串，或 {url, name} 对象（name 作为订阅条目显示名，可选）；
• 自动导入走与手动订阅完全相同的流程：点播源默认勾选（成人过滤开启时跳过成人源）、直播源自动启用，均带「订阅」标识；
• 同步时机：首次自动导入后，超过 24 小时未同步的预置订阅会在启动阶段静默刷新一次；也可随时在设置中手动同步（⟳）；
• 失败回退：拉取失败时保留上次成功导入的数据，下次启动自动重试，不影响站点运行；
• 用户删除：同步成功过的预置订阅被用户删除后，不会被自动加回；从未同步成功的则会持续重试直至成功；
• 远端清单由部署者自行托管（gist / 私有仓库 raw 均可），更新源列表无需修改容器配置或重启。

首页推荐数据源默认值（DEFAULT_RECOMMEND_SOURCE）

首页「推荐」区支持豆瓣热门、Bangumi 新番放送、影视热榜三种数据源，用户的选择保存在浏览器本地，出厂默认为影视热榜。部署者可通过该变量为所有用户指定默认项（对应 issue #918 的场景：换浏览器、清缓存或无痕模式下不再回落到热榜）：

DEFAULT_RECOMMEND_SOURCE=douban

• 可选值：douban（豆瓣热门）/ bangumi（Bangumi 每日放送）/ hot-list（影视热榜）；取值非法时告警并忽略，不影响站点运行；
• 仅对未主动选择过的用户生效：用户一旦在设置中主动选择过推荐数据源（或偏好已不是出厂默认值），部署者的默认值不再覆盖——用户的选择始终优先；
• 经 /api/status 下发，仅影响首页推荐区的初始展示，不影响其他功能。

封面图加载方式默认值（DEFAULT_IMAGE_MODE）

封面图加载方式（直连优先 / 内置代理 / 自定义代理）的用户选择保存在浏览器本地，出厂默认为直连优先。部署者可通过该变量为所有用户指定默认项：

DEFAULT_IMAGE_MODE=proxy

• 可选值：direct（直连优先，最省服务器流量）/ proxy（内置代理优先，最稳定，消耗服务器流量）；取值非法时告警并忽略，不影响站点运行；
• 不开放 custom：自定义代理模板是每用户手填的本地配置，没有全局模板可下发，强设 custom 只会让未填模板的用户静默退化为直连；
• 仅对未主动选择过的用户生效：用户一旦在设置中主动选择过加载方式（或偏好已不是出厂默认值），部署者的默认值不再覆盖——用户的选择始终优先；
• 经 /api/status 下发，仅影响封面图的初始加载方式；各方式的行为与降级链见下文 封面图加载方式。

运行时设置（用户级）

以下设置保存在每个用户浏览器的 localStorage（键 libretv-settings），通过「设置」抽屉修改：

点播源

• 自定义 API 列表：名称、API 地址、详情页地址（可选）、成人标记；顶部工具栏支持按名称/地址搜索、按来源与状态筛选（全部 / 已启用 / 已停用 / 来自订阅 / 手动添加），以及批量勾选；
• 勾选参与搜索的源：仅勾选的源会参与聚合搜索与换源，支持「全选 / 全部启用」等批量操作；
• ⚡ 批量测活：一次测活当前筛选出的全部源，带实时进度与「取消」；结果写入健康度，与真实搜索共用同一份数据；
• 删除：删除单个源后 6 秒内可「撤销」；删除订阅会级联清理其导入的源（有影响面提示与二次确认）；
• 健康度与自动停用：每次真实搜索会按源记录结果（耗时 / 超时 / 错误，持久化保存）。同一源连续 2 次失败或超时会被暂停参与搜索（勾选保留），停用时长按「第几次被停用」逐级加重：30 分钟 → 24 小时 → 长期停用（长期停用需手动恢复）；每成功一次降一级，因此偶发抽风的源会自行回落，只有从未成功过的源才会升到长期停用。期间首页结果区会显示停用提示，设置 → 源管理 → 点播源中该源显示琥珀色「已停用」徽章（长期停用为红色）并可一键「恢复」。健康源显示绿色「上次搜索 Xms」徽章。详见 Data-Sources · 源可用性测试与自动停用。

直播源

• 直播源列表：M3U 地址、名称（可选）、EPG 节目单地址（可选），支持探活与导出 .m3u；
• 来自订阅的源带归属标记，由订阅统一管理，不可单独删除；
• 勾选启用的源：仅启用的源会在「直播」页聚合频道；详见 Live-IPTV。

数据源订阅

• 入口：设置 → 源管理 → 数据源订阅；保存订阅地址、名称、上次同步时间；
• 一份订阅可同时下发点播源与直播源，订阅地址兼容 LibreTV-SourceList JSON 与 TVBOX 配置，格式与行为见 Data-Sources · 数据源订阅；
• 整体启用 / 停用：每条订阅的开关可临时停用它，其源不再参与搜索；不改各源勾选状态、不删数据，重新打开即完全恢复（无损可逆）；
• 同步为手动操作（订阅条目 ⟳），远端列表更新后需手动刷新；部署者可通过 DEFAULT_SUBSCRIPTIONS 预置订阅，首次访问自动导入、超 24h 静默刷新，见上文 预置数据源订阅；
• 分享：「导出数据源」导出全量 JSON 文件供自行托管；「发布为链接」把仅已勾选启用的源发布到公开粘贴板并直接返回订阅 URL（注意事项见 Data-Sources · 分享）；
• 删除订阅会移除其导入的两类源（含启用状态与最近观看），但保留已收藏的频道。

播放与过滤（设置 → 偏好设置 → 播放与过滤）

首页与内容过滤（设置 → 偏好设置 → 首页与内容）

搜索历史

• 交互：首页搜索框聚焦即展开下拉列出最近 10 条关键词（顶栏搜索框同样支持，两处共用同一套交互）；输入时按关键字实时过滤历史，↑ ↓ 选择、Enter 采用、Esc 或点击外部收起；
• 管理：每条可单独删除（✕），也可一键「清空」——清空后 6 秒内可「撤销」恢复；
• 存储：本机 IndexedDB 的 searchHistory 表（主键为关键词，上限 10 条，按时间倒序），随「导出配置」一并迁移；
• 早期版本把「最近搜索」常驻在搜索框下方，现已改为下拉：不占首屏，也消除了首次搜索后该行出现导致的布局跳动。

封面图加载方式（设置 → 偏好设置 → 封面图加载）

每种方式是一条「加载链」，加载失败时按链自动降级，无需手动干预：

• 部署者可通过 DEFAULT_IMAGE_MODE 为所有用户指定默认加载方式（直连优先 / 内置代理），见上文 封面图加载方式默认值；
• 代理地址为查询串形式（?url=）：路径里的 %2F 会被 EdgeOne 等网关在路由前解码，查询串不受影响，全平台行为一致；旧路径形式仍兼容；
• 封面 <img> 均带 referrerPolicy="no-referrer"，不向图床暴露来源页；
• 经代理转发的图片响应缓存 30 天（分片 / key 保守 1 小时）。

主题

• 头部太阳/月亮/显示器图标，点击在 浅色 → 深色 → 跟随系统 间循环；
• 存储于 localStorage['libretv-theme']；
• 页面 HTML 内有同步脚本，刷新无闪烁；
• 跟随系统模式下监听 prefers-color-scheme 变化实时切换。

配置导入导出

• 导出：生成 LibreTV-Settings_<时间戳>.json（点播源与直播源、播放设置、观看历史、搜索历史）；
• 导入：兼容旧版 LibreTV 导出的配置文件；旧版观看历史（含全集 URL 列表）会自动迁移为定位信息格式。

存储结构（IndexedDB libretv）