没有公网 IP,也能接入钉钉和飞书:企业级 AI 平台的渠道网关设计
需求评审会上,客户的 IT 负责人只问了一句:我们这儿没有公网 IP,你们要是需要回调地址,这活儿就没法接。
这句话我听过太多次。做企业 AI 平台,第一关从来不是模型,是入口。没人会为了跟 AI 说句话专门去登一个新网站,他们就在钉钉里开会、在企微里审批、在飞书里写周报。所以"把 AI 塞进他们已经在用的 IM 里",基本是每个项目都绕不开的选项。
一落到交付,麻烦就来了:私有化部署在客户自己的机房里,没有公网 IP;没有域名,也没备案;就算有网络,客户安全规范也不允许随随便便开一个内网穿透。好不容易糊过去一层,后面还有验签、加解密、幂等、越权一堆事等着。
这篇讲我们把钉钉、企业微信、飞书、GitHub 四个渠道收进 BizBuddy 这个平台时的设计,重点在开头那个死结怎么解:没公网 IP,怎么让四端都接得进来,而且是同一套代码。
两种接入形态
渠道接入说穿了就两种形态。
一种是 Webhook。平台把消息回调到你暴露出去的 HTTP 接口上,你是被动的一方。这就要求你的服务在公网上有个可达地址,另外还得处理 URL 校验握手、报文解密和签名验证。
另一种是长连接。方向反过来了:你的应用主动去连平台网关,连上之后消息复用这条通道推过来。既然没有"入站连接"这回事,就不需要公网 IP,不需要域名,回调地址校验和报文加解密也一起省了——建连的那一刻就完成鉴权了。
| Webhook | 长连接 | |
|---|---|---|
| 谁先发起 | 平台回调你 | 你主动连平台 |
| 要公网地址 | 必须 | 不需要 |
| 回调 URL 校验 | 需要 | 不需要 |
| 报文加密 / 验签 | 基本都要 | 免了,建连即鉴权 |
| 断线怎么办 | 平台重试 | SDK 自己重连 |
| 谁支持 | 飞书、企微、GitHub | 钉钉、飞书(可选) |
所以"能不能免公网 IP",答案就一句话:看你选的平台有没有长连接形态。
钉钉只有长连接这一种(Stream),天生免公网。飞书两种都支持,官方后台二选一,我们两种都做了,让部署环境来定。企业微信和 GitHub 只有 Webhook,必须有公网可达地址——这是平台能力的边界,不是实现上偷懒。
既然运行期得知道某个渠道走的是哪种形态,渠道表就加了一列:
sql
-- ai_channel
mode varchar(16) not null default 'webhook' -- webhook | ws默认给 webhook,老数据不用动。飞书按这列分叉,钉钉恒为长连接、不读它——省得为历史行做一次数据迁移。
别做四个适配器
四个平台的差异比想象中大。钉钉的报文是明文 JSON,企微要 AES 解密,GitHub 要验 HMAC 签名,飞书加解密又是另一套。要是把这些差异直接铺到业务代码里,代码量一上来就没法维护了。
我们的做法是让它们在入站侧收敛成一个类型——用 AgentScope channel 扩展里的 InboundMessage:
钉钉 Stream ┐
飞书 长连接 │
飞书 Webhook ├─→ InboundMessage ─→ 统一入站管道 ─→ 无人值守执行 ─→ 各平台出站
企微 Webhook │
GitHub Hook ┘落到代码,是一个按平台装配的工厂类 AiChannelRuntime,核心是段 switch:
java
switch (channel.getPlatformType()) {
case AiChannel.PLATFORM_FEISHU -> {
String base = StringUtils.isBlank(apiBase) ? DEFAULT_FEISHU_API_BASE : apiBase;
if (AiChannel.MODE_WS.equals(channel.getMode())) {
// 长连接建连即鉴权、报文明文,不建验签和解密件
feishuStreamLocal = new FeishuStreamClient(
channel.getAppId(), channel.getAppSecret(), base, this::onFeishuPayload);
} else if (StringUtils.isNotBlank(channel.getEncryptKey())) {
feishuCryptoLocal = new FeishuCrypto(channel.getEncryptKey());
}
// 出站回复和媒体下载照旧走 OpenAPI,跟接入形态无关
feishuTokenProviderLocal = new FeishuAccessTokenProvider(base, appId, appSecret);
feishuOutboundLocal = new FeishuOutboundClient(base, feishuTokenProviderLocal);
feishuMapperLocal = new FeishuInboundMapper(channel.getChannelCode());
}
case AiChannel.PLATFORM_WECOM -> {
weComCryptoLocal = new WeComCrypto(verificationToken, encryptKey, appId);
// ... token / outbound / mapper
}
case AiChannel.PLATFORM_GITHUB -> {
gitHubVerifierLocal = new GitHubSignatureVerifier(channel.getWebhookSecret());
gitHubBotLoginLocal = StringUtils.trim(channel.getPlatformAgentId());
// ... outbound / mapper
}
case AiChannel.PLATFORM_DINGTALK -> {
// 长连接注册地址要自己派生,第二篇细说
}
default -> throw new IllegalArgumentException("不支持的平台类型:" + channel.getPlatformType());
}这段代码里有三个决定,都是踩出来的:
差异只在装配层出现。 业务层拿到的是 InboundMessage,它不认识"飞书 Encrypt Key"这种概念,也不需要认识。
出站跟接入形态解耦。 哪怕是长连接,回复还是走各平台的 OpenAPI。也就是说长连接解决的只是"收","发"的能力四个平台完全一致。
构件做成无状态、构造期不发网络请求。 这一点很重要——正因为这样,配置一改我们才敢直接重建装配,不用担心半途炸出个连接泄漏。
配置改了不重启
渠道配置改一次就重启一次服务,客户那边肯定不干。所以装配是按配置指纹缓存的:
java
// AiChannelRuntimeRegistry
String fingerprint = channel.getId() + "|" + channel.getUpdateTime();
if (cached != null && fingerprint.equals(cached.getFingerprint())) {
return cached; // 没变,复用
}
if (cached != null) {
stopQuietly(cached); // 变了,先停旧连接
}
AiChannelRuntime runtime = AiChannelRuntime.build(channel, ..., deduplicator, rateLimiter);
cache.put(channelCode, runtime);
startRuntime(runtime); // 首次装配或重建后立刻拉起指纹就是"渠道主键 + 更新时间",配置动过就重建,没动就复用。
长连接是应用主动连出去的,连没连上外面看不见,所以生命周期得有人管:
| 时机 | 做什么 |
|---|---|
| 应用就绪 | 把启用中的长连接渠道批量拉起来 |
| 管理面保存 / 删除 / 停用渠道 | 先停旧连接,再按新配置重建 |
| 应用关闭 | 全部停掉,释放连接 |
连接状态单独做了登记,回显到列表里的"连接状态"列:未启动、运行中、启动失败(带原因)。这条挺关键的——长连接断了不会有人来告诉你,只有自己盯。
消息进来之后才是正题
能收发消息只是 Demo 水平。真正决定这套东西能不能上生产的,是消息进来之后那几道关。
重复投递。 平台重试、多连接分派、重连补投,都会让同一条消息来两遍。我们用平台自己的事件 id 做幂等键(飞书是 event_id,钉钉是 msgId),状态写 Redis:
java
Optional<String> eventId = FeishuInboundMapper.extractEventId(payload);
if (eventId.isPresent() && !idempotency.firstSeen(channelCode + "|" + eventId.get())) {
return; // 重复事件,丢掉
}自环。 机器人回了消息,可能又被当成新消息投回来;群里两个机器人互相 @,能刷一屏。所以按"渠道 + 会话对端"维度做了限流:
java
if (!rateLimiter.allow(channelCode, message.peer().key())) {
log.warn("触发防自环限流:channelCode={}, peer={}", channelCode, message.peer().key());
return;
}身份。 这条是真正的安全边界。外部标识不是手机号也不是昵称——钉钉给的是 senderStaffId,飞书给的是 open_id——必须显式绑到平台账号上,没绑的一律拒绝:
渠道入站被拒(外部身份未映射):channelCode=dd_robot, externalUserId=xxxxxxxx刚上线时这条日志看着像故障,其实它是安全设计在工作。外部消息的能力,等于被绑定那个账号的权限。 要是"没绑定就回退到管理员",那群里任何人 @ 一下机器人就等于拿到管理员权限;要是回退到一个游客账号,外部渠道的数据访问又跟平台权限体系脱了钩,审计也对不上账。所以正确的做法只有一个:拒绝,并告诉对方去哪儿绑。
配映射时管理员最头疼的是"我该填什么标识"。后来我们干脆把这个查询做进了产品:渠道列表行内一个图标,输手机号查出标识,再一键预填到绑定表单。平台账号还是得管理员自己选——"标识绑到谁"是权限决策,不该被自动化。
会话。 外部世界的一"个群"和平台世界的一"个会话"不是一回事,中间得有一层映射(我们落成 ai_channel_thread)。同一个线程再来消息就续接原会话,上下文不丢;会话结束之后再发消息就新建并重绑,免得把旧话题带进来。
顺带说一句,渠道消息统一走无人值守通道:查资料、回答问题没问题,写类工具一律拒绝。边上没人在点确认,就不该让 AI 能动数据。
现在能做到什么
| 钉钉 | 飞书 | 企业微信 | GitHub | |
|---|---|---|---|---|
| 接入形态 | 长连接 | Webhook / 长连接二选一 | Webhook | Webhook |
| 免公网 IP | 可以 | 选长连接则可以 | 不行 | 不行 |
| 入站幂等 | 有 | 有 | 有 | 有 |
| 验签 / 加解密 | 建连鉴权 | 看形态 | EncodingAESKey | HMAC-SHA256 |
| 身份映射 | 有 | 有 | 有 | 有 |
| 会话映射 | 有 | 有 | 有 | 有 |
| 出站回复 | 有 | 有 | 有 | 有 |
| 按手机号查标识 | 支持 | 支持 | 不支持(要通讯录独立 secret) | 不支持(没这个概念) |
上线前建议对着这条清单过一遍
- 先定形态:没公网 IP 就优先长连接,钉钉没得选,飞书选
ws - 凭据密文落库,页面和接口都不回显明文
- 加
mode列时别忘同步存量库的增列语句(老库不会自己跑建表脚本) - 每个要用机器人的同事,各配一条身份映射
- 长连接形态确认单副本接收,集群模式下多副本会分摊消息
- 上线前把"机器人不回话"的排查顺序走一遍:连接状态 → 幂等 → 身份映射
最后
渠道接入的难点,从来不是"把某个平台的 API 调通"。真正花时间的是四件事:形态怎么选(它直接决定内网能不能落地)、差异怎么收敛、连接的生命周期谁来管、以及幂等限流身份会话这四关怎么补。
源码和文档都在 Gitee 上(zl3624/biz-buddy),渠道接入的核心类集中在 core/channel 包。下一篇钻最硬的部分:钉钉 Stream 和飞书长连接具体怎么写,以及三个必须守的官方约束。
关于 BizBuddy
BizBuddy 是一个全量开源的企业级智能体平台(MIT License):开源中后台底座(Spring Boot 4.1.1 / JDK 21)做底座,AgentScope Java Harness 做智能体内核,纯 Java 全栈、不含 Python,权限、审计、配额、多渠道接入等能力全部随仓库开源。
欢迎 Star、Issue 与共建。