OAuth2 登录与群 Webhook 开放接入

「、皓子~2026-06-25 10:20

海狸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 前端通常直接：

html 复制代码 
<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 端配置步骤（操作向）

  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 支持例如：

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 ，观众变成了 未知的第三方：

  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

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

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

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

相关链接

项目源码：

学习资源：

核心教学视频：

热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07轻量化AI渗透武器库｜ARTEX自主攻防系统、资产梳理、漏洞挖掘、链路分析全流程智能化落地08Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）09Telegram APK 下载安装完整指南 — 2026年最新10微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新