yeyin/KatelyaTV
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: remove outdated documentation and fix overlay issue in SkipController

Browse Source 
- Deleted SKIP_CONTROLLER_TEST.md and SKIP_CONTROLLER_UPDATE.md as they are no longer relevant.
- Removed SKIP_FEATURE_GUIDE.md to streamline user documentation.
- Eliminated SKIP_OVERLAY_FIX.md after addressing the click offset issue caused by the SkipController overlay.
- Improved user experience by ensuring the SkipController does not interfere with episode selection.
This commit is contained in:
katelya
2025-09-04 18:10:59 +08:00
parent 82485d1939
commit 22c68b7e19
14 changed files with 578 additions and 3106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
D1初始化.md
-94
View File
@@ -1,94 +0,0 @@
```sql
CREATE TABLE IF NOT EXISTS users (
username TEXT PRIMARY KEY,
password TEXT NOT NULL,
created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
);
CREATE TABLE IF NOT EXISTS play_records (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
key TEXT NOT NULL,
title TEXT NOT NULL,
source_name TEXT NOT NULL,
cover TEXT NOT NULL,
year TEXT NOT NULL,
index_episode INTEGER NOT NULL,
total_episodes INTEGER NOT NULL,
play_time INTEGER NOT NULL,
total_time INTEGER NOT NULL,
save_time INTEGER NOT NULL,
search_title TEXT,
UNIQUE(username, key)
);
CREATE TABLE IF NOT EXISTS favorites (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
key TEXT NOT NULL,
title TEXT NOT NULL,
source_name TEXT NOT NULL,
cover TEXT NOT NULL,
year TEXT NOT NULL,
total_episodes INTEGER NOT NULL,
save_time INTEGER NOT NULL,
UNIQUE(username, key)
);
CREATE TABLE IF NOT EXISTS search_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
keyword TEXT NOT NULL,
created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
UNIQUE(username, keyword)
);
CREATE TABLE IF NOT EXISTS admin_config (
id INTEGER PRIMARY KEY DEFAULT 1,
config TEXT NOT NULL,
updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
);
CREATE TABLE IF NOT EXISTS skip_configs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
username TEXT NOT NULL,
key TEXT NOT NULL,
source TEXT NOT NULL,
video_id TEXT NOT NULL,
title TEXT NOT NULL,
segments TEXT NOT NULL,
updated_time INTEGER NOT NULL,
UNIQUE(username, key)
);
-- 基本索引
CREATE INDEX IF NOT EXISTS idx_play_records_username ON play_records(username);
CREATE INDEX IF NOT EXISTS idx_favorites_username ON favorites(username);
CREATE INDEX IF NOT EXISTS idx_search_history_username ON search_history(username);
CREATE INDEX IF NOT EXISTS idx_skip_configs_username ON skip_configs(username);
-- 复合索引优化查询性能
-- 播放记录：用户名+键值的复合索引，用于快速查找特定记录
CREATE INDEX IF NOT EXISTS idx_play_records_username_key ON play_records(username, key);
-- 播放记录：用户名+保存时间的复合索引，用于按时间排序的查询
CREATE INDEX IF NOT EXISTS idx_play_records_username_save_time ON play_records(username, save_time DESC);
-- 收藏：用户名+键值的复合索引，用于快速查找特定收藏
CREATE INDEX IF NOT EXISTS idx_favorites_username_key ON favorites(username, key);
-- 收藏：用户名+保存时间的复合索引，用于按时间排序的查询
CREATE INDEX IF NOT EXISTS idx_favorites_username_save_time ON favorites(username, save_time DESC);
-- 搜索历史：用户名+关键词的复合索引，用于快速查找/删除特定搜索记录
CREATE INDEX IF NOT EXISTS idx_search_history_username_keyword ON search_history(username, keyword);
-- 搜索历史：用户名+创建时间的复合索引，用于按时间排序的查询
CREATE INDEX IF NOT EXISTS idx_search_history_username_created_at ON search_history(username, created_at DESC);
-- 搜索历史清理查询的优化索引
CREATE INDEX IF NOT EXISTS idx_search_history_username_id_created_at ON search_history(username, id, created_at DESC);
-- 跳过配置索引
-- 跳过配置：用户名+键值的复合索引，用于快速查找特定配置
CREATE INDEX IF NOT EXISTS idx_skip_configs_username_key ON skip_configs(username, key);
-- 跳过配置：用户名+更新时间的复合索引，用于按时间排序的查询
CREATE INDEX IF NOT EXISTS idx_skip_configs_username_updated_time ON skip_configs(username, updated_time DESC);
```
DEPLOYMENT_COMPATIBILITY.md
-226
View File
@@ -1,226 +0,0 @@
# 🚀 部署兼容性说明
## 跳过片头片尾功能部署兼容性
我们的跳过片头片尾功能已经完全兼容各种部署方式，具体如下：
## 📋 功能概述
- ✅ **自动跳过片头片尾** - 智能检测并跳过重复内容
- ✅ **手动配置跳过段** - 用户可自定义跳过时间段
- ✅ **多剧集支持** - 每个剧集独立配置
- ✅ **多存储后端** - 支持 LocalStorage、Redis、D1、Upstash
## 🌐 部署方式兼容性
### 1. Cloudflare Pages ✅
**Runtime**: Edge Runtime
**配置要求**: 所有 API 路由必须使用 `export const runtime = 'edge';`
```typescript
// ✅ 已正确配置
export const runtime = 'edge';
```
**特性支持**:
- ✅ 跳过配置 API (`/api/skip-configs`)
- ✅ 所有存储后端（D1、Redis、Upstash）
- ✅ 自动缓存优化
### 2. Docker 部署 ✅
**Runtime**: Node.js Runtime (自动转换)
**自动转换**: Dockerfile 会自动将 Edge Runtime 转换为 Node.js Runtime
```dockerfile
# Dockerfile 中的自动转换逻辑
RUN find ./src -type f -name "route.ts" -print0 \
| xargs -0 sed -i "s/export const runtime = 'edge';/export const runtime = 'nodejs';/g"
```
**特性支持**:
- ✅ 跳过配置 API
- ✅ 所有存储后端
- ✅ 环境变量配置
- ✅ 健康检查
### 3. Vercel 部署 ✅
**Runtime**: Edge Runtime / Node.js Runtime (自动检测)
**配置**: 无需特殊配置，自动适配
**特性支持**:
- ✅ 跳过配置 API
- ✅ 所有存储后端
- ✅ Serverless 函数优化
### 4. 其他部署方式 ✅
**Runtime**: Node.js Runtime
**要求**: Node.js 18+ 环境
**支持的部署方式**:
- ✅ 传统服务器部署
- ✅ PM2 进程管理
- ✅ Nginx 反向代理
- ✅ Kubernetes
- ✅ Railway、Render 等云平台
## 🗄️ 存储后端支持
### LocalStorage (默认)
```bash
# 无需额外配置，适用于单机部署
NEXT_PUBLIC_STORAGE_TYPE=localstorage
```
### Redis
```bash
# 高性能缓存存储
NEXT_PUBLIC_STORAGE_TYPE=redis
REDIS_URL=redis://localhost:6379
```
### Cloudflare D1
```bash
# Cloudflare 原生数据库
NEXT_PUBLIC_STORAGE_TYPE=d1
```
### Upstash Redis
```bash
# 无服务器 Redis
NEXT_PUBLIC_STORAGE_TYPE=upstash
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxx
```
## 🔧 环境变量配置
### 核心配置
```bash
# 存储类型 (必需)
NEXT_PUBLIC_STORAGE_TYPE=localstorage|redis|d1|upstash
# Docker 环境标识 (Docker 部署时自动设置)
DOCKER_ENV=true
```
### 存储特定配置
```bash
# Redis
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=optional
# Upstash
UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxx
# D1 (Cloudflare 自动注入)
# 无需手动配置
```
## 🚀 快速部署指南
### Cloudflare Pages
1. 连接 GitHub 仓库
2. 设置构建命令: `npm run build`
3. 设置输出目录: `.next`
4. 配置环境变量 (可选)
### Docker
```bash
# 构建镜像
docker build -t katelyatv .
# 运行容器
docker run -p 3000:3000 \
-e NEXT_PUBLIC_STORAGE_TYPE=localstorage \
katelyatv
```
### Vercel
```bash
# 一键部署
npx vercel
# 或使用 Vercel CLI
vercel --prod
```
## 🧪 兼容性测试
运行兼容性测试脚本：
```bash
# 测试所有部署方式的兼容性
node scripts/test-docker-compatibility.js
```
## ⚠️ 注意事项
1. **Edge Runtime 限制**: 在 Cloudflare Pages 上，所有 API 路由必须使用 Edge Runtime
2. **存储选择**: 根据部署环境选择合适的存储后端
3. **环境变量**: 确保在生产环境中正确配置存储相关环境变量
4. **缓存策略**: LocalStorage 仅适用于单机部署，集群部署请使用 Redis
## 📊 性能建议
### 小型部署 (< 1000 用户)
- **推荐**: LocalStorage
- **优点**: 零配置，性能良好
- **缺点**: 仅支持单机
### 中型部署 (1000-10000 用户)
- **推荐**: Redis
- **优点**: 高性能，支持集群
- **缺点**: 需要 Redis 服务器
### 大型部署 (> 10000 用户)
- **推荐**: Cloudflare D1 + Redis 缓存
- **优点**: 高可用，全球分布
- **缺点**: 依赖 Cloudflare
## 🆘 故障排除
### 常见问题
1. **API 路由 404**
- 检查 Edge Runtime 配置
- 确认部署环境支持
2. **跳过配置保存失败**
- 检查存储后端配置
- 验证环境变量设置
3. **Docker 构建失败**
- 确认 Node.js 版本 ≥ 18
- 检查 pnpm 安装
4. **Cloudflare Pages 部署失败**
- 确认所有 API 路由有 Edge Runtime 配置
- 检查构建命令和输出目录
---
🎉 **恭喜！** 您的跳过片头片尾功能已完全兼容所有主流部署方式！
DEPLOYMENT_COMPLETION_REPORT.md
-174
View File
@@ -1,174 +0,0 @@
# 🎯 KatelyaTV 部署方案完善工作总结
## 📋 任务完成情况
### ✅ 已完成的主要任务
1. **🔧 修复 Kvrocks 部署问题**
- 解决了用户反馈的密码认证错误问题
- 优化了密码处理逻辑，支持无密码和密码认证两种模式
- 创建了详细的修复报告和部署指南
2. **📁 完善所有部署配置文件**
- Docker + Redis: `docker-compose.redis.yml` + `.env.redis.example`
- Docker + Kvrocks (无密码): `docker-compose.kvrocks.yml` + `.env.kvrocks.example`
- Docker + Kvrocks (密码认证): `docker-compose.kvrocks.auth.yml`
- Cloudflare Pages + D1: `wrangler.toml` + `.env.cloudflare.example` + `scripts/d1-init.sql`
- 所有配置文件都经过验证，确保可以正常使用
3. **📖 更新 README.md 文档**
- 添加了 Kvrocks 修复说明
- 完善了所有部署方案的引用
- 创建了部署对比表格，包含配置文件列表
- 添加了故障排除章节
4. **🛠️ 创建验证和测试工具**
- `scripts/test-kvrocks-deployment.js` - Kvrocks 部署测试脚本
- `scripts/verify-kvrocks-fix.js` - 密码修复验证脚本
- `scripts/check-deployment-configs.js` - 全方案配置检查脚本
- `scripts/d1-init.sql` - D1 数据库初始化脚本
5. **🔍 解决 VSCode 问题**
- 修复了脚本文件中的 ESLint 错误
- 创建了 `scripts/.eslintrc.js` 配置文件
- 通过了所有代码质量检查（ESLint、TypeScript）
## 📊 部署方案总览
| 部署方案 | 配置文件 | 状态 | 适用场景 |
| -------------------------- | --------------------------------- | ------- | -------------------- |
| 🐳 Docker 单容器 | 无需配置文件 | ✅ 完成 | 个人使用，最简单 |
| 🐳 Docker + Redis | `docker-compose.redis.yml` | ✅ 完成 | 家庭/团队使用 |
| 🏪 Docker + Kvrocks | `docker-compose.kvrocks.yml` | ✅ 完成 | 生产环境，高可靠性 |
| 🏪 Docker + Kvrocks (认证) | `docker-compose.kvrocks.auth.yml` | ✅ 完成 | 安全要求高的生产环境 |
| ☁️ Vercel + Upstash | `vercel.json` | ✅ 完成 | 免费云端部署 |
| 🌐 Cloudflare + D1 | `wrangler.toml` | ✅ 完成 | 免费云端，技术爱好者 |
## 🎯 关键修复内容
### 1. Kvrocks 密码认证问题修复
**问题描述**：
```
❌ Kvrocks Client Error: [Error]: ERR Client sent AUTH, but no password is set
```
**修复方案**：
- 优化客户端密码处理逻辑，只有当密码非空时才进行认证
- 提供两种部署模式：无密码（开发）和密码认证（生产）
- 添加详细的调试日志，便于排查问题
**核心代码修复**（`src/lib/kvrocks.db.ts`）：
```typescript
// 只有当密码存在且不为空时才添加密码配置
if (kvrocksPassword && kvrocksPassword.trim() !== '') {
clientConfig.password = kvrocksPassword;
console.log('🔐 Using password authentication');
} else {
console.log('🔓 No password authentication (connecting without password)');
}
```
### 2. 部署配置完善
**创建的新文件**：
- `docker-compose.redis.yml` - Redis 部署配置
- `docker-compose.kvrocks.auth.yml` - Kvrocks 密码认证配置
- `wrangler.toml` - Cloudflare Pages 配置
- 各种 `.env.*.example` 环境变量示例文件
### 3. 文档和工具完善
**新增文档**：
- `docs/KVROCKS_DEPLOYMENT.md` - Kvrocks 详细部署指南
- `KVROCKS_FIX_REPORT.md` - 问题修复详细报告
**新增工具脚本**：
- 部署测试和验证脚本
- 配置完整性检查脚本
- D1 数据库初始化脚本
## 🧪 质量验证
### 代码质量检查
- ✅ ESLint 检查通过（0 errors, 0 warnings）
- ✅ TypeScript 类型检查通过
- ✅ 所有测试脚本运行正常
### 配置完整性检查
- ✅ 26 项配置检查通过
- ⚠️ 2 项警告（不影响基本功能）
- ❌ 0 项失败
### 部署方案验证
- ✅ Docker + Redis 配置验证通过
- ✅ Docker + Kvrocks 配置验证通过（两种模式）
- ✅ Cloudflare Pages 配置验证通过
- ✅ Vercel 配置验证通过
## 🚀 用户体验改进
### 1. 清晰的部署选择指南
- 根据用户需求和技术水平提供推荐方案
- 详细的对比表格，包含难度、成本、功能等维度
### 2. 完善的故障排除
- 针对常见问题提供解决方案
- 提供调试工具和日志查看方法
- 详细的文档引用和帮助指南
### 3. 一键部署体验
- 所有配置文件都可以直接下载使用
- 提供验证脚本确保配置正确性
- 详细的步骤说明，降低部署门槛
## 📝 后续建议
1. **监控用户反馈**
- 关注 GitHub Issues 中的部署问题
- 根据用户反馈持续优化配置文件
2. **定期测试验证**
- 定期运行验证脚本确保配置有效性
- 测试新版本的兼容性
3. **文档持续更新**
- 根据新功能更新部署文档
- 添加更多故障排除案例
4. **工具脚本优化**
- 增加更多自动化检查功能
- 提供一键修复常见问题的脚本
## 🎉 总结
本次工作成功解决了用户反馈的 Kvrocks 部署问题，并完善了所有部署方案的配置文件和文档。所有部署方案都经过验证，可以正常使用。用户现在可以根据自己的需求选择最适合的部署方案，享受稳定可靠的影视播放服务。
**主要成果**：
- 🔧 修复了关键的 Kvrocks 认证问题
- 📁 完善了 6 种部署方案的完整配置
- 📖 提供了详细的文档和故障排除指南
- 🛠️ 创建了多个验证和测试工具
- ✅ 通过了全面的质量检查
所有修改都经过充分测试，确保向后兼容性和稳定性。用户可以放心升级和部署。
DOCKER_TROUBLESHOOTING.md
-124
View File
@@ -1,124 +0,0 @@
# Docker + Kvrocks 部署故障排除指南
## 🐛 常见问题及解决方案
### 问题一：`failed to read dockerfile: open Dockerfile: no such file or directory`
**症状**：
```bash
docker compose -f docker-compose.kvrocks.yml up -d
# 报错：failed to read dockerfile: open Dockerfile: no such file or directory
```
**原因**：
- 使用了旧版本的 `docker-compose.kvrocks.yml` 文件
- 旧版本使用 `build: .` 需要完整源代码和 Dockerfile
- 但部署文档只让下载配置文件，没有下载源代码
**解决方案**：
#### 方案一：使用预构建镜像（推荐）
```bash
# 重新下载最新版本的配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/docker-compose.kvrocks.yml
# 启动服务
docker compose -f docker-compose.kvrocks.yml up -d
```
最新版本使用 `image: ghcr.io/katelya77/katelyatv:latest`，无需本地构建。
#### 方案二：本地构建
如果想要从源代码构建：
```bash
# 克隆完整源代码
git clone https://github.com/katelya77/KatelyaTV.git
cd KatelyaTV
# 使用本地构建版本
docker compose -f docker-compose.kvrocks.local.yml up -d
```
### 问题二：Kvrocks 连接失败
**症状**：
```bash
# 应用日志显示连接 Kvrocks 失败
Error: connect ECONNREFUSED
```
**解决方案**：
1. 检查 `.env` 文件中的 `KVROCKS_URL` 是否正确：
```bash
KVROCKS_URL=redis://kvrocks:6666
```
2. 确保 Kvrocks 服务正常运行：
```bash
docker compose -f docker-compose.kvrocks.yml ps
```
3. 测试 Kvrocks 连接：
```bash
docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 ping
```
### 问题三：环境变量配置错误
**常见错误**：
- `NEXTAUTH_SECRET` 未设置
- `KVROCKS_PASSWORD` 不匹配
**解决方案**：
检查 `.env` 文件，确保所有必要变量都已正确配置：
```bash
# 必须配置的变量
NEXT_PUBLIC_STORAGE_TYPE=kvrocks
KVROCKS_URL=redis://kvrocks:6666
KVROCKS_PASSWORD=your_secure_password_here
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000
```
## 🔧 调试命令
```bash
# 查看服务状态
docker compose -f docker-compose.kvrocks.yml ps
# 查看应用日志
docker compose -f docker-compose.kvrocks.yml logs -f katelyatv
# 查看 Kvrocks 日志
docker compose -f docker-compose.kvrocks.yml logs -f kvrocks
# 进入容器调试
docker compose -f docker-compose.kvrocks.yml exec katelyatv sh
# 重建服务
docker compose -f docker-compose.kvrocks.yml up -d --force-recreate
```
## 📞 获取帮助
如果以上方案都无法解决问题，请：
1. 提供完整的错误日志
2. 说明使用的配置文件版本
3. 提供系统环境信息（操作系统、Docker 版本等）
---
**文档版本**：v0.6.0-katelya
**更新日期**：2025 年 9 月 3 日
EPISODE_CLICK_DEEP_FIX.md
-147
View File
@@ -1,147 +0,0 @@
# 选集点击偏移问题的深度修复
## 问题复现
用户点击第 6 集（紫色框框），但系统选择了第 7 集（绿色填充），存在点击偏移问题。
## 深度分析与修复
### 🔍 问题根因分析
经过多轮调试，发现问题有**多个层面**：
#### 1. CSS Grid 布局问题
```css
/* 问题代码 */
grid-cols-[repeat(auto-fill,minmax(40px,1fr))]
/* 问题分析 */
- minmax(40px,1fr) 中的 1fr 导致按钮宽度不固定
- 在不同屏幕宽度下，按钮实际宽度变化很大
- 视觉按钮位置与点击区域不匹配
```
#### 2. 事件处理逻辑问题
```javascript
// 问题代码
const handleEpisodeChange = (episodeNumber: number) => {
if (episodeNumber >= 0 && episodeNumber < totalEpisodes) {
setCurrentEpisodeIndex(episodeNumber); // 错误！
}
};
// 问题分析
- EpisodeSelector传递的是显示集数(1-based): 1, 2, 3, 4, 5, 6, 7...
- 但直接设置为currentEpisodeIndex(0-based): 0, 1, 2, 3, 4, 5, 6...
- 导致点击第6集实际设置为index=6，对应第7集
```
#### 3. 可能的覆盖层问题
- SkipController 的固定定位面板可能覆盖选集区域
- 已移动到左下角，但可能不彻底
### 🔧 完整修复方案
#### 修复 1: CSS 布局优化
```tsx
// 修复前
<div className='grid grid-cols-[repeat(auto-fill,minmax(40px,1fr))] auto-rows-[40px] gap-x-3 gap-y-3'>
// 修复后
<div className='grid grid-cols-[repeat(auto-fill,48px)] justify-center gap-3'>
```
**效果**：
- 每个按钮固定 48px 宽度
- 使用 justify-center 居中对齐
- 消除弹性宽度导致的位置偏移
#### 修复 2: 事件处理修正
```tsx
// 修复前
const handleEpisodeChange = (episodeNumber: number) => {
if (episodeNumber >= 0 && episodeNumber < totalEpisodes) {
setCurrentEpisodeIndex(episodeNumber); // 直接使用显示集数作为索引
}
};
// 修复后
const handleEpisodeChange = (episodeNumber: number) => {
const episodeIndex = episodeNumber - 1; // 转换：显示集数 -> 数组索引
if (episodeIndex >= 0 && episodeIndex < totalEpisodes) {
setCurrentEpisodeIndex(episodeIndex);
}
};
```
**效果**：
- 正确处理集数显示值到数组索引的转换
- 点击第 6 集 → episodeNumber=6 → episodeIndex=5 → 正确选择第 6 集
#### 修复 3: 增强事件控制
```tsx
// 添加更强的事件控制
onClick={(e) => {
e.preventDefault();
e.stopPropagation();
handleEpisodeClick(episodeNumber);
}}
```
### 🎯 修复验证
#### 数据流验证
1. **用户点击第 6 集按钮**
2. **EpisodeSelector.tsx**: `handleEpisodeClick(6)` → `onChange(6)`
3. **play/page.tsx**: `handleEpisodeChange(6)` → `episodeIndex = 6-1 = 5`
4. **状态更新**: `setCurrentEpisodeIndex(5)` → 选中第 6 集（index=5）
5. **UI 更新**: `value={currentEpisodeIndex + 1} = 5+1 = 6` → 第 6 集高亮
#### 布局验证
- 固定 48px 宽度确保按钮大小一致
- justify-center 确保居中对齐
- gap-3 提供合适的间距
### 📁 修改文件
1. **src/components/EpisodeSelector.tsx**
- 修复 CSS Grid 布局：固定按钮宽度
- 增强点击事件处理
2. **src/app/play/page.tsx**
- 修复 handleEpisodeChange 逻辑错误
- 正确处理显示集数到索引的转换
3. **src/components/SkipController.tsx**
- 移动固定面板位置（之前已修复）
### 🚀 预期效果
修复后的行为：
- ✅ 点击第 1 集 → 选择第 1 集
- ✅ 点击第 6 集 → 选择第 6 集
- ✅ 点击第 7 集 → 选择第 7 集
- ✅ 按钮布局美观，宽度一致
- ✅ 不受屏幕宽度影响
### 💡 经验总结
1. **UI 显示值 vs 数据索引**：要区分用户看到的值(1-based)和内部索引(0-based)
2. **CSS 弹性布局**：在需要精确点击的场景下，避免使用 1fr 等弹性单位
3. **多层问题**：复杂 bug 可能有多个层面的原因，需要逐层排查
4. **事件处理**：添加 preventDefault 和 stopPropagation 增强控制
这次修复解决了根本问题，确保点击精确性和用户体验。
EPISODE_SELECTOR_FIX.md
-81
View File
@@ -1,81 +0,0 @@
# 选集点击偏移 Bug 修复
## 问题描述
用户报告在选集界面中，点击第 6 集（紫色框框选中的区域）时，系统错误地选择了第 7 集（绿色填充的区域）。这是一个经典的点击目标偏移问题。
## 根因分析
1. **CSS 网格布局问题**：原来使用 `grid-cols-[repeat(auto-fill,minmax(40px,1fr))]`
- `1fr` 使每个按钮占据相同的可用空间
- 这导致视觉按钮大小和实际点击区域不匹配
- auto-fill 在某些屏幕尺寸下可能导致不可预测的布局
2. **点击事件处理**：原有的点击处理没有足够的事件控制
## 修复方案
### 1. 布局修复
将 CSS 网格布局改为 Flexbox 布局：
```css
/* 原来的布局 */
grid grid-cols-[repeat(auto-fill,minmax(40px,1fr))] auto-rows-[40px] gap-x-3 gap-y-3
/* 修复后的布局 */
flex flex-wrap justify-start gap-3
```
### 2. 按钮尺寸固定
- 设置固定的按钮尺寸：`w-12 h-10`（48px × 40px）
- 添加 `flex-shrink-0` 确保按钮不会收缩
- 使用明确的尺寸避免布局计算错误
### 3. 点击事件优化
```javascript
onClick={(e) => {
e.preventDefault();
e.stopPropagation();
handleEpisodeClick(episodeNumber);
}}
```
- 添加 `preventDefault()` 和 `stopPropagation()` 防止事件冒泡
- 设置 `type="button"` 明确按钮类型
- 添加聚焦样式 `focus:ring-2 focus:ring-green-400`
### 4. 样式改进
- 添加 `border-0 outline-none` 移除默认边框
- 保持悬停和选中状态的视觉反馈
- 确保按钮在所有主题下都有清晰的视觉边界
## 预期效果
修复后，用户点击哪个集数按钮就会选择对应的集数，不再出现点击偏移的问题。每个按钮都有：
- 精确的 48px 宽度和 40px 高度
- 清晰的点击边界
- 正确的事件处理
- 良好的视觉反馈
## 测试方法
1. 打开任意多集剧集的播放页面
2. 在选集面板中点击不同的集数按钮
3. 验证点击的集数和实际选中的集数是否一致
4. 测试不同屏幕尺寸下的表现
5. 验证键盘导航和聚焦状态
## 技术细节
- 文件位置：`src/components/EpisodeSelector.tsx`
- 主要修改：布局从 CSS Grid 改为 Flexbox
- 兼容性：保持所有现有功能不变
- 性能：无性能影响，反而可能更好
这个修复确保了点击精确性，解决了用户体验问题。
KVROCKS_FIX_REPORT.md
-148
View File
@@ -1,148 +0,0 @@
# 🐛 Kvrocks 部署问题修复报告
## 📋 问题描述
用户反馈在使用 Docker + Kvrocks 部署方案时遇到以下错误：
```
❌ Kvrocks Client Error: [Error]: ERR Client sent AUTH, but no password is set
```
## 🔍 问题分析
### 根本原因
当环境变量 `KVROCKS_PASSWORD` 被设置为空字符串时，Redis 客户端仍然会尝试进行密码认证，但 Kvrocks 服务端没有配置密码，导致认证失败。
### 问题场景
1. **用户配置**：`KVROCKS_PASSWORD=` 或 `KVROCKS_PASSWORD=""`
2. **Docker Compose**：`${KVROCKS_PASSWORD:-}` 解析为空字符串
3. **Kvrocks 服务**：没有设置 `requirepass`，不需要密码认证
4. **客户端行为**：检测到 `password: ""` 参数，尝试发送 AUTH 命令
5. **服务端响应**：`ERR Client sent AUTH, but no password is set`
## 🔧 修复方案
### 1. 客户端密码处理优化
修改 `src/lib/kvrocks.db.ts` 中的客户端创建逻辑：
```typescript
// 修复前（有问题）
kvrocksClient = createClient({
url: kvrocksUrl,
password: kvrocksPassword, // 即使为空字符串也会尝试认证
database: kvrocksDatabase,
// ...
});
// 修复后（正确）
const clientConfig = {
url: kvrocksUrl,
database: kvrocksDatabase,
// ...
};
// 只有当密码存在且不为空时才添加密码配置
if (kvrocksPassword && kvrocksPassword.trim() !== '') {
clientConfig.password = kvrocksPassword;
console.log('🔐 Using password authentication');
} else {
console.log('🔓 No password authentication (connecting without password)');
}
kvrocksClient = createClient(clientConfig);
```
### 2. Docker Compose 配置分离
创建两个独立的部署配置：
- **无密码部署**：`docker-compose.kvrocks.yml`（开发环境推荐）
- **密码认证部署**：`docker-compose.kvrocks.auth.yml`（生产环境推荐）
### 3. 环境变量示例更新
更新 `.env.kvrocks.example` 提供清晰的配置指导：
```bash
# 选项1：不使用密码（推荐用于开发环境）
# KVROCKS_PASSWORD=
# 选项2：使用密码（推荐用于生产环境）
# KVROCKS_PASSWORD=your_secure_password_here
```
## ✅ 修复验证
### 测试场景覆盖
修复已通过以下场景验证：
1. ✅ **空字符串密码**：`KVROCKS_PASSWORD=""`
2. ✅ **未设置密码**：`KVROCKS_PASSWORD` 未定义
3. ✅ **有效密码**：`KVROCKS_PASSWORD="validpassword"`
4. ✅ **空格密码**：`KVROCKS_PASSWORD=" "`
### 验证工具
提供验证脚本 `scripts/verify-kvrocks-fix.js` 用于测试修复效果。
## 📚 部署指南
### 快速修复（现有部署）
如果您已经遇到此问题：
1. **停止服务**
```bash
docker-compose down
```
2. **更新代码**
```bash
git pull origin main
```
3. **清理环境变量**
```bash
# 编辑 .env 文件，确保 KVROCKS_PASSWORD 设置正确
# 选择以下之一：
# KVROCKS_PASSWORD= # 无密码
# KVROCKS_PASSWORD=your_password # 有密码
```
4. **重新启动**
```bash
# 无密码部署
docker-compose -f docker-compose.kvrocks.yml up -d
# 或密码认证部署
docker-compose -f docker-compose.kvrocks.auth.yml up -d
```
### 新部署
请参考 [docs/KVROCKS_DEPLOYMENT.md](../docs/KVROCKS_DEPLOYMENT.md) 获取完整部署指南。
## 🚀 改进效果
修复后的部署将：
- ✅ 消除密码认证错误
- ✅ 支持灵活的密码配置
- ✅ 提供清晰的部署选项
- ✅ 增强错误日志可读性
## 📞 技术支持
如果仍有问题，请：
1. 运行测试脚本：`node scripts/test-kvrocks-deployment.js`
2. 检查日志：`docker-compose logs -f`
3. 参考部署文档：`docs/KVROCKS_DEPLOYMENT.md`
PROJECT_STATUS.md
-212
View File
@@ -1,212 +0,0 @@
# 📊 KatelyaTV 项目状态报告
## 🎯 项目概述
**KatelyaTV** 是一个功能完整的影视聚合播放器，基于现代 Web 技术栈构建，支持多平台部署和多种存储后端。该项目为在原始项目「MoonTV」基础上的二创与继承版本，延续其优秀架构并在此之上进行持续优化与维护。
**当前版本**: v0.1.0-katelya
**最后更新**: 2025-01-XX
**项目状态**: 🟢 生产就绪
## ✨ 功能完成度
### 🎬 核心功能
| 功能模块 | 状态 | 完成度 | 说明 |
|---------|------|--------|------|
| 多源聚合搜索 | ✅ 完成 | 100% | 集成20+个资源站点，支持智能去重 |
| 视频播放器 | ✅ 完成 | 100% | ArtPlayer + HLS.js，支持多种格式 |
| 观看历史记录 | ✅ 完成 | 100% | 智能进度记录，断点续播，多设备同步 |
| 收藏系统 | ✅ 完成 | 100% | 个性化片单，多端同步 |
| 用户管理 | ✅ 完成 | 100% | 注册、登录、权限管理 |
| PWA 支持 | ✅ 完成 | 100% | 离线缓存，桌面安装 |
| 响应式设计 | ✅ 完成 | 100% | 完美适配桌面和移动端 |
### 🎨 用户体验
| 特性 | 状态 | 完成度 | 说明 |
|------|------|--------|------|
| 深色模式 | ✅ 完成 | 100% | 自动跟随系统主题 |
| 移动端优化 | ✅ 完成 | 100% | 触摸友好，底部导航 |
| 动画效果 | ✅ 完成 | 100% | Framer Motion 流畅动画 |
| 加载状态 | ✅ 完成 | 100% | 骨架屏，进度条 |
| 错误处理 | ✅ 完成 | 100% | 友好提示，重试机制 |
### 🚀 技术特性
| 技术栈 | 状态 | 完成度 | 说明 |
|--------|------|--------|------|
| Next.js 14 | ✅ 完成 | 100% | App Router，最新特性 |
| TypeScript | ✅ 完成 | 100% | 类型安全，开发体验 |
| Tailwind CSS | ✅ 完成 | 100% | 原子化 CSS，主题系统 |
| 状态管理 | ✅ 完成 | 100% | React Hooks，Context API |
| 数据库支持 | ✅ 完成 | 100% | localStorage, Redis, D1, Upstash |
| 测试框架 | ✅ 完成 | 100% | Jest, Testing Library |
## 🏗️ 架构状态
### 前端架构
- ✅ **组件化设计**: 模块化组件，可复用性强
- ✅ **状态管理**: 合理的状态分层和更新机制
- ✅ **路由系统**: Next.js App Router，支持动态路由
- ✅ **样式系统**: Tailwind CSS + CSS 变量，主题切换
- ✅ **类型安全**: TypeScript 全覆盖，接口定义完整
### 后端架构
- ✅ **API 设计**: RESTful API，统一响应格式
- ✅ **数据存储**: 多存储后端支持，数据隔离
- ✅ **认证系统**: Cookie 认证，会话管理
- ✅ **缓存策略**: 智能缓存，减少重复请求
- ✅ **错误处理**: 统一错误处理，友好提示
### 部署架构
- ✅ **容器化**: Docker 支持，多架构镜像
- ✅ **云平台**: Vercel, Cloudflare Pages 支持
- ✅ **CI/CD**: GitHub Actions 自动化流程
- ✅ **监控**: 性能监控，错误追踪
- ✅ **安全**: 密码保护，访问控制
## 📱 平台兼容性
### 浏览器支持
- ✅ **Chrome**: 90+ (完全支持)
- ✅ **Firefox**: 88+ (完全支持)
- ✅ **Safari**: 14+ (完全支持)
- ✅ **Edge**: 90+ (完全支持)
### 设备支持
- ✅ **桌面端**: Windows, macOS, Linux (完全支持)
- ✅ **移动端**: iOS 14+, Android 8+ (完全支持)
- ✅ **平板**: iPad, Android 平板 (完全支持)
- ✅ **智能电视**: Android TV (部分支持)
### 存储后端
- ✅ **localStorage**: 单用户，浏览器存储
- ✅ **Redis**: 多用户，数据持久化
- ✅ **Cloudflare D1**: 多用户，边缘数据库
- ✅ **Upstash**: 多用户，托管 Redis
## 🔧 开发工具链
### 代码质量
- ✅ **ESLint**: 代码规范检查
- ✅ **Prettier**: 代码格式化
- ✅ **TypeScript**: 类型检查
- ✅ **Husky**: Git hooks
- ✅ **Lint-staged**: 提交前检查
### 测试覆盖
- ✅ **Jest**: 单元测试框架
- ✅ **Testing Library**: 组件测试
- ✅ **Mock**: API 模拟
- ✅ **Coverage**: 测试覆盖率
### 构建工具
- ✅ **Next.js**: 构建和优化
- ✅ **Tailwind**: CSS 构建
- ✅ **TypeScript**: 类型编译
- ✅ **SWC**: 快速编译
## 📊 性能指标
### 加载性能
- ✅ **首屏加载**: < 2s (优化后)
- ✅ **交互响应**: < 100ms
- ✅ **图片加载**: 懒加载 + 占位符
- ✅ **代码分割**: 按需加载
### 运行时性能
- ✅ **内存使用**: 优化内存泄漏
- ✅ **CPU 使用**: 减少不必要的计算
- ✅ **网络请求**: 智能缓存，减少重复
- ✅ **渲染性能**: 虚拟滚动，组件优化
## 🚀 部署状态
### 生产环境
- ✅ **Docker Hub**: 镜像可用
- ✅ **GitHub Packages**: 镜像可用
- ✅ **Vercel**: 部署就绪
- ✅ **Cloudflare**: 部署就绪
### 自动化流程
- ✅ **版本管理**: 自动化版本更新
- ✅ **构建部署**: CI/CD 流水线
- ✅ **测试验证**: 自动化测试
- ✅ **发布管理**: 自动化发布
## 📈 项目健康度
### 代码质量
- **代码覆盖率**: 85%+
- **类型覆盖率**: 100%
- **Lint 通过率**: 100%
- **测试通过率**: 100%
### 维护状态
- **依赖更新**: 定期更新
- **安全扫描**: 自动扫描
- **性能监控**: 持续监控
- **用户反馈**: 及时响应
### 社区活跃度
- **Issue 响应**: 24小时内
- **PR 审查**: 48小时内
- **文档更新**: 持续更新
- **版本发布**: 定期发布
## 🎯 下一步计划
### 短期目标 (1-2个月)
- [ ] 弹幕系统支持
- [ ] 字幕文件支持
- [ ] 下载功能
- [ ] 社交分享功能
### 中期目标 (3-6个月)
- [ ] 用户评分系统
- [ ] 推荐算法优化
- [ ] 多语言支持
- [ ] 高级搜索过滤
### 长期目标 (6-12个月)
- [ ] AI 内容推荐
- [ ] 社区功能
- [ ] 移动端原生应用
- [ ] 企业级功能
## 🏆 项目亮点
1. **技术先进性**: 使用最新的 Web 技术栈
2. **功能完整性**: 覆盖影视播放的完整流程
3. **部署灵活性**: 支持多种部署方式
4. **用户体验**: 现代化 UI 设计，流畅交互
5. **扩展性**: 模块化架构，易于扩展
6. **社区友好**: 完善的文档和贡献指南
## 📞 支持状态
- **问题反馈**: 24小时内响应
- **功能建议**: 48小时内评估
- **代码贡献**: 72小时内审查
- **紧急修复**: 12小时内处理
## 🎉 总结
KatelyaTV 项目目前处于**生产就绪**状态，核心功能完整，技术架构成熟，用户体验优秀。项目具备以下特点：
- ✅ **功能完整**: 所有核心功能均已实现
- ✅ **技术先进**: 使用最新的 Web 技术
- ✅ **部署灵活**: 支持多种部署方式
- ✅ **维护活跃**: 持续更新和维护
- ✅ **社区友好**: 完善的文档和指南
项目可以安全地用于生产环境，适合个人用户和中小型团队使用。
> 注：KatelyaTV 基于 MoonTV 二创与继承开发，保留并致谢原作者与社区贡献；如有授权或版权问题，请联系以尽快处理。
---
**最后更新**: 2025-01-XX
**维护状态**: 🟢 活跃维护
**推荐使用**: ✅ 生产就绪
README.md
+207 -1497
View File
@@ -4,32 +4,34 @@
<h1>KatelyaTV</h1>
<p><strong>跨平台 · 聚合搜索 · 即开即用 · 自托管影视聚合播放器</strong></p>
<p>基于 <code>Next.js 14</code> · <code>TypeScript</code> · <code>Tailwind CSS</code> · 多源聚合 / 播放记录 / 收藏同步 / 跳过片头片尾 / PWA</p>
<p>MoonTV 二创延续版 · 持续维护与增强</p>
<p>
<a href="#部署">🚀 部署</a> ·
<a href="#功能特性">✨ 功能</a> ·
<a href="#方案四vercel-部署免服务器支持多用户">☁️ Vercel+Upstash</a> ·
<a href="#docker">🐳 Docker</a> ·
<a href="#环境变量">⚙️ 配置</a>
<a href="#-快速开始">🚀 快速开始</a> ·
<a href="#-功能特性">✨ 功能特性</a> ·
<a href="#-部署方案">📋 部署方案</a> ·
<a href="#-配置说明">⚙️ 配置说明</a>
</p>
</div>
## 📰 项目来源与声明
---
本项目自「MoonTV」演进而来，为其二创/继承版本，持续维护与改进功能与体验。保留并致谢原作者与社区贡献者；如有授权或版权问题请联系以处理。目标：在原作基础上提供更易部署、更友好、更稳定的体验。
## 📰 项目声明
> **🔔 重要变更通知**：应用户社区的宝贵建议，为确保项目的长期稳定运行和合规性，我们已将内置的视频源移除。现在用户需要自行配置资源站以使用本应用的完整功能。我们提供了经过测试的推荐配置文件，让您能够快速上手使用（具体配置文件见 README.md 内容底部）。
本项目自「MoonTV」演进而来，为其二创/继承版本，持续维护与改进功能与体验。保留并致谢原作者与社区贡献者。
> **🔔 重要变更**：应用户社区建议，为确保项目长期稳定运行和合规性，内置视频源已移除。现需要用户自行配置资源站以使用完整功能。我们提供了经过测试的推荐配置文件，让您快速上手使用。
---
## ✨ 功能特性
### 🎬 核心播放功能
### 🎬 核心功能
- **🔍 聚合搜索**：整合多个影视资源站，一键搜索全网内容
- **📺 高清播放**：基于 ArtPlayer 的强大播放器，支持多种格式和画质
- **📺 高清播放**：基于 ArtPlayer 的强大播放器，支持多种格式
- **⏭️ 智能跳过**：自动检测并跳过片头片尾，手动设置跳过时间段
- **🎯 断点续播**：自动记录播放进度，跨设备同步观看位置
- **📱 响应式设计**：完美适配手机、平板、电脑各种屏幕尺寸
- **📱 响应式设计**：完美适配手机、平板、电脑各种屏幕
### 💾 数据管理
@@ -38,1306 +40,196 @@
- **👥 多用户支持**：独立的用户系统，每个用户独享个人数据
- **🔄 数据同步**：支持多种存储后端（LocalStorage、Redis、D1、Upstash）
### 🚀 部署与扩展
### 🚀 部署特性
- **🐳 Docker 一键部署**：提供完整的 Docker 镜像，开箱即用
- **☁️ 多平台支持**：Vercel + Upstash、Docker + Redis、Cloudflare Pages + D1、传统服务器全兼容
- **☁️ 多平台支持**：Vercel、Docker、Cloudflare Pages 全兼容
- **🔧 灵活配置**：支持自定义资源站、代理设置、主题配置
- **📱 PWA 支持**：可安装为桌面/手机应用，离线缓存
- **📺 TVBox 兼容**：支持 TVBox 配置接口，可导入到各种电视盒子应用
### 🎨 用户体验
- **🌓 深色模式**：支持明暗主题切换，护眼舒适
- **⚡ 性能优化**：智能缓存、懒加载、播放源优选算法
- **🔐 隐私保护**：本地部署，数据完全掌控
- **🌍 国际化**：多语言支持（规划中）
## 📋 技术栈
| 分类 | 主要依赖 |
| --------- | ----------------------------------------------------------------------------------------------------- |
| 前端框架 | [Next.js 14](https://nextjs.org/) · App Router |
| UI & 样式 | [Tailwind&nbsp;CSS 3](https://tailwindcss.com/) · [Framer Motion](https://www.framer.com/motion/) |
| 语言 | TypeScript 5 |
| 播放器 | [ArtPlayer](https://github.com/zhw2590582/ArtPlayer) · [HLS.js](https://github.com/video-dev/hls.js/) |
| 状态管理 | React Hooks · Context API |
| 代码质量 | ESLint · Prettier · Jest · Husky |
| 部署 | Docker · Vercel · CloudFlare pages · Upstash |
## 📺 TVBox 兼容功能
KatelyaTV 新增了 TVBox 配置接口，可以将您的视频源导入到各种电视盒子应用中使用：
### ✨ 功能特点
- **🔄 自动同步**：自动同步 KatelyaTV 中配置的所有视频源
- **📋 标准格式**：支持 TVBox 标准 JSON 配置格式
- **🎬 内置解析**：集成多个视频解析接口，支持主流视频平台
- **🌐 跨域支持**：自动处理 CORS 跨域问题
- **📱 多格式**：支持 JSON 和 Base64 两种配置格式
### 🚀 快速使用
1. **访问配置页面**：在 KatelyaTV 中点击侧边栏的"TVBox 配置"或访问 `/config` 页面
2. **选择格式类型**：在页面中选择 JSON 或 Base64 格式
3. **复制配置链接**：点击复制按钮获取配置链接
4. **导入到 TVBox**：在 TVBox 应用中导入配置链接
### 🔗 API 端点
- **JSON 配置**：`https://your-domain.com/api/tvbox?format=json`
- **Base64 配置**：`https://your-domain.com/api/tvbox?format=base64`
- **视频解析**：`https://your-domain.com/api/parse?url={视频地址}`
> 📖 详细使用说明请查看：[TVBox 配置指南](docs/TVBOX.md)
## 🚀 部署教程
> **💡 推荐方案**：
>
> - 🆕 **个人用户**：优先选择 **Vercel + Upstash**（免费 + 多用户 + 同步）
> - 🏠 **进阶用户**：选择 **Docker + Redis**（自托管 + 功能完整）
> - 🏢 **生产环境**：强烈推荐 **Docker + Kvrocks**（极高可靠性，零数据丢失风险）
### 📋 部署方式对比
| 方式 | 难度 | 成本 | 多用户 | 数据可靠性 | 配置文件 | 推荐场景 |
| ----------------------- | ------ | -------- | ------ | ---------- | ----------------------------------------------------- | --------------------------- |
| 🐳 **Docker 单容器** | ⭐ | 需服务器 | ❌ | ⭐⭐ | 无需配置文件 | 个人使用，最简单 |
| 🐳 **Docker + Redis** | ⭐⭐ | 需服务器 | ✅ | ⭐⭐⭐ | `docker-compose.redis.yml` + `.env.redis.example` | 家庭/团队，功能完整 |
| 🏪 **Docker + Kvrocks** | ⭐⭐ | 需服务器 | ✅ | ⭐⭐⭐⭐⭐ | `docker-compose.kvrocks.yml` + `.env.kvrocks.example` | 生产环境，高可靠性 |
| ☁️ **Vercel（单机版）** | ⭐ | 免费 | ❌ | ⭐ | `vercel.json` | 临时体验，无服务器 |
| ☁️ **Vercel + Upstash** | ⭐⭐ | 免费 | ✅ | ⭐⭐⭐⭐ | `vercel.json` + Upstash 配置 | **推荐**：无服务器 + 多用户 |
| 🌐 **Cloudflare + D1** | ⭐⭐⭐ | 免费 | ✅ | ⭐⭐⭐ | `wrangler.toml` + `.env.cloudflare.example` | 技术爱好者 |
> **💡 快速选择指南**：
>
> - 🆕 **第一次部署**：选择方案一（Docker 单容器）或方案四（Vercel + Upstash）
> - 🏠 **家庭/团队使用**：选择方案二（Docker + Redis）或方案三（Docker + Kvrocks）
> - 🏢 **生产环境**：强烈推荐方案三（Docker + Kvrocks）
> - 💰 **免费用户**：选择方案四（Vercel + Upstash）或方案五（Cloudflare + D1）
### 🛠️ 部署状态检查
在部署前，可以运行配置检查脚本验证所有文件是否完整：
```bash
# 检查所有部署方案的配置文件
node scripts/check-deployment-configs.js
# 检查 Kvrocks 部署配置
node scripts/test-kvrocks-deployment.js
```
- **📱 PWA 支持**：可安装为桌面/手机应用
- **📺 TVBox 兼容**：支持 TVBox 配置接口
---
## 🎯 方案一：Docker 单容器（推荐新手）
## 🚀 快速开始
> **适合场景**：个人使用，有服务器/NAS/电脑，想要最简单的部署方式
### 推荐方案选择
### 🔧 前置要求
| 用户类型 | 推荐方案 | 特点 |
| ----------- | ---------------- | -------------------- |
| 🆕 新手用户 | Docker 单容器 | 最简单，5 分钟部署 |
| 👥 多人使用 | Vercel + Upstash | 免费，支持多用户 |
| 🏠 自托管 | Docker + Redis | 功能完整，数据可控 |
| 🏢 生产环境 | Docker + Kvrocks | 高可靠性，零丢失风险 |
- 一台能联网的设备（服务器/NAS/Windows/Mac/Linux 都行）
- 已安装 Docker（[Docker 官网下载](https://www.docker.com/get-started/)）
---
### 📝 详细步骤
## 📋 部署方案
#### 第一步：拉取镜像
### 方案一：Docker 单容器（推荐新手）
**适合场景**：个人使用，最简单的部署方式
```bash
# 下载最新版本镜像（支持 ARM 和 x86 架构）
docker pull ghcr.io/katelya77/katelyatv:latest
```
#### 第二步：启动容器
```bash
# 一键启动（请把 your_password 改成你的密码）
# 一键启动
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_password \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
# 访问 http://localhost:3000
```
> **Windows 用户注意**：在 PowerShell 中运行上述命令
#### 第三步：访问应用
1. 打开浏览器，访问：`http://你的服务器IP:3000`
2. 如果是本机安装，访问：`http://localhost:3000`
3. 输入你在第二步设置的密码即可进入
#### 第四步：自定义资源站配置
> **📢 重要说明**：为确保项目的长期稳定运行和避免潜在的法律风险，应用户社区的建议，我们已将内置的视频源移除。现在需要用户自行配置视频源以正常使用本应用。
##### 🔗 获取推荐的资源站配置
为了方便用户快速上手，我们提供了一个经过测试的资源站配置文件：
**配置文件下载地址**: [https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file](https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file)
**配置文件 Plus 下载地址**: [配置文件 Plus 版本【94 片源】](https://www.mediafire.com/file/fbpk1mlupxp3u3v/configplus.json/file)
##### 📋 配置步骤
1. **下载配置文件**：点击上方链接下载 `config.json` 文件
2. **保存到本地**：将文件保存到服务器的合适位置（如 `/opt/katelyatv/config.json`）
3. **挂载配置文件**：按以下命令重新启动容器
**自定义配置文件（可选）**：
```bash
# 先停止并删除旧容器
docker stop katelyatv && docker rm katelyatv
# 重新运行并挂载配置文件
# 挂载配置文件
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_password \
-v /path/to/your/config.json:/app/config.json:ro \
-v ./config.json:/app/config.json:ro \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
```
> **路径说明**：把 `/path/to/your/config.json` 替换成你的配置文件完整路径
> **Windows 示例**：`-v C:/Users/你的用户名/Desktop/config.json:/app/config.json:ro`
### 方案二：Docker + Redis（多用户推荐）
##### 🛡️ 免责声明
- 提供的配置文件仅为方便用户测试和学习使用
- 所有视频源均来源于公开的网络资源，请用户自行判断使用的合法性
- 我们不对任何第三方视频源的内容、质量或合法性负责
- 建议用户仅使用合法、正版的视频源
### 🛠️ 常用管理命令
**适合场景**：家庭/团队使用，支持多用户和数据同步
```bash
# 查看运行状态
docker ps
# 查看日志
docker logs katelyatv
# 重启应用
docker restart katelyatv
# 停止应用
docker stop katelyatv
# 删除容器
docker rm katelyatv
```
---
## 🎯 方案二：Docker + Redis（推荐进阶）
> **适合场景**：多人使用，需要账号系统、观看记录同步、收藏功能
### 🔧 前置要求
- 已完成方案一，确认单容器版本能正常运行
- 了解基本的 Docker Compose 概念
### 📝 详细步骤
#### 第一步：下载配置文件
```bash
# 创建项目目录
mkdir katelyatv-redis && cd katelyatv-redis
# 下载 Redis 部署配置
# 下载配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/docker-compose.redis.yml
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.redis.example
# 复制环境变量模板
cp .env.redis.example .env
```
> **📌 重要说明**：此配置使用预构建的 Docker 镜像，无需下载源代码。
#### 第二步：配置环境变量
```bash
# 编辑环境变量文件
# 编辑环境变量
nano .env
# 启动服务
docker compose -f docker-compose.redis.yml up -d
```
**重要配置项**：
**重要环境变量配置**：
```bash
# 存储类型：使用 Redis
# 存储类型
NEXT_PUBLIC_STORAGE_TYPE=redis
# 站点全局访问密码 (必填)
PASSWORD=your_site_access_password
# 管理员账号
USERNAME=admin
PASSWORD=your_admin_password
# Redis 连接配置
# Redis配置
REDIS_URL=redis://katelyatv-redis:6379
# Redis 密码配置（可选）
# REDIS_PASSWORD=your_redis_password
REDIS_DATABASE=0
# NextAuth 配置
NEXTAUTH_SECRET=your_nextauth_secret_here # 改成随机字符串
NEXTAUTH_URL=http://localhost:3000 # 改成你的域名
# 开启用户注册
NEXT_PUBLIC_ENABLE_REGISTER=true
```
#### 第三步：启动服务
### 方案三：Docker + Kvrocks（高可靠性）
````bash
# 启动 KatelyaTV + Redis
docker compose -f docker-compose.redis.yml up -d
# 查看启动状态
docker compose -f docker-compose.redis.yml ps
# 查看日志
docker compose -f docker-compose.redis.yml logs -f
---
## � 方案三：Docker + Kvrocks（高可靠性推荐）
> **适合场景**：生产环境，需要极高的数据可靠性，担心 Redis 数据丢失风险
### 🌟 Kvrocks 优势
- **🛡️ 极高可靠性**：基于 RocksDB，数据持久化到磁盘，几乎零丢失风险
- **⚡ 性能优异**：完全兼容 Redis 协议，性能接近甚至超越 Redis
- **💾 节省内存**：数据存储在磁盘，内存使用量大幅降低
- **🔄 无需 AOF/RDB**：RocksDB 天然支持数据持久化，无需额外配置
- **📈 更好扩展性**：支持更大的数据集，不受内存限制
### 🔧 前置要求
- 服务器/NAS/电脑（支持 Docker）
- 已安装 Docker 和 Docker Compose
### 📝 详细步骤
#### 第一步：下载配置文件
**适合场景**：生产环境，需要极高的数据可靠性
```bash
# 创建项目目录
mkdir katelyatv-kvrocks && cd katelyatv-kvrocks
# 下载 Kvrocks 部署配置
# 下载配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/docker-compose.kvrocks.yml
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.kvrocks.example
# 复制环境变量模板
cp .env.kvrocks.example .env
````
> **📌 重要说明**：此配置使用预构建的 Docker 镜像 (`ghcr.io/katelya77/katelyatv:latest`)，无需下载源代码。镜像会自动从 GitHub Container Registry 拉取。
#### 第二步：配置环境变量
```bash
# 编辑环境变量文件
# 编辑环境变量
nano .env
```
**重要配置项**：
```bash
# 存储类型：使用 Kvrocks
NEXT_PUBLIC_STORAGE_TYPE=kvrocks
# 站点全局访问密码 (必填)
PASSWORD=your_site_access_password
# Kvrocks 连接配置
KVROCKS_URL=redis://kvrocks:6666
# 密码配置（选择以下其中一种方式）：
# 方式1：无密码部署（开发环境推荐）
# KVROCKS_PASSWORD=
# 方式2：密码认证部署（生产环境推荐）
KVROCKS_PASSWORD=your_secure_password_here
KVROCKS_DATABASE=0
# NextAuth 配置
NEXTAUTH_SECRET=your_nextauth_secret_here # 改成随机字符串
NEXTAUTH_URL=http://localhost:3000 # 改成你的域名
```
> **🚨 重要提示**：请根据您的需求选择部署方式：
>
> - **无密码部署**：适合开发环境，将 `KVROCKS_PASSWORD` 留空或注释掉
> - **密码认证部署**：适合生产环境，设置强密码并使用对应的 Docker 配置
#### 第三步：选择部署配置并启动
**选项 A：无密码部署（开发环境）**
```bash
# 确保环境变量中 KVROCKS_PASSWORD 未设置或为空
# KVROCKS_PASSWORD=
# 启动无密码配置
# 启动服务（无密码版本）
docker compose -f docker-compose.kvrocks.yml up -d
# 如需密码认证版本，使用：
# docker compose -f docker-compose.kvrocks.auth.yml up -d
```
**选项 B：密码认证部署（生产环境）**
**Kvrocks 优势**：
- 🛡️ **极高可靠性**：基于 RocksDB，数据持久化到磁盘
- ⚡ **性能优异**：完全兼容 Redis 协议，性能更佳
- 💾 **节省内存**：数据存储在磁盘，内存使用量大幅降低
> 详细部署指南请查看：[Kvrocks 部署文档](docs/KVROCKS_DEPLOYMENT.md)
### 方案四：Vercel + Upstash（免费推荐）
**适合场景**：无服务器，免费部署，支持多用户
1. **Fork 仓库**：Fork [KatelyaTV](https://github.com/katelya77/KatelyaTV) 到你的 GitHub
2. **部署到 Vercel**：
- 登录 [Vercel](https://vercel.com/)，导入你的仓库
- 添加环境变量：`PASSWORD=your_password`
- 点击 Deploy
3. **配置多用户（可选）**：
```bash
# 创建 Upstash Redis 数据库
# 在 Vercel 中添加环境变量：
NEXT_PUBLIC_STORAGE_TYPE=upstash
UPSTASH_URL=https://xxx.upstash.io
UPSTASH_TOKEN=your_token
NEXT_PUBLIC_ENABLE_REGISTER=true
USERNAME=admin
PASSWORD=admin_password
```
### 方案五：Cloudflare + D1（技术爱好者）
**适合场景**：全球 CDN 加速，免费但配置稍复杂
```bash
# 确保环境变量中设置了强密码
# KVROCKS_PASSWORD=your_secure_password_here
# 启动密码认证配置
docker compose -f docker-compose.kvrocks.auth.yml up -d
```
#### 第四步：验证部署
```bash
# 查看启动状态
docker compose ps
# 检查服务日志（重要：确认无认证错误）
docker compose logs -f
# 验证 Kvrocks 连接（根据配置选择命令）
# 无密码版本：
docker compose exec kvrocks redis-cli -h localhost -p 6666 ping
# 密码认证版本：
docker compose exec kvrocks redis-cli -h localhost -p 6666 -a your_password ping
```
> **📖 详细部署指南**：如遇到问题，请参考 [Kvrocks 部署指南](docs/KVROCKS_DEPLOYMENT.md)
### 🔧 高级选项：本地构建
如果你想要从源代码本地构建而不是使用预构建镜像，可以：
```bash
# 克隆完整源代码
git clone https://github.com/katelya77/KatelyaTV.git
cd KatelyaTV
# 使用本地构建版本的配置
docker compose -f docker-compose.kvrocks.local.yml up -d
```
> **注意**：本地构建需要下载完整源代码，首次构建时间较长，但可以自定义修改代码。
#### 第五步：访问应用
1. 浏览器访问：`http://你的服务器IP:3000`
2. 注册账号开始使用
### 🛠️ 管理命令
```bash
# 停止服务
docker compose -f docker-compose.kvrocks.yml stop
# 重启服务
docker compose -f docker-compose.kvrocks.yml restart
# 查看 Kvrocks 状态
docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 info
# 备份数据
docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 BGSAVE
# 数据量统计
docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 dbsize
```
### 🔒 数据备份与恢复
#### 备份数据
```bash
# 自动备份（推荐）
docker run --rm \
-v katelyatv-kvrocks_kvrocks-data:/data \
-v $(pwd):/backup \
alpine tar czf /backup/kvrocks-backup-$(date +%Y%m%d).tar.gz /data
# 手动触发 RocksDB 备份
docker compose -f docker-compose.kvrocks.yml exec kvrocks redis-cli -h localhost -p 6666 BGSAVE
```
#### 恢复数据
```bash
# 先停止服务
docker compose -f docker-compose.kvrocks.yml down
# 恢复数据
docker run --rm \
-v katelyatv-kvrocks_kvrocks-data:/data \
-v $(pwd):/backup \
alpine tar xzf /backup/kvrocks-backup-20241201.tar.gz -C /
# 重新启动
docker compose -f docker-compose.kvrocks.yml up -d
```
### 🚀 性能优化建议
1. **SSD 存储**：建议使用 SSD 存储以获得最佳性能
2. **内存配置**：为 Kvrocks 分配 512MB-1GB 内存即可
3. **磁盘空间**：预留足够磁盘空间，推荐至少 10GB
4. **监控配置**：定期检查磁盘使用率和性能指标
### ⚠️ 注意事项
- Kvrocks 端口 6666 仅限内部网络访问，确保安全
- 定期备份数据，虽然 Kvrocks 可靠性很高，但备份是好习惯
- 监控磁盘空间使用，避免磁盘满导致的问题
---
## 🎯 方案四：Vercel 部署（免服务器，支持多用户）
> **适合场景**：没有服务器，想要快速体验，支持多用户和跨设备同步
### 🔧 前置要求
- 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**
4. 在 **Environment Variables** 部分添加：
- Key: `PASSWORD`
- Value: `你的访问密码`（这是进入网站的密码）
5. 点击 **Deploy** 开始部署
#### 第三步：等待部署完成
- 通常需要 2-3 分钟
- 部署成功后会显示域名，比如 `https://your-project.vercel.app`
#### 第四步：访问和使用
1. 点击 Vercel 提供的域名链接
2. 输入你在第二步设置的密码
3. 开始使用！
### 🔧 自定义资源站
> **📢 重要说明**：由于项目长期稳定性考虑，应社区用户建议已移除内置视频源，需要配置资源站后才能正常使用。
#### 方法一：使用推荐配置（推荐）
**第一步：下载配置文件**
选择以下任一配置文件：
- **基础版**: [config.json](https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file)
- **Plus 版**: [配置文件 Plus 版本【94 片源】](https://www.mediafire.com/file/fbpk1mlupxp3u3v/configplus.json/file)
**第二步：获取正确的 JSON 内容**
⚠️ **重要**: 请下载文件到本地，不要直接复制网页内容！
1. **下载文件**: 点击 MediaFire 的 "Download" 按钮
2. **打开文件**: 用记事本打开下载的 `.json` 文件
3. **复制内容**: 全选并复制文件中的 JSON 内容
**第三步：更新仓库配置**
1. 在你 Fork 的仓库中找到 `config.json` 文件
2. 点击编辑按钮（✏️ 铅笔图标）
3. **删除所有原有内容**，粘贴从本地文件复制的完整 JSON 内容
4. 确保内容格式正确（以 `{` 开头，以 `}` 结尾）
5. 点击 **Commit changes**
**第四步：等待重新部署**
Vercel 会自动重新部署（约 1-2 分钟），部署成功后即可正常使用。
#### 方法二：手动配置
如果你想添加自己的资源站：
1. 在你 Fork 的仓库中找到 `config.json` 文件
2. 点击编辑按钮（铅笔图标）
3. 修改配置内容
4. 点击 **Commit changes**
5. Vercel 会自动重新部署
### 🚀 Vercel + Upstash 多用户部署（推荐升级方案）
如果你需要**多用户支持**和**跨设备数据同步**功能，可以配置 Upstash Redis 数据库：
#### 🔧 配置步骤
**第一步：创建 Upstash Redis 数据库**
1. 访问 [Upstash Console](https://console.upstash.com/)
2. 使用 GitHub 账号登录（或注册新账号）
3. 点击 **Create Database**
4. 配置数据库：
- **Name**: 输入数据库名称（如 `katelyatv-db`）
- **Region**: 选择离你最近的区域
- **Type**: 选择 **Regional**（免费版）
5. 点击 **Create** 创建数据库
**第二步：获取连接信息**
1. 在数据库详情页面，找到 **REST API** 部分
2. 复制以下信息：
- **UPSTASH_REDIS_REST_URL**: `https://xxx-xxx-xxx.upstash.io`
- **UPSTASH_REDIS_REST_TOKEN**: `AXXXXxxxxxxxxxxxxxx`
**第三步：配置 Vercel 环境变量**
1. 在 Vercel 项目仪表板中，进入 **Settings** → **Environment Variables**
2. 添加以下环境变量：
| Key | Value | 说明 |
| ----------------------------- | -------------------------------- | ------------------ |
| `NEXT_PUBLIC_STORAGE_TYPE` | `upstash` | 启用 Upstash 存储 |
| `UPSTASH_URL` | `https://xxx-xxx-xxx.upstash.io` | Upstash REST URL |
| `UPSTASH_TOKEN` | `AXXXXxxxxxxxxxxxxxx` | Upstash REST Token |
| `NEXT_PUBLIC_ENABLE_REGISTER` | `true` | 开启用户注册 |
| `USERNAME` | `admin` | 管理员用户名 |
| `PASSWORD` | `your_admin_password` | 管理员密码 |
3. 点击 **Save** 保存配置
**第四步：重新部署**
1. 进入 **Deployments** 页面
2. 点击最新部署右侧的 **···** 菜单
3. 选择 **Redeploy** 重新部署
#### ✨ 升级后的功能
配置完成后，你的应用将支持：
- **👥 多用户系统**: 用户可以注册独立账号
- **🔄 跨设备同步**: 观看记录、收藏夹在所有设备间同步
- **🛡️ 管理员功能**: 用户管理、系统配置等高级功能
- **📊 数据持久化**: 数据存储在云端，永不丢失
#### 💰 费用说明
- **Upstash 免费额度**: 每月 10,000 个命令，通常足够个人/家庭使用
- **Vercel 免费额度**: 包含 100GB 带宽和无限部署
- **总成本**: 正常使用完全免费！
### ⚠️ 单机版注意事项
如果你选择不配置 Upstash（单机版）：
- 不支持用户注册和账号系统
- 观看记录保存在浏览器本地，换设备会丢失
- 如果需要多用户功能，强烈推荐配置 Upstash 或考虑 Docker + Redis 方案
---
## 🎯 方案五：Cloudflare Pages（进阶用户）
> **适合场景**：技术爱好者，想要全球 CDN 加速，免费但配置复杂
### 🔧 前置要求
- GitHub 账号
- Cloudflare 账号
- 对前端构建有基本了解
### 📝 详细步骤
#### 第一步：Fork 仓库并连接
1. Fork [KatelyaTV 仓库](https://github.com/katelya77/KatelyaTV)
2. 登录 [Cloudflare](https://cloudflare.com)
3. 进入 **Workers 和 Pages** → 点击 **创建应用程序**
4. 选择 **Pages** → **连接到 Git**
5. 选择你 Fork 的仓库
#### 第二步：配置构建设置
在构建设置页面填写：
- **构建命令**: `pnpm install && pnpm pages:build`
- **构建输出目录**: `.vercel/output/static`
- **Root directory**: `./`（默认）
- **Node.js 版本**: `18`（推荐）
#### 第三步：设置兼容性
1. 点击 **保存并部署**
2. 等待首次构建完成（可能会失败，没关系）
3. 进入项目 **设置** → **兼容性标志**
4. 添加标志: `nodejs_compat`
#### 第四步：添加环境变量
在 **设置** → **环境变量** 中添加：
- `PASSWORD`: 你的访问密码
#### 第五步：重新部署
1. 进入 **部署** 页面
2. 点击最新部署旁的 **...** → **重试部署**
3. 等待部署成功
#### 第六步：配置资源站
> **📢 重要提醒**：为保障项目长期稳定运行，应用户建议已移除内置视频源，需要配置资源站。
##### 📋 详细配置步骤（重要）：
**第一步：下载配置文件**
选择以下任一配置文件下载：
- **基础版**: [config.json](https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file)
- **Plus 版**: [配置文件 Plus 版本【94 片源】](https://www.mediafire.com/file/fbpk1mlupxp3u3v/configplus.json/file)
**第二步：验证下载的文件内容**
❌ **错误做法**: 直接复制网页上显示的内容
✅ **正确做法**: 下载 `.json` 文件到本地，然后打开查看
⚠️ **常见错误**: 如果你直接从 MediaFire 页面复制内容，可能会包含网页元素，导致 JSON 格式错误！
**第三步：获取正确的 JSON 内容**
1. **下载文件**: 点击 MediaFire 的 "Download" 按钮，下载 `.json` 文件到电脑
2. **打开文件**: 用记事本或代码编辑器打开下载的 `.json` 文件
3. **复制内容**: 选择全部内容并复制（应该以 `{` 开头，以 `}` 结尾）
**第四步：更新 GitHub 仓库**
1. **进入仓库**: 回到你 Fork 的 GitHub 仓库
2. **编辑文件**: 找到 `config.json` 文件，点击 **✏️ 编辑** 按钮
3. **替换内容**:
- **删除所有原有内容**
- **粘贴从本地文件复制的完整 JSON 内容**
- **确保内容以 `{` 开头，以 `}` 结尾**
4. **验证格式**: 在提交前检查内容是否为有效的 JSON 格式
5. **提交更改**: 填写提交信息，点击 **Commit changes**
**第五步：等待自动部署**
1. Cloudflare Pages 会自动检测到 GitHub 仓库的更改
2. 等待 2-3 分钟自动重新构建和部署
3. 部署成功后即可正常使用影视聚合功能
##### 🔍 故障排除
**如果遇到 "config.json 不是有效的 JSON" 错误：**
1. **检查文件内容**: 确保内容是纯 JSON，没有 HTML 标签或其他字符
2. **重新下载**: 从 MediaFire 重新下载文件，不要复制网页内容
3. **使用 JSON 验证器**: 将内容粘贴到 [JSON 验证器](https://jsonlint.com/) 检查格式
4. **查看构建日志**: 在 Cloudflare Pages 的部署页面查看详细错误信息
**示例正确的 JSON 格式开头：**
```json
{
"cache_time": 7200,
"api_site": {
"example": {
"api": "https://example.com/api.php/provide/vod",
"name": "示例资源站"
}
// ... 更多配置
}
}
```
🎉 **完成！配置正确后即可正常使用所有影视聚合功能了**
### 🗄️ 启用 D1 数据库（可选，支持多用户）
如果你想要用户系统和数据同步：
> ⚠️ **升级提醒**：如果你已有 D1 数据库，需要手动添加新功能表。请查看 [D1_MIGRATION.md](./D1_MIGRATION.md) 文件。
#### 方式一：使用 Cloudflare Dashboard（推荐）
**第一步：创建 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 语句
4. 粘贴到查询窗口，点击 **Run All**
**第三步：绑定数据库**
1. 回到 Pages 项目设置
2. 进入 **绑定** → **添加绑定**
3. 选择 **D1 数据库**
4. 变量名: `DB`
5. 选择你刚创建的数据库
**第四步：添加环境变量**
在环境变量中追加：
- `NEXT_PUBLIC_STORAGE_TYPE`: `d1`
- `USERNAME`: 管理员用户名
- `PASSWORD`: 管理员密码
#### 方式二：使用 Wrangler CLI（高级用户）
**第一步：下载配置文件**
```bash
# 下载 wrangler 配置文件
# 下载配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/wrangler.toml
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.cloudflare.example
# 复制环境变量模板
cp .env.cloudflare.example .env.local
```
**第二步：创建 D1 数据库**
```bash
# 安装 Wrangler CLI
npm install -g wrangler
# 登录 Cloudflare
wrangler login
# 创建 D1 数据库
wrangler d1 create katelyatv-db
# 初始化数据库表
wrangler d1 execute katelyatv-db --file=./scripts/d1-init.sql
```
**第三步：部署**
```bash
# 部署到 Cloudflare Pages
# 部署
wrangler pages deploy
```
**第五步：重新部署**
重新部署后，你就可以：
- 使用管理员账号登录
- 访问 `/admin` 管理后台
- 支持用户注册和数据同步
---
## 🆙 升级和维护
## ⚙️ 配置说明
### Docker 升级
### 🔧 环境变量
```bash
# 单容器版本
docker stop katelyatv
docker rm katelyatv
docker pull ghcr.io/katelya77/katelyatv:latest
# 然后重新运行启动命令
| 变量名 | 说明 | 默认值 |
| ----------------------------- | ---------------- | ------------ |
| `PASSWORD` | 访问密码（必填） | 无 |
| `USERNAME` | 管理员用户名 | 无 |
| `SITE_NAME` | 站点名称 | KatelyaTV |
| `NEXT_PUBLIC_STORAGE_TYPE` | 存储类型 | localstorage |
| `REDIS_URL` | Redis 连接地址 | 无 |
| `NEXT_PUBLIC_ENABLE_REGISTER` | 开启用户注册 | false |
# Compose 版本
docker compose pull
docker compose up -d
```
### 📁 视频源配置
### Vercel 升级
> **重要**：为保障项目合规性，需要配置视频源才能正常使用。
- 自动升级：当原仓库更新时，你的 Fork 仓库会收到更新提示
- 手动升级：在你的 Fork 仓库点击 **Sync fork** 按钮
#### 方法一：使用推荐配置（推荐）
### Cloudflare 升级
1. 下载配置文件：
- 同 Vercel，通过 Git 同步自动触发重新构建
- [基础版 config.json](https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file)
- [Plus 版（94 个片源）](https://www.mediafire.com/file/fbpk1mlupxp3u3v/configplus.json/file)
### 🚨 常见问题排查
2. 配置方式：
- **Docker**：挂载配置文件 `-v ./config.json:/app/config.json:ro`
- **Vercel**：替换仓库中的 `config.json` 文件内容
- **管理员界面**：登录后台 `/admin` 导入配置
| 问题 | 现象 | 解决方法 |
| --------------- | -------------------------- | ---------------------------------- |
| 无法访问 | 浏览器显示无法连接 | 检查端口 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，体积小启动快。
### 🚀 快速开始
#### 1. 基础部署（LocalStorage，最快验证）
```bash
# 拉取最新镜像（支持 amd64/arm64 多架构）
docker pull ghcr.io/katelya77/katelyatv:latest
# 快速启动（LocalStorage 存储）
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_secure_password \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
```
访问 `http://服务器IP:3000` 即可使用。（需要在服务器控制台开放 3000 端口）
> Windows 本地构建如遇 Node Standalone `EPERM symlink`：优先使用 **Docker 镜像** 或在 **WSL2** 环境构建；无需修改源码。
#### 2. 自定义配置（挂载 config.json）
```bash
# 创建配置文件目录
mkdir -p ./katelyatv-config
# 将你的 config.json 放入该目录，然后运行：
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_secure_password \
-v ./katelyatv-config/config.json:/app/config.json:ro \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
```
#### 3. 常用运维命令
```bash
# 查看容器状态
docker ps
# 查看日志
docker logs katelyatv
# 查看实时日志
docker logs -f katelyatv
```
#### 4. 升级镜像
```bash
# 停止并删除旧容器
docker stop katelyatv && docker rm katelyatv
# 拉取最新镜像
docker pull ghcr.io/katelya77/katelyatv:latest
# 重新创建容器（使用相同的配置）
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_secure_password \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
```
### 📦 镜像特性
- **🏗️ 多架构支持**：同时支持 `linux/amd64` 和 `linux/arm64` 架构
- **⚡ 优化构建**：基于 Alpine Linux，镜像体积小，启动速度快
- **🔒 安全可靠**：定期更新底层依赖，修复安全漏洞
- **🚀 开箱即用**：内置所有必要依赖，无需额外配置
### 🔧 常用操作
```bash
# 进入容器终端（调试用）
docker exec -it katelyatv /bin/sh
# 重启容器
docker restart katelyatv
# 停止容器
docker stop katelyatv
# 查看容器资源使用情况
docker stats katelyatv
# 备份容器（如果有挂载卷）
docker run --rm -v katelyatv_data:/data -v $(pwd):/backup alpine tar czf /backup/katelyatv-backup.tar.gz /data
```
## 🐙 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（基础单机）
适合个人使用，数据存储在浏览器本地：
```yaml
# docker-compose.yml
version: '3.8'
services:
katelyatv:
image: ghcr.io/katelya77/katelyatv:latest
container_name: katelyatv
restart: unless-stopped
ports:
- '3000:3000'
environment:
- PASSWORD=your_secure_password
- SITE_NAME=我的影视站
- ANNOUNCEMENT=欢迎使用 KatelyaTV！请遵守相关法律法规。
# 可选：挂载自定义配置
# volumes:
# - ./config.json:/app/config.json:ro
healthcheck:
test:
[
'CMD',
'wget',
'--quiet',
'--tries=1',
'--spider',
'http://localhost:3000',
]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
**启动命令：**
```bash
# 创建并启动服务
docker compose up -d
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f katelyatv
```
### 🔐 Redis 版本（推荐：多用户 + 同步）
支持多用户、跨设备数据同步、完整的用户权限管理：
```yaml
# docker-compose.yml
version: '3.8'
services:
katelyatv:
image: ghcr.io/katelya77/katelyatv:latest
container_name: katelyatv
restart: unless-stopped
ports:
- '3000:3000'
environment:
# 基础配置
- 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:
- katelyatv-network
depends_on:
katelyatv-redis:
condition: service_healthy
# 可选：挂载自定义配置和持久化数据
# volumes:
# - ./config.json:/app/config.json:ro
# - ./logs:/app/logs
healthcheck:
test:
[
'CMD',
'wget',
'--quiet',
'--tries=1',
'--spider',
'http://localhost:3000',
]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
katelyatv-redis:
image: redis:7-alpine
container_name: katelyatv-redis
restart: unless-stopped
command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
networks:
- katelyatv-network
volumes:
# Redis 数据持久化
- katelyatv-redis-data:/data
healthcheck:
test: ['CMD', 'redis-cli', 'ping']
interval: 10s
timeout: 3s
retries: 3
start_period: 10s
# 可选：端口映射（用于外部访问 Redis）
# ports:
# - '6379:6379'
networks:
katelyatv-network:
driver: bridge
name: katelyatv-network
volumes:
katelyatv-redis-data:
driver: local
name: katelyatv-redis-data
```
**完整部署流程：**
```bash
# 1. 创建项目目录
mkdir katelyatv && cd katelyatv
# 2. 创建 docker-compose.yml 文件（复制上面的内容）
nano docker-compose.yml
# 3. 检查配置文件语法
docker compose config
# 4. 启动所有服务
docker compose up -d
# 5. 查看服务状态
docker compose ps
# 6. 查看启动日志
docker compose logs -f
# 7. 等待服务完全启动（通常需要 30-60 秒）
# 检查健康状态
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
# 8. 首次访问 http://your-server:3000
# 使用管理员账号 admin / admin_super_secure_password 登录
# 然后访问 /admin 进行管理员配置
```
**🔍 部署验证步骤：**
```bash
# 验证 Redis 连接
docker compose exec katelyatv-redis redis-cli ping
# 应该返回 "PONG"
# 验证 KatelyaTV 服务
curl -I http://localhost:3000
# 应该返回 HTTP 200 状态码
# 查看服务启动顺序
docker compose logs --timestamps | grep "Ready in"
```
### 🔄 管理与维护
```bash
# 更新到最新版本
docker compose pull && docker compose up -d
# 备份 Redis 数据
docker compose exec katelyatv-redis redis-cli BGSAVE
docker run --rm -v katelyatv-redis-data:/data -v $(pwd):/backup alpine tar czf /backup/redis-backup-$(date +%Y%m%d).tar.gz /data
# 查看资源使用情况
docker compose stats
# 重启特定服务
docker compose restart katelyatv
# 查看特定服务日志
docker compose logs -f katelyatv-redis
# 进入容器调试
docker compose exec katelyatv /bin/sh
# 完全清理（注意：会删除所有数据！）
docker compose down -v --remove-orphans
```
### 🚨 重要注意事项
1. **修改默认密码**：部署后请立即修改 `admin` 账号的默认密码
2. **数据备份**：定期备份 Redis 数据卷，避免数据丢失
3. **端口安全**：确保服务器防火墙正确配置，只开放必要端口
4. **资源监控**：定期检查容器资源使用情况，必要时调整配置
5. **日志管理**：配置日志轮转，避免日志文件过大
### 🛠️ 常见部署问题排查
**问题 1：容器启动失败**
```bash
# 检查容器状态
docker compose ps
# 查看详细错误日志
docker compose logs katelyatv
# 常见原因：端口被占用、环境变量配置错误、镜像拉取失败
```
**问题 2：Redis 连接失败**
```bash
# 检查 Redis 容器状态
docker compose exec katelyatv-redis redis-cli ping
# 检查网络连通性
docker compose exec katelyatv ping katelyatv-redis
# 验证环境变量
docker compose exec katelyatv env | grep REDIS
```
**问题 3：Upstash Redis 连接问题**
```bash
# 验证 Upstash 配置
curl -H "Authorization: Bearer YOUR_TOKEN" YOUR_UPSTASH_URL/ping
# 检查环境变量格式
echo $UPSTASH_URL # 应该是 https://xxx.upstash.io
echo $UPSTASH_TOKEN # 应该是长字符串令牌
```
**问题 4：Cloudflare D1 初始化失败**
- 确保在 D1 控制台中正确执行了所有 SQL 语句
- 检查数据库绑定名称是否为 `DB`
- 验证环境变量 `NEXT_PUBLIC_STORAGE_TYPE=d1`
**问题 5：Vercel 部署问题**
- 检查环境变量是否正确设置
- 确保 `config.json` 文件格式正确
- 查看 Vercel 部署日志中的错误信息
## 🔄 自动同步最近更改
建议在 fork 的仓库中启用本仓库自带的 GitHub Actions 自动同步功能（见 `.github/workflows/sync.yml`）。
如需手动同步主仓库更新，也可以使用 GitHub 官方的 [Sync fork](https://docs.github.com/cn/github/collaborating-with-issues-and-pull-requests/syncing-a-fork) 功能。
## ⚙️ 环境变量
### 📋 变量说明表
| 变量 | 说明 | 可选值 | 默认值 |
| --------------------------- | ----------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| USERNAME | redis 部署时的管理员账号 | 任意字符串 | （空） |
| PASSWORD | 默认部署时为唯一访问密码，redis 部署时为管理员密码 | 任意字符串 | （空） |
| SITE_NAME | 站点名称 | 任意字符串 | KatelyaTV |
| ANNOUNCEMENT | 站点公告 | 任意字符串 | 本网站仅提供影视信息搜索服务，所有内容均来自第三方网站。本站不存储任何视频资源，不对任何内容的准确性、合法性、完整性负责。 |
| NEXT_PUBLIC_STORAGE_TYPE | 播放记录/收藏的存储方式 | localstorage、redis、d1、upstash | localstorage |
| REDIS_URL | redis 连接 url，若 NEXT_PUBLIC_STORAGE_TYPE 为 redis 则必填 | 连接 url | 空 |
| UPSTASH_URL | upstash redis 连接 url（REST API） | 连接 url | 空 |
| UPSTASH_TOKEN | upstash redis 连接 token（REST API） | 连接 token | 空 |
| NEXT_PUBLIC_ENABLE_REGISTER | 是否开放注册，仅在非 localstorage 部署时生效 | true / false | false |
| NEXT_PUBLIC_SEARCH_MAX_PAGE | 搜索接口可拉取的最大页数 | 1-50 | 5 |
| NEXT_PUBLIC_IMAGE_PROXY | 默认的浏览器端图片代理 | url prefix | (空) |
| NEXT_PUBLIC_DOUBAN_PROXY | 默认的浏览器端豆瓣数据代理 | url prefix | (空) |
### 🔧 配置验证
**部署后可通过以下方式验证环境变量是否生效：**
1. **访问服务状态页**：`http://your-domain/api/server-config`
2. **检查管理员面板**：使用管理员账号登录后访问 `/admin`
3. **查看容器日志**：
```bash
# Docker 单容器
docker logs katelyatv
# Docker Compose
docker compose logs katelyatv
```
## � 配置说明
所有可自定义项集中在根目录的 `config.json` 中：
编辑 `config.json` 文件：
```json
{
@@ -1348,314 +240,132 @@ echo $UPSTASH_TOKEN # 应该是长字符串令牌
"name": "示例资源站",
"detail": "https://example.com"
}
// ...更多站点
}
}
```
- `cache_time`：接口缓存时间（秒）。
- `api_site`：你可以增删或替换任何资源站，字段说明：
- `key`：唯一标识，保持小写字母/数字。
- `api`：资源站提供的 `vod` JSON API 根地址。
- `name`：在人机界面中展示的名称。
- `detail`：（可选）部分无法通过 API 获取剧集详情的站点，需要提供网页详情根 URL，用于爬取。
---
KatelyaTV 支持标准的苹果 CMS V10 API 格式。
## 📱 高级功能
修改后 **无需重新构建**，服务会在启动时读取一次。
### TVBox 兼容
## 👨‍💼 管理员配置
支持 TVBox 配置接口，可以将视频源导入到各种电视盒子应用：
**该特性目前仅支持通过非 localstorage 存储的部署方式使用**
- **配置地址**：`https://your-domain.com/api/tvbox?format=json`
- **详细说明**：查看 [TVBox 配置指南](docs/TVBOX.md)
支持在运行时动态变更服务配置
### 跳过片头片尾
设置环境变量 USERNAME 和 PASSWORD 即为站长用户，站长可设置用户为管理员
智能跳过片头片尾功能：
站长或管理员访问 `/admin` 即可进行管理员配置
- 🎯 自动检测已设置的跳过片段
- ⚙️ 手动设置跳过时间段（精确到秒）
- 🔄 支持多设备同步（需配置 Redis/D1/Upstash）
### 🔧 视频源配置管理
### AndroidTV 支持
管理员界面提供了完整的视频源配置管理功能：
配合 [OrionTV](https://github.com/zimplexing/OrionTV) 在 Android TV 上使用：
#### 📤 导出配置
1. 在 OrionTV 中填入 KatelyaTV 部署地址
2. 输入设置的 PASSWORD
3. 即可在电视上观看
- **一键导出**：点击"📤 导出配置"按钮，系统会自动生成符合标准格式的 `config.json` 文件
- **自动格式化**：导出的配置文件包含所有已启用的视频源，格式完全符合项目要求
- **本地保存**：配置文件会自动下载到浏览器的下载文件夹，文件名包含日期标记
---
#### 📂 导入配置
## 🛠️ 管理与维护
- **文件选择**：点击"📂 导入配置"按钮，选择本地的 `.json` 配置文件
- **格式验证**：系统会自动验证配置文件格式，确保数据正确性
- **批量导入**：支持一次性导入多个视频源，显示详细的导入结果
- **错误提示**：如果导入过程中出现错误，会显示具体的错误信息
### 升级更新
#### 📋 支持的配置格式
```bash
# Docker 升级
docker compose pull && docker compose up -d
```json
{
"cache_time": 7200,
"api_site": {
"source_key": {
"api": "https://example.com/api.php/provide/vod",
"name": "视频源名称",
"detail": "https://example.com" // 可选
}
}
}
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f
```
#### ✨ 其他管理功能
### 数据备份
- **拖拽排序**：支持通过拖拽调整视频源的优先级顺序
- **启用/禁用**：可以临时禁用某个视频源而不删除配置
- **实时生效**：所有配置修改都会立即生效，无需重启服务
```bash
# Redis 数据备份
docker compose exec redis redis-cli BGSAVE
> **💡 提示**：导入的配置会永久保存在数据库中，不会因为浏览器刷新而丢失。这比直接修改 `config.json` 文件更加可靠和方便。
# Kvrocks 数据备份
docker run --rm \
-v katelyatv_kvrocks-data:/data \
-v $(pwd):/backup \
alpine tar czf /backup/kvrocks-backup.tar.gz /data
```
## 📱 AndroidTV 使用
### 常见问题
目前该项目可以配合 [OrionTV](https://github.com/zimplexing/OrionTV) 在 Android TV 上使用，可以直接作为 OrionTV 后端
| 问题 | 解决方案 |
| ---------------- | ------------------------------------------- |
| 无法访问 | 检查端口 3000 是否开放 |
| 密码错误 | 检查 PASSWORD 环境变量 |
| Redis 连接失败 | 检查 Redis 容器状态和网络 |
| Kvrocks 认证错误 | 查看 [详细文档](docs/KVROCKS_DEPLOYMENT.md) |
### 🆕 v0.5.0-katelya 修复说明
---
**修复了 OrionTV 客户端无法播放的问题**：
## 🔒 安全提醒
- **✅ 新增 CORS 支持**：为所有 API 路由添加了跨域请求头部，解决 OrionTV 客户端访问问题
- **✅ 修复认证拦截**：调整了中间件配置，确保 OrionTV 必需的 API 路由不被认证系统拦截
- **✅ 兼容性优化**：优化了搜索、详情、图片代理等关键 API 的响应头部
### 强烈建议
**如果你之前遇到"OrionTV 显示了资源但点击无法播放"的问题，现在应该已经解决了！**
- **设置密码**：避免公开访问，防范法律风险
- **个人使用**：请勿公开分享实例链接
- **遵守法律**：确保使用行为符合当地法规
### 📱 OrionTV 配置方法
1. **下载 OrionTV 客户端**：在 Android TV 上安装 OrionTV 应用
2. **配置 API 地址**：在 OrionTV 中填入你的 KatelyaTV 部署地址
3. **输入密码**：填写你设置的 PASSWORD 环境变量
4. **测试播放**：尝试搜索和播放视频
### 🔍 故障排除
如果还有播放问题，请检查：
- 确保你的 KatelyaTV 版本是 v0.5.0-katelya 或更新版本
- 确认已正确配置视频源（参考本文档的配置文件说明）
- 检查网络连接和防火墙设置
- 确保密码配置正确
暂时收藏夹与播放记录和网页端隔离，后续会支持同步用户数据
## 🗓️ Roadmap
- [x] 深色模式
- [x] 持久化存储
- [x] 多账户
- [x] 观看历史记录
- [x] PWA 支持
- [x] 豆瓣集成
- [ ] 弹幕系统
- [ ] 字幕支持
- [ ] 下载功能
- [ ] 社交分享
## ⚠️ 安全与隐私提醒
### 强烈建议设置密码保护
为了您的安全和避免潜在的法律风险，我们**强烈建议**在部署时设置密码保护：
- **避免公开访问**：不设置密码的实例任何人都可以访问，可能被恶意利用
- **防范版权风险**：公开的视频搜索服务可能面临版权方的投诉举报
- **保护个人隐私**：设置密码可以限制访问范围，保护您的使用记录
### 部署建议
1. **设置环境变量 `PASSWORD`**：为您的实例设置一个强密码
2. **仅供个人使用**：请勿将您的实例链接公开分享或传播
3. **遵守当地法律**：请确保您的使用行为符合当地法律法规
### 重要声明
### 免责声明
- 本项目仅供学习和个人使用
- 请勿将部署的实例用于商业用途或公开服务
- 如因公开分享导致的任何法律问题，用户需自行承担责任
- 项目开发者不对用户的使用行为承担任何法律责任
- 请勿用于商业用途或公开服务
- 用户需对使用行为承担法律责任
---
## 🤝 贡献与支持
### 技术栈
- **前端**：Next.js 14, TypeScript, Tailwind CSS
- **播放器**：ArtPlayer, HLS.js
- **存储**：Redis, Kvrocks, Cloudflare D1, Upstash
- **部署**：Docker, Vercel, Cloudflare Pages
### Star History
[![Star History Chart](https://api.star-history.com/svg?repos=katelya77/KatelyaTV&type=Date)](https://star-history.com/#katelya77/KatelyaTV&Date)
### 支持项目
如果这个项目对您有帮助，欢迎给个 ⭐ Star！
<div align="center">
<img src="public/wechat.jpg" alt="微信支付" width="200">
<br>
<strong>请开发者喝杯咖啡 ☕</strong>
</div>
---
## 📄 License
[MIT](LICENSE) © 2025 KatelyaTV & Contributors
## ⭐ Star History
## 🙏 致谢
- [LibreTV](https://github.com/LibreSpark/LibreTV) — 项目启发
- [LunaTV](https://github.com/MoonTechLab/LunaTV) — 原始项目基础
- [ArtPlayer](https://github.com/zhw2590582/ArtPlayer) — 强大的网页视频播放器
- 感谢所有贡献者和支持者
---
<div align="center">
[![Star History Chart](https://api.star-history.com/svg?repos=katelya77/KatelyaTV&type=Date)](https://star-history.com/#katelya77/KatelyaTV&Date)
<p>❤️ Made with love by KatelyaTV Community</p>
</div>
## 💖 支持项目
如果这个项目对您有帮助，欢迎给个 ⭐️ Star 支持一下！
您也可以通过以下方式支持项目的持续开发：
<div align="center">
### 请开发者喝杯咖啡 ☕
<table>
<tr>
<td align="center">
<img src="public/wechat.jpg" alt="微信支付" width="200">
<br>
<strong>微信支付</strong>
</td>
</tr>
</table>
> 💝 感谢您的支持！您的捐赠将用于项目的持续维护和功能改进。
</div>
## � 推荐配置文件说明
### 🎯 为什么需要配置文件？
为了项目的长期稳定运行和合规性，我们根据用户社区的建议，将内置的视频源移除。这样做的好处包括：
- **🛡️ 降低法律风险**：避免项目因内置资源问题而受到影响
- **⚡ 提升加载速度**：减少应用本体大小，提高启动速度
- **🔧 更灵活配置**：用户可以根据需要选择最适合的资源站
- **📈 长期维护性**：确保项目能够持续健康发展
### 📥 获取推荐配置
我们为用户精心准备了一个经过测试和优化的配置文件：
**📂 配置文件下载链接**: [https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file](https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file)
**📂 配置文件 Plus 下载地址**: [配置文件 Plus 版本【94 片源】](https://www.mediafire.com/file/fbpk1mlupxp3u3v/configplus.json/file)
### ✨ 配置文件特点
- ✅ **经过充分测试**：所有资源站均经过可用性验证
- ⚡ **响应速度优化**：优选响应快速的资源接口
- 🎬 **内容丰富**：覆盖电影、电视剧、综艺、动漫等多种类型
- 🔄 **定期更新**：我们会根据可用性定期更新推荐配置
---
## 🛠️ 故障排除
### 🐳 Docker 部署问题
#### Docker + Kvrocks 认证错误
如果遇到以下错误：
```
❌ Kvrocks Client Error: [Error]: ERR Client sent AUTH, but no password is set
```
**解决方案**：这是密码配置不一致导致的，请参考 [Kvrocks 修复报告](./KVROCKS_FIX_REPORT.md) 获取详细解决方案。
**快速修复步骤**：
1. 选择正确的部署配置：
- 无密码部署：`docker-compose.kvrocks.yml`
- 密码认证部署：`docker-compose.kvrocks.auth.yml`
2. 正确配置环境变量中的 `KVROCKS_PASSWORD`
3. 重新启动服务
#### 其他 Docker 问题
| 问题 | 可能原因 | 解决方案 |
| ---------------------- | ---------------- | ------------------------------ |
| 端口冲突 (port in use) | 3000 端口被占用 | 修改端口映射 `-p 3001:3000` |
| 连接超时 | 防火墙阻止访问 | 开放 3000 端口或检查防火墙设置 |
| 镜像拉取失败 | 网络问题 | 使用代理或更换 Docker 镜像源 |
| 容器启动失败 | 环境变量配置错误 | 检查环境变量格式和必填项 |
### ☁️ 云平台部署问题
#### Vercel 部署问题
| 问题 | 解决方案 |
| -------------- | --------------------------------------- |
| 构建失败 | 检查环境变量设置，确认 Node.js 版本兼容 |
| 函数超时 | 检查是否为 Edge Runtime 兼容性问题 |
| 环境变量不生效 | 重新部署，确认变量名拼写正确 |
#### Cloudflare Pages 问题
| 问题 | 解决方案 |
| ----------------- | -------------------------------------------- |
| D1 数据库连接失败 | 检查数据库绑定和初始化 SQL |
| 构建失败 | 确认 `pages:build` 脚本配置正确 |
| 权限错误 | 检查 Cloudflare 账户权限和 D1 数据库访问权限 |
### 🔍 调试工具
#### 配置检查脚本
```bash
# 检查所有部署配置文件
node scripts/check-deployment-configs.js
# 测试 Kvrocks 连接
node scripts/test-kvrocks-deployment.js
# 验证 Kvrocks 密码修复
node scripts/verify-kvrocks-fix.js
```
#### 日志查看
```bash
# Docker 日志
docker logs katelyatv
docker-compose logs -f
# Vercel 日志
vercel logs
# Cloudflare Pages 日志
# 在 Cloudflare Dashboard 中查看构建日志
```
### 📖 详细文档
- [Kvrocks 部署指南](./docs/KVROCKS_DEPLOYMENT.md) - 完整的 Kvrocks 部署教程
- [Kvrocks 修复报告](./KVROCKS_FIX_REPORT.md) - 密码认证问题修复详情
- [TVBox 配置指南](./docs/TVBOX.md) - TVBox 兼容功能说明
- [D1 迁移指南](./D1_MIGRATION.md) - Cloudflare D1 数据库升级说明
### 🆘 获取帮助
如果上述方案都无法解决问题：
1. **检查日志**：查看应用和数据库的详细日志
2. **运行诊断**：使用提供的测试脚本进行诊断
3. **社区支持**：在 GitHub Issues 中描述问题和环境信息
4. **文档查阅**：参考相关部署方案的详细文档
---
### 🛡️ 使用声明
- 提供的配置文件仅供学习交流和技术测试使用
- 所有资源均来源于公开的网络接口，请用户自行判断使用的合法性
- 我们不对任何第三方资源的内容质量或合法性承担责任
- 强烈建议用户仅使用合法、正版的影视内容
---
## �🙏 致谢
- [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) — 原始项目与作者社区，感谢原作奠定坚实基础。
- [ArtPlayer](https://github.com/zhw2590582/ArtPlayer) — 提供强大的网页视频播放器。
- [HLS.js](https://github.com/video-dev/hls.js) — 实现 HLS 流媒体在浏览器中的播放支持。
- 感谢所有提供免费影视接口的站点。
README_new.md
+371
View File
@@ -0,0 +1,371 @@
<div align="center">
<img 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>
<a href="#-快速开始">🚀 快速开始</a> ·
<a href="#-功能特性">✨ 功能特性</a> ·
<a href="#-部署方案">📋 部署方案</a> ·
<a href="#-配置说明">⚙️ 配置说明</a>
</p>
</div>
---
## 📰 项目声明
本项目自「MoonTV」演进而来，为其二创/继承版本，持续维护与改进功能与体验。保留并致谢原作者与社区贡献者。
> **🔔 重要变更**：应用户社区建议，为确保项目长期稳定运行和合规性，内置视频源已移除。现需要用户自行配置资源站以使用完整功能。我们提供了经过测试的推荐配置文件，让您快速上手使用。
---
## ✨ 功能特性
### 🎬 核心功能
- **🔍 聚合搜索**：整合多个影视资源站，一键搜索全网内容
- **📺 高清播放**：基于 ArtPlayer 的强大播放器，支持多种格式
- **⏭️ 智能跳过**：自动检测并跳过片头片尾，手动设置跳过时间段
- **🎯 断点续播**：自动记录播放进度，跨设备同步观看位置
- **📱 响应式设计**：完美适配手机、平板、电脑各种屏幕
### 💾 数据管理
- **⭐ 收藏功能**：收藏喜欢的影视作品，支持跨设备同步
- **📖 播放历史**：自动记录观看历史，快速找回看过的内容
- **👥 多用户支持**：独立的用户系统，每个用户独享个人数据
- **🔄 数据同步**：支持多种存储后端（LocalStorage、Redis、D1、Upstash）
### 🚀 部署特性
- **🐳 Docker 一键部署**：提供完整的 Docker 镜像，开箱即用
- **☁️ 多平台支持**：Vercel、Docker、Cloudflare Pages 全兼容
- **🔧 灵活配置**：支持自定义资源站、代理设置、主题配置
- **📱 PWA 支持**：可安装为桌面/手机应用
- **📺 TVBox 兼容**：支持 TVBox 配置接口
---
## 🚀 快速开始
### 推荐方案选择
| 用户类型 | 推荐方案 | 特点 |
| ----------- | ---------------- | -------------------- |
| 🆕 新手用户 | Docker 单容器 | 最简单，5 分钟部署 |
| 👥 多人使用 | Vercel + Upstash | 免费，支持多用户 |
| 🏠 自托管 | Docker + Redis | 功能完整，数据可控 |
| 🏢 生产环境 | Docker + Kvrocks | 高可靠性，零丢失风险 |
---
## 📋 部署方案
### 方案一：Docker 单容器（推荐新手）
**适合场景**：个人使用，最简单的部署方式
```bash
# 一键启动
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_password \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
# 访问 http://localhost:3000
```
**自定义配置文件（可选）**：
```bash
# 挂载配置文件
docker run -d \
--name katelyatv \
-p 3000:3000 \
--env PASSWORD=your_password \
-v ./config.json:/app/config.json:ro \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest
```
### 方案二：Docker + Redis（多用户推荐）
**适合场景**：家庭/团队使用，支持多用户和数据同步
```bash
# 下载配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/docker-compose.redis.yml
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.redis.example
cp .env.redis.example .env
# 编辑环境变量
nano .env
# 启动服务
docker compose -f docker-compose.redis.yml up -d
```
**重要环境变量配置**：
```bash
# 存储类型
NEXT_PUBLIC_STORAGE_TYPE=redis
# 管理员账号
USERNAME=admin
PASSWORD=your_admin_password
# Redis配置
REDIS_URL=redis://katelyatv-redis:6379
# 开启用户注册
NEXT_PUBLIC_ENABLE_REGISTER=true
```
### 方案三：Docker + Kvrocks（高可靠性）
**适合场景**：生产环境，需要极高的数据可靠性
```bash
# 下载配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/docker-compose.kvrocks.yml
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.kvrocks.example
cp .env.kvrocks.example .env
# 编辑环境变量
nano .env
# 启动服务（无密码版本）
docker compose -f docker-compose.kvrocks.yml up -d
# 如需密码认证版本，使用：
# docker compose -f docker-compose.kvrocks.auth.yml up -d
```
**Kvrocks 优势**：
- 🛡️ **极高可靠性**：基于 RocksDB，数据持久化到磁盘
- ⚡ **性能优异**：完全兼容 Redis 协议，性能更佳
- 💾 **节省内存**：数据存储在磁盘，内存使用量大幅降低
> 详细部署指南请查看：[Kvrocks 部署文档](docs/KVROCKS_DEPLOYMENT.md)
### 方案四：Vercel + Upstash（免费推荐）
**适合场景**：无服务器，免费部署，支持多用户
1. **Fork 仓库**：Fork [KatelyaTV](https://github.com/katelya77/KatelyaTV) 到你的 GitHub
2. **部署到 Vercel**：
- 登录 [Vercel](https://vercel.com/)，导入你的仓库
- 添加环境变量：`PASSWORD=your_password`
- 点击 Deploy
3. **配置多用户（可选）**：
```bash
# 创建 Upstash Redis 数据库
# 在 Vercel 中添加环境变量：
NEXT_PUBLIC_STORAGE_TYPE=upstash
UPSTASH_URL=https://xxx.upstash.io
UPSTASH_TOKEN=your_token
NEXT_PUBLIC_ENABLE_REGISTER=true
USERNAME=admin
PASSWORD=admin_password
```
### 方案五：Cloudflare + D1（技术爱好者）
**适合场景**：全球 CDN 加速，免费但配置稍复杂
```bash
# 下载配置文件
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/wrangler.toml
curl -O https://raw.githubusercontent.com/katelya77/KatelyaTV/main/.env.cloudflare.example
# 创建 D1 数据库
wrangler d1 create katelyatv-db
wrangler d1 execute katelyatv-db --file=./scripts/d1-init.sql
# 部署
wrangler pages deploy
```
---
## ⚙️ 配置说明
### 🔧 环境变量
| 变量名 | 说明 | 默认值 |
| ----------------------------- | ---------------- | ------------ |
| `PASSWORD` | 访问密码（必填） | 无 |
| `USERNAME` | 管理员用户名 | 无 |
| `SITE_NAME` | 站点名称 | KatelyaTV |
| `NEXT_PUBLIC_STORAGE_TYPE` | 存储类型 | localstorage |
| `REDIS_URL` | Redis 连接地址 | 无 |
| `NEXT_PUBLIC_ENABLE_REGISTER` | 开启用户注册 | false |
### 📁 视频源配置
> **重要**：为保障项目合规性，需要配置视频源才能正常使用。
#### 方法一：使用推荐配置（推荐）
1. 下载配置文件：
- [基础版 config.json](https://www.mediafire.com/file/xl3yo7la2ci378w/config.json/file)
- [Plus 版（94 个片源）](https://www.mediafire.com/file/fbpk1mlupxp3u3v/configplus.json/file)
2. 配置方式：
- **Docker**：挂载配置文件 `-v ./config.json:/app/config.json:ro`
- **Vercel**：替换仓库中的 `config.json` 文件内容
- **管理员界面**：登录后台 `/admin` 导入配置
#### 方法二：手动配置
编辑 `config.json` 文件：
```json
{
"cache_time": 7200,
"api_site": {
"example": {
"api": "https://example.com/api.php/provide/vod",
"name": "示例资源站",
"detail": "https://example.com"
}
}
}
```
---
## 📱 高级功能
### TVBox 兼容
支持 TVBox 配置接口，可以将视频源导入到各种电视盒子应用：
- **配置地址**：`https://your-domain.com/api/tvbox?format=json`
- **详细说明**：查看 [TVBox 配置指南](docs/TVBOX.md)
### 跳过片头片尾
智能跳过片头片尾功能：
- 🎯 自动检测已设置的跳过片段
- ⚙️ 手动设置跳过时间段（精确到秒）
- 🔄 支持多设备同步（需配置 Redis/D1/Upstash）
### AndroidTV 支持
配合 [OrionTV](https://github.com/zimplexing/OrionTV) 在 Android TV 上使用：
1. 在 OrionTV 中填入 KatelyaTV 部署地址
2. 输入设置的 PASSWORD
3. 即可在电视上观看
---
## 🛠️ 管理与维护
### 升级更新
```bash
# Docker 升级
docker compose pull && docker compose up -d
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f
```
### 数据备份
```bash
# Redis 数据备份
docker compose exec redis redis-cli BGSAVE
# Kvrocks 数据备份
docker run --rm \
-v katelyatv_kvrocks-data:/data \
-v $(pwd):/backup \
alpine tar czf /backup/kvrocks-backup.tar.gz /data
```
### 常见问题
| 问题 | 解决方案 |
| ---------------- | ------------------------------------------- |
| 无法访问 | 检查端口 3000 是否开放 |
| 密码错误 | 检查 PASSWORD 环境变量 |
| Redis 连接失败 | 检查 Redis 容器状态和网络 |
| Kvrocks 认证错误 | 查看 [详细文档](docs/KVROCKS_DEPLOYMENT.md) |
---
## 🔒 安全提醒
### 强烈建议
- **设置密码**：避免公开访问，防范法律风险
- **个人使用**：请勿公开分享实例链接
- **遵守法律**：确保使用行为符合当地法规
### 免责声明
- 本项目仅供学习和个人使用
- 请勿用于商业用途或公开服务
- 用户需对使用行为承担法律责任
---
## 🤝 贡献与支持
### 技术栈
- **前端**：Next.js 14, TypeScript, Tailwind CSS
- **播放器**：ArtPlayer, HLS.js
- **存储**：Redis, Kvrocks, Cloudflare D1, Upstash
- **部署**：Docker, Vercel, Cloudflare Pages
### Star History
[![Star History Chart](https://api.star-history.com/svg?repos=katelya77/KatelyaTV&type=Date)](https://star-history.com/#katelya77/KatelyaTV&Date)
### 支持项目
如果这个项目对您有帮助，欢迎给个 ⭐ Star！
<div align="center">
<img src="public/wechat.jpg" alt="微信支付" width="200">
<br>
<strong>请开发者喝杯咖啡 ☕</strong>
</div>
---
## 📄 License
[MIT](LICENSE) © 2025 KatelyaTV & Contributors
## 🙏 致谢
- [LibreTV](https://github.com/LibreSpark/LibreTV) — 项目启发
- [LunaTV](https://github.com/MoonTechLab/LunaTV) — 原始项目基础
- [ArtPlayer](https://github.com/zhw2590582/ArtPlayer) — 强大的网页视频播放器
- 感谢所有贡献者和支持者
---
<div align="center">
<p>❤️ Made with love by KatelyaTV Community</p>
</div>
SKIP_CONTROLLER_TEST.md
-99
View File
@@ -1,99 +0,0 @@
# 跳过控制器片尾倒计时功能测试指南
## 测试目标
验证新优化的片尾倒计时功能是否正确基于剩余时间工作
## 测试准备
1. 服务器已启动在 http://localhost:3001
2. SkipController 组件已优化完成
3. 支持两种模式：剩余时间模式（推荐）和绝对时间模式
## 测试步骤
### 测试 1：剩余时间模式（主要功能）
1. 打开任意视频播放页面
2. 点击跳过设置按钮（⚙️ 图标）
3. 在"片尾设置"部分：
- 选择"剩余时间（推荐）"模式
- 设置剩余时间为 "0:30"（30 秒）
- 启用"自动下一集"选项
4. 点击"保存批量设置"
5. 播放视频并快进到接近结束前 30 秒
6. 预期结果：
- 当剩余时间为 30 秒时开始倒计时
- 显示倒计时界面："X 秒后自动播放下一集"
- 倒计时结束后自动跳转下一集
### 测试 2：绝对时间模式（兼容性）
1. 在跳过设置中：
- 选择"绝对时间"模式
- 设置开始时间为 "1:00"（1 分钟）
2. 点击"保存批量设置"
3. 从视频开始播放
4. 预期结果：
- 当播放到第 1 分钟时开始检测片尾
- 行为与旧版本一致
### 测试 3：界面交互测试
1. 验证模式切换时提示文本的变化：
- 剩余时间模式：显示"基于剩余时间倒计时（如：还剩 2 分钟时开始）"
- 绝对时间模式：显示"基于播放时间（如：播放到第 20 分钟时开始）"
2. 验证输入框 placeholder 的变化：
- 剩余时间模式：placeholder 显示"2:00"
- 绝对时间模式：placeholder 显示"20:00"
3. 验证标签文本的变化：
- 剩余时间模式：显示"剩余时间 (分:秒)"
- 绝对时间模式：显示"开始时间 (分:秒)"
## 验证要点
### 功能正确性
- [x] 剩余时间模式能正确计算实际开始时间（duration - remainingTime）
- [x] 绝对时间模式保持原有行为
- [x] 倒计时显示正确的剩余秒数
- [x] 倒计时结束后正确跳转下一集
### 用户体验
- [x] 界面文字清晰易懂
- [x] 默认使用推荐的剩余时间模式
- [x] 提供取消倒计时的选项
- [x] 配置保存后立即生效
### 技术实现
- [x] 无语法错误，编译成功
- [x] 保持向后兼容性
- [x] 正确的依赖管理
- [x] 合理的错误处理
## 测试结果记录
### 编译测试 ✅
- 组件无语法错误
- TypeScript 类型检查通过
- Next.js 开发服务器启动成功
### 功能测试 📋
需要手动测试：
1. 视频播放页面的跳过设置界面
2. 剩余时间模式的倒计时触发
3. 绝对时间模式的兼容性
4. 用户界面交互响应
## 相关文件
- 主要组件：`src/components/SkipController.tsx`
- 测试页面：播放页面 `/play`
- 功能文档：`SKIP_CONTROLLER_UPDATE.md`
这个测试指南确保新功能按预期工作，解决了用户提出的"片尾是倒计时，就是还有几分钟结束跳到下一集"的需求。
SKIP_CONTROLLER_UPDATE.md
-101
View File
@@ -1,101 +0,0 @@
# 跳过控制器功能优化：片尾倒计时改进
## 概述
我们已经优化了 SkipController 组件的片尾倒计时功能，现在支持基于剩余时间的倒计时模式，更符合用户的使用习惯。
## 主要改进
### 1. 新增片尾计时模式选择
- **剩余时间模式（推荐）**：基于视频剩余时间进行倒计时
- 例如：设置 "2:00" 表示还剩 2 分钟时开始倒计时
- 适用于不同长度的剧集，更加智能
- **绝对时间模式**：基于视频开始播放的时间
- 例如：设置 "20:00" 表示播放到第 20 分钟时开始检测
- 保持旧版本的兼容性
### 2. 用户界面改进
- 添加了模式选择单选框
- 根据选择的模式动态更新标签和提示文本
- 更清晰的帮助说明文档
### 3. 技术实现详情
#### 配置结构变更
```typescript
const batchSettings = {
openingStart: '0:00', // 片头开始时间
openingEnd: '1:30', // 片头结束时间
endingMode: 'remaining', // 新增：片尾模式选择
endingStart: '2:00', // 片尾开始时间（默认改为剩余时间）
endingEnd: '', // 片尾结束时间（可选）
autoSkip: true, // 自动跳过开关
autoNextEpisode: true, // 自动下一集开关
};
```
#### 核心逻辑变更
```typescript
// 根据模式计算实际的开始时间
let actualStartSeconds: number;
if (batchSettings.endingMode === 'remaining') {
// 剩余时间模式：从视频总长度减去剩余时间
actualStartSeconds = duration - endingStartSeconds;
} else {
// 绝对时间模式：使用输入的时间
actualStartSeconds = endingStartSeconds;
}
```
## 使用指南
### 设置剩余时间模式片尾（推荐）
1. 在视频播放页面点击跳过设置按钮
2. 选择"片尾设置"部分
3. 在"计时模式"中选择"剩余时间（推荐）"
4. 在"剩余时间"字段输入期望的时间，例如 "2:00"
5. 点击"保存批量设置"
这样设置后，当视频剩余时间为 2 分钟时，将开始倒计时并自动跳转到下一集。
### 设置绝对时间模式片尾（兼容性）
1. 在"计时模式"中选择"绝对时间"
2. 在"开始时间"字段输入视频播放时间，例如 "20:00"
3. 点击"保存批量设置"
这样设置后，当视频播放到第 20 分钟时，将开始检测片尾。
## 实际效果
### 剩余时间模式
- 对于 25 分钟的剧集，设置 "2:00" 剩余时间
- 实际在第 23 分钟（25-2=23）开始倒计时
- 倒计时 2 分钟后自动跳转下一集
### 绝对时间模式
- 设置 "20:00" 绝对时间
- 实际在第 20 分钟开始检测片尾
- 无论剧集长度如何，都在第 20 分钟触发
## 向后兼容性
- 现有的跳过配置会继续正常工作
- 默认新配置使用推荐的剩余时间模式
- 用户可以随时在两种模式间切换
## 技术细节
- 组件文件：`src/components/SkipController.tsx`
- 核心倒计时逻辑已经支持剩余时间计算
- 主要改进是配置界面和批量设置逻辑
- 包含输入验证和错误处理
这个优化解决了用户提出的"片尾是倒计时，就是还有几分钟结束跳到下一集"的需求，让跳过功能更加智能和实用。
SKIP_FEATURE_GUIDE.md
-123
View File
@@ -1,123 +0,0 @@
# 🎬 智能跳过功能使用指南
## ✨ 功能特色
### 🚀 全新智能跳过体验
- **🎯 分:秒格式输入** - 更符合观影习惯，如 `2:10` 表示 2 分 10 秒
- **⚡ 自动跳过** - 无需手动点击，到达设定时间自动跳转
- **🎭 智能片尾** - 可设置从指定时间直接跳转下一集
- **🎨 优化布局** - 悬浮式配置显示，不与内容重叠
## 📱 使用方法
### 1. 开启跳过设置
在播放页面，点击标题右侧的 **"跳过设置"** 按钮
### 2. 智能配置模式（推荐）
#### 全局开关
- ✅ **启用自动跳过** - 到达时间自动跳转，无需手动点击
- ✅ **片尾自动播放下一集** - 片尾时显示倒计时，自动播放下一集
#### 片头设置
- **开始时间**: `0:00` (通常从视频开始)
- **结束时间**: `2:10` (跳过 2 分 10 秒的片头)
#### 片尾设置
- **开始时间**: `19:20` (从 19 分 20 秒开始检测片尾)
- **结束时间**: 留空 (直接跳转下一集) 或 `20:50` (跳过片尾到此时间)
### 3. 支持的时间格式
- **分:秒格式**: `2:10`, `19:20`, `1:30.5`
- **秒数格式**: `130`, `1160`, `90.5`
- **自动识别**: 系统会自动识别并转换格式
## 🎯 使用场景示例
### 场景一：跳过片头
```
片头设置:
开始时间: 0:00
结束时间: 2:10
效果: 视频开始播放时，自动从0秒跳转到2分10秒
```
### 场景二：片尾直接下一集
```
片尾设置:
开始时间: 19:20
结束时间: 留空
效果: 播放到19分20秒时，显示倒计时，自动播放下一集
```
### 场景三：跳过片头+片尾
```
片头: 0:00 → 2:10 (跳过片头)
片尾: 19:20 → 留空 (直接下一集)
效果: 完全自动化的观影体验
```
## 🎨 界面说明
### 播放时显示
- **倒计时器**: 片尾时屏幕中央显示"X 秒后自动播放下一集"
- **跳过提示**: 自动跳过时显示"自动跳过片头/片尾"
- **取消按钮**: 可随时取消自动操作
### 配置显示
- **悬浮卡片**: 右下角显示当前跳过配置
- **状态标识**: 显示自动跳过状态
- **快速修改**: 点击卡片可快速修改配置
## ⚙️ 高级功能
### 精确设置
- 支持小数点精度: `90.5` 秒
- 支持多段跳过: 可设置多个片头/片尾段落
- 智能检测: 自动识别当前播放时间是否在跳过区间
### 数据同步
- **LocalStorage**: 单设备本地存储
- **云端同步**: 支持 Redis、D1、Upstash 跨设备同步
- **实时更新**: 配置修改后立即生效
## 🔧 故障排除
### 常见问题
1. **时间格式错误**: 确保使用 `分:秒` 格式，如 `2:10`
2. **配置不生效**: 检查是否开启了"启用自动跳过"开关
3. **重叠显示**: 新版本已修复，配置卡片不会与内容重叠
### 兼容性
- ✅ 支持所有部署方式 (Docker, Vercel, Cloudflare Pages)
- ✅ 支持所有存储后端 (LocalStorage, Redis, D1, Upstash)
- ✅ 支持桌面和移动设备
## 💡 使用技巧
1. **首次设置**: 建议先观看一遍内容，记录片头片尾时间
2. **批量配置**: 使用智能配置模式一次性设置片头和片尾
3. **个性化**: 不同类型的内容可以设置不同的跳过规则
4. **测试验证**: 设置后可以快进到设定时间测试效果
---
🎉 **享受更流畅的观影体验！**
SKIP_OVERLAY_FIX.md
-80
View File
@@ -1,80 +0,0 @@
# 选集点击偏移问题的真正原因和修复
## 问题重现
用户报告：点击第 6 集（紫色框框选中区域）时，系统错误地选择了第 7 集（绿色填充区域）。
## 真正的根因
经过仔细分析，问题**不是**EpisodeSelector 组件本身的布局问题，而是**SkipController 组件的固定定位面板覆盖了选集区域**！
### 罪魁祸首：跳过配置面板
```tsx
// 这个面板positioned fixed bottom-4 right-4，覆盖了选集面板的右下角
<div className="fixed bottom-4 right-4 z-[9998] max-w-sm bg-white/95 dark:bg-gray-800/95 backdrop-blur-sm rounded-lg shadow-lg border border-gray-200 dark:border-gray-600 animate-fade-in">
```
### 问题分析
1. **时机匹配**：用户说这个问题是在添加跳过片头片尾功能后出现的 ✅
2. **位置匹配**：从截图看，第 6 集和第 7 集在选集面板的右下角区域 ✅
3. **覆盖问题**：fixed 定位的面板虽然有 backdrop-blur，但仍然会拦截点击事件 ✅
### 用户体验问题
- 用户点击第 6 集的位置
- 但实际点击被固定面板拦截
- 点击事件"穿透"或被重新路由到第 7 集
- 造成点击偏移的错觉
## 修复方案
### 1. 移动跳过配置面板位置
将面板从右下角移动到左下角，避免与选集面板冲突：
```tsx
// 修复前
<div className="fixed bottom-4 right-4 z-[9998] ...">
// 修复后
<div className="fixed bottom-4 left-4 z-[9998] ...">
```
### 2. 为什么不降低 z-index
- SkipController 的元素需要在视频播放器之上显示
- 降低 z-index 可能导致被其他元素覆盖
- 改变位置是更安全的解决方案
### 3. 为什么不修改 EpisodeSelector
- EpisodeSelector 组件本身的逻辑是正确的
- 问题在于外部覆盖层拦截点击事件
- 修改布局只是治标不治本
## 预期效果
修复后：
1. 跳过配置面板显示在左下角，不会干扰选集面板
2. 用户点击任何集数都能正确选择
3. 保持所有跳过功能的正常工作
4. 用户界面更加合理，避免元素重叠
## 测试验证
1. 打开任意多集剧集
2. 确保有跳过配置（会显示跳过配置面板）
3. 点击选集面板右下角的集数按钮
4. 验证选择的集数是否正确
## 经验教训
- 固定定位元素要特别注意与其他 UI 组件的位置冲突
- 高 z-index 不意味着不会影响用户交互
- backdrop-blur 等视觉效果不影响点击事件的拦截
- 调试此类问题时要考虑所有 fixed/absolute 定位的元素
这个修复彻底解决了点击偏移问题，恢复了正常的用户体验。