KatelyaTV 部署指南 ✨ 配合 TVBox & OrionTV 深度联动实战！

---

公益站点

• 公益站点：
  https://tv2.910501.xyz/
• TVBox 配置链接（JSON 格式）⚙️：

https://tv2.910501.xyz/api/tvbox/config?format=json&mode=fast

项目地址 🔗

• GitHub 仓库： KatelyaTV — https://github.com/katelya77/KatelyaTV
• 如果本项目对你有帮助，欢迎点个 ⭐️ 支持一下作者，也可以 Fork 去试用与改进！

---

前言

KatelyaTV自「MoonTV」演进而来，为其二创/继承版本，持续维护与改进功能与体验。 内置了 TVBox 配置接口（GET /api/tvbox），并支持 JSON / Base64 / TXT / XML 等格式，TVBox 应用能通过该接口导入频道源、解析器与播放规则。若要实现设备间同步（播放记录、跳过片头片尾、收藏等），部署时需要考虑持久化与缓存策略。

准备工作

• 域名与 HTTPS（必须）：TVBox 导入配置强烈建议使用 HTTPS。
• 配置 CORS：确保 /api/tvbox 与 /api/parse 等接口允许跨域请求。
• 环境变量（常见）：
  • APP_HOST（或 NEXT_PUBLIC_HOST）
  • DATABASE_URL / D1 配置（如使用 Cloudflare D1）
  • REDIS_URL（如使用 Redis / Upstash）
  • SESSION_SECRET、JWT_SECRET 等

---

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

优点：快速、可控，适合个人 VPS / 本地调试。
缺点：单机状态，不利于多实例扩展。

示例 docker-compose（最简单）：

version: "3.8"
services:
  katelyatv:
    image: ghcr.io/katelya77/katelyatv:main-3ce1bd1
    container_name: katelyatv
    restart: unless-stopped
    ports:
      # 本地访问端口：建议修改前面的 3000 为自己喜欢的端口，避免和其他服务冲突
      # 例如改成 "8080:3000" 就是用 http://IP:8080 访问
      - "3030:3000"
    environment:
      - PASSWORD=10000
      # 设置访问密码，建议更换为复杂密码

注意：

• 持久化日志与数据（如果使用内置数据库或 sqlite）。
• 若想支持 TVBox 的多设备状态同步，考虑将缓存/会话外置到 Redis。

---

部署方案二：Docker + Redis（推荐用于家庭多用户）

优点：高性能缓存、跨实例同步（播放记录、跳过片头）、成熟生态。
示例 docker-compose（含 redis）：

version: "3.8"

services:
  katelyatv:
    image: ghcr.io/katelya77/katelyatv:main-3ce1bd1
    container_name: katelyatv
    restart: unless-stopped
    ports:
      # 本地访问端口：建议修改前面的 3000 为自己喜欢的端口，避免和其他服务冲突
      # 例如改成 "8080:3000" 就是用 http://IP:8080 访问
      - "3030:3000"
    environment:
      # 管理员账号（必填，登录用）
      - USERNAME=admin
      # 管理员密码（必填，建议使用复杂密码）
      - PASSWORD=your_secure_password

      # 存储配置：这里指定使用 Redis
      - NEXT_PUBLIC_STORAGE_TYPE=redis
      # Redis 地址，默认使用同一 compose 内的服务名
      - REDIS_URL=redis://katelyatv-redis:6379

      # 功能开关：是否允许新用户注册
      - NEXT_PUBLIC_ENABLE_REGISTER=true

    depends_on:
      - katelyatv-redis

  katelyatv-redis:
    image: redis:7-alpine
    container_name: katelyatv-redis
    restart: unless-stopped
    volumes:
      # 数据持久化，避免容器删除后数据丢失
      - redis_data:/data

volumes:
  redis_data:

小贴士：

• 开启 Redis AUTH，配置持久化与备份。
• 在 KatelyaTV 中配置 REDIS_URL，以启用共享缓存和跳片头等功能。

---

部署方案三：Vercel + Upstash 🚀💸 (免费推荐)

🎯 特点

• 完全免费（适合轻量用户、白嫖党）💰
• 自动开启 HTTPS 🔒
• 全球 CDN 加速，访问速度快 ⚡
• 无需自备服务器，部署流程简单 ✨

---

🚀 部署步骤

1. Fork 项目

• 打开 KatelyaTV GitHub 仓库
• 点击右上角 Fork，把项目复制到自己的 GitHub 账户下

2. 部署到 Vercel

1. 登录 Vercel 官网

2. 点击 New Project → Import Git Repository

3. 选择刚才 Fork 的仓库

4. 在 Environment Variables（环境变量） 添加：

   Plaintext

   PASSWORD=your_password
   

   ⚠️ 这里的 PASSWORD 是管理员登录密码，请修改为复杂密码。

5. 点击 Deploy，稍等片刻，Vercel 会自动完成构建和部署

6. 部署成功后，你将得到一个类似 https://xxxx.vercel.app 的访问地址

---

👥 多用户配置 (推荐)

如果只设置 PASSWORD，只能单用户使用。想要多用户管理，就需要用 Upstash 来存储数据。

1. 创建 Upstash 数据库

1. 登录 Upstash 官网
2. 创建一个免费的 Redis 数据库 📊
3. 获取数据库的连接信息：
   • UPSTASH_URL
   • UPSTASH_TOKEN

2. 添加环境变量

在 Vercel 项目设置里，进入 Settings → Environment Variables，新增：

Plaintext

# 存储配置
NEXT_PUBLIC_STORAGE_TYPE=upstash
UPSTASH_URL=https://xxx.upstash.io
UPSTASH_TOKEN=your_token

# 管理员账号
USERNAME=admin
PASSWORD=your_password

📌 USERNAME 和 PASSWORD 是管理员账号和密码

3. 重新部署

在 Vercel Dashboard → 点击项目 → Redeploy
即可应用新的环境变量配置。🔄

---

✅ 使用体验

• 单用户模式：简单快速，适合个人使用 👩‍💻
• 多用户模式：结合 Upstash，支持多人账号、注册登录、数据持久化 👨‍👩‍👧‍👦
• 免费额度：
  • Vercel 免费版每月 125 小时构建时长 ⏱️
  • Upstash 免费版每月 10,000 次请求，轻度使用绰绰有余 ✨

---

部署方案四：Docker + Kvrocks（生产环境）

优点：Kvrocks 使用 RocksDB，磁盘效率高，适合长期大量数据。
缺点：运维、监控需要注意磁盘 IO 与 compaction。

示例（docker-compose）：

version: "3.8"

services:
  katelyatv:
    image: ghcr.io/katelya77/katelyatv:main-3ce1bd1
    container_name: katelyatv
    restart: unless-stopped
    ports:
      # 宿主机访问端口，可根据需要修改
      # 例如 "8080:3000"，访问 http://IP:8080
      - "3030:3000"
    environment:
      # 管理员账号（必填）
      - USERNAME=admin
      # 管理员密码（必填，请务必修改为强密码，避免使用默认值）
      - PASSWORD=your_secure_password
      # 存储类型：使用 Kvrocks
      - NEXT_PUBLIC_STORAGE_TYPE=kvrocks
      # Kvrocks 连接 URL（容器内服务名 + 容器端口）
      - KVROCKS_URL=redis://kvrocks:6666
      # 是否允许用户注册
      - NEXT_PUBLIC_ENABLE_REGISTER=true
    depends_on:
      # 确保 kvrocks 容器先启动
      - kvrocks

  kvrocks:
    image: apache/kvrocks:latest
    container_name: kvrocks
    restart: unless-stopped
    # 默认配置，不挂载外部 conf 文件，避免找不到报错
    ports:
      # 宿主机端口映射，可修改避免端口冲突
      - "6666:6666"
    volumes:
      # 数据持久化，容器删除后数据仍然保留
      - kvrocks_data:/data

volumes:
  # Kvrocks 数据卷
  kvrocks_data:

适用场景：

• 你希望在低成本 VPS 上获得比传统 Redis 更高的磁盘压缩效果，但仍兼容 Redis 协议。

---

方案五：Cloudflare Pages + D1（全球加速）

特点：全球 CDN，无限带宽，免费 SSL

快速部署

Fork 项目 → GitHub 仓库

创建 Pages 项目：

• 登录 Cloudflare Dashboard
• Pages → Connect to Git → 选择仓库
• 构建设置：
  • Build command:

    pnpm install --frozen-lockfile && pnpm run pages:build
    

  • Build output directory:

    .vercel/output/static
    

  • 兼容性标志：

    nodejs_compat
    

环境变量配置：

# 管理员账号
USERNAME=admin
PASSWORD=your_password

# 存储配置
NEXT_PUBLIC_STORAGE_TYPE=d1

# 功能开关
NEXT_PUBLIC_ENABLE_REGISTER=true

创建 D1 数据库（多用户支持）：

# 安装Wrangler CLI
npm install -g wrangler
wrangler auth login

# 创建数据库
wrangler d1 create katelyatv-db
# ⚠️ 重要：确保在项目根目录下运行此命令
# 如果遇到文件路径错误，请参考 D1_MIGRATION.md 排查指南
wrangler d1 execute katelyatv-db --file=./scripts/d1-init.sql

配置数据库绑定 → 在 wrangler.toml 中添加数据库 ID

---

与 TVBox 的联动细节（核心）

• 接口：/api/tvbox 支持 format 参数（json、base64、txt、xml）。TVBox 通过这个接口导入配置。
• 自动同步：
  • 如果 KatelyaTV 后端开启缓存/同步（Redis / Upstash / D1 / Kvrocks），TVBox 在刷新配置时可以立即看到新增的源。
  • 若使用单容器且未启用共享缓存，多设备间的播放记录/跳片头等功能可能无法同步。
• CORS / HTTPS：强制使用 HTTPS，配置正确的 CORS header，防止 TVBox 导入失败。
• 缓存策略：推荐默认缓存 1 小时，需要即时更新时提供手动刷新接口或短缓存 TTL。

配置地址生成：

• JSON 格式：https://你的域名/api/tvbox?format=json
• TXT 格式：https://你的域名/api/tvbox?format=txt
• XML 格式：https://你的域名/api/tvbox?format=xml

支持的 TVBox 应用：

• TVBox（开源版）
• CatVodTVOfficial
• EasyBox
• FongMi TV
• 其他兼容应用

配置导入步骤：

1. 打开 TVBox 应用
2. 进入「配置」或「设置」页面
3. 选择「导入配置」或「添加配置」
4. 输入上述配置地址
5. 等待导入完成

🔄 多设备数据同步

[](https://github.com/katelya77/KatelyaTV?tab=readme-ov-file#-%E5%A4%9A%E8%AE%BE%E5%A4%87%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5)

支持的数据：

• 观看历史记录
• 收藏夹内容
• 跳过片段设置
• 用户偏好配置

同步方式对比：

存储方式	同步范围	配置难度	免费程度
LocalStorage	单设备	无需配置	完全免费
Redis	全同步	需要服务器	自建免费
Upstash	全同步	简单配置	有免费额度
D1	全同步	中等难度	完全免费
Kvrocks	全同步	需要部署	自建免费

---

手动导入配置

1. 配置下载 ⬇️

   基础版 config_isadult.json

2. 配置方式：

   • Docker：挂载配置文件 -v ./config.json:/app/config.json:ro
   • Vercel：替换仓库中的 config.json 文件内容
   • 管理员界面：登录后台 /admin 导入配置

---

OpenWrt 中部署：

• 首先确定你的OpenWrt中有Docker组件，如果没有需要提前安装

• 使用方案二为例

  1: 启动 Redis ，数据存放在 /opt/docker/redis

  docker run -d \
    --name katelyatv-redis \
    --restart unless-stopped \
    -v /opt/docker/redis:/data \
    redis:7-alpine
  

  2: 启动 KatelyaTV

  docker run -d \
    --name katelyatv \
    --restart unless-stopped \
    -p 3000:3000 \
    -e USERNAME=admin \
    -e PASSWORD=10000 \
    -e NEXT_PUBLIC_STORAGE_TYPE=redis \
    -e REDIS_URL=redis://katelyatv-redis:6379 \
    -e NEXT_PUBLIC_ENABLE_REGISTER=true \
    ghcr.io/katelya77/katelyatv:main-3ce1bd1
  

结语

把 KatelyaTV 做成你的电视盒子后厨，关键在于：选择合适的存储/缓存方案以保证与 TVBox 的实时性和一致性；做好 HTTPS 与 CORS 配置；并根据访问量与维护能力在 Docker、本地数据库与 Serverless 间取舍。希望这篇文章能帮你在下一个视频中顺利演示「点一点 → TVBox 一键导入 → 全家都能看」的华丽场景。

如果你希望我出一篇「一步步从零到能被 TVBox 导入的视频教学」，或者想要我把上面某一种部署写成详细的 shell 脚本与 docker-compose 文件，留言告诉我你的云服务商和预算，我来为你量身定制！