添加跳过片头片尾功能，更新相关组件和文档，支持用户自定义设置

2025-09-02 14:18:44 +08:00
parent 5bbea4f3d5
commit a6bcb72987
5 changed files with 375 additions and 32 deletions
@@ -1,8 +1,44 @@
 <div align="center">
-  <img src="public/logo.png" alt="KatelyaTV Logo" width="128" />
+ ## 📰 项目来源与声明
+
+本项目自「MoonTV」演进而来，为其二创/继承版本，持续维护与改进功能与体验。保留并致谢原作者与社区贡献者；如有授权或版权问题请联系以处理。目标：在原作基础上提供更易部署、更友好、更稳定的体验。
+
+## ✨ 功能特性
+
+### 🎬 核心播放功能
+
+- **🔍 聚合搜索**：整合多个影视资源站，一键搜索全网内容
+- **📺 高清播放**：基于 ArtPlayer 的强大播放器，支持多种格式和画质
+- **⏭️ 智能跳过**：自动检测并跳过片头片尾，手动设置跳过时间段
+- **🎯 断点续播**：自动记录播放进度，跨设备同步观看位置
+- **📱 响应式设计**：完美适配手机、平板、电脑各种屏幕尺寸
+
+### 💾 数据管理
+
+- **⭐ 收藏功能**：收藏喜欢的影视作品，支持跨设备同步
+- **📖 播放历史**：自动记录观看历史，快速找回看过的内容
+- **👥 多用户支持**：独立的用户系统，每个用户独享个人数据
+- **🔄 数据同步**：支持多种存储后端（LocalStorage、Redis、D1、Upstash）
+
+### 🚀 部署与扩展
+
+- **🐳 Docker 一键部署**：提供完整的 Docker 镜像，开箱即用
+- **☁️ 多平台支持**：Vercel、Cloudflare Pages、传统服务器全兼容
+- **🔧 灵活配置**：支持自定义资源站、代理设置、主题配置
+- **📱 PWA 支持**：可安装为桌面/手机应用，离线缓存
+
+### 🎨 用户体验
+
+- **🌓 深色模式**：支持明暗主题切换，护眼舒适
+- **⚡ 性能优化**：智能缓存、懒加载、播放源优选算法
+- **🔐 隐私保护**：本地部署，数据完全掌控
+- **🌍 国际化**：多语言支持（规划中）
+
+## 🚀 部署教程 src="public/logo.png" alt="KatelyaTV Logo" width="128" />
+
  <h1>KatelyaTV</h1>
  <p><strong>跨平台 · 聚合搜索 · 即开即用 · 自托管影视聚合播放器</strong></p>
-  <p>基于 <code>Next.js 14</code> · <code>TypeScript</code> · <code>Tailwind CSS</code> · 多源聚合 / 播放记录 / 收藏同步 / PWA</p>
+  <p>基于 <code>Next.js 14</code> · <code>TypeScript</code> · <code>Tailwind CSS</code> · 多源聚合 / 播放记录 / 收藏同步 / 跳过片头片尾 / PWA</p>
  <p>MoonTV 二创延续版 · 持续维护与增强</p>
  <p>
    <a href="#部署">🚀 部署</a> ·
@@ -33,12 +69,12 @@

 ### 📋 部署方式对比

-| 方式 | 难度 | 成本 | 多用户 | 推荐场景 |
-|------|------|------|--------|----------|
-| 🐳 **Docker 单容器** | ⭐ | 需服务器 | ❌ | 个人使用，最简单 |
-| 🐳 **Docker + Redis** | ⭐⭐ | 需服务器 | ✅ | 家庭/团队，功能完整 |
-| ☁️ **Vercel** | ⭐ | 免费 | ❌ | 临时体验，无服务器 |
-| 🌐 **Cloudflare** | ⭐⭐⭐ | 免费 | ✅ | 技术爱好者 |
+| 方式                  | 难度   | 成本     | 多用户 | 推荐场景            |
+| --------------------- | ------ | -------- | ------ | ------------------- |
+| 🐳 **Docker 单容器**  | ⭐     | 需服务器 | ❌     | 个人使用，最简单    |
+| 🐳 **Docker + Redis** | ⭐⭐   | 需服务器 | ✅     | 家庭/团队，功能完整 |
+| ☁️ **Vercel**         | ⭐     | 免费     | ❌     | 临时体验，无服务器  |
+| 🌐 **Cloudflare**     | ⭐⭐⭐ | 免费     | ✅     | 技术爱好者          |

 </div>

@@ -49,18 +85,21 @@
 > **适合场景**：个人使用，有服务器/NAS/电脑，想要最简单的部署方式

 ### 🔧 前置要求
+
 - 一台能联网的设备（服务器/NAS/Windows/Mac/Linux 都行）
 - 已安装 Docker（[Docker 官网下载](https://www.docker.com/get-started/)）

 ### 📝 详细步骤

 #### 第一步：拉取镜像
+
 ```bash
 # 下载最新版本镜像（支持 ARM 和 x86 架构）
 docker pull ghcr.io/katelya77/katelyatv:latest
 ```

 #### 第二步：启动容器
+
 ```bash
 # 一键启动（请把 your_password 改成你的密码）
 docker run -d \
@@ -74,11 +113,13 @@ docker run -d \
 > **Windows 用户注意**：在 PowerShell 中运行上述命令

 #### 第三步：访问应用
+
 1. 打开浏览器，访问：`http://你的服务器IP:3000`
 2. 如果是本机安装，访问：`http://localhost:3000`
 3. 输入你在第二步设置的密码即可进入

 #### 第四步：自定义资源站（可选）
+
 如果你有自己的资源站配置，可以挂载 `config.json` 文件：

 ```bash
@@ -99,6 +140,7 @@ docker run -d \
 > **Windows 示例**：`-v C:/Users/你的用户名/Desktop/config.json:/app/config.json:ro`

 ### 🛠️ 常用管理命令
+
 ```bash
 # 查看运行状态
 docker ps
@@ -123,12 +165,14 @@ docker rm katelyatv
 > **适合场景**：多人使用，需要账号系统、观看记录同步、收藏功能

 ### 🔧 前置要求
+
 - 已完成方案一，确认单容器版本能正常运行
 - 了解基本的 Docker Compose 概念

 ### 📝 详细步骤

 #### 第一步：创建配置文件
+
 在你的服务器上创建一个文件夹，比如 `/opt/katelyatv`：

 ```bash
@@ -184,11 +228,14 @@ EOF
 ```

 #### 第二步：修改配置
+
 编辑 `docker-compose.yml` 文件，**必须修改**以下内容：
+
 - `PASSWORD=your_strong_password` 改成你的强密码
 - `USERNAME=admin` 可以改成你喜欢的管理员用户名

 #### 第三步：启动服务
+
 ```bash
 # 启动所有服务
 docker compose up -d
@@ -198,12 +245,14 @@ docker compose ps
 ```

 #### 第四步：验证部署
+
 1. 访问 `http://你的服务器IP:3000`
 2. 使用你设置的用户名和密码登录
 3. 登录后访问 `http://你的服务器IP:3000/admin` 进入管理后台
 4. 在管理后台可以配置资源站、管理用户等

 ### 🛠️ 管理命令
+
 ```bash
 # 查看所有服务状态
 docker compose ps
@@ -223,6 +272,7 @@ docker compose up -d
 ```

 ### 💾 备份数据
+
 ```bash
 # 备份 Redis 数据
 docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar czf /backup/redis-backup-$(date +%Y%m%d).tar.gz /data
@@ -238,17 +288,20 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 > **适合场景**：没有服务器，想要快速体验，个人使用

 ### 🔧 前置要求
+
 - GitHub 账号
 - Vercel 账号（可用 GitHub 登录）

 ### 📝 详细步骤

 #### 第一步：Fork 仓库
+
 1. 打开 [KatelyaTV GitHub 页面](https://github.com/katelya77/KatelyaTV)
 2. 点击右上角 **Fork** 按钮
 3. 等待 Fork 完成

 #### 第二步：部署到 Vercel
+
 1. 访问 [Vercel](https://vercel.com/)，用 GitHub 账号登录
 2. 点击 **Add New... → Project**
 3. 找到你刚才 Fork 的 `KatelyaTV` 仓库，点击 **Import**
@@ -258,16 +311,20 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 5. 点击 **Deploy** 开始部署

 #### 第三步：等待部署完成
+
 - 通常需要 2-3 分钟
 - 部署成功后会显示域名，比如 `https://your-project.vercel.app`

 #### 第四步：访问和使用
+
 1. 点击 Vercel 提供的域名链接
 2. 输入你在第二步设置的密码
 3. 开始使用！

 ### 🔧 自定义资源站
+
 如果你想添加自己的资源站：
+
 1. 在你 Fork 的仓库中找到 `config.json` 文件
 2. 点击编辑按钮（铅笔图标）
 3. 修改配置内容
@@ -275,6 +332,7 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 5. Vercel 会自动重新部署

 ### ⚠️ 注意事项
+
 - Vercel 版本不支持用户注册和账号系统
 - 观看记录保存在浏览器本地，换设备会丢失
 - 如果需要多用户功能，请考虑 Docker + Redis 方案
@@ -286,6 +344,7 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 > **适合场景**：技术爱好者，想要全球 CDN 加速，免费但配置复杂

 ### 🔧 前置要求
+
 - GitHub 账号
 - Cloudflare 账号
 - 对前端构建有基本了解
@@ -293,6 +352,7 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 ### 📝 详细步骤

 #### 第一步：Fork 仓库并连接
+
 1. Fork [KatelyaTV 仓库](https://github.com/katelya77/KatelyaTV)
 2. 登录 [Cloudflare](https://cloudflare.com)
 3. 进入 **Workers 和 Pages** → 点击 **创建应用程序**
@@ -300,22 +360,28 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 5. 选择你 Fork 的仓库

 #### 第二步：配置构建设置
+
 在构建设置页面填写：
+
 - **构建命令**: `npm install && npm run pages:build`
 - **构建输出目录**: `.vercel/output/static`
 - **Root directory**: `./`（默认）

 #### 第三步：设置兼容性
+
 1. 点击 **保存并部署**
 2. 等待首次构建完成（可能会失败，没关系）
 3. 进入项目 **设置** → **兼容性标志**
 4. 添加标志: `nodejs_compat`

 #### 第四步：添加环境变量
+
 在 **设置** → **环境变量** 中添加：
+
 - `PASSWORD`: 你的访问密码

 #### 第五步：重新部署
+
 1. 进入 **部署** 页面
 2. 点击最新部署旁的 **...** → **重试部署**
 3. 等待部署成功
@@ -324,17 +390,22 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /

 如果你想要用户系统和数据同步：

+> ⚠️ **升级提醒**：如果你已有 D1 数据库，需要手动添加新功能表。请查看 [D1_MIGRATION.md](./D1_MIGRATION.md) 文件。
+
 #### 第一步：创建 D1 数据库
+
 1. 在 Cloudflare Dashboard 进入 **存储和数据库** → **D1 SQL 数据库**
 2. 点击 **创建数据库**，名称随意（比如 `katelyatv-db`）

 #### 第二步：初始化数据库
+
 1. 进入刚创建的数据库
 2. 点击 **Explore Data**
-3. 打开项目中的 [D1初始化.md](https://github.com/katelya77/KatelyaTV/blob/main/D1%E5%88%9D%E5%A7%8B%E5%8C%96.md) 文件，复制所有 SQL 语句
+3. 打开项目中的 [D1 初始化.md](https://github.com/katelya77/KatelyaTV/blob/main/D1%E5%88%9D%E5%A7%8B%E5%8C%96.md) 文件，复制所有 SQL 语句
 4. 粘贴到查询窗口，点击 **Run All**

 #### 第三步：绑定数据库
+
 1. 回到 Pages 项目设置
 2. 进入 **绑定** → **添加绑定**
 3. 选择 **D1 数据库**
@@ -342,13 +413,17 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 5. 选择你刚创建的数据库

 #### 第四步：添加环境变量
+
 在环境变量中追加：
+
 - `NEXT_PUBLIC_STORAGE_TYPE`: `d1`
 - `USERNAME`: 管理员用户名
 - `PASSWORD`: 管理员密码

 #### 第五步：重新部署
+
 重新部署后，你就可以：
+
 - 使用管理员账号登录
 - 访问 `/admin` 管理后台
 - 支持用户注册和数据同步
@@ -358,6 +433,7 @@ docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar xzf /
 ## 🆙 升级和维护

 ### Docker 升级
+
 ```bash
 # 单容器版本
 docker stop katelyatv
@@ -371,23 +447,26 @@ docker compose up -d
 ```

 ### Vercel 升级
+
 - 自动升级：当原仓库更新时，你的 Fork 仓库会收到更新提示
 - 手动升级：在你的 Fork 仓库点击 **Sync fork** 按钮

 ### Cloudflare 升级
+
 - 同 Vercel，通过 Git 同步自动触发重新构建

 ### 🚨 常见问题排查

-| 问题 | 现象 | 解决方法 |
-|------|------|----------|
-| 无法访问 | 浏览器显示无法连接 | 检查端口 3000 是否开放，防火墙设置 |
-| 403 Forbidden | 显示访问被拒绝 | 检查 PASSWORD 环境变量是否设置正确 |
-| Docker 启动失败 | 容器无法启动 | 查看日志 `docker logs katelyatv` |
-| Redis 连接失败 | 无法登录或保存数据 | 检查 Redis 容器是否正常运行 |
-| 构建失败 | Vercel/Cloudflare 部署失败 | 查看构建日志，检查环境变量设置 |
+| 问题            | 现象                       | 解决方法                           |
+| --------------- | -------------------------- | ---------------------------------- |
+| 无法访问        | 浏览器显示无法连接         | 检查端口 3000 是否开放，防火墙设置 |
+| 403 Forbidden   | 显示访问被拒绝             | 检查 PASSWORD 环境变量是否设置正确 |
+| Docker 启动失败 | 容器无法启动               | 查看日志 `docker logs katelyatv`   |
+| Redis 连接失败  | 无法登录或保存数据         | 检查 Redis 容器是否正常运行        |
+| 构建失败        | Vercel/Cloudflare 部署失败 | 查看构建日志，检查环境变量设置     |

 需要帮助？可以在 [GitHub Issues](https://github.com/katelya77/KatelyaTV/issues) 提问。
+
 ## 🐳 Docker

 推荐方式。镜像多架构 (`linux/amd64`,`linux/arm64`)，基于 Alpine，体积小启动快。
@@ -487,8 +566,50 @@ docker run --rm -v katelyatv_data:/data -v $(pwd):/backup alpine tar czf /backup
 ```

 ## 🐙 Docker Compose 最佳实践
+
 Docker Compose 是管理多容器应用的最佳方式，特别适合需要数据库支持的部署场景。
+
+## 📚 功能使用教程
+
+### ⏭️ 跳过片头片尾功能
+
+KatelyaTV 提供了智能的跳过片头片尾功能，帮助您快速进入正片内容。
+
+#### 🎯 如何使用
+
+1. **自动检测**：系统会自动检测已设置的跳过片段，在观看时显示跳过按钮
+2. **手动设置**：在播放页面标题右侧点击"跳过设置"按钮
+3. **添加片段**：选择片头或片尾类型，设置开始和结束时间
+4. **保存配置**：配置会自动保存并应用到当前剧集
+
+#### ⚙️ 功能特点
+
+- **智能检测**：自动识别播放时间是否在跳过区间内
+- **手动配置**：支持精确设置跳过时间段（精确到秒）
+- **多类型支持**：支持片头、片尾等不同类型的跳过片段
+- **跨设备同步**：配置数据支持多设备同步（需使用 Redis/D1/Upstash 存储）
+- **个性化**：每个用户可独立设置不同的跳过偏好
+
+#### 💾 存储支持
+
+| 存储类型      | 支持状态 | 同步能力  | 推荐场景        |
+| ------------- | -------- | --------- | --------------- |
+| LocalStorage  | ✅       | ❌ 单设备 | 个人本地使用    |
+| Redis         | ✅       | ✅ 多设备 | 家庭/团队使用   |
+| Cloudflare D1 | ✅       | ✅ 多设备 | Cloudflare 部署 |
+| Upstash       | ✅       | ✅ 多设备 | 无服务器部署    |
+
+> ⚠️ **D1 用户注意**：如果你之前已经部署了项目并使用 D1 数据库，需要手动更新数据库表结构才能使用跳过功能。请参考 [D1_MIGRATION.md](./D1_MIGRATION.md) 进行升级。
+
+#### 🛠️ 使用技巧
+
+- **最佳时机**：建议在剧集开始播放后设置，可以实时看到当前播放时间
+- **时间精度**：支持小数点精度，如 `90.5` 秒
+- **批量设置**：一次设置后，所有相同剧集都会应用相同规则
+- **删除管理**：可以随时删除不需要的跳过片段
+
 ## 📁 配置说明
+
 ### 📝 LocalStorage（基础单机）

 适合个人使用，数据存储在浏览器本地：
@@ -512,7 +633,15 @@ services:
    # volumes:
    #   - ./config.json:/app/config.json:ro
    healthcheck:
-      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000"]
+      test:
+        [
+          'CMD',
+          'wget',
+          '--quiet',
+          '--tries=1',
+          '--spider',
+          'http://localhost:3000',
+        ]
      interval: 30s
      timeout: 10s
      retries: 3
@@ -520,6 +649,7 @@ services:
 ```

 **启动命令：**
+
 ```bash
 # 创建并启动服务
 docker compose up -d
@@ -550,18 +680,18 @@ services:
      # 基础配置
      - SITE_NAME=KatelyaTV 影视站
      - ANNOUNCEMENT=支持多用户注册，请合理使用！
-      
+
      # 管理员账号（重要！）
      - USERNAME=admin
      - PASSWORD=admin_super_secure_password
-      
+
      # Redis 存储配置
      - NEXT_PUBLIC_STORAGE_TYPE=redis
      - REDIS_URL=redis://katelyatv-redis:6379
-      
+
      # 用户功能
      - NEXT_PUBLIC_ENABLE_REGISTER=true
-      
+
      # 可选：搜索配置
      - NEXT_PUBLIC_SEARCH_MAX_PAGE=8
    networks:
@@ -574,7 +704,15 @@ services:
    #   - ./config.json:/app/config.json:ro
    #   - ./logs:/app/logs
    healthcheck:
-      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000"]
+      test:
+        [
+          'CMD',
+          'wget',
+          '--quiet',
+          '--tries=1',
+          '--spider',
+          'http://localhost:3000',
+        ]
      interval: 30s
      timeout: 10s
      retries: 3
@@ -591,7 +729,7 @@ services:
      # Redis 数据持久化
      - katelyatv-redis-data:/data
    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
+      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3
@@ -693,6 +831,7 @@ docker compose down -v --remove-orphans
 ### 🛠️ 常见部署问题排查

 **问题 1：容器启动失败**
+
 ```bash
 # 检查容器状态
 docker compose ps
@@ -704,6 +843,7 @@ docker compose logs katelyatv
 ```

 **问题 2：Redis 连接失败**
+
 ```bash
 # 检查 Redis 容器状态
 docker compose exec katelyatv-redis redis-cli ping
@@ -716,6 +856,7 @@ docker compose exec katelyatv env | grep REDIS
 ```

 **问题 3：Upstash Redis 连接问题**
+
 ```bash
 # 验证 Upstash 配置
 curl -H "Authorization: Bearer YOUR_TOKEN" YOUR_UPSTASH_URL/ping
@@ -726,11 +867,13 @@ echo $UPSTASH_TOKEN  # 应该是长字符串令牌
 ```

 **问题 4：Cloudflare D1 初始化失败**
+
 - 确保在 D1 控制台中正确执行了所有 SQL 语句
 - 检查数据库绑定名称是否为 `DB`
 - 验证环境变量 `NEXT_PUBLIC_STORAGE_TYPE=d1`

 **问题 5：Vercel 部署问题**
+
 - 检查环境变量是否正确设置
 - 确保 `config.json` 文件格式正确
 - 查看 Vercel 部署日志中的错误信息
@@ -767,10 +910,11 @@ echo $UPSTASH_TOKEN  # 应该是长字符串令牌
 1. **访问服务状态页**：`http://your-domain/api/server-config`
 2. **检查管理员面板**：使用管理员账号登录后访问 `/admin`
 3. **查看容器日志**：
+
   ```bash
   # Docker 单容器
   docker logs katelyatv
-   
+
   # Docker Compose
   docker compose logs katelyatv
   ```
@@ -896,7 +1040,7 @@ KatelyaTV 支持标准的苹果 CMS V10 API 格式。

 - [ts-nextjs-tailwind-starter](https://github.com/theodorusclarence/ts-nextjs-tailwind-starter) — 项目最初基于该脚手架。
 - [LibreTV](https://github.com/LibreSpark/LibreTV) — 由此启发，站在巨人的肩膀上。
- [LunaTV-原MoonTV](https://github.com/MoonTechLab/LunaTV) — 原始项目与作者社区，感谢原作奠定坚实基础。
+- [LunaTV-原 MoonTV](https://github.com/MoonTechLab/LunaTV) — 原始项目与作者社区，感谢原作奠定坚实基础。
 - [ArtPlayer](https://github.com/zhw2590582/ArtPlayer) — 提供强大的网页视频播放器。
 - [HLS.js](https://github.com/video-dev/hls.js) — 实现 HLS 流媒体在浏览器中的播放支持。
 - 感谢所有提供免费影视接口的站点。