fd-bot

七条腿,一套契约。

自托管的 IM 传输层。换出口不会断、凭据不出服务边界、发送失败会告诉你为什么。

A self-hosted IM transport layer. It knows what a platform lets you do — not what you want to do with it.

电报房 · WIRE ROOM 2026-11-20
平台入站出站能力依据
企微 · 智能机器人 wss url-keyed 实测
企微 · 自建应用 cb ip-gated
企微 · 群机器人 — url-keyed 只出不进
公众号 cb ip-gated
飞书 / Lark wss url-keyed
Slack cb url-keyed
Telegram poll url-keyed

★ 零入站主动发送实测成功。 url-keyed = 凭据在 URL/body/header 里,无调用方 IP 白名单,换出口不受影响。

实测

为什么要有这一层

WHY THIS LAYER EXISTS

协议代码原先住在每个应用进程里。改一句群文案要走出片链,加一个平台要改契约与闸三处,每个实例各自连平台。

搬出来之后:加一个平台 = 一个模块 + 一次重启。fd-bot 知道这个平台允许你做什么,不知道你要拿它做什么。

它只拥有一条语义——能力披露:每个适配器必须声明自己的出流形态,声明与发送代码同处一文件,服务启动即校验。缺声明不是警告,是进程起不来。这条规矩是被一次真实事故逼出来的:某条腿漏了声明,面板把一个能发的机器人报成了「寄不回去」。

这条腿,换出口也不会断

MEASURED, NOT DECLARED

企微智能机器人原先只有 HTTP 回调:只能在一小时的被动窗口内回复,且受「企业可信 IP」约束——出口一漂,回答全部寄不出去。换成长连接之后,我们主动外连,没有调用方地址可供平台加白,也没有被动窗口。

旧腿 · HTTP 回调 群 ──▶ ⏳ 1h 被动窗口 ──▶ ✗ 超窗即丢 IP 白名单 ──▶ 出口一漂即全断
新腿 · 长连接(我们拨出去) 群 ◀──────── wss ────────▶ fd-bot 零入站也能主动发送 ✓
360 ms零入站,主动发送 · 三次实测
308 mserrcode 0
291 ms滚版重连后复测

媒体同样经得起查:一条含图片的消息产出信封,信封里的取件地址返回 234,816 字节的真实 JPEG(magic ffd8ffe0)。篡改的票据与格式非法的票据都回 410。删掉正在跑的 pod,新 pod 无人值守地把两条长连接重新建立,绑定从 Postgres 回来,受理队列补发期间到达的消息。

契约

SIX ENDPOINTS, ONE ENVELOPE

方法路径做什么
POST /v1/bindings 建一条腿;返回能力与回调地址
GET /v1/bindings 列出,带连接健康
DELETE /v1/bindings/:id 停连接再退休(不硬删)
POST /v1/send 发送;失败带分类,不带 5xx
POST /v1/callbacks/:p/:s 平台回调(POST 与 GET 握手)
GET /v1/media/:ticket 短期取件地址

事件信封 · 调用方不必按平台分支解析

{ "platform": "wecom-bot", "bindingId": "b_mwo…", "chatKey": "wrqmGucgAAB…", "chatType": "group", "senderName": "…", "text": "@智语 你好", "media": [{ "kind": "image", "url": "/v1/media/…" }], "platformMessageId": "df0525f2a6ca…", "receivedAt": 1795180975208 }

三个常被问的事

THREE QUESTIONS

发送失败为什么返回 200?
因为「出口地址不被接受」和「被动回复窗口已关闭」是平台的判定,不是服务的故障。用 5xx 会让通用重试层去重试一个永远不会成功的调用。它们以 200 {ok:false, failure} 返回,分类由我们自己判定——不做平台措辞的子串匹配,那套语法平台随时能改。
媒体为什么给地址不给字节?
字节直传会把传输层变成一个需要配额的存储服务。信封里是 HMAC 签名的短期票据(默认五分钟),取件时才按需下载并解密。不接受调用方提供的任意 URL——SSRF 面在服务内部关闭。
服务挂了会怎样?
调用方拿到可判定的失败信号(连接失败/超时/非 2xx),自己决定排队还是告警。服务不会用空集或成功状态掩盖自己不可用——「传输层挂了」和「没人在发消息」必须是两个可区分的状态。

七条腿已经跑在生产上。源码、实测与运维手册都在仓库里。

打开仓库