Configuration

配置

环境变量

变量	必填	默认	说明
PASSWORD	是	—	访问密码。未设置时站点可用但所有功能接口返回 503，并提示管理员配置
PROXY_SECRET	否	从 PASSWORD 派生	会话与代理签名密钥。单实例可不设；多实例/负载均衡部署必须显式设置，否则各实例会话互不认账
REQUEST_TIMEOUT	否	8000	代理上游请求超时（毫秒）
MAX_RETRIES	否	1	代理请求重试次数
SEARCH_MAX_PAGES	否	5	每个搜索源最多抓取的页数（1-50）。第一页响应携带源站真实总页数 pagecount，实际抓取页数取两者较小值；后续页并行请求，单页失败仅丢弃该页。调大会显著增加上游请求量（约等于 源数 × 页数），搜索延迟与源站压力随之上升
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 链接即可，首次访问自动为所有用户导入点播源与直播源：

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 地址、详情页地址（可选）、成人标记；
• 勾选参与搜索的源：仅勾选的源会参与聚合搜索与换源。

直播源

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

数据源订阅

• 入口：设置 → 订阅与配置 → 数据源订阅；保存订阅地址、名称、上次同步时间；
• 一份订阅可同时下发点播源与直播源，格式与行为见 Data-Sources · 数据源订阅；
• 同步为手动操作（订阅条目 ⟳），远端列表更新后需手动刷新；部署者可通过 DEFAULT_SUBSCRIPTIONS 预置订阅，首次访问自动导入、超 24h 静默刷新，见上文 预置数据源订阅；
• 删除订阅会移除其导入的两类源（含启用状态与最近观看），但保留已收藏的频道。

播放与过滤

开关	默认	说明
成人内容过滤	开	服务端按分类关键词过滤（伦理片/福利片等）
广告过滤	开	hls.js loader 剔除 m3u8 中的 #EXT-X-DISCONTINUITY 广告片段
自动连播	开	单集结束自动播放下一集
豆瓣推荐	开	首页展示豆瓣热门影视

封面图加载方式

方式	说明
内置代理（默认）	经 /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 条