Qzone3TG：把 QQ 空间搬到 Telegram，一个开源机器人是如何炼成的

当回忆中的说说遇上现代化的即时通讯

背景

QQ 空间是一个奇妙的产品。它承载了许多人的青春记忆——那些年的非主流说说、旅行照片、深夜感慨——但它的使用体验却停留在了十年前。推送不及时、移动端体验割裂、内容检索困难……越来越多用户希望换一种方式消费 Qzone 内容。

Telegram 则代表了另一种极端：纯粹的即时通讯体验、强大的 Bot API、跨平台无缝同步。如果把 Qzone 的说说实时推送到 Telegram，会怎样？

Qzone3TG（仓库名 Qzone2TG）就是这样一个项目。它是一个 AGPL-3.0 开源的 Telegram 机器人，能够将 QQ 空间的说说自动转发到 Telegram 频道或群组，并支持在 Telegram 内完成点赞、评论等互动操作。

两条核心链路

Qzone3TG 的内部架构可以概括为两条数据流水线。

链路一：抓取链路（Qzone → 本地队列）

机器人启动后，通过密码或二维码登录 Qzone，此后每 5 分钟发送一次心跳请求以维持登录态。心跳响应中会报告新的说说数量，有更新时立即触发抓取：

1. BaseApp._fetch() 获取互斥锁（防止并发冲突）
2. 调用 aioqzone-feed 库抓取最新的说说列表
3. 每条说说经过三道关卡——黑名单过滤（静态配置 + 动态黑名单表）、去重检测（数据库查 FeedOrm）、消息分割（Splitter）
4. 通过关卡的说会被加入发送队列

链路二：发送链路（本地队列 → Telegram）

发送队列是系统的核心，它从队列中取出说说，逐条发送：

1. 分割器（Splitter） 将一条说说解析为多个"消息原子"（MsgAtom）——纯文本用 send_message、单图用 send_photo、多图组成相册用 send_media_group
2. 每条消息自动附加内联按钮（赞/取消赞、评论、自定义表情）
3. 发送引擎 带重试机制（最多 2 次、指数退避），发送失败时自动重新下载媒体文件并重试
4. 发送完成后，保存 feed 与 message 的映射关系到 SQLite 数据库

消息原子化：优雅地处理 Telegram 限制

Telegram 对单条消息有严格限制（文本 4096 字符、媒体组最多 10 个），而一条 Qzone 说说可能包含长文本 + 20 张图片 + 视频。Qzone3TG 的解决方案是"消息原子化"：

MsgAtom 是一个抽象基类，每个 Atom 对应一次 Bot.send_* 调用。系统定义了六种具体原子类型：

• TextAtom：纯文本消息
• PicAtom：单张图片
• VideoAtom：单个视频
• AnimAtom：动图
• DocAtom：文档/大尺寸图片
• MediaGroupAtom：相册组（最多 10 个媒体）

分割器采用 pipeline 模式，每次从媒体列表中取出 Telegram 允许的最大数量构建一个 Atom，返回剩余部分继续处理。对于不确定类型的媒体文件，FetchSplitter 甚至会下载文件头来判断是 GIF、视频还是图片，确保发送格式准确。

在 Telegram 里玩转 Qzone

Qzone3TG 不仅是单向的转发工具，它还构建了完整的交互闭环：

• 点赞/取消赞：每条说说下方的按钮，点击即操作
• 评论：通过 FSM 对话状态机，与机器人对话即可发表评论
• 自定义表情：支持 Qzone 的表情系统
• 命令面板：/status 查看状态、/block 管理黑名单、/qr_login 扫码登录

所有操作都通过 aiogram 3.x 的 Dispatcher + Router 架构实现，消息回调数据经过序列化后存储在按钮的 callback_data 中，无需额外状态服务器。

双模式部署

Qzone3TG 支持两种启动模式：

• Polling（轮询模式）：简单直接，适合个人使用和调试
• Webhook（Webhook 模式）：生产环境推荐，通过 aiohttp 启动小型 HTTP 服务，接收 Telegram 服务器的回调

官方镜像托管在 GitHub Container Registry，通过 Docker Compose 一键部署。配置系统支持 YAML 文件、环境变量和 Docker Secrets 三种来源，敏感信息（Bot Token、QQ 密码）可以从文件中加载，不暴露在配置中。

幕后：可靠性与容错

一个长期运行的 Bot 会面对各种网络异常。Qzone3TG 的设计中处处体现了对不稳定的容忍：

• 心跳失败暂停：连续心跳失败自动暂停，避免频繁重试触发风控
• 发送重试：2 次重试 + 指数退避，网络波动时自动恢复
• 媒体降级：GIF 发送失败降级为图片，视频发送失败降级为链接
• 去重机制：相同内容不会重复发送
• 数据库清理：定时清理超过保留期限的历史记录

技术栈一览

层	技术
Qzone 接口	aioqzone + aioqzone-feed
Telegram Bot	aiogram 3.x
数据库	SQLAlchemy (async) + SQLite
定时调度	APScheduler
配置校验	Pydantic v2
重试策略	tenacity
部署	Docker 多阶段构建 / zipapp

结语

Qzone3TG 从一个简单的"转发说说"想法出发，成长为一个涵盖登录、抓取、处理、发送、交互全链路的成熟机器人项目。它的设计哲学是：把复杂留给自己，把简单交给用户。用户只需要一个 Docker Compose 文件，就能拥有一个自动同步 Qzone 到 Telegram 的个人助理。

如果你还在为错过朋友的 Qzone 更新而烦恼，或者想换个更现代化的方式回顾自己的青春说说，Qzone3TG 值得一试。

---

GitHub: github.com/aioqzone/Qzone2TG

文档: aioqzone.github.io/Qzone2TG

讨论群: t.me/qzone2tg_discuss