OAuth2 登录与群 Webhook 开放接入

「、皓子~

340人浏览 · 2026-06-24 18:35:01

「、皓子~ · 2026-06-24 18:35:01 发布

海狸IM 功能深度解析（下）：OAuth2 登录与群 Webhook 开放接入

写在前面：开放能力不是「一个大平台」

很多人第一次看海狸的六个工程，会把 beaver-open 理解成「万能开放平台」——既能第三方登录，又能配 IM 事件回调，还能 @ 机器人问答。

2.0 的实际边界要克制得多。 按当前代码与门户功能，落地的是两条独立的线：

能力	2.0 状态	配置入口
OAuth2 第三方登录	✅	beaver-open + beaver-oauth
群通知单向推送（Webhook）	✅	PC 群助手
门户配置 IM 事件 Webhook	❌	—
群内 @ 机器人自动回复	❌	2.1 智能机器人

OAuth 管身份（谁登录了 OA）；Webhook 管通知（CI 往群里推一条消息）。协议不同、入口不同、部署时可 只开其中一个。下面分开讲透。

1. 两条线一张表：先别混

维度	OAuth2	群推送机器人
解决什么问题	第三方 Web/App 用海狸账号登录	外部系统往指定群发消息
谁发起	用户点「海狸登录」	服务器脚本 / 监控系统 POST
用户是否参与	是（授权确认、扫码）	否（单向推送）
涉及工程	open、oauth、server(open/auth)	desktop（配置）、server(bot_public)
协议	Authorization Code / Token	HTTP POST + Token
数据方向	用户 → 授权 → 第三方拿 Token	系统 → 群会话
与 avatar/fileUrl 的关系	用户信息接口返回可直接展示的 avatar URL	消息体里媒体字段是完整 url

部署、排错、写接入文档时，请把这两张表分开维护。45 号文里也有同样的对照，本篇从 功能解析 + 开发反思 角度再展开一层。

2. OAuth2：让 OA、门户、自研 Web 认海狸账号

2.1 三个工程各干什么

工程	谁打开	干什么
beaver-open	开发者 / 运维	创建 OAuth2 应用，拿 AppId、AppSecret，配 redirect_uri、Scope，Secret 轮换、Token 吊销
beaver-oauth	终端用户	授权确认 UI：展示应用名、权限范围；支持扫码、H5
beaver-server（open_api / auth_api）	后端	签发 Code、换 Token、用户信息、扫码状态流转

门户和授权页 分仓库部署，职责清晰：开发者 never 和用户授权页搅在一起。

beaver-manager 还有一层 OAuth 应用审核——运营通过/拒绝开发者提交的应用，适合内网「先审后接」的场景。manager 管运营，open 管开发者自助，别和 56 号要写的运营专题混为一谈，这里只点一句。

2.2 标准 Authorization Code 流程

从用户点按钮到 OA 建立会话，逻辑顺序如下：

① 用户在 OA 点击「海狸账号登录」
② 浏览器跳转 beaver-oauth 授权页（或展示二维码）
③ 用户在海狸 App 扫码 / 在页面上确认授权
④ 浏览器回调 OA 的 redirect_uri，URL 带 authorization_code
⑤ OA 后端用 code + AppSecret 向 beaver-server 换 access_token
⑥ OA 后端带 token 调用户信息接口，拿到 userId、nickName、avatar…
⑦ OA 建立自己的 session，用户登录完成

和 50 号文的 avatar URL 在这里接上：第 ⑥ 步返回的 avatar 必须是 https 完整地址。OA 前端通常直接：

<img src="{{ user.avatar }}" />

若只返回 fileKey，OA 还要对接 file 预览接口、处理 Beaver 登录态——每家接入方写一遍，文档和维护成本都爆炸。这是我坚持资料层存 URL 的核心原因之一。

2.3 Scope：限制第三方能读什么

创建 OAuth 应用时可配 Scope，限制第三方 Token 能读取的用户信息字段（昵称、头像、邮箱等）。这是私有化 IdP 的基本功：最小权限，避免一个内部小工具拿到过多用户数据。

Secret 轮换、Token 吊销在 open 门户完成；具体字段以 open_api 定义和文档站为准。

2.4 2.0 支持的授权方式

方式	典型场景
扫码登录	PC / Web 展示二维码，海狸 App 扫
OAuth2 Authorization Code	有后端的 Web 应用标准接入
H5 授权码	移动浏览器
OAuth Code 登录	2.0.1 服务端补充，可与 PC 登录联动

Web 侧还可参考 beaver-sdk（JS SDK），减少自己拼授权 URL 的错误。

2.5 常见接入场景

内网 OA、CRM、工单 统一「海狸账号登录」
自研 Web 把海狸 IM 当 身份提供方（IdP）
私有化部署、数据不出域，但希望 账号体系统一

2.0 不做的： open 门户不能配置 IM 消息事件订阅；不能在门户里创建群 Webhook——那是下一节。

3. 群 Webhook：外部系统往群里发消息

3.1 功能定义

2.0 的机器人类型是 通知机器人（群助手 →「自定义机器人」模板）：

群主 / 管理员在 PC 端 创建，设置名称、头像、描述
创建成功后得到带 Token 的 Webhook 推送 URL
外部系统 POST 该地址 → 群内出现一条 Bot 用户 发出的消息
PC / Flutter 群成员 收消息路径与普通人无异（WS + sync）

群聊详情与群助手

配置入口只在 beaver-desktop 群助手，不在 beaver-open。Flutter 2.0 能收 Bot 消息，不能在 App 里创建 Webhook。

3.2 PC 端配置步骤（操作向）

用 beaver-desktop 2.0 进入目标群
群详情 → 群助手 → 添加群助手
类型选「通知机器人」，模板选「自定义机器人」
填写展示名称、头像（可以是任意 https 图片 URL）
保存后 复制 Webhook URL（含 token 参数）
用 curl 或 Jenkins 发测试 POST，确认群内可见

启用 / 禁用、密钥重置、从群内移除，都在群助手界面完成。

3.3 服务端接口与消息类型

公开接口定义在 app/open/open_api/api/bot_public.api：

POST /api/open/bot_public/v1/send

Query 带 token（Webhook Token）；可选 timestamp + sign 做 HMAC 签名校验。Body 里 msgtype 决定消息形态，2.0 支持例如：

msgtype	用途	媒体字段特点
text	纯文本	可带 @ 信息
markdown	标题 + 正文	`image` 字段为配图 URL
image	图片消息	`url` 为图片完整 URL
video	视频	`url`、`thumbnailUrl`
file	文件	`url`
voice / audioFile	语音 / 音频	`url`
link	链接卡片	`url`、`imageUrl`
…	见 api 定义	均为 URL 或文本

响应示例字段：messageId、sendTime——方便调用方做对账。

注意看表： 几乎每种富媒体都是 url，不是 fileKey。这和 50 号里消息体 fileUrl、UserModel avatar 的设计 是同一条线——Webhook 集成方手里只有外链，不会先 upload。

3.4 一条 Webhook 消息进群后的链路

外部系统 POST bot_public/v1/send
    → Gateway 放行 bot_public 路由
    → logic 校验 Token（+ 可选签名校验）
    → 写入群会话（Bot 作为 sender）
    → 与普通群消息相同：落库 → MQ → WS 推在线成员
    → 离线成员：datasync + chatSync 补消息

Bot 在 user 表里 userType=2（推送机器人），和 OAuth 无配置依赖。只想要 CI 通知、不要 OAuth 的场景，部署 server + desktop 即可。

技术细节（MQ、tableUpdates）见 46 / 47 号文；本篇只强调：Webhook 消息和用户消息走同一套聊天管道，所以群里看起来就是「多了一个机器人账号在说话」。

3.5 适用场景示例

场景	说明
运维告警	Prometheus / Zabbix 触发后 POST，值班群收到告警
发布通知	Jenkins / GitLab CI 推送构建结果、版本号
定时报告	Cron 脚本推日报、周报摘要
流程通知	审批系统结束后推结果到业务群

不适合： 用户在群里 @ 机器人提问、机器人读群消息自动回复、在 open 门户订阅「任意群消息回调」——这些 2.0 没有，2.1 规划智能机器人。

3.6 2.0 与 2.1 边界

能力	2.0	2.1 规划
单向 Webhook 通知	✅
群内 @ Robot 对话	❌	智能机器人
open 门户统一配 Webhook	❌	可能收敛入口
IM 事件订阅回调业务服	❌	—

2.0 的 Bot 是 通知型，不是 ChatGPT 式问答；别在 2.0 里找交互式 Robot。

4. 开发反思：开放接入如何反过来塑造数据模型

做 IM 核心时，我默认观众是 自研 PC + Flutter 客户端——upload 接口、preview 路由、本地缓存，闭环在自己手里。

一旦 2.0 承诺 OAuth 和 Webhook，观众变成了 未知的第三方：

OAuth 集成方 只会标准 OAuth2，不会为你单独写 fileKey 解析器。
Webhook 集成方 只有 Jenkins 插件、Shell curl、监控 Webhook 表单，字段里填 URL 最自然。
Bot 头像 创建时就可能是外部 CDN 地址，不会走 upload。

所以「库里存 fileKey、展示再换 URL」在 纯客户端时代 说得通；开放时代 会在三个入口同时撞墙。最终选择：

协议层（用户 avatar、消息 fileUrl、Webhook body）统一 完整 URL，互操作优先
存储层 file 服务仍保留 fileKey，自有上传走 upload → 拿 fileUrl 填入消息
安全层 若要加强，在 preview 网关做签名 / 时效，而不是改协议逼 Jenkins 改代码

这不是偷懒，是 IM 从「封闭客户端」走向「可集成」时的常见代价。以后 2.1 上 @ Robot、流式 AI，还会再碰「Bot 消息从哪来、媒体怎么存」——那是新一篇的故事。

5. 部署与验证清单

5.1 OAuth2 最小验证

beaver-server 已部署，open、auth 相关服务可用
beaver-open、beaver-oauth 前端可访问
门户创建测试应用，redirect_uri 与测试 OA 一致
走通扫码或 Code 流程，Token 能换用户信息
确认返回的 avatar 为可访问 URL

5.2 群 Webhook 最小验证

beaver-desktop 2.0，操作账号为群主或管理员
目标群创建通知机器人，复制 Webhook URL
curl POST text 类型测试消息
PC / Flutter 群成员均能看到
无需在 beaver-open 额外配置

5.3 常见问题

Q：门户里找不到 IM 事件 Webhook？
2.0 没有。群通知只通过 PC 群助手创建的 URL。

Q：OAuth 和 Webhook 必须一起部署吗？
否。只做登录 → open + oauth；只做群通知 → server + desktop 配机器人。

Q：beaver-open 和 beaver-manager 区别？
open 给 接入 OAuth 的开发者；manager 给 运营管理员（用户、审核、监控）。角色不同。

Q：移动端能创建机器人吗？
2.0 创建入口主要在 PC 群助手。

6. 「只私有化」意味着什么

海狸 不做官方公共 SaaS。开放能力全部连 你自己部署的 server：

open / oauth 跟你的域名
Webhook Token 只对你的群有效
用户数据、消息、文件在你自己的 MinIO / 磁盘

适合 内网 OA 统一登录、自建 DevOps 通知；不适合「接官方开放平台、用公共 AppId 就行」的模式——这是产品定位，接入前心里要有数。

7. 本篇小结与系列后续

本篇讲了什么：

OAuth2 三工程分工、Code 流程、Scope、与 avatar URL 的关系
群 Webhook 配置步骤、bot_public 接口与 msgtype、消息进群链路
开放接入如何逼回完整 URL 的开发反思
部署验证清单与常见 FAQ

后续功能解析（尚未撰写）：

计划篇	主题
52	好友与私聊
53	群聊（禁言、入群审批、@）
54	表情与动态
55	音视频 LiveKit、通知中心
56	beaver-manager 运营与审核
57	datasync 与离线（可对接 46/47）