DESKTOP-77LRNCU\dsx2016
caece7537a
更新频道 2 的 YouTube 密钥与抖音源站列表；完善网络诊断、IP 画像与功能开关文档。 Co-authored-by: Cursor <cursoragent@cursor.com>
599 lines
27 KiB
Markdown
599 lines
27 KiB
Markdown
# 无人直播助手
|
||
|
||
Windows 桌面端 **抖音 → YouTube 无人转播** 控制台：内置 Electron 客户端、FastAPI 控制面（`web2`）、FFmpeg 推流 worker、多频道 Pro、推流诊断。
|
||
|
||
[](https://www.python.org/)
|
||
[](https://www.electronjs.org/)
|
||
[]()
|
||
|
||
> 录制核心基于 [DouyinLiveRecorder](https://github.com/ihmily/DouyinLiveRecorder) 生态；Linux 全功能服务端可参考同级项目 **sh2**（`d2ypp2`）。本仓库侧重 **Windows 懒人包 + Electron 控制台**。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [快速开始](#快速开始)
|
||
- [产品定位](#产品定位)
|
||
- [系统架构](#系统架构)
|
||
- [仓库结构](#仓库结构)
|
||
- [界面与功能](#界面与功能)
|
||
- [网络诊断与 IP 画像](#网络诊断与-ip-画像)
|
||
- [功能开关](#功能开关)
|
||
- [web2 API](#web2-api)
|
||
- [配置与数据路径](#配置与数据路径)
|
||
- [单频道与多频道 Pro](#单频道与多频道-pro)
|
||
- [网络诊断 / IP 画像 / 代理](#网络诊断--ip-画像--代理)
|
||
- [推流诊断 / 质量守卫 / 转播历史](#推流诊断--质量守卫--转播历史)
|
||
- [youLIVE 目标端监控](#youlive-目标端监控)
|
||
- [摄像头直推](#摄像头直推)
|
||
- [外部拉流转推](#外部拉流转推)
|
||
- [会员登录门禁（可选）](#会员登录门禁可选)
|
||
- [开发与构建](#开发与构建)
|
||
- [打包发布](#打包发布)
|
||
- [环境变量](#环境变量)
|
||
- [故障排查](#故障排查)
|
||
- [相关文档](#相关文档)
|
||
- [许可证](#许可证)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 最终用户（便携包）
|
||
|
||
1. 运行发布包中的 **无人直播助手** 可执行文件。
|
||
2. 打开 **直播** 页，在界面中填写：
|
||
- YouTube **串流密钥**（Studio → 直播 → 串流设置）；
|
||
- **源站地址**（抖音直播间 URL，每行一个）。
|
||
3. 点击 **开始直播**；在 **当前直播日志** 中查看业务状态与 FFmpeg 输出。
|
||
|
||
### 开发者
|
||
|
||
```bash
|
||
cd electron
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
首次开发若缺少离线 Python/FFmpeg，可在 `electron/` 下执行 `pnpm prepare:runtime`。
|
||
|
||
仅调试后端 API（仓库根目录）：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
uvicorn web2:app --host 127.0.0.1 --port 8001 --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 产品定位
|
||
|
||
| 场景 | 说明 |
|
||
|------|------|
|
||
| **无人转播** | 从抖音等源站拉流，经本机 FFmpeg 推送到 YouTube RTMPS。 |
|
||
| **值守运行** | 通过内置 `BuiltinSupervisor`（或可选 PM2）管理 `youtube2.py`、`douyin_youtube_ffplay.py` 等 worker。 |
|
||
| **桌面控制台** | Electron 提供直播、网络、系统等页面。 |
|
||
| **多路 Pro** | 多组「一个抖音直播间 ↔ 一个 YouTube 串流密钥」并行，进程名 `youtube2__{channelId}`。 |
|
||
|
||
**配对原则（强制）**
|
||
|
||
- 一个抖音直播间地址只对应 **一个** YouTube 串流密钥；
|
||
- **禁止** 同一抖音向多个 YouTube 推流；
|
||
- **禁止** 多个抖音共用同一密钥。
|
||
|
||
---
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Electron 渲染进程 (React + Vite) │
|
||
│ 直播 / 摄像头 / 拉流 / 网络 / 系统 │
|
||
└───────────────────────────┬─────────────────────────────────────┘
|
||
│ preload (contextBridge)
|
||
┌───────────────────────────▼─────────────────────────────────────┐
|
||
│ Electron 主进程 │
|
||
│ · 启动 uvicorn (web2:app) │
|
||
│ · sql.js → client-data.sqlite │
|
||
│ · 托盘、深链 --nav= │
|
||
│ · YouTube Studio 系统浏览器侧车 │
|
||
│ · youLIVE 服务（监听 / 弹幕 / 桌面通知 / 本地 SQLite） │
|
||
└───────────────────────────┬─────────────────────────────────────┘
|
||
│ http://127.0.0.1:8001（可 0.0.0.0）
|
||
┌───────────────────────────▼─────────────────────────────────────┐
|
||
│ web2.py (FastAPI) │
|
||
│ 进程启停 / 状态诊断 / 配置读写 / Pro / 质量守卫 / 会话历史 │
|
||
└───────────────────────────┬─────────────────────────────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
▼ ▼ ▼
|
||
youtube2.py douyin_youtube_ffplay.py camera_youtube.py
|
||
│ │ │
|
||
│ pull_stream_youtube.py │
|
||
└──────── FFmpeg + Supervisor / PM2 ────────────────┘
|
||
```
|
||
|
||
| 模块 | 文件 | 职责 |
|
||
|------|------|------|
|
||
| Worker | `youtube2.py`, `douyin_youtube_ffplay.py`, `main.py` | 拉流、转码、推流 |
|
||
| 控制面 | `web2.py` | HTTP API |
|
||
| 运行时诊断 | `web2_process_runtime.py` | `business_status`、FFmpeg 速度/帧数 |
|
||
| 质量守卫 | `web2_quality_guard.py` | 推流质量评分 |
|
||
| 网络测速 | `web2_network.py` | 境内外可达性、上下行测速、分流判断 |
|
||
| IP 画像 | `web2_ip_profile.py` | 出口 IP 类型（住宅/机房/代理）、洁净度评分 |
|
||
| IP 质量 | `web2_ip_quality.py` | 代理/VPN/机房风险、流媒体解锁探测 |
|
||
| 功能开关 | `web2_feature_flags.py` | 摄像头/拉流 API 与 worker 显隐 |
|
||
| 转播历史 | `web2_relay_log.py` | 会话 SQLite、日志导入 |
|
||
| 配置治理 | `web2_config_governance.py` | 保存前备份、恢复 |
|
||
| 多频道 | `web2_relay_pro.py` | `youtube_channels.json`、`config/relay_pro/` |
|
||
| 摄像头 | `web2_camera.py`, `camera_youtube.py` | DirectShow 采集、NVENC 推流 |
|
||
| 拉流 | `web2_pull_stream.py`, `pull_stream_youtube.py` | RTMP/SRT/HLS/FLV/WHEP 拉流转推 |
|
||
| IP 画像 | `web2_ip_profile.py` | 出口 IP 类型、住宅/机房判定、WebRTC 泄露联动 |
|
||
| IP 质量 | `web2_ip_quality.py` | 风险评分、流媒体解锁探测（参考 xykt/IPQuality） |
|
||
| 功能开关 | `web2_feature_flags.py`, `electron/src/shared/featureFlags.ts` | 摄像头/拉流 UI 与 API 显隐 |
|
||
| youLIVE | `electron/src/youlive/` | YouTube 监听、弹幕、账号、桌面通知 |
|
||
| 主进程 | `electron/src/main/` | 运行时打包、IPC、本地 DB |
|
||
| 界面 | `electron/src/renderer/` | React SPA |
|
||
|
||
---
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
.
|
||
├── electron/ # 无人直播助手（Electron + React）
|
||
│ ├── src/main/ # 主进程
|
||
│ ├── src/preload/ # contextBridge
|
||
│ ├── src/renderer/ # UI（直播 / 摄像头 / 拉流 / 网络 / 系统）
|
||
│ │ ├── components/worker/ # 业务工作台（链路条 / 清单 / 指标）
|
||
│ │ └── components/network/ # 网络页（链路条 / IP 画像 / IP 质量 / 测速图）
|
||
│ ├── src/shared/ # 前后端共享常量（功能开关 featureFlags）
|
||
│ ├── src/youlive/ # 内嵌 youLIVE（主进程服务 + 共享类型）
|
||
│ └── scripts/ # 离线运行时、图标
|
||
├── web2.py # FastAPI 入口
|
||
├── web2_*.py # 后端子模块（含 ip_profile / ip_quality / feature_flags）
|
||
├── third_party/IPQuality/ # IP 质量检测脚本参考（ip.sh）
|
||
├── config/ # 运行配置
|
||
├── backup_config/__web__/ # 配置自动备份
|
||
├── runtime/youtube_relay/ # 转播会话 sessions.sqlite
|
||
├── src/ # 录制核心（spider、stream、room…）
|
||
├── camera_youtube.py # 摄像头→YouTube worker
|
||
├── pull_stream_youtube.py # 外部拉流→YouTube worker
|
||
├── douyin_youtube_ffplay.py # 抖音→YouTube 转播
|
||
├── youtube2.py # YouTube worker
|
||
├── third_party/IPQuality/ # IP 质量检测参考脚本（ip.sh）
|
||
├── docs/ # 补充文档
|
||
└── requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 界面与功能
|
||
|
||
| 页面 | 说明 |
|
||
|------|------|
|
||
| **直播** | 抖音源站无人转播：单频道 / Pro、链路诊断、转播历史、youLIVE 目标端监控 |
|
||
| **摄像头** | 本机采集直推：设备预览、采集/编码配置、独立控制台（进程 `camera_youtube`） |
|
||
| **拉流** | 外部流转推：RTMP/SRT/HLS/FLV/WHEP 拉流、转码或流复制（进程 `pull_stream_youtube`） |
|
||
| **网络** | 链路诊断、境内外测速、IP 画像与质量、WebRTC 泄露检测、FFmpeg 代理 |
|
||
| **系统** | CPU/内存/磁盘/GPU、开机启动、路径、会员登录限制开关 |
|
||
|
||
**直播** 页面向抖音无人转播业务，含 Pro 多频道、三层链路诊断、转播历史等。
|
||
|
||
**摄像头** / **拉流** 页各自独立 UI 与工作流，不复用直播页布局；侧栏深链可直达（见下表）。默认构建中这两项为**隐藏**状态，见 [功能开关](#功能开关)。
|
||
|
||
**网络** 页采用链路管线布局：源站 / 分流 / YouTube / 上行四段可视化，配合实时测速曲线、境内外带宽对比、代理设置，以及 IP 画像与 IP 质量面板（见 [网络诊断与 IP 画像](#网络诊断与-ip-画像)）。
|
||
|
||
| 深链参数 | 页面 | 说明 |
|
||
|----------|------|------|
|
||
| `--nav=record` | 直播 | 默认页；Windows 任务栏快捷方式 |
|
||
| `--nav=camera` | 摄像头 | 本机采集直推 |
|
||
| `--nav=pull` | 拉流 | 外部流转推 |
|
||
| `--nav=network` | 网络 | 测速与代理（`--nav=proxy` 同义） |
|
||
| `--nav=system` | 系统 | 负载、路径、会员门禁 |
|
||
|
||
**业务工作台**（摄像头 / 拉流共用 `components/worker/`）：
|
||
|
||
- **WorkerFlowStrip**：三段链路条（采集/拉流 → 处理/编码 → YouTube 输出），按 `business_status` 着色
|
||
- **WorkerChecklist**：启动前配置清单（设备/地址、密钥、码率等），未就绪项显示提示
|
||
- **WorkerMetrics**：推流中展示 FFmpeg 速度、帧序号、worker 进程数与业务状态
|
||
|
||
直播页能力摘要：
|
||
|
||
- **自适应轮询**：推流中 ~0.8s，空闲 ~4s，后台标签 ~30s
|
||
- **链路诊断**：源站 / 推流 / 目标三层检查（`GET /youtube/diagnostics`）
|
||
- **YouTube 目标端监控**：监听地址写入 `youtube_channels.json`，与转播线路绑定
|
||
- **桌面通知**：推流未到达 YouTube、目标端下播、弹幕关键词（需 youLIVE 桌面通知开启）
|
||
- **转播历史**：PM2 状态自动记会话；支持从 PM2 日志导入
|
||
- **配置历史备份**：保存前自动备份，界面可恢复
|
||
- **YouTube Studio**：系统浏览器打开，便于核对密钥
|
||
- **源站预览**：解析抖音 URL 并尝试显示主播昵称
|
||
- **配对校验**：Pro 多线路保存时检测抖音地址 / YouTube 密钥跨频道重复，冲突时展示横幅并阻止启动
|
||
|
||
**网络** 页面向转播前的出口与链路自检，含：
|
||
|
||
- **链路快检**：国内源站（抖音）/ Google / 线路分流 / 海外上行 / 录制代理五项状态芯片
|
||
- **NetworkPipeline**：源站 → 分流 → YouTube → 上行四段链路条，按可达性与测速结果着色
|
||
- **境内外站点卡**：Google 与抖音的延迟、上下行测速、解析 IP 与地区
|
||
- **IP 出口画像**（`GET /ip_profile`）：本机默认出口与海外出口的类型（住宅/机房/代理/移动）、洁净度评分、WebRTC 本地泄露参考
|
||
- **IP 质量检测**（`GET /ip_quality`）：代理/VPN/Tor/机房风险因子、Abuser 评分、YouTube/Netflix 等流媒体解锁状态
|
||
- **测速趋势图**：`NetworkSpeedChart` 记录近期上下行采样
|
||
- **FFmpeg 代理**：录制/推流专用 HTTP/SOCKS 代理，与系统代理设置联动
|
||
- **自动刷新**：约 45s 静默轮询；WebRTC 检测完成后自动刷新 IP 画像
|
||
|
||
> 摄像头 / 拉流功能默认在导航中**隐藏**（见 [功能开关](#功能开关)），代码与 API 仍保留，可按需开启。
|
||
|
||
---
|
||
|
||
## 网络诊断与 IP 画像
|
||
|
||
**网络** 页在原有测速与代理基础上，新增出口画像与质量评估，帮助在推流前判断代理/VPN/机房 IP 是否适合 YouTube 转播。
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **链路管线** | 四段状态条：抖音源站可达性 → 分流路径 → Google/YouTube 延迟 → 上行带宽 |
|
||
| **测速曲线** | 境内外下载/上传 Mbps 实时采样与历史折线 |
|
||
| **IP 画像** | 本机默认出口与代理后海外出口对比：ISP、ASN、住宅/机房/代理类型、洁净度评分 |
|
||
| **WebRTC 泄露** | 渲染进程轻量 STUN 探测本地私网候选，结果上报 `ip_profile` 参与评分 |
|
||
| **IP 质量** | 多源风险评分（ipinfo、ipapi.is 等）、代理/VPN/Tor/机房因子、YouTube/TikTok/Netflix 等媒体解锁状态 |
|
||
| **代理设置** | FFmpeg 代理开关与 HTTP/SOCKS 地址，写入 `config/ffmpeg_proxy.ini` |
|
||
|
||
后端模块：
|
||
|
||
- `web2_ip_profile.py`：数据源 ip-api.com、ping0.cc、ipify
|
||
- `web2_ip_quality.py`：Python 化集成 [xykt/IPQuality](https://github.com/xykt/IPQuality) 思路；参考脚本见 `third_party/IPQuality/ip.sh`
|
||
|
||
> IP 检测依赖外部公开 API，结果仅供参考，不构成安全或合规保证。
|
||
|
||
---
|
||
|
||
## 功能开关
|
||
|
||
摄像头直推与外部拉流转推在代码中完整保留，但**默认关闭** UI 与相关 API，便于精简发布包。需要时分别修改前后端开关：
|
||
|
||
| 开关 | 文件 | 变量 |
|
||
|------|------|------|
|
||
| 后端 API / worker 发现 | `web2_feature_flags.py` | `SHOW_CAMERA_FEATURE`, `SHOW_PULL_STREAM_FEATURE` |
|
||
| 前端导航与深链 | `electron/src/shared/featureFlags.ts` | `SHOW_CAMERA_UI`, `SHOW_PULL_STREAM_UI` |
|
||
|
||
关闭时：
|
||
|
||
- 侧栏不显示 **摄像头** / **拉流** 入口；
|
||
- 深链 `--nav=camera` / `--nav=pull` 自动回落到 **直播** 页；
|
||
- `GET /camera/*`、`GET/POST /pull_stream/*` 返回功能已禁用提示。
|
||
|
||
---
|
||
|
||
## web2 API
|
||
|
||
默认：`http://127.0.0.1:8001`（`WEB2_PORT` 可改）。
|
||
|
||
| 分类 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 健康 | `GET /health` | 存活（无需鉴权） |
|
||
| 进程 | `GET /process_monitor` | 任务列表（含 Pro 频道） |
|
||
| 进程 | `GET /start` `/stop` `/restart` | 参数 `process=` |
|
||
| 状态 | `GET /status?process=` | 进程状态 + 业务诊断 + FFmpeg 指标 |
|
||
| 配置 | `GET/POST /youtube/ini_model` | 结构化 `youtube.ini` |
|
||
| 配置 | `GET/POST /get_url_config` `save_url_config` | `URL_config.ini` |
|
||
| 配置 | `GET /config/backups?file=` | 历史备份列表 |
|
||
| 配置 | `POST /config/restore` | 恢复（`file`, `backupId`） |
|
||
| Pro | `/relay_pro/*` | 多频道 CRUD、密钥、URL、YouTube 监听地址、live_status |
|
||
| 诊断 | `GET /youtube/diagnostics` | 源站 / FFmpeg / 目标三层诊断 |
|
||
| 诊断 | `GET /youtube/quality_guard` | 质量评分（诊断内部复用） |
|
||
| 摄像头 | `GET /camera/devices` | FFmpeg 枚举音视频采集设备 |
|
||
| 摄像头 | `GET/POST /camera/config` | 读写 `camera_live.ini` |
|
||
| 拉流 | `GET/POST /pull_stream/config` | 读写 `pull_stream.ini` |
|
||
| 拉流 | `GET /pull_stream/protocols` | 协议预设与示例地址 |
|
||
| 历史 | `GET /youtube/relay/sessions` | 转播会话 |
|
||
| 历史 | `POST /youtube/relay/sessions/import` | 从 PM2 日志导入 |
|
||
| 网络 | `GET /network_status` `GET/POST /proxy_config` | 测速与代理 |
|
||
| 网络 | `GET /ip_profile` | 出口 IP 画像（可选 `client_tz`、`client_lang`、`webrtc_leak`） |
|
||
| 网络 | `GET /ip_quality` | IP 质量与流媒体解锁探测 |
|
||
| 系统 | `GET /system_metrics` `GET /host/gpu_status` | 主机、磁盘、NVENC |
|
||
| OAuth | `GET /youtube/oauth/*` | Google 拉取串流密钥（UI 可关） |
|
||
|
||
**可选鉴权**：`config/web2_api_token.txt` 或 `WEB2_API_TOKEN` 存在时，除 `/health` 外需：
|
||
|
||
```http
|
||
Authorization: Bearer <密钥>
|
||
```
|
||
|
||
Electron 主进程自动注入 API 鉴权头。
|
||
|
||
---
|
||
|
||
## 配置与数据路径
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `config/youtube.ini` | 单路密钥与 `[youtube]` 选项（GPU、分辨率、RTMPS） |
|
||
| `config/URL_config.ini` | 单路源站 URL 列表 |
|
||
| `config/youtube_channels.json` | Pro 频道元数据（见 `youtube_channels.example.json`） |
|
||
| `config/relay_pro/url_config.ch_*.ini` | 每频道源站地址 |
|
||
| `config/relay_pro/youtube.ch_*.ini` | 每频道密钥（后端物化） |
|
||
| `config/web2_api_token.txt` | API 鉴权密钥 |
|
||
| `config/web2_bind_host.txt` | 监听地址（懒人包默认 `127.0.0.1`；局域网访问可设 `0.0.0.0` 并配置 token） |
|
||
| `config/google_oauth.example.json` | YouTube OAuth 模板 |
|
||
| `config/ffmpeg_proxy.ini` | FFmpeg 代理 |
|
||
| `config/camera_live.ini` | 摄像头采集参数（见 `camera_live.example.ini`） |
|
||
| `config/pull_stream.ini` | 外部拉流参数（见 `pull_stream.example.ini`） |
|
||
| `backup_config/__web__/` | 配置版本备份 |
|
||
| `runtime/youtube_relay/sessions.sqlite` | 转播会话库 |
|
||
| 用户数据目录 `client-data.sqlite` | Electron 本地事件与快照 |
|
||
|
||
示例 `config/youtube_channels.json`：
|
||
|
||
```json
|
||
{
|
||
"version": 1,
|
||
"channels": [
|
||
{
|
||
"id": "ch_a",
|
||
"name": "路线A",
|
||
"douyinUrl": "https://live.douyin.com/123456789",
|
||
"youtubeKey": "xxxx-xxxx-xxxx-xxxx"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 单频道与多频道 Pro
|
||
|
||
### 单频道
|
||
|
||
1. 填写 `config/youtube.ini` 中的串流密钥。
|
||
2. 填写 `config/URL_config.ini` 中的抖音直播间地址。
|
||
3. **直播** 页选择 `youtube2` → **开始直播**。
|
||
|
||
### 多频道 Pro
|
||
|
||
1. 直播页打开 **Pro** 开关。
|
||
2. 界面新增频道，或编辑 `config/youtube_channels.json`。
|
||
3. 每频道进程：`youtube2__{channelId}`，独立密钥与 URL 文件。
|
||
4. 网格内按频道启停；预检要求密钥与源站均已配置。
|
||
|
||
---
|
||
|
||
## 网络诊断 / IP 画像 / 代理
|
||
|
||
**网络** 页帮助在开播前确认「抖音源站可达 + 海外出口可用 + 上行带宽足够」。
|
||
|
||
### 链路诊断（`GET /network_status`）
|
||
|
||
| 检测项 | 说明 |
|
||
|--------|------|
|
||
| 国内源站 | 抖音域名可达性与延迟 |
|
||
| Google 出口 | YouTube 推流路径可达性 |
|
||
| 线路分流 | 对比境内外解析 IP，判断代理/TUN 是否生效 |
|
||
| 海外测速 | 参考上下行 Mbps（测速失败不代表无法推流） |
|
||
| 录制代理 | `config/ffmpeg_proxy.ini` 是否已配置 |
|
||
|
||
### IP 出口画像（`GET /ip_profile`）
|
||
|
||
参考 whoer / ping0.cc 维度，聚合 ip-api.com、ping0.cc 等数据源：
|
||
|
||
- **默认出口**与**海外出口**（经 Google 探测路径采样）的类型标签
|
||
- 住宅 / 机房 / 代理 / 移动判定与洁净度评分
|
||
- 浏览器侧 **WebRTC 本地候选**检测（`useWebRtcLeak`），结果通过 `webrtc_leak` 参数回传后端
|
||
|
||
### IP 质量检测（`GET /ip_quality`）
|
||
|
||
集成 [xykt/IPQuality](https://github.com/xykt/IPQuality) 思路（参考 `third_party/IPQuality/ip.sh`）：
|
||
|
||
- 代理、VPN、Tor、机房等风险因子
|
||
- 多源 Abuser / IPQS 评分
|
||
- YouTube、TikTok、Netflix、Disney+ 等流媒体解锁状态
|
||
|
||
### FFmpeg 代理
|
||
|
||
`GET/POST /proxy_config` 读写 `config/ffmpeg_proxy.ini`，供 `youtube2` 等 worker 拉流时使用，与 Windows 系统代理设置独立。
|
||
|
||
---
|
||
|
||
## 推流诊断 / 质量守卫 / 转播历史
|
||
|
||
`GET /status` 的 `business_status` 示例：
|
||
|
||
| 状态 | 含义 |
|
||
|------|------|
|
||
| `streaming` | 正在推流 |
|
||
| `relay_slow` | 推流速度低于实时 |
|
||
| `source_stalled` | FFmpeg 进度停滞 |
|
||
| `youtube_key_rejected` | YouTube 拒绝 RTMPS |
|
||
| `waiting_source` | 等待源站开播 |
|
||
| `misconfigured` | 配置不完整 |
|
||
| `monitoring` | 在线监测中 |
|
||
|
||
**链路诊断**：`GET /youtube/diagnostics` → 源站 / FFmpeg / 目标三层检查与综合评分。
|
||
|
||
**质量守卫**：`GET /youtube/quality_guard` → FFmpeg 指标与告警（诊断层内部复用）。
|
||
|
||
**转播历史**：`runtime/youtube_relay/sessions.sqlite`
|
||
|
||
- PM2 `online` / 停止时自动开闭会话；
|
||
- `/status` 轮询时从日志同步主播与时长；
|
||
- 界面 **从日志导入** 可解析历史 PM2 输出。
|
||
|
||
---
|
||
|
||
## youLIVE 目标端监控
|
||
|
||
内嵌于 Electron 主进程的 **youLIVE** 模块（`electron/src/youlive/`），通过 preload 暴露 `window.youlive` API，为直播页提供 YouTube **目标端**能力，与 `web2` 控制的 **源站推流** 互补。
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **监听列表** | 按 YouTube 频道 / 直播页 URL 轮询开播状态、观众数 |
|
||
| **转播绑定** | 将监听地址写入 `youtube_channels.json` 的 `youtubeWatchUrl`，与 Pro 线路一一对应 |
|
||
| **弹幕抓取** | 直播进行中拉取聊天消息，支持关键词告警 |
|
||
| **桌面通知** | 推流未到达 YouTube、目标端下播、弹幕关键词命中时通知（需在 youLIVE 设置中开启） |
|
||
| **本地存储** | `youlive` SQLite 保存监听项、会话、告警历史 |
|
||
|
||
直播页 **YouTube 目标端监控** 面板在 Pro / 单路模式下自动同步监听地址。
|
||
|
||
---
|
||
|
||
## 摄像头直推
|
||
|
||
**摄像头** 页面向本机采集业务，采用独立 **业务工作台** 布局：
|
||
|
||
- **顶部 Hero**：设备摘要、链路条（采集 → 编码 → YouTube）、配置清单与启停按钮
|
||
- **左侧**：`CameraLocalPreview` 实时画面预览
|
||
- **下方三栏**：设备选择、编码参数、YouTube 密钥与高级选项
|
||
- **推流中**：右侧展示 `WorkerMetrics`（FFmpeg 速度 / 帧序号 / 业务状态）
|
||
|
||
进程名 `camera_youtube`，与抖音转播 `youtube2` 独立，请勿同时开启冲突 worker。
|
||
|
||
1. 选择 **视频设备** / **音频设备**（`GET /camera/devices` 枚举 DirectShow）。
|
||
2. 设置分辨率、帧率、码率；可选 NVENC。
|
||
3. 填写 YouTube **串流密钥**（复用 `config/youtube.ini`）。
|
||
4. 点击 **开始直播**。
|
||
|
||
配置：`config/camera_live.ini`（模板 `config/camera_live.example.ini`）。
|
||
|
||
---
|
||
|
||
## 外部拉流转推
|
||
|
||
**拉流** 页面向已有流媒体管线：从 SRS、OBS、其他节点提供的地址拉流，转码或复制后推到 YouTube Live。布局与摄像头页一致的业务工作台：
|
||
|
||
- **顶部 Hero**：拉流地址摘要、协议预设芯片、链路条（拉流 → 处理 → YouTube）、配置清单与启停
|
||
- **下方三栏**：处理策略（协议/转码/码率）、YouTube 密钥、高级参数（SRT 延迟、重连、额外 FFmpeg 参数）
|
||
- **推流中**：展示实时 FFmpeg 指标与业务状态
|
||
|
||
进程名 `pull_stream_youtube`。
|
||
|
||
### 支持协议
|
||
|
||
| 协议 | 示例 |
|
||
|------|------|
|
||
| RTMP / RTMPS | `rtmp://127.0.0.1/live/stream` |
|
||
| SRT | `srt://host:10080?mode=caller&streamid=…` |
|
||
| HLS | `https://example.com/live/index.m3u8` |
|
||
| HTTP-FLV | `http://127.0.0.1:8080/live/stream.flv` |
|
||
| WebRTC (WHEP) | `whep://…`（需 FFmpeg 支持；否则经 SRS 转 RTMP/SRT） |
|
||
| UDP / MPEG-TS | `udp://@:1234` |
|
||
|
||
### 处理模式
|
||
|
||
- **转码**（默认）：H.264 + AAC，兼容 YouTube
|
||
- **流复制**：源须已是 H.264 + AAC，延迟更低
|
||
|
||
### 使用步骤
|
||
|
||
1. 打开 **拉流** 页，填写拉流 URL（可点协议预设快速填入示例）。
|
||
2. 选择协议（可自动识别）、转码/复制、码率与 NVENC。
|
||
3. 填写 YouTube 串流密钥 → **开始转推**。
|
||
4. SRT 延迟、断线重连、额外 FFmpeg 参数等在「高级参数」中配置。
|
||
|
||
配置：`config/pull_stream.ini`（模板 `config/pull_stream.example.ini`）。
|
||
|
||
---
|
||
|
||
## 会员登录门禁（可选）
|
||
|
||
默认 **关闭**（无登录 UI，启动直播无账号要求）。
|
||
|
||
开启：**系统** → **客户端与系统集成** → **会员登录限制**
|
||
|
||
- 侧栏显示登录/注册；
|
||
- 开始/重启前需 PocketBase 会员（`X-PB-Token`）；
|
||
- 状态键：`localStorage` → `pb_auth_gate_enabled`。
|
||
|
||
---
|
||
|
||
## 功能开关
|
||
|
||
摄像头直推与外部拉流转推默认**关闭**（导航隐藏、相关 API 返回 404、PM2 忽略对应 worker），以降低首屏复杂度。需要时分别修改：
|
||
|
||
| 位置 | 常量 | 默认 |
|
||
|------|------|------|
|
||
| `electron/src/shared/featureFlags.ts` | `SHOW_CAMERA_UI`、`SHOW_PULL_STREAM_UI` | `false` |
|
||
| `web2_feature_flags.py` | `SHOW_CAMERA_FEATURE`、`SHOW_PULL_STREAM_FEATURE` | `False` |
|
||
|
||
前后端开关需保持一致。深链 `--nav=camera` / `--nav=pull` 在关闭时会回落到 **直播** 页。
|
||
|
||
---
|
||
|
||
## 开发与构建
|
||
|
||
| 组件 | 版本 |
|
||
|------|------|
|
||
| Node.js | 18+ |
|
||
| pnpm | 10+ |
|
||
| Python | 3.10+（开发机；发布包自带运行时） |
|
||
|
||
| 命令（在 `electron/`） | 说明 |
|
||
|------------------------|------|
|
||
| `pnpm dev` | 开发模式 |
|
||
| `pnpm build` | 编译到 `out/` |
|
||
| `pnpm prepare:runtime` | 准备离线 Python/FFmpeg |
|
||
| `pnpm verify:runtime` | 校验运行时 |
|
||
| `pnpm dist` | Windows 便携包 |
|
||
|
||
---
|
||
|
||
## 打包发布
|
||
|
||
```bash
|
||
cd electron
|
||
pnpm install
|
||
pnpm dist
|
||
```
|
||
|
||
产物：`electron/dist/` 便携版。仓库根（除 `electron/`）打入 `resources/backend/`，用户机无需单独安装 Python。
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `WEB2_PORT` | API 端口，默认 `8001` |
|
||
| `WEB2_HOST` | 监听地址（优先于 `web2_bind_host.txt`） |
|
||
| `WEB2_API_TOKEN` | API 密钥 |
|
||
| `WEB2_SUPERVISOR` | 进程后端；Pro 多频道勿强制 PM2 |
|
||
| `VITE_API_BASE` | 渲染进程 API 根（非 Electron 调试） |
|
||
| `VITE_WEB2_API_TOKEN` | 开发用 Bearer |
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| 无法启动 / 服务未就绪 | 查 uvicorn 日志；确认 8001 未被占用；`pnpm verify:runtime` |
|
||
| YouTube 无画面 | 看 `youtube_key_rejected`；核对 Studio 密钥；检查 RTMPS 与代理 |
|
||
| `relay_slow` / 掉帧 | 查 NVENC；降分辨率；关占用 CPU 的程序 |
|
||
| Pro 无法启动 | 勿 `WEB2_SUPERVISOR=pm2`；每频道密钥与 URL 已保存；检查配对冲突横幅 |
|
||
| 摄像头无画面 | 确认 DirectShow 设备名与 `camera_live.ini` 一致；尝试关闭 GPU 编码 |
|
||
| 拉流连接失败 | 核对协议与 URL；SRT 检查 caller/streamid；WebRTC 建议经 SRS 转 RTMP |
|
||
| 拉流有画面 YouTube 无 | 流复制模式下源可能非 H.264+AAC，改转码模式 |
|
||
| 目标端监听无数据 | 直播页确认 `youtubeWatchUrl` 已填写；youLIVE 桌面通知已开启 |
|
||
| Google 不可达 / 分流未生效 | **网络** 页查看链路快检；配置 TUN/规则代理；填写 FFmpeg 代理 |
|
||
| IP 画像显示机房/代理 | 更换住宅出口或调整代理节点；关注 WebRTC 泄露提示 |
|
||
| IP 质量检测超时 | 外网 API 偶发慢；稍后刷新；检查本机防火墙 |
|
||
| 配置误改 | 直播页 **历史备份** 或 `POST /config/restore` |
|
||
|
||
日志：
|
||
|
||
- Worker：`.pm2/logs/` 或界面「当前直播日志」
|
||
- 客户端：系统页打开「客户端日志」目录
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [docs/YOUTUBE_LIVE_SEO.md](docs/YOUTUBE_LIVE_SEO.md) | YouTube 直播 SEO |
|
||
| [docs/REALTIME_AUDIO_DEMUCS.md](docs/REALTIME_AUDIO_DEMUCS.md) | 实时音频 Demucs |
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目继承上游 DouyinLiveRecorder 及相关依赖的许可证条款。使用第三方平台直播服务请遵守各平台服务条款。
|