YT 下载中心 · 部署与交接文档

> 部署日期：2026-09-02 · 服务器：va（甲骨文 VPS，aarch64 / Ubuntu 22.04，root@va.485494.xyz:35134，私钥 C:\Users\rui\.ssh\va） > 面板地址：https://yt.va.485494.xyz · 本地源码副本：D:\tools\yt_va_sync\server\

一、功能总览

模块说明
视频任务 (video)迁移自本地 d:\dl\ytb\update\yt-rss-dl.py。RSS 驱动，YouTube 最高画质 (bestvideo+bestaudio→mp4)、全字幕转 srt，B站走直接链接模式。跳过 Shorts、直播、关键字命中（黑白名单见第十二节）。
音频任务 (audio)迁移自本地 d:\dl\ytb\audios\yt-rss-dl-audios.py。播客 RSS enclosure / YouTube 频道音频，ffmpeg loudnorm (-10 LUFS) 转码 MP3。xyzrank 小宇宙热榜改用纯 JSON API（无需浏览器），支持按节目名过滤。
聚合下载 (media)整合自本地 8208 全能媒体下载器（FastAPI + yt-dlp + ReportLab）。支持小红书图文排版 A4 PDF、B站选集、YouTube 4K、微博、播客、Twitter 等 1000+ 网站单条/合集智能解析与实时下载，保存在 /opt/yt-rss-dl/downloads/。
Web 面板登录鉴权（HMAC-SHA256 Cookie）、运行状态、日志查看、立即运行、Feeds 增删改、📥 聚合下载中心内嵌、订阅源级黑白名单编辑 + 试算预览、全局黑白名单、Cookies 在线更新、Bark 设置与测试、本部署文档页。
Bark 通知Cookie 失效 / 需要登录 / 分辨率低于阈值 / Feed 解析失败 / 转码失败 / 任务崩溃 → 推送 https://bark.ihust.de/ba2HG5BN5saaYq5k6xfW27（fnos 自建 bark-server）。
Windows 同步本地 D:\tools\yt_va_sync\sync_local.py 定时拉取成品到 d:\dl\ytb\update\（视频）与 d:\dl\ytb\audios\01_downloaded\（音频），校验完整后删除 va 上的文件释放空间。

二、目录结构（va）

/opt/yt-rss-dl/
├── common.py            # 共享库：配置/日志/锁/Bark/监控/feeds 管理
├── video_worker.py      # 视频任务（yt-rss-video.timer 每30分钟）
├── audio_worker.py      # 音频任务（yt-rss-audio.timer 每30分钟）
├── panel.py             # Web 面板（yt-rss-panel.service，127.0.0.1:8210）
├── DEPLOY.md            # 本文档（面板 /docs 页读取）
├── config.json          # 全局配置（bark、质量阈值、关键字等）
├── auth.json            # 面板账号（admin，SHA256 密码，0600）
├── bin/yt-dlp           # 自更新二进制（每24h检查一次）
├── youtube_cookies.txt  # YouTube cookies（0600，面板可更新，双服务共享）
├── bilibili_cookies.txt # B站 cookies（双服务共享）
├── downloads/           # 聚合下载成品存储目录
├── media_downloader/    # 全能媒体聚合下载服务（FastAPI，127.0.0.1:8208）
│   ├── main.py          # FastAPI 主入口与 API 路由
│   ├── config.json      # 聚合下载服务配置
│   ├── static/          # 前端单页（Vue 3 + Tailwind）
│   └── core/            # 调度器、任务管理、小红书/微博/播客/ytdlp 提取器与 A4 PDF 生成器
├── video/
│   ├── feeds.json       # 视频订阅源（面板管理）
│   ├── downloaded.txt   # yt-dlp 下载归档去重
│   ├── tmp/             # 下载中文件
│   └── sync/            # 成品暂存区（等 Windows 拉取，拉走即删）
└── audio/
    ├── feeds.json
    ├── downloaded.txt
    ├── raw/             # 原始音频（待转码）
    ├── tmp/             # 转码中
    └── sync/            # MP3 成品暂存区

三、systemd 服务与定时器

单元说明
yt-rss-video.service/.timer视频任务，OnCalendar *-*-* *:07/2:00（每2小时的第7分和第37分 ≈ 30分钟节奏）
yt-rss-audio.service/.timer音频任务，同节奏（第17/47分，与视频错开）
yt-rss-panel.service控制面板（8210 端口），Always 重启
yt-media-downloader.service全能媒体聚合下载服务（8208 端口），Always 重启
bash
systemctl list-timers | grep yt-rss     # 查看下次触发
systemctl start yt-rss-video            # 手动立即运行
journalctl -u yt-rss-video -n 100       # 看服务级日志
tail -f /opt/yt-rss-dl/logs/video.log   # 任务日志（轮转5MB×3）
防重入：单实例 flock（上一轮没跑完自动跳过本轮）；单轮 100 分钟硬时限，到期后未处理的 feed 下轮继续 —— 保证 30 分钟定时器不会堆叠。

四、域名 / HTTPS

五、登录凭据

六、Cookie 维护

1. YouTube cookie 失效时手机会收到「⚠️ 视频任务 Cookie 异常」推送。 2. Windows 浏览器（登录 youtube.com 后）用 *Get cookies.txt LOCALLY* 扩展导出 Netscape 格式。 3. 打开面板 → Cookies → 粘贴 → 保存；或 scp 覆盖 /opt/yt-rss-dl/youtube_cookies.txt。 4. yt-dlp 每 24 小时自动 -U 自更新，是绕过 YouTube 风控的第一道防线。

七、质量保障机制

八、Windows 同步端

九、常见运维

bash

改订阅源关键字/新增 feed → 直接用面板


查 cookie 告警上下文

grep -iE 'sign in|cookies' /opt/yt-rss-dl/logs/video.log | tail

清理卡死的临时文件

ls -la /opt/yt-rss-dl/video/tmp/ /opt/yt-rss-dl/audio/{raw,tmp}/

磁盘水位

df -h / && du -sh /opt/yt-rss-dl/*/sync

十、单集生命周期与自愈机制（v3.1 更新）

1. ⚙️ 云端转码/下载中 (processing): 仅在后台存在真实的 .processing / .part / .tmp 临时文件或进程正在运行转码时统计展示，无正在处理任务时严格为 0； 2. ⏳ 待本地拉取 (pending): 云端成品暂存区（/opt/yt-rss-dl/*/sync/）真实就绪的成品文件； 3. ✅ 已同步到电脑 (synced): Windows 本地校验大小一致并清除云端暂存区后的完成归档。

十一、数据流

YouTube/B站/播客 RSS ──▶ va: video_worker/audio_worker (yt-dlp + ffmpeg)
                              │  成品落 /opt/yt-rss-dl/*/sync/
                              ▼
Windows 计划任务 sync_local.py ──HTTP / SFTP──▶ d:\dl\ytb\{update,audios}\01_auto\
                              │  校验大小一致
                              ▼
                       删除 va 端文件 + 记录 sync_activity.jsonl
告警链路：worker 日志 ──▶ RunMonitor ──▶ Bark(App)

十二、下载黑白名单（关键字过滤）· 2026-09-16 新增

规则合成逻辑（务必按此理解，避免误判）

层级配置位置黑名单 exclude白名单 include
全局面板 ⚙️ 设置 → 🚫 下载黑白名单（存 config.json）exclude_keywordsinclude_keywords
订阅源面板 📁 订阅源 → 每行 🚫 规则（存 audiovideo/feeds.json）该源的 exclude该源的 include
小宇宙热榜同上页 xyz_exclude_keywords / xyz_include_keywords按 节目名 + 单集标题 匹配同左

现网已生效的规则

试算预览（推荐先试算再保存）

面板 📁 订阅源 → 某行 🚫 规则 → 🔍 试算最近 20 条：后端 POST /api/feeds/preview 会实时拉取该源最近条目，逐条标注 放行 / 拦截 及命中原因，不落盘、不触发下载。

排障

bash
grep -aE "黑名单命中|白名单未命中|白名单命中|过滤跳过" /opt/yt-rss-dl/logs/{video,audio}.log | tail -20

十三、B 站（bilibili）在 va VPS 上下载 · 2026-09-16 结题

结论：可行，且已在代码层打通（普通稿件）

⚠️ 核心坑：HTTP 412 的根因是「UA 与 TLS 指纹不自洽」

www.bilibili.com 的 WAF 会校验 User-Agent 与 TLS/HTTP 指纹是否匹配。yt-dlp 默认发 Chrome 浏览器 UA，但底层是 Python 的 urllib TLS 栈 → 被判定为爬虫，100% 返回 HTTP Error 412: Precondition Failed，连网页都取不到。 实测 UA 矩阵（va，美西 IDC IP）：
传给 --user-agent 的值结果
yt-dlp 默认（Chrome 浏览器 UA）❌ 412 Precondition Failed
python-requests/2.31.0❌ 412
curl/8.5.0△ 能过首页，但卡在 Unable to extract initial state
Wget/1.21✅ 连续 3/3 通过，格式全档可取
空（不带 --user-agent）❌ 412
> 反直觉点：curl 命令行用默认 UA 访问该页面反而 200，换成 Chrome UA 立刻 412 —— 同一把尺子。 已实施的修复（common.extra_net_args()）：凡是 URL 含 bilibili.com，自动追加 --user-agent Wget/1.21；UA 可在面板「设置 → B 站 User-Agent」调整（切勿改回浏览器 UA）。YouTube 路径完全不受影响。

实测数据（va → upos CDN）

项目结果
首页连通性www.bilibili.com HTTP 200；api.bilibili.com 200
格式360P/480P/720P/1080P 全档，含 avc1 / hvc1 / av01 三种编码
1080P 是否需要登录本批测试稿件不需要（未带 SESSDATA 也能取到 1920x1080）
音频轨bestaudio 正常，49 分钟视频音频 55.8 MiB
单流下载速度7.4 MB/s（55.8 MiB / 7.52 s）；另一轮 CDN 节点为 ~1 MB/s，节点间波动大
完整流水线720P 视频+音频合并 mp4，ffprobe 校验 av1 + aac，时长 298.3s，合法可播

尚未打通 / 已知缺口

1. UP 主空间列表（space.bilibili.com/<mid>/video）→ Request is rejected by server (352) / blocked (412)。 空间接口走 WBI 签名 + 风控，必须有登录态。当前 bilibili_cookies.txt 里只有匿名设备 Cookie（buvid3/buvid4/_uuid/b_lsid…），没有 SESSDATA → 无法列空间视频。 ⇒ video/feeds.json 里那 3 个 B站空间源（没脸鉴车 / 备胎说车 / 大锤RUNKMD，均 disabled）在补 SESSDATA 之前不要启用，否则每轮都是失败并累计 fail_counts。 补法：浏览器登录 B站 → Get cookies.txt LOCALLY 导出 → 面板 Cookies → Bilibili 粘贴保存（文件需含 SESSDATA）。至少含：SESSDATA、bili_jct、buvid3、buvid4、DedeUserID。 2. 1080P60 / 4K / 大会员 / 付费课程：需带 SESSDATA（4K 还需大会员账号）。 3. 港澳台限定番剧 / 部分区域受限稿件：会返回 This video may be deleted or geo-restricted；普通番剧季（如 bangumi/play/ss*）实测可列出条目。 4. 编码偏好建议：当前 -f bestvideo[ext=mp4]+... 会优先选中 AV1（av01）。AV1 在旧设备/电视上兼容性差，如需最稳的兼容性可给 B站 追加 -S "vcodec:h264" 之类的排序偏好（尚未实施，按需再加）。

想启用 B 站订阅的顺序

1. 先确认能下单条视频（面板加一个 https://www.bilibili.com/video/BVxxxx 视频任务源，跑一轮看是否落到 video/sync/）。 2. 再更新带 SESSDATA 的 B站 Cookies。 3. 最后才把空间源改成 enabled: true，并配好黑白名单（B站空间靠 --match-title/--reject-title 过滤）。

十四、全能媒体聚合下载中心整合 · 2026-09-20 新增

核心架构与部署

1. 引擎部署： 2. 安全网关与鉴权： 3. 控制面板深度功能整合与去冗余： 4. 严格的 24 小时安全留存与自动清理机制：
← 返回控制台