From 0411ed60e08cde354752b2089590ae31297d36e1 Mon Sep 17 00:00:00 2001 From: qql1 <2482076557@qq.com> Date: Sat, 20 Jun 2026 02:06:48 +0800 Subject: [PATCH 1/2] docs: add CLAUDE.md with platform compatibility notes and crawl issues --- CLAUDE.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..1d6ab7ae --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,42 @@ +# BettaFish 项目注意事项 + +## 爬虫平台兼容性问题 + +### 1. 抖音 (Douyin) — aweme_id/comment_id 类型不匹配 +- **根因：** MediaCrawler 的 `database/models.py` 中 `aweme_id` / `comment_id` 定义为 `BigInteger`，但 API 返回的是字符串。`_store_impl.py` 做了 `int()` 转换用于 WHERE 查询，但**没有把 int 值写回 `content_item` 字典**，导致 `DouyinAweme(**content_item)` 传给 asyncpg 时仍是字符串，PostgreSQL 报 `invalid input for query argument: str object cannot be interpreted as an integer`。 +- **影响范围：** PostgreSQL 环境下必现。MySQL 因隐式类型转换不会报错。 +- **修复方案：** 在 `store/douyin/_store_impl.py` 中，`aweme_id = int(content_item.get("aweme_id"))` 后加一行 `content_item["aweme_id"] = aweme_id`；`comment_id` 同理。 +- **建议：** 放弃抖音爬取，改用搜索 API Key（Tavily/Anspire）通过 QueryEngine/MediaEngine 获取实时数据。 + +### 2. 快手 (Kuaishou) — comment_id 类型不匹配 +- **根因：** 同抖音，`kuaishou_video_comment.comment_id` 在数据库中是 `bigint`，但 store 层传入字符串，PostgreSQL 报 `operator does not exist: bigint = character varying`。 +- **影响范围：** 视频数据可以正常爬取，评论写入失败。 +- **修复方案：** 在 `store/kuaishou/_store_impl.py` 的 `store_comment` 方法中，`comment_id` 做 `int()` 转换并写回字典。 +- **建议：** 放弃快手爬取。 + +### 3. 小红书 (Xiaohongshu) — humps.decamelize AttributeError +- **根因：** `pyhumps` 库版本不兼容。低版本和高版本的 API 不同，`extractor.py` 调用的 `humps.decamelize()` 在新版本中不存在。 +- **修复方案：** `pip install pyhumps==3.8.0` 锁定兼容版本。 +- **参考 Issue：** https://github.com/666ghj/BettaFish/issues/656 + +### 4. 知乎 (Zhihu) — 社区已知问题 +- **参考 Issue：** https://github.com/666ghj/BettaFish/issues/389（分页重复爬取） +- **参考 Issue：** https://github.com/666ghj/BettaFish/issues/399（字段类型不匹配） + +### 5. 贴吧 (Tieba) — 需要百度扫码登录 +- 首次使用需要人工扫码登录，无登录状态则超时失败。 + +## 部署注意事项 + +### PostgreSQL 与 asyncpg 版本 +- `requirements.txt` 中 `asyncpg` 没有锁定版本，最新版 0.31.0 对类型检查更严格，会暴露字符串传 BigInteger 列的问题。 +- Docker 镜像内置的 asyncpg 0.29.0 类型检查较宽松，不会报这个错。 +- 宿主机 `uv run` 安装时会获取最新版，需注意版本差异。 + +### 数据库初始化 +- **务必使用 Docker 容器内的代码初始化数据库**（通过 `docker exec bettafish python3 -c "from MindSpider.main import MindSpider; MindSpider().initialize_database()"`），因为容器内 `models_bigdata.py` 的 `aweme_id` 类型是 `BigInteger`，与 MediaCrawler 运行时模型一致。 +- 不要在宿主机上通过 `uv run python main.py --setup` 初始化数据库，宿主机代码可能包含不同的模型定义。 + +### 运行爬虫 +- 在宿主机用 `uv run python main.py --deep-sentiment` 运行爬虫，数据库指到 Docker 暴露的端口（`127.0.0.1:5444`）。 +- 运行前确认 `.env` 文件配置正确，且 shell 环境变量中没有 `DB_HOST` 等覆盖变量（可用 `DB_HOST=127.0.0.1 DB_PORT=5444 uv run ...` 明确指定）。 From 9109dd60960d750023a0eed735de345d721f346f Mon Sep 17 00:00:00 2001 From: qql1 <2482076557@qq.com> Date: Sat, 20 Jun 2026 02:31:29 +0800 Subject: [PATCH 2/2] docs: update CLAUDE.md with full platform compatibility test results --- CLAUDE.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1d6ab7ae..f31e94aa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,8 +23,15 @@ - **参考 Issue：** https://github.com/666ghj/BettaFish/issues/389（分页重复爬取） - **参考 Issue：** https://github.com/666ghj/BettaFish/issues/399（字段类型不匹配） -### 5. 贴吧 (Tieba) — 需要百度扫码登录 -- 首次使用需要人工扫码登录，无登录状态则超时失败。 +### 5. 贴吧 (Tieba) — 元素定位符失效 / 需要手动扫码登录 +- **根因：** 贴吧登录流程中，`login.py` 使用 CSS 选择器 `"//li[@class='u_login']"` 定位登录按钮，该选择器在当前贴吧页面结构上无法匹配。同时 `"//img[@class='tang-pass-qrcode-img']"` 无法找到二维码图片，30 秒超时后失败。 +- **影响范围：** 当前贴吧页面结构与爬虫代码中的定位符不匹配。 +- **建议：** 放弃贴吧爬取。 + +### 6. 平台兼容性一览 +- **✅ 可正常爬取：** 微博 (wb)、B站 (bili) +- **❌ 不可爬取：** 抖音 (dy)、快手 (ks)、小红书 (xhs)、知乎 (zhihu)、贴吧 (tieba) +- 不可爬取的平台数据可通过搜索 API Key（Tavily/Anspire）从前端界面获取实时数据。 ## 部署注意事项