OAuth2 登录与群 Webhook 开放接入

海狸IM 功能深度解析下OAuth2 登录与群 Webhook 开放接入写在前面开放能力不是「一个大平台」很多人第一次看海狸的六个工程会把beaver-open理解成「万能开放平台」——既能第三方登录又能配 IM 事件回调还能 机器人问答。2.0 的实际边界要克制得多。按当前代码与门户功能落地的是两条独立的线能力2.0 状态配置入口OAuth2 第三方登录✅beaver-open beaver-oauth群通知单向推送Webhook✅PC 群助手门户配置 IM 事件 Webhook❌—群内 机器人自动回复❌2.1 智能机器人OAuth 管身份谁登录了 OAWebhook 管通知CI 往群里推一条消息。协议不同、入口不同、部署时可只开其中一个。下面分开讲透。1. 两条线一张表先别混维度OAuth2群推送机器人解决什么问题第三方 Web/App用海狸账号登录外部系统往指定群发消息谁发起用户点「海狸登录」服务器脚本 / 监控系统 POST用户是否参与是授权确认、扫码否单向推送涉及工程open、oauth、server(open/auth)desktop配置、server(bot_public)协议Authorization Code / TokenHTTP POST Token数据方向用户 → 授权 → 第三方拿 Token系统 → 群会话与 avatar/fileUrl 的关系用户信息接口返回可直接展示的 avatar URL消息体里媒体字段是完整 url部署、排错、写接入文档时请把这两张表分开维护。45 号文里也有同样的对照本篇从功能解析 开发反思角度再展开一层。2. OAuth2让 OA、门户、自研 Web 认海狸账号2.1 三个工程各干什么工程谁打开干什么beaver-open开发者 / 运维创建 OAuth2 应用拿 AppId、AppSecret配 redirect_uri、ScopeSecret 轮换、Token 吊销beaver-oauth终端用户授权确认 UI展示应用名、权限范围支持扫码、H5beaver-serveropen_api / auth_api后端签发 Code、换 Token、用户信息、扫码状态流转门户和授权页分仓库部署职责清晰开发者 never 和用户授权页搅在一起。beaver-manager还有一层OAuth 应用审核——运营通过/拒绝开发者提交的应用适合内网「先审后接」的场景。manager 管运营open 管开发者自助别和 56 号要写的运营专题混为一谈这里只点一句。2.2 标准 Authorization Code 流程从用户点按钮到 OA 建立会话逻辑顺序如下① 用户在 OA 点击「海狸账号登录」 ② 浏览器跳转 beaver-oauth 授权页或展示二维码 ③ 用户在海狸 App 扫码 / 在页面上确认授权 ④ 浏览器回调 OA 的 redirect_uriURL 带 authorization_code ⑤ OA 后端用 code AppSecret 向 beaver-server 换 access_token ⑥ OA 后端带 token 调用户信息接口拿到 userId、nickName、avatar… ⑦ OA 建立自己的 session用户登录完成和 50 号文的avatar URL在这里接上第 ⑥ 步返回的avatar必须是https 完整地址。OA 前端通常直接imgsrc{{ user.avatar }}/若只返回 fileKeyOA 还要对接 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-sdkJS 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.apiPOST /api/open/bot_public/v1/sendQuery 带tokenWebhook Token可选timestampsign做 HMAC 签名校验。Body 里msgtype决定消息形态2.0 支持例如msgtype用途媒体字段特点text纯文本可带 信息markdown标题 正文image字段为配图 URLimage图片消息url为图片完整 URLvideo视频url、thumbnailUrlfile文件urlvoice / audioFile语音 / 音频urllink链接卡片url、imageUrl…见 api 定义均为 URL 或文本响应示例字段messageId、sendTime——方便调用方做对账。注意看表几乎每种富媒体都是url不是 fileKey。这和 50 号里消息体fileUrl、UserModelavatar的设计是同一条线——Webhook 集成方手里只有外链不会先 upload。3.4 一条 Webhook 消息进群后的链路外部系统 POST bot_public/v1/send → Gateway 放行 bot_public 路由 → logic 校验 Token 可选签名校验 → 写入群会话Bot 作为 sender → 与普通群消息相同落库 → MQ → WS 推在线成员 → 离线成员datasync chatSync 补消息Bot 在 user 表里userType2推送机器人和 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.02.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 为可访问 URL5.2 群 Webhook 最小验证beaver-desktop 2.0操作账号为群主或管理员目标群创建通知机器人复制 Webhook URLcurl POSTtext类型测试消息PC / Flutter 群成员均能看到无需在 beaver-open 额外配置5.3 常见问题Q门户里找不到 IM 事件 Webhook2.0 没有。群通知只通过 PC 群助手创建的 URL。QOAuth 和 Webhook 必须一起部署吗否。只做登录 → open oauth只做群通知 → server desktop 配机器人。Qbeaver-open 和 beaver-manager 区别open 给接入 OAuth 的开发者manager 给运营管理员用户、审核、监控。角色不同。Q移动端能创建机器人吗2.0 创建入口主要在 PC 群助手。6. 「只私有化」意味着什么海狸不做官方公共 SaaS。开放能力全部连你自己部署的 serveropen / oauth 跟你的域名Webhook Token 只对你的群有效用户数据、消息、文件在你自己的 MinIO / 磁盘适合内网 OA 统一登录、自建 DevOps 通知不适合「接官方开放平台、用公共 AppId 就行」的模式——这是产品定位接入前心里要有数。7. 本篇小结与系列后续本篇讲了什么OAuth2 三工程分工、Code 流程、Scope、与avatar URL的关系群 Webhook 配置步骤、bot_public接口与 msgtype、消息进群链路开放接入如何逼回完整 URL的开发反思部署验证清单与常见 FAQ后续功能解析尚未撰写计划篇主题52好友与私聊53群聊禁言、入群审批、54表情与动态55音视频 LiveKit、通知中心56beaver-manager 运营与审核57datasync 与离线可对接 46/47功能清单仍以48 号文为准。45 号文偏接入操作46 / 47 偏源码链路50 / 51 是产品功能 设计取舍三份对照读最完整。相关链接项目源码后端源码https://github.com/wsrh8888/beaver-server移动端Flutter源码https://github.com/wsrh8888/beaver-flutterPC端源码https://github.com/wsrh8888/beaver-desktop.git后台管理系统源码https://github.com/wsrh8888/beaver-manager开放平台门户源码https://github.com/wsrh8888/beaver-openOAuth 授权登录页源码https://github.com/wsrh8888/beaver-oauthWeb SDKhttps://github.com/wsrh8888/beaver-sdk学习资源在线文档https://wsrh8888.github.io/beaver-docs/核心教学视频本地搭建教程合集https://space.bilibili.com/269553626/lists/6075764?typeseason服务器部署教程合集https://space.bilibili.com/269553626/lists/6075828?typeseason