OAuth2 登录与群 Webhook 开放接入

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

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

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

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

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

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

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

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

2.1 三个工程各干什么

门户和授权页 分仓库部署，职责清晰：开发者 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 支持的授权方式

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 端配置步骤（操作向）

1. 用 beaver-desktop 2.0 进入目标群
2. 群详情 → 群助手 → 添加群助手
3. 类型选「通知机器人」，模板选「自定义机器人」
4. 填写展示名称、头像（可以是任意 https 图片 URL）
5. 保存后 复制 Webhook URL（含 token 参数）
6. 用 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 支持例如：

响应示例字段：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 适用场景示例

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

3.6 2.0 与 2.1 边界

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

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

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

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

1. OAuth 集成方 只会标准 OAuth2，不会为你单独写 fileKey 解析器。
2. Webhook 集成方 只有 Jenkins 插件、Shell curl、监控 Webhook 表单，字段里填 URL 最自然。
3. 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

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

功能清单仍以 48 号文 为准。45 号文偏 接入操作，46 / 47 偏 源码链路；50 / 51 是 产品功能 + 设计取舍，三份对照读最完整。

相关链接

项目源码：

• 后端源码：https://github.com/wsrh8888/beaver-server
• 移动端Flutter源码：https://github.com/wsrh8888/beaver-flutter
• PC端源码：https://github.com/wsrh8888/beaver-desktop.git
• 后台管理系统源码：https://github.com/wsrh8888/beaver-manager
• 开放平台门户源码：https://github.com/wsrh8888/beaver-open
• OAuth 授权登录页源码：https://github.com/wsrh8888/beaver-oauth
• Web SDK：https://github.com/wsrh8888/beaver-sdk

学习资源：

• 在线文档：https://wsrh8888.github.io/beaver-docs/

核心教学视频：

• 本地搭建教程合集：https://space.bilibili.com/269553626/lists/6075764?type=season
• 服务器部署教程合集：https://space.bilibili.com/269553626/lists/6075828?type=season