基于 FastAPI + yt-dlp的无水印视频解析微信小程序

核心需求：为什么要下载无水印视频？

在日常使用短视频平台时，最常见的操作就是点击“保存视频”。但这种官方渠道下载的视频，往往在角落里带有跳动的水印（包含平台 Logo 和作者 ID）。

对于普通用户来说，这可能只是观感上的小小瑕疵；但对于开发者、内容创作者或技术研究者而言，水印的存在意味着：

视觉干扰：水印会遮挡画面细节，在进行视频分析、AI 识别或技术演示时，这些动态 Logo 会成为干扰噪声。
分发受限：主流平台（如抖音、小红书等）拥有极强的内容识别算法。带有 A 平台水印的视频直接上传到 B 平台，会被系统判定为“搬运”从而限流。
二次创作痛点：剪辑素材需要较高纯净度的原始画面，以保证成片的质量。

因此，StreamPick 的核心目标就是通过技术手段，绕过客户端的展示层，直接嗅探并提取存储在 CDN 上的原始无水印视频直链。

项目架构

StreamPick 采用了一套前端轻量化、后端工程化、网关标准化的架构。

全链路流程

整个解析流程可以抽象为四个核心阶段：

用户交互层：微信小程序接收用户粘贴的原始分享链接（如 v.douyin.com/...）。
流量调度层 (Nginx)：通过反向代理将请求转发至内部 API 端口，并对外部加密请求进行安全卸载。
核心逻辑层 (FastAPI)：后端接入请求后，通过解析引擎模拟终端访问，深度追踪链接的跳转轨迹并提取隐藏的原始资源指纹。。
资源交付层：后端返回视频、封面及标题的直链，小程序通过 downloadFile 接口完成最终的物理保存。

核心组件设计逻辑

接入网关：Nginx

我们没有直接暴露后端端口，而是利用 Nginx 做了路径重写（Path Rewrite）：

版本控制：对外统一暴露 /v1/stream-pick/，方便后续版本迭代。
安全隔离：隐藏了后端真实的端口，通过阿里云安全组实现物理隔离。
协议对齐：解决反向代理下 HTTPS 的证书校验问题，确保小程序请求不被拦截。

解析引擎：FastAPI + yt-dlp

后端选择 FastAPI 是为了利用其异步非阻塞（Asynchronous）的特性，这在处理耗时较长的网络嗅探任务时表现优异。

yt-dlp 集成：利用其成熟的插件生态，实现对数百个短视频平台的协议支持。
模拟 UA 策略：通过注入特定的 User-Agent（如高版本 Chrome 或移动端 Safari），绕过目标平台的简易风控。

C. 环境隔离：venv 物理沙盒

为了保证生产环境的整洁，我们在 /var/www/ 下为项目建立了独立的 python3 -m venv 虚拟环境。

优势：解析库（尤其是 yt-dlp）需要高频更新以对抗平台算法升级，虚拟环境确保了升级操作不会影响服务器上的其他 Python 服务（如我们的自动化脚本或监控工具）。

流程自动化

流媒体平台的风控逻辑是动态的。为了防止“今天好用，明天报废”，我们在架构中加入了一层自动运维逻辑：

Systemd 守护：确保服务崩溃后秒级重启。
Crontab 定时任务：每月自动触发更新脚本，强制升级解析库并重启服务，将维护成本降至最低。

前端实现

在小程序前端开发中，核心任务是处理异步状态的可靠性以及微信原生权限接口的特殊行为。StreamPick 的前端设计主要聚焦于状态锁、权限自愈以及多媒体资源的动态调度。

异步状态管理：防止解析请求过载

视频解析涉及后端的网络嗅探，其响应时间受目标平台反爬策略影响，通常在 3-8 秒。为避免用户在请求处理期间重复触发解析逻辑，程序在 onParse 函数入口处设置了布尔型变量 loading。

逻辑实现：

if (this.data.loading) return; 
this.setData({ loading: true });

通过状态预检拦截后续指令，直至 complete 回调触发并重置 loading。这一设计确保了后端 yt-dlp 进程的有序调度，防止服务器因瞬时并发导致的 IP 频控或资源耗尽。

权限自愈链路：应对 writePhotosAlbum 授权异常

微信小程序的相册写入权限（scope.writePhotosAlbum）具有特定的持久化行为。一旦用户在首次请求时点击“拒绝”，后续的保存指令将直接进入失败分支（Fail Callback），且系统不再自动弹出授权申请窗口。

权限恢复逻辑如下：

状态嗅探：在执行保存动作前，调用 wx.getSetting 获取当前的权限集合。
异常判定：若检测到 authSetting['scope.writePhotosAlbum'] 为 false（即已拒绝），则判断为功能受限状态。
手动引导：通过 wx.showModal 明确告知用户功能失效原因，并配合 confirm 回调执行 wx.openSetting。
提权跳转：用户在设置页面手动开启权限后，返回小程序即可恢复正常的保存链路。

多媒体资源调度：高阶封装与动态分发

后端 API 返回的数据结构包含视频 URL、封面图 URL 以及标题文本。为了优化代码结构，前端引入了基于状态的动态分发机制。

上下文映射：根据当前活跃的标签页（activeTab）状态，系统自动路由至不同的处理逻辑：

二进制流下载：视频与图片统一通过 _doDownloadFile 封装函数处理。该函数内部集成了 wx.downloadFile，并根据传入的 type 参数（video/image）动态调用 wx.saveVideoToPhotosAlbum 或 wx.saveImageToPhotosAlbum。
文本流操作：标题部分直接路由至剪贴板写入接口（wx.setClipboardData）。

域名校验规范：在生产环境中，所有解析出的 CDN 链接必须符合微信公众平台配置的 downloadFile 合法域名要求。前端通过监测 res.statusCode 确保资源成功拉取至本地临时路径，随后执行持久化保存。

后端设计：基于 FastAPI 与 Systemd 的自动化解析体系

后端架构的核心任务是在生产环境下提供高可用的解析接口，并确保解析引擎能够自动应对短视频平台的算法迭代。StreamPick 的后端设计聚焦于环境隔离、进程守护以及自动化的运维策略。

环境隔离与依赖管理策略

在 /var/www/ 生产目录下，后端通过 Python 虚拟环境实现物理隔离。

隔离必要性：由于 yt-dlp 等解析库需要频繁更新以对抗平台风控，使用 venv 可确保项目依赖库的升级不会污染全局系统环境，同时避免不同项目间因版本冲突导致的运行异常。
依赖配置：核心组件包括 FastAPI（异步 Web 框架）、Uvicorn（高性能 ASGI 服务器）以及 yt-dlp。

# 创建项目根目录
mkdir -p /var/www/stream-pick-api
cd /var/www/stream-pick-api

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装生产环境依赖
pip install fastapi uvicorn yt-dlp

4.2 解析逻辑实现：特征嗅探与指纹提取

后端接口接收前端传参后的核心逻辑是对目标 URL 进行多级跳转追踪与资源定位。

模拟访问配置：通过在 yt-dlp 的 ydl_opts 中注入高版本的 User-Agent（如 Chrome 122），模拟真实浏览器行为，绕过基础频率限制。

非阻塞提取：采用 download=False 模式。

逻辑描述：程序仅抓取网页源代码及 JSON 元数据，不触发实际的物理下载动作。通过正则匹配或 DOM 解析，提取出隐藏在 CDN 节点中的无水印视频直链（URL）、封面图（Thumbnail）及视频标题。

异常处理：针对不同平台的返回结构差异，设置了分级容错机制。若解析出的 url 为空，则自动尝试从 formats 列表的末尾抓取最高质量的流地址。

# main.py 核心片段
@app.post("/parse")
async def parse_video(req: VideoRequest):
    ydl_opts = {
        'format': 'bestvideo+bestaudio/best',
        'quiet': True,
        'extract_flat': False,
        'user_agent': 'Mozilla/5.0 ...'
    }
    try:
        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
            info = ydl.extract_info(req.url, download=False)
            # ... 提取关键信息逻辑
            return {"success": True, "data": {...}}
    except Exception:
        return {"success": False, "error": "Internal Processing Error"} # 隐藏底层报错详情

if __name__ == "__main__":
    import uvicorn
    # 仅监听 127.0.0.1，强制流量走 Nginx
    uvicorn.run(app, host="127.0.0.1", port=18000)

进程守护：Systemd 服务自动化管理

为了确保解析服务在服务器重启或进程崩溃后能够自动恢复，系统编写了 stream-pick.service 配置文件。

生命周期控制：

ExecStart：指定虚拟环境内的 uvicorn 绝对路径执行 main:app，确保环境的一致性。
Restart策略：配置 Restart=always 与 RestartSec=3。当检测到后端进程因内存溢出或逻辑错误退出时，系统将在 3 秒内强制拉起新进程。

权限管控：服务运行于 www-data 用户组下，通过最小权限原则降低系统被渗透的风险。

创建一个系统服务，让它随开机启动：

vim /etc/systemd/system/stream-pick.service

粘贴以下内容：

[Unit]
Description=StreamPick API Service
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/project-api
ExecStart=/var/www/project-api/venv/bin/python3 -m uvicorn main:app --host 127.0.0.1 --port 18000
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

启动并开机自启：

systemctl daemon-reload
systemctl start streampick
systemctl enable streampick

自动化维护：应对平台算法迭代

短视频平台的加密协议具有高度不稳定性，依赖库的滞后会导致解析失效。系统通过自动化脚本实现了“零人工”维护。

脚本逻辑设计：

调用虚拟环境 pip 执行 -U yt-dlp 强制升级。
将升级结果与当前时间戳追加至 update.log，构建可追溯的运维日志。
执行 systemctl restart streampick，确保新版本的解析算法立即生效。

编写自动化更新脚本

在 /var/www/streampick-api/ 目录下创建 update_ydl.sh：

vim /var/www/streampick-api/update_ydl.sh

输入以下内容：

#!/bin/bash
# 进入项目目录
cd /var/www/stream-pick-api
# 使用虚拟环境内的 pip 完整路径进行更新，并记录日志
./streampick_env/bin/pip install -U yt-dlp >> /var/www/stream-pick-api/update.log 2>&1
# 更新完后重启服务，确保新版本生效
systemctl restart stream-pick
echo "Update check at $(date)" >> /var/www/stream-pick-api/update.log

保存退出后，赋予执行权限：

chmod +x /var/www/stream-pick-api/update_ydl.sh

配置 Cron 计划任务

使用 crontab -e 来设置定时触发，在文件末尾添加一行（设定为每月 1 号的凌晨 3 点执行）：

0 3 1 * * /var/www/stream-pick-api/update_ydl.sh
# 0 3 1 * * 分别代表：第0分、第3时、每月1日、每月、每周。

使用crontab -l列出当前的计划任务验证设置是否成功。

生产环境部署

在完成前后端开发后，将系统推向生产环境（如阿里云 ECS）需要解决最后的架构兼容性问题。这不仅涉及反向代理的配置，还包括处理 HTTPS 强制校验下的资源加载异常。

流量分发：Nginx 的反向代理设计

为了隐藏后端真实端口并实现多业务共存，系统利用 Nginx 作为统一入口。

路径映射逻辑：通过 location /v1/streampick/ 块将外部流量导向本地 18000 端口。
关键配置：

Nginx
```
location /v1/streampick/ {
    proxy_pass http://127.0.0.1:18000/; # 末尾斜杠实现路径剥离
    proxy_set_header X-Forwarded-Proto $scheme;
    # ... 其他 Header 配置
}
```
通过 X-Forwarded-Proto 头部，Nginx 将外部请求的原始协议（HTTPS）告知后端 FastAPI，确保生成的资源链接与外部访问协议保持一致。

物理隔离：安全组与防火墙策略

生产环境的安全性依赖于最小化暴露面。

端口收敛：在阿里云控制台的安全组配置中，仅保留 80 (HTTP) 和 443 (HTTPS) 端口对公网开放。
后端遮蔽：解析服务的 18000 端口仅允许 127.0.0.1 访问，通过 Nginx 进行内部转发。这种设计切断了攻击者直接扫描并利用后端 API 漏洞的物理路径。

域名合规性：微信 downloadFile 白名单

微信小程序对资源下载有严格的白名单机制。

动态域名挑战：由于解析出的视频直链可能指向 douyin.com、weibo.com 或各平台的 CDN 域名，这些域名必须提前在小程序管理后台的“服务器域名”列表中备案。
实战规避：对于无法穷举的 CDN 域名，目前的生产实践通常是定期监测解析日志，将高频出现的域名批量加入白名单，或通过自建中转服务器（Proxy）实现固定域名下载。