OneUptime 连接 Microsoft Teams 全指南:账户连接、团队安装与通知规则配置
OneUptime 连接 Microsoft Teams 全指南:账户连接、团队安装与通知规则配置
本文是 OneUptime 工作区连接(Workspace Connections)系列中 Microsoft Teams 集成的完整操作指南。文章基于仓库文档 fa/workspace-connections/microsoft-teams.md(英文原文见 en 版本)展开,覆盖从创建 OneUptime 账户、连接 Microsoft Teams 账户,到为每个团队安装 OneUptime 应用、再到为事件(Incident)、告警(Alert)和计划维护(Scheduled Maintenance)配置 Teams 通知规则的完整链路,并补充自托管(self-hosted)部署下的网络访问要求。读完本文,你将掌握在 OneUptime 中打通 Microsoft Teams 通知所需的全部配置步骤、注意事项与底层原理,并能独立排查“测试通知成功但实际收不到消息”等典型问题。
一、整体流程概览
将 OneUptime 与 Microsoft Teams 打通,官方文档给出了五个关键阶段:
- 创建 OneUptime 账户并新建项目;
- 在项目中连接 Microsoft Teams 账户;
- 把 OneUptime 应用添加到每一个需要接收通知的团队(官方明确标注为“必做”步骤,也是最容易被遗漏的一步);
- 配置事件(Incident)通知规则;
- 为告警(Alert)与计划维护(Scheduled Maintenance)配置同样的规则。
其中第 3 步是整个集成的分水岭:仅仅连接账户并不足以让机器人发消息。Microsoft 只允许 OneUptime Bot 在“它被加入过的团队”中发帖,因此每一个需要通知的团队都必须单独完成应用安装。
从源码结构看,这套集成在仓库中由一条完整的服务链支撑:Bot 框架适配层 packages/Common/Server/Utils/Workspace/MicrosoftTeams/MicrosoftTeams.ts、API 路由层 packages/Common/Server/API/MicrosoftTeamsAPI.ts、以及数据模型层 packages/Common/Models/DatabaseModels/UserMicrosoftTeams.ts 与 WorkspaceProjectAuthToken.ts。后文会结合这些实现逐一展开。
二、第一步:创建 OneUptime 账户与项目
如果你还没有 OneUptime 账户,按以下步骤准备:
- 访问 OneUptime 官网注册账户(在托管云服务上使用,或选择自托管部署);
- 账户创建完成后,新建一个项目(Project)。后续 Microsoft Teams 的连接与通知规则都是挂在项目维度上的。
说明:对于自托管实例,创建账户与项目的方式相同,只是后台部署在你自己维护的环境中,具体部署方式可参考仓库根目录的 README.md 与 config.example.env。
三、第二步:将 Microsoft Teams 连接到 OneUptime 项目
在 OneUptime 项目中,按以下路径完成账户级连接:
- 进入 Project Settings(项目设置) > Microsoft Teams;
- 按照屏幕上的引导提示,将你的 Microsoft Teams(Microsoft 365 组织/租户)账户与 OneUptime 项目关联起来。
这一步本质上是 OAuth 授权:OneUptime 拿到访问令牌后,才能通过 Microsoft Graph API 读取团队与频道列表、向频道投递消息。在 MicrosoftTeamsUtil.ts 中可以看到,授权令牌(appAccessToken)会被保存在项目的 WorkspaceProjectAuthToken 记录中(miscData 字段),并在过期前通过 OAuth 2.0 client_credentials 流程自动刷新(令牌剩余有效期不足 5 分钟即触发刷新),确保长期稳定可用。
需要注意,账户连接不等于团队安装:连接授予的是租户级别的 Graph 读取能力,这也是频道选择器能看到“机器人其实发不了消息的团队”的频道的原因。真正能否发消息,取决于下一节的团队级安装。
四、第三步:将 OneUptime 应用到每个团队(必做)
这一步是官方文档中反复强调的重点。仅在账户层面连接还不够——Microsoft 只允许 OneUptime Bot 向“它被添加进去的团队”发消息。因此,对于每一个希望在其中收到通知的团队,都必须执行如下安装:
- 在 Microsoft Teams 中,点击团队名称(注意:不是频道名称)旁边的“...”按钮;
- 依次选择 Manage team(管理团队) > Apps(应用) > More apps(更多应用);
- 找到 OneUptime,点击 Add(添加)。
4.1 三个容易踩坑的注意事项
- 安装对象必须正确:为自己安装 OneUptime,或把它添加到一个对话(chat)中,属于另一种安装形态,都不能让它向团队频道发帖。只有“安装进团队”才算数。
- 私有频道(Private channels)需要单独安装:团队级别的安装不会覆盖私有频道。必须打开该频道 > “...” > Manage channel > Apps > Add an app,把应用安装到频道本身。
- 共享频道(Shared channels)无法接收通知:Microsoft Teams 不支持机器人出现在共享频道中,这类频道天然收不到 OneUptime 通知,无需尝试。
排查信号:如果发送测试通知时系统报告“OneUptime 应用未安装在团队中”,几乎可以断定就是漏掉了本步骤。另外从源码实现看,OneUptime 在诊断时会利用 Microsoft Graph 的
TeamsAppInstallation.ReadForTeam.All权限区分“应用确实没装”与“装了但是是别的包的机器人”,并据此给出精确的报错文案(对应 MicrosoftTeamsUtil.ts 中的MicrosoftTeamsAppInstallState枚举:Installed / NotInstalled / PermissionDenied / Unknown)。
五、第四步:配置事件(Incident)通知规则
账户连接完成、团队安装就绪后,就可以配置真正的通知规则了:
- 在 OneUptime 中进入 Incidents Page(事件页面) > Microsoft Teams;
- 添加一条把事件通知发送到 Microsoft Teams 的规则。例如,可以创建一条规则:当事件被创建时,在指定的 Teams 频道发布消息。
规则的判定逻辑在类型定义 NotificationRuleCondition.ts 中实现,支持基于过滤器(filters)的条件匹配(多个条件之间可取 AND 或 OR,空过滤器数组表示“全部命中”)。通知目标的载体在 BaseNotificationRule.ts 中定义,其中与 Teams 直接相关的字段包括:
| 字段 | 含义 |
|---|---|
shouldPostToExistingChannel |
是否投递到已有频道 |
existingChannelNames |
目标频道名(逗号分隔) |
existingTeam |
目标团队(仅 Microsoft Teams 使用) |
shouldPostToExistingChat |
是否投递到现有对话/群聊(仅 Teams) |
existingChatIds |
已安装 OneUptime 应用的 Teams 对话 ID 列表 |
此外,通知规则还支持“动态创建频道”的高级形态(见 CreateChannelNotificationRule.ts):当过滤器命中时自动 shouldCreateNewChannel,在指定团队中新建一个频道并把相关成员/团队邀请进去,还支持在事件/告警/计划维护进入终态(如已解决)时 archiveChannelAutomatically 自动归档该频道。这与官方文档中“创建一条规则,在事件创建时向 Teams 频道发消息”的场景一脉相承,属于同一套规则引擎的两种目标动作。
六、第五步:配置告警(Alert)与计划维护(Scheduled Maintenance)通知
事件通知规则配置好后,同样的模式可以复用到告警与计划维护:
- 进入对应的 Alerts(告警) 页面与 Scheduled Maintenance(计划维护) 页面;
- 在各自的 Microsoft Teams 小节中配置你期望的规则即可。
也就是说,Incident、Alert、Scheduled Maintenance 三类对象共享同一套工作区通知规则引擎。在服务端,三类对象各自的通知消息生成器分布在 WorkspaceMessages/Incident.ts、WorkspaceMessages/Alert.ts 与 WorkspaceMessages/ScheduledMaintenance.ts,它们最终都会调用 Microsoft Teams 专属的消息发送实现(Workspace/MicrosoftTeams/ 目录),将事件/告警/维护的标题、状态、时间等事实字段组织成 Teams 可渲染的卡片消息。
七、底层实现:机器人如何把消息送进 Teams
为了让读者对“配置背后的机制”有更立体的认识,这里结合源码补充三点实现细节(均可在 MicrosoftTeamsUtil.ts 中验证):
- Bot Framework 适配器:OneUptime 通过 Microsoft Bot Framework 的
CloudAdapter与TeamsActivityHandler实现机器人的入站/出站通信。适配器是单例缓存,且强制使用SingleTenant(单租户)应用类型,客户端 ID、密钥、租户 ID 分别来自环境变量MICROSOFT_TEAMS_APP_CLIENT_ID、MICROSOFT_TEAMS_APP_CLIENT_SECRET、MICROSOFT_TEAMS_APP_TENANT_ID(定义见 EnvironmentConfig.ts)。 - 双通道消息发送:向频道投递通知走 Microsoft Graph(
ChannelMessage.Send委托权限);机器人入站活动(安装事件、对话注册、卡片按钮点击、给机器人发消息)则通过 Azure Bot Service 回调 OneUptime 的/api/microsoft-bot/messages端点。 - 消息卡片渲染:OneUptime 会把 Markdown 格式的通知内容转换成 Teams 的
MessageCard结构化卡片(标题 + facts 键值对 + 可点击动作),并通过convertMarkdownTablesToHtml将 Markdown 表格转成 HTML 表格以适配 Teams 的渲染限制;在 1:1 私聊场景则使用 Adaptive Card。此外,卡片按钮(如确认事件、查看详情)对应Actions/目录下按对象拆分的动作处理器(Incident、Alert、ScheduledMaintenance 等),处理结果会回写 OneUptime 状态。
八、自托管部署的网络访问要求
原文档在最后专门提示:自托管部署必须关注网络访问。这一点非常关键——OneUptime 的 Teams 集成依赖 Azure Bot,而微软要求自托管机器人必须有一个公网可达的 HTTPS 端点。私有 IP、内部 DNS 名或员工 VPN 都无法让 Azure Bot Service 访问到你的 OneUptime 实例。完整细节见仓库中的 self-hosted/microsoft-teams-integration.md,核心网络方向如下表:
| 方向 | 目标 | 用途 |
|---|---|---|
| OneUptime → Microsoft | 443/TCP HTTPS 到 Microsoft Graph、Microsoft 身份与 Bot Framework 服务 | 令牌交换、团队/频道查询、通知投递 |
| Microsoft → OneUptime | POST /api/microsoft-bot/messages |
机器人消息、会话安装事件、卡片动作 |
| 用户浏览器 → OneUptime | /api/microsoft-teams/auth 与 /api/microsoft-teams/admin-consent/callback |
登录与管理员同意重定向 |
需要特别强调:出站方向与入站方向是相互独立的。即使告警卡片能正常从 OneUptime 发出并显示在 Teams 里,也不代表入站端点可达——机器人交互、会话发现、卡片按钮点击全部依赖微软能成功回调到你的实例。因此:
- 公网网关必须原样透传
/api/microsoft-bot/messages(保留方法、/api前缀、查询串、请求体与Authorization头),不要在该路由上叠加重定向、浏览器 SSO、验证码或代理登录; - 对外出站需放行
graph.microsoft.com、login.microsoftonline.com以及 Bot Framework 认证/频道端点(腾讯云/阿里云等环境的防火墙如需固定 IP 白名单,需注意微软不提供固定的 Bot Framework 入站 IP 白名单,且 Teams 客户端媒体 IP 段并不代表机器人 webhook 来源); - 若策略上完全禁止入站连接,则 Teams 机器人集成(命令、卡片动作、会话发现)将无法工作——完全断网隔离的部署无法使用 Teams 功能。
九、自托管完整接入(概述)
对于自托管实例,官方还提供了从零到一的完整接入文档(self-hosted/microsoft-teams-integration.md),其要点可概括为八步:
- 在 Azure 门户创建 App Registration(单租户,Redirect URI 填
https://你的域名/api/microsoft-teams/auth与.../admin-consent/callback); - 配置 Microsoft Graph 权限:委托权限
User.Read、Team.ReadBasic.All、Channel.ReadBasic.All、ChannelMessage.Send;应用权限Team.ReadBasic.All、Channel.ReadBasic.All与用于诊断的TeamsAppInstallation.ReadForTeam.All;并授予管理员同意; - 创建 Client Secret(注意复制的是“值”而非“机密 ID”);
- 创建 Azure Bot 服务,把 Messaging endpoint 设为
https://你的域名/api/microsoft-bot/messages,并用curl -sS -i从外网验证(返回 405 即正确,说明端点只接受 POST 且路由可达); - 在 Bot 资源中为 Microsoft Teams 启用 Channel;
- 在 OneUptime 中配置环境变量:Docker Compose 写入
MICROSOFT_TEAMS_APP_CLIENT_ID、MICROSOFT_TEAMS_APP_CLIENT_SECRET、MICROSOFT_TEAMS_APP_TENANT_ID;Helm 则在values.yaml的microsoftTeamsApp下配置clientId/clientSecret/tenantId,配置后需重启服务; - 在 Project Settings > Workspace > Microsoft Teams 下载 Teams 应用清单(manifest),再到 Teams 中通过 Apps > Manage your apps > Upload a custom app 上传(该清单由 MicrosoftTeamsAPI.ts 依据
MICROSOFT_TEAMS_APP_CLIENT_ID动态生成,因而每个部署的包都是专属的); - 按本文第四节的方法,把 OneUptime 应用添加到每一个需要通知的团队。
十、常见问题速查
结合原文档与源码,将高频问题的定位思路整理如下:
- 测试通知成功,但真实通知一直不到:检查规则实际启用的目标。规则只对它配置的目标生效——例如开启了“Create Microsoft Teams Channel”时,测试会在“被创建频道的那个团队”里发帖,并不能证明其他团队可用。可到 Settings > Notification Logs 查看每次测试发送的记录(包括微软返回的原始错误)。
- “The OneUptime app is not installed…”:微软 Graph 确认应用确实不在该团队(或私有频道)中,回到第四/八步完成团队级安装。
- “bot is not a member of that conversation”:微软拒绝了投递(其原始措辞为
BotNotInConversationRoster),且 OneUptime 无法确认应用缺失。按优先级排查:团队里装的是不是“别的部署的包”(商店里的公共 OneUptime 应用指向云端的 Bot,不会接受自托管实例的投递)→ Azure Bot 是否启用了 Teams 频道 → 应用是否只装给了个人/对话而没装进团队 → 目标是否为私有频道。授予TeamsAppInstallation.ReadForTeam.All可以让 OneUptime 直接告诉你属于哪一种。 - 一个团队能收到、另一个团队收不到:安装是按团队独立生效的,连接集成并不能覆盖其他团队,请对每个团队重复安装步骤。
- “Sorry, I couldn't find your project configuration”:机器人活动来自的 Microsoft 租户与任何 OneUptime 项目连接过的租户不一致(常见于 guest/B2B 账号),可在服务端日志中
grep "Project auth not found for tenant ID"并与WorkspaceProjectAuthToken表中workspaceType = 'MicrosoftTeams'的记录对比;也可通过/api/microsoft-bot/test端点检查本部署的机器人配置(client id/secret 是否设置、期望的消息端点与 bot id)。
十一、小结
至此,OneUptime 与 Microsoft Teams 的集成链路已经完整呈现:账户与项目准备 → 项目内连接 Teams 账户 → 逐个团队安装应用(必做) → 配置事件/告警/计划维护通知规则 → (自托管)打通网络与 Azure Bot 配置。把握住“账户连接 ≠ 团队安装”这一核心原则,再配合通知日志与 /api/microsoft-bot/messages 的入站验证方法,绝大多数连接与投递问题都能在几分钟内定位。若需更深入的自托管部署细节(Azure 权限矩阵、bot 端点发布、TLS 证书链验证等),可继续阅读仓库文档 self-hosted/microsoft-teams-integration.md。