一步步教你部署Telegram频道历史消息定时清理机器人

功能定位：为什么需要“可审计的清理”

Telegram 频道消息一旦发出即写入云端，官方并未提供「到期自动删除」开关。对日更 200 条的资讯类频道而言，三个月后历史消息便突破 1.8 万条，带来三重压力：客户端拉取慢、管理员搜索卡顿、云端配额（虽无公开上限，但经验性观察显示超过 5 万条时 forward 接口偶发 420 错误）。

“定时清理机器人”因此出现：它通过 TDLib 遍历 message history，按设定策略调用 deleteMessages，并在本地留一份只读 SQLite 审计库，实现「云端瘦身 + 本地留痕」。与 Telegram 自带的「限时消息」「讨论组自动清理」不同，该方案面向频道主，兼顾合规与性能，且可回退。

2025 年接口边界与兼容性速览

TDLib 1.8.36 变更点

2025-10 发布的 TDLib 1.8.36 将 deleteMessages 的并发限制从每秒 50 条提升到 100 条，但新增 can_delete_message 权限校验：若机器人在频道中仅为「管理员」而非「拥有者」，只能删除自己发的消息。该限制直接影响脚本设计——必须在「拥有者」账号下运行，否则需降级为「标记 + 人工二次确认」模式。

平台差异小结

• Android：设置 → 频道信息 → 管理员 → 长按机器人账号 → 勾选「删除任意消息」。
• iOS：频道页 → 右上角笔形图标 → Administrators → 点选机器人 → 开启 Delete messages。
• 桌面版：右键频道 → Manage channel → Administrators → 勾选 Delete messages。

若缺少该勾选，TDLib 返回 error_code 400，日志关键字 MESSAGE_DELETE_FORBIDDEN，可作为排障首项。

决策树：先判断「值不值得清」

1. 订阅 ≤ 5k 且日更 < 10 条：直接关闭「搜索」即可，无需清理；因为客户端差异拉取耗时 < 300 ms，用户无感。
2. 订阅 > 50k 且存在「限时促销」内容：建议保留 90 天再清，否则旧链接失效导致客诉。
3. 频道已开启「讨论组」：清理前先备份 Thread 引用，否则讨论消息会显示「原消息已删除」，影响可读性。
4. 合规要求 ≥ 3 年留存：跳过自动删除，改用「归档 + 冷存」方案（见后文协同章节）。

若四条均通过，则进入「可清理」分支，继续下一章节。

技术选型：TDLib 还是 Bot API？

能力对比

维度	TDLib	Bot API
删除他人消息	✔ 拥有者可删任意	✘ 只能删机器人自己
遍历历史速度	约 3 000 条/分（100 并发）	无 getHistory，无法遍历
本地审计库	可写入 SQLite	需额外拉取再写入
运维门槛	需编译 C++ 依赖	HTTP 调用即可

结论：若目标为「频道历史清理」而非「个人聊天记录」，TDLib 是唯一可行路线；Bot API 只能做「用户自助删除」或「新消息限时」。

操作路径：30 分钟完成最小可运行版本

环境准备（以 Ubuntu 24.04 为例）

sudo apt update
sudo apt install g++ cmake zlib1g-dev libssl-dev gperf
wget https://github.com/tdlib/td/archive/v1.8.36.tar.gz
tar xzf v1.8.36.tar.gz && cd td-1.8.36
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
sudo make install

创建 Telegram 应用

登录 https://my.telegram.org → API development tools → 创建应用，记录 api_id、api_hash。此处生成的应用归属「拥有者」账号，后续删除消息才合规。

最小 Python 脚本（使用 python-tdlib 0.9.1）

import sqlite3, time, datetime
from telegram.client import Telegram

def on_auth_state_update(td_client, state):
    if state['@type'] == 'authorizationStateReady':
        print('>>> Logged in')

def delete_older_than_days(channel_id, days=30):
    cutoff_ts = int((datetime.datetime.utcnow() -
                     datetime.timedelta(days=days)).timestamp())
    offset, limit = 0, 100
    while True:
        hist = tg.call_method('getChatHistory', {
            'chat_id': channel_id,
            'limit': limit,
            'offset': offset
        })
        hist.wait()
        if not hist.update['messages']:
            break
        ids = [m['id'] for m in hist.update['messages']
               if m['date'] < cutoff_ts]
        if ids:
            tg.call_method('deleteMessages', {
                'chat_id': channel_id,
                'message_ids': ids,
                'revoke': True
            })
            # 写入审计库
            audit.executemany('INSERT INTO del(msg_id, del_ts) VALUES (?,?)',
                              [(i, int(time.time())) for i in ids])
            audit.commit()
        offset += limit
        time.sleep(1)  # 限速

if __name__ == '__main__':
    tg = Telegram(api_id=YOUR_API_ID, api_hash=YOUR_API_HASH,
                  phone='+86YOURPHONE', database_encryption_key='')
    tg.add_message_handler(on_auth_state_update)
    tg.login()
    audit = sqlite3.connect('audit.db')
    audit.execute('CREATE TABLE IF NOT EXISTS del(msg_id PRIMARY KEY, del_ts)')
    delete_older_than_days(channel_id=-1001234567890, days=90)
    tg.stop()

将脚本放入 systemd timer 或 cron，每日 02:00 运行，即完成「定时清理」。

例外与取舍：哪些消息必须跳过

固定消息（Pinned）

TDLib 返回的 message['is_pinned'] 为 True 时，应跳过；否则清理后频道顶部空白，用户误以为「频道被拉黑」。

带投票（Poll）

经验性观察：删除投票消息会导致对应 Poll ID 404，但已投票用户仍能在「已投票列表」看到选项，造成「结果悬空」。若频道用投票做决策，建议保留至少 180 天。

外链卡片（WebPage）

部分 SEO 工具通过 Telegram 外链做「快速收录」。清理后，搜索引擎再次抓取返回 404，可能降权。若频道为品牌官方，可仅删除文本而保留带外链消息。

与第三方归档机器人协同

若合规要求 ≥ 3 年留存，可在删除前将消息转发至「冷存频道」或「私有群」。该操作对 TDLib 而言只是额外 forwardMessages 调用，但需注意：

• 目标聊天必须与源频道在同一账号下，否则转发会暴露「来源频道」ID，引发隐私争议。
• 一次转发 ≤ 100 条，连续调用需间隔 1 秒，否则触发 429。
• 冷存频道建议关闭「搜索」与「成员列表」，降低被爬虫概率。

示例：某 30 万订阅的科技资讯频道采用「30 天热存 + 转发至私有群 + 云端删除」策略，半年后频道消息量稳定在 1.2 万条，客户端搜索响应从 1.8 s 降至 0.4 s，归档群仅 3 名法务账号可访问，满足上市公司审计要求。

故障排查：现象→原因→验证→处置

现象 1：脚本报 MESSAGE_DELETE_FORBIDDEN

可能原因：机器人未勾选「删除任意消息」；验证：在桌面版查看 Manage channel → Administrators → 机器人权限；处置：勾选后重跑，无需重启 TDLib。

现象 2：删除速度骤降，从 3 000 条/分跌至 300 条/分

经验性观察：当频道剩余消息 < 2 000 条时，Telegram 后端似乎进入「冷索引」，getChatHistory 延迟升高；验证：手动调用 getChatHistory 并记录响应头 @extra 时间戳；处置：可接受范围内维持现状，或一次性删完剩余消息后关闭任务。

现象 3：audit.db 中出现重复 msg_id

原因：脚本异常中断后重新运行，offset 计算基于消息序号而非唯一 ID；验证：SELECT COUNT(DISTINCT msg_id) FROM del；处置：在 delete 前加 INSERT OR IGNORE，或使用 PRIMARY KEY 冲突忽略。

验证与观测方法

为了量化清理效果，建议建立三条可观测指标：

1. 客户端拉取耗时：在 Android 10.12 版，打开频道 → 下拉刷新 → 抓 logcat 关键字 chatHistoryLoaded，记录毫秒级耗时；样本量 20 次取中位数。
2. 索引大小：桌面版 Settings → Advanced → Data and storage → Storage usage → 选中频道 → 查看「Messages」占用；该值与消息量呈线性正相关，经验系数 0.42 KB/条。
3. 云端 420 错误率：在 TDLib 日志过滤 FLOOD_WAIT_420，统计每小时触发次数；当剩余消息 < 1 万条时，错误率接近 0。

将三项指标写入 Prometheus exporter，即可在 Grafana 面板中可视化「清理 ROI」。经验性结论：当拉取耗时下降 50 % 且 420 错误率归零，可认为清理达到目标，继续延长保留周期不会带来额外收益。

适用/不适用场景清单

场景特征	适用	不适用
订阅量	≥ 10 k	< 5 k
日更频率	≥ 50 条	< 10 条
合规留存	≤ 90 天	≥ 3 年
消息类型	纯文本/图片	投票/外链卡片/固定消息
账号权限	频道拥有者	仅管理员

最佳实践 10 条速查表

1. 清理前先运行一次「只读统计」模式，确认将被删除的消息范围。
2. 保留 audit.db 与冷存频道双份证据，SQLite 文件放加密盘。
3. 使用 systemd timer 而非 cron，方便统一查看日志 journalctl -u tgclean。
4. 给脚本加 --dry-run 参数，通过环境变量切换，降低误操作概率。
5. 删除速率上限 100 条/秒，但建议限速 50 %，留出突发转发窗口。
6. 每周随机抽样 10 条已删消息，尝试通过冷存频道重新转发，验证备份完整性。
7. 若频道启用「签名」，删除后原作者仍可在个人聊天中看到消息，提前告知作者避免投诉。
8. 清理当日暂停广告投放，防止「广告已删但结算链接 404」引发纠纷。
9. 版本升级时，先在测试频道跑 24 h，对比旧版日志无 420 错误再切生产。
10. 每季度复核一次保留天数，若业务下降及时延长，避免过度清理导致 SEO 损失。

版本差异与迁移建议

TDLib 1.8.34 之前，deleteMessages 的参数名为 message_ids；1.8.35 起新增 revoke 布尔值，用于控制「是否从对方设备删除」。频道场景下 revoke 必须为 True，否则消息仍占云端索引。迁移时检查脚本关键字，如无该字段需补全，避免「假删除」。

另外，Telegram 桌面版 5.6.0 在 2025-09 引入「批量删除可撤销 5 秒」弹窗，该交互仅影响人工删除，对 API 调用无影响，但会误导测试人员以为「脚本失效」。建议在测试频道先人工删除一条，确认弹窗出现后再跑脚本，排除视觉干扰。

未来趋势与官方动向

2025-11 的 Telegram Beta 曾短暂出现「Auto cleanup after N days」开关，但次日在 10.13.0 被移除，说明官方仍在评估该功能对后端索引的影响。可以预期，若该功能正式上线，第三方清理脚本将退居「高阶定制」场景（如按标签删除、跳过投票）。建议持续关注 Beta 更新日志，一旦官方原生支持，优先切回官方开关，减少维护成本。

收尾：核心结论

部署 Telegram 频道历史消息定时清理机器人的本质，是在「性能-合规-用户体验」三角中寻找可审计平衡点。TDLib 提供了唯一可遍历删除的接口，但权限、限速、例外消息与备份策略缺一不可。通过 30 分钟最小脚本 + audit.db 本地证据链，你能在保证 90 天合规留存的同时，把 10 万条频道压缩到 1 万条以内，客户端拉取耗时下降一半以上。若未来官方推出原生「自动清理」，及时迁移至官方方案即可无缝交接，让脚本功成身退。