OneUptime 连接 Microsoft Teams 工作区指南：从账号授权到告警与事件通知规则配置

OneUptime 连接 Microsoft Teams 工作区指南：从账号授权到告警与事件通知规则配置

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本文以 OneUptime 的 Workspace Connection 功能为主线，完整讲解如何把 Microsoft Teams 接入 OneUptime 项目，并把事件（Incident）、告警（Alert）与计划维护（Scheduled Maintenance）通知投递到 Teams 频道。读完本文，你将掌握账号级 OAuth 授权、团队级应用安装（含私有频道与共享频道的边界）、基于规则的频道通知配置，以及自托管部署下 Bot 消息端点的网络可达性要求。

一、接入前准备：账号与项目

在开始任何配置之前，需要先具备两样东西：

1. 一个 OneUptime 账号。前往 oneuptime.com 注册后登录。
2. 在账号下创建一个项目（Project）。Workspace 连接、通知规则等所有配置都以项目为边界隔离，Teams 授权令牌、安装的团队列表和通知规则都归属于某一个具体项目。

创建项目后，整个 Teams 接入链路才能有归属地：后续 OAuth 授权回调中的state参数会携带projectId:userId两个标识（见下文源码分析），OneUptime 正是借此把 Microsoft 身份与你的项目和用户一一对应。

二、连接 Microsoft Teams 到 OneUptime 项目

在 OneUptime 控制台进入项目设置（Project Settings）>Microsoft Teams，按照页面提示完成 Microsoft Teams 账号与当前项目的连接。

这一步在底层发生的是标准 OAuth 2.0 授权码流程，对应源码位于 Common/Server/API/MicrosoftTeamsAPI.ts：

• 浏览器跳转到GET /api/microsoft-teams/auth，该端点要求同时配置了MICROSOFT_TEAMS_APP_CLIENT_ID与MICROSOFT_TEAMS_APP_CLIENT_SECRET，并通过state参数（格式<projectId>:<userId>）携带项目与用户标识；
• 回调携带授权码后，服务端向https://login.microsoftonline.com/common/oauth2/v2.0/token换取访问令牌（grant_type=authorization_code），请求 scope 固定包含：
  • https://graph.microsoft.com/User.Read
  • https://graph.microsoft.com/Team.ReadBasic.All
  • https://graph.microsoft.com/Channel.ReadBasic.All
  • https://graph.microsoft.com/ChannelMessage.Send
• 随后调用https://graph.microsoft.com/v1.0/me获取用户资料，并把用户级令牌写入WorkspaceUserAuthToken（workspaceType 为MicrosoftTeams）；
• 若项目尚未完成管理员授权，则跳转至管理员同意流程。

管理员同意流程对应两个端点（同样是state=<projectId>:<userId>）：

• GET /api/microsoft-teams/admin-consent：向https://login.microsoftonline.com/<tenant>/v2.0/adminconsent发起租户级授权；
• GET /api/microsoft-teams/admin-consent/callback：回调中携带tenant、admin_consent等参数，OneUptime 使用client_credentials换取应用级 Graph 令牌，将tenantId、appAccessToken、availableTeams等数据合并写入WorkspaceProjectAuthToken，并把该租户 ID 作为workspaceProjectId持久化——这是后续「一个微软租户只能连接一个项目」判断的数据基础。

三、把 OneUptime 应用添加到每个团队（必做步骤）

仅连接账号远远不够。Microsoft 只允许 OneUptime Bot 向「已经添加了该应用」的团队发消息，因此必须为每一个需要接收通知的团队单独执行安装。

正确操作方式：

1. 在 Microsoft Teams 中点击团队名称（注意不是频道名称）旁边的...；
2. 选择管理团队（Manage team）>应用（Apps）>更多应用（More apps）；
3. 找到OneUptime，点击添加（Add）。

需要特别区分的三种安装边界：

场景	能否向团队频道发消息	说明
个人安装（Installing for yourself）	否	属于个人维度安装
添加到聊天（groupChat）	否	仅作用于该聊天
添加到团队（team）	是	唯一能让 Bot 向该团队频道发消息的安装方式
添加到私有频道（private channel）	视情况	私有频道必须在频道自身内部安装：打开频道 >...>管理频道（Manage channel）>应用>添加应用；仅做团队级安装不会覆盖私有频道
共享频道（shared channel）	否	Microsoft Teams 不支持 Bot 出现在共享频道中，OneUptime 无法向共享频道投递通知

典型排错信号：如果测试通知返回「OneUptime 应用未安装在该团队中」，几乎都是因为漏做了本步骤。

从源码看，OneUptime 之所以能给出「未安装」这类明确诊断，依赖 Teams 应用清单（Manifest）中的 Resource-Specific Consent（RSC）权限TeamsAppInstallation.Read.Group——它允许 OneUptime 在向某个团队发消息前确认该团队里安装的确实是本部署生成的 OneUptime 应用包。若缺少该权限，应用会退化为「未知」并把发送交给 Microsoft 去拒绝。清单的完整生成逻辑见 MicrosoftTeamsAPI.ts 中的getTeamsAppManifest()。

四、配置事件通知规则（Incident Notification Rules）

连接成功后，进入事件页面（Incidents Page）>Microsoft Teams，添加规则即可把事件通知投递到 Teams 频道。例如：创建一个「事件创建时向某 Teams 频道发消息」的规则。

规则的底层模型是 Common/Models/DatabaseModels/WorkspaceNotificationRule.ts（CRUD 端点/workspace-notification-rule），其核心字段决定了规则的行为边界：

• name/description：规则名称与描述；
• workspaceType：工作区类型，Teams 场景下取值为MicrosoftTeams；
• eventType：触发规则的事件类型（如事件创建、监控状态变更等），对应NotificationRuleEventType枚举；
• notificationRule：JSON 格式的具体规则体，包含目标团队、目标频道、要创建的频道等投递细节；
• projectId：规则归属项目，所有规则按项目隔离。

值得说明的是，规则是按需触发的：如果规则中开启了「创建 Microsoft Teams 频道（Create Microsoft Teams Channel）」，那么测试该规则时会真的创建频道并向其发消息——但这只能证明 Bot 能向「该频道所属的团队」发消息，不能证明其他团队也可达。真实通知是否到达，应以设置（Settings）> 通知日志（Notification Logs）中的记录为准，失败时日志会保留 Microsoft 返回的原始错误。

五、为告警与计划维护配置同样的通知

告警（Alerts）与计划维护（Scheduled Maintenance）的通知配置方式与事件完全一致：分别进入对应模块页面，按照同样的方式配置投递到 Teams 频道的规则即可。

OneUptime 为每一类实体提供了独立的消息构建器与动作处理器，源码结构位于 Common/Server/Utils/Workspace/MicrosoftTeams/：

• Messages/目录下的Incident.ts、Alert.ts、ScheduledMaintenance.ts、Monitor.ts等负责把实体状态渲染为 Teams 可识别的消息卡片；
• Actions/目录下的同名文件负责处理用户在卡片上的交互动作（如确认事件、跳转处理），并通过 Bot Framework 适配器接收用户的点击回调。

此外，个人维度的 Teams 绑定也有对应的直接消息能力：UserMicrosoftTeamsAPI.ts 提供POST /user-microsoft-teams/test端点，可向用户本人发送一条 Teams 私聊测试消息，用于在真实页面依赖它之前提前暴露「应用未为用户安装」这类可操作的错误。

六、底层链路：Bot Framework 与关键 API 端点

云托管与自托管场景下，Teams 集成的消息链路都依赖以下几个由 OneUptime 暴露的端点（全部位于 MicrosoftTeamsAPI.ts）：

端点	方法	作用
/api/microsoft-teams/auth	GET	OAuth 授权回调（state=<projectId>:<userId>）
/api/microsoft-teams/admin-consent	GET	发起租户级管理员同意
/api/microsoft-teams/admin-consent/callback	GET	管理员同意回调，换取并持久化应用级 Graph 令牌
/api/microsoft-bot/messages	POST	Bot Framework 消息端点，接收 Bot 消息、会话安装事件与卡片动作
/api/microsoft-bot/messages	GET	健康自检：返回405 Method Not Allowed即证明路由存在且部署可达
/api/microsoft-bot/test	GET	回显本部署的clientId、botId与消息端点
/api/microsoft-teams/app-manifest-zip	GET	下载本部署专属的 Teams 应用清单 ZIP 包
/api/microsoft-teams/teams、/channels、/chats	GET	拉取可选团队、频道与 Bot 已加入的会话列表

其中GET /api/microsoft-bot/messages是排查「Azure 是否可达本部署」最便宜的探针：返回405说明路由存在；若返回404且响应体是{"message":"Page not found - /api/microsoft-bot/messages"}，则请求已经到达OneUptime（通常是旧版本或前置代理剥离了/api前缀）；若返回的是 nginx/Ingress 的 HTML 错误页，则请求根本没到达应用。

七、自托管部署的网络访问要求

如果你运行的是自托管 OneUptime，Teams 集成的网络要求与云托管不同，完整细节见 App/FeatureSet/Docs/Content/en/self-hosted/microsoft-teams-integration.md。核心要点如下：

OneUptime 的 Teams 集成依赖 Azure Bot。Incoming Webhook 或 Teams Workflow URL 无法替代 Bot 的消息端点，Microsoft 要求自托管 Bot 必须有公网可达的 HTTPS 端点。

方向	目的地	用途
OneUptime → Microsoft	TCP 443 HTTPS 至 Microsoft Graph、Microsoft 身份与 Bot Framework 服务	令牌交换、团队/频道查询与通知投递
Microsoft → OneUptime	POST /api/microsoft-bot/messages	Bot 消息、会话安装事件与卡片动作
用户浏览器 → OneUptime	/api/microsoft-teams/auth与/api/microsoft-teams/admin-consent/callback	登录与管理员同意跳转

需要警惕的认知误区：OneUptime 向频道投递告警卡片时，是 OneUptime 主动调用 Microsoft 完成鉴权并发送，不需要Azure 能反向连回你；而卡片按钮点击、help命令、会话注册则全部依赖 Azure Bot Service 主动 POST 到/api/microsoft-bot/messages。因此「告警卡片能正常收到」只能证明出站投递正常，不能证明入站 Bot 端点可用——这也是最常见的「看起来半坏」状态。

自托管部署需要额外完成：

1. 创建 Azure App Registration（建议单租户），配置重定向 URI：https://your-domain.com/api/microsoft-teams/auth与https://your-domain.com/api/microsoft-teams/admin-consent/callback；
2. 在 API 权限中授予 Microsoft Graph 委托权限（User.Read、Team.ReadBasic.All、Channel.ReadBasic.All、ChannelMessage.Send）与应用权限（Team.ReadBasic.All、Channel.ReadBasic.All、TeamsAppInstallation.ReadForTeam.All），并执行管理员同意；
3. 创建客户端密钥（务必复制密钥值而非密钥 ID），创建 Azure Bot 资源，并把 Messaging endpoint 设为https://your-domain.com/api/microsoft-bot/messages；
4. 通过 Docker Compose 环境变量（MICROSOFT_TEAMS_APP_CLIENT_ID、MICROSOFT_TEAMS_APP_CLIENT_SECRET、MICROSOFT_TEAMS_APP_TENANT_ID）或 Helm values（microsoftTeamsApp.clientId/clientSecret/tenantId）注入配置，并重启服务；
5. 从项目设置 > 工作区 > Microsoft Teams下载应用清单，在 Teams 中通过「上载自定义应用」安装，再按本文第三节逐团队添加应用。

发布私有部署的 Bot 端点时，还需要把GET /api/microsoft-bot/messages的 405 探针、openssl s_client证书链校验、公网 DNS 解析检查纳入验收流程，并注意：完全没有入站连接受限策略（如完全断网隔离）的环境无法使用 Teams 集成——命令、卡片动作与会话发现都依赖 Microsoft 能访问 OneUptime。

八、常见问题速查

• 「OneUptime 应用未安装在该团队」：应用确实未安装（私有频道需在频道内安装），按第三节完成安装即可；
• 「Microsoft Teams 拒绝了消息，因为 Bot 不是该会话成员」（BotNotInConversationRoster）：依次排查 ① 团队里装的是否本部署清单生成的应用包（比对botId与MICROSOFT_TEAMS_APP_CLIENT_ID）；② Azure Bot 是否启用了 Microsoft Teams 频道；③ 应用是否仅个人安装而未加入团队；④ 目标频道是否为私有频道；
• 一个团队能收到、另一个团队收不到：安装是按团队逐个生效的，为每个需要通知的团队重复第三节；
• 「Test Rule」通过但真实通知不到：检查规则实际启用的目标；真实发送结果以设置 > 通知日志为准；
• 「找不到你的项目配置」：消息来源租户与项目连接的租户不一致（常见于来宾/B2B 账号），比对WorkspaceProjectAuthToken表中的workspaceProjectId与日志中的租户 ID；
• 「该 Microsoft 365 组织连接了多个 OneUptime 项目」：同一微软租户只能连接一个 OneUptime 项目，请在多余项目中断开 Teams 连接。

参考资料

• 本指南依据：workspace-connections/microsoft-teams.md
• 自托管完整配置：self-hosted/microsoft-teams-integration.md
• 核心 API 实现：Common/Server/API/MicrosoftTeamsAPI.ts
• 个人消息测试端点：Common/Server/API/UserMicrosoftTeamsAPI.ts
• 通知规则数据模型：Common/Models/DatabaseModels/WorkspaceNotificationRule.ts
• 消息与动作处理：Common/Server/Utils/Workspace/MicrosoftTeams/

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime