docs: 添加全平台技术文档与逆向工程百科

This commit is contained in:
ucmao
2026-08-29 20:22:28 +08:00
parent 64bff798a3
commit adf5ea62fc
35 changed files with 1838 additions and 0 deletions
+154
View File
@@ -0,0 +1,154 @@
# 系统架构与解析生命周期设计 (Architecture)
本文档详细阐述 **Media Parser** 的内部架构分层、请求处理生命周期、工厂模式插件化发现机制以及数据响应标准。
---
## 🏛️ 整体分层架构
项目遵循模块化、高内聚、低耦合的设计原则,自底向上分为以下四层:
```mermaid
flowchart TD
Client["客户端 / Web体验页 / API调用者"]
subgraph WebLayer["1. Web 接入层 (app.py & src/api/)"]
App["Flask App / 路由"]
ParseAPI["POST /api/parse"]
HealthAPI["GET /api/health"]
end
subgraph CoreLayer["2. 调度与解析引擎 (Core Engine)"]
UrlParser["UrlParser (正则提取/平台识别)"]
WebFetcher["WebFetcher (302重定向追踪)"]
Factory["ParserFactory (动态发现与分发)"]
end
subgraph ParserLayer["3. 平台解析器层 (src/parsers/)"]
BaseParser["BaseParser (基类/Session管理)"]
Douyin["DouyinParser"]
Kuaishou["KuaishouParser"]
XHS["XiaohongshuParser"]
Bili["BilibiliParser"]
Others["... 30+ 其它解析器"]
end
subgraph UtilLayer["4. 工具与逆向支持 (utils/ & configs/)"]
Signer["BogusSigner (mini-racer JS执行)"]
Logger["LoggingConfig"]
CommonUtils["make_response 标准化响应"]
end
Client --> App
App --> ParseAPI
ParseAPI --> UrlParser
ParseAPI --> WebFetcher
ParseAPI --> Factory
Factory --> BaseParser
BaseParser --> Douyin & Kuaishou & XHS & Bili & Others
Douyin --> Signer
ParseAPI --> CommonUtils
```
---
## 🔄 请求处理生命周期 (Lifecycle)
当客户端向 `/api/parse` 发送一段包含分享文案的文本时,完整处理流如下:
```mermaid
sequenceDiagram
autonumber
actor User as 客户端 (Client)
participant API as /api/parse
participant Fetcher as WebFetcher & UrlParser
participant Factory as ParserFactory
participant Parser as Platform Parser (如 DouyinParser)
participant Output as Response Formatter
User->>API: POST {"text": "7.22 复制打开抖音... https://v.douyin.com/xxx/"}
API->>Fetcher: UrlParser.get_url(text) 提取原始链接
API->>Fetcher: WebFetcher.fetch_redirect_url(url) 追踪302重定向
Fetcher-->>API: 返回落地真实URL (Real URL)
API->>Fetcher: UrlParser.get_platform(real_url) 识别平台名称
API->>Factory: ParserFactory.create_parser(platform, real_url)
Factory-->>API: 实例化对应平台解析器
API->>Parser: 执行抓取 (_fetch_with_retry)
Note over Parser: 提取标题、视频直链、图集、LivePhoto、音频等
Parser-->>API: 返回原始抓取字典 content_data
API->>Output: UrlParser.convert_to_https 统一转 HTTPS
API->>Output: make_response(200, '成功', data_dict)
Output-->>User: 返回标准 JSON 结构
```
---
## 🧩 插件化解析器设计 (ParserFactory)
为了便于扩展和多人协作,解析器采用 **装饰器自动注册 + 模块自动发现机制**:
### 1. 自动发现 (`_discover`)
[src/parser_factory.py](file:///Users/leo/Projects/media-parser/src/parser_factory.py) 会在模块载入时利用 `pkgutil.iter_modules` 自动扫描并动态 `import` `src/parsers/` 下所有除 `base_parser` 以外的 Python 模块。
### 2. 声明式注册 (`@register_parser`)
新增任何平台解析器时,**无需修改任何工厂类核心代码**,只需继承 `BaseParser` 并加上装饰器:
```python
from src.parser_factory import register_parser
from src.parsers.base_parser import BaseParser
@register_parser("示例平台", "示例平台别名")
class ExampleParser(BaseParser):
def __init__(self, real_url):
super().__init__(real_url)
# 初始化与数据提取
def get_real_video_url(self):
return "https://..."
```
---
## 📦 统一响应格式标准 (Data Contract)
所有解析接口均通过 `utils/common_utils.py` 中的 `make_response` 返回一致的 JSON 响应体。
### 成功响应示例 (`200 OK`)
```json
{
"code": 200,
"msg": "成功",
"data": {
"platform": "抖音",
"video_id": "7616399587141737704",
"title": "视频文案标题",
"video_url": "https://aweme.snssdk.com/aweme/v1/play/...",
"cover_url": "https://p3-pc.douyinpic.com/...",
"author": {
"nickname": "创作者昵称",
"author_id": "unique_id_123",
"avatar": "https://p3.douyinpic.com/..."
},
"audio_url": "https://sf6-cdn-tos.douyinstatic.com/...",
"image_list": [
{
"url": "https://p3-pc.douyinpic.com/image1.jpeg",
"live_photo_url": "https://aweme.snssdk.com/aweme/v1/play/live_photo.mp4"
}
],
"video_list": []
},
"success": true
}
```
### 错误响应示例 (`400 / 500`)
```json
{
"code": 400,
"msg": "未找到有效的分享链接",
"data": null,
"success": false,
"error_code": "URL_NOT_FOUND"
}
```
+97
View File
@@ -0,0 +1,97 @@
# Media Parser 项目技术文档与逆向百科
欢迎查阅 **Media Parser** 开发者文档与逆向工程知识库。
本项目是一个高性能、模块化、支持 **30+ 主流媒体与 AI 内容平台** 的无水印音视频、图文及 LivePhoto 结构化解析引擎。
---
## 📚 文档导航
* 🏗️ **[系统架构与生命周期 (Architecture)](architecture.md)**:了解请求处理链路、302 跳转跟踪与 ParserFactory 自动发现机制。
* 🔍 **[通用逆向方法论 (Reverse Engineering Guide)](reverse-guide.md)**:掌握 SSR 数据提取、H5 接口伪装、JS 签名沙箱及抓包 SOP。
* 🧪 **[测试与回归验证 (Testing Guide)](testing.md)**:学习 Pytest 单元测试、Mock 构造与真实样本(Live Samples)测试。
* 📖 **平台实战指南 (Parser Guides)**:
* **短视频与轻社区**:[抖音](parsers/short-video/douyin.md) | [快手](parsers/short-video/kuaishou.md) | [皮皮虾](parsers/short-video/pipixia.md) | [皮皮搞笑](parsers/short-video/pipigaoxiao.md) | [最右](parsers/short-video/zuiyou.md) | [美拍](parsers/short-video/meipai.md) | [微视](parsers/short-video/weishi.md) | [绿洲](parsers/short-video/lvzhou.md)
* **图文与综合社区**:[小红书](parsers/community/xiaohongshu.md) | [微博](parsers/community/weibo.md) | [知乎](parsers/community/zhihu.md) | [闲鱼](parsers/community/xianyu.md) | [Soul](parsers/community/soul.md)
* **长视频与弹幕/创作**:[哔哩哔哩](parsers/video-streaming/bilibili.md) | [AcFun](parsers/video-streaming/acfun.md) | [新片场](parsers/video-streaming/xinpianchang.md) | [好看视频](parsers/video-streaming/haokan.md) | [西瓜视频](parsers/video-streaming/xigua.md) | [剪映](parsers/video-streaming/jianying.md)
* **AI 生成与大模型**:[豆包 AI](parsers/ai-generation/doubao.md) | [即梦 AI](parsers/ai-generation/jimeng.md) | [可灵 AI](parsers/ai-generation/kling.md) | [通义千问](parsers/ai-generation/qianwen.md) | [夸克 AI](parsers/ai-generation/quark-ai.md) | [小云雀 AI](parsers/ai-generation/xiaoyunque.md)
* **音频与垂直频道**:[汽水音乐](parsers/audio-others/qsmusic.md) | [全民K歌](parsers/audio-others/quanminkge.md) | [虎牙](parsers/audio-others/huya.md) | [梨视频](parsers/audio-others/lishipin.md) | [微信视频号](parsers/audio-others/wechat-channels.md) | [腾讯频道](parsers/audio-others/tencent-channel.md)
---
## 📊 平台支持与测试状态矩阵
> **图例说明**:
> * ✅ **支持 / 已验证** | ⚠️ **条件依赖 (如需 Cookie)** | ❌ **不支持 / 无需配置**
| 序号 | 平台名称 | 支持媒体类型 | 无水印直链 | 需配置 Cookie | 逆向提取模式 | 对应指南 |
| :--- | :--- | :--- | :---: | :---: | :--- | :--- |
| 1 | **抖音** | 视频 / 图文 / LivePhoto / 音频 | ✅ | ❌ | a_bogus 签名 + 动态 ttwid | [查看指南](parsers/short-video/douyin.md) |
| 2 | **小红书** | 图文 / LivePhoto / 视频 | ✅ | ⚠️ 部分需 Cookie | SSR HTML 注入数据提取 | [查看指南](parsers/community/xiaohongshu.md) |
| 3 | **快手** | 视频 / 图文 / 音频 | ✅ | ❌ (已内置游客凭证) | GraphQL / H5 双端多路由 Fallback | [查看指南](parsers/short-video/kuaishou.md) |
| 4 | **哔哩哔哩** | 视频 (MP4) / 音频分流 | ✅ | ❌ | 官方 View + PlayURL API | [查看指南](parsers/video-streaming/bilibili.md) |
| 5 | **豆包 AI** | AI 视频生成直链 | ✅ | ✅ `DOUBAO_COOKIE` | Web Session 维持 + 任务轮询 | [查看指南](parsers/ai-generation/doubao.md) |
| 6 | **即梦 AI** | AI 视频生成直链 | ✅ | ❌ | 移动分享端接口解析 | [查看指南](parsers/ai-generation/jimeng.md) |
| 7 | **可灵 AI** | AI 视频生成直链 | ✅ | ❌ | 快手可灵 H5 分享接口 | [查看指南](parsers/ai-generation/kling.md) |
| 8 | **通义千问** | AI 图文 / 图像生成 | ✅ | ⚠️ `YUANBAO_COOKIE` | AI Studio 移动分享端抓取 | [查看指南](parsers/ai-generation/qianwen.md) |
| 9 | **夸克 AI** | AI 图文 / 图像 | ✅ | ❌ | 夸克 H5 分享路由解析 | [查看指南](parsers/ai-generation/quark-ai.md) |
| 10 | **小云雀 AI** | AI 图文 / 图像 | ✅ | ❌ | 剪映小云雀分享端 | [查看指南](parsers/ai-generation/xiaoyunque.md) |
| 11 | **微博** | 视频 / 微博正文 / 多图 | ✅ | ❌ | 移动端 H5 接口 + Base62 解码 | [查看指南](parsers/community/weibo.md) |
| 12 | **知乎** | 视频 (Video Pin) / 想法 / 问答 | ✅ | ❌ | Web API 多路由正则提取 | [查看指南](parsers/community/zhihu.md) |
| 13 | **皮皮虾** | 视频 / 图文 | ✅ | ❌ | H5 接口数据解析 | [查看指南](parsers/short-video/pipixia.md) |
| 14 | **皮皮搞笑** | 视频 | ✅ | ❌ | H5 页面 JSON 提取 | [查看指南](parsers/short-video/pipigaoxiao.md) |
| 15 | **最右** | 视频 / 图集 | ✅ | ❌ | H5 接口键值映射提取 | [查看指南](parsers/short-video/zuiyou.md) |
| 16 | **AcFun** | 视频 (m3u8/MP4) | ✅ | ❌ | KSPlayer 播放器参数还原 | [查看指南](parsers/video-streaming/acfun.md) |
| 17 | **汽水音乐** | UGC 视频 / 背景原声 | ✅ | ❌ | 字节系分享 API | [查看指南](parsers/audio-others/qsmusic.md) |
| 18 | **全民K歌** | 视频 / 伴奏音频 | ✅ | ❌ | H5 播放页正则提取 | [查看指南](parsers/audio-others/quanminkge.md) |
| 19 | **虎牙** | 视频 / 录播 | ✅ | ❌ | 移动端短链解析 | [查看指南](parsers/audio-others/huya.md) |
| 20 | **微信视频号** | 视频 | ✅ | ❌ | 视频号短链解析 | [查看指南](parsers/audio-others/wechat-channels.md) |
| 21 | **腾讯视频/频道** | 视频 | ✅ | ❌ | 企鹅频道分享解析 | [查看指南](parsers/audio-others/tencent-channel.md) |
| 22 | **西瓜视频** | 视频 | ✅ | ❌ | 字节系引擎继承解析 | [查看指南](parsers/video-streaming/xigua.md) |
| 23 | **新片场** | 高清视频 | ✅ | ❌ | Next.js SSR 播放页提取 | [查看指南](parsers/video-streaming/xinpianchang.md) |
| 24 | **好看视频** | 百度短视频 | ✅ | ❌ | 百度视频落地页提取 | [查看指南](parsers/video-streaming/haokan.md) |
| 25 | **美拍** | 视频 | ✅ | ❌ | 网页 MP4 流还原 | [查看指南](parsers/short-video/meipai.md) |
| 26 | **微视** | 腾讯微视视频 | ✅ | ❌ | 微视开放接口 | [查看指南](parsers/short-video/weishi.md) |
| 27 | **绿洲** | 新浪绿洲图文 | ✅ | ❌ | 微博绿洲 H5 提取 | [查看指南](parsers/short-video/lvzhou.md) |
| 28 | **闲鱼** | 闲鱼图文贴 | ✅ | ❌ | 淘系分享页解析 | [查看指南](parsers/community/xianyu.md) |
| 29 | **Soul** | 视频 / 瞬间 | ✅ | ❌ | Web 话题页解析 | [查看指南](parsers/community/soul.md) |
| 30 | **剪映** | 剪映模板视频 | ✅ | ❌ | 字节剪映 API | [查看指南](parsers/video-streaming/jianying.md) |
| 31 | **梨视频** | 资讯短视频 | ✅ | ❌ | 动态防盗链时间戳解密 | [查看指南](parsers/audio-others/lishipin.md) |
---
## ⚡ 快速开始
### 1. 安装依赖
```bash
# 建议使用 Python 3.10+
pip install -r requirements.txt
```
### 2. 环境变量配置 (可选)
复制 `.env.example` 为 `.env`:
```bash
cp .env.example .env
```
如需解析受限的小红书笔记或大模型 AI 平台(如豆包),在 `.env` 中填入对应 Cookie:
```env
DOUBAO_COOKIE="your_doubao_cookie_here"
YUANBAO_COOKIE="your_yuanbao_cookie_here"
```
### 3. 运行服务
```bash
# 开发环境启动 (端口 8051)
python app.py
# 访问 Web 演示前台:http://127.0.0.1:8051/
# 测试健康检查:http://127.0.0.1:8051/api/health
```
---
## ⚖️ 免责声明 (Disclaimer)
本项目所有代码和文档仅用于**网络技术研究、接口逆向工程学习与防御性安全交流**。
使用者请遵守各目标平台的《用户服务协议》与相关法律法规,不得用于任何形式的商业盈利抓取或恶意攻击行为。因使用本工具造成的任何直接或间接法律责任由使用者自行承担。
+105
View File
@@ -0,0 +1,105 @@
# 豆包 AI (Doubao) 逆向解析指南
本篇详细记录字节跳动旗下**豆包 AI** 对话分享(Thread)与独立视频生成分享(Video Sharing)的逆向解析方案、FPLAY 播放凭证解密与 Cookie 鉴权机制。
---
## 1. 平台特征与支持能力
* **平台标识**:`豆包`
* **支持媒体类型**:
* AI 生成 1080P 高清无水印视频 (MP4)
* AI 生成图文 / 提示词生图 (PNG/JPEG)
* 对话标题、Prompt 提示词与创作者信息
* **常见链接形态**:
* 独立视频分享:`https://www.doubao.com/video-sharing?share_id=41356597786354690&video_id=v0d69cg10004d6978e2ljht0i4fdpp00`
* 对话历史/线程分享:`https://www.doubao.com/thread/w8293749281`
* **Cookie 依赖**:
* **图片解析**:**无需 Cookie**(公开元数据直接包含 `image_ori_raw` 高清原图)。
* **视频无水印解析**:**必须配置 Cookie**(1080P 原始流被权限隔离,未登录仅能获取服务端硬压制水印的预览切片)。
---
## 2. 核心逆向流程
[DoubaoParser](file:///Users/leo/Projects/media-parser/src/parsers/doubao_parser.py) 内部实现了双分支解析引擎与优雅降级策略:
```mermaid
flowchart TD
Start["输入豆包分享 URL"] --> Route{"判断 URL 路径"}
Route -->|"/thread/xxx"| ThreadFlow["1. 会话线程解析 (_parse_thread)"]
Route -->|"/video-sharing"| VideoFlow["2. 独立视频解析 (_parse_video_sharing)"]
ThreadFlow --> ScriptPayload["提取 HTML 中 script 注入的 JSON 负载"]
ScriptPayload --> Creations["递归遍历提取 creation 实体 (视频/图像)"]
VideoFlow --> AuthCheck{"是否配置了 DOUBAO_COOKIE?"}
AuthCheck -->|已配置| SamanthaAPI["调用 /samantha/media/get_play_info"]
SamanthaAPI --> AES["执行 FPLAY KDF 盐值派生 + AES-128-CBC 解密"]
AES --> HDVideo["获得 1080P 纯净无水印原画视频 (3960kbps)"]
AuthCheck -->|未配置 (降级)| ShareAPI["调用 /creativity/share/get_video_share_info"]
ShareAPI --> StripParam["清理 URL 水印参数 (降级为带水印预览切片)"]
```
---
## 3. 核心 API 与加密解密技术细节
### 3.1 核心 API 汇总
* **无水印高清媒体接口 (需鉴权)**:
`POST https://www.doubao.com/samantha/media/get_play_info`
* **公开视频分享接口 (未登录降级用)**:
`POST https://www.doubao.com/creativity/share/get_video_share_info`
* **模型资源接口**:
`POST https://www.doubao.com/alice/resource/get_video_model`
### 3.2 FPLAY 播放流密钥派生 (KDF & AES 解密)
豆包的高清无水印视频源采用了字节跳动 **FPLAY 自定义加密流**。解析器内置了基于固定盐值的密钥派生与 AES-128-CBC 解密算法:
* **KDF Salt 盐值**:
`TdTC5rgxYgkOUrPHpnM7pByyRiuCmrWKGWs521cXdST0m69/COjWjSanLjfBqVovHwWlGJKu8pSXMrYqOKrdWA==`
* **解密逻辑**:
1. 通过 SHA256 与 Salt 派生出 AES Key 与 IV;
2. 利用 `Crypto.Cipher.AES` 对 `get_play_info` 下发的密文字符串进行解密并去除 PKCS7 Padding;
3. 解密后即可还原出官方原始 1080P MP4 直链(经验证,文件 MD5 与平台原始生成视频完全一致)。
---
## 4. 经典踩坑与逆向攻防复盘 (Case Study: Issue #14)
### 踩坑 1:URL 参数去水印的“假象”
* **初始误区**:在公开分享接口中,视频 URL 带有 `lr=video_gen_watermark_dyn`、`logo_type` 等参数。直觉上容易认为只要清洗掉这些 URL Query 参数就能去水印。
* **攻防真相**:豆包服务端对于未登录/公开状态的请求,**在服务器端转码切片时就已经将水印物理硬编码压制进了视频画面**。清洗 URL 参数无法改变视频底层的像素内容。
* **最终解法**:必须通过 `samantha/media/get_play_info` 鉴权接口提取 `original_media_info.main_url` 并完成 FPLAY 解密。
### 踩坑 2:图文与视频的鉴权隔离差异
* **图片无水印**:豆包在公开分享 HTML 中直接完整下发了 `image_ori_raw` 与 `image_ori` 原图直链,无需任何登录态即可提取无水印原图。
* **视频强鉴权**:未登录请求 `get_play_info` 会直接报 `login invalid`,因此视频无水印必须依赖登录态。
---
## 5. Cookie 配置最小指南
为避免用户复制过长且包含无关追踪标记的 Cookie,豆包仅需提取关键的身份凭据即可:
1. 打开浏览器访问 [豆包网页版](https://www.doubao.com/) 并登录。
2. 按 `F12` 打开开发者工具,在 **Application (应用程序) ➔ Cookies** 中找到核心认证字段:`sessionid_ss`。
3. 在项目根目录的 `.env` 文件中配置(两者格式均支持):
```env
# 精简格式 (推荐)
DOUBAO_COOKIE="sessionid_ss=你的sessionid_ss值"
# 或者完整 Cookie 字符串
DOUBAO_COOKIE="sessionid_ss=xxx; passport_csrf_token=yyy; ..."
```
---
## 6. 测试与验证
* **单元测试**:[tests/test_doubao_parser.py](file:///Users/leo/Projects/media-parser/tests/test_doubao_parser.py)
* **执行测试**:
```bash
pytest tests/test_doubao_parser.py
python tests/manual_verify_parsers.py --platform 豆包
```
+82
View File
@@ -0,0 +1,82 @@
# 即梦 AI (Jimeng) 逆向解析指南
本篇详细记录字节跳动剪映旗下 **即梦 AI (jimeng.jianying.com)** 视频与图像生成的解析方案及接口细节。
---
## 1. 平台特征与支持能力
* **平台标识**:`即梦AI`
* **支持媒体类型**:
* AI 生成高清视频 (MP4)
* AI 生成图集 (PNG/JPEG)
* 提示词文案 (Prompt) 与创作者昵称/头像
* **常见链接形态**:
* 分享短链:`https://jimeng.jianying.com/s/rdloCrYi2wc/?t=8011`
* 移动详情长链:`https://jimeng.jianying.com/ai-tool/share/item/7631885529415568665`
* **Cookie 依赖**:公开分享链接**无需配置 Cookie**。
---
## 2. 核心逆向流程
```mermaid
sequenceDiagram
autonumber
participant Parser as JimengParser
participant H5 as 即梦短链服务
participant API as mweb/v1/get_item_info
Parser->>H5: 请求短链接 (跟踪 302 重定向)
H5-->>Parser: 获取包含 item_id 的最终长链接
Parser->>Parser: 正则提取 item_id / share_id
Parser->>API: POST {"item_id": "xxx"}
API-->>Parser: 返回包含 video_model / image_list 的作品 JSON
Parser->>Parser: 提取无水印 MP4 直链与封面
```
### 2.1 核心请求定义
* **接口地址**:
`POST https://jimeng.jianying.com/mweb/v1/get_item_info`
* **请求头**:
```python
headers = {
"Accept": "application/json, text/plain, */*",
"Content-Type": "application/json",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
}
```
* **Payload 载荷**:
```json
{
"item_id": "7631885529415568665"
}
```
---
## 3. 字段提取规则
* **视频直链**:从 `item_info.video.play_addr.url_list[0]` 或 `item_info.video_model.video_list[0].main_url` 获取。
* **生图图集**:从 `item_info.image_list` 提取高清渲染图。
* **Prompt 标题**:从 `item_info.title` 或 `item_info.prompt` 中提取。
---
## 4. 常见踩坑与注意事项
1. **短链参数丢失**:
* 即梦短链(`/s/xxxx`)必须先发起一次带 `allow_redirects=True` 的 GET 请求,从重定向后的真实 URL 查询参数或路径中提取真正的 `item_id`。
2. **多清晰度选择**:
* 接口返回的 `video_list` 可能包含预览低清流和渲染高清流,代码中已内置按分辨率倒序优先挑选最高清直链。
---
## 5. 测试与验证
* **单元测试**:[tests/test_jimeng_parser.py](file:///Users/leo/Projects/media-parser/tests/test_jimeng_parser.py)
* **执行测试**:
```bash
pytest tests/test_jimeng_parser.py
python tests/manual_verify_parsers.py --platform 即梦AI
```
+67
View File
@@ -0,0 +1,67 @@
# 快手可灵 AI (Kling) 逆向解析指南
本篇详细记录快手旗下大模型 **可灵 AI (Kling AI)** 视频与创意作品分享的接口抓取机制与参数解析。
---
## 1. 平台特征与支持能力
* **平台标识**:`可灵AI`
* **支持媒体类型**:
* AI 生成高清视频 (MP4)
* 视频生成封面与 Prompt 描述
* 创作者昵称与作品 ID
* **常见链接形态**:
* 分享落地页:`https://klingai-share.kuaishou.com/h5-app/share?work_id=305387532165182&creative_id=305387532165182&creative_type=WORK`
* **Cookie 依赖**:无需 Cookie,支持公开查询。
---
## 2. 核心逆向流程
### 2.1 创意作品参数提取 (`_extract_creative`)
从传入链接的 Query String 中提取两个核心参数:
* `creative_id` (或 `work_id`):作品唯一数字编号。
* `creative_type`:作品类型(默认为 `WORK`)。
### 2.2 核心查询接口
* **接口地址**:
`GET https://klingai-share.kuaishou.com/app/creatives/query`
* **Query 参数**:
* `creativeId={creative_id}`
* `creativeType={creative_type}`
* **必备请求头**:
* `User-Agent`:移动端 UA (如 iPhone Safari)
* `Referer`:`https://klingai-share.kuaishou.com/`
---
## 3. 数据提取规则
在返回的 JSON 数据中:
* **视频无水印直链**:
位于 `data.playUrl` 或 `data.works[0].resource.url`。
* **封面图**:
位于 `data.coverUrl` 或 `data.works[0].resource.coverUrl`。
* **Prompt 标题**:
位于 `data.prompt` 或 `data.title`。
---
## 4. 常见踩坑记录 (Gotchas)
1. **Query 字段命名多变**:
* 部分版本分享出来的参数为 `work_id`,新版本为 `creative_id`。代码中采用 fallback 容错兼容逻辑。
2. **纯纯数字 ID 兼容**:
* 解析器支持直接传入数字 ID 字符串,自动识别为 `creative_id` 并构造请求。
---
## 5. 测试与验证
* **单元测试**:[tests/test_kling_parser.py](file:///Users/leo/Projects/media-parser/tests/test_kling_parser.py)
* **执行测试**:
```bash
pytest tests/test_kling_parser.py
python tests/manual_verify_parsers.py --platform 可灵AI
```
+71
View File
@@ -0,0 +1,71 @@
# 通义千问 (Qwen) 逆向解析指南
本篇详细记录阿里巴巴 **通义千问 (Qwen)** AI Studio 及移动分享作品的 `__INITIAL_PROPS__` SSR 数据提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`通义千问`
* **支持媒体类型**:
* AI 创作图集 / 扩图 / 文生图 (PNG/JPEG)
* AI 生成视频 (MP4)
* 提示词 Prompt、标题与作者信息
* **常见链接形态**:
* 移动分享长链:`https://activity.qianwen.com/r/ai-studio-mobile/qwen-external-share?shareId=ZeeOedXncnGlElkluRMA&authorId=OjTAcGHgZgye...`
* **Cookie 依赖**:公开外部分享**无需 Cookie**。
---
## 2. 核心逆向方案:`__INITIAL_PROPS__` 提取与反序列化
通义千问的分享落地页使用 React SSR,所有作品和图片 CDN 地址均直接挂载在 `window.__INITIAL_PROPS__` 全局脚本变量中。
### 2.1 提取与双重 URL 解码流程
```python
# 1. 定位 script 中的 window.__INITIAL_PROPS__
marker = "window.__INITIAL_PROPS__"
pos = html_text.find(marker)
sub = html_text[pos + len(marker):].lstrip(" =")
sub = sub[:sub.find("</script>")].rstrip().rstrip(";")
# 2. 解析 JSON
data = json.loads(sub)
raw_initial = data.get("initialData", {})
# 3. 处理 URL 编码与嵌套 JSON
if isinstance(raw_initial, str) and raw_initial.startswith("%"):
raw_initial = urllib.parse.unquote(raw_initial)
raw_initial = json.loads(raw_initial)
```
---
## 3. 字段提取规则
* **生成图像列表**:
* 从 `initial_data.images` 或 `initial_data.resultList` 遍历提取 CDN 高清图片地址。
* **生图 Prompt**:
* 提取 `initial_data.prompt` 或 `initial_data.title`。
* **作者信息**:
* 提取 `initial_data.author` 对象的昵称与头像。
---
## 4. 常见踩坑记录 (Gotchas)
1. **`initialData` 双重编码**:
* 某些版本的前端模板将 `initialData` 先做了 `encodeURIComponent`,因此在 `json.loads` 之前必须进行 `urllib.parse.unquote`,否则直接反序列化会报错。
2. **图文与视频多态结构**:
* 部分 AI 助手生成的是短视频,部分是 4 宫格图集,解析器中通过类型自适应兼容两种结构。
---
## 5. 测试与验证
* **单元测试**:[tests/test_qianwen_parser.py](file:///Users/leo/Projects/media-parser/tests/test_qianwen_parser.py)
* **执行测试**:
```bash
pytest tests/test_qianwen_parser.py
python tests/manual_verify_parsers.py --platform 通义千问
```
+43
View File
@@ -0,0 +1,43 @@
# 夸克 AI (Quark AI) 逆向解析指南
本篇详细记录阿里巴巴旗下 **夸克 AI (Quark AI)** 分享作品的解析方案与复用继承架构。
---
## 1. 平台特征与支持能力
* **平台标识**:`夸克AI`
* **支持媒体类型**:
* AI 创作图集 (PNG/JPEG)
* AI 生成内容与提示词
* **常见链接形态**:
* 分享落地页:`https://act.quark.cn/apps/sharepages/routes/share?biz_id=ai_chat_v2&share_id=3aeb87e5f7214ecbb54881903cd02a23`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 架构设计:底层复用与平台隔离
阿里巴巴旗下夸克 AI 的分享页面底层与通义千问(Qwen)共享相同的 **AI Studio** 基础设施与前端渲染协议(均采用 `window.__INITIAL_PROPS__` 注入方式)。
为了减少重复代码并维持整洁的代码库,[QuarkAIParser](file:///Users/leo/Projects/media-parser/src/parsers/quark_ai_parser.py) 采用了 **继承复用** 模式:
```python
from src.parser_factory import register_parser
from src.parsers.qianwen_parser import QianwenParser
@register_parser("夸克AI")
class QuarkAIParser(QianwenParser):
"""夸克 AI 与通义千问分享页使用相同的数据结构,完全复用核心解析逻辑。"""
```
---
## 3. 测试与验证
* **单元测试**:[tests/test_quark_ai_parser.py](file:///Users/leo/Projects/media-parser/tests/test_quark_ai_parser.py)
* **执行测试**:
```bash
pytest tests/test_quark_ai_parser.py
python tests/manual_verify_parsers.py --platform 夸克AI
```
+42
View File
@@ -0,0 +1,42 @@
# 小云雀 AI (Xiaoyunque) 逆向解析指南
本篇详细记录字节跳动剪映旗下 **小云雀 AI (xiaoyunque.jianying.com)** 分享作品的接口抓取机制与参数解析。
---
## 1. 平台特征与支持能力
* **平台标识**:`小云雀AI`
* **支持媒体类型**:
* AI 创作图集 (PNG/JPEG)
* 提示词 Prompt、封面与作者信息
* **常见链接形态**:
* 分享短链:`https://xiaoyunque.jianying.com/s/z_7nWGLGruM/`
* **Cookie 依赖**:公开短链**无需配置 Cookie**。
---
## 2. 核心逆向流程
### 2.1 短链解析与落地页跳转
通过发起 GET 请求跟踪 302 跳转,从小云雀长链接中提取 Query 参数字典 `qdict`。
### 2.2 核心数据接口
* **接口地址**:
`GET/POST https://xiaoyunque.jianying.com/luckycat/cn/jianying/campaign/v1/pippit/share/landing_page`
* **请求头**:
* `User-Agent`: 现代浏览器 UA
* `Accept`: `application/json, text/plain, */*`
* **提取数据**:
* 从返回的 `data.item_info` 或 `data.share_info` 中提取高清图集 URL 与封面。
---
## 3. 测试与验证
* **单元测试**:[tests/test_xiaoyunque_parser.py](file:///Users/leo/Projects/media-parser/tests/test_xiaoyunque_parser.py)
* **执行测试**:
```bash
pytest tests/test_xiaoyunque_parser.py
python tests/manual_verify_parsers.py --platform 小云雀AI
```
+28
View File
@@ -0,0 +1,28 @@
# 虎牙 (Huya) 逆向解析指南
本篇详细记录 **虎牙直播 / 虎牙短视频** 录播与视频切片的抓取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`虎牙`
* **支持媒体类型**:高清视频 (MP4/HLS) / 封面图 / 视频标题
* **常见链接形态**:
* 短链接:`https://hy.fan/v3cwMK`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **302 跳转提取视频 ID**:跟随短链跳转至虎牙视频真实落地页。
2. **提取视频播放流**:
* 从落地页 HTML 中提取 `<video>` 源或调用虎牙短视频接口获取 MP4 直链。
---
## 3. 测试与验证
* **单元测试**:[tests/test_huya_parser.py](file:///Users/leo/Projects/media-parser/tests/test_huya_parser.py)
* **执行命令**:`pytest tests/test_huya_parser.py`
+30
View File
@@ -0,0 +1,30 @@
# 梨视频 (PearVideo) 逆向解析指南
本篇详细记录 **梨视频** 资讯短视频与动态防盗链时间戳解密方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`梨视频`
* **支持媒体类型**:高清资讯视频 (MP4) / 封面图 / 视频标题与作者
* **常见链接形态**:
* 网页链接:`https://www.pearvideo.com/video_1805408`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取 Video ID**:从 URL 中提取数字 ID(如 `1805408`)。
2. **防盗链 API 请求**:
* 接口:`GET https://www.pearvideo.com/videoStatus.jsp?contId={video_id}`
* 必备 Header:`Referer: https://www.pearvideo.com/video_{video_id}`
3. **动态 URL 拼接替换**:
* 接口返回伪装的 `srcUrl`,需根据系统时间戳将 URL 中的临时 hash 替换为 `cont-{video_id}` 即可还原真实可播放的 MP4 地址。
---
## 3. 测试与验证
* **样本验证**:`python tests/manual_verify_parsers.py --platform 梨视频`
+31
View File
@@ -0,0 +1,31 @@
# 汽水音乐 (Qishui Music) 逆向解析指南
本篇详细记录字节跳动旗下 **汽水音乐** UGC 视频与背景原声音频的提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`汽水音乐`
* **支持媒体类型**:高清 UGC 视频 (MP4) / 歌曲完整音频 (MP3) / 专辑封面 / 歌曲名称与作者
* **常见链接形态**:
* 分享短链:`https://qishui.douyin.com/s/iX21ep91/`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **302 跳转获取真实 Item ID**:跟随短链跳转至 `qishui.douyin.com/track/...` 或 `video/...`。
2. **字节系音乐接口调用**:
* 请求汽水音乐 Web 端曲目详情接口。
3. **媒体分离提取**:
* `audio_url`:提取无损或高码率音频直链;
* `video_url`:提取 UGC 伴随视频直链。
---
## 3. 测试与验证
* **单元测试**:[tests/test_qsmusic_parser.py](file:///Users/leo/Projects/media-parser/tests/test_qsmusic_parser.py)
* **执行命令**:`pytest tests/test_qsmusic_parser.py`
+31
View File
@@ -0,0 +1,31 @@
# 全民K歌 (Quanmin K-Song) 逆向解析指南
本篇详细记录腾讯旗下 **全民K歌** K歌录音、MV 视频及伴奏音频的提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`全民K歌`
* **支持媒体类型**:K歌 MV 视频 (MP4) / 录音音频 (M4A/MP3) / 歌曲封面与演唱者
* **常见链接形态**:
* 播放页:`https://static-play.kg.qq.com/node/on3NDg1SU2/play_v2?s=rv8cHFpUTXw32p0l`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取歌曲 ShareID (`s`)**:从 Query 中提取 `s` 参数。
2. **H5 落地页内嵌数据解析**:
* 请求 `play_v2` 页面,正则提取 `window.__DATA__`。
3. **提取音视频直链**:
* 从 `playurl_video` 提取高清 MV 视频;
* 从 `playurl` 提取纯音频录音。
---
## 3. 测试与验证
* **单元测试**:[tests/test_quanminkge_parser.py](file:///Users/leo/Projects/media-parser/tests/test_quanminkge_parser.py)
* **执行命令**:`pytest tests/test_quanminkge_parser.py`
@@ -0,0 +1,28 @@
# 腾讯频道 / 腾讯视频 (Tencent Channel) 逆向解析指南
本篇详细记录 **腾讯频道 / 腾讯视频** 分享视频的解析方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`腾讯频道` / `腾讯视频`
* **支持媒体类型**:高清视频 (MP4) / 封面图 / 视频标题与作者
* **常见链接形态**:
* 频道分享:`https://pd.qq.com/s/9df0az124?b=2`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **302 跟随跳转与参数提取**:请求短链解析频道或视频的唯一 Key。
2. **企鹅开放接口与元数据提取**:
* 调用企鹅开放平台接口,解析高清 MP4 视频直链及封面。
---
## 3. 测试与验证
* **单元测试**:[tests/test_tencent_channel_parser.py](file:///Users/leo/Projects/media-parser/tests/test_tencent_channel_parser.py)
* **执行命令**:`pytest tests/test_tencent_channel_parser.py`
@@ -0,0 +1,28 @@
# 微信视频号 (WeChat Channels) 逆向解析指南
本篇详细记录 **微信视频号** 分享短链的解析方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`视频号` / `微信视频号`
* **支持媒体类型**:无水印短视频 (MP4) / 封面图 / 创作者昵称
* **常见链接形态**:
* 视频号短链:`https://weixin.qq.com/sph/AzGrUgqzFv`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **302 跟随跳转**:请求视频号短链获取落地页。
2. **提取视频流与作者信息**:
* 从 H5 落地页 HTML 或元数据中解析高清 MP4 播放地址与封面。
---
## 3. 测试与验证
* **单元测试**:[tests/test_wechat_channels_parser.py](file:///Users/leo/Projects/media-parser/tests/test_wechat_channels_parser.py)
* **执行命令**:`pytest tests/test_wechat_channels_parser.py`
+32
View File
@@ -0,0 +1,32 @@
# Soul 逆向解析指南
本篇详细记录 **Soul App** 瞬间、话题与广场短视频/图文的接口解析方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`Soul`
* **支持媒体类型**:无水印视频 (MP4) / 瞬间高清图集 / 音频瞬间 / 正文与作者
* **常见链接形态**:
* 话题分享:`https://w13.soulsmile.cn/activity/#/web/topic/detail?postIdEcpt=djB4RGY...`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取加密帖子标识 (`postIdEcpt`)**:从分享 URL 的 Query 中提取 `postIdEcpt` 及签名版本。
2. **Web 话题详情接口**:
* 接口:`https://api-h5.soulapp.cn/html6/v2/post/detail`
* 参数:`postIdEcpt={postIdEcpt}`
3. **数据提取**:
* 视频:提取 `data.attachments[].video.url` 或 `data.videoUrl`。
* 图集:提取 `data.attachments[].image.url`。
---
## 3. 测试与验证
* **单元测试**:[tests/test_soul_parser.py](file:///Users/leo/Projects/media-parser/tests/test_soul_parser.py)
* **执行命令**:`pytest tests/test_soul_parser.py`
+39
View File
@@ -0,0 +1,39 @@
# 微博 (Weibo) 逆向解析指南
本篇详细记录新浪微博长微博图集、博文视频(包含 `1034:xxx` 视频流)的逆向提取与 Base62 ID 转换算法。
---
## 1. 平台特征与支持能力
* **平台标识**:`微博`
* **支持媒体类型**:
* 微博无水印短视频 (MP4)
* 多图与高清 Live 图集 (JPEG/PNG)
* 微博正文内容与博主信息
* **常见链接形态**:
* 视频页:`https://video.weibo.com/show?fid=1034:5336219874426938`
* 网页长链:`https://weibo.com/1234567890/Mabcdef`
* **Cookie 依赖**:无需登录 Cookie。
---
## 2. 核心算法与逆向流程
### 2.1 微博 Base62 转换算法 (`mid_to_id`)
微博长链中的字符串 ID(如 `Mabcdef`)为 Base62 编码。在请求数据前,解析器通过 `base62_decode` 将其还原为数据库中的真实纯数字 `id`。
### 2.2 视频流与图文分支提取
* **分支 1 (视频专页 `fid=1034:xxx`)**:
* 接口:`https://weibo.com/tv/api/component/page`
* 直接提取 1080P/720P 高清播放流。
* **分支 2 (标准微博动态 `statuses/show`)**:
* 从 `page_info.media_info.playback_list` 获取不同分辨率的 MP4 直链;
* 从 `pic_infos` 遍历提取 `large` 或 `original` 档位高清原图。
---
## 3. 测试与验证
* **单元测试**:[tests/test_weibo_parser.py](file:///Users/leo/Projects/media-parser/tests/test_weibo_parser.py)
* **执行命令**:`pytest tests/test_weibo_parser.py`
+30
View File
@@ -0,0 +1,30 @@
# 闲鱼 (Xianyu) 逆向解析指南
本篇详细记录阿里巴巴旗下 **闲鱼** 二手商品与帖子图文的解析方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`闲鱼`
* **支持媒体类型**:商品高清大图 (JPEG/PNG) / 宝贝标题与描述
* **常见链接形态**:
* 口令/短链:`https://e.tb.cn/h.87fj9SNrqHW8kfC?tk=y1E5Tb4wkGd`
* 商品长链:`https://2.taobao.com/item.htm?id=123456789`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **302 跳转获取真实 itemId**:请求淘口令或短链,从最终 Location 或 HTML 中解析商品 `id`。
2. **移动端 H5 状态提取**:
* 请求闲鱼 H5 详情页。
* 解析 HTML 中注入的商品元数据与相册大图列表,去除缩略图裁剪参数以获取原图。
---
## 3. 测试与验证
* **单元测试**:[tests/test_xianyu_parser.py](file:///Users/leo/Projects/media-parser/tests/test_xianyu_parser.py)
* **执行命令**:`pytest tests/test_xianyu_parser.py`
+76
View File
@@ -0,0 +1,76 @@
# 小红书 (Xiaohongshu) 逆向解析指南
本篇详细记录小红书平台图文笔记、视频笔记与 LivePhoto 的完整逆向提取方案及反爬对抗经验。
---
## 1. 平台特征与支持能力
* **平台标识**:`小红书`
* **支持媒体类型**:
* 高清图文图集 (无水印 WebP/JPEG)
* 实况照片 (LivePhoto 动态视频流)
* 视频笔记 (H264 Master MP4 流)
* 笔记正文与作者信息
* **常见链接形态**:
* 短链接:`http://xhslink.com/a/xxxx`
* 网页发现长链:`https://www.xiaohongshu.com/discovery/item/6a8fbccc000000002a03825a`
* 网页探索长链:`https://www.xiaohongshu.com/explore/6a8fbccc000000002a03825a`
* **Cookie 依赖**:公开普通笔记无需 Cookie;部分强受限笔记或高频调用建议在 `.env` 中提供 Cookie。
---
## 2. 核心逆向方案 (SSR HTML 状态注入)
小红书 Web 页面采用 Nuxt / Vue SSR 服务端渲染。页面加载时,首屏所有笔记详情、高清媒体流及作者信息均已经内嵌在 HTML 的 `window.__INITIAL_STATE__` 变量中。
### 2.1 请求配置
* **请求方式**:`GET` 目标长链接
* **必备请求头**:
* `User-Agent`: 现代 PC 浏览器 UA
* `Referer`: `https://www.xiaohongshu.com/`
### 2.2 正则状态提取
```python
import re, json
pattern = re.compile(r'window\.__INITIAL_STATE__\s*=\s*(\{.*\})', re.DOTALL)
json_str = BaseParser.parse_html_data(html_content, pattern)
if json_str:
full_data = json.loads(json_str)
first_note_id = full_data.get('note', {}).get('firstNoteId')
note_data = full_data['note']['noteDetailMap'].get(first_note_id, {}).get('note', {})
```
---
## 3. 字段提取与 LivePhoto 解析
### 3.1 视频笔记提取
* 视频直链位于:`note_data.video.media.stream.h264[0].masterUrl`
* 字符转义处理:将 Unicode 斜杠 `\\u002F` 替换为标准 `/`。
### 3.2 图文与 LivePhoto 提取
* 遍历 `note_data.imageList`:
* **原图直链**:提取 `urlDefault` 字段。
* **实况动图 (LivePhoto)**:检查 `image.get('livePhoto') == True`,若为真,则提取 `image.stream.h264[0].masterUrl` 作为实况动图关联的视频流。
---
## 4. 常见踩坑与反爬对抗 (Gotchas)
1. **重定向至登录页 (`/login`) 或 404**:
* *原因*:小红书对单一 IP 频次较高的请求,或者未带参数的特定私密笔记会强制要求登录。
* *解法*:在 [src/api/parse.py](file:///Users/leo/Projects/media-parser/src/api/parse.py) 中针对小红书内置了 3 次自适应重试机制(`_fetch_with_retry`);若持续失败,则友好提示用户配置 Cookie。
2. **字符转义问题**:
* JSON 字符串中经常包含 JSON 编码的斜杠 `\u002F`,必须统一格式化清洗。
---
## 5. 测试与验证
* **真实样本验证**:
```bash
python tests/manual_verify_parsers.py --platform 小红书
```
+40
View File
@@ -0,0 +1,40 @@
# 知乎 (Zhihu) 逆向解析指南
本篇详细记录知乎问答(Answer)、专栏文章(Article)、视频(Zvideo)与想法(Pin / Video Pin)的多形态解析方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`知乎`
* **支持媒体类型**:
* 知乎视频 (MP4) 与 Video Pin
* 专栏文章 / 想法图集
* 问答回答正文与作者信息
* **常见链接形态**:
* 想法:`https://www.zhihu.com/pin/2066168388699807826`
* 视频:`https://www.zhihu.com/zvideo/12345678`
* 问答:`https://www.zhihu.com/question/123/answer/456`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
### 2.1 多形态路由分发 (`_extract_content_id`)
通过正则表达式自动识别链接类型:
* `answer` ➔ `api.zhihu.com/answers/{id}`
* `zvideo` ➔ `api.zhihu.com/videos/{id}`
* `pin` ➔ `api.zhihu.com/pins/{id}`
* `article` ➔ `api.zhihu.com/articles/{id}`
### 2.2 媒体提取规则
* **视频提取**:从 `attachment.video` 或 `video_info` 中解析清晰度播放列表 `playlist`,优先挑选 `HD` / `SD` 直链。
* **图文提取**:从正文 HTML 中通过 BeautifulSoup 提取 `<img>` 标签的 `data-original` 或 `data-actualsrc` 原图。
---
## 3. 测试与验证
* **单元测试**:[tests/test_zhihu_parser.py](file:///Users/leo/Projects/media-parser/tests/test_zhihu_parser.py)
* **执行命令**:`pytest tests/test_zhihu_parser.py`
+101
View File
@@ -0,0 +1,101 @@
# 抖音 (Douyin) 逆向解析指南
本篇详细记录抖音平台短视频、图文笔记与 LivePhoto 的完整逆向提取方案、签名机制及踩坑经验。
---
## 1. 平台特征与支持能力
* **平台标识**:`抖音`
* **支持媒体类型**:
* 无水印高清视频 (MP4)
* 高清图文图集 (JPEG/PNG)
* 动态实况照片 (LivePhoto 动态视频流)
* 背景音乐原声 (Audio MP3)
* **常见链接形态**:
* 短链接:`https://v.douyin.com/Nid-fFF_sdI/`
* 网页端视频长链:`https://www.douyin.com/video/7616399587141737704`
* 网页端图文长链:`https://www.douyin.com/note/7616399587141737704`
* **Cookie 依赖**:无需用户登录 Cookie,系统内置**动态 TTWID 游客凭证注册与缓存**。
---
## 2. 链路追踪与 ID 提取
1. **302 重定向**:通过 `WebFetcher.fetch_redirect_url` 跟随短链 302 跳转至标准长链接。
2. **ID 提取**:使用 `UrlParser.get_video_id` 匹配数字 ID(`aweme_id`)。
---
## 3. 核心逆向方案 (Web API + a_bogus 签名)
### 3.1 核心请求定义
* **接口地址**:
```text
https://www.douyin.com/aweme/v1/web/aweme/detail/?device_platform=webapp&aid=6383&channel=channel_pc_web&aweme_id={aweme_id}&msToken={ms_token}&a_bogus={a_bogus}
```
* **必备请求头**:
* `User-Agent`:必须与签名计算时传入的 UA 保持严格一致(见 [BogusSigner](file:///Users/leo/Projects/media-parser/utils/signer/bytedance/bogus_signer.py))。
* `Referer`:`https://www.douyin.com/video/{aweme_id}?previous_page=web_code_link`
* `Cookie`:`ttwid={ttwid}`
### 3.2 动态 TTWID 获取机制
抖音 Web 端详情接口要求必须携带有效的 `ttwid`。我们在 [DouyinParser](file:///Users/leo/Projects/media-parser/src/parsers/douyin_parser.py) 中实现了自动注册与类级别内存缓存:
```python
# 向字节注册接口发送请求获取合法游客凭证
url = "https://ttwid.bytedance.com/ttwid/union/register/"
data = {
"region": "cn",
"aid": 6383,
"need_t": 1,
"service": "www.douyin.com",
"domain": ".douyin.com"
}
resp = session.post(url, json=data)
ttwid = resp.cookies.get('ttwid')
```
### 3.3 签名计算 (a_bogus)
通过 `py_mini_racer` 在 Google V8 引擎中执行提取的前端混淆脚本,计算 `a_bogus` 防篡改签名:
```python
from utils.signer.bytedance.bogus_signer import BogusSigner
signer = BogusSigner()
abogus = signer.get_abogus(play_url, signer.user_agent)
```
---
## 4. 字段提取与去水印规则
### 4.1 视频提取 (无水印源站流)
在返回的 `aweme_detail.video.bit_rate[0].play_addr.url_list` 中包含多个 CDN 节点:
* `url_list[0]`:主 CDN
* `url_list[1]`:备用 CDN
* `url_list[2]`:源站 CDN(通常为最纯净、最高清流)
### 4.2 图文与 LivePhoto 提取
* ⚠️ **防坑警示**:`download_url_list` 包含带官方水印的图片;**必须提取 `url_list[-1]`**(末尾项通常为无水印最高清原图)。
* **LivePhoto 识别**:若单张图片对象包含 `img['video']['play_addr']`,则说明该图为苹果实况动态照片,提取该视频流即为 LivePhoto 动画。
---
## 5. 常见踩坑记录 (Gotchas)
1. **TTWID 失效导致返回空详情**:
* *现象*:接口 HTTP 状态码返回 200,但 JSON 中缺少 `aweme_detail` 字段。
* *解法*:代码中内置重试机制,初次失败立即清空 `_TTWID_CACHE` 并重新获取。
2. **User-Agent 不匹配导致签名校验失败**:
* *现象*:接口返回参数错误或 403。
* *原因*:`BogusSigner` 生成 `a_bogus` 时参与哈希计算的 UA 与实际发起 HTTP 请求的 UA 不一致。
---
## 6. 测试与验证
* **单元测试文件**:[tests/test_bogus_signer.py](file:///Users/leo/Projects/media-parser/tests/test_bogus_signer.py)
* **执行测试**:
```bash
pytest tests/test_bogus_signer.py
python tests/manual_verify_parsers.py --platform 抖音
```
+77
View File
@@ -0,0 +1,77 @@
# 快手 (Kuaishou) 逆向解析指南
本篇详细记录快手短视频、图文图集(ATLAS)的多路由容灾抓取机制与防封策略。
---
## 1. 平台特征与支持能力
* **平台标识**:`快手`
* **支持媒体类型**:
* 无水印高清短视频 (MP4)
* 高清图文图集 (ATLAS 图集)
* 背景音乐音频 (Audio)
* **常见链接形态**:
* App 短链:`https://v.kuaishou.com/xxxx`
* 移动端 H5 落地页:`https://v.m.chenzhongtech.com/fw/photo/3xbr5pi8hxi4e6s`
* PC 网页长链:`https://www.kuaishou.com/short-video/3xbr5pi8hxi4e6s`
* **Cookie 依赖**:无需用户登录,解析器已内置经过脱敏的高权重游客签名 Cookie。
---
## 2. 核心逆向方案:双端多路由 Fallback 容灾
快手不同公开路由的封控力度和可用性波动较大。在 [KuaishouParser](file:///Users/leo/Projects/media-parser/src/parsers/kuaishou_parser.py) 中,我们设计了**多路由自适应降级重试机制**:
```mermaid
flowchart TD
Start["获取快手视频 ID (photo_id)"] --> Route1["尝试路由 1: 原始落地页 (PC/H5)"]
Route1 --> Check1{"是否有效状态 (非 result:2 风控)?"}
Check1 -- Yes --> Success["解析成功,提取媒体"]
Check1 -- No --> Route2["自动降级路由 2: chenzhongtech 移动端 H5 接口"]
Route2 --> Check2{"校验成功?"}
Check2 -- Yes --> Success
Check2 -- No --> Fail["返回解析失败"]
```
### 2.1 候选路由构建 (`_candidate_urls`)
* 优先使用 302 重定向后的原生落地页。
* 备用使用移动端专用解析网关:`https://v.m.chenzhongtech.com/fw/photo/{video_id}`。
### 2.2 风控识别与拦截检测
当快手触发安全拦截时,接口或页面通常直接返回 `{"result": 2}` JSON 负载。解析器通过 `_is_blocked_payload` 自动拦截此类响应并立即触发备用通道。
---
## 3. 数据提取规则
### 3.1 视频数据提取
* 优先从 `mainMvUrls` 中提取高质量直链:
```python
video_url = photo.get('mainMvUrls', [{}])[0].get('url')
```
* 备用从流媒体清单 `manifest` 中提取。
### 3.2 图集 (ATLAS) 提取
* 快手图文内容在数据结构中标识为 `ATLAS`,图片 CDN 列表位于 `photo.atlas.list`。
* 遍历列表并结合 CDN 域名拼接最高清无水印大图。
---
## 4. 常见踩坑记录 (Gotchas)
1. **PC 端与移动端结构差异巨大**:
* PC 端页面数据挂载在 `defaultClient` 树下;移动端直接返回 `photo` 结构。解析器必须做形态判断。
2. **IP 访问频率限制**:
* 在移动端路由中必须伪装成真实的移动端浏览器 Headers(如 `v.m.chenzhongtech.com` 的专用 Referer)。
---
## 5. 测试与验证
* **单元测试**:[tests/test_kuaishou_parser.py](file:///Users/leo/Projects/media-parser/tests/test_kuaishou_parser.py)
* **执行命令**:
```bash
pytest tests/test_kuaishou_parser.py
python tests/manual_verify_parsers.py --platform 快手
```
+29
View File
@@ -0,0 +1,29 @@
# 绿洲 (Lvzhou) 逆向解析指南
本篇详细记录新浪微博旗下 **绿洲 (Oasis)** 图文与生活帖子的逆向提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`绿洲`
* **支持媒体类型**:高清图集 (JPEG/PNG) / 动态正文 / 作者信息
* **常见链接形态**:
* 移动分享:`https://oasis.weibo.cn/v1/h5/share?sid=4641407099208582`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取 SID**:从 Query 参数中提取绿洲动态的唯一编号 `sid`。
2. **HTML SSR 解析**:
* 请求绿洲 H5 分享页。
* 解析 HTML 中的正文与图片相册列表,提取最高清大图 CDN 链接。
---
## 3. 测试与验证
* **单元测试**:[tests/test_lvzhou_parser.py](file:///Users/leo/Projects/media-parser/tests/test_lvzhou_parser.py)
* **执行测试**:`pytest tests/test_lvzhou_parser.py`
+29
View File
@@ -0,0 +1,29 @@
# 美拍 (Meipai) 逆向解析指南
本篇详细记录 **美拍** 短视频的网页提取与解密方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`美拍`
* **支持媒体类型**:无水印视频 (MP4) / 封面图 / 视频标题
* **常见链接形态**:
* 视频页:`http://www.meipai.com/video/533/6777602107506448933`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **HTML 提取**:请求美拍落地页 HTML 内容。
2. **Base64 / 混淆解密**:
* 早期美拍将视频地址编码在 `data-video` 属性中,结合特定的 Base64 替换字典解码为真实 MP4 直链。
3. **备用正则匹配**:直接从 HTML 中匹配 `video` 标签或 `mp4` 源地址。
---
## 3. 测试与验证
* **单元测试**:[tests/test_meipai_parser.py](file:///Users/leo/Projects/media-parser/tests/test_meipai_parser.py)
* **执行命令**:`pytest tests/test_meipai_parser.py`
+29
View File
@@ -0,0 +1,29 @@
# 皮皮搞笑 (Pipigaoxiao) 逆向解析指南
本篇详细记录 **皮皮搞笑** 帖子短视频与搞笑内容的逆向提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`皮皮搞笑`
* **支持媒体类型**:无水印视频 (MP4) / 帖子标题 / 封面
* **常见链接形态**:
* 移动分享页:`https://h5.pipigx.com/pp/post/815491325984?pid=815491325984&type=post`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **ID 提取**:从 Query 参数或 Path 中提取 `pid` / `post_id`。
2. **H5 数据接口**:
* 接口:`POST https://api.pipigx.com/ppapi/cell/detail`
* 或直接在 H5 落地页 HTML 中提取内嵌 JSON。
3. **视频直链提取**:从 `post.video.video_download_url` 或 `post.video.video_url` 中提取 MP4 直链。
---
## 3. 测试与验证
* **样本验证**:`python tests/manual_verify_parsers.py --platform 皮皮搞笑`
+32
View File
@@ -0,0 +1,32 @@
# 皮皮虾 (Pipixia) 逆向解析指南
本篇详细记录字节跳动旗下 **皮皮虾 (Pipixia)** 短视频与图文帖子的逆向提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`皮皮虾`
* **支持媒体类型**:无水印视频 (MP4) / 图文帖子 / 评论区原声
* **常见链接形态**:
* 短链接:`https://h5.pipix.com/s/lggjR-ynbpI/`
* 移动落地页:`https://h5.pipix.com/item/6987123456789`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **302 跳转与 ID 提取**:请求短链获取 `Location` 头部,提取最后的纯数字 `item_id` / `cell_id`。
2. **移动端 API 抓取**:
* 接口:`https://api.pipix.com/bds/cell/cell_comment/`
* 参数:`cell_id={cell_id}&cell_type=1&api_version=1&aid=1319&app_name=super`
3. **无水印直链提取**:
* 视频直链位于 `data.cell_comments[0].comment_info.item.video.video_high.url_list[0].url`。
---
## 3. 测试与验证
* **单元测试**:[tests/test_pipixia_parser.py](file:///Users/leo/Projects/media-parser/tests/test_pipixia_parser.py)
* **命令**:`pytest tests/test_pipixia_parser.py`
+29
View File
@@ -0,0 +1,29 @@
# 腾讯微视 (Weishi) 逆向解析指南
本篇详细记录腾讯旗下 **微视 (Weishi)** 短视频的抓取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`微视`
* **支持媒体类型**:无水印视频 (MP4) / 封面图 / 标题
* **常见链接形态**:
* 分享页:`https://video.weishi.qq.com/5D41bben`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **Feed ID 提取**:从短链接路径中提取 `feed_id`(如 `5D41bben`)。
2. **微视开放接口**:
* 接口:`https://h5.weishi.qq.com/trpc.weishi.weishi_h5_proxy.weishi_h5_proxy/wspersonalfeed`
* 或调用微视分享落地页获取内置 JSON 状态。
3. **视频提取**:从 `data.feeds[0].video_url` 提取纯净 MP4 直链。
---
## 3. 测试与验证
* **样本验证**:`python tests/manual_verify_parsers.py --platform 微视`
+33
View File
@@ -0,0 +1,33 @@
# 最右 (Zuiyou) 逆向解析指南
本篇详细记录 **最右 (Zuiyou)** 搞笑视频与神评帖子的接口抓取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`最右`
* **支持媒体类型**:高清视频 (MP4) / 帖子正文 / 作者信息
* **常见链接形态**:
* 分享落地页:`https://share.xiaochuankeji.cn/hybrid/share/post?pid=423835942&vid=2542343457`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取帖子 PID**:从分享链接的 Query 中提取 `pid`。
2. **核心接口**:
* 接口:`POST https://share.xiaochuankeji.cn/planck/share/post/detail_h5`
* 请求头:`Referer: https://share.xiaochuankeji.cn/`
* 载荷:`{"h_av": "5.2.13.011", "pid": pid}`
3. **视频键值映射提取**:
* 从 `data.post.imgs[0].id` 获得 `video_key`。
* 通过 `data.post.videos[video_key].url` 取得最终播放直链。
---
## 3. 测试与验证
* **单元测试**:[tests/test_zuiyou_parser.py](file:///Users/leo/Projects/media-parser/tests/test_zuiyou_parser.py)
* **执行命令**:`pytest tests/test_zuiyou_parser.py`
+31
View File
@@ -0,0 +1,31 @@
# AcFun 弹幕视频网逆向解析指南
本篇详细记录 **AcFun (A站)** 视频页面与 KSPlayer 播放器参数的逆向提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`AcFun`
* **支持媒体类型**:高清视频流 (m3u8 / MP4) / 视频封面 / UP主信息
* **常见链接形态**:
* 网页长链:`https://www.acfun.cn/v/ac43445963`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取 AC 号**:从 URL 中通过正则匹配 `ac\d+`。
2. **提取页面内嵌 `window.pageInfo`**:
* 请求 A 站视频页,通过正则匹配 `window.pageInfo = ({.*?});`。
3. **解析 KSPlayer 播放器参数 (`ksPlayJson`)**:
* 从 `currentVideoInfo.ksPlayJson` 中解析出流媒体自适应清单 `adaptationSet`。
* 提取 `representation[0].url` 获取最高清视频播放流地址。
---
## 3. 测试与验证
* **单元测试**:[tests/test_base_parser.py](file:///Users/leo/Projects/media-parser/tests/test_base_parser.py)
* **样本验证**:`python tests/manual_verify_parsers.py --platform AcFun`
+81
View File
@@ -0,0 +1,81 @@
# 哔哩哔哩 (Bilibili) 逆向解析指南
本篇详细记录 B 站视频基本信息与可直接播放的单文件 MP4 播放流提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`哔哩哔哩`
* **支持媒体类型**:
* 高清视频流 (单文件 MP4)
* 高清封面图 (Cover)
* 视频标题与 UP 主作者信息
* **常见链接形态**:
* 短链接:`https://b23.tv/xxxx`
* 网页端长链:`https://www.bilibili.com/video/BV1asTR6FEWu`
* **Cookie 依赖**:无需登录 Cookie(可获取 720P/1080P HTML5 基础流)。
---
## 2. 核心逆向流程:双 API 联动
Bilibili 解析采用官方公开的 Web 开放接口进行两步联动查询:
```mermaid
sequenceDiagram
autonumber
participant Parser as BilibiliParser
participant ViewAPI as x/web-interface/view
participant PlayAPI as x/player/playurl
Parser->>Parser: 正则提取 BV 号 (如 BV1asTR6FEWu)
Parser->>ViewAPI: GET ?bvid=BVxxxx (获取基本信息与 cid)
ViewAPI-->>Parser: 返回 标题、封面、UP主、分P cid 列表
Parser->>PlayAPI: GET ?bvid=BVxxxx&cid={cid}&platform=html5&fnval=3...
PlayAPI-->>Parser: 返回 durl 包含音视频的单文件 MP4 直链
```
### 2.1 步骤 1:获取视频详情与 `cid`
* **接口**:`https://api.bilibili.com/x/web-interface/view`
* **参数**:`bvid={bvid}`
* **产出**:获取视频的 `cid`(内容分块 ID)、`title`、`pic`(封面图)、`owner`(UP主)。
### 2.2 步骤 2:获取无需合成的单文件 MP4 流 (`PlayURL`)
* **接口**:`https://api.bilibili.com/x/player/playurl`
* **关键传参技巧(避开 DASH 音视频分离)**:
```python
params = {
"otype": "json",
"fnver": 0,
"fnval": 3, # 避免默认返回 DASH 分离流
"player": 3,
"qn": 112, # 请求高质量档位
"bvid": self.bvid,
"cid": cid,
"platform": "html5", # 指定 HTML5 平台
"high_quality": 1
}
```
* **数据提取**:直接从 `data.durl[0].url` 获取已合并音视频的完整 MP4 直链,免去服务器端调用 `ffmpeg` 转码的性能开销。
---
## 3. 常见踩坑记录 (Gotchas)
1. **DASH 格式音视频分流陷阱**:
* 现代 B 站客户端默认使用 DASH(音轨与视轨分开为两个独立的 m4s 文件),如果直接提取会导致视频没有声音。
* **解法**:如上述参数配置,强制指定 `platform=html5` 请求,B 站服务端会自动返回封装好的 Progressive MP4 单文件流。
2. **防盗链 (403 Forbidden)**:
* 播放或下载 B 站视频直链时,客户端请求头中必须附带 `Referer: https://www.bilibili.com/`,否则会被 CDN 拦截。
---
## 4. 测试与验证
* **单元测试**:[tests/test_bilibili_parser.py](file:///Users/leo/Projects/media-parser/tests/test_bilibili_parser.py)
* **执行测试**:
```bash
pytest tests/test_bilibili_parser.py
python tests/manual_verify_parsers.py --platform 哔哩哔哩
```
+28
View File
@@ -0,0 +1,28 @@
# 好看视频 (Haokan) 逆向解析指南
本篇详细记录百度旗下 **好看视频** 短视频的逆向提取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`好看视频`
* **支持媒体类型**:无水印高清视频 (MP4) / 视频封面 / 标题与作者
* **常见链接形态**:
* 网页链接:`https://haokan.baidu.com/v?vid=17831460188721240800`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取 VID**:从 Query 中提取 `vid` 参数。
2. **提取 HTML 内嵌视频源**:
* 请求好看视频播放落地页;
* 正则匹配 `playurl` 或 HTML 内的 `<video>` 播放源链接。
---
## 3. 测试与验证
* **样本验证**:`python tests/manual_verify_parsers.py --platform 好看视频`
+29
View File
@@ -0,0 +1,29 @@
# 剪映 (Jianying) 逆向解析指南
本篇详细记录字节跳动旗下 **剪映** 模板视频与剪同款视频的解析方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`剪映`
* **支持媒体类型**:高清模板视频 (MP4) / 封面图 / 模板标题
* **常见链接形态**:
* 分享长链:`https://lv.ulikecam.com/activity/lv/sharevideo?template_id=7631885529415568665`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取 Template ID**:从 Query 参数中解析 `template_id`。
2. **调用剪映开放接口**:
* 接口:`https://lv.ulikecam.com/activity/lv/sharevideo` 或剪映移动端模板 API。
3. **提取视频播放源**:从返回数据中提取视频直链 `video_url`。
---
## 3. 测试与验证
* **单元测试**:[tests/test_jianying_parser.py](file:///Users/leo/Projects/media-parser/tests/test_jianying_parser.py)
* **执行命令**:`pytest tests/test_jianying_parser.py`
+36
View File
@@ -0,0 +1,36 @@
# 西瓜视频 (Xigua) 逆向解析指南
本篇详细记录字节跳动旗下 **西瓜视频** 中长视频的解析与继承机制。
---
## 1. 平台特征与支持能力
* **平台标识**:`西瓜视频`
* **支持媒体类型**:高清视频 (MP4) / 封面图 / 视频标题与作者
* **常见链接形态**:
* 分享链接:`https://v.douyin.com/Nid-fFF_sdI/`
* 网页链接:`https://www.ixigua.com/7676450021063735414`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心架构与继承实现
西瓜视频底层与抖音共享字节跳动的 **Aweme / TTVideo** 视频分发网络与相同的 `a_bogus` 鉴权体系。[XiguaParser](file:///Users/leo/Projects/media-parser/src/parsers/xigua_parser.py) 继承自 `DouyinParser`:
```python
from src.parser_factory import register_parser
from src.parsers.douyin_parser import DouyinParser
@register_parser("西瓜视频")
class XiguaParser(DouyinParser):
"""西瓜视频复用字节跳动核心解析与 a_bogus 签名引擎。"""
```
---
## 3. 测试与验证
* **单元测试**:[tests/test_xigua_parser.py](file:///Users/leo/Projects/media-parser/tests/test_xigua_parser.py)
* **执行命令**:`pytest tests/test_xigua_parser.py`
@@ -0,0 +1,29 @@
# 新片场 (Xinpianchang) 逆向解析指南
本篇详细记录影视创作人社区 **新片场** 4K/1080P 高清影视作品的抓取方案。
---
## 1. 平台特征与支持能力
* **平台标识**:`新片场`
* **支持媒体类型**:原画/高清视频 (MP4/HLS) / 作品封面 / 创作人信息
* **常见链接形态**:
* 网页链接:`https://www.xinpianchang.com/a13792376`
* **Cookie 依赖**:无需 Cookie。
---
## 2. 核心逆向流程
1. **提取文章/视频 ID**:从 URL 中提取 `a\d+` 或 `article_id`。
2. **提取 `__NEXT_DATA__` 或播放器 API**:
* 新片场使用 Next.js SSR 渲染,从首屏 `__NEXT_DATA__` 中解析视频播放配置;
* 或调用新片场 API 获取 `video_url` 及多清晰度档位。
---
## 3. 测试与验证
* **单元测试**:[tests/test_xinpianchang_parser.py](file:///Users/leo/Projects/media-parser/tests/test_xinpianchang_parser.py)
* **执行命令**:`pytest tests/test_xinpianchang_parser.py`
+104
View File
@@ -0,0 +1,104 @@
# 通用逆向方法论与抓包排查指南 (Reverse Engineering Guide)
本文档归纳了多媒体平台逆向解析的核心技术范式、抓包排查标准操作程序(SOP)以及常见反爬机制的应对策略。
---
## 🎯 4 大通用逆向技术范式
在分析 30+ 平台的过程中,我们将主流的解析方案归纳为以下 4 种模式:
```mermaid
graph TD
Start["目标平台页面 / 接口"] --> Decision{"数据载荷形式"}
Decision -->|"模式 1: HTML 内嵌状态"| SSR["SSR 状态提取<br>(__INITIAL_STATE__)"]
Decision -->|"模式 2: 开放/半开放 API"| API["移动端/H5 AJAX 抓取<br>(Headers 伪装)"]
Decision -->|"模式 3: 前端算法加密"| JS["JS 签名沙箱执行<br>(mini-racer / BogusSigner)"]
Decision -->|"模式 4: 登录态会话维持"| Session["Session 维持与任务轮询<br>(Cookie 注入)"]
```
### 模式 1:SSR 页面状态注入提取 (Server-Side Rendering)
* **适用平台**:小红书、最右、部分知乎/微博页面。
* **原理**:现代前端框架(Vue/React)在服务端渲染时,会将页面首屏的完整 JSON 序列化注入在 HTML 的 `<script>` 标签内(如 `window.__INITIAL_STATE__`、`window._ROUTER_DATA`)。
* **提取套路**:
```python
import re, json
# 使用正则非贪婪或贪婪匹配 script 块中的 JSON
pattern = re.compile(r'window\.__INITIAL_STATE__\s*=\s*(\{.*?\});</script>', re.DOTALL)
match = pattern.search(html_content)
if match:
data = json.loads(match.group(1))
```
---
### 模式 2:移动端 / H5 AJAX 接口抓取与伪装
* **适用平台**:快手、皮皮虾、AcFun、Bilibili。
* **原理**:PC 网页端通常反爬较严,但平台的移动端分享落地页(H5 / 微信内分享页)为了兼容性和加载速度,往往使用结构更简洁、校验更宽松的 AJAX REST API。
* **关键策略**:
1. 切换 User-Agent 为移动端(如 iPhone Safari / Android Chrome)。
2. 构造平台要求的 `Referer` 来源头(很多平台会验证 Referer 防盗链)。
3. 去除无用的 App 专有设备指纹字段。
---
### 模式 3:JS 签名解密与 V8 沙箱执行 (`mini-racer`)
* **适用平台**:字节跳动系(抖音、西瓜、汽水音乐等)。
* **原理**:平台在前端通过混淆的 JavaScript 脚本计算请求签名(如 `a_bogus`、`x_bogus`、`msToken`),后端校验该签名以阻止未经授权的自动化爬取。
* **工程解法**:
* 使用 [py_mini_racer](https://github.com/sqreen/py-mini-racer) 在 Python 中内嵌轻量级 Google V8 引擎。
* 提取并脱敏原始 JS 签名逻辑至 [utils/signer/bytedance/](file:///Users/leo/Projects/media-parser/utils/signer/bytedance/)。
* 通过 Python 直接向 V8 实例传入 URL query 与 UA 计算签名:
```python
from utils.signer.bytedance.bogus_signer import BogusSigner
signer = BogusSigner()
abogus = signer.get_abogus(play_url, user_agent)
```
---
### 模式 4:登录态维持与异步任务轮询
* **适用平台**:豆包 AI、通义千问等大模型生成平台。
* **原理**:AI 生成视频或富文本内容依赖用户 Session,且视频生成通常是异步任务。
* **工程解法**:
* 通过环境变量(如 `DOUBAO_COOKIE`)注入有效 Cookie。
* 在 Session 请求头中带上身份鉴权凭证。
* 轮询或从分享会话(Share Session)中提取已完成的任务直链。
---
## 🛠️ 抓包与排障 SOP (Standard Operating Procedure)
当某个平台解析失效或新增平台支持时,按以下 SOP 进行抓包分析:
### 第一步:链路重定向分析
使用 `curl -I` 观察分享短链接的跳转链路,获取最终真实 URL:
```bash
curl -I "https://v.douyin.com/xxxx/"
# 重点观察 HTTP 302 / 301 中的 Location 头部
```
### 第二步:浏览器 DevTools 抓包
1. 打开 Chrome 开发者工具 (`F12`),勾选 **Preserve log (保留日志)** 与 **Disable cache (停用缓存)**。
2. 切换设备仿真为 **iPhone 14 Pro** 或 **Pixel 7**。
3. 粘贴短链接回车,在 Network 标签页过滤:
* **Fetch/XHR**:观察页面加载完成后异步发出的数据请求。
* **Media**:观察加载的视频流地址(`.mp4`, `.m3u8`, `blob:`)。
* **Doc**:如果是 SSR 页面,右键查看首屏 Doc 响应源码,搜索视频标题关键词。
### 第三步:接口最小化提纯 (Header Stripping)
抓取到目标 API 请求后,右键选择 **Copy as cURL**,逐步剔除 Headers,找出哪些是**不可或缺的鉴权头**:
* 必须保留:通常为 `User-Agent`、`Referer`、特定 Cookie(如 `ttwid`)。
* 可以剔除:大部分 `sec-ch-ua`、`Sec-Fetch-*` 等浏览器指纹头。
---
## 🛡️ 常见反爬对抗与避坑技巧
| 反爬特征 | 表现形式 | 解决方案 |
| :--- | :--- | :--- |
| **IP 频控限制** | 连续请求后返回 403 / 429 或滑动验证码 | 增加 Session 复用,设置重试间隔;必要时配置代理池。 |
| **Cookie 过期** | 接口返回 `login required` 或空数据 | 动态向平台注册游客凭证(如抖音 `ttwid` 动态获取接口并做本地缓存)。 |
| **防盗链 (Hotlinking)** | 视频直链直接打开报 403 Forbidden | 下载或播放时必须在请求头中携带对应的平台 `Referer`。 |
| **水印 URL 替换** | 官方返回带水印的播放地址 | 分析 URL 结构,进行模式替换(如将 `playwm` 替换为 `play`,或取 CDN 列表最后一项)。 |
+87
View File
@@ -0,0 +1,87 @@
# 测试体系与回归验证指南 (Testing Guide)
本项目拥有完备的多层级测试体系,涵盖**单元测试 (Unit Tests)**、**API 契约测试 (Contract Tests)**、**真实网络样本回归 (Live Regression Tests)** 以及 **交互式手动验证工具**。
---
## 🧪 测试套件分层
```text
tests/
├── test_api_contract.py # API 统一契约与错误码断言测试
├── test_api_video_compat.py # 兼容性测试
├── test_parser_factory.py # 解析器自动注册与工厂路由测试
├── test_web_fetcher.py # 302跳转与URL正则提取测试
├── test_*_parser.py # 各平台专属的单元测试
├── live_parser_samples.json # 真实线上验证样本库 (30+ 平台活跃样例)
├── test_live_parser_samples.py # 自动化执行样本库回归测试
└── manual_verify_parsers.py # 命令行交互式/全量人工排查脚本
```
---
## 🚀 常用测试命令
### 1. 运行所有基础单元测试
用于日常开发与 CI 流程,速度极快(使用 Mock 或本地逻辑):
```bash
pytest
```
### 2. 运行指定平台的测试
调试某个特定解析器时使用:
```bash
# 测试抖音解析器
pytest tests/test_douyin_parser.py -v
# 测试小红书解析器
pytest tests/test_xiaohongshu_parser.py -v
# 测试 B 站解析器
pytest tests/test_bilibili_parser.py -v
```
### 3. 运行真实线上样例回归测试 (Live Tests)
通过 [tests/live_parser_samples.json](file:///Users/leo/Projects/media-parser/tests/live_parser_samples.json) 中的真实链接,发起实际网络请求测试各大平台的可用性:
```bash
pytest tests/test_live_parser_samples.py -s
```
### 4. 运行交互式手动验证脚本
[tests/manual_verify_parsers.py](file:///Users/leo/Projects/media-parser/tests/manual_verify_parsers.py) 提供了一个美观的终端报告:
```bash
# 全量验证所有平台当前线上可用状态
python tests/manual_verify_parsers.py --all
# 验证单个平台 (例如:抖音)
python tests/manual_verify_parsers.py --platform 抖音
```
---
## 📝 如何为新平台添加测试用例?
当你开发了一个新的解析器(例如 `NewPlatformParser`)时,请按以下两步补齐测试:
### 步骤 1:添加专属单元测试 (`tests/test_newplatform_parser.py`)
```python
import pytest
from src.parsers.newplatform_parser import NewPlatformParser
def test_newplatform_parser_success(monkeypatch):
# 构造假数据或测试实例
parser = NewPlatformParser("https://example.com/item/12345")
assert parser.get_title_content() is not None
```
### 步骤 2:在 `tests/live_parser_samples.json` 登记真实测试样例
```json
{
"platform": "新平台",
"url": "https://example.com/share/xxxx",
"media_types": ["video"],
"expected_fields": ["video", "cover", "title", "author"],
"note": "2026-08-29 已验证"
}
```
登记后,自动化回归测试脚本将自动纳入该平台的持续健康检查。