WarHutTV

自托管影视聚合播放器 · 跨源搜索 · 在线点播

---

📖 项目简介

WarHutTV 是一个自托管的媒体聚合播放器，从多个第三方视频源聚合影视内容，提供统一的搜索、浏览和播放体验。

• 搜索即所得 — 同时搜索多个资源站，SSE 流式实时返回结果
• 聚合去重 — 按标题和年份自动合并不同来源的同一影片
• 智能优选 — 自动测速所有可播放源，选择最流畅的线路
• 沉浸观看 — 基于 HLS.js + Artplayer，支持倍速、画中画、广告过滤
• 全端覆盖 — PWA 支持，移动端底部导航 + 桌面端侧边栏

---

✨ 功能特性

🔍 跨源聚合搜索

• SSE 流式搜索，同时查询所有已配置的资源站
• 实时进度展示，每个源返回结果即显示
• 搜索结果按标题和年份智能聚合去重

▶️ 在线播放

• Artplayer 播放器，支持 HLS（.m3u8）流媒体
• 多播放线路切换 + 自动测速优选
• 倍速播放、画中画、进度拖拽
• 广告拦截（内置规则过滤）

🎬 影视发现

• 豆瓣热门推荐：电影、电视剧、综艺、动漫分类浏览
• Bangumi 番组日历：每日放送列表，星期筛选

🎨 多主题系统

6 套深色视觉主题，每套包含独特的纹理、光晕动画和卡片风格：

📦 本地存储（IndexedDB）

🔧 其他

• PWA 支持 — Service Worker 离线缓存，可添加到桌面
• 密码保护 — JWT 认证，保护非公开 API
• 速率限制 — 基于 IP 的请求频率控制
• 响应式布局 — 桌面端侧边栏、移动端底部导航栏
• 快捷部署 — Docker 一键启动，支持 Docker Compose

---

🏗️ 技术架构

┌──────────────────────────────────────────────────┐
│                   前端 (React + Vite)             │
│  ┌────────┐ ┌──────────┐ ┌───────────────────┐   │
│  │ 页面层  │ │  组件层   │ │  状态层            │   │
│  │ 10 页   │ │ Layout   │ │ AuthContext       │   │
│  │ 路由    │ │ Player   │ │ ConfigContext     │   │
│  │ 鉴权    │ │ VideoCard│ │ IndexedDB(Dexie)  │   │
│  └────┬───┘ └────┬─────┘ └────────┬──────────┘   │
│       └──────────┼────────────────┘              │
│                  ▼                                │
│          ┌──────────────┐                        │
│          │  API 客户端   │  Axios + SSE          │
│          └──────┬───────┘                        │
└─────────────────┼────────────────────────────────┘
                  │  /api/*
┌─────────────────┼────────────────────────────────┐
│                 ▼                                 │
│         后端 (Go + Gin)                            │
│  ┌────────┐ ┌──────────┐ ┌────────────────────┐  │
│  │ 中间件  │ │ 处理器    │ │  服务层             │  │
│  │ CORS   │ │ search   │ │  代理转发           │  │
│  │ JWT    │ │ detail   │ │  文件缓存           │  │
│  │ 限流   │ │ play     │ │                    │  │
│  │        │ │ douban   │ │                    │  │
│  │        │ │ bangumi  │ │                    │  │
│  └────────┘ └──────────┘ └────────────────────┘  │
│                                                   │
│  ┌──────────────┐  ┌─────────────────────┐        │
│  │ 配置层 env   │  │ 第三方视频源 API    │        │
│  │ + config.json│  │ 豆瓣 / Bangumi     │        │
│  └──────────────┘  └─────────────────────┘        │
└───────────────────────────────────────────────────┘

数据流

用户搜索 → 前端 SSE → 后端并发请求各视频源 → 标准化返回
              ↓
        前端聚合去重 → 展示结果
              ↓
        用户点击 → 获取详情 → 解析播放地址
              ↓
        多源测速优选 → 播放

---

🚀 快速开始

环境要求

• Go 1.26（与 backend/go.mod、CI、Dockerfile 保持一致）
• Node.js 20+ & pnpm 10+（仅开发需要）

开发模式

# 克隆项目
git clone https://github.com/OuOumm/WarHutTV.git
cd WarHutTV

# 1. 配置密码
# 创建或编辑 data/config.json，至少设置 password
# 详见下方配置章节

# 2. 启动后端（默认 :3000）
cd backend && go run .

# 3. 新终端，启动前端（Vite dev server :5173）
cd frontend && pnpm install && pnpm run dev

浏览器打开 http://localhost:5173，输入配置的密码即可登录。

生产构建

make build    # 构建前端 + 后端，输出到 bin/
make run      # 直接运行（需先构建）

跨平台构建：

# Linux / macOS
chmod +x build.sh && ./build.sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File build.ps1

构建产物：

bin/
├── warhutv-linux-amd64
├── warhutv-linux-arm64
├── warhutv-windows-amd64.exe
├── warhutv-darwin-amd64
└── warhutv-darwin-arm64

---

🐳 Docker 部署

使用预构建镜像

docker pull ghcr.io/OuOumm/warhutv:latest
docker run -d \
  --name warhutv \
  -p 3000:3000 \
  -e PASSWORD=your_password \
  -e JWT_SECRET=your_secret \
  -v ./data:/root/data \
  ghcr.io/OuOumm/warhutv:latest

本地构建运行

docker build -t warhutv .
docker run -d --name warhutv -p 3000:3000 -e PASSWORD=your_password warhutv

Docker Compose

services:
  warhutv:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PASSWORD=your_password
      - JWT_SECRET=your_secret
    volumes:
      - ./data:/root/data
    restart: unless-stopped

---

⚙️ 配置

配置优先级

环境变量 > data/config.json

环境变量

⚠️ 生产环境请务必设置 PASSWORD 和 JWT_SECRET，并使用强随机字符串。

data/config.json

{
  "site_name": "WarHutTV",
  "announcement": "欢迎使用 WarHutTV",
  "password": "your_password",
  "jwt_secret": "your_secret",
  "api_site": {
    "source_1": {
      "api": "http://example.com/api.php/provide/vod",
      "name": "资源站 1"
    },
    "source_2": {
      "api": "http://example2.com/api.php/provide/vod",
      "name": "资源站 2"
    }
  }
}

---

🛠️ 开发指南

项目结构

WarHutTV/
├── backend/                  # Go 后端
│   ├── main.go               # 入口 + 路由注册
│   ├── config/               # 配置加载（环境变量 + JSON）
│   ├── handlers/             # HTTP 处理器
│   │   ├── auth.go           #   登录认证
│   │   ├── search.go         #   跨源搜索（SSE）
│   │   ├── detail.go         #   视频详情
│   │   ├── play.go           #   播放地址解析
│   │   ├── proxy.go          #   代理转发
│   │   ├── douban.go         #   豆瓣分类/推荐
│   │   ├── bangumi.go        #   Bangumi 番组日历
│   │   ├── config.go         #   站点配置
│   │   └── version.go        #   版本信息
│   ├── middleware/            # Gin 中间件
│   │   ├── auth.go           #   JWT 认证
│   │   ├── cors.go           #   跨域
│   │   └── ratelimit.go      #   速率限制
│   ├── services/              # 业务逻辑层
│   │   ├── proxy.go          #   代理请求转发
│   │   └── cache.go          #   文件缓存
│   └── utils/                 # 工具
│       └── jwt.go            #   JWT 令牌
│
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── api/              # API 客户端
│   │   │   ├── client.ts     #   Axios 实例 + 拦截器
│   │   │   ├── auth.ts       #   登录登出
│   │   │   ├── config.ts     #   站点配置
│   │   │   ├── douban.ts     #   豆瓣
│   │   │   └── bangumi.ts    #   Bangumi
│   │   ├── components/        # 可复用组件
│   │   ├── pages/             # 页面组件（9 页）
│   │   ├── store/             # 状态管理
│   │   │   ├── auth.tsx      #   AuthContext
│   │   │   ├── config.tsx    #   ConfigContext
│   │   │   ├── theme.ts      #   6 套主题定义
│   │   │   ├── db.ts         #   Dexie.js 数据库
│   │   │   ├── favorites.ts  #   收藏 CRUD
│   │   │   ├── history.ts    #   历史 CRUD
│   │   │   ├── apiCache.ts   #   API 缓存
│   │   │   └── detailCache.ts#   详情缓存
│   │   ├── hooks/             # 自定义 Hooks
│   │   ├── utils/             # 工具函数
│   │   │   ├── filter.ts     #   搜索结果聚合
│   │   │   ├── speedtest.ts  #   播放源测速
│   │   │   ├── adblock.ts    #   广告过滤规则
│   │   │   └── image.ts      #   图片代理
│   │   └── types/             # TypeScript 类型
│   ├── public/                # PWA 资源（sw.js、图标）
│   └── ...config files
│
├── data/
│   └── config.json            # 运行时配置
├── bin/                        # 编译产物
├── docs/                       # 设计/评审文档
├── .github/workflows/          # CI/CD
├── Dockerfile                  # 开发镜像
├── Dockerfile.release          # 多阶段发布镜像
├── Makefile
├── build.sh / build.ps1
└── version                     # 版本文件

常用命令

make dev              # 启动前端开发服务器
make build            # 完整构建（前端 + 后端）
make run              # 运行后端
make clean            # 清理产物
make docker           # 构建 Docker 镜像

添加新页面 / API

• 新页面：在 frontend/src/pages/ 创建组件 → 在 App.tsx 注册路由
• 新后端 API：在 backend/handlers/ 添加 handler → main.go 注册路由 → frontend/src/api/ 添加客户端
• 新主题：在 frontend/src/store/theme.ts 中添加主题定义
• 新视频源：在 data/config.json 的 api_site 中添加

---

📦 GitHub Actions CI/CD

发布新版本

# 更新版本号
echo "1.1.0" > version

# 打标签推送
git add version && git commit -m "chore: bump version to 1.1.0"
git tag v1.1.0
git push origin v1.1.0

自动生成：

• 5 个平台二进制（.tar.gz / .zip）
• Docker 镜像 ghcr.io/OuOumm/warhutv:latest + :v1.1.0
• Release Notes 自动生成

---

❓ 常见问题

登录密码是什么？

首次使用需要在 data/config.json 中设置 password 字段，或者通过环境变量 PASSWORD 设置。默认无密码，请务必设置。

如何添加视频源？

编辑 data/config.json 的 api_site 字段，添加资源站的 API 地址。格式要求兼容通用资源站 API（/api.php/provide/vod 接口）。

支持哪些播放格式？

主要支持 .m3u8（HLS）流媒体格式。通过后端代理转发，绕过跨域限制。

移动端体验如何？

支持 PWA 添加到桌面，移动端采用底部导航栏布局，适配小屏操作。

如何切换主题？

页面左下角主题切换按钮，提供 6 套预置深色主题可选。设置保存在浏览器 localStorage 中。

---

📸 截图预览

🖥️ 桌面端

📱 移动端

---

🙏 致谢

• LunaTV — 项目灵感来源
• Artplayer — 播放器
• hls.js — HLS 流播放
• Dexie.js — IndexedDB 优雅封装
• React + Tailwind CSS — 前端框架
• Gin — Go HTTP 框架
• Vite — 构建工具

---

📄 License

CC BY-NC-SA 4.0 — 非商业使用，二改必须开源

• NonCommercial — 不得以商业盈利为目的使用
• ShareAlike — 任何修改、衍生作品必须以相同许可证发布
• Attribution — 必须保留原作者署名