OneUptime 连接 Microsoft Teams 全指南:账户连接、团队安装与通知规则配置

原创2026-09-19 16:20:581,976 阅读
文章标签:可观测性后端运维前端云原生微服务AI Agent

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 打通,官方文档给出了五个关键阶段:

  1. 创建 OneUptime 账户并新建项目;
  2. 在项目中连接 Microsoft Teams 账户;
  3. 把 OneUptime 应用添加到每一个需要接收通知的团队(官方明确标注为“必做”步骤,也是最容易被遗漏的一步);
  4. 配置事件(Incident)通知规则;
  5. 为告警(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 账户,按以下步骤准备:

  1. 访问 OneUptime 官网注册账户(在托管云服务上使用,或选择自托管部署);
  2. 账户创建完成后,新建一个项目(Project)。后续 Microsoft Teams 的连接与通知规则都是挂在项目维度上的。

说明:对于自托管实例,创建账户与项目的方式相同,只是后台部署在你自己维护的环境中,具体部署方式可参考仓库根目录的 README.md 与 config.example.env。

三、第二步:将 Microsoft Teams 连接到 OneUptime 项目

在 OneUptime 项目中,按以下路径完成账户级连接:

  1. 进入 Project Settings(项目设置) > Microsoft Teams;
  2. 按照屏幕上的引导提示,将你的 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 向“它被添加进去的团队”发消息。因此,对于每一个希望在其中收到通知的团队,都必须执行如下安装:

  1. 在 Microsoft Teams 中,点击团队名称(注意:不是频道名称)旁边的“...”按钮;
  2. 依次选择 Manage team(管理团队) > Apps(应用) > More apps(更多应用);
  3. 找到 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)通知规则

账户连接完成、团队安装就绪后,就可以配置真正的通知规则了:

  1. 在 OneUptime 中进入 Incidents Page(事件页面) > Microsoft Teams;
  2. 添加一条把事件通知发送到 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),其要点可概括为八步:

  1. 在 Azure 门户创建 App Registration(单租户,Redirect URI 填 https://你的域名/api/microsoft-teams/auth 与 .../admin-consent/callback);
  2. 配置 Microsoft Graph 权限:委托权限 User.Read、Team.ReadBasic.All、Channel.ReadBasic.All、ChannelMessage.Send;应用权限 Team.ReadBasic.All、Channel.ReadBasic.All 与用于诊断的 TeamsAppInstallation.ReadForTeam.All;并授予管理员同意;
  3. 创建 Client Secret(注意复制的是“值”而非“机密 ID”);
  4. 创建 Azure Bot 服务,把 Messaging endpoint 设为 https://你的域名/api/microsoft-bot/messages,并用 curl -sS -i 从外网验证(返回 405 即正确,说明端点只接受 POST 且路由可达);
  5. 在 Bot 资源中为 Microsoft Teams 启用 Channel;
  6. 在 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,配置后需重启服务;
  7. 在 Project Settings > Workspace > Microsoft Teams 下载 Teams 应用清单(manifest),再到 Teams 中通过 Apps > Manage your apps > Upload a custom app 上传(该清单由 MicrosoftTeamsAPI.ts 依据 MICROSOFT_TEAMS_APP_CLIENT_ID 动态生成,因而每个部署的包都是专属的);
  8. 按本文第四节的方法,把 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。

登录后查看全文
oneuptime