ai_crawler_tiktok/README.md

# crawler_tiktok

TikTok 数据抓取脚本，分为两阶段：
- 按关键词搜索视频链接并生成快照（`links`）
- 根据视频链接抓取评论与二级回复并生成快照与可选 CSV（`comments`）

全项目基于 Python 标准库实现（`urllib`、`threading` 等），不依赖第三方包。

## 目录结构

```
crawler_tiktok/
├─ core/                # cURL 文本解析与请求发送
│  └─ curl.py
├─ tiktok/              # TikTok 业务逻辑
│  ├─ search.py         # 关键词搜索视频链接
│  └─ comments.py       # 抓取评论与二级回复
├─ data/                # 示例数据与输出目录
│  ├─ 1.text            # cURL 文本（包含多个 curl 命令块）
│  ├─ keyword.txt       # 关键词文件（每行一个关键词）
│  ├─ urls.json         # 链接搜索快照输出（示例已有）
│  ├─ comments.csv      # 评论 CSV 输出（可选）
│  └─ store.py          # 统一的快照写入工具
├─ utils/               # 通用 IO 工具
│  └─ io.py
├─ main.py              # 命令行入口（子命令：links / comments / all）
└─ __init__.py          # 包入口
```

## 准备工作

- 安装 Python（建议 3.8+）
- 准备 `data/1.text`：
  - 打开浏览器访问 TikTok，登录后在开发者工具的 Network 面板选中相关请求，使用 “Copy as cURL” 复制。
  - 将“评论接口”的 `curl ...` 放在第一段，“搜索接口”的 `curl ...` 放在第二段；两段之间可直接换行即可。
  - 保留请求头（尤其是 `cookie`）以便接口正常返回。
- 准备关键词文件 `data/keyword.txt`（每行一个关键词），或使用命令行传参。

## 快速开始

在仓库根目录（必须为 `D:\work\crawler_tiktok`）直接运行脚本：

```
python main.py -h
```


### 1) 搜索视频链接（links）

将关键词并发搜索，统一去重并保存到 `urls.json`。

```
python main.py links \
  --keywords-file data\keyword.txt \
  --file-path data\1.text \
  --out data\urls.json \
  --max-pages 50 \
  --count 12 \
  --timeout 30 \
  --workers 5
```

可选：
- 通过 `--keyword` 重复传入多个关键词（可与 `--keywords-file` 混用）
- `--keywords` 逗号分隔的关键词字符串

输出 `urls.json` 结构示例：

```json
{
  "keywords": ["xxx", "yyy"],
  "items": [
    {"keyword": "xxx", "count": 10, "links": ["https://www.tiktok.com/@user/video/123" ...]},
    {"keyword": "yyy", "count": 8,  "links": [ ... ]}
  ],
  "total_count": 17855,
  "links": ["https://www.tiktok.com/@user/video/123", ...]
}
```

### 2) 抓取评论与回复（comments）

从链接快照读取链接，抓取主评论与二级回复，并保存 JSON 与可选 CSV。

```
python main.py comments \
  --links-json data\urls.json \
  --out data\tik_comments.json \
  --file-path data\1.text \
  --count 100 \
  --pages 100 \
  --timeout 30 \
  --reply-count 100 \
  --reply-pages 100 \
  --csv data\comments.csv \
  --workers 8
```

输出 `tik_comments.json` 结构示例：

```json
{
  "items": [
    {
      "link": "https://www.tiktok.com/@user/video/123",
      "count": 42,
      "comments": [
        {
          "cid": "xxx",
          "text": "...",
          "user": {"unique_id": "..."},
          "replies": [{"text": "..."}, ...],
          "reply_count": 3
        }
      ]
    }
  ]
}
```

若提供 `--csv`，会将主评论与回复分别以 `username,text` 形式追加到该文件。

### 3) 全流程一体化（all）

一次性串联链接搜索与评论抓取，适合流水线执行：

```
python main.py all \
  --keywords-file data\keyword.txt \
  --file-path data\1.text \
  --links-out data\urls.json \
  --search-max-pages 50 \
  --search-count 12 \
  --search-timeout 30 \
  --search-workers 5 \
  --comments-out data\tik_comments.json \
  --comments-count 100 \
  --comments-pages 100 \
  --comments-timeout 30 \
  --comments-limit 1000 \
  --reply-count 100 \
  --reply-pages 100 \
  --reply-limit 2000 \
  --csv data\comments.csv \
  --comments-workers 8
```

### 4) 写入 MySQL（从 CSV 导入）

在 `D:\work\crawler_tiktok` 下执行：

```
pip install pymysql
python main.py mysql \
  --csv data\comments.csv \
  --host localhost \
  --port 3306 \
  --user root \
  --password <你的密码> \
  --database crawler_tiktok \
  --table comments
```

若数据库不存在，请先在 MySQL 中创建：

```
CREATE DATABASE IF NOT EXISTS `crawler_tiktok` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

导入会在指定库中自动建表（如不存在），并批量插入 `username,text` 两列数据。

## 重要参数说明

- `--keyword / --keywords / --keywords-file`：三种方式提供关键词，最终会合并并去重。
- `--file-path`：cURL 文本文件路径（包含多个 `curl ...` 命令块）。
  - 第 1 块作为评论接口基准。
  - 第 2 块作为搜索接口基准。
- 搜索阶段：`--max-pages` 分页轮次上限；`--count` 每页条数（默认从 URL 中推断，通常为 12）；`--workers` 并发线程数。
- 评论阶段：`--pages` 评论分页上限；`--count` 每页评论数；`--reply-count` / `--reply-pages` 回复分页与每页数；`--workers` 并发抓取线程数。
- `--timeout`：请求超时秒数。
- `--csv`：若提供则会将主评论与回复按 `username,text` 追加到该 CSV。

## 输出文件约定

- `data/urls.json`：链接搜索快照，包含 `keywords/items/total_count/links`。
- `data/tik_comments.json`：评论抓取快照，包含 `items`（每项含 `link/count/comments`）。
- `data/comments.csv`：CSV 格式的评论与回复（用户名、文本）。

## 常见问题

- 返回为空或报错：优先检查 `data/1.text` 的 cURL 是否有效，`cookie` 是否过期。
- 速率限制：适当降低 `--workers`、提高 `--timeout`，或分批执行。
- Windows 路径：示例中使用反斜杠；若在类 Unix 环境，改为 `/`。
- 进度打印：抓取过程会打印 START/DONE/ERROR 以及评论统计，便于观察执行状态。