Skip to content

一分钟搭建影视站,支持Docker等部署方式

chore: 停止跟踪 .codebuddy 计划文件

bestZweib140d4c78b12
diff --git a/.codebuddy/plans/libretv-iptv-live-module_1d20a03d.md b/.codebuddy/plans/libretv-iptv-live-module_1d20a03d.md
deleted file mode 100644
index ea86907..0000000
--- a/.codebuddy/plans/libretv-iptv-live-module_1d20a03d.md
+++ /dev/null
@@ -1,256 +0,0 @@
----
-name: libretv-iptv-live-module
-overview: 为 LibreTV 新增 /live 直播模块:M3U 订阅解析(支持用户订阅 + 环境变量预置 + 导出)、HLS/HTTP-FLV 站内播放、XMLTV 节目单(EPG),并改造代理以适配直播长连接。
-design:
- architecture:
- framework: react
- styleKeywords:
- - 深色直播控制台
- - 暗亮双主题
- - 毛玻璃导航
- - 分组标签条
- - LIVE 呼吸红点
- - 卡片圆角
- - 微交互动效
- fontSystem:
- fontFamily: Noto Sans
- heading:
- size: 20px
- weight: 600
- subheading:
- size: 15px
- weight: 500
- body:
- size: 13px
- weight: 400
- colorSystem:
- primary:
- - "#2563EB"
- - "#3B82F6"
- - "#1D4ED8"
- background:
- - "#0B0F1A"
- - "#121826"
- - "#FFFFFF"
- text:
- - "#E5E7EB"
- - "#9CA3AF"
- - "#111827"
- functional:
- - "#EF4444"
- - "#10B981"
- - "#F59E0B"
-todos:
- - id: live-parsers
- content: 实现 m3u-parser.ts 与 xmltv.ts 并补齐 vitest 单测
- status: completed
- - id: live-api
- content: 新增 /api/live 的 playlist、epg、stream 三个路由与 live-cache
- status: completed
- dependencies:
- - live-parsers
- - id: live-config
- content: 新增 DEFAULT_LIVE_SOURCES 解析、status 下发与 types 扩展
- status: completed
- dependencies:
- - live-api
- - id: live-store
- content: 扩展 store 直播订阅/收藏/最近观看与 client-api 方法
- status: completed
- dependencies:
- - live-config
- - id: live-page
- content: 实现 /live 页面、live-player 与频道列表达
- status: completed
- dependencies:
- - live-store
----
-
-## 产品概述
-
-在 LibreTV 现有影视点播能力之外,新增一个独立的「直播 / IPTV」模块。用户(或部署者)提供 M3U 直播订阅地址后,可在站内 `/live` 页面按分组浏览频道、搜索频道、查看节目单,并直接在站内播放;不改动、不影响现有点播链路。项目本身不内置任何具体频道源,仅提供解析与播放能力。
-
-## 核心功能
-
-- **直播源管理**:支持用户粘贴 M3U/M3U8 订阅地址(订阅、手动同步、移除)与部署者环境变量预置两种方式;预置源开箱可见,用户取消后不再自动勾回。
-- **频道列表**:按 `group-title` 分组展示频道卡片(台标、频道名、分组标签),支持关键字搜索、分组筛选、收藏与最近观看。
-- **站内播放**:点击频道即在页面内播放,支持 HLS(m3u8)与 HTTP-FLV 两种直播流;播放失败时自动从直连切换到代理通道重试;直播态隐藏进度条、倍速、连播、截图等点播专属控件。
-- **节目单(EPG)**:解析 XMLTV(含 gzip 压缩)并按 `tvg-id` 匹配频道,侧栏展示「正在播出 / 即将播出」与时间轴,点击节目可查看简介。
-- **视觉效果**:沿用站点亮暗双主题与半透明导航风格;播放器区为 16:9 黑色画布,右侧为频道侧栏(分组折叠 + 频道项),底部为当前频道信息条与 EPG 时间轴;LIVE 状态以红色呼吸点标识,分组筛选为横向可滑动标签条。
-
-## 技术栈
-
-沿用项目现有技术栈,仅新增一个前端播放依赖:
-
-- Next.js 15(App Router)+ TypeScript + Tailwind CSS 3 + React 19
-- 播放:ArtPlayer 5 + hls.js 1.5(现有)+ **mpegts.js**(新增,仅直播页动态加载)
-- 状态:zustand + persist(现有 `libretv-settings`);数据获取:@tanstack/react-query
-- 测试:vitest(对齐 `cms-parser.test.ts` 风格)
-- 服务端:Node runtime 路由 + 项目现有 `fetchUpstream()` / `checkUpstreamAllowed()` / 内存 TTL 缓存
-
-## 实现方案
-
-### 整体架构
-
-```mermaid
-flowchart TB
- subgraph 客户端
- A[/live 页面] --> B[LivePlayer 协议分发]
- B -->|m3u8| C[hls.js]
- B -->|flv| D[mpegts.js 动态 import]
- A --> E[频道列表 / 分组 / 搜索]
- A --> F[EPG 时间轴]
- A --> G[直播源管理抽屉]
- end
- subgraph 服务端 Next.js API
- H[/api/live/playlist] -->|拉取+解析| I[m3u-parser]
- J[/api/live/epg] -->|拉取+解压+解析| K[xmltv]
- L[/api/live/stream/[url]] -->|长连接流式透传| M[上游直播源]
- N[/api/status] --> O[env-live-sources]
- end
- H -.复用.-> P[fetchUpstream + checkUpstreamAllowed]
- J -.复用.-> P
- L -.复用.-> P
- I -.写入.-> Q[live-cache 大对象 TTL 缓存]
- K -.写入.-> Q
-```
-
-### 关键技术决策
-
-**1. 直播流不能复用 `/api/proxy`(必须新建专用通道)**
-现有 `src/app/api/proxy/[url]/route.ts` 使用 `signal: AbortSignal.timeout(TIMEOUT_MS)`(默认 8000ms),该超时作用于**整个响应流**;且 M3U 不重写、非 m3u8 响应统一加 `Cache-Control: public, max-age=3600`,并且失败会重试。HTTP-FLV 是单一长连接,走该代理会在 8 秒后被切断。因此新建 `/api/live/stream/[url]`:
-
-- 只对「收到响应头」设超时(约 15s),拿到响应后立即释放超时信号,之后不限总时长;
-- 不重试、不读取 body 到内存(直接 `new NextResponse(response.body)`);
-- 响应头 `Cache-Control: no-store, no-transform`、`Connection: keep-alive`、透传 `content-type`;
-- 客户端断开(`req.signal`)时主动 `abort` 上游,防止连接泄漏;
-- 每次请求仍强制过 `checkUpstreamAllowed()`(不信任解析阶段的校验结果)。
-
-**2. 直播播放器独立组件,不污染点播播放器**
-新建 `src/components/live-player.tsx`,而非在 `player-shell.tsx` 的 `customType` 里加 flv 分支。理由:点播播放器耦合了进度恢复、IndexedDB 写入、自动连播、集数切换、广告过滤(剔除 `#EXT-X-DISCONTINUITY`,对直播有误伤风险),参数(backBufferLength/maxBufferLength)也是点播调优值。直播需要 `liveSyncDurationCount`、`lowLatencyMode`、直播态 UI。独立组件可将改动限制在新文件,点播链路零风险。
-
-**3. mpegts.js 动态导入**
-仅在检测到 flv 源时 `await import('mpegts.js')`,避免点播首屏为此多下载约 150KB。
-
-**4. 频道源两种来源并存**
-
-- 用户订阅:复用现有订阅心智(订阅 URL、手动同步、按前缀整体替换),但**独立于采集站订阅模型**存于 `liveSubscriptions`,避免与 `customAPIs` 的 `subKeyPrefix` 命名空间冲突;
-- 部署者预置:新增 `DEFAULT_LIVE_SOURCES` 环境变量,解析逻辑对齐 `src/lib/env-sources.ts`(JSON 数组、解析失败仅告警忽略),经 `/api/status` 下发,沿用 `envKeysSeen` 的「首次自动勾选」策略。
-
-**5. EPG 解析与大对象缓存**
-XMLTV 文件常达数十 MB,不可每次请求拉取:服务端按 `tvg-id` 建立 `Map<channelId, 节目[]>` 后**只保留所需窗口**(当前及未来 24 小时)并丢弃原始文本,写入独立缓存(`src/lib/live-cache.ts`,独立 LRU/TTL 上限)。刻意不复用 `fetch-utils.ts` 的 `getCache/setCache`:其条目超 500 会 `cache.clear()`,EPG 大对象会连带清掉豆瓣等热点数据。M3U 列表用较短 TTL(10 分钟)走通用缓存即可。
-
-**6. 安全与合规**
-
-- 所有直播源 URL 播放前必须过 `checkUpstreamAllowed()`(M3U 内容远程可控,解析期校验不可信);
-- 频道名/logo 由 React 文本渲染天然转义;logo URL 仅放行 http(s),渲染走现有图片代理模式;
-- 不内置任何公共 IPTV 源列表;README 沿用「不存储不制作内容,合法性由数据源负责」声明;
-- 内网自建源(`http://192.168.x.x`)默认仍被 SSRF 拦截,提供显式环境变量 `LIVE_ALLOW_PRIVATE=1` 供自部署者按需开启(默认关闭)。
-
-### 性能要点
-
-- M3U 解析为单趟扫描(O(n)),频道去重按 `url` + `tvg-id`;大列表(数千频道)在服务端裁剪后返回,前端分组用 `useMemo`;
-- EPG 只在用户展开某频道时按需查询该 `tvg-id`,不做全量下发;
-- 频道列表与 EPG 查询接入 react-query(`staleTime` 缓存),避免切台重复请求;
-- 直播流代理为纯流式管道,无内存缓冲累积。
-
-## 目录结构
-
-```
-src/
-├── lib/
-│ ├── m3u-parser.ts # [NEW] M3U/M3U8 播放列表解析:#EXTM3U 校验、#EXTINF 行与 tvg-id/tvg-name/tvg-logo/group-title 属性提取、频道去重、URL 标准化(相对地址按订阅 URL 解析)。导出 parseM3u() 返回 LiveChannel[]。
-│ ├── m3u-parser.test.ts # [NEW] 单测:标准 M3U、无属性简写、相对路径、重复频道去重、异常输入不抛错。对齐 cms-parser.test.ts 风格。
-│ ├── xmltv.ts # [NEW] XMLTV 解析:gzip 解压(zlib.gunzipSync)、<channel id>/<programme channel start stop> 提取、YYYYMMDDHHmmss +0800 时间解析、按 tvg-id 索引、时间窗裁剪(当前至 +24h)。导出 parseXmltv()/pickPrograms()。
-│ ├── xmltv.test.ts # [NEW] 单测:gz 与明文、偏移时区、节目排序、当前/后续节目定位。
-│ ├── live-cache.ts # [NEW] 大对象专用 TTL 缓存(EPG),带条目数与内存上限的自清理,与 fetch-utils 通用缓存隔离。
-│ ├── env-live-sources.ts # [NEW] 解析 DEFAULT_LIVE_SOURCES 环境变量(JSON 数组:name/url/epg),失败仅 console.warn 并忽略,模式对齐 env-sources.ts。
-│ ├── types.ts # [MODIFY] 新增 LiveSourceConfig / LiveChannel / EpgProgram / LivePlaylistResponse / LiveEpgResponse 类型;AuthStatusResponse 增加 defaultLiveSources 字段。
-│ ├── store.ts # [MODIFY] 新增 liveSubscriptions、liveEnvSources、liveFavorites、liveRecent;对应 actions(订阅/同步/移除/整体替换、收藏切换、最近观看记录上限 20);partialize 持久化白名单同步扩展(注意 skipHydration 的 SSR 一致性)。
-│ └── client-api.ts # [MODIFY] 新增 api.livePlaylist(url, force)、api.liveEpg(epgUrl, tvgId)、api.liveTest(url),沿用 request() 的 401/503 处理。
-├── app/
-│ ├── api/
-│ │ ├── live/
-│ │ │ ├── playlist/route.ts # [NEW] 拉取并解析 M3U 订阅 → 分组后的频道 JSON;SSRF 校验 + 通用缓存(TTL 10min)+ force 参数跳过缓存;支持 format=m3u 导出订阅文件。
-│ │ │ ├── epg/route.ts # [NEW] 拉取 XMLTV(含 .gz)→ 解析并按 tvg-id(批量)返回节目窗口;写入 live-cache(TTL 6h)。
-│ │ │ └── stream/[url]/route.ts # [NEW] 直播流专用长连接代理:首字节超时、无总时长限制、no-store、客户端断开即 abort 上游、强制 SSRF 校验、可选 LIVE_ALLOW_PRIVATE 放行内网。
-│ │ └── status/route.ts # [MODIFY] 下发 defaultLiveSources(由 env-live-sources 提供)。
-│ └── live/page.tsx # [NEW] 直播页:左侧播放器 + 右侧频道侧栏(分组筛选/搜索/收藏/最近),底部 EPG 时间轴;URL 参数 ?src=&ch= 支持频道深链与刷新保持。
-├── components/
-│ ├── live-player.tsx # [NEW] 直播播放器:ArtPlayer 直播态配置(隐藏进度/连播/截图/倍速)、扩展名→协议分发(m3u8→hls.js;flv→动态 import mpegts.js)、直连失败自动切 /api/live/stream 重试、错误提示与重载。
-│ ├── live-channel-list.tsx # [NEW] 频道侧栏:分组横向标签条 + 搜索框 + 频道项(台标走现有图片代理、名称、LIVE/收藏标记)、虚拟滚动或分页以应对大列表。
-│ ├── live-epg-panel.tsx # [NEW] EPG 面板:当前节目高亮、进度条、后续节目列表、点击展开简介;无数据时优雅降级。
-│ ├── live-source-manager.tsx # [NEW] 直播源管理(嵌入现有设置抽屉):添加/同步/移除订阅、显示预置源、探活耗时、导出 .m3u。
-│ ├── source-manager.tsx # [MODIFY] 在设置抽屉中新增「直播源」分区并挂载 LiveSourceManager。
-│ └── header.tsx # [MODIFY] 顶部导航新增「直播」HeaderLink(复用现有 HeaderLink 组件与高亮逻辑)。
-├── package.json # [MODIFY] 新增依赖 mpegts.js。
-└── README.md # [MODIFY] 环境变量表格补充 DEFAULT_LIVE_SOURCES / LIVE_ALLOW_PRIVATE;核心特性与免责声明补充直播说明。
-```
-
-## 关键代码结构
-
-```ts
-// src/lib/types.ts 新增(示意)
-export interface LiveSourceConfig {
- key: string;
- name: string;
- url: string; // M3U 订阅地址
- epg?: string; // XMLTV 地址,可选
- builtin?: boolean; // 来自 DEFAULT_LIVE_SOURCES
-}
-
-export interface LiveChannel {
- id: string; // tvg-id 或由 url 生成的稳定 id
- name: string;
- url: string;
- logo?: string;
- group?: string;
- tvgId?: string;
- rawName?: string;
-}
-
-export interface EpgProgram {
- channelId: string;
- start: number; // epoch ms
- stop: number;
- title: string;
- desc?: string;
-}
-```
-
-```ts
-// src/lib/m3u-parser.ts
-export function parseM3u(content: string, baseUrl?: string): LiveChannel[];
-
-// src/lib/xmltv.ts
-export function parseXmltv(content: string | Buffer, windowMs?: number): Map<string, EpgProgram[]>;
-export function currentAndNext(programs: EpgProgram[], at?: number): { current?: EpgProgram; next?: EpgProgram };
-```
-
-## 实施注意事项
-
-- **不改动** `src/app/api/proxy/[url]/route.ts` 与 `src/components/player-shell.tsx` 的点播行为,直播全部走新增文件,blast radius 可控;
-- 直播路由需显式 `export const runtime = 'nodejs'` 与 `export const dynamic = 'force-dynamic'`,避免被静态化或缓存;
-- 流式响应禁用 Next.js 缓冲:不要 `await response.text()`,且勿设置 `content-length`;
-- 新解析器必须补 vitest 单测,`npm test` 是 CI 门禁;
-- 交付前需全部通过:`npm run typecheck`、`npm test`、`npm run lint`、`npm run build`。
-
-## 设计风格
-
-沿用 LibreTV 现有视觉语言(亮暗双主题、半透明毛玻璃导航、蓝色强调色 #2563eb),新增直播模块仅在既有设计系统内扩展,不引入新组件库:全部使用 Tailwind 工具类,复用项目现成的 `Drawer`、`HeaderLink`、`btn / btn-ghost / btn-primary`、`input`、`bg-surface / bg-surface-raised`、`text-content / text-muted / text-faint`、`border-line`、`bg-hover`、`accent` 等既有 class,保证与点播页视觉完全一致。
-
-## 页面:/live(单页,桌面为主、移动端单列自适应)
-
-1. **顶部导航条(复用全局 Header)**:Logo、搜索框(首页外可见)、新增「直播」入口高亮、主题切换、历史、设置;sticky + backdrop-blur。
-2. **主播放区(左侧主栏)**:16:9 纯黑画布,圆角卡片;右下角红色圆点 + "LIVE" 呼吸动效;播放失败时黑色遮罩 + 重试按钮;加载中显示旋转指示器。
-3. **频道信息条(播放器下方)**:当前频道台标(40px 圆角)、频道名、分组标签、EPG 当前节目名与进度条、收藏星标、复制/外部打开按钮。
-4. **频道侧栏(右侧 300px,移动端下移到底部)**:分组横向可滑动标签条(全部 / 央视 / 卫视 / 地方 / 体育...)+ 搜索输入框 + 频道列表项(台标 28px、名称单行截断、LIVE 红点、收藏星);当前播放项左侧蓝色竖条高亮并自动滚动进视区;支持「收藏 / 最近观看」切换 tab。
-5. **EPG 时间轴(侧栏底部或主栏下方)**:当前节目卡片(标题 + 时间 + 简介折叠)+ 「接下来」列表(时间 + 标题),时间轴用细横线 + 已播进度条表示;无 EPG 数据时显示占位文案。
-
-## 交互与动效
-
-- 切台:频道项点击即播,播放器淡入切换,列表高亮平滑过渡;
-- 分组切换:标签条滑动 + 下划线指示器动画;
-- LIVE 标识:红色圆点 2s 周期呼吸;
-- 收藏:星标填充时 0.2s 缩放弹跳;
-- 全部动效时长控制在 150-300ms,与现有 `animate-fade-in` / `animate-slide-up` 保持一致。
\ No newline at end of file