版本历史
> 每次迭代更新此表，按时间倒序。
| 版本 | 日期 | 变更内容 |
|---|---|---|
| v3.12 | 2026-06-05 | 🔧 第五轮 Review 修复 (3 项)。P0: get_entity 短 FloodWait 重试后不回溯 (B16)、resume 误跳过 rate_limited/partial 频道 (B18)。P1: dry-run 过滤说明从 "backfill" 修正为 "discover" 关键词 (B17)。重构 _backfill_channels: get_entity 提取为重试包装器，移除笨重的内嵌 retry 逻辑 |
| v3.11 | 2026-06-05 | 🚀 实战 Review 修复 (10 项)。P0: YAML 追加改用 dump 全量重写 (B13)、get_entity FloodWait + ChannelPrivateError 专用 catch (B14)、run_hybrid discover 后 load_targets 失败兜底 (B15)。P1: YAML 写入后校验 + 失败回滚 (D10)、追加前 .bak 备份 (D11)、asyncio disconnect 先于 loop.close (D12)。P2: targets_common.yaml 自动修复脚本、短 FloodWait 分级处理 |
| v3.10 | 2026-06-05 | 🚀 三轮 Code Review 全面修复 (13 项)。P0: title 二次过滤/discover 阶段2.5 用生态词、_parse_channel_from_link UnboundLocalError、run_backfill 缺 rules→TypeError。P1: FloodWaitError 全局覆盖、save_message 原子去重 (INSERT OR IGNORE)、media_files 同事务写入。P2: iter_messages FloodWait 保底、--purge-after-export VACUUM、VACUUM<10MB 跳过。P3: --skip-discover/--match-mode word|regex/YAML 追加保留注释/monitor progress 写入/rstrip 清理 |
| v3.9 | 2026-06-05 | 🧹 数据保留策略。新增 --retention-days（默认 90 天自动清理）、--no-vacuum、--purge-after-export。新增 media_files 表追踪媒体文件。每次运行结束后自动清理过期消息、媒体文件和断点记录。新增 run_retention_cleanup() 统一入口 |
| v3.8 | 2026-06-04 | 🔧 backfill 发送者信息获取修复。新增 --fetch-sender 参数，通过 SenderCache（内存缓存） + 批量延迟策略安全获取发送者名称和用户名，避免 Flood Wait。新增 database.update_senders_batch() 延迟补充机制 |
| v3.7 | 2026-06-03 | 🔒 failover 安全加固。failover 必须用专属 code_acc{N}.txt，禁止共用验证码；不可恢复错误（2FA/密码/AuthKey）不触发 failover；连接失败后自动 disconnect |
| v3.6 | 2026-06-03 | P2: dry-run 模式。新增 --dry-run，不连接 TG 打印执行计划 |
| v3.5 | 2026-06-03 | P3: 账号自动 failover。新增 --failover 参数，主账号 Flood Wait/凭证缺失时自动尝试后续账号 |
| v3.4 | 2026-06-03 | P2: 数据库导出 CLI。新增 --export/--export-format/--since/--until/--chats 参数，支持 csv/json/markdown 三种格式导出 |
| v3.3 | 2026-06-03 | P1: 搜索 Bot 结果 title 二次过滤。利用回溯阶段 get_entity 获取真实 title，不匹配的跳过 iter_messages |
| v3.2 | 2026-06-03 | P1: hybrid 断点续传。新增 channel_progress 表 + --no-resume 参数 |
| v3.1 | 2026-06-03 | P1: backfill 新频道相关性过滤。hybrid stage2 跳过 title/username 与关键词不匹配的新频道 |
| v3.0 | 2026-06-03 | P0: discover/backfill 关键词分离、6 行业 targets 分文件、三账号代理隔离、SOCKS5 认证 |
| v2.0 | 2026-06-03 | 三账号支持、TG Web 应急扫描、行业适配策略、羊毛频道预置、实战经验库 |
| v1.0 | 2026-06-02 | Skill 化，四模式，71 频道，单账号 |
| 原型 | 2026-05-20 | 初始原型，66 外挂频道，backfill + monitor |
TG 爬虫 Skill
基于 Telethon 的 TG 频道/群组消息采集与舆情监控工具。
触发条件
当用户提到以下任一意图时触发：
- "扫描TG"/"搜一下 TG"/"TG 上有没有 XX 外挂"
- "回溯 TG 消息"/"爬一下XX频道的消息"
- "发现XX相关的TG频道"/"找一下XX的TG群"
- "监控 TG 频道"
- 更广义的舆情扫描任务中需要 TG 数据源时
⚠️ 核心规则：行业适配（必读）
TG 上不同行业的黑灰产分布在完全不同的频道生态中，搜索关键词必须根据目标行业调整。
| 行业 | TG 搜索关键词 | 禁止用 |
|---|---|---|
| 🎮 游戏 | 游戏名、外挂、辅助、破解 | 优惠券、漏洞单 |
| 🥛 快消/零售 | 优惠券、薅羊毛、漏洞、线报、Bug价、0元购 | 外挂、破解 |
| 💰 金融 | 套利、路子、代刷、水钱 | 优惠券、外挂 |
| 📱 App | 破解版、Mod、去广告、解锁 | 优惠券 |
| 💬 社交 | 交友、引流、号商、脚本、代聊 | 外挂 |
| ✈️ 航司 | 里程、积分、代订、机票诈骗、退改签 | 外挂 |
| 🚗 汽车 | 车贷、二手车、违章代办、改表 | 优惠券、外挂 |
两步法通用模式：
# 第1步：搜生态关键词 → 发现频道（用 discover 关键词）
# 第2步：在频道中搜品牌名 → 回溯消息（用 backfill 关键词）
python3 main.py --mode hybrid \
--keywords "生态词1,生态词2" \
--backfill-keywords "品牌名1,品牌名2" \
--targets <行业profile> \
--env ../config/.env
各行业两步法完整命令示例 → references/industry-playbook.md。
> 🛑 何时放弃 TG 渠道：目标行业是快消/传统零售/餐饮/医疗且 discover 阶段返回 0 频道 → 切到 web_search（微博/知乎/黑猫投诉）。
运行模式
| 模式 | 命令 | 说明 |
|---|---|---|
| hybrid | --mode hybrid --keywords "词" |
发现 + 回溯（推荐） |
| discover | --mode discover --keywords "词" |
仅发现频道 |
| backfill | --mode backfill --limit 500 |
对已有频道回溯 |
| monitor | --mode monitor |
7×24 实时监听 |
| export | --export results.csv |
导出数据（不连 TG） |
参数速查
| 参数 | 说明 | 默认值 |
|---|---|---|
--mode |
hybrid / discover / backfill / monitor | — |
--keywords |
discover 搜索关键词，逗号分隔 | — |
--backfill-keywords |
backfill 专属关键词，不传回退 --keywords |
— |
--targets |
配置文件路径 或 行业 profile (gaming/retail/social/airline/auto/all) | ../config/targets.yaml |
--backfill-limit |
单频道回溯消息条数 | 500 |
--account |
TG 账号 1/2/3 | 1 |
--failover |
失败后尝试后续 N 个备用账号 | 0 |
--no-bots |
禁用搜索 Bot | false |
--no-backfill-filter |
禁用新频道相关性过滤 | false |
--no-resume |
禁用断点续传 | false |
--fetch-sender |
🆕 获取发送者用户名/名称（缓存+批量延迟防Flood Wait） | false |
--sender-batch-size |
🆕 每批获取发送者数量 | 15 |
--sender-batch-delay |
🆕 批次间延迟秒数 | 3.0 |
--dry-run |
试运行：不连 TG，打印参数和频道数 | false |
--retention-days |
🆕 数据保留天数，自动清理过期消息/媒体/断点记录 | 90 |
--no-vacuum |
🆕 禁用清理后的 VACUUM 空间回收 | false |
--purge-after-export |
🆕 导出完成后清空数据库和媒体文件（需确认） | false |
--skip-discover |
🆕 hybrid 模式下跳过频道发现，仅回溯已有频道 | false |
--match-mode |
🆕 匹配模式: substring(子串)/word(词边界)/regex | substring |
--export |
导出文件路径（跳过采集） | — |
--export-format |
csv / json / markdown | csv |
--since / --until |
导出时间范围 YYYY-MM-DD | — |
--chats |
导出限定频道 (逗号分隔 username) | — |
--db |
数据库路径 | ../data/crawler.db |
--session |
Telethon session 名 | tg_crawler |
--password |
2FA 密码 | — |
--log-level |
DEBUG / INFO / WARNING / ERROR | INFO |
配置文件
.env（凭证 + 代理）
# 账号 1
TG1_API_ID=xxx
TG1_API_HASH=xxx
TG1_PHONE=+86xxx
TG1_PASSWORD= # 2FA（可选）
# 账号 2
TG2_API_ID=xxx
TG2_API_HASH=xxx
TG2_PHONE=+86xxx
# 账号 3
TG3_API_ID=xxx
TG3_API_HASH=xxx
TG3_PHONE=+86xxx
# SOCKS5 代理（可选，每账号可独立）
# TG1_PROXY_HOST=45.xx.xx.1
# TG1_PROXY_PORT=1080
# TG2_PROXY_HOST=45.xx.xx.2
# TG2_PROXY_PORT=1080
- 代理优先级：
TG{account}_PROXY_HOST>PROXY_HOST（全局回退） - 账号 1 支持向后兼容
TG_API_ID/TG_API_HASH/TG_PHONE - Session 自动区分：
tg_crawler.session/tg_crawler_acc2.session/tg_crawler_acc3.session - 🆕 发送者信息获取：
FETCH_SENDER_INFO=true启用 / CLI--fetch-sender临时启用（v3.8 新增，通过 SenderCache + 批量延迟策略防 Flood Wait）
targets.yaml（频道列表）
放在 config/，格式参考 references/targets-format.md。按行业分文件：
- targets_gaming.yaml — 76 个游戏外挂频道
- targets_retail.yaml — 5 个羊毛频道
- targets_common.yaml — 118 个自动发现的跨行业频道
- targets_social.yaml / targets_airline.yaml / targets_auto.yaml — 空模板
验证码
# 命令行传入
python3 main.py --code "12345" --mode hybrid --keywords "游戏名"
# 文件读取（非交互环境）
python3 main.py --code-file /path/to/code.txt --mode hybrid --keywords "游戏名"
# 交互式输入（默认）
python3 main.py --mode hybrid --keywords "游戏名"
注意事项
- Flood Wait：TG API 严格限速，单次避免过大
--backfill-limit - Session 文件：首次运行后生成，必须在
scripts/目录下运行main.py - 2FA：账号开启二次验证需传
--password - web_fetch 应急：Flood Wait 阻塞时可用
web_fetch https://t.me/s/{channel}?q={关键词}应急（限 ~20 条） - 私密群组：需
invite_link，否则无法加入
数据保留策略（v3.9+）
| 机制 | 默认值 | 说明 |
|---|---|---|
| 消息保留 | 90 天 | --retention-days N 调整，超期消息自动删除 |
| 媒体文件 | 关联删除 | 消息删除时关联的图片/视频同步清理 |
| 断点记录 | 同步清理 | channel_progress 的超期记录一并清理 |
| VACUUM | 自动执行 | 清理后自动回收磁盘空间，--no-vacuum 禁用 |
| 彻底清空 | 手动触发 | --export results.csv --purge-after-export 导出后清库 |
设计原则：
- 舆情数据的时效性天然有限（超过 90 天的历史消息情报价值极低）
- 自动清理避免 SQLite 数据库和 data/media/ 无限膨胀
- 每次采集运行结束后执行清理，不影响采集性能
已知限制
| 限制 | 应对 |
|---|---|
| Flood Wait 全阻塞 | 换账号/等冷却/--failover 自动切；短FloodWait(<60s)自动重试 |
| web_fetch 只能 ~20 条 | 应急用，不是 backfill 替代 |
| 频道发现仅限公开频道 | 私密群需手动提供 invite_link |
| CPS 推广频道信息密度低 | 采样分析，不必全量回溯 |
| 子串匹配误报 | 用 keyword_rules.match_mode=word 减少误报 |
| discover 重复搜索 | 用 --skip-discover 跳过发现阶段 |
| YAML 追加丢失注释 | v3.11 起用 dump 全量重写，注释不再保留（优先保证文件正确性） |
相关文档
- 行业两步法详细命令 + 羊毛频道预置列表 →
references/industry-playbook.md - 代理池自建方案（VPS 对比 + Dante 脚本） →
references/proxy-pool-setup.md - targets 格式说明 →
references/targets-format.md - 完整架构设计 →
references/tg-crawler-architecture.md - 爬虫源码 →
scripts/
