joeseesun/qiaomu-iptv
GitHub: joeseesun/qiaomu-iptv
一个基于 iptv-org 数据源、浏览器优先的 IPTV 在线直播指南，提供电视式换台体验和静态部署方案。
Stars: 12 | Forks: 3
# 乔木 IPTV
[](https://iptv.qiaomu.ai/)
[](https://github.com/joeseesun/qiaomu-iptv/actions)
[](LICENSE)
一个更像电视、更适合浏览器直接观看的 IPTV 在线直播指南。
它基于 [iptv-org](https://github.com/iptv-org/iptv) 的公开频道索引，把海量直播源整理成一个可以直接打开、搜索、换台、收藏、点赞、反馈线路的电视体验。乔木服务器只缓存频道索引和推荐信号，不代理、不转发、不托管任何第三方视频流。
## 为什么值得 fork
多数 IPTV 项目停在“给你一份 m3u 列表”。乔木 IPTV 更像一个可以长期运营的小型电视产品：
- 浏览器优先：默认筛选 HTTPS HLS、无需 Referer/User-Agent 的浏览器可播源。
- 电视式换台：播放器右侧是播放列表，点一下就换台，不让用户在表格里迷路。
- 中文和英文优先：精选推荐更适合中英文用户，其他频道通过搜索和筛选进入。
- 多源切换：同一个频道有多路源时，可以在播放器内切换线路。
- 收藏、点赞、无法播放反馈：可本地保存，也可通过同源日志聚合成热门推荐。
- 自动数据刷新：服务器可定时拉取 iptv-org API，生成静态 JSON 缓存。
- 纯静态前端：Vite + hls.js，部署到任意静态服务器、Nginx、Docker、Cloudflare Pages 都很轻。
- 站内悬浮播放器：滚动查看频道库时，播放器保持在最高层级继续可操作。
## 在线体验
Live demo: [https://iptv.qiaomu.ai](https://iptv.qiaomu.ai/)
浏览器不会允许页面自动播放视频。首次进入时，页面会引导你点击第一个推荐频道开始播放。
## 功能
| 模块 | 能力 |
| --- | --- |
| 播放器 | HLS 播放、线路切换、停止播放、原生画中画、站内悬浮播放 |
| 换台侧栏 | 我的收藏、大家收藏、高赞频道、热门播放、高清优先、中文常看、国际新闻、旅游/纪录片、电影、音乐 |
| 频道库 | 搜索频道/国家/分类、国家筛选、分类筛选、清晰度筛选、滚动自动加载 |
| 个性化 | 本地收藏、本地点赞、本地无法播放记录 |
| 推荐信号 | 可选同源事件日志，聚合播放、收藏、点赞、反馈，用于热门推荐 |
| 数据缓存 | 从 iptv-org API 拉取 streams/channels/countries/categories/logos，生成静态缓存 |
| 开源部署 | 静态部署、Docker、Nginx 日志事件接口、systemd 定时刷新模板 |
## 快速开始
git clone https://github.com/joeseesun/qiaomu-iptv.git
cd qiaomu-iptv
npm install
npm run dev
打开 Vite 输出的本地地址即可。
默认情况下，如果 `public/data/iptv-data.json` 不存在，前端会直接回退读取 iptv-org 的公开 API。想生成本地缓存：
npm run update:data
npm run dev
## 构建
npm run build
npm run preview
构建产物在 `dist/`。
## 可选配置
复制 `.env.example` 为 `.env.local`：
cp .env.example .env.local
可选 Umami 统计：
VITE_UMAMI_SRC=https://your-umami.example.com/script.js
VITE_UMAMI_WEBSITE_ID=your-website-id
留空则不加载任何第三方统计脚本。
## 数据刷新
生成频道缓存：
npm run update:data
默认输出到：
public/data/iptv-data.json
自定义输出路径：
QIAOMU_IPTV_DATA_OUT=/var/www/iptv/data/iptv-data.json npm run update:data
生成推荐信号：
QIAOMU_IPTV_EVENTS_LOG=/var/log/nginx/iptv-channel-events.log \
QIAOMU_IPTV_RECOMMENDATIONS_OUT=public/data/recommendations.json \
npm run update:recommendations
`public/data/*.json` 是生成缓存，默认不提交到 Git。这样 fork 后仓库保持轻量，部署环境也能按自己的频率刷新。
## 推荐信号如何工作
前端会向同源接口发送轻量事件：
/api/channel-event?type=play&channel=...&url_hash=...
Nginx 可以直接 `return 204`，同时把请求写进独立 access log。`scripts/update-recommendations.mjs` 再从日志里聚合：
- `favorite_add`: +10
- `like_add`: +7
- `play`: +2
- `unplayable`: -4
直播源地址不会原样上报，只会发送短 hash。你也可以完全不配置这个接口，网站仍然可以作为纯本地 IPTV 浏览器使用。
## 部署方式
### 静态部署
npm run build
rsync -az --delete dist/ user@server:/www/wwwroot/iptv.example.com/
### Docker
docker compose up -d --build
默认容器监听：
127.0.0.1:3138
### systemd 定时器
`deploy/systemd/` 里提供了两个模板：
- `qiaomu-iptv-data-refresh.timer`: 每周刷新 iptv-org 数据缓存。
- `qiaomu-iptv-recommendations-refresh.timer`: 每 15 分钟从事件日志聚合推荐信号。
按你的服务器路径调整 `Environment=` 和 `ExecStart=` 后启用即可。
## Nginx 事件接口示例
`nginx.conf` 里包含一个最小可用例子：
location = /api/channel-event {
access_log /var/log/nginx/iptv-channel-events.log combined;
add_header Cache-Control "no-store" always;
return 204;
}
这让你不用写后端，也能记录播放、收藏、点赞和无法播放反馈。
## 项目结构
.
├── src/
│ ├── main.js # 应用逻辑、播放器、筛选、推荐、事件
│ └── styles.css # Netflix 风格电视 UI
├── scripts/
│ ├── update-iptv-data.mjs # 拉取 iptv-org API 生成频道缓存
│ └── update-recommendations.mjs
├── deploy/systemd/ # 数据刷新和推荐刷新 timer 模板
├── public/assets/ # 关注/打赏二维码等公开静态资产
├── public/data/ # 生成数据缓存目录，不提交 JSON
├── nginx.conf # Docker/Nginx 示例配置
└── docker-compose.yml
## Fork 之后可以做什么
- 换成你自己的品牌、域名、二维码和 Umami 配置。
- 修改 `FEATURED_CHANNELS` 和 `PLAYLISTS`，做自己的精选电视台。
- 接入数据库，把收藏/点赞从本地存储升级为账号体系。
- 把频道可用性探测做成后台任务，只展示稳定可播源。
- 部署到 Cloudflare Pages、Vercel、Nginx 静态目录或 NAS。
## 隐私和边界
- 视频流由浏览器直连源站，本项目不代理、不缓存、不转发第三方视频内容。
- 收藏、点赞、无法播放反馈默认保存在浏览器本地。
- 如果你配置了 `/api/channel-event`，事件会发到同源服务器；默认实现只适合做聚合推荐，不应当用于采集个人身份信息。
- 直播源可用性取决于源站、地区、浏览器策略和网络环境，无法保证所有频道都能播放。
## 数据来源与授权
- 频道索引来自 [iptv-org/iptv](https://github.com/iptv-org/iptv) 和 [iptv-org/api](https://github.com/iptv-org/api)。`iptv-org/iptv` 当前 GitHub license 显示为 The Unlicense。
- 本仓库代码使用 [MIT License](LICENSE) 发布。
- 本项目不声明拥有任何频道、台标、节目或视频流内容。请在你所在地区的法律和内容授权边界内使用。
## 作者
由 [向阳乔木](https://qiaomu.ai/) 制作和维护。
- X: [@vista8](https://x.com/vista8)
- GitHub: [@joeseesun](https://github.com/joeseesun)
- Live demo: [iptv.qiaomu.ai](https://iptv.qiaomu.ai/)
如果这个项目帮你快速搭了一个自己的 IPTV 浏览站，欢迎 star、fork，或者提 issue 分享你想要的电视体验。
标签：hls.js, IPTV, MITM代理, Vite, 前端, 数据可视化, 自定义脚本, 视频播放器, 请求拦截, 静态站点