海狸IM 2.0 开放能力说明：OAuth2 接入与群推送机器人

接上一篇《海狸IM 2.0 发版记录：六端工程拆分与主要变更说明》，本文单独说明 2.0 中与「开放」相关的两条实现路径：OAuth2 第三方登录 与 群推送机器人。内容为工程实践记录，供部署与二次开发时查阅。

1. 能力范围总览

2.0 的开放相关能力不宜笼统称为「全功能开放平台」。按当前代码与门户功能，实际落地情况如下：

能力	状态	涉及工程
OAuth2 第三方登录	已支持	beaver-open、beaver-oauth、beaver-server（open/auth）
群通知单向推送（Webhook）	已支持	beaver-desktop（配置入口）、beaver-server（bot_public）
开放平台门户配置 IM 事件 Webhook	未开放	---
群内 @机器人触发回复	未支持	---
机器人与用户双向对话	未支持	---

OAuth2 处理 身份接入 （谁登录了第三方系统）；群推送机器人处理 通知下发（外部系统向群内发送一条消息）。二者协议、配置入口均不同，部署时不应混用同一套配置流程。

2. OAuth2 接入说明

2.1 相关工程职责

工程	职责
beaver-open	开发者门户：创建 OAuth2 应用、配置 redirect_uri、Scope、密钥管理
beaver-oauth	用户侧授权页：展示授权确认、扫码登录确认 UI
beaver-server	open_api / auth_api：Token 签发、Code 交换、扫码状态流转

门户（open）与授权页（oauth）分仓库部署，前端职责分离：开发者配置走 open，终端用户授权走 oauth。

2.2 门户侧可配置项（beaver-open）

注册 OAuth2 应用，获取 AppId、AppSecret
配置回调地址（redirect_uri）
设置权限范围（Scope），限制第三方可读取的用户信息字段
Secret 轮换、Token 吊销

门户 不提供 IM 事件订阅、群内机器人交互等配置项。

2.3 支持的授权方式（2.0）

方式	典型用途
扫码登录	PC / Web 展示二维码，移动端海狸客户端扫码确认
OAuth2 Authorization Code	具备后端的 Web 应用标准接入
H5 授权码	移动端浏览器 H5 页面
OAuth Code 登录	2.0.1 服务端补充，可与 PC 端登录流程联动

2.4 扫码登录流程（逻辑顺序）

从用户操作角度，链路可概括为：

用户在第三方系统（如内部 OA）发起「海狸账号登录」
系统进入授权流程，展示二维码或跳转授权页
用户使用手机海狸客户端扫码
beaver-oauth 展示授权确认（应用名、权限范围）
用户确认后，beaver-server 完成 Token 签发
第三方系统凭 Token 建立会话

具体接口路径与参数以在线文档及 open_api 定义为准。

2.5 常见接入场景

内部 OA、CRM 等系统统一使用海狸账号登录
自研 Web 应用将海狸 IM 作为身份提供方（IdP）
需要私有化部署且希望账号体系统一的企业内网环境

Web 侧可参考 beaver-sdk（JS SDK）；细节见文档站 OAuth2 章节。

3. 群推送机器人说明

3.1 与 OAuth2 的区别

群推送机器人 不在 beaver-open 门户中配置 。创建与管理入口在 beaver-desktop 客户端：群详情 → 群助手。

服务端通过 bot_public 相关接口接收外部 HTTP 请求，将消息写入对应群会话。该路径与 OAuth2 应用管理无配置依赖，可独立使用。

3.2 功能定义

2.0 支持的机器人类型为 通知机器人（群助手内可选「自定义机器人」模板）：

群主或管理员在 PC 端创建机器人，设置名称、头像、描述
创建成功后获得带 Token 的 Webhook 推送 URL
外部系统向该 URL 发起 POST，即可在群内产生一条机器人发出的通知消息

数据流向为单向：

复制代码

外部系统（监控 / CI / 定时任务）
    → HTTP POST（Webhook 推送 URL）
    → beaver-server（bot_public）
    → 群聊会话中出现通知消息

3.3 当前不支持的行为

用户在群内 @机器人并期待自动回复
机器人拉取并处理群消息内容
在 beaver-open 门户订阅「群消息」等 IM 事件

若业务需要上述交互式机器人能力，2.0 尚未提供，需关注后续版本或自行在服务端扩展。

3.4 PC 端配置步骤

使用 beaver-desktop 2.0 进入目标群聊
打开群详情 → 群助手 → 添加群助手
类型选择「通知机器人」
模板选择「自定义机器人」，填写展示信息
保存后复制 Webhook 推送地址
使用脚本或监控系统 POST 该地址，验证群内是否收到消息

机器人启用状态、密钥重置、从群内移除等操作亦在群助手界面完成。移动端 2.0 以聊天为主，创建入口主要在 PC 端。

3.5 适用场景示例

场景	说明
运维告警	监控系统触发后 POST 推送地址，值班群收到告警文本
发布通知	CI 完成后推送版本号与构建结果
定时报告	定时任务推送日报、周报摘要
流程通知	审批结束后向业务群推送结果

不适合依赖 @机器人问答、自动建单回复等双向交互的场景。

4. 需求与实现路径对照

需求	建议路径	配置入口
第三方系统使用海狸账号登录	OAuth2	beaver-open + beaver-oauth
外部系统向群发送通知消息	群推送机器人	beaver-desktop 群助手
用户 @机器人提问	2.0 未实现	---
IM 事件回调至业务服务器	门户未开放	---

5. 部署与验证要点

5.1 OAuth2

beaver-server 已部署，且 open、auth 相关服务可用
beaver-open、beaver-oauth 前端已部署并可访问
在门户创建测试应用，配置合法 redirect_uri
按文档完成扫码或 Code 流程，确认 Token 可换取用户信息

5.2 群推送机器人

beaver-desktop 2.0 已安装，操作账号为群主或管理员
在目标群创建通知机器人并获取推送 URL
使用 curl 或监控脚本发送测试请求，确认群消息落库与展示
无需在 beaver-open 中为该机器人额外配置

部署细节见项目文档站；本地与服务器环境可参考已有部署教程。

6. 常见问题（技术向）

门户能否配置 IM 事件 Webhook？

2.0 不能。beaver-open 仅承担 OAuth2 应用管理。群通知推送通过 PC 端群助手创建的 Webhook URL 实现。

OAuth2 与群推送机器人是否必须同时部署？

否。二者可独立使用：仅做登录接入时部署 open + oauth；仅做群通知时只需服务端与 PC 客户端配置机器人。

beaver-open 与 beaver-manager 的区别？

beaver-manager 面向运营人员（用户、内容、监控）；beaver-open 面向接入 OAuth2 的开发者。使用角色与功能域不同。

移动端能否创建推送机器人？

2.0 创建与管理入口主要在 PC 端群助手；移动端以消息收发为主。

7. 小结

海狸 IM 2.0 在开放能力上的实现较为克制：

OAuth2：门户 + 授权页 + 服务端，完成第三方登录接入
群推送机器人：PC 端配置 + 服务端 bot_public，完成单向通知推送

IM 事件订阅、@机器人交互等能力尚未在 2.0 开放。接入前应以上表「能力范围总览」为准，避免按商业 IM 开放平台的全套能力做架构假设。

参考链接

工程	地址	说明
beaver-server	https://github.com/wsrh8888/beaver-server	OAuth2、bot_public 接口
beaver-open	https://github.com/wsrh8888/beaver-open	OAuth2 应用门户
beaver-oauth	https://github.com/wsrh8888/beaver-oauth	用户授权页
beaver-desktop	https://github.com/wsrh8888/beaver-desktop	群推送机器人配置入口
beaver-sdk	https://github.com/wsrh8888/beaver-sdk	Web 侧 OAuth2 SDK
文档	https://wsrh8888.github.io/beaver-docs/	接口与部署说明

上一篇： $海狸IM 2.0 发版记录：六端工程拆分与主要变更说明$ (44.海狸IM 2.0 正式发布：全端能力大升级.md)