文档

米视TV 开发文档

这个项目是什么

米视TV（仓库 jinghui/katelyatv）是一个开源自部署的影视聚合站：全网聚合搜片 + 51 个港澳台频道直播 + TVBOX/影视仓一键接入。它基于上游 KatelyaTV（MIT）深度增强——需要特别理解的是：本仓库不是 Next.js 应用源码仓库，而是"部署 + 补丁"仓库。上游应用以容器镜像形式运行，本仓库用 patches/ 目录对容器内编译产物打补丁并固化成本地镜像（当前为 katelyatv:fixed33），从而获得 TVBOX 聚合接口、直播、筛选页提速等自研能力。

技术栈与架构

仓库结构

顶层真实目录及职责：

路径 说明
docker-compose.redis.yml Redis 模式的 compose（应用 + Redis，restart: always，端口 3030:3000）
.env.example 环境变量模板（复制为 .env 后填真实值）
config.json 站点基础配置，只读挂载进容器 /app/config.json
patches/ 核心：对编译产物的补丁集（详见下文"补丁说明"），含 apply.sh 一键重放与 inject_live.py 直播注入脚本
public-live/ 直播页静态资产（hls.min.js / mpegts.min.js），挂载为容器 /app/public
conf/ 配置目录（.env 等敏感文件已 gitignore）
fix-admin-users.py 管理员账号修复脚本
RELEASING.md 发布流程清单（每次推送必做）
CHANGELOG.md 更新日志（版本号形如 v-fixed33）

补丁说明（本仓库的真正核心）

上游镜像 ghcr.io/katelya77/katelyatv:latest 直接使用存在若干问题，patches/ 逐一修复：

补丁文件 解决的问题
app-api-tvbox-route.js TVBOX 核心：顶级分类收敛为 7 类（香港电影/香港剧/电影/电视剧/综艺/动画片/动漫）、根分类聚合、全源聚合站点、年份/地区/排序/子分类筛选
app-api-filter-route.js 筛选页从 176 秒提速到约 1 秒（禁用失效源）、结果数翻倍、真实分页
routes-manifest.json 路径式 TVBOX 站点 API：/api/tvbox/<site>?ac=videolist 与 /live rewrite
filter-page-chunk.js 筛选页"加载更多"结果去重
live-inject.js + inject_live.py 港澳台直播全套：解码、反代、播放页、EPG、TVBOX 直播源

上游大版本升级后的重放流程：

bash patches/apply.sh                          # 重放补丁到运行中容器
python3 patches/inject_live.py                 # 重放直播注入（幂等可重跑）
docker commit katelyatv katelyatv:fixed33      # 固化新镜像
docker compose -f docker-compose.redis.yml up -d

配置项说明

.env.example 与 compose 中真实存在的配置键：

配置键 含义 默认值（compose 内）
USERNAME 管理员用户名 admin
PASSWORD 站点访问密码（登录必需） 空，需自行填写
AUTH_PASSWORD 认证密码 空
NEXT_PUBLIC_STORAGE_TYPE 存储类型 redis
REDIS_URL Redis 地址 redis://katelyatv-redis:6379
REDIS_PASSWORD Redis 密码 空
REDIS_DATABASE Redis 库号 0
NEXTAUTH_SECRET 会话签名密钥（必填随机串） 无
NEXTAUTH_URL 站点对外地址 http://localhost:3000
NEXT_PUBLIC_ENABLE_REGISTER 是否开放注册 true
SITE_NAME 站名（界面/标题/TVBOX 内置名全量生效） 米视TV
NEXT_PUBLIC_IMAGE_PROXY / NEXT_PUBLIC_DOUBAN_PROXY 豆瓣海报代理前缀 指向站内 /api/image-proxy?url=

另有 Redis 运行时配置 admin:config（通过 redis-cli -x set admin:config 写入），包含 ImageProxy 与 DoubanProxy 完整地址——首次启动后必须写入，否则海报全部裂图。

部署方式

git clone https://gitea.88531.cn/jinghui/katelyatv.git && cd katelyatv
docker pull gitea.88531.cn/jinghui/katelyatv:latest
docker tag   gitea.88531.cn/jinghui/katelyatv:latest katelyatv:fixed33
cp .env.example .env
vi .env        # 至少填 PASSWORD 与 NEXTAUTH_SECRET，可选 SITE_NAME
docker compose -f docker-compose.redis.yml up -d

应用对外端口为宿主 3030 → 容器 3000；Redis 数据通过命名卷 katelyatv-redis-data 持久化。首次启动后写入海报代理配置：

docker exec -i katelyatv-redis redis-cli -x set admin:config <<'JSON'
{"SiteConfig":{"ImageProxy":"http://你的服务器IP:3030/api/image-proxy?url=","DoubanProxy":"http://你的服务器IP:3030/api/image-proxy?url="}}
JSON
docker restart katelyatv

二次开发要点

相关链接