短剧内容采集工具

# macOS 部署指南 — 番茄漫剧 + 红果双 App

> 本文档覆盖 `fanqie_dramas_delivery/` 交付包在 macOS 上的完整部署流程。
> 番茄小说（`com.dragon.read`）和红果短剧（`com.phoenix.read`）共用同一台模拟器与同一份 Frida Server，只需部署一次。

---

## 一、交付包结构

```
fanqie_dramas_delivery/
├── README.md                    # 总览
├── docs/
│   ├── MAC_DEPLOY_GUIDE.md      # 本文档
│   ├── WINDOWS_DEPLOY_GUIDE.md
│   └── STARTUP_GUIDE.md
├── tools/                       # 二进制资源
│   ├── frida-server-17.11.0-android-arm64
│   ├── fanqie_xiaoshuo_arm64.apk
│   └── hongguo_arm64.apk
├── fanqie/                      # 番茄漫剧脚本
│   ├── auto_decrypt.py
│   ├── decrypt.py / download.py / hook_key_final.js
│   └── README_AUTO.md
├── hongguo/                     # 红果短剧脚本
│   ├── auto_decrypt_hongguo.py
│   ├── hongguo_decrypt.py / decrypt.py / hook_key_final.js
│   └── README_HONGGUO.md
├── youmanju/                    # 柚漫剧（HTTP 直链，无需模拟器，本文档不涉及）
└── data/                        # 剧库快照
```

⚠️ 拷贝到新 Mac 时**整个目录一起拷**，脚本内部有相对路径引用。

---

## 二、环境依赖一览

| 依赖 | 作用 | 版本要求 | 安装方式 |
|------|------|---------|---------|
| Python | 运行脚本 | ≥3.9（推荐 3.11+） | Homebrew |
| pycryptodome | AES-CTR 解密 | 最新 | pip |
| frida-tools | Frida CLI + Python 绑定 | **必须 17.11.0** | pip |
| requests | HTTP 请求 | 最新 | pip |
| FFmpeg | 音频加密探测、视频验证 | ≥5.0 | Homebrew |
| Android Studio | AVD 模拟器 + ADB | 2023.1+ | 官网 |
| Frida Server | 模拟器端 hook 代理 | 17.11.0（与 frida-tools 严格对齐） | 交付包内已预置 |

---

## 三、基础环境安装

### 3.1 Homebrew（已有可跳过）

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew --version   # 期望: Homebrew 4.x.x
```

### 3.2 Python + pip 依赖

```bash
brew install python@3.11
pip3 install pycryptodome 'frida==17.11.0' 'frida-tools==17.11.0' requests
```

验证：
```bash
python3 --version                                          # Python 3.11.x
python3 -c "from Crypto.Cipher import AES; print('ok')"    # ok
python3 -m frida_tools.frida --version                     # 17.11.0（必须精确匹配）
python3 -c "import requests; print(requests.__version__)"  # 2.x.x
```

⚠️ frida 版本必须**精确等于 17.11.0**，与交付包内的 `frida-server-17.11.0-android-arm64` 对齐。否则连接会失败或功能异常。

### 3.3 FFmpeg

```bash
brew install ffmpeg
ffmpeg -version | head -1    # ffmpeg version 7.x.x
ffprobe -version | head -1   # ffprobe version 7.x.x
```

红果解密的 `_is_audio_encrypted` 探测强依赖 ffmpeg，缺了会全部走音频解密路径导致个别集无声。

### 3.4 Android Studio + ADB

1. 官网下载：https://developer.android.com/studio（Apple Silicon 选 `mac_arm`）
2. 首次启动装 SDK：Platform 33+、Platform-Tools、Emulator
3. 加 PATH：

```bash
echo 'export PATH="$HOME/Library/Android/sdk/platform-tools:$PATH"' >> ~/.zshrc
source ~/.zshrc
adb version   # Android Debug Bridge version 1.0.41
```

⚠️ Android 模拟器需要单独部署一份。

---

## 四、部署服务器

部署服务器分为两部分：**采集器部署机器**和**内容数据服务器**。

### 4.1 采集器部署机器

采集器需要部署到一台**在国外的 Mac 电脑**上，用于执行内容采集及相关处理流程。

| 项 | 要求 |
|---|---|
| 部署位置 | 国外的 Mac 电脑 |
| 操作系统 | macOS |
| 硬件配置 | 无特殊要求 |

采集器完成内容采集后，通过数据接口将采集到的内容上传至自家的内容数据库。

### 4.2 内容数据服务器

内容数据服务器用于存储采集器上传的内容数据。

| 项 | 要求 |
|---|---|
| 操作系统 | 无特殊要求，可使用 Linux 或其他任意系统 |
| 硬件配置 | 无特殊要求 |
| 数据上传方式 | 通过数据接口接收采集器上传的内容 |

采集器与内容数据服务器相互独立：采集器负责内容采集，内容数据服务器负责接收和存储采集后的内容数据。

---

## 五、模拟器准备

### 4.1 创建 AVD

Android Studio → **More Actions → Virtual Device Manager → Create device**

| 项 | 值 |
|---|---|
| 设备型号 | Pixel 6 / Pixel 7 |
| 系统镜像 | Android 13.0 (API 33) **arm64-v8a** |
| 变体 | **不要** Google Play 版（要 root） |
| RAM | 4096 MB |
| 内部存储 | 8192 MB |
| 图形 | Hardware - GLES 2.0 |

⚠️ 关键：**arm64-v8a**（APK 只提供 arm64）且**非 Google Play 版**（Frida 需要 root）。

### 4.2 启动并验证

Device Manager → ▶️ 启动，等桌面出来。

```bash
adb devices
# List of devices attached
# emulator-5554   device
```

如显示 `offline`：`adb kill-server && adb start-server` 后重连。

### 4.3 内存优化（必须，2GB → 4GB）

⚠️ **关键**：红果 app 在默认 2GB 内存下会导致闪退和性能问题，**必须增加到 4GB**。

#### 为什么需要增加内存？

**症状**：
- App 启动后闪退
- 点击剧集后自动返回首页  
- 日志显示 `java.lang.VerifyError`（字节码验证失败）
- 内存状态显示 `critical`（临界状态）

**原因**：
- 红果 app 是大型应用（需要约 400-500 MB）
- Frida + hook 额外消耗约 100-150 MB
- GMS 和系统服务消耗约 400-600 MB
- 2GB 总内存下可用内存经常低于 700 MB → **不够用**

**解决方案**：增加到 4GB，确保可用内存 > 1.5 GB

#### 修改步骤（Android Studio GUI - 推荐）

1. **关闭模拟器**
   ```bash
   adb emu kill
   ```

2. **打开 Device Manager**
   - Android Studio → 右上角 → Device Manager（手机图标）

3. **编辑 AVD**
   - 找到你的模拟器（如 Pixel_6）
   - 点击右侧 ⋮ (三点菜单) → **Edit**

4. **修改内存**
   - 点击 **Show Advanced Settings**
   - 找到 **Memory and Storage** 部分
   - **RAM**: 改为 `4096` MB
   - （可选）Internal Storage: 保持 `8192` MB 或更大

5. **保存并重启**
   - 点击 **Finish**
   - 重新启动模拟器

6. **验证修改**
   ```bash
   adb shell "cat /proc/meminfo | grep MemTotal"
   # 期望: MemTotal:  4062880 kB (约 4GB)
   
   adb shell "dumpsys meminfo | grep 'Total RAM'"
   # 期望: Total RAM: 4,062,880K (status normal)  ← normal，不是 critical
   ```

#### 命令行修改方式（高级，仅在 GUI 失败时使用）

⚠️ **警告**：直接编辑配置文件有风险，推荐使用 GUI 方式。

```bash
# 1. 关闭模拟器
adb emu kill
sleep 5

# 2. 备份配置
cp ~/.android/avd/Pixel_6.avd/config.ini ~/.android/avd/Pixel_6.avd/config.ini.backup

# 3. 手动编辑文件（用文本编辑器打开）
# 文件路径: ~/.android/avd/Pixel_6.avd/config.ini
# 找到: hw.ramSize=2048
# 改为: hw.ramSize=4096
# 保存

# 4. 重启模拟器（通过 Android Studio）
```

⚠️ **常见错误**：
- **不要用 `sed -i` 直接修改**（可能破坏文件导致 0 字节）
- 修改后如果模拟器无法启动，恢复备份：
  ```bash
  cp ~/.android/avd/Pixel_6.avd/config.ini.backup ~/.android/avd/Pixel_6.avd/config.ini
  ```

#### 额外优化：禁用干扰服务（可选）

在 4GB 内存下通常不需要禁用服务，但可以禁用会干扰自动化的服务：

```bash
# 禁用 Calendar（会自动弹出，干扰自动化） - 推荐
adb shell "pm disable-user com.android.providers.calendar"
adb shell "pm disable-user com.google.android.calendar"

# 禁用 Chrome（节省 ~80MB） - 可选
adb shell "pm disable-user com.android.chrome"

# 禁用 Wellbeing（节省 ~50MB） - 可选
adb shell "pm disable-user com.google.android.apps.wellbeing"
```

⚠️ **重要**：
- **不要禁用 GMS**（Google Play Services），红果需要它，否则会持续弹窗
- 如果之前禁用了 GMS，必须重新启用：
  ```bash
  adb shell "pm enable com.google.android.gms"
  ```

---

## 六、Frida Server 部署（两 App 共用）

红果在 native 层做了**两层反 Frida 检测**：
1. **进程名检测**：扫描 `frida-server` 字样 → **必须改名为 `fs`**
2. **端口检测**：扫描默认端口 27042 → **必须用非标端口 38888**

番茄不做检测，但为了两 App 共用同一个 fs，统一用 38888 端口。

### 5.1 推送并启动

```bash
cd ~/fanqie_dramas_delivery/tools

adb push frida-server-17.11.0-android-arm64 /data/local/tmp/fs
adb shell "chmod 755 /data/local/tmp/fs"
adb shell "su 0 /data/local/tmp/fs -l 0.0.0.0:38888 &"
adb forward tcp:38888 tcp:38888
```

⚠️ **关键**：
- `-l 0.0.0.0:38888` 让 fs 监听 38888 端口（绕过红果的 27042 端口检测）
- `adb forward` 把本机 38888 映射到模拟器 38888（番茄和红果脚本都走这个端口）

### 5.2 验证

```bash
adb shell "ps -A | grep ' fs$'"
# 期望: 一行 root ... fs

python3 -m frida_tools.ps -H 127.0.0.1:38888 | head -5
# 期望: 列出模拟器进程列表
# 提示: 直接跑 frida-ps 可能报 command not found,pip 用户 bin 没进 PATH
#       可用 `python3 -m frida_tools.ps -H 127.0.0.1:38888`
```

成功示例：
```
chuzu@Mac-29 ~ % adb shell "ps -A | grep ' fs$'"
root         13526     1   15499120  46628 0                   0 S fs
chuzu@Mac-29 ~ % python3 -m frida_tools.ps -H 127.0.0.1:38888 | head -5
  PID  Name
-----  -------------------------
 3535  .adservices                                           
 3201  Camera                                                
 3722  Chrome
```

### 5.3 每次开机后

模拟器重启后 `fs` 会丢失，有两种方式重启：

**方式1：使用 ensure_frida.py（推荐）**
```bash
cd ~/fanqie_dramas_delivery/hongguo
python3 ensure_frida.py
```

**方式2：手动启动**
```bash
adb shell "su 0 /data/local/tmp/fs -l 0.0.0.0:38888 &"
adb forward tcp:38888 tcp:38888
```

---

## 七、番茄漫剧部署

### 6.1 安装 APK

```bash
cd ~/fanqie_dramas_delivery/tools
adb install fanqie_xiaoshuo_arm64.apk
```

如提示签名冲突：`adb uninstall com.dragon.read` 后重装。

### 6.2 冒烟测试

```bash
cd ~/fanqie_dramas_delivery/fanqie

# 模拟器里手动打开番茄小说 → 搜"青皮葫芦" → 点开播第1集
python3 auto_decrypt.py \
  --title "青皮葫芦" \
  --series-id 7642019605518486590 \
  --episodes 1 \
  --skip-nav \
  --output-dir ./test_output
```

成功标志：`[OK] → 青皮葫芦_第001集_720p_decrypted.mp4`

验证：
```bash
ffprobe test_output/青皮葫芦/青皮葫芦_第001集_720p_decrypted.mp4 2>&1 | grep -E "Stream|Duration"
# 应含 Video: hevc 和 Audio: aac
```

---

## 八、红果短剧部署

### 7.1 安装 APK

```bash
cd ~/fanqie_dramas_delivery/tools
adb install hongguo_arm64.apk
```

如提示签名冲突：`adb uninstall com.phoenix.read` 后重装。

### 7.2 冒烟测试

红果流程不同：先启动 App 播放，脚本再抓 key + 拉 dataloader 缓存 + 本地解密。

```bash
cd ~/fanqie_dramas_delivery/hongguo

# 模拟器里打开红果 → 播任意一集 3-5 秒
python3 hongguo_decrypt.py auto --hold 30 --output-dir ./test_output
```

成功标志：
```
[FRIDA] attached pid=xxxx via emulator-5554
[+] Hooks installed on libttffmpeg.so
[KEY+] file_hash=xxx key=xxx
完成: 成功 N  失败 0
```

按剧名跑全流程：
```bash
python3 auto_decrypt_hongguo.py --title "青皮葫芦" --series-id <id> --output-dir ./test_output
```

---

## 九、日常使用速查

### 8.1 每次开机流程

#### 方式1：使用 ensure_frida.py（推荐）

`ensure_frida.py` 是一个**独立的环境管理工具**，可以自动检测并修复 frida 环境问题：

```bash
# 1. 启动模拟器

# 2. 运行环境检查工具（自动启动/修复 frida-server）
cd ~/fanqie_dramas_delivery/hongguo
python3 ensure_frida.py

# 3. 模拟器里手动打开目标 App 的播放页
# 4. 终端跑对应脚本（见 9.2 / 9.3）
```

**ensure_frida.py 特性**：
- ✅ **智能检测**：环境正常时 0.5 秒通过，不做任何改动
- ✅ **自动修复**：检测到问题时自动清理并重启 frida-server
- ✅ **安全可靠**：可重复运行，不会破坏已有环境
- ✅ **完全独立**：不依赖其他脚本，适用于所有需要 frida 的场景

**常用命令**：
```bash
python3 ensure_frida.py           # 默认：确保环境就绪
python3 ensure_frida.py --check   # 仅检查状态，不修改
python3 ensure_frida.py --restart # 强制重启 frida-server
python3 ensure_frida.py --status  # 显示详细诊断信息
```

#### 方式2：手动启动（传统方式）

```bash
# 1. 启动模拟器
# 2. 手动启动 frida-server
adb shell "su 0 /data/local/tmp/fs -l 0.0.0.0:38888 &"
adb forward tcp:38888 tcp:38888

# 3. 模拟器里手动打开目标 App 的播放页
# 4. 终端跑对应脚本（见 9.2 / 9.3）
```

⚠️ **注意**：`ensure_frida.py` 是独立工具，不会被其他脚本自动调用，也不会影响其他脚本的运行。你可以选择使用或不使用。

### 8.2 番茄脚本 `auto_decrypt.py`

| 参数 | 必填 | 说明 |
|------|------|------|
| `--title` | ✅ | 剧名（用于文件命名） |
| `--series-id` | ✅ | 19 位漫剧 ID |
| `--episodes` | ❌ | `1` / `1-10` / `1,3,5`，默认全部 |
| `--skip-nav` | ❌ | 跳过自动搜索（推荐，配合手动打开播放页） |
| `--output-dir` | ❌ | 默认 `./downloads` |
| `--quality` | ❌ | `360p/480p/540p/720p`，默认 720p |
| `--hold` | ❌ | 每集停留秒数，默认 6，慢机 10-12 |
| `--resume` | ❌ | 断点续传 |

**首集必须单独跑**（第一集 key 位与其他集错位）：
```bash
python3 auto_decrypt.py --title "X" --series-id <id> --episodes 1 --skip-nav
python3 auto_decrypt.py --title "X" --series-id <id> --episodes 2-50 --skip-nav
```

### 8.3 红果脚本 `hongguo_decrypt.py` / `auto_decrypt_hongguo.py`

| 命令 | 用途 |
|------|------|
| `hongguo_decrypt.py list` | 列 dataloader 中 mdl 及 key 匹配状态 |
| `hongguo_decrypt.py capture` | 只抓 key（Ctrl-C 退出），手动切集 |
| `hongguo_decrypt.py decrypt --output-dir X` | 解密已有 key 的 mdl |
| `hongguo_decrypt.py auto --hold N` | 抓 key + 等 N 秒 + 自动解密 |
| `auto_decrypt_hongguo.py --title X --series-id Y` | 按剧名跑全流程（含自动翻集） |

红果不用区分首集，dataloader 缓存与 key 是 file_hash 匹配的。

---

## 十、常见问题

### 9.1 通用

**Q：frida 注入失败 / 连接超时 / TransportError**
1. 先运行 `python3 hongguo/ensure_frida.py --status` 查看详细状态
2. 如果是版本问题：查 `python3 -m frida_tools.frida --version`，必须精确 17.11.0
3. 如果是环境问题：运行 `python3 hongguo/ensure_frida.py` 自动修复
4. 如果仍失败：运行 `python3 hongguo/ensure_frida.py --restart` 强制重建

**Q：`adb devices` 显示 unauthorized**
模拟器弹窗点"允许"，勾"始终允许"。

**Q：报错 `No module named 'Crypto'`**
装错了包：
```bash
pip3 uninstall crypto pycrypto
pip3 install pycryptodome
```

**Q：Cookie 过期（API 返回 400 / 空数据）**
在模拟器抓包拿新 Cookie，更新对应 `config.py` 的 `COOKIE`。

### 9.2 番茄专属

**Q：第 1 集解密后黑屏**
第 1 集必须单独跑一次 `--episodes 1`，不能跟其他集合并。

**Q：key 捕获数量为 0**
App 缓存过播放记录，不重触发解密函数：
```bash
adb shell "am force-stop com.dragon.read"
# 然后再打开播放
```
或加大 `--hold 12`。

### 9.3 红果专属

**Q：`[ERR] /data/local/tmp/fs 不存在`**
没 push frida-server 或改名不对。回到 §6.1 重推。

**Q：没有 `[URL]` / `[KEY]` 日志**
1. 红果反 Frida 检测触发 → 确认二进制改名为 `fs`（不是 `frida-server`）
2. `libttffmpeg.so` 未加载 → 播放页停留 ≥3s
3. ADB 断开 → `adb devices` 检查

**Q：下载成功但视频无声**
`decrypt.py` 的 `_is_audio_encrypted` 必须走真解码（`-vn -f null -`），不能 `-c:a copy`。检查 ffmpeg 是否装好。

**Q：某集报 `[SKIP] 第 N 集不在目标`**
vid 白名单命中防污染逻辑，说明播的不是目标剧或翻页翻到了首页。确认播放页是目标剧再重试。

---

## 附录：一键环境检查

保存为 `check_env.sh` 运行：

```bash
#!/bin/bash
echo "=== 环境检查 ==="

check() { printf "[%s] %-18s " "$1" "$2"; }

check 1/8 Python
python3 --version 2>/dev/null || echo "❌ brew install python@3.11"

check 2/8 pycryptodome
python3 -c "from Crypto.Cipher import AES; print('OK')" 2>/dev/null || echo "❌ pip3 install pycryptodome"

check 3/8 frida-tools
V=$(python3 -m frida_tools.frida --version 2>/dev/null)
[ "$V" = "17.11.0" ] && echo "$V ✅" || echo "❌ 需 17.11.0，实际 $V"

check 4/8 requests
python3 -c "import requests; print(requests.__version__)" 2>/dev/null || echo "❌ pip3 install requests"

check 5/8 FFmpeg
ffmpeg -version 2>/dev/null | head -1 || echo "❌ brew install ffmpeg"

check 6/8 ADB
adb version 2>/dev/null | head -1 || echo "❌ 装 Android Studio 或 Platform-Tools"

check 7/8 emulator
adb devices | grep -q "emulator.*device$" && echo "✅" || echo "❌ 未启动"

check 8/8 fs
adb shell "ps -A | grep ' fs$'" 2>/dev/null | grep -q fs && echo "✅ 运行中" || echo "❌ adb shell \"su 0 /data/local/tmp/fs &\""

echo "=== 完毕 ==="
```

使用：
```bash
chmod +x check_env.sh
./check_env.sh
```