KatelyaTV

跨平台 · 聚合搜索 · 即开即用 · 自托管影视聚合播放器
基于 Next.js 14 · TypeScript · Tailwind CSS · 多源聚合 / 播放记录 / 收藏同步 / 跳过片头片尾 / PWA

🚀 快速开始 ·
✨ 功能特性 ·
📋 部署方案 ·
⚙️ 配置说明

---

📰 项目声明

本项目自「MoonTV」演进而来，为其二创/继承版本，持续维护与改进功能与体验。保留并致谢原作者与社区贡献者。

[!IMPORTANT] 重要变更：应用户社区建议，为确保项目长期稳定运行和合规性，内置视频源已移除。现需要用户自行配置资源站以使用完整功能。我们提供了经过测试的推荐配置文件，让您快速上手使用。

---

✨ 功能特性

🎬 核心功能

• 🔍 聚合搜索：整合多个影视资源站，一键搜索全网内容
• 📺 高清播放：基于 ArtPlayer 的强大播放器，支持多种格式
• ⏭️ 智能跳过：自动检测并跳过片头片尾，手动设置跳过时间段
• 🎯 断点续播：自动记录播放进度，跨设备同步观看位置
• 📱 响应式设计：完美适配手机、平板、电脑各种屏幕

💾 数据管理

• ⭐ 收藏功能：收藏喜欢的影视作品，支持跨设备同步
• 📖 播放历史：自动记录观看历史，快速找回看过的内容
• 👥 多用户支持：独立的用户系统，每个用户独享个人数据
• 🔄 数据同步：支持多种存储后端（LocalStorage、Redis、D1、Upstash）
• 🔒 内容过滤：智能成人内容过滤系统，默认开启安全保护

🚀 部署特性

• 🐳 Docker 一键部署：提供完整的 Docker 镜像，开箱即用
• ☁️ 多平台支持：Vercel、Docker、Cloudflare Pages 全兼容
• 🔧 灵活配置：支持自定义资源站、代理设置、主题配置
• 📱 PWA 支持：可安装为桌面/手机应用
• 📺 *** 兼容：支持 *** 配置接口

---

🚀 快速开始

💡 方案选择指南

[!NOTE] 重要提示：成人内容过滤功能需要数据库存储支持，不支持 localstorage 方式

---

📋 部署方案

方案一：Docker 单容器（最简单）

特点：5 分钟部署，个人使用，无多用户功能

docker run -d \
--name katelyatv \
-p 3000:3000 \
-e PASSWORD=your_password \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest

挂载自定义配置（可选）：

docker run -d \
--name katelyatv \
-p 3000:3000 \
-e PASSWORD=your_password \
-v $(pwd)/config.json:/app/config.json:ro \
--restart unless-stopped \
ghcr.io/katelya77/katelyatv:latest

方案二：Docker + Redis（推荐家庭使用）

特点：完整功能，多用户支持，成人内容过滤

# 1. 下载配置文件
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

# 2. 配置环境变量
cp .env.redis.example .env

编辑 .env 文件：

# 管理员账号（必填）
USERNAME=admin
PASSWORD=your_secure_password

# 存储配置
NEXT_PUBLIC_STORAGE_TYPE=redis
REDIS_URL=redis://katelyatv-redis:6379

# 功能开关
NEXT_PUBLIC_ENABLE_REGISTER=true

# 3. 启动服务
docker compose -f docker-compose.redis.yml up -d

💾 数据备份与恢复

备份脚本示例：

#!/bin/bash
# backup.sh - 完整备份脚本
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="backups/$DATE"
mkdir -p $BACKUP_DIR

echo "开始备份 KatelyaTV 数据..."

# 备份配置文件
cp config.json $BACKUP_DIR/config.json
echo "✓ 配置文件备份完成"

# 根据存储类型备份数据
if [ -f .env ] && grep -q "REDIS_URL" .env; then
# Redis 数据备份
docker compose exec redis redis-cli --rdb $BACKUP_DIR/dump.rdb
echo "✓ Redis 数据备份完成"
elif [ -f .env ] && grep -q "UPSTASH" .env; then
# Upstash 数据导出
echo "Upstash 数据需手动在控制台导出"
fi

# Kvrocks 数据备份
if docker compose ps | grep -q kvrocks; then
docker run --rm \
-v katelyatv_kvrocks-data:/data:ro \
-v $(pwd)/$BACKUP_DIR:/backup \
alpine tar czf /backup/kvrocks-data.tar.gz /data
echo "✓ Kvrocks 数据备份完成"
fi

# 压缩备份文件
tar -czf "katelyatv-backup-$DATE.tar.gz" -C backups $DATE
rm -rf $BACKUP_DIR

echo "✓ 备份完成: katelyatv-backup-$DATE.tar.gz"

恢复数据：

#!/bin/bash
# restore.sh - 数据恢复脚本
BACKUP_FILE="$1"

if [ -z "$BACKUP_FILE" ]; then
echo "用法: $0 "
exit 1
fi

echo "恢复数据从: $BACKUP_FILE"
tar -xzf $BACKUP_FILE

# 恢复配置文件
BACKUP_DIR=$(tar -tzf $BACKUP_FILE | head -1 | cut -f1 -d"/")
cp $BACKUP_DIR/config.json ./config.json

# 恢复数据库
if [ -f "$BACKUP_DIR/dump.rdb" ]; then
docker compose exec redis redis-cli FLUSHALL
docker cp $BACKUP_DIR/dump.rdb redis:/data/dump.rdb
docker compose restart redis
fi

echo "✓ 数据恢复完成"

🔍 故障诊断指南

常见问题快速排查：

诊断命令：

# 系统状态检查
docker compose ps
docker compose logs --tail=50

# 网络连通性测试
curl -I http://localhost:3000
wget --spider http://localhost:3000

# 数据库连接测试
# Redis
redis-cli -u $REDIS_URL ping
# 或者
docker compose exec redis redis-cli ping

# 配置文件验证
cat config.json | jq '.'
# 如果没有 jq，可以用 python
python -m json.tool config.json

# 端口占用检查
netstat -tlnp | grep 3000
ss -tlnp | grep 3000

🚨 安全加固

生产环境安全检查清单：

• 设置强密码策略（至少 12 位包含特殊字符）
• 启用 HTTPS（使用 Let's Encrypt 或 Cloudflare）
• 配置防火墙规则（仅开放必要端口）
• 定期更新系统和依赖包
• 设置访问日志监控
• 配置自动备份策略
• 限制管理员界面访问（IP 白名单）
• 启用 fail2ban 防止暴力破解

安全配置示例：

# nginx 配置增强安全性
# /etc/nginx/sites-available/katelyatv
server {
listen 443 ssl http2;
server_name your-domain.com;

# SSL 配置
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
ssl_protocols TLSv1.2 TLSv1.3;

# 安全头
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";

# 限制请求大小
client_max_body_size 10M;

# 速率限制
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/m;

location /api/ {
limit_req zone=api burst=5 nodelay;
proxy_pass http://localhost:3000;
}

location /admin {
# 仅允许特定IP访问管理界面
allow 192.168.1.0/24;
deny all;
proxy_pass http://localhost:3000;
}
}

---

📚 扩展文档

📖 详细指南

功能配置：

• 📺 *** 兼容配置指南
• 💾 Kvrocks 高性能部署
• 🗄️ D1 数据库迁移指南

故障排除：

• 🔧 Docker 故障排除手册
• ⚠️ 兼容性问题解决

🎯 最佳实践

新手快速上手路径：

1. 选择 Vercel + 基础配置（最简单）
2. 升级到 Vercel + Upstash（支持多用户）
3. 进阶到 Docker 自建（完全控制）
4. 终极配置：Kvrocks 集群（高可用）

生产环境推荐方案：

• 小型个人站：Vercel + Upstash
• 中型团队使用：Docker + Redis Cluster
• 大型服务：Kubernetes + Kvrocks 集群
• 全球服务：Cloudflare Pages + D1

🔗 相关资源

官方资源：

• https://github.com/katelya77/KatelyaTV
• https://hub.docker.com/r/katelya77/katelyatv
• https://github.com/katelya77/KatelyaTV/pkgs/container/katelyatv
• https://github.com/katelya77/KatelyaTV/releases

社区支持：

• https://github.com/katelya77/KatelyaTV/discussions
• https://github.com/katelya77/KatelyaTV/issues
• https://github.com/katelya77/KatelyaTV/wiki
• https://github.com/katelya77/KatelyaTV/issues?q=label%3Aenhancement

在线演示：

• 🎬 官方演示站点 (密码: demo123)
• 📱 PWA 功能演示
• 🎨 主题预览站点

🤝 参与贡献

贡献方式：

• ⭐ 给项目点 Star
• 🐛 报告 Bug 和问题
• 💡 提出新功能建议
• 📝 完善文档和翻译
• 💻 贡献代码和修复

开发者指南：

# 本地开发环境搭建
git clone https://github.com/katelya77/KatelyaTV.git
cd KatelyaTV

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 运行测试
pnpm test

# 构建生产版本
pnpm build

# 代码格式化
pnpm lint --fix
pnpm format

---

🔒 安全与合规

🚨 重要提醒

强烈建议：

• ✅ 设置强密码：避免公开访问，保护个人隐私
• ✅ 个人使用：请勿公开分享实例链接或商业使用
• ✅ 遵守***：确保使用行为符合当地******
• ✅ 版权意识：尊重内容版权，支持正版

安全配置：

• 启用 HTTPS 加密传输
• 设置访问密码和用户认证
• 配置 IP 访问限制
• 定期更新和安全检查

⚖️ 免责声明

• 本项目仅供个人学习、研究和合法使用
• 用户需对自己的使用行为承担完全***责任
• 开发者不对用户的任何违法行为承担责任
• 请确保遵守所在地区的******

---

🌟 致谢与支持

🙏 特别感谢

感谢以下优秀的开源项目和技术社区：

核心依赖：

• Next.js — 强大的 React 全栈框架
• https://github.com/zhw2590582/ArtPlayer — 功能丰富的 HTML5 视频播放器
• Tailwind CSS — 实用优先的 CSS 框架
• TypeScript — JavaScript 的超集

基础设施：

• Cloudflare — 全球 CDN 和边缘计算
• Vercel — 现代化的部署平台
• Docker — 容器化部署方案
• Redis — 高性能内存数据库

项目启发：

• https://github.com/LibreSpark/LibreTV — 提供设计理念
• https://github.com/MoonTechLab/LunaTV — 项目基础架构

💝 支持项目发展

如果 KatelyaTV 对您有帮助，欢迎通过以下方式支持项目：

免费支持：

• ⭐ https://github.com/katelya77/KatelyaTV/stargazers
• 🍴 https://github.com/katelya77/KatelyaTV/fork
• 💬 https://github.com/katelya77/KatelyaTV/discussions
• 📖 https://github.com/katelya77/KatelyaTV/tree/main/docs
• 🔗 https://github.com/katelya77/KatelyaTV

赞助支持：

请开发者喝杯咖啡 ☕
您的支持是项目持续发展的动力

企业赞助：
如果您的企业希望赞助 KatelyaTV 项目，请通过 https://github.com/***/katelya77 或发邮件联系我们。

📊 项目统计

Star History：

---

📄 开源协议

本项目基于 MIT License 开源协议发布。

MIT License

Copyright (c) 2025 KatelyaTV & Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

🎉 感谢您选择 KatelyaTV！

如果项目对您有帮助，请给个 ⭐ Star 支持一下！

🏠 项目首页
•
🐛 问题反馈
•
💬 讨论交流
•
📚 使用文档

❤️ Made with love by KatelyaTV Community ❤️