一、项目简介

TVHelper 是一个由 wukongdaily/tvhelper 提供的 Docker 化 Android TV 盒子管理工具。

它可以让你通过浏览器或 SSH，在电脑、NAS、服务器上远程管理电视盒子，实现：

📺 “用网页管理你的电视盒子 + ADB远程安装应用”

---

✨ 核心功能

该项目主要能力包括：

• 📱 通过 ADB 连接 Android TV / 盒子
• 📦 批量安装 APK / XAPK 应用
• 🌐 Web 页面管理盒子
• 🧰 一键安装常用流媒体应用（Netflix / YouTube 等）
• ⚙️ 修改系统设置（如 NTP 时间服务器）
• 🖥 支持 SSH 进入容器操作
• 🐳 Docker 一键部署

---

二、项目架构说明

TVHelper 本质是一个容器化 ADB 管理环境：

浏览器 Web UI
      ↓
Docker 容器（TVHelper）
      ↓
ADB 工具 + Shell脚本
      ↓
连接 Android TV / 电视盒子

---

三、环境要求

在安装之前，请确认你的环境：

• Docker 已安装
• Docker Compose（推荐）
• Linux / Windows / NAS / macOS
• 网络可访问局域网电视盒子
• 端口默认开放：
  • 2288（Web界面）
  • 2299（SSH）
  • 15000（文件上传）

---

四、Docker 一键安装（推荐方式）

1. 拉取镜像

docker pull wukongdaily/box:latest

---

2. 运行容器

docker run -d \
  --name tvhelper \
  -p 2288:2288 \
  -p 2299:2299 \
  -p 15000:15000 \
  -v tvhelper_data:/data \
  wukongdaily/box:latest

---

3. 访问 Web 页面

打开浏览器：

http://localhost:2288

如果是服务器部署：

http://你的IP:2288

---

五、Docker Compose（推荐生产部署）

创建 docker-compose.yml：

version: "3.8"

services:
  tvhelper:
    image: wukongdaily/box:latest
    container_name: tvhelper
    ports:
      - "2288:2288"
      - "2299:2299"
      - "15000:15000"
    volumes:
      - tvhelper_data:/data
    restart: unless-stopped

volumes:
  tvhelper_data:

启动：

docker compose up -d

---

六、如何连接电视盒子（ADB）

1. 打开盒子开发者模式

在电视盒子中：

• 设置 → 关于设备 → 连续点击版本号
• 打开 USB 调试 / 网络调试（ADB）

---

2. 获取盒子 IP

例如：

192.168.1.50

---

3. 在 TVHelper 中连接

进入 Web 界面：

http://IP:2288

然后执行：

adb connect 192.168.1.50:5555

---

七、常用功能使用说明

1. 安装应用（APK）

上传 APK 后执行：

• 自动安装
• 或批量安装目录 APK

---

2. 一键安装流媒体应用

内置脚本支持：

• YouTube
• Netflix
• Disney+
• Apple TV+
• HBO

---

3. 修改电视系统时间（NTP）

用于解决：

• 时间不同步
• 证书错误
• 应用无法登录

---

八、SSH 进入容器

默认信息：

host: 你的IP
port: 2299
user: root
password: password

进入：

ssh root@IP -p 2299

---

九、文件上传目录

上传 APK 文件到：

/data

容器会自动识别并支持安装。

---

十、常见问题（FAQ）

Q1：网页打不开？

检查：

• Docker 是否启动
• 端口是否被占用
• 防火墙是否拦截

---

Q2：ADB 连接失败？

可能原因：

• 盒子未开启开发者模式
• IP 不在同一局域网
• 5555 端口未开启

---

Q3：安装 APK 失败？

检查：

• APK 是否损坏
• 盒子存储空间是否足够
• ADB 是否已连接成功

---

十一、适用场景

TVHelper 适合：

• 智能电视用户
• NAS 用户
• 家庭影音系统
• 盒子批量管理
• 流媒体应用部署

---

十二、总结

TVHelper 的核心价值是：

🔥 把“复杂的电视盒子ADB操作”变成“网页一键操作”

通过 Docker，你可以在任何设备上：

• 管理电视盒子
• 安装应用
• 远程调试
• 批量维护设备