持续监控小红书、B站、抖音的多媒体数据采集系统，基于关键词增量抓取帖子与评论。
v0.2 - B站 + 小红书全链路可用（搜索 + 详情 + 评论 + 签名 + 定时调度）
| 平台 | 搜索 | 详情 | 评论 | 签名 | 调度 |
|---|---|---|---|---|---|
| B站 (bili) | ✅ | ✅ | ✅ | - | ✅ |
| 小红书 (xhs) | ✅ | ✅ | ✅ | ✅ X-s/X-t | ✅ |
| 抖音 (dy) | 🔜 Phase 7 | 🔜 Phase 7 | 🔜 Phase 7 | 🔜 Phase 7 | 🔜 Phase 7 |
- Python 3.12+ (项目使用 3.14)
- MySQL 8.0
- uv (包管理器)
Windows 用户注意：如果
uv run命令挂起，请改用.venv\Scripts\python.exe直接执行，例如：.venv\Scripts\python.exe scripts/init_db.py
# 1. 克隆项目
git clone <repo-url> && cd swarm
# 2. 安装依赖
uv sync
# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 MySQL 连接信息
# 4. 初始化数据库
uv run scripts/init_db.py
# 5. 添加爬虫 Cookie（可选，无 Cookie 以降级模式运行）
# 交互式添加（执行后会提示粘贴 cookie）：
uv run scripts/add_cookie.py add --platform bili --name "我的B站号"
# 或直接传入：
uv run scripts/add_cookie.py add --platform bili --name "我的B站号" --cookie "SESSDATA=xxx"
# 6. 添加监控关键词（关键词通过 --keyword 传入，支持多个）
uv run scripts/manage_keywords.py add --platform bili --keyword "Python教程"
# 7. 启动调度器（持续运行） ps:这个相当于定时任务，会根据配置的 cron 表式定时执行爬取
uv run main.py
# 8. 单次爬取指定平台或关键词
uv run main.py --once --platform bili
uv run main.py --once --platform bili --keyword "Python教程"所有配置通过 .env 文件管理，参考 .env.example。
.env 的配置会覆盖 config/settings.py 中的默认值。
cron 格式：分 时 日 月 周（共5个字段，用空格分隔）
常用调度间隔：
| 表达式 | 含义 | 示例 |
|---|---|---|
* * * * * |
每分钟 | 每分钟检查一次 |
*/5 * * * * |
每5分钟 | |
*/15 * * * * |
每15分钟 | |
0 * * * * |
每小时整点 | |
0 */1 * * * |
每1小时 | |
0 */2 * * * |
每2小时 | B站默认 |
0 */3 * * * |
每3小时 | 小红书默认 |
0 */4 * * * |
每4小时 | 抖音默认 |
0 2 * * * |
每天凌晨2点 | 评论补充 |
0 3 * * * |
每天凌晨3点 | 日志清理 |
数据库：
| 变量 | 默认值 | 说明 |
|---|---|---|
DB_HOST |
localhost | MySQL 地址 |
DB_PORT |
3306 | MySQL 端口 |
DB_USER |
root | MySQL 用户 |
DB_PASSWORD |
(空) | MySQL 密码 |
DB_NAME |
swarm | 数据库名 |
爬虫参数：
| 变量 | 默认值 | 说明 |
|---|---|---|
SEARCH_MAX_PAGES |
1 | 每个关键词搜索页数 |
SEARCH_PAGE_SIZE |
50 | B站搜索每页条数 (最大50) |
XHS_SEARCH_PAGE_SIZE |
20 | 小红书搜索每页条数 (最大20) |
SEARCH_ORDER |
default | B站搜索排序: default=综合, pubdate=最新, click=播放量, stow=收藏量 |
XHS_SEARCH_SORT |
general | 小红书搜索排序: general=综合, popularity=热门, latest=最新 |
COMMENT_MAX_PAGES |
3 | 每个帖子评论页数 (无comment_count时的兜底) |
COMMENT_MAX_PAGES_LIMIT |
50 | 评论翻页绝对上限 (0=无限制, 由API has_more控制) |
COMMENT_PAGE_SIZE |
20 | B站评论每页条数 (最大20) |
XHS_COMMENT_PAGE_SIZE |
10 | 小红书评论每页条数 (最大10) |
CRAWL_RETRY_COUNT |
1 | 请求失败重试次数 |
CRAWL_TIMEOUT |
15.0 | 请求超时秒数 |
COMMENT_PAGE_INTERVAL |
1.0 | 评论翻页间隔(秒) |
DETAIL_INTERVAL |
1.0 | 详情请求间隔(秒) |
Cookie 管理：
| 变量 | 默认值 | 说明 |
|---|---|---|
COOKIE_COOLDOWN_MINUTES |
30 | 同账号最小使用间隔(分钟) |
COOKIE_MAX_FAIL_COUNT |
3 | 连续失败阈值(超限自动失效) |
日志：
| 变量 | 默认值 | 说明 |
|---|---|---|
LOG_LEVEL |
INFO | 日志级别: DEBUG/INFO/WARNING |
LOG_RETENTION_DAYS |
30 | 日志保留天数 |
调度频率（cron 表达式）：
| 变量 | 默认值 | 说明 |
|---|---|---|
SCHEDULER_BILI_CRON |
0 */2 * * * |
B站爬取频率 |
SCHEDULER_XHS_CRON |
0 */3 * * * |
小红书爬取频率 |
SCHEDULER_DY_CRON |
0 */4 * * * |
抖音爬取频率 |
SCHEDULER_COMMENT_CRON |
0 2 * * * |
评论补充频率 |
SCHEDULER_LOG_CLEAN_CRON |
0 3 * * * |
日志清理频率 |
SCHEDULER_COOKIE_CHECK_CRON |
0 * * * * |
Cookie健康检查频率 |
详细配置见 config/settings.py。
Windows 用户：
uv run挂起时，替换为.venv\Scripts\python.exe
# 调度模式（持续运行，按 cron 定时爬取）
uv run main.py
# 单次执行（适合调试）
uv run main.py --once --platform bili
uv run main.py --once --platform bili --keyword "Python教程"# 交互式添加
uv run scripts/add_cookie.py add --platform bili --name "我的B站号"
# 直接传入
uv run scripts/add_cookie.py add --platform bili --name "测试" --cookie "SESSDATA=xxx"
# 查看所有
uv run scripts/add_cookie.py list
# 按平台查看
uv run scripts/add_cookie.py list --platform bili
# 删除 ps: 3 是 Cookie ID，根据实际情况修改
uv run scripts/add_cookie.py delete 3# 添加（支持批量，多个关键词用空格分隔）
uv run scripts/manage_keywords.py add --platform bili --keyword "Python教程" "机器学习"
# 列出所有
uv run scripts/manage_keywords.py list
# 按平台 / 仅启用
uv run scripts/manage_keywords.py list --platform bili --active-only
# 停用 / 启用 / 删除
uv run scripts/manage_keywords.py disable 3
uv run scripts/manage_keywords.py enable 3
uv run scripts/manage_keywords.py delete 3# 建库建表
uv run scripts/init_db.py
# 删除重建（危险！）
uv run scripts/init_db.py --dropswarm/
├── main.py # 入口（CLI + 调度器）
├── config/
│ └── settings.py # 全局配置（pydantic-settings）
├── core/
│ ├── scheduler.py # APScheduler 定时调度器
│ ├── cookie_manager.py # Cookie 池管理器
│ ├── exceptions.py # 自定义异常
│ └── signers/ # 签名模块（xhs/dy 可插拔）
│ └── xhs_signer.py # 小红书 X-s/X-t 签名
├── spiders/
│ ├── base.py # 爬虫基类
│ ├── bili/ # B站爬虫（搜索+详情+评论）
│ │ ├── spider.py # 爬虫主逻辑
│ │ ├── api.py # API 封装
│ │ └── parser.py # 数据解析
│ └── xhs/ # 小红书爬虫（搜索+详情+评论）
│ ├── spider.py # 爬虫主逻辑
│ ├── api.py # API 封装（含签名）
│ └── parser.py # 数据解析
├── models/ # SQLAlchemy ORM 模型
│ ├── base.py # 基类 + 混入
│ ├── account.py # 账号池
│ ├── keyword.py # 关键词
│ ├── spider_log.py # 爬虫日志
│ ├── bili_*.py # B站帖子/评论模型
│ └── xhs_*.py # 小红书帖子/评论模型
├── storage/ # 数据库存取封装
│ ├── database.py # MySQL 连接管理
│ ├── cookie_store.py # Cookie CRUD
│ ├── keyword_store.py # 关键词 CRUD
│ └── log_store.py # 日志存取
├── scripts/ # 命令行工具
│ ├── init_db.py # 数据库初始化
│ ├── add_cookie.py # Cookie 管理
│ └── manage_keywords.py # 关键词管理
├── utils/
│ └── logger.py # loguru 日志配置
└── tests/ # 测试脚本
Python 3.14 / uv / httpx / SQLAlchemy 2.0 / MySQL 8.0 / APScheduler / Pydantic v2 / loguru
爬到的数据存储在 MySQL 数据库中，可通过以下方式查询：
# 查看视频总数
SELECT COUNT(*) FROM bili_posts;
# 查看最新爬取的10条视频
SELECT post_oid, title, url, publish_time, view_count
FROM bili_posts
ORDER BY crawl_time DESC
LIMIT 10;
# 查看某视频的评论数
SELECT COUNT(*) FROM bili_comments
WHERE post_id = (SELECT id FROM bili_posts WHERE post_oid = 'BV号');
# 查看笔记总数
SELECT COUNT(*) FROM xhs_posts;
# 查看最新爬取的10条笔记
SELECT post_oid, title, url, note_type, publish_time, like_count
FROM xhs_posts
ORDER BY crawl_time DESC
LIMIT 10;
# 查看某笔记的评论数
SELECT COUNT(*) FROM xhs_comments
WHERE post_id = (SELECT id FROM xhs_posts WHERE post_oid = '笔记ID');
# 查看爬虫日志
SELECT * FROM spider_logs ORDER BY created_at DESC LIMIT 20;
# 查看 Cookie 状态
SELECT id, account_name, is_valid, fail_count FROM account_pool;# 运行全面测试（50个测试用例）
uv run tests/test_phase5_full.py
# 运行 Phase 2 Cookie 测试
uv run tests/test_phase2_cookie.py
# 运行 Phase 4/5 测试
uv run tests/test_phase4.py
uv run tests/test_phase5.py
# 运行 Phase 6 小红书测试（19个用例）
uv run tests/test_phase6.py- 本项目仅用于技术学习和研究，禁止将抓取数据用于商业用途
- Cookie 需手动从浏览器获取，支持多账号轮询
- B站搜索无需 Cookie 即可工作（降级模式），但评论需要登录态
- 小红书搜索和详情必须有 Cookie（签名依赖 a1 字段），无 Cookie 无法工作
- 默认调度: B站每2小时、小红书每3小时、抖音每4小时、日志清理每天凌晨3点（可通过 .env 覆盖）
MIT