Configuration

配置

环境变量

变量	必填	默认	说明
PASSWORD	是	—	访问密码。未设置时站点可用但所有功能接口返回 503，并提示管理员配置
PROXY_SECRET	否	从 PASSWORD 派生	会话与代理签名密钥。单实例可不设；多实例/负载均衡部署必须显式设置，否则各实例会话互不认账
REQUEST_TIMEOUT	否	8000	代理上游请求超时（毫秒）
MAX_RETRIES	否	1	代理请求重试次数
SEARCH_MAX_PAGES	否	5	每个搜索源最多抓取的页数（1-50）。第一页响应携带源站真实总页数 pagecount，实际抓取页数取两者较小值；后续页并行请求，单页失败仅丢弃该页。调大会显著增加上游请求量（约等于 源数 × 页数），搜索延迟与源站压力随之上升
SEARCH_SOURCE_TIMEOUT_MS	否	10000	单个搜索源的总死线（毫秒，3s-60s）：该源所有分页请求须在时限内完成，到点中断在途请求并将该源标记为「超时」（failures[].timedOut）。避免慢源拖住首页流式搜索的整体等待；健康度自动停用也以此为超时判定依据
USER_AGENT	否	Chrome UA	代理请求使用的 UA（豆瓣防盗链等场景）
DEFAULT_SOURCES	否	—	预置采集站，JSON 数组，见下文 预置采集站
DEFAULT_LIVE_SOURCES	否	—	预置直播源（M3U 订阅），JSON 数组，见下文 预置直播源
DEFAULT_SUBSCRIPTIONS	否	—	预置数据源订阅（LibreTV-SourceList JSON 链接），JSON 数组，见下文 预置数据源订阅
LIVE_ALLOW_PRIVATE	否	false	设为 1 时允许直播流代理访问内网/保留地址（自建 IPTV 场景，如 http://192.168.x.x），默认关闭以维持 SSRF 防护
60S_API_BASE	否	https://60s.viki.moe	影视榜单推荐源（豆瓣周榜/百度热播）使用的 60s API 实例地址。服务端每类榜单缓存 1 小时，官方公共实例限流下通常够用；高频使用可用 docker run -d -p 4399:4399 vikiboss/60s:latest 自部署后指向它
DEBUG	否	false	调试日志

旧版的 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 均可），更新源列表无需修改容器配置或重启。

运行时设置（用户级）

以下设置保存在每个用户浏览器的 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 · 分享）；
• 删除订阅会移除其导入的两类源（含启用状态与最近观看），但保留已收藏的频道。

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

开关	默认	说明
广告过滤	开	hls.js loader 剔除 m3u8 中的 #EXT-X-DISCONTINUITY 广告片段
自动连播	开	单集结束自动播放下一集

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

开关	默认	说明
成人内容过滤	开	服务端按分类关键词过滤（伦理片/福利片等）
首页推荐	开	首页展示推荐内容
推荐数据源	影视榜单	豆瓣 / Bangumi / 影视榜单三选一，详见 Recommendations

搜索历史

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

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

方式	说明
内置代理（默认）	经 /api/proxy/ 转发（带豆瓣 Referer 伪装），规避豆瓣防盗链与图床直连失败
直连	浏览器直接加载豆瓣/采集站封面，最快；部分网络下豆瓣图会 418
自定义代理	模板字符串，{url} 为编码后的原图地址；不含占位符则直接拼接

主题

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

配置导入导出

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

存储结构（IndexedDB libretv）

表	主键	字段	说明
history	id = sourceKey_vodId	title, pic, episodeIndex, totalEpisodes, playbackPosition, duration, timestamp	上限 100 条，超出淘汰最旧
progress	key = sourceKey_vodId_index	position, duration, updatedAt	每集一条，看完清除
searchHistory	text	timestamp	上限 10 条