# 无人直播助手

Windows 桌面端 **抖音 → YouTube 无人转播** 控制台：内置 Electron 客户端、FastAPI 控制面（`web2`）、FFmpeg 推流 worker、多频道 Pro、推流诊断。

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Electron](https://img.shields.io/badge/electron-33-blue.svg)](https://www.electronjs.org/)
[![Platform](https://img.shields.io/badge/platform-Windows-blue.svg)]()

> 录制核心基于 [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 及相关依赖的许可证条款。使用第三方平台直播服务请遵守各平台服务条款。