# BaoTvBox

**Repository Path**: ostaer/bao-tv-box

## Basic Information

- **Project Name**: BaoTvBox
- **Description**: 参考kodi，给飞牛写一个HDMI直通播放器，支持tvbox协议
- **Primary Language**: TypeScript
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BaoTvBox

BaoTvBox 是面向飞牛 fnOS 和 NAS 本机显示器的电视端影院应用。它提供自研 TV UI、浏览器控制台、手机遥控、TVBox/TVBox2 内容适配、统一播放策略和本地数据管理，并以 Docker + FPK 交付。

```text
TV UI / 浏览器控制台 / 手机遥控
            ↓
       Fastify 后端
            ↓
TVBox 单仓、多仓、直播、CMS、DRPY、Android Spider
            ↓
Chromium 页面播放器 → mpv / FFmpeg 兜底
            ↓
        SQLite 持久化
```

> BaoTvBox 不提供或维护影视内容。内置地址仅用于协议兼容测试，可能失效；请遵守所在地法律和内容服务条款。

## 主要功能

- 飞牛/NAS 本机显示器运行完整电视 UI，支持键盘、USB/红外遥控和 HDMI CEC。
- 电脑浏览器可配置、搜索、预览，并将内容投到本机显示器。
- 手机扫码进入遥控页面，支持方向键、确认、返回和中文搜索。
- 支持 TVBox/TVBox2 单仓、多仓、直播，以及 HTTP CMS、HTTP Spider、DRPY2 和可选 Android `csp_* + JAR`。
- 聚合搜索仅查询用户启用的源，按运行时分别限流并持续返回结果，前端断开后停止任务。
- 直播按频道聚合来源和线路；影视详情按“源 → 线路 → 剧集”展示。
- 播放页提供“选集｜线路｜换源”，切换线路尽量保持当前集数，上一集、下一集和自动连播不跨线路。
- 支持收藏、历史、进度、播放列表、片头片尾规则、网盘登录交互和源健康管理。
- 无显示器或电视断开时仍保留 Web 服务；显示器重新连接后自动恢复 Weston/Chromium。

## 安装

### 支持架构

正式镜像支持：

- `linux/amd64`：常见 Intel/AMD x86_64 飞牛设备。
- `linux/arm64`：使用标准 ARM64 用户态的飞牛设备。

SSH 中查看架构：

```bash
uname -m
docker info --format '{{.Architecture}}'
```

`x86_64` 对应 `amd64`，`aarch64` 对应 `arm64`。FPK 的 `platform=all` 只表示 fnOS 可以分发该包，不代表镜像支持其它 CPU 架构。

### 安装 FPK

1. 从 [Gitee Releases](https://gitee.com/ostaer/bao-tv-box/releases) 下载 `bao-tv-box_<version>_all.fpk`。
2. 在飞牛应用中心手动安装第三方应用。
3. 宿主机访问端口默认 `8088`；其余参数都可留空。
4. 安装后访问 `http://<飞牛地址>:8088/`，或从飞牛应用中心打开。

| 安装项 | 要求 | 默认行为 |
| --- | --- | --- |
| 宿主机访问端口 | 必填，已预填 `8088` | 只修改浏览器入口；容器内和本机显示器仍使用 8088 |
| 初始订阅地址 | 选填 | 留空写入内置单仓、多仓和直播示例 |
| Android Spider | 选填，默认关闭 | 仅 `csp_* + JAR` 需要，存在额外资源和安全风险 |
| 显示、声音、遥控、硬解 | 选填 | 留空按标准 DRM、ALSA、evdev 和 CEC 自动探测 |

本机显示器入口由容器内 Chromium 打开；其它电脑不能通过自己的 `127.0.0.1` 访问飞牛。

### 应用设置生效方式

普通订阅、播放偏好和界面设置在应用内保存后立即生效。以下变更需要重新创建容器：

- 安装后开启或关闭 Android Spider。
- 修改飞牛应用设置中的容器环境或硬件参数。
- 重复安装相同版本的测试包，而镜像仓库中的同版本镜像已经被覆盖更新。

进入“飞牛 Docker → 项目管理 → bao-tv-box”执行：

```text
停止 → 构建
```

构建完成后项目会自动启动，不需要再点“启动”。“构建”只是重新读取 Compose、拉取镜像并创建容器，不是在飞牛上编译。不要删除项目或应用数据。

### 更新检查

“设置 → 关于 → 版本更新”可查询 Gitee Release。自动检查默认关闭；开启后只显示新版本和下载入口，不会自动安装 FPK、重启应用或迁移数据。

## 硬件兼容

应用不安装或替换宿主机驱动，优先使用 Linux 标准接口：

| 能力 | 自动探测范围 |
| --- | --- |
| 显示 | `/dev/dri/card*`、DRM connector、EDID、`/dev/dri/renderD*` |
| 声音 | `/dev/snd`、ALSA、HDMI/DP ELD 和 `mpv --audio-device=help` |
| 输入 | `/dev/input/event*`、键盘、USB/红外遥控 |
| CEC | `/dev/cecN`，优先于普通 evdev 遥控 |
| TTY | 可用 `tty0/tty1`，仅本机 Kiosk 需要 |

自动模式只在检测到可信的 `connected` DRM 接口时启动 Weston/Chromium。电视稳定断开后停止显示子进程，Web 后端继续运行；接口恢复后再启动。用户手动指定输出接口时会强制尝试该接口。

NVIDIA 专有 `/dev/nvidia*`、ARM 厂商私有 Mali/RGA/MPP/amstream 节点、摄像头、采集卡和原始 USB HID 不会默认开放。硬件节点存在也不代表驱动、用户态库或解码能力一定可用。

目前真机型号覆盖有限。未验证设备建议依次检查：应用安装、Web 页面、诊断页、显示、声音、遥控和硬解，并在反馈时附上架构和脱敏日志。

## 容器职责

普通安装运行三个容器；开启 Android Spider 后运行第四个。

| 容器 | 职责 | 驻留方式 |
| --- | --- | --- |
| `bao-tv-box` | Fastify、React 静态页、SQLite、订阅聚合、播放器、Weston/Chromium/mpv | 常驻 |
| `bao-tv-box-drpy` | 执行 DRPY2 JavaScript 规则 | 常驻，空闲等待 |
| `bao-tv-box-drpy-egress` | DRPY 和 Android 的受控 HTTP/HTTPS 出口 | 常驻，空闲等待 |
| `bao-tv-box-android-spider` | ReDroid、CatVod JAR、Android 登录与本地代理中继 | 默认关闭；开启后常驻 |

主容器可以访问用户配置的内网 OmniBox、CMS 和媒体地址。DRPY/Android 的第三方代码经受控出口访问公网，并拒绝回环、局域网、元数据和其它保留地址。

## Android Spider

Android Spider 只用于 TVBox 的 `csp_* + JAR`。普通 CMS、DRPY 和直播不需要开启。

### 资源开销

| 架构 | 镜像下载 | 解压后磁盘 |
| --- | --- | --- |
| x86_64 / amd64 | 约 0.9 GB | 约 2.2 GB |
| arm64 / aarch64 | 约 0.6 GB | 约 1.5 GB |

两种架构均建议至少预留 1.5 GB 可用内存。x86_64 使用第三方 Houdini 兼容层运行常见 ARM64 Spider 原生库；固定摘要只能避免镜像漂移，不能证明供应链安全。

### 风险边界

- 远程 JAR、`ext` 和后续更新由第三方提供者控制，可以执行代码并联网。
- ReDroid 必须使用特权模式；即使不映射主数据目录，也可能影响飞牛主机。
- 网络隔离、固定摘要和 MD5 只能降低部分风险，不能证明代码安全。
- Android 侧禁止直接访问内网；依赖局域网接口、QUIC、UDP 或自定义 Socket 的 JAR 可能不可用。
- 不保证所有历史 JAR、CPU ABI、宿主类和已失效接口都兼容。

登录 Cookie、WebView 数据和第三方应用文件保存在独立 Docker 卷中，正常重启、项目重构建和镜像升级不会主动清除。卸载时删除数据或手动删除卷会丢失登录状态。

## 订阅与 TVBox 兼容

BaoTvBox 把 TVBox 和 TVBox2 视为同类配置协议。兼容表示可以读取配置并通过对应运行时浏览、搜索和播放，不代表复刻 Android TVBox 的全部插件、账号系统或界面。

### 可添加的订阅

| 类型 | 接受内容 | 说明 |
| --- | --- | --- |
| 单仓 | HTTP/HTTPS TVBox JSON、常见影视仓 Base64 封装 | 读取 `sites` 和根级 `lives`；不执行 HTML/JS 落地页 |
| 多仓 | JSON 数组，或 `urls/storeHouse/warehouses/subscriptions` 目录 | 最多展开 100 个子仓，保留未变 URL 的启停和健康状态 |
| 直播 | TVBox TXT、扩展 M3U | 支持 HTTP(S)、RTMP(S)、RTSP、SRT、UDP 和 RTP |

配置使用 JSON5 数据解析，兼容注释、单引号、尾逗号及部分非法换行，但不会执行 JavaScript 表达式。

### 点播源执行方式

| TVBox 声明 | 运行方式 | 主要能力 |
| --- | --- | --- |
| `type=0/1/2` + HTTP(S) `api` | 主容器 CMS | 分类、筛选、分页、搜索、详情、选集、播放；兼容旧 XML CMS |
| `type=4` + HTTP(S) `api` | 主容器 HTTP/T4 | 分类、搜索、详情、播放和 action |
| `type=3` + `drpy2*.js` | DRPY2 容器 | home、category、search、detail、play、proxy 和可选 action |
| `type=3` + `csp_*` | Android Spider | CatVod 首页、分类、搜索、详情、播放、直播、proxy 和 action |
| 未知或缺少运行描述 | 标记不支持 | 不执行未知脚本、JAR 或网页代码 |

播放响应兼容常见 `url/playUrl/play_url`、`parse`、header、字幕、弹幕、DRM、格式和续播字段。HLS、MP4、FLV 等直链优先直接播放；无扩展名地址先探测媒体响应，HTML 或间接地址再进入解析器或 `yt-dlp`。

`searchable=0` 会关闭普通搜索；`quickSearch=0` 只退出跨源快搜。测试失败的源保留配置但暂停参与聚合，重新测试或同步成功后自动恢复。

### 当前边界

- 支持常见 `sites`、`lives`、`spider`、`flags`、受限 `parses` 和 `Vod.action`。
- 根级 `hosts/proxy/doh/headers/ads/rules` 只检测，不接管主容器网络和全局请求。
- 不支持任意 TVBox 插件 UI、未知本地二进制、未知 JavaScript 引擎和未声明执行协议。
- Android Spider 兼容性以具体 JAR、架构和真机结果为准。
- 网盘登录入口不等于已实现对应网盘的转存和直链；最终取决于具体 JAR 能否返回可播放地址。

## 内置示例

新数据库首次启动写入以下第三方测试地址：

| 名称 | 类型 | 地址 |
| --- | --- | --- |
| 盒子迷 · 单仓 | 单仓 | `https://盒子迷.top/禁止贩卖` |
| Noimank · 多仓 | 多仓 | `https://gh-proxy.com/https://raw.githubusercontent.com/noimank/tvbox/master/tvboxmuti.json` |
| FongMI 线路 | 多仓子项 | `https://gh-proxy.com/raw.githubusercontent.com//gaotianliuyun/gao/master/0827.json` |
| 高天流云 JS | 多仓子项 | `https://gh-proxy.com/raw.githubusercontent.com/gaotianliuyun/gao/master/js.json` |
| 盒子迷 · 直播 | 直播 | `https://盒子迷.top/ZB` |

这些地址不由 BaoTvBox 维护，可能调整、限流或失效。用户主动清空订阅后，应用重启不会再次写入。

添加、保存或测试订阅时会识别单仓、多仓、直播，以及 CMS、DRPY 和 Android Spider 数量。只有检测到可解析的 `csp_* + JAR` 时才展示 Spider 开启方法和风险提示。

## 页面与播放

- **影视**：首页分类、来源筛选、搜索、详情、收藏、历史和播放列表。
- **详情**：先选择可播放版本（内容源），再选择线路，最后选择剧集。
- **播放**：控制栏提供选集、线路和换源；切换线路保持当前集数，当前线路失效时再切换。
- **直播**：聚合相同频道的来源和线路，保留 EPG 元数据，三栏区域使用剩余屏幕高度。
- **设置**：订阅、内容源、源工具、首页分类、播放、显示、声音、遥控、诊断和更新。
- **网盘登录**：二维码、凭证和 Android 交互统一使用弹窗；每两秒只更新弹窗状态，不刷新页面。

浏览器播放器优先使用 HLS/MSE 或代理直通；不兼容时由 FFmpeg 转码。用户选择本机 `mpv` 或页面策略无法处理时，才由 `mpv` 接管。

## 数据、缓存与备份

主数据目录：

```text
/var/apps/bao-tv-box/shares/bao-tv-box/data
```

| 路径 | 内容 |
| --- | --- |
| `/data/baotvbox.sqlite` | 订阅、源状态、分类、收藏、历史、进度、播放列表和片头片尾 |
| `/data/runtime-settings.env` | 显示、声音、硬解、窗口和遥控设置 |
| `/data/ime-dicts/baotvbox_candidates.json` | 片名建议索引 |
| `/data/live-streams` | 直播转码临时 HLS，播放结束后清理 |

迁移或备份前先停止应用，再备份整个数据目录。

单仓配置默认缓存 5 分钟；分类和媒体列表有 24 小时内存缓存。首次访问、上游慢、缓存失效或新源预热时可能加载较久。诊断页“清理缓存”不会删除 SQLite 数据。

## 日志与排障

统一日志：

```text
/var/log/apps/bao-tv-box.log
```

常用前缀：

| 前缀 | 内容 |
| --- | --- |
| `[lifecycle:*]` | 安装、升级、配置、硬件探测和健康检查 |
| `[container:main]` | Web、SQLite、播放解析、mpv、FFmpeg 和本机显示 |
| `[container:drpy]` | DRPY2 运行服务 |
| `[container:egress]` | 受控出口代理 |
| `[container:android]` | Android Spider、JAR、登录、代理和 watchdog |
| `[baotvbox-display]` | 显示器连接状态和 Kiosk 启停 |
| `[baotvbox-kiosk]` | Weston、Chromium 的启动、停止和异常 |

SSH 查看：

```bash
sudo tail -n 300 /var/log/apps/bao-tv-box.log
sudo grep -Ei 'failed|error|异常|失败|oom|killed' /var/log/apps/bao-tv-box.log | tail -n 200
sudo docker ps -a --filter 'name=bao-tv-box'
sudo docker logs --tail 200 bao-tv-box
```

快速判断：

1. 没有 `[lifecycle:install]`：优先查看 FPK 校验和飞牛安装日志。
2. 有生命周期开始但没有完成：查看失败命令、行号和 `[lifecycle:hardware]`。
3. 生命周期完成但没有 `[container:*]`：检查镜像拉取、Compose、挂载和 Docker 系统日志。
4. Web 正常但电视无画面：检查 DRM connector、手动输出接口和 `[baotvbox-display]`。
5. 有画面无声音：在应用设置选择 ALSA HDMI/DP 设备并播放测试音。
6. `csp_*` 不可用：确认 Spider 已开启，并执行过“停止 → 构建”，再看 Android 容器健康状态。

正常 `/api/health` 成功检查和空遥控轮询不会持续刷日志。为真机排障，日志可能记录搜索词、频道、内容源和播放地址；分享前请检查其中的短期签名和隐私信息。

## 本地开发

要求 Node.js 22 和 Docker：

```bash
npm ci
```

分别启动后端和前端：

```bash
npm run dev:server
npm run dev
```

- 开发页面：`http://127.0.0.1:5173/?surface=console`
- API：`http://127.0.0.1:8088`

完整验证：

```bash
npm run verify
```

该命令依次执行 ESLint、Prettier 检查、Vitest 和生产构建。

## 版本、镜像和 FPK

主应用唯一版本源是 `package.json`：

```bash
npm version patch --no-git-tag-version
```

`package-lock.json` 会同步更新；前端、镜像 tag、OCI label、FPK 文件名、`BUILD_INFO` 和 Release tag 均复用该版本。`manifest.template` 只保留 `__PACKAGE_VERSION__`，打包时生成真实 manifest。

Android Spider 使用独立版本源 `android-spider-bridge/VERSION`，只有桥接 APK、兼容接口或 ReDroid 运行时改变时才升级。

只生成 FPK，不重建镜像：

```bash
npm run package:fpk
```

构建并推送主应用和 Spider 双架构镜像，再生成 FPK：

```bash
npm run package:fpk:push
```

只有主应用代码变化时可跳过 Spider：

```bash
BUILD_ANDROID_IMAGE=0 npm run package:fpk:push
```

默认镜像：

- `ccr.ccs.tencentyun.com/baotvbox/bao-tv-box:<version>`
- `ccr.ccs.tencentyun.com/baotvbox/bao-tv-box-android-spider:<spider-version>`

FPK 固定版本 tag，不使用 `latest`。同版本覆盖推送镜像后，飞牛可能保留旧缓存，需要在 Docker 项目执行“停止 → 构建”。

## 反馈

设备兼容性仍需要更多真机验证。安装、显示、声音、遥控、硬解、源解析或播放出现问题时，请附上：

- BaoTvBox 版本和设备架构。
- 飞牛型号、显示接口和连接方式。
- 问题发生步骤、源类型和错误提示。
- 脱敏后的 `/var/log/apps/bao-tv-box.log`。

不要公开 Cookie、Token、账号凭证或带长期签名的播放地址。