从企业微信到QQ重构博客机器人

QQ 的签名模型清爽在哪#

QQ 机器人走 Webhook，核心是 Ed25519（而不是企微的 SHA1 + 自定义 AES）。两件事：

• 握手（op13）：QQ 给你发一个 plain_token 和 event_ts，你用私钥对 "plain_token" + plain_token + event_ts 签名返回，平台确认你持有私钥就算验证通过。
• 消息事件：每条推送带 X-Signature 头，值是 Ed25519(私钥, "https://bots.qq.com" + 请求路径 + 时间戳 + body) 的 base64。你本地按同样规则算一遍比对即可。

没全链路加密、没自定义块长的 AES、没 XML 套娃。验签就是验签，发消息走官方 API。

1
import * as ed from "@noble/ed25519";
2
import { sha512 } from "@noble/hashes/sha2.js";
3
ed.hashes.sha512 = sha512; // ⚠️ Workers 里必须手动注入，否则 ed.signAsync 会找不到哈希函数
4

5
// 握手
6
const sd = "plain_token" + plain_token + event_ts;
7
const sig = await ed.signAsync(new TextEncoder().encode(sd), privKey);
8
return Response.json({ plain_token, signature: b64(sig) });
9

10
// 消息验签
11
const concat = "https://bots.qq.com" + url.pathname + timestamp + body;
12
const sigBytes = base64ToBytes(signatureHeader); // X-Signature 头取出的 base64 解码
13
const ok = await ed.verifyAsync(sigBytes, new TextEncoder().encode(concat), pubKey);

一个差点栽的坑：@noble/ed25519 在 Cloudflare Workers 里必须手动把 sha512 挂上去（ed.hashes.sha512 = sha512）。不挂的话签名走的是它内部默认实现，在 Workers 运行时下会报「hash 未定义」——这个报错信息非常误导性，查了半天才反应过来是注入没做。

关键一步：把「接平台」和「写业务」拆开#

我一开始的想法是「再加个 Worker 专门跑 QQ」。一想不对——企微和 QQ 干的是同一件事：解析用户意图 → 发博文 / 动态 / 友链。平台差异只在「收消息、验身份、回消息」这三步。

于是我把结构改成了这样：

共享业务层 src/shared.js 只认一条统一结构 {msgType, content, fromUser}，根本不关心消息来自企微还是 QQ。两个平台各自把自家协议翻译成这条结构，丢给 dispatch 就完事。

1
// worker.js 入口（节选）
2
export default {
3
  async fetch(request, env, ctx) {
4
    const url = new URL(request.url);
5
    if (url.pathname === env.QQ_CALLBACK_PATH) return handleQQCallback(request, env, ctx);
6
    if (url.pathname === "/__qqmenu")  return qqSetMenu(env);   // QQ 自定义菜单
7
    if (url.pathname === "/__qqpanel") return qqSetPanel(env);  // QQ 指令面板
8
    if (url.pathname === "/api/apply-friend") return handleApplyFriend(request, env);
9
    if (url.pathname === "/friends.json") return r2Friends(env);
10
    // 其余交给企微适配器；它内部对「非企微请求」返回 null，由这里兜底 404
11
    const wxRes = await handleWechat(request, env, url, ctx);
12
    if (wxRes) return wxRes;
13
    return new Response("not found", { status: 404 });
14
  }
15
};

这里有个我挺满意的小设计：企微适配器不负责「路由归属」。它 export 一个 handleWechat，把企微相关的 GET 验签、POST 解密、各调试端点全收进去；对于「这请求根本不是企微的」情况返回 null，交给 root 兜底 404。这样 root 的 fetch 永远是「先 QQ、再各业务端点、再丢给企微、最后 404」，顺序清晰，互不越界。

代码分离的取舍#

我原本把企微逻辑整个抽成了独立部署的 wxbot/worker.js，后来觉得没必要——独立部署意味着企微回调地址要改、要管两份绑定、出问题时查两个地方。

最后方案是只分代码目录，不分架构：把企微那一坨挪进 wxbot/wx.js，root 用 import { handleWechat } 调它。线上还是同一个 Worker，企微回调地址一个字都不用动，QQ 和企微在同一进程里共存。对外部（企微后台、QQ 开放平台）来说，什么都没变。

1
import { dispatch } from "../src/shared.js";
2
export async function handleWechat(request, env, url, ctx) {
3
  // 企微全套：验签 / 解密 / 被动回包 / cf+hybrid 双模式 / 调试端点
4
  // 非企微请求 → return null
5
}

哪天真不想留企微了，删掉这一行 import 和这个文件夹就行，QQ 半边一行都不用碰。反过来想留企微、砍 QQ 也一样。平台成了可插拔的模块。

几个踩过的坑#

• Ed25519 的 sha512 注入：上面提过，Workers 里忘了 ed.hashes.sha512 = sha512 会莫名其妙报错，记住就好。
• X-Signature 的拼接串：必须是 "https://bots.qq.com" + path + timestamp + body 原样拼，少一段、顺序错、把 query 也算进去，验签全失败。建议直接拿官方示例的拼接方式对齐，别自己发挥。
• 企微收不到图片：企微的 media/get 受「可信 IP 名单」限制，Worker 出口 IP 不在名单里，下载素材会报 60020。所以图片一律改成链接写（封面：外链、![说明](外链)），适配器里根本不存图，只引导。这点 QQ 反而省心，能直接发图。
• 命令路由的正则：早期我用 /^\/(友链|friend|fl)(\s.*)?$/ 匹配，结果 . 不匹配换行，一发多行信息块就被当成普通博文吞了。改成「前缀式」/^\/(友链|friend|fl)(?:\s|$)/ 才行。