一分钟搭建影视站,支持Docker等部署方式
docs: 移除仓库内 docs/,GitHub Wiki 为唯一文档源
bestZweiee9331880de0
diff --git a/README.md b/README.mdindex eb5f17c..63aa2a3 100644--- a/README.md+++ b/README.md@@ -4,7 +4,6 @@ LibreTV Next.js 迁移版:免费在线视频聚合搜索与观看平台。基> 📖 **完整文档**:[GitHub Wiki](https://github.com/bestZwei/LibreTV-Next/wiki) · [架构](https://github.com/bestZwei/LibreTV-Next/wiki/Architecture) · [部署](https://github.com/bestZwei/LibreTV-Next/wiki/Deployment) · [配置](https://github.com/bestZwei/LibreTV-Next/wiki/Configuration) · [数据源](https://github.com/bestZwei/LibreTV-Next/wiki/Data-Sources) · [首页推荐](https://github.com/bestZwei/LibreTV-Next/wiki/Recommendations) · [播放器](https://github.com/bestZwei/LibreTV-Next/wiki/Player) · [代理与安全](https://github.com/bestZwei/LibreTV-Next/wiki/Proxy-Security) · [FAQ](https://github.com/bestZwei/LibreTV-Next/wiki/FAQ)>-> 仓库内 docs/ 目录为同一份文档的镜像,便于在代码浏览时就近阅读。## 核心特性@@ -56,7 +55,7 @@ docker compose pull && docker compose up -d`linux/amd64` 与 `linux/arm64` 双架构)。需要固定版本时在 `.env` 中设置`LIBRETV_IMAGE=ghcr.io/librespark/libretv:2.0.1`。-> 版本号以 `package.json` 为单一来源,部署后可用 `/api/status` 返回的 `version` 字段核对。详见[部署文档](docs/Deployment.md)。+> 版本号以 `package.json` 为单一来源,部署后可用 `/api/status` 返回的 `version` 字段核对。详见[部署文档](https://github.com/bestZwei/LibreTV-Next/wiki/Deployment)。### 手动运行@@ -72,7 +71,7 @@ PASSWORD=your-password npm start # 监听 8080| --- | --- | --- || `PASSWORD` | 是 | 访问密码;未设置时站点会提示管理员配置 || `PROXY_SECRET` | 否 | 会话/代理签名密钥;不设置时从 PASSWORD 派生(多实例部署建议显式设置) |-| `DEFAULT_SOURCES` | 否 | 预置采集站(JSON 数组),用户端自动出现且默认勾选,详见[配置文档](docs/Configuration.md) |+| `DEFAULT_SOURCES` | 否 | 预置采集站(JSON 数组),用户端自动出现且默认勾选,详见[配置文档](https://github.com/bestZwei/LibreTV-Next/wiki/Configuration) || `REQUEST_TIMEOUT` | 否 | 代理上游请求超时(毫秒),默认 8000 || `MAX_RETRIES` | 否 | 代理请求重试次数,默认 1 || `SEARCH_MAX_PAGES` | 否 | 每个搜索源最多抓取的页数(1-50,默认 5)。第一页会读取源站 `pagecount`,实际页数 = min(源站总页数,该值);页间并行请求,单页失败只丢该页 |@@ -116,7 +115,7 @@ PASSWORD=your-password npm start # 监听 8080- **管理边界**:订阅源以远端列表为准,单独编辑会在下次同步时被覆盖,单独移除会在重新同步时恢复;如需调整请改远端列表,或直接删除整个订阅(会一并移除其导入的源);- **导出分享**:设置 → 源订阅 / 分享 → 「导出源列表」,把当前全部来源(预置 + 手动 + 订阅,按 URL 去重)导出为上述 JSON。-> 订阅由服务端拉取(经过 SSRF 校验),因此订阅地址无需配置 CORS。完整说明见 [数据源文档](docs/Data-Sources.md#源订阅--分享)。+> 订阅由服务端拉取(经过 SSRF 校验),因此订阅地址无需配置 CORS。完整说明见 [数据源文档](https://github.com/bestZwei/LibreTV-Next/wiki/Data-Sources)。## 开发@@ -136,7 +135,7 @@ npm version patch # 或 minor / major;会更新 package.json 并打 gitgit push && git push --tags```-CI 校验通过后自动构建并推送 `ghcr.io/librespark/libretv:<版本>`(详见[部署文档](docs/Deployment.md))。+CI 校验通过后自动构建并推送 `ghcr.io/librespark/libretv:<版本>`(详见[部署文档](https://github.com/bestZwei/LibreTV-Next/wiki/Deployment))。## 安全说明diff --git a/docs/Architecture.md b/docs/Architecture.mddeleted file mode 100644index d19969d..0000000--- a/docs/Architecture.md+++ /dev/null@@ -1,118 +0,0 @@-# 架构--## 技术栈--| 层 | 技术 | 说明 |-| --- | --- | --- |-| 框架 | Next.js 15(App Router)+ React 19 | 服务端 API Routes 与客户端页面同仓 |-| 语言 | TypeScript(strict) | 全量类型覆盖 |-| 样式 | Tailwind CSS(构建期编译)+ CSS 变量主题 | 亮暗双主题,`darkMode: 'class'` |-| 数据获取 | TanStack Query | 搜索/详情/推荐数据的缓存、重试、失效 |-| 客户端状态 | Zustand(persist → localStorage) | 数据源列表与播放设置 |-| 持久化 | Dexie(IndexedDB) | 观看历史、播放进度、搜索历史 |-| 播放 | ArtPlayer + hls.js | 广告过滤 loader、代理回退 |--## 目录结构--```-libretv/-├── src/-│ ├── app/-│ │ ├── page.tsx # 首页:搜索 + 推荐区(?s= URL 驱动)-│ │ ├── watch/page.tsx # 播放页(唯一入口,URL 即状态)-│ │ ├── about/page.tsx-│ │ ├── layout.tsx # 主题无闪烁内联脚本 + Providers-│ │ ├── manifest.ts # PWA manifest-│ │ └── api/ # 服务端 Route Handlers-│ │ ├── auth/route.ts # 登录/登出/会话状态-│ │ ├── status/route.ts # 站点状态(客户端据此弹登录框)-│ │ ├── search/route.ts # 聚合搜索(并行 + 失败隔离 + 过滤)-│ │ ├── detail/route.ts # 详情(列表接口 → 详情页 HTML 降级)-│ │ ├── douban/route.ts # 豆瓣推荐(直连 + 缓存 + 代理降级)-│ │ ├── bangumi/calendar/ # Bangumi 每日放送(免 key)-│ │ ├── hot-list/route.ts # 影视榜单(60s API:豆瓣周榜 + 百度热播)-│ │ └── proxy/[url]/route.ts# 流式代理(SSRF 防护 + m3u8 重写)-│ ├── components/ # UI 组件(见下)-│ └── lib/ # 纯逻辑库(可单元测试)-│ ├── cms-parser.ts # Apple CMS 解析(列表/详情/详情页爬取)-│ ├── m3u8.ts # m3u8 重写与广告过滤-│ ├── ssrf.ts # 内网地址识别与 DNS 校验-│ ├── auth.ts # 会话签名/校验、登录限流-│ ├── douban.ts # 豆瓣数据获取(降级链 + TTL 缓存)-│ ├── bangumi.ts # Bangumi 每日放送(免 key,星期分组)-│ ├── douban-weekly.ts # 影视榜单聚合(60s API,六个榜单归一化)-│ ├── fetch-utils.ts # 超时/重试/内存缓存-│ ├── db.ts # Dexie schema 与历史/进度 CRUD-│ ├── store.ts # Zustand 全局设置-│ ├── client-api.ts # 客户端 API 封装(401 → 全局登录框)-│ └── utils.ts # 时间格式化、图片代理 URL、sha256 等-├── docs/ # 本 Wiki-├── Dockerfile / docker-compose.yml-└── README.md-```--## 组件一览--| 组件 | 职责 |-| --- | --- |-| `providers.tsx` | QueryClient + Theme + Toast + Auth 四层 Provider 嵌套 |-| `theme.tsx` | 亮暗主题上下文与三态切换按钮(light/dark/system) |-| `auth.tsx` | 认证上下文;监听全局 401 事件弹出登录框 |-| `header.tsx` | 顶部导航 + 通用抽屉(Drawer)骨架 |-| `search`(page.tsx 内联) | 搜索框、历史 chips、结果网格、空态引导 |-| `douban-section.tsx` | 首页推荐区(RecommendSection):豆瓣 / Bangumi / 影视榜单三源按设置分支渲染 |-| `video-card.tsx` | 搜索结果卡片 / 豆瓣卡片(封面多级降级) |-| `detail-modal.tsx` | 详情弹窗(海报 + 元信息 + 剧集 + 复制链接) |-| `source-manager.tsx` | 设置抽屉:数据源 CRUD、过滤开关、封面加载方式、配置导入导出 |-| `history-panel.tsx` | 观看历史抽屉(Dexie liveQuery 实时刷新) |-| `player-shell.tsx` | ArtPlayer/HLS 封装:广告过滤、快捷键、长按倍速、代理回退 |-| `switch-source.tsx` | 换源面板:跨源搜索 → 同名匹配 → 测速排序 → 切换 |-| `toast.tsx` | 并行堆叠 Toast + 全局 Loading 遮罩 |--## 数据流--### 搜索--```-浏览器 服务端 上游- │ POST /api/search │ │- │ {wd, sources[], filter} │── 并行 fetch(8s 超时)────→│ 采集站 ×N- │ │← JSON ─────────────────────│- │← {list, failures[]} ──────│ 合并/去重/排序/成人过滤 │-```--- 客户端把自定义数据源配置随请求上传(数据源配置仅存于用户浏览器);-- 单源失败进入 `failures`,不影响其他源结果;-- React Query 以 `['search', wd, selectedKeys, filter]` 为缓存键。--### 播放--```-/watch?source=key&id=vodId&index=n&title=..&sourceUrl=..- │- ├─ resolveSource(): 从 Zustand store 取数据源配置(URL 参数兜底,支持分享链接)- ├─ GET /api/detail → episodes[] → 当前集 URL- └─ PlayerShell(ArtPlayer+hls)- ├─ 直连 m3u8- └─ 致命网络错误 → /api/proxy/<url> 重试一次(cookie 鉴权)-```--进度:`video:timeupdate`(5s 节流)+ 暂停 + 卸载 → IndexedDB `progress`;-历史:进入播放页 2s 后 upsert,仅存定位信息(`sourceKey + vodId + episodeIndex`),不存全集 URL。--### 换源--`switch-source.tsx` → `POST /api/search`(按标题)→ 每源取完全同名结果(否则第一条)→ `GET /api/detail` 并发测速(接口耗时)→ 按速度排序展示 → 切换时保留集数索引。--## 与旧版的架构差异--| 维度 | 旧版 | 本版 |-| --- | --- | --- |-| API 层 | 浏览器内 monkey-patch `window.fetch` 假装 `/api/*` | 真实服务端 Route Handlers |-| 聚合搜索位置 | 用户浏览器(IP 暴露、无法缓存) | 服务端 |-| 鉴权 | 页面下发 sha256(password),`auth=` 哈希即凭证 | httpOnly cookie + HMAC 签名会话 |-| m3u8 分片 | 重写为 `/proxy/...` 但丢失鉴权参数 → 401 | cookie 同源自动携带,天然通过 |-| 页面间状态 | URL + localStorage 双总线(10+ key) | URL 即状态 + IndexedDB |-| 播放入口 | watch.html → player.html 跳转链 | 单一 `/watch` 路由 |-| 转义 | 4 种手工转义函数,存在 XSS 缺口 | React 自动转义,无 innerHTML |-| 主题 | 无 | CSS 变量 + class 策略,三态切换 |diff --git a/docs/Configuration.md b/docs/Configuration.mddeleted file mode 100644index 0dd135d..0000000--- a/docs/Configuration.md+++ /dev/null@@ -1,78 +0,0 @@-# 配置--## 环境变量--| 变量 | 必填 | 默认 | 说明 |-| --- | --- | --- | --- |-| `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_sources) |-| `60S_API_BASE` | 否 | `https://60s.viki.moe` | 影视榜单推荐源(豆瓣周榜/百度热播)使用的 [60s API](https://github.com/vikiboss/60s) 实例地址。服务端每类榜单缓存 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)--部署者可通过环境变量为所有用户预置数据源,用户无需手动添加即可搜索:--```bash-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` 下发,展示在设置抽屉顶部并带「部署者预置」标记,用户可勾选/取消但**不可编辑或删除**;-- 预置源首次出现时自动勾选(开箱即搜);用户取消勾选后刷新页面不会被反复勾回;-- 预置源不参与用户侧的配置导出(导出文件只含用户自建源),部署者变更环境变量即可全站生效。--## 运行时设置(用户级)--以下设置保存在每个用户浏览器的 localStorage(键 `libretv-settings`),通过「设置」抽屉修改:--### 数据源--- **自定义 API 列表**:名称、API 地址、详情页地址(可选)、成人标记;-- **勾选参与搜索的源**:仅勾选的源会参与聚合搜索与换源;-- **源订阅**:远程源列表地址与上次同步时间,格式与行为见 [Data-Sources · 源订阅](Data-Sources.md#源订阅--分享)。同步为手动操作(订阅条目 **⟳**),远端列表更新后需手动刷新。--### 播放与过滤--| 开关 | 默认 | 说明 |-| --- | --- | --- |-| 成人内容过滤 | 开 | 服务端按分类关键词过滤(伦理片/福利片等) |-| 广告过滤 | 开 | 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 条 |diff --git a/docs/Data-Sources.md b/docs/Data-Sources.mddeleted file mode 100644index 9c8b6c2..0000000--- a/docs/Data-Sources.md+++ /dev/null@@ -1,122 +0,0 @@-# 数据源--LibreTV 采用**空壳设计**:不内置任何采集站,由部署者/用户自行添加,避免内置源失效与合规风险。--> 搜索用的**采集源**与首页的**推荐源**(豆瓣 / Bangumi / 影视榜单)是两套独立配置:前者决定"能搜到什么",后者决定首页展示什么,见 [Recommendations](Recommendations.md)。--- **部署者预置**:通过 `DEFAULT_SOURCES` 环境变量下发(JSON 数组),所有用户开箱即搜,详见[配置文档](Configuration.md);-- **用户自建**:设置抽屉「+ 添加 API」手动添加,保存在浏览器 localStorage。--## 支持的数据源类型--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 秒超时;-- 任一源失败不影响整体,失败源在结果区顶部以名称列出;-- 结果按「源内去重(sourceKey+vodId)→ 名称排序(zh-CN)」合并;-- 成人过滤在服务端执行,关键词包括:伦理片、福利、里番动漫、无码、SWAG 等。--## 源可用性测试--设置 → 数据源,每个源右侧的 **⚡** 按钮触发服务端探活:--- 以搜索 `test` 的完整往返衡量:返回响应耗时(ms)与结果条数;-- 结果以徽章内联展示(`✓ 610ms` 绿色 / `✗ 超时` 红色);-- 探活请求与搜索一样经过 SSRF 校验,仅支持公网 http(s) 地址。--## 源订阅 / 分享--源列表可以脱离单台设备流转:导出为 JSON 文件 → 托管到任意公开 URL → 他人在「设置」里填入该 URL 订阅。--### 订阅格式(LibreTV-SourceList JSON)--```json-{- "name": "我的源列表",- "version": 1,- "sources": [- {- "name": "暴风资源",- "url": "https://bfzyapi.com/api.php/provide/vod",- "detail": "https://bfzyapi.com",- "isAdult": false- }- ]-}-```--**字段说明**:--| 字段 | 位置 | 类型 | 必填 | 说明 |-| --- | --- | --- | --- | --- |-| `name` | 顶层 | string | 否 | 列表名称,订阅后显示在订阅条目上;缺省时显示订阅地址主机名 |-| `version` | 顶层 | number | 否 | 格式版本,当前为 `1`;导入端目前忽略该字段 |-| `sources` | 顶层 | array | **是** | 源数组,最多 100 个,超出部分截断 |-| `sources[].name` | 项 | string | 否 | 源显示名;缺省时使用 URL 主机名 |-| `sources[].url` | 项 | string | **是** | Apple CMS 采集接口地址(公网 http/https),结尾 `/` 自动去除 |-| `sources[].detail` | 项 | string | 否 | 详情页根地址,用于列表接口拿不到播放地址的源 |-| `sources[].isAdult` | 项 | boolean | 否 | 成人内容标记,默认 `false`;受「成人内容过滤」开关控制 |--**兼容与限制**:--- 也接受**裸数组**格式 `[{ "name": "...", "url": "..." }, ...]`(此时列表名显示为主机名);-- 按 `url` 去重(先到先得);非公网 http(s) 地址(内网/回环/保留地址)会被**静默过滤**;-- 订阅由**服务端**拉取(拉取前经过 SSRF 校验),因此订阅地址**无需配置 CORS**,Gist、对象存储、任意静态托管均可。--### 订阅行为--- **导入**:设置 → 源订阅 / 分享 → 填入订阅地址 → 「订阅」;导入的源自动勾选(成人过滤开启时跳过成人源),并在列表中带「订阅」标识;-- **手动同步**:订阅条目上的 **⟳** 随时强制同步——整体替换该订阅名下的源(与订阅 URL 相同的手动源会被去重合并),成功/失败均以提示反馈;-- **订阅源的管理边界**:订阅源以远端列表为准——单独编辑会在下次同步时被覆盖,单独移除会在重新同步时恢复;如需调整请修改远端列表后同步,或直接删除整个订阅;-- **删除订阅**:同时移除其导入的所有源。--### 分享(导出)--设置 → 源订阅 / 分享 → 「导出源列表」:把当前全部来源(部署者预置 + 手动添加 + 订阅导入,按 URL 去重)导出为上述格式的 JSON 文件。托管后即可被他人订阅。--## 自定义源的数据流--数据源配置**只保存在用户浏览器**(localStorage),服务端不存储。每次搜索/详情请求会把用到的源配置随请求上传,因此:--- 同一部署的不同用户可以有不同的数据源集合;-- 分享播放链接时 URL 会携带 `sourceUrl` 参数,接收者即使未配置同名的源也能播放(见 [Player](Player.md))。--## 常见问题--**Q: 添加源后搜索无结果?**-用浏览器直接访问 `{api}?ac=videolist&wd=test` 验证是否返回 JSON。部分源校验 Referer/UA 或已停更。--**Q: 搜索成功但详情提示"未找到播放资源"?**-该源的播放地址可能需要详情页爬取,请补填「详情页地址」;或该影片在源内本身无 m3u8 地址。--**Q: 可以批量导入吗?**-旧版支持逗号分隔的多个 API 地址一次性导入(`?urls=` 参数)。重构版暂未移植该入口,可通过「导出/导入配置」迁移。diff --git a/docs/Deployment.md b/docs/Deployment.mddeleted file mode 100644index 64a6c9c..0000000--- a/docs/Deployment.md+++ /dev/null@@ -1,151 +0,0 @@-# 部署--## Docker(推荐)--```bash-git clone <本仓库>-cd libretv--# 设置密码-echo "PASSWORD=your-strong-password" > .env--docker compose up -d --build-# 访问 http://localhost:8080-```--镜像为多阶段构建(`DOCKER_BUILD=1` 时输出 standalone),运行容器不包含构建工具,体积小。--## 镜像分发与版本管理--### 版本号:单一事实来源--版本号**只在 `package.json` 的 `version` 字段维护**:--- `/api/status` 返回的 `version` 由 `next.config.ts` 在构建时读取并注入(`process.env.APP_VERSION`);-- Docker 镜像 tag 建议与它保持一致,使用者可凭 `/api/status` 的返回值核对部署版本。--改版本只需一处:`npm version patch|minor|major`(会同步更新 `package.json` 并打 git tag)。--### 发布镜像(已自动化)--镜像由 GitHub Actions 自动构建并推送到 **GHCR**:`.github/workflows/docker-publish.yml`。--发布流程(开发者侧只需三步):--```bash-npm version patch # 2.0.0 → 2.0.1,自动更新 package.json 并打 git tag-git push-git push --tags-```--推送到 `v*` tag 后,CI 会先校验 tag 与 `package.json` 版本一致(不一致直接失败,防止镜像标签-与 `/api/status` 返回值脱节),再跑类型检查与单测,通过则构建 `linux/amd64` + `linux/arm64`-双架构镜像并推送,产出三个 tag:--- `ghcr.io/librespark/libretv:2.0.1`(完整版本)-- `ghcr.io/librespark/libretv:2.0`(次版本)-- `ghcr.io/librespark/libretv:latest`--无需配置任何 secrets,`GITHUB_TOKEN` 由 GitHub 自动注入并具备 `packages: write` 权限。-首次发布后,需要到仓库的 **Packages** 页面把镜像可见性设为 Public(默认 Private,拉取需要登录)。--### 使用者侧--```bash-git clone <本仓库> && cd LibreTV-echo "PASSWORD=your-strong-password" > .env-docker compose pull && docker compose up -d # 拉取 ghcr.io/librespark/libretv:latest-```--锁定特定版本时在 `.env` 中设置:--```bash-LIBRETV_IMAGE=ghcr.io/librespark/libretv:2.0.1-```--### 本地源码构建(不经过 CI)--`docker-compose.yml` 同时声明了 `build: .` 与 `image:`,本地没有镜像时会用源码构建-(tag 落在 `ghcr.io/librespark/libretv:latest`):--```bash-docker compose up -d --build-```--### 构建上下文--仓库含 `.dockerignore`,`node_modules`/`.next`/文档/日志不会进入构建上下文,-`COPY . .` 不会把本地依赖或构建产物带进镜像,也不会因 `.git` 而使 context 膨胀。--### docker-compose.yml--```yaml-services:- libretv:- build: .- image: ${LIBRETV_IMAGE:-ghcr.io/librespark/libretv:latest}- restart: unless-stopped- ports: ["8080:8080"]- environment:- - PASSWORD=${PASSWORD:?请在 .env 中设置 PASSWORD}- # - PROXY_SECRET=your-secret-```--## 手动部署--要求 Node.js ≥ 20(推荐 22):--```bash-npm ci-PASSWORD=your-password npm run build-PASSWORD=your-password npm start # 默认 8080 端口-```--> 注意:`output: 'standalone'` 仅在 `DOCKER_BUILD=1` 时启用,本地 `next start` 无需(也不兼容)standalone。--### 生产建议--- 使用反向代理(Nginx / Caddy)终结 HTTPS,转发到 8080;-- 会话 Cookie 在生产环境(`NODE_ENV=production`)下自动启用 `Secure`,需 HTTPS 访问;-- 设置 `PROXY_SECRET` 而非依赖 PASSWORD 派生,避免更换密码导致全员会话失效以外的副作用。--## 环境变量--完整列表见 [Configuration](Configuration.md)。最小可运行配置只有一个 `PASSWORD`。--## 健康检查与验证--```bash-curl http://localhost:8080/api/status-# {"passwordRequired":true,"verified":false,"version":"2.0.0"}--# 未登录访问受保护接口应返回 401-curl -X POST http://localhost:8080/api/search -d '{}' -H 'Content-Type: application/json' -i | head -1-# HTTP/1.1 401 Unauthorized--# SSRF 防护应拦截内网地址-curl -i "http://localhost:8080/api/proxy/http%3A%2F%2F127.0.0.1%3A8080%2F" | head -1-# HTTP/1.1 400/403-```--## 升级--1. `git pull`-2. `npm ci && npm run build`(Docker 部署改为 `docker compose pull && docker compose up -d`,源码构建则为 `docker compose up -d --build`)-3. 用户数据(历史/进度/设置)在浏览器端,升级无感迁移。-4. 可通过 `/api/status` 的 `version` 字段核对线上版本是否已更新。--## 从旧版迁移--- 旧版打开「设置 → 配置文件 → 导出」,新版「设置 → 配置 → 导入配置」选择同一文件即可迁移数据源与观看历史;-- 旧版 localStorage 各零散 key 不会被读取,仅识别标准导出 JSON;-- 旧版的 `PASSWORD` 环境变量直接沿用(明文比对改为服务端恒定时间比较,用户无感知)。--## 开发--```bash-npm install-PASSWORD=dev-password npm run dev # http://localhost:8080-npm run typecheck # TypeScript 检查-npm test # 单元测试(cms-parser / m3u8 / ssrf)-```diff --git a/docs/FAQ.md b/docs/FAQ.mddeleted file mode 100644index b6e256b..0000000--- a/docs/FAQ.md+++ /dev/null@@ -1,74 +0,0 @@-# FAQ--## 部署相关--**Q: 打开站点一直提示"需要配置密码"?**-服务器未设置 `PASSWORD` 环境变量。Docker 部署检查 `.env`;手动部署确认启动命令中带 `PASSWORD=...`。设置后需重启服务。--**Q: 登录后刷新又要求输入密码?**-- 生产环境(HTTPS)下 Cookie 为 `Secure`,用 HTTP 访问生产构建会导致 Cookie 无法保存——请配置 HTTPS 或以开发模式运行;-- 多实例部署未设置 `PROXY_SECRET`:各实例派生密钥不同,会话互不认账。--**Q: 忘记密码怎么办?**-修改 `PASSWORD` 环境变量并重启。旧会话立即全部失效(密钥随之改变)。--## 搜索相关--**Q: 搜索提示"请先添加数据源" / "尚未勾选数据源"?**-本项目不内置采集站。到「设置 → 数据源」添加 Apple CMS 采集站地址并勾选。--**Q: 某个源一直搜索失败?**-结果区顶部会列出失败源名称。直接浏览器访问 `{api}?ac=videolist&wd=test` 判断是源挂了还是网络不通;不用的源可以取消勾选或删除。--**Q: 搜索结果为什么按名称排序?**-跨源聚合后按影片名(zh-CN locale)排序、同名片按源名排序,便于对比同一影片在不同源的画质/集数。--**Q: 从播放页返回搜索页会重新搜索吗?**-通常不会。客户端缓存搜索结果 5 分钟、服务端缓存同一关键词+源组合的结果 60 秒:返回时直接呈现缓存,不重复请求上游。需要强制刷新时重新提交一次搜索即可。--**Q: 详情为什么有缓存?会不会导致新剧集看不到?**-详情接口有 60 秒服务端缓存(同一影片 + 同一源),用于换源测速等场景避免重复打上游。剧集更新以源站为准,60 秒后即取到最新。--## 播放相关--**Q: 视频一直"正在加载"?**-按顺序尝试:① 点「切换资源」换其他源;② 设置中切换封面/直连相关配置确认网络;③ 该源分片可能仅允许特定地区/Referer,代理回退通常能自动解决,若仍失败请换源。--**Q: 出现"直连失败,改用代理重试"后播放正常,但快进卡顿?**-代理播放的带宽受限于服务器。属预期行为,建议优先寻找可直连的源。--**Q: 自动跳到下一集后从头播放了?**-确认「自动连播」开关已打开(播放页操作栏或设置中)。--**Q: 换源后集数对不上?**-换源按集数索引对齐,目标源集数少于当前集数时会回到第 1 集。--## 推荐相关--**Q: 首页推荐区不显示 / 加载失败?**-先确认「设置 → 首页推荐」开关已打开。加载失败按来源区分:豆瓣多为上游限流(可配置 `FALLBACK_CORS_PROXY` 降级);影视榜单多为官方 60s 公共实例限流或被墙(可自部署后用 `60S_API_BASE` 指向),详见 [Recommendations](Recommendations.md)。--**Q: 推荐内容点开后搜不到片源?**-推荐只提供片名与封面,实际播放依赖你在「设置 → 数据源」里配置的采集站覆盖范围。换标题关键词重搜或补充更多采集源。--## 数据相关--**Q: 换浏览器/设备后历史和进度还在吗?**-不在。历史与进度保存在本机 IndexedDB,不上传服务器。可用「设置 → 导出配置」手动迁移。--**Q: 观看历史里某条记录播放时提示"数据源不存在"?**-该记录的来源源已被删除。重新在设置中添加同名 API 地址(key 一致即可恢复),或删除该历史。--**Q: IndexedDB 数据会占多少空间?**-仅存定位信息(不含全集 URL),100 条历史通常 < 100KB。--## 安全相关--**Q: 密码是明文传输吗?**-登录请求把密码放在 POST body 中,生产环境务必启用 HTTPS 防止传输层被窃听。--**Q: 代理会被滥用吗?**-代理需要登录会话;未登录仅放行图片类目标且同样受 SSRF 校验约束。公网部署建议在反代层再加 IP 级限流。--**Q: 为什么不给站点加注册/多用户?**-LibreTV 定位为轻量自托管工具,单密码门禁 + 本机数据即可满足场景;多用户会引入服务端存储与隐私复杂度。diff --git a/docs/Home.md b/docs/Home.mddeleted file mode 100644index cb7a191..0000000--- a/docs/Home.md+++ /dev/null@@ -1,45 +0,0 @@-# LibreTV Wiki--欢迎来到 LibreTV 的项目文档。LibreTV 是一个免费的在线视频聚合搜索与观看平台,基于 Next.js 15 重构。--## 文档目录--| 文档 | 内容 |-| --- | --- |-| [Architecture](Architecture.md) | 系统架构、目录结构、数据流、技术选型说明 |-| [Deployment](Deployment.md) | Docker / 手动部署、环境变量、升级指南 |-| [Configuration](Configuration.md) | 环境变量详解、主题系统、数据源管理、配置导入导出 |-| [Data-Sources](Data-Sources.md) | 采集站(Apple CMS)接入说明、自定义 API 格式、源订阅与分享 |-| [Recommendations](Recommendations.md) | 首页推荐源(豆瓣 / Bangumi / 影视榜单)、切换与自部署 |-| [Player](Player.md) | 播放器功能、快捷键、广告过滤、代理回退、进度与历史 |-| [Proxy-Security](Proxy-Security.md) | 代理鉴权设计、SSRF 防护、安全模型与旧版对比 |-| [FAQ](FAQ.md) | 常见问题排查 |--## 快速开始--```bash-# Docker 部署(推荐)-echo "PASSWORD=your-password" > .env-docker compose up -d--# 本地开发-npm install-PASSWORD=dev-password npm run dev # http://localhost:8080-```--## 核心特性--- **聚合搜索**:多采集站服务端并行搜索,单源失败不影响整体,用户 IP 不暴露给第三方-- **跨源同名聚合**:同名影片合并为一张卡片,展开即可比较和选择各来源-- **HLS 播放**:ArtPlayer + hls.js,广告分片过滤、自动连播、倍速、快捷键、移动端长按 3 倍速-- **智能回退**:视频直连失败(CORS / 防盗链)时自动改走内置代理重试-- **进度同步**:播放进度与观看历史存于本机 IndexedDB,精确到秒的续播-- **换源测速**:跨源搜索同名资源并测速排序,一键切换保留集数位置-- **源测试与订阅**:一键探活数据源;订阅远程源列表(LibreTV-SourceList JSON),可导出分享-- **首页推荐**:豆瓣 / Bangumi 新番 / 影视榜单三源可选,服务端直连 + 缓存,免 key 免配置-- **亮暗主题**:跟随系统 / 手动切换,无首屏闪烁-- **PWA**:可安装到桌面 / 主屏幕--## 与旧版(静态 HTML + Express)的关系--本项目是 [LibreTV 旧版](https://github.com/LibreSpark/LibreTV/tree/backup-2025)(backup-2025 分支)的完整重构。功能对齐的同时修复了旧版的多项问题(历史记录 XSS、m3u8 分片鉴权丢失、密码哈希暴露等),架构差异详见 [Architecture](Architecture.md)。diff --git a/docs/Player.md b/docs/Player.mddeleted file mode 100644index caf0e2a..0000000--- a/docs/Player.md+++ /dev/null@@ -1,52 +0,0 @@-# 播放器--播放器基于 ArtPlayer + hls.js,封装在 `src/components/player-shell.tsx`,页面入口为 `/watch` 路由。--## 播放链接格式--```-/watch?source=custom_0&id=20717&index=0&title=流浪地球&sourceUrl=https://..- └─数据源 key └─影片 id └─集数 └─标题 └─数据源地址(分享链接兜底)-```--- `source` + `id` 存在时:从 `/api/detail` 拉取剧集列表,`index` 指定当前集;-- 仅 `url` 参数时(直连分享):直接播放该地址,无剧集列表;-- URL 即状态:刷新/分享/前进后退均无损。--## 功能--| 功能 | 说明 |-| --- | --- |-| 自动连播 | 单集结束 0.8s 后自动下一集;片尾自动清除该集进度 |-| 进度恢复 | 优先 URL `position` 参数,否则读 IndexedDB;>10s 且非片尾(95%)时恢复并提示"已从 XX:XX 继续播放" |-| 换源 | 「切换资源」→ 跨源搜索同名影片 → 详情接口测速 → 按速度排序;切换后保留当前集数索引 |-| 集数倒序 | 倒序排列按钮,激活集自动滚动进可视区 |-| 广告过滤 | 自定义 hls.js loader 对 manifest/level 文本剔除 `#EXT-X-DISCONTINUITY` 广告分段(设置中可关) |-| 错误恢复 | HLS 网络错误自动 `startLoad`,媒体错误自动 `recoverMediaError`;多次失败显示错误面板 |-| 代理回退 | 直连致命网络错误(CORS/防盗链/分片被拒)时,自动改走 `/api/proxy/`(cookie 鉴权)重试一次 |-| 画中画 / 截图 / 网页全屏 / 倍速 | ArtPlayer 原生能力 |--## 快捷键--| 按键 | 功能 |-| --- | --- |-| `空格` | 播放 / 暂停 |-| `←` / `→` | 快退 / 快进 5 秒 |-| `↑` / `↓` | 音量 ±10% |-| `F` | 全屏切换 |-| `Alt + ←` / `Alt + →` | 上一集 / 下一集 |-| 双击 | 全屏切换 |-| 移动端长按 | 3 倍速播放(松开恢复) |--## 播放进度与历史--- **进度**:`video:timeupdate` 每 5 秒节流保存 + 暂停/页面隐藏/组件卸载时强制保存 → IndexedDB `progress` 表;-- **历史**:进入播放页 2 秒后写入 `history` 表(仅 `sourceKey + vodId + episodeIndex` 定位信息),播放中增量更新进度;-- **剧集同步**:从历史进入播放页时重新拉取详情,天然获得最新剧集列表(旧版需专门的同步逻辑)。--## 播放失败的排查顺序--1. **换源**:点击「切换资源」,选择测速绿色(低延迟)的其他源;-2. **观察回退提示**:若出现"直连失败,改用代理重试"说明该源分片有防盗链,代理通常可解;-3. **关广告过滤**:个别源本身依赖 DISCONTINUITY 做多码率切换,误过滤会黑屏;-4. **直接验证**:浏览器访问详情返回的 m3u8 地址确认源本身可用。diff --git a/docs/Proxy-Security.md b/docs/Proxy-Security.mddeleted file mode 100644index 0671987..0000000--- a/docs/Proxy-Security.md+++ /dev/null@@ -1,69 +0,0 @@-# 代理与安全--本项目的服务端承担三类安全职责:**访问鉴权**、**代理防护(SSRF)**、**上游伪装(防盗链)**。--## 鉴权模型--### 会话--- 登录:`POST /api/auth`,body 携带明文密码(**不走 URL**,避免进访问日志);-- 服务端用 SHA-256 摘要做**恒定时间比较**(`crypto.timingSafeEqual`),不暴露时序信息;-- 通过后签发会话 Cookie:`ltv_session = <过期时间戳>.<HMAC-SHA256(密钥, 时间戳)>`;- - `httpOnly`(JS 不可读)、`SameSite=Lax`、生产环境 `Secure`、有效期 90 天;- - 密钥 = `PROXY_SECRET`,未设置时从 `PASSWORD` 派生;-- 所有 `/api/*`(除 status/登录外)通过 `guardRequest` 校验会话,未登录返回 401,客户端全局弹出登录框。--### 速率限制--登录接口按 IP 限流:**10 次 / 10 分钟**,超限返回 429。内存实现,适合单实例部署。--### 与旧版的安全差异--| 问题 | 旧版 | 本版 |-| --- | --- | --- |-| 密码哈希下发 | 页面源码含 `sha256(PASSWORD)` | 服务端独享,前端零凭证 |-| 哈希即凭证 | `?auth=<哈希>` 可无限重放代理请求 | 已移除该兼容模式 |-| 明文密码上 URL | `GET /api/proxy-token?password=...` | `POST /api/auth` body |-| 登录限流 | 无 | 10 次 / 10 分钟 |-| token 轮换 | 10 分钟短时效 token(需手工附参) | 会话 Cookie,m3u8 分片同源自动携带 |--## 代理(`GET /api/proxy/<encoded-url>`)--### 访问规则--- **已登录**:可代理任意符合 SSRF 校验的目标(视频分片、key、JSON、图片);-- **未登录**:仅放行豆瓣域(`douban.com` / `doubanio.com` 及其子域)下的图片类目标,用于登录页前的封面展示;其余一律 401。- > 判定按**完整域名**匹配(`host === 'douban.com' || host.endsWith('.douban.com')`),- > 避免 `evil-douban.com` 这类后缀伪装绕过鉴权。--### SSRF 防护(双层)--所有**由用户输入驱动的服务端出网请求**都走同一套校验(`checkUpstreamAllowed`):-`/api/proxy`、`/api/search`(采集站 API 地址)、`/api/detail`(采集站 API 地址与详情页根地址)。-用户可填写的采集站地址同样是攻击面,只校验代理而放过搜索/详情会留下内网探测跳板。--1. **字面量校验**(请求前):协议白名单 http/https;主机名黑名单(localhost 等);IPv4/IPv6 字面量直接比对私有段;-2. **DNS 解析校验**(请求前):域名解析出的所有地址逐一检查,拦截解析到内网的域名(防 DNS rebinding 基础形态)。--被拦截的地址段:回环(127.0.0.0/8, ::1)、私有(10/8, 172.16/12, 192.168/16)、链路本地(169.254/16,含云元数据 169.254.169.254)、CGNAT(100.64/10)、协议保留(192.0.0.0/24)、唯一本地(fc00::/7)、链路本地 v6(fe80::/10)。--### 行为--- **流式透传**:视频分片 / 图片 / key 不落盘,直接 pipe;-- **m3u8 重写**:manifest/level 文本中的分片、`#EXT-X-KEY`、`#EXT-X-MAP` 地址全部改写为 `/api/proxy/<encoded>`(递归深度 ≤5),嵌套播放列表同样经代理,规避上游 CORS 限制;-- **响应头净化**:剔除 CSP/Cookie/Set-Cookie/X-Frame-Options/CORS 头与 Content-Encoding/Length(fetch 已解压,防止二次解压乱码);-- **Range 透传**:保留 `Range`/`Content-Range`,支持拖动;-- **重试**:上游失败按 `MAX_RETRIES` 重试。--### 上游伪装--- 目标为 `doubanio.com` 时自动携带 `Referer: https://movie.douban.com/`,绕过豆瓣图片 418 防盗链;-- 统一携带 Chrome UA。--## 已知边界--- 速率限制为内存实现,多实例部署需换共享存储(Redis);-- SSRF 的 DNS 校验存在理论上的 TOCTOU 窗口(校验后、请求前 DNS 记录变更);对公网部署建议叠加网络层出口限制;-- 上游请求目前跟随 30x 跳转(`redirect: 'follow'`),SSRF 校验只覆盖首跳:目标域名若 301/302 到内网地址仍可绕过。改造为 `redirect: 'manual'` + 逐跳校验可彻底闭合;-- 私有/保留地址一律拒绝,因此**部署在内网或本机(`localhost`、`192.168.x.x`)的采集站无法作为数据源使用**;-- 会话无法服务端主动吊销(无状态签名);更换 `PROXY_SECRET` 或 `PASSWORD` 可使全部会话失效。diff --git a/docs/Recommendations.md b/docs/Recommendations.mddeleted file mode 100644index 3b734e7..0000000--- a/docs/Recommendations.md+++ /dev/null@@ -1,58 +0,0 @@-# 首页推荐--首页在没有搜索关键词时展示推荐内容。推荐**数据源可在设置中切换**(设置 → 播放与过滤 → 「首页推荐」开关 + 「推荐数据源」下拉),同一时间只展示一个来源:--| 来源 | 内容 | 依赖 |-| --- | --- | --- |-| 豆瓣 | 电影/剧集分类 + 标签(热门、最新、高分等),分页加载 | 无 |-| Bangumi 新番放送 | 每日放送表,按星期筛选(周一~周日),一次全量 | 无,[api.bgm.tv](https://github.com/bangumi/api) 免 key |-| 影视榜单 | 豆瓣五个周榜(电影/国产剧/海外剧/国内外综艺)+ 百度热播剧,chips 切换 | [60s API](https://github.com/vikiboss/60s) 免 key,见 `60S_API_BASE` |--所有来源均在**服务端**直连上游并做内存缓存,浏览器只请求本站 API,不暴露用户 IP。--## 各来源实现细节--### 豆瓣(`/api/douban`)--- 上游 `movie.douban.com/j/search_subjects`,服务端伪装 UA/Referer 直连;-- 直连被拒时降级到 `FALLBACK_CORS_PROXY` 环境变量指定的代理;-- 缓存 10 分钟。--### Bangumi(`/api/bangumi/calendar`)--- 上游 `api.bgm.tv/calendar`(每日放送),完全公开免 key;-- 条目转换为与豆瓣一致的卡片结构:中文名优先(`name_cn`)、评分保留一位小数、封面取 `large` 档;-- 缓存 30 分钟;-- 点击卡片同样走标题搜索采集站,Bangumi 中文名可直接命中。--### 影视榜单(`/api/hot-list`)--经 [60s API](https://github.com/vikiboss/60s) 聚合,六个榜单:--| 榜单 | 标识 | 上游 |-| --- | --- | --- |-| 电影周榜 | `douban_movie_weekly` | 豆瓣移动端 rexxar 接口(60s 代为伪装 iPhone UA 抓取) |-| 国产剧周榜 | `douban_tv_chinese` | 同上 |-| 海外剧周榜 | `douban_tv_global` | 同上 |-| 国内综艺 | `douban_show_chinese` | 同上 |-| 海外综艺 | `douban_show_global` | 同上 |-| 百度热播剧 | `baidu_teleplay` | top.baidu.com 电视剧榜(无评分,海报偶缺,缺图条目已过滤) |--- 豆瓣周榜海报默认走 `doubanio.viki.moe` 代理域名,规避豆瓣图床防盗链;-- 缓存 1 小时;-- `60S_API_BASE` 环境变量可指向自部署的 60s 实例(`docker run -d -p 4399:4399 vikiboss/60s:latest`),官方公共实例有限流。--## 为什么默认是影视榜单--豆瓣搜索接口偶尔限流且封面有防盗链;影视榜单数据最完整(海报/评分/简介齐全)、60s 侧做了封面代理,且榜单内容与"找片看"的意图最匹配。旧部署升级后**已保存过设置的用户不受影响**,仍沿用其已持久化的选择。--## 常见问题--**Q: 首页推荐区完全不显示?**-检查设置 → 播放与过滤 → 「首页推荐」开关是否关闭。--**Q: 切换推荐源后没变化?**-来源选择保存在浏览器 localStorage,切换后立即生效;若被浏览器策略清除存储则回到默认。--**Q: 影视榜单加载失败?**-多为官方 60s 公共实例限流或被墙。可在服务端配置 `60S_API_BASE` 指向自部署实例或社区镜像后重启。