# AI SRE 自治排障 Agent Source: https://docs.flashduty.com/zh/ai-sre 对话式的自治 SRE Agent 平台，让 AI 自主调查故障、排查根因、沉淀运维知识，并与 Flashduty 故障响应体系深度联动 **公测功能**：AI SRE 已全量开放公测，无需申请，登录控制台即可直接使用，公测期间免费。功能与界面可能继续调整。 ## 什么是 AI SRE？ Flashduty AI SRE 是一个对话式的自治 SRE Agent 平台。你用自然语言下达指令，它便自主规划步骤、查询监控与日志、执行命令、调用外部工具（MCP），在需要时把子任务委派出去，最终给出有调查过程支撑的结论。 它不是只会问答的聊天机器人，而是一个**能动手的排障工作者**，并与 Flashduty 的故障响应体系深度联动：故障触发或开启作战室时，可一键拉起会话，让 Agent 带着故障上下文进入排查现场——既能在控制台对话，也能直接在你的 IM 群（Slack / 飞书 / 钉钉 / 企业微信）里 @ 它。 ## 核心能力 用自然语言描述问题，Agent 自主规划、调用工具、流式输出调查过程与结论 从故障或作战室一键拉起会话，Agent 携带上下文进入排查，沉淀的知识反哺下一次响应 以 DUTY.md 为入口的 Knowledge Pack 承载服务清单、runbook、值班路径等长期上下文 通过 Skill、MCP、A2A Agent 扩展能力；自托管 Runner 让排障进入你的内网 ## 典型场景 在控制台对话工作区提问：某服务为何异常、一条告警的根因、一次变更的影响范围 在 Slack / 飞书 / 钉钉 / 企业微信里 @ AI SRE 即可发起或续接排查，团队全程可见 为故障开启 IM 作战室时，AI SRE 自动跑一轮初步诊断并把结论回贴到作战室 用 /insight 复盘最近 30 天会话，量化运维摩擦并输出可复制的改进建议 ## 公测说明 AI SRE 已全量开放公测，无需申请，登录控制台即可使用。 公测期间 AI SRE 不单独收费。正式商用前，Flashduty 会提前提供计费信息。 生产变更、重启、回滚和外部通知，最终都由你确认后才会执行。 ## 快速开始 了解 AI SRE 的能力全景、公测使用条件与控制台导航 了解会话、流式输出、取消与上下文压缩，以及从故障拉起排查 在 IM 群里 @ Agent 排障，了解作战室自动诊断 用 /insight 复盘近 30 天会话，发现重复上下文与缺失 runbook # 更新日志 Source: https://docs.flashduty.com/zh/changelog/changelog 本页面记录 Flashduty 产品的重要更新和功能发布 ### 状态页嵌入组件（Widget） 公开状态页新增**嵌入组件**：一段可直接粘贴到任意网站 HTML 中的代码，把服务实时状态展示在你的官网、帮助中心或内部系统里。 * **两种形态**：**状态徽标**常显当前整体状态，适合放在页脚或帮助中心；**事件横幅**仅在故障或维护时出现在页面顶部/底部，访客可关闭，计划维护开始前 24 小时自动显示 * **外观可配**：主题（自动/亮色/暗色）、语言（中文/English）、徽标尺寸、横幅位置 * **嵌入简单**：控制台 状态页详情 → 设置 → 嵌入组件，实时预览并一键复制嵌入代码（` ``` ```html 事件横幅 theme={null} ``` 脚本标签带有 `integrity`（SRI 校验）与 `crossorigin="anonymous"` 属性，请整段复制，不要只拷贝 `` 标签。示例中的 `https://status.example.com` 请替换为你状态页的实际地址（控制台生成的代码中已是真实地址）。 ### 属性参考 `` 支持以下属性： | 属性 | 取值 | 默认值 | 适用形态 | 说明 | | --------------------------- | ---------------------------- | --------- | ---- | ------------------------------------------------------ | | `page` | 状态页完整 URL（http/https） | 无（**必填**） | 两者 | Widget 据此请求 `/api/widget/v1/summary.json` 获取状态数据 | | `type` | `badge` / `banner` | `badge` | 两者 | 徽标或横幅形态 | | `theme` | `auto` / `light` / `dark` | `auto` | 两者 | `auto` 跟随访客系统的深色模式设置 | | `locale` | `zh` / `en` | 跟随浏览器语言 | 两者 | Widget 文案语言 | | `size` | `small` / `medium` / `large` | `medium` | 仅徽标 | 徽标尺寸 | | `position` | `top` / `bottom` | `top` | 仅横幅 | 横幅固定在页面顶部或底部 | | `show-upcoming-maintenance` | `true` / `false` | `true` | 仅横幅 | 计划维护是否在开始前 24 小时自动显示 | *** ## 行为说明 ### 数据刷新 * Widget 默认每 **30 秒**轮询一次状态接口（间隔由接口的 `poll_after_seconds` 字段下发），并带有随机抖动，避免大量访客同时请求 * 请求携带 `If-None-Match`（ETag）条件头；数据未变化时服务端返回 `304`，不重复传输内容 * 页面隐藏（切到后台标签页）时**暂停轮询**，回到前台立即刷新一次 * 请求失败时按指数退避重试（5 秒起步，最长 5 分钟） ### 数据过期（Stale） 接口通过 `max_stale_seconds`（默认 **120 秒**）声明数据保鲜期。超过该时间未能成功校验数据时： * **徽标**进入「未知状态」，并显示最近一次确认数据的时间 * **横幅**在无有效数据时不显示 ### 横幅的显示与关闭 * 横幅按优先级选取展示内容：**进行中的故障** > **进行中的维护** > **24 小时内开始的计划维护**；存在多条事件时，横幅会显示「另有 N 条」 * 访客可点击 × 关闭横幅。关闭状态记忆在**当前浏览器会话**中，按「事件 ID + 最近更新时间」记录——当事件有新进展（状态更新或新增时间线）时，横幅会重新出现 * 设置 `show-upcoming-maintenance="false"` 可关闭计划维护的提前显示 ### 状态枚举与颜色 | 状态 | 含义 | 颜色 | | ---------------- | ---- | ----- | | `operational` | 运行正常 | 🟢 绿色 | | `degraded` | 性能下降 | 🟡 黄色 | | `partial_outage` | 部分中断 | 🟠 橙色 | | `full_outage` | 完全中断 | 🔴 红色 | | `maintenance` | 维护中 | 🔵 蓝色 | 状态页中被设置为**隐藏**的组件不会出现在 Widget 数据中——快照只包含对外可见组件的故障与维护事件。 *** ## 公开接口 summary.json 如果你不想使用现成的 Web Component，可以直接调用每个公开状态页自带的 JSON 快照接口，自行渲染或集成到你的监控体系中。控制台「嵌入组件 → API」页签展示了该地址。 ``` GET {状态页地址}/api/widget/v1/summary.json ``` * **公开访问**：无需鉴权、无需 API Key * **跨域**：响应携带 `Access-Control-Allow-Origin: *`，浏览器可直接调用；支持 `GET`、`HEAD` 与 `OPTIONS`（预检） * **缓存**：响应头 `Cache-Control: public, max-age=30, s-maxage=30, stale-while-revalidate=120, stale-if-error=3600`，并返回 `ETag`——携带 `If-None-Match` 且数据未变化时返回 `304` * **时效**：响应头 `X-Status-Validated-At` 表示快照最近一次从后端成功校验的时间，可据此判断数据是否过期 该接口面向浏览器端低频轮询设计。**高流量场景下请通过你的服务端代理并缓存响应**，不要让大量客户端直连该地址。 ### 响应字段 响应为单个 JSON 对象，`schema_version` 当前固定为 `"1.0"`： | 字段 | 类型 | 说明 | | -------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | `schema_version` | string | 数据结构版本，当前为 `"1.0"` | | `generated_at` | string | 快照的数据版本时间（ISO 8601），数据有变化才会更新 | | `poll_after_seconds` | number | 建议的轮询间隔（秒），当前为 `30` | | `max_stale_seconds` | number | 数据保鲜期（秒），超过未校验成功应视为过期，当前为 `120` | | `page` | object | 状态页信息：`name`（名称）、`url`（地址） | | `overall` | object | 整体状态：`status` 取 `operational` / `degraded` / `partial_outage` / `full_outage` / `maintenance` 之一 | | `ongoing_incidents` | array | 进行中的故障列表（见下表） | | `in_progress_maintenances` | array | 进行中的维护列表（见下表） | | `scheduled_maintenances` | array | 72 小时内开始的计划维护，最多返回 3 条 | `ongoing_incidents` 数组元素： | 字段 | 类型 | 说明 | | --------------------- | -------------- | ---------------------------------------------------- | | `id` | string | 事件 ID | | `title` | string | 事件标题 | | `phase` | string | 生命周期状态：`investigating` / `identified` / `monitoring` | | `impact` | string | 影响程度，取值同状态枚举 | | `started_at` | string \| null | 开始时间（ISO 8601） | | `updated_at` | string | 最近更新时间（ISO 8601） | | `url` | string \| null | 事件在状态页上的详情链接 | | `last_update` | object \| null | 最近一条时间线更新：`at`（时间）、`message`（内容） | | `affected_components` | array | 受影响组件：`id`、`name`、`group_name`（可选）、`status`（可为 null） | `in_progress_maintenances` 与 `scheduled_maintenances` 数组元素： | 字段 | 类型 | 说明 | | --------------------- | --------------- | --------------------------------- | | `id` | string | 事件 ID | | `title` | string | 事件标题 | | `phase` | string | 生命周期状态：`scheduled` / `ongoing` | | `starts_at` | string | 计划开始时间（ISO 8601） | | `ends_at` | string \| null | 计划结束时间；手动推进的维护可能没有结束时间，此时为 `null` | | `updated_at` | string | 最近更新时间（ISO 8601） | | `overdue` | boolean \| null | 是否已超过计划结束时间仍未完成 | | `url` | string \| null | 事件在状态页上的详情链接 | | `last_update` | object \| null | 最近一条时间线更新：`at`、`message` | | `affected_components` | array | 受影响组件，结构同故障 | ### 响应示例 ```json theme={null} { "schema_version": "1.0", "generated_at": "2026-08-11T08:00:00Z", "poll_after_seconds": 30, "max_stale_seconds": 120, "page": { "name": "Example Status", "url": "https://status.example.com" }, "overall": { "status": "partial_outage" }, "ongoing_incidents": [ { "id": "1024", "title": "API 错误率上升", "phase": "investigating", "impact": "partial_outage", "started_at": "2026-08-11T07:40:00Z", "updated_at": "2026-08-11T07:55:00Z", "url": "https://status.example.com/incidents/1024", "last_update": { "at": "2026-08-11T07:55:00Z", "message": "我们正在排查错误率上升的问题。" }, "affected_components": [ { "id": "cmp-1", "name": "公共 API", "group_name": "核心服务", "status": "partial_outage" } ] } ], "in_progress_maintenances": [], "scheduled_maintenances": [] } ``` ### 错误响应 | 状态码 | 响应体 | 说明 | | ----- | ----------------------------------------- | ---------------------------- | | `404` | `{"error": "status_page_not_found"}` | 状态页不存在、非公开，或部署侧关闭了 Widget 功能 | | `503` | `{"error": "widget_summary_unavailable"}` | 状态数据暂时不可用，请稍后重试 | Widget 功能默认开启，你无需任何配置即可使用。私有化部署环境中，部署管理员可通过 `deploy.widgetEnabled` 开关整体关闭该功能（关闭后接口返回 404）。 # API 文档 Source: https://docs.flashduty.com/zh/openapi Flashduty Open API 文档，用于访问和操作 FlashDuty 的实体数据 # 审计日志 Source: https://docs.flashduty.com/zh/platform/audit-log 查询和审查主体内所有成员的操作记录，追踪系统变更，保障安全合规 审计日志记录了主体内所有成员的操作行为，帮助你追踪系统变更、排查异常操作、满足安全合规要求。你可以按时间范围、操作人、事件类型等条件灵活检索日志。 ## 查看审计日志 *** **配置路径**：平台管理 → 审计日志 审计日志以表格形式展示，每条记录包含以下信息： | 字段 | 说明 | | --------- | ----------------------- | | **时间** | 操作发生的时间，精确到秒 | | **用户名** | 执行操作的成员名称和头像 | | **事件名称** | 操作的具体类型，如创建协作空间、修改分派策略等 | | **事件 ID** | 操作的唯一请求标识，可用于问题定位 | | **来源 IP** | 发起操作的客户端 IP 地址 | 点击某条记录的时间，可以查看该操作的完整请求详情（JSON 格式）。 ## 筛选与检索 *** 审计日志提供多种筛选条件，帮助你快速定位目标操作： | 筛选条件 | 说明 | | --------- | ------------------------------------ | | **时间范围** | 选择查询的时间区间，默认展示最近 7 天的日志，最大可查询最近 30 天 | | **用户** | 按操作人筛选，支持搜索成员名称或邮箱 | | **事件** | 按事件类型筛选，支持多选和关键词搜索 | | **事件 ID** | 输入事件 ID 精确匹配特定操作记录 | 多个筛选条件可以组合使用。例如，你可以同时指定时间范围和操作人，快速查找某位成员在特定时段内的所有操作。 ## 日志翻页 *** 审计日志每页展示 10 条记录，通过页面底部的翻页按钮浏览更多记录。页面底部会显示当前页码和总页数。 审计日志最多保留 30 天，超过 30 天的日志将被自动清理。 ## 常见问题 *** 当前控制台不支持直接导出审计日志。如有导出需求，请联系技术支持。 审计日志记录主体内所有通过控制台或 API 执行的写操作，包括创建、修改、删除各类资源，以及成员管理、权限变更等操作。只读操作（如查看页面）不会被记录。 # 单点登录 Source: https://docs.flashduty.com/zh/platform/configure-sso 通过单点登录实现一次登录，访问多个关联应用，提高工作效率并增强安全性 Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的单点登录（SSO）接入，帮助您轻松集成到各种应用和平台中。用户只需登录一次，便可访问多个关联的应用程序和服务，无需重复身份验证。 ## 网络访问要求 *** 不同协议对身份提供商（IdP）的网络可达性要求不同，配置前建议先确认，避免因网络不通导致登录失败： | 协议 | 是否需要 Flashduty 访问身份提供商 | 说明 | | -------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | SAML 2.0 | 不需要 | 登录全程通过成员的浏览器完成：浏览器被重定向到身份提供商，登录后再把签名的 SAMLResponse 回传给 Flashduty。Flashduty 服务端不会主动连接身份提供商，签名基于您上传的元数据在本地校验 | | OIDC | 需要 | 每次登录，Flashduty 服务端都需要访问身份提供商的 Discovery 文档、Token 端点和 JWKS 端点；当 ID Token 未携带完整的映射字段时，还会额外访问 UserInfo 端点 | | CAS | 需要 | 每次登录，Flashduty 服务端都需要调用身份提供商的 `/serviceValidate` 接口校验登录票据。CAS 协议本身不提供其他校验方式——票据不携带签名信息，只能回源验证 | | LDAP | 不涉及公网访问 | 仅私有化版本支持，Flashduty 部署在您自有网络内，不存在公网可达性问题 | 如果您的身份提供商部署在内网、无法从公网访问： * 可以将 Flashduty 的出口 IP `47.94.95.118`、`123.56.8.183`、`47.94.193.81` 和 `1.13.19.96` 加入防火墙白名单，放通 Flashduty 到身份提供商的访问 * 如果不希望为身份提供商开放任何公网访问，**SAML 2.0** 是唯一无需 Flashduty 访问身份提供商的协议，推荐优先选择 以上出口 IP 仅适用于 Flashduty **SaaS（公有云）服务**。如果您使用的是私有化部署版本，Flashduty 运行在您自己的网络中，出口 IP 由您自身的部署环境决定，请向您的基础设施团队确认，不要使用上述地址。 ## 配置 SAML 协议 *** **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 SAML2.0 协议类型 | 字段 | 描述 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 SAML2.0 | | 元数据文档 | 通过身份提供商获取的 XML 文档 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息 | | 稳定用户 ID 字段（`user_id`） | 可选。身份提供商返回的用户唯一标识属性，用于识别同一成员，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `employee_id`；填写 `name_id` 时取 SAML 断言中的 NameID（Subject）。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Flashduty 服务提供商信息 | **Service Provider Metadata** 和 **Assertion Consumer Service URL**（断言地址，用于身份提供商调用进行单点登录） | ## 配置 OIDC 协议 *** **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 OIDC 协议类型 | 字段 | 描述 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 OIDC 协议 | | Issuer | 从身份提供商获取，大小写敏感的 URL，不能包含 query 参数 | | Client ID | 客户端 ID，从身份提供商获取 | | Client Secret | 客户端密钥，从身份提供商获取 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息 | | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识 Claim，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `sub`。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Scopes | 指定请求可访问的信息和功能权限，支持自定义。默认值为 `openid`、`profile`、`email`、`phone`，支持以标签形式添加自定义 Scope | | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址
**支持签名算法**：RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512（不支持 HS256） | Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是 OIDC 协议正常工作所需的基础权限。删除这些默认值可能导致单点登录失败或无法正确获取用户信息。如需添加自定义 Scope，建议在保留默认值的基础上追加。 ## 配置 CAS 协议 *** **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 CAS 协议类型 | 字段 | 描述 | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 CAS 协议 | | CAS 地址 | 从身份提供商获取的 CAS 服务地址，如 `https://xqlsd3irx2gm-demo.authing.cn/cas-idp/669e050856d5b07b4399b242` | | CAS 登录路径 | CAS 登录路径，如 `/login` | | 跳过 TLS 检查 | 可选项，启用后将跳过 TLS 证书验证，适用于使用自签名证书的 CAS 服务 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息 | | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `principal`（即 CAS 认证用户名），也可配置为 CAS 返回的某个属性。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址 | ## 配置 LDAP 协议 *** LDAP 单点登录仅**私有化版本**支持。 **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 LDAP 协议类型 | 字段 | 描述 | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 LDAP 协议 | | LDAP 链接 | LDAP 服务地址，如：`ldap://10.10.10.10:389` | | BIND DN | 用于连接 LDAP 的用户名，如：`cn=admin,dc=flashduty,dc=com` | | BIND DN 密码 | 用于连接 LDAP 的密码，将加密存储到数据库中 | | 加密机制 | 支持 **TLS** 和 **StartTLS** 两种加密方式（二者互斥，只能启用一种）。启用任一加密方式后，可选择 **跳过 SSL/TLS 证书验证**；如不跳过，可选填写 SSL/TLS 证书路径 | | 用户 DN | 定义从哪个目录开始搜索用户，如：`ou=people,dc=flashduty,dc=com` | | 认证过滤 | 用于检索用户 DN 信息的自定义 filter 表达式，基本形式为：`(&(mail=%s))`。注意：开始和结束的括号是必须的 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名、手机和 Group 信息。邮箱为必填映射字段，Group 字段默认值为 `memberOf`，用于角色和团队同步 | | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识属性，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `uid`，也可使用 `entryUUID` 等稳定属性。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | 字段映射需要和身份提供商的配置保持一致，否则会导致异常。具体配置可参考 [OpenLDAP 集成指引](/zh/on-call/integration/sso/openldap)。 ### LDAP 连接检测 配置 LDAP 连接信息后，你可以点击设置抽屉底部的 **连接检测** 按钮，验证 Flashduty 能否成功连接到你的 LDAP 服务器。系统会使用当前填写的 LDAP 链接、BIND DN 和密码尝试建立连接，并返回连接成功或失败的结果。 建议在保存配置前先执行连接检测，确保连接参数正确无误，避免因配置错误导致成员无法通过 LDAP 登录。 ### LDAP 角色和团队同步 当你使用 LDAP 协议时，可以根据用户所属的 LDAP Group 自动同步 Flashduty 中的角色和团队。 **配置路径**：LDAP 设置页面 → 同步配置 在同步配置区域，分别开启 **同步角色** 和/或 **同步团队** 开关。 点击 **添加映射规则**，为每条规则配置以下内容： | 字段 | 说明 | | ------------ | ----------------------------------------------------------------------------- | | **Group DN** | LDAP 中 Group 的完整 Distinguished Name，如 `cn=devops,ou=groups,dc=example,dc=com` | | **映射角色** | 当同步角色开启时可选，选择该 Group 对应的 Flashduty 角色 | | **映射团队** | 当同步团队开启时可选，选择该 Group 对应的 Flashduty 团队 | 当同步角色开启时，你可以配置 **默认角色**。当用户的 LDAP Group 未匹配到任何映射规则时，系统将赋予这些默认角色。 * 你可以添加多条映射规则，每条规则对应一个 LDAP Group * 用户登录时，系统会根据其 LDAP Group 成员关系自动匹配并同步对应的角色和团队 * 映射规则中的 Group DN 必须是 LDAP 中 Group 的完整路径 ## 成员关联方式 *** 单点登录时，系统需要将身份提供商返回的用户与账户内成员进行关联，关联方式取决于 SSO 配置是否设置了**稳定用户 ID 字段**，对新建与既有配置均适用： | 配置 | 关联方式 | | ----------------- | -------------------------------------------------------------------------------------- | | 已配置稳定用户 ID 字段 | 按身份提供商返回的稳定用户 ID 识别同一成员，成员邮箱或手机号变更不影响识别。稳定用户 ID 尚未绑定时，系统会先通过邮箱或手机号匹配既有成员，并建立稳定用户 ID 绑定 | | 未配置稳定用户 ID 字段（留空） | 继续按下方映射的邮箱或手机号字段关联成员，行为保持不变 | 请确保身份提供商始终返回稳定且唯一的用户 ID。映射失败（身份提供商未返回该字段）将导致成员无法登录。 修改身份域相关设置（协议类型、身份提供商地址或稳定用户 ID 字段）会被视为身份域变更，系统将轮换 SSO 配置 ID。既有成员会在下次登录时通过邮箱或手机号重新关联，并绑定新的稳定用户 ID。 ## 强制 SSO 登录 *** `force_sso` 选项用于强制账户内所有成员仅能通过 SSO 登录，从而把身份验证完全收敛到身份提供商。 **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → **成员仅支持 SSO 登录** | 项 | 行为 | | --- | -------------------------------------- | | 字段名 | `force_sso` | | 默认值 | **开启**——首次配置 SSO 时，设置抽屉中的该开关预置为开启状态 | | 开启后 | 该账户的所有成员只能通过 SSO 登录，密码登录和验证码登录均会被服务端拒绝 | | 关闭后 | 允许成员同时使用 SSO 登录、密码登录与验证码登录 | | 例外 | **无**。账户主体（Owner）与超级管理员也受该限制约束，不存在豁免分支 | 当成员在该选项开启后尝试使用密码或验证码登录时，登录接口会返回错误： ```text theme={null} This account requires SSO login. Password/code login is disabled. ``` 通过密码会话切换账户时，若目标账户开启了该选项，同样会被拒绝并提示：`The target account requires SSO login. Switching via password session is not allowed.` **操作风险**：开启 `force_sso` 后，如果身份提供商（IdP）未正确连通，所有成员都将无法登录该账户，包括账户主体。在打开该开关前，请务必： 1. 使用任一具备 SSO 登录能力的成员账号端到端验证 SSO 登录链路。 2. 至少保留一条已可正常通过 SSO 登录的账户主体路径，避免锁出。 3. 若身份提供商配置可能临时不可用，请先关闭该选项，待修复后再启用。 ### 与「禁止编辑外部成员」的区别 `force_sso` 控制的是**登录方式**——是否允许密码/验证码登录；`sso_user_non_editable`（[禁止编辑外部成员](#外部成员管理)）控制的是**编辑权限**——通过 SSO 同步创建的外部成员是否能在控制台中修改资料与角色。两者作用层面不同，可独立开启或关闭。 ## 外部成员管理 *** 当您启用单点登录后，通过 SSO 首次登录并自动创建的成员会被标记为**外部成员**。您可以在 SSO 设置中开启**禁止编辑外部成员**选项（默认关闭），启用后，这些外部成员在 Flashduty 中将变为只读状态——无法在 Flashduty 中修改其角色或删除该成员，所有成员信息的管理只能通过身份提供商完成。 此功能适用于需要统一在身份提供商中管理用户权限的场景，确保 Flashduty 中的成员信息始终与身份提供商保持一致。 * 该选项仅影响通过 SSO 创建的外部成员，手动邀请的成员不受影响 * 如果 SSO 配置被删除，已存在的外部成员将默认保持只读状态 ## 登录域名管理 *** 登录域名是识别您的主体账号的重要依据，用于单点登录时定位到正确的 SSO 配置。每个主体的登录域名全局唯一。 配置登录域名后，成员可以通过 `{域名}.sso.flashcat.cloud` 地址直接发起单点登录，无需手动选择身份提供商。 您可以在 **平台管理 → 组织 → 组织信息 → 组织资料** 页面修改主体账号的域名。修改域名时请注意，域名只能使用 5–40 位字母、数字或 `-`，且不能以 `-` 开头或结尾。 修改域名后，该域名将应用于以下场景： * **SSO 单点登录配置**：所有已配置的 SSO 登录域名会随之变更，成员需要使用新域名发起单点登录 * **邮件集成推送的邮箱地址**：邮件集成的接收地址格式为 `prefix@{域名}.{邮箱后缀}`，域名变更后地址也会随之变化，请及时更新相关配置 修改前请确认已检查邮件集成配置，并在组织内进行了通报。修改操作可能需要通过多因素认证（MFA）验证。如在使用过程中遇到任何问题，请及时联系技术支持。 * 建议使用公司英文名称作为登录域名，便于记忆 * 登录域名一旦设置，变更后原域名将立即失效，使用旧域名的成员需要更新登录地址 ## 最佳实践 *** 通过 Authing 配置 Flashduty SSO 单点登录 通过 Keycloak 配置 Flashduty SSO 单点登录 通过 OpenLDAP 配置 Flashduty SSO 单点登录 # 自定义菜单 Source: https://docs.flashduty.com/zh/platform/custom-menu 在 Flashduty 控制台侧边栏中嵌入自定义链接或内部页面，并通过角色权限控制可见性 自定义菜单允许管理员在控制台侧边栏中添加自定义导航项，将外部系统页面或内部链接直接嵌入 Flashduty 导航树。每个菜单项对应一个账户级权限点，由管理员按角色授权后方可在导航中显示。 **配置路径**：平台管理 → 自定义菜单 ## 创建菜单 前往 **平台管理 → 自定义菜单**，点击 **新建菜单** 按钮。 按照以下字段填写菜单配置： | 字段 | 是否必填 | 限制 | 说明 | | ------------------- | :--: | ----------------- | -------------------------- | | **中文名称**（label\_zh） | 必填 | 最多 128 字符 | 菜单在中文界面显示的名称 | | **英文名称**（label\_en） | 选填 | 最多 128 字符 | 菜单在英文界面显示的名称；不填时英文界面沿用中文名称 | | **图标**（icon） | 选填 | 最多 255 字符 | 菜单图标标识符 | | **链接地址**（url） | 必填 | 最多 2048 字符 | 点击菜单时跳转或嵌入的目标 URL | | **打开方式**（mode） | 必填 | `iframe` 或 `open` | 见下方说明 | | **授权角色** | 选填 | — | 指定可见该菜单的角色列表；不填则默认无成员可见 | 打开方式决定用户点击菜单后的行为： * **iframe**：在控制台主内容区内嵌显示目标页面。适用于希望用户留在 Flashduty 界面内访问内部工具的场景，例如 Grafana 大盘、内部知识库等。目标页面需允许被 iframe 嵌套（即 HTTP 响应头 `X-Frame-Options` 不为 `DENY` / `SAMEORIGIN`）。 * **open**：在浏览器新标签页中打开目标 URL。适用于外部系统或不支持 iframe 嵌入的页面。 在 **授权角色** 字段中选择允许看到该菜单的角色。 系统预置角色（**Admin**、**Responder**、**Viewer**）不支持绑定到自定义菜单，因为它们在运行时已自动继承账户内所有权限。请使用**自定义角色**进行授权。 未选择任何角色时，该菜单对所有普通成员不可见（主体账号和 Admin 角色仍可通过管理界面访问）。 点击 **保存** 完成创建。系统会自动为该菜单生成一个权限点（格式为 `customMenu:visit:`），并将其同步到所选角色的权限位图中。 ## 编辑菜单 在菜单列表中点击目标菜单的 **编辑** 按钮，即可修改上述所有字段。 修改 **授权角色** 字段时，系统执行全量同步：新列表中的角色获得该菜单的访问权限，不在新列表中的角色将失去该权限。若不传授权角色字段，则保留原有绑定不变（仅用于修改名称、图标、URL 等字段时）。 ## 删除菜单 在菜单列表中点击 **删除** 按钮即可删除对应菜单。删除操作会同时移除关联的权限点，并从所有角色的权限位图中清除对应权限——**持有该角色的成员在下次登录或权限刷新后将不再看到该菜单入口**。 删除操作是幂等的：对已删除的菜单再次执行删除不会报错。 ## 菜单排序 菜单列表支持拖拽调整顺序。系统使用 LexoRank 算法持久化排列位置，多次在同一位置插入后仍可正常排序。 ## 配额限制 每个账户最多可创建 **100 个**自定义菜单。超出配额时，创建请求将返回错误，需先删除不再使用的菜单后方可继续新增。 ## 权限说明 自定义菜单使用账户级动态权限，与系统内置权限平级展示于角色配置界面的 **自定义菜单** 分组下： * **权限点命名**：`customMenu:visit:`，其中 `` 为菜单创建时由系统分配的唯一数字标识。 * **可见性控制**：仅被授予对应权限点的成员才能在导航侧边栏中看到该菜单项；未被授予的成员看不到该入口，也无法通过直接访问 URL 触发导航高亮。 * **主体账号**：主体账号（即账户创建者）绕过权限过滤，始终可见所有自定义菜单。 * **权限生命周期**：菜单删除后，其对应权限点随之失效，已写入角色位图的权限位也会同步清除；新增菜单后，需在角色配置界面重新将其授予目标角色，已有角色不会自动获得新菜单的访问权限。 关于 `customMenu:visit:` 权限点在角色体系中的完整语义，请参阅[权限设计](/zh/platform/permission-design)中的「自定义菜单权限组」章节。 ## 延伸阅读 了解 Flashduty RBAC 权限体系与账户级动态权限 管理团队和成员，配置角色与访问控制 # 组织信息 Source: https://docs.flashduty.com/zh/platform/organization-info 查看和维护组织资料、通知设置与故障处理默认配置 ## 组织信息 *** **组织信息** 页面集中展示组织身份与组织级默认配置，所有成员均可访问。入口为 **平台管理 → 组织 → 组织信息**，也可以点击个人中心名片上的 **组织信息** 按钮直达。 页面包含以下区块： | 区块 | 说明 | | -------- | ---------------------------- | | **组织资料** | 组织的 Logo、名称、ID 与域名 | | **通知设置** | 组织内系统通知的内容与语言，对所有成员生效 | | **故障处理** | 故障处理操作的组织级默认，对控制台和 IM 告警卡片生效 | 本页面**对所有成员开放**：普通成员可以查看全部配置项，但页面整体为只读；仅**主体账户**或具备 **Account.Admin** 角色的账户可以修改配置。 ## 组织资料 *** 组织资料区块维护组织的身份信息，仅主体账户或 Account.Admin 可以修改，其余成员只读。 | 配置项 | 说明 | | -------- | ------------------------- | | **Logo** | 组织的 Logo 图片，通过图片 URL 设置 | | **名称** | 组织名称，展示在邀请成员的邮件和短信中 | | **ID** | 组织的唯一标识，对接 API 或联系技术支持时提供 | | **域名** | 用于登录和邮件集成推送的专属子域名 | ### 域名 域名是识别主体账号的重要依据，用于单点登录时定位到正确的 SSO 配置。每个主体的登录域名全局唯一，配置后成员可以通过 `{域名}.sso.flashcat.cloud` 地址直接发起单点登录。 修改域名时请注意以下规则： * 域名只能使用 **5–40 位**字母、数字或 `-`，且不能以 `-` 开头或结尾 * 修改后的域名不能与当前域名相同 * 修改操作需要确认影响范围，并可能通过多因素认证（MFA）验证 修改域名后，该域名将应用于以下场景： * **SSO 单点登录配置**：所有已配置的 SSO 登录域名会随之变更，成员需要使用新域名发起单点登录 * **邮件集成推送的邮箱地址**：邮件集成的接收地址格式为 `prefix@{域名}.{邮箱后缀}`，域名变更后地址也会随之变化，请及时更新相关配置 更多信息请参阅 [单点登录配置](/zh/platform/configure-sso)。 ## 通知设置 *** 通知设置区块维护组织内系统通知的内容与语言，对所有成员生效。仅主体账户或 Account.Admin 可以修改，其余成员以只读文本查看当前配置。 ### 默认通知语言 系统通知文案的组织级默认语言，可选 **中文** 或 **English**，应用于故障分派、值班轮换、订阅到期提醒等系统通知的文案语言。 * 该设置**不影响控制台界面语言** * 验证码、邀请等邮件按接收者的浏览器语言发送，不受此设置影响 * 该设置此前位于个人 **通知偏好** 页面，现已迁移为组织级配置 ### 发送完整告警短信 控制故障告警短信是否截断的组织级开关： | 状态 | 行为 | | ------ | --------------------------------- | | **开启** | 故障告警短信不再截断，超长内容可能被运营商拆分为多条，并按多条计费 | | **关闭** | 故障告警短信按单条长度截断 | 开启时需要二次确认：开启后国内和国际故障告警短信将不再截断，超长内容可能被运营商拆分为多条短信并按多条计费。 验证码、邀请、值班短信**不受该开关影响**，始终按原有逻辑发送。 ## 故障处理 *** 故障处理区块维护故障处理操作的组织级默认值，**对控制台和 IM 告警卡片生效**。 ### 暂缓时间快捷选项 在控制台和 IM 卡片（飞书 / 钉钉 / 企微 / Slack / Teams）上暂缓故障时，系统提供 3 个快捷时长供选择： * 固定 **3 个槽位**，每个槽位可选择 **小时** 或 **分钟** 作为单位 * 每个值须大于 0，且单个时长最长 **24 小时**（以小时为单位时不超过 24，以分钟为单位时不超过 1440） * 快捷选项**不能重复** * 默认值为 **2 小时 / 4 小时 / 12 小时**，点击 **恢复默认** 可快速还原 修改后点击 **保存** 提交，立即对控制台与 IM 告警卡片生效。仅主体账户或 Account.Admin 可以修改，其余成员以只读文本查看当前预设。更多故障暂缓操作请参阅 [暂缓处理](/zh/on-call/incident/handle-update-incident)。 ## 延伸阅读 *** 登录域名与 SSO 单点登录 设置个人通知偏好 # 权限设计 Source: https://docs.flashduty.com/zh/platform/permission-design 了解 Flashduty 基于角色（RBAC）的功能权限和基于团队的数据权限设计 Flashduty 使用两种类型的权限：**功能权限**和**数据权限**，并在不同的功能场景配合使用。 您必须同时拥有**功能权限**和**数据权限**，才能操作某些数据对象。功能权限是前提，决定您是否有权执行某类操作；数据权限在此基础上，进一步限定您可操作的数据范围。 ## 功能权限 功能权限也叫操作权限，决定了用户可以使用系统的哪些功能或操作。具体表现为：API 是否可调用、按钮是否可点击、页面和菜单是否可见等。 Flashduty **基于角色（RBAC）来控制功能权限**，按模块划分权限，实现精细化管理。系统预置了以下角色（您也可以自定义角色）： ### 预置角色 拥有所有权限，适用于需要完整管理能力的核心成员。Admin 的权限位图查询范围为 `account_id IN (0, 当前账户 ID)`，因此会**自动包含**该账户下所有自定义菜单的访问权限点，无需单独绑定。 拥有除「费用中心」「成员管理」「角色管理」「单点登录管理」外的全部**系统权限**，适用于处理日常运维工作的成员。Responder 的权限查询范围为系统权限和当前账户权限（`account_id IN (0, 当前账户 ID)`），其中标记为 `admin_only=1` 的权限会从 Responder 预置角色中排除。因此，非管理员专用的账户级动态权限（包括自定义菜单访问权限）会自动包含。 拥有除「审计」「快速开始」外的绝大部分只读**系统权限**，适用于仅需查看数据的成员。Viewer 受 `id < 100000` 过滤限制，**不会**自动获得任何自定义菜单的访问权限，需在自定义菜单中显式授权。 **Responder** 角色不包含成员管理和角色管理权限。如需管理团队成员或分配角色，请使用 **Admin** 角色。 ### 权限列表 系统按产品模块划分权限点，每个权限点分为 **Read**（只读）和 **Manage**（管理）两种类型。权限按以下产品范围分组展示，每组带有对应图标： * **平台（Platform）**：组织管理、费用中心等基础平台权限 * **On-call**：告警响应、配置管理、状态页等值班相关权限 * **RUM**：前端监控相关权限 * **Monitors**：监控告警相关权限 * **自定义菜单（Custom menu）**：账户级动态权限组，每个已配置的自定义菜单对应一个权限点 当某个权限点同时存在 **Read** 和 **Manage** 类型时，授予 **Manage** 权限会自动关联授予对应的 **Read** 权限，无需单独勾选。 #### 系统权限与账户级动态权限 Flashduty 的权限点分为两类： * **系统权限（System）**：由 Flashduty 预先定义，所有账户一致，覆盖平台、On-call、RUM、Monitors 等内置模块。 * **账户级动态权限（Account）**：根据当前账户配置的资源动态生成，仅在该账户内可见。例如自定义菜单的访问权限属于此类——每新增一个自定义菜单，就会自动产生一个对应的权限点。 在角色配置接口返回的权限对象中，可以通过以下字段区分二者： | 字段 | 说明 | | ------------ | ------------------------------------ | | `account_id` | `0` 表示系统权限；非 `0` 表示账户级动态权限，值为对应账户 ID | | `source` | `system` 表示系统权限；`account` 表示账户级动态权限 | | `source_ref` | 账户级动态权限的来源标识。自定义菜单为对应的 `menu_id` | #### 自定义菜单权限组 自定义菜单是一个独立的权限范围，与平台、On-call、RUM、Monitors 平级展示。该组以**扁平列表**形式呈现，不再按 Read / Manage 拆分子类——账户内每配置一个自定义菜单，就会在该组下生成一个权限点： * **权限点命名**：`customMenu:visit:`，其中 `` 为自定义菜单的唯一标识。 * **作用**：授予该权限点的成员可以在导航中看到并访问对应的自定义菜单；未授予则该菜单对成员不可见。 * **动态性**：删除自定义菜单后，对应的权限点会随之消失；新增自定义菜单后，需重新进入角色编辑界面将其授予目标角色。 **自定义菜单权限与预置角色的继承规则不同：** * **Admin**：自动继承账户内所有自定义菜单的访问权限，无需任何额外配置。 * **Responder**：会自动包含当前账户中 `admin_only=0` 的权限点。因此，非管理员专用的自定义菜单访问权限无需额外角色绑定；标记为管理员专用的权限会从 Responder 预置角色中排除。 * **Viewer**：不会自动继承自定义菜单权限。Viewer 的权限位图只包含系统预定义的权限点（`id < 100000`），而自定义菜单权限点的 ID 由 Snowflake 算法生成，远超该阈值，因此会被过滤掉。如需让 Viewer 成员访问某个自定义菜单，必须在该菜单的角色绑定配置（`role_ids` 字段）中显式添加 Viewer。 * **自定义角色**：自定义角色同样不会自动继承自定义菜单权限，需在菜单的角色绑定中显式授权。 关于自定义菜单的创建与管理，请在**平台管理 → 自定义菜单**界面进行配置；本节仅描述权限层面的语义。 | 权限点 | 类型 | 说明 | | ------------ | -- | -------------------- | | **成员管理** | 管理 | 邀请和移除成员，授予和撤销成员角色 | | **角色管理** | 管理 | 创建、编辑和删除角色，管理角色内的权限 | | **团队管理** | 管理 | 创建、编辑和删除团队，管理团队成员 | | **单点登录查看** | 只读 | 查看单点登录配置信息 | | **单点登录管理** | 管理 | 启用或禁用单点登录并修改其配置 | | **审计日志查看** | 只读 | 检索和读取操作审计日志 | | **API 密钥查看** | 只读 | 查看账户 API 密钥 | | **API 密钥管理** | 管理 | 创建、查看、修改和删除账户 API 密钥 | | 权限点 | 类型 | 说明 | | -------- | -- | --------------------- | | **费用查看** | 只读 | 查看账单、订阅信息、消费记录等付款相关信息 | | **费用管理** | 管理 | 管理订阅、充值、开票等费用中心操作 | | 权限点 | 类型 | 说明 | | ---------- | -- | ------------------------------- | | **协作空间查看** | 只读 | 查看协作空间列表、成员、消息等信息（需同时拥有数据权限） | | **协作空间管理** | 管理 | 创建、编辑和删除协作空间，管理成员和配置（需同时拥有数据权限） | | **故障查看** | 只读 | 查看故障列表、详情、时间线等信息 | | **故障管理** | 管理 | 创建、编辑、处理和关闭故障，管理故障响应流程 | | **集成查看** | 只读 | 查看已配置的集成列表和集成详情 | | **集成管理** | 管理 | 添加、配置、测试和删除集成（需同时拥有数据权限） | | **数据分析查看** | 只读 | 查看故障响应、系统健康等分析报告和统计数据 | | 权限点 | 类型 | 说明 | | ----------- | -- | -------------------------------- | | **自定义字段查看** | 只读 | 查看自定义字段配置和字段定义 | | **自定义字段管理** | 管理 | 创建、编辑和删除自定义字段，配置字段类型和验证规则 | | **值班表查看** | 只读 | 查看值班表、轮换规则和值班人员信息 | | **值班表管理** | 管理 | 创建、编辑和删除值班表，配置轮换规则和覆盖时段 | | **服务日历查看** | 只读 | 查看服务日历、假期安排和特殊时段配置 | | **服务日历管理** | 管理 | 创建、编辑和删除服务日历，配置假期和工作日 | | **通知模板查看** | 只读 | 查看通知模板、故障模板等模板配置 | | **通知模板管理** | 管理 | 创建、编辑和删除模板，自定义模板内容和格式（需同时拥有数据权限） | | **映射规则查看** | 只读 | 查看数据映射规则和映射关系配置 | | **映射规则管理** | 管理 | 创建、编辑和删除映射规则等（需同时拥有数据权限） | | 权限点 | 类型 | 说明 | | ----------- | -- | ----------------------- | | **状态页查看** | 只读 | 查看状态页配置、服务状态和历史事件 | | **状态页管理** | 管理 | 创建、编辑和发布状态页，管理服务组件和事件 | | **状态页事件管理** | 管理 | 发布、编辑和删除状态页中的事件，包括故障和维护 | | 权限点 | 类型 | 说明 | | ---------- | -- | --------- | | **监控概览查看** | 只读 | 查看监控概览等 | | **告警规则查看** | 只读 | 查看监控告警规则等 | | **告警规则管理** | 管理 | 管理监控告警规则等 | | **规则仓库查看** | 只读 | 查看规则仓库等 | | **规则仓库管理** | 管理 | 管理规则仓库等 | | **节点权限查看** | 只读 | 查看监控节点权限等 | | **节点权限管理** | 管理 | 管理监控节点权限等 | | **数据源查看** | 只读 | 查看监控数据源等 | | **数据源管理** | 管理 | 管理监控数据源等 | | **告警引擎查看** | 只读 | 查看监控引擎等 | | **告警引擎管理** | 管理 | 管理监控引擎等 | | 权限点 | 类型 | 说明 | | ----------- | -- | --------------------------- | | **应用管理** | 管理 | 创建、配置和管理前端监控应用，设置采样规则和告警策略等 | | **性能监控查看** | 只读 | 查看前端性能监控问题等 | | **错误追踪查看** | 只读 | 查看前端错误等 | | **会话浏览器查看** | 只读 | 查看事件详情等 | | **会话回放查看** | 只读 | 查看前端监控会话回放等 | | 权限点 | 类型 | 说明 | | ---------- | -- | ------------------------------- | | **快速开始查看** | 只读 | 查看快速开始信息，需具备相关团队、空间、故障、值班和集成的权限 | ### 自定义角色 除了预置角色外，你可以创建自定义角色以满足更精细的权限控制需求。 **配置路径**：平台管理 → 角色管理 进入角色管理页面，点击 **创建角色** 按钮，填写角色名称和描述。你也可以通过复制已有角色快速创建。 在角色详情页中，点击角色名称或描述旁的 **编辑图标（笔形图标）** 即可直接内联编辑角色名称和描述，修改后自动保存。 在角色详情页的 **权限列表** 标签下，点击 **编辑** 进入编辑模式。在编辑模式中，你可以通过批量勾选的方式一次性授予或撤销多个权限点，完成后点击 **保存** 即可。 在角色详情页的 **授权成员** 标签下，点击 **编辑** 进入编辑模式，通过批量勾选的方式添加或移除该角色的授权成员，完成后点击 **保存**。 * 系统预置角色（Admin、Responder、Viewer）不可修改或删除 * 自定义角色支持编辑、复制、启用/禁用和删除操作 * 一个成员可以同时拥有多个角色，其权限为所有角色权限的并集 ### 权限矩阵 | 权限模块 | Admin | Responder | Viewer | | ------------------------------------ | :---: | :-------: | :----: | | **成员管理** | ✔️ | | | | **角色管理** | ✔️ | | | | **团队管理** | ✔️ | ✔️ | | | **单点登录** | ✔️ | | 只读 | | **操作审计** | ✔️ | ✔️ | | | **API 密钥** | ✔️ | ✔️ | | | **费用中心** | ✔️ | | 只读 | | **协作空间** | ✔️ | ✔️ | 只读 | | **故障管理** | ✔️ | ✔️ | 只读 | | **集成管理** | ✔️ | ✔️ | 只读 | | **数据分析** | ✔️ | ✔️ | 只读 | | **配置管理**（自定义字段、值班、日历、模板、映射） | ✔️ | ✔️ | 只读 | | **状态页** | ✔️ | ✔️ | 只读 | | **监控告警**（概览、告警规则、规则仓库、节点权限、数据源、告警引擎） | ✔️ | ✔️ | 只读 | | **前端监控**（应用管理、性能监控、错误追踪、会话浏览器、会话回放） | ✔️ | ✔️ | 只读 | | **快速开始** | ✔️ | ✔️ | | | **自定义菜单**（每个菜单独立授权） | 自动继承 | 需显式授权 | 需显式授权 | ## 数据权限 数据权限也叫访问权限，该权限控制用户可以访问或查看的数据范围。 **功能权限是数据权限的前提。** 您必须先拥有对应的功能权限，数据权限才会生效。例如：一个 **Viewer** 角色的成员属于 A 团队，某个协作空间归属于 A 团队且设置为私有，虽然该成员在数据权限上可以访问此空间，但由于 **Viewer** 没有空间管理的功能权限，因此只能查看，不能编辑。 Flashduty **基于团队来控制数据权限**，并应用于以下场景： | 场景 | 权限说明 | | -------- | -------------------------------------- | | **团队管理** | 创建者、主体账号和团队成员可以修改团队信息，以及管理团队成员 | | **协作空间** | 创建者、主体账号和负责团队成员，可以修改空间的基本信息、降噪配置、分派策略等 | | **值班管理** | 创建者、主体账号和负责团队成员，可以修改值班的基本信息、轮换规则等 | | **模板管理** | 创建者、主体账号和负责团队成员，可以修改模板的基本信息、各通道模板配置等 | | **服务日历** | 创建者、主体账号和负责团队成员，可以修改日历的基本信息、节假日设定等 | | **集成管理** | 创建者、主体账号和负责团队成员，可以管理集成的配置 | | **映射规则** | 创建者、主体账号和负责团队成员，可以管理映射规则的配置 | 当您没有对应资源的数据权限时，系统会显示以下提示： 权限不足提示 ## 历史角色迁移 以下历史预置角色已于 **2026 年 1 月 30 日** 废弃，系统已自动完成迁移。 ### 历史角色说明 | 角色 | 说明 | | --------------- | ------------------------- | | `Account.Admin` | 账户管理员，原拥有全部操作权限 | | `Fin.Admin` | 财务管理员，原拥有费用中心下单权限 | | `Tech.Admin` | 技术管理员，原拥有访问控制和审计权限（含成员管理） | ### 迁移映射 | 原角色 | 新角色 | 说明 | | --------------- | ------------- | ------------------------- | | `Account.Admin` | **Admin** | 权限保持不变 | | `Fin.Admin` | **Admin** | 权限提升 | | `Tech.Admin` | **Responder** | 移除成员管理权限 | | 无角色 | **Responder** | 自动授予 | | 自定义角色 | 保持不变 | 可能丢失部分 Monitors 权限，建议自行检查 | ### 兼容性说明 以下场景将自动授予 **Viewer** 角色，确保成员具备基本访问权限： * 通过 [Open API 邀请新成员](/zh/api-reference/platform/members/member-invite) 时未指定角色 * 通过 **单点登录（SSO）** 自动创建成员时未指定角色 **兼容期截止日期：2026 年 6 月 30 日** 届时，未指定角色的 API 请求将返回错误，请提前完成适配。 自定义角色用户请在升级后检查权限配置，确保符合预期。 ## 延伸阅读 了解团队和成员的管理方式 配置 SSO 实现统一身份认证 # 产品定价 Source: https://docs.flashduty.com/zh/platform/pricing 了解 Flashduty 各产品的收费模式和定价方案 ## On-call 定价 *** On-call 采用 **License 订阅制**收费，按活跃用户数量计费。 ### 收费模式 每个 License 对应一个账户成员。只有持有 License 的成员才能使用 On-call 的全部功能。 | 版本 | 说明 | 适用场景 | | ------- | ----------- | --------- | | **免费版** | 永久免费，功能受限 | 个人或小团队体验 | | **标准版** | 基础功能完整 | 中小型团队日常使用 | | **专业版** | 全部功能 + 高级特性 | 企业级生产环境 | ### 功能对比 | 功能 | 免费版 | 标准版 | 专业版 | | --------------------------------- | :-: | :-: | :-: | | **单点登录（SSO）** | ✅ | ✅ | ✅ | | **告警路由** | ✅ | ✅ | ✅ | | **故障协同** | ✅ | ✅ | ✅ | | **故障分派** | ✅ | ✅ | ✅ | | **故障升级** | ✅ | ✅ | ✅ | | **故障暂缓** | ✅ | ✅ | ✅ | | **故障抖动检测** | ✅ | ✅ | ✅ | | **静默策略** | ✅ | ✅ | ✅ | | **使用量看板** | ✅ | ✅ | ✅ | | **抑制策略** | ❌ | ✅ | ✅ | | **告警聚合** | ❌ | ✅ | ✅ | | **规则告警聚合** | ❌ | ✅ | ✅ | | **智能告警聚合** | ❌ | ❌ | ✅ | | **告警风暴** | ❌ | ✅ | ✅ | | **分析看板** | ❌ | ✅ | ✅ | | **变更集成** | ❌ | ✅ | ✅ | | **Webhook 集成** | ❌ | ✅ | ✅ | | **自定义字段** | ❌ | ✅ | ✅ | | **IM 集成**（飞书、钉钉、企业微信、Slack、Teams） | ❌ | ❌ | ✅ | | **服务日历** | ❌ | ❌ | ✅ | | **自定义通知模板** | ❌ | ❌ | ✅ | | **自定义值班角色** | ❌ | ❌ | ✅ | | **高级标签增强** | ❌ | ❌ | ✅ | | **历史故障查询** | ❌ | ❌ | ✅ | | **新奇故障识别** | ❌ | ❌ | ✅ | | **外部创建故障** | ❌ | ❌ | ✅ | | **故障复盘** | ❌ | ❌ | ✅ | | **公开状态页** | ✅ | ✅ | ✅ | | **内部状态页** | ❌ | ❌ | ✅ | | **AI 故障摘要** | ❌ | ❌ | ✅ | | **作战室** | ❌ | ❌ | ✅ | | **工单集成**（Jira、ServiceNow） | ❌ | ❌ | ✅ | 详细功能对比也可访问：[价格页面](https://flashcat.cloud/flashduty/price/) ### 资源限制 | 资源 | 免费版 | 标准版 | 专业版 | | ------- | ----- | ----- | ----- | | 最大用户数 | 5 | 不限 | 不限 | | 最大值班表数 | 1 | 不限 | 不限 | | 最大协作空间数 | 1 | 不限 | 不限 | | 每日告警上限 | 100 条 | 不限 | 不限 | | 公开状态页 | 1 个 | 1 个 | 5 个 | | 内部状态页 | 不支持 | 不支持 | 20 个 | | 数据保留时长 | 30 天 | 180 天 | 360 天 | | 审计日志 | 不支持 | 10 天 | 30 天 | 免费版每日最多接收 100 条告警，超出部分将被**静默丢弃**且不会返回错误。如需接收更多告警，请升级至标准版或专业版。 ### 通知额度 每个版本包含一定的免费通知额度，额度按 **每用户每月** 计算，总额度 = 单用户额度 × License 数量。 | 通知渠道 | 免费版 | 标准版 | 专业版 | | ------- | ---------- | ------------ | ------------ | | 免费短信 | 10 条/用户/月 | 500 条/用户/月 | 1,000 条/用户/月 | | 超出短信 | 停止通知 | ¥0.05/条 | ¥0.05/条 | | 免费电话 | 10 分钟/用户/月 | 50 分钟/用户/月 | 100 分钟/用户/月 | | 超出电话 | 停止通知 | ¥0.12/分钟 | ¥0.12/分钟 | | 免费邮件 | 100 封/用户/月 | 2,000 封/用户/月 | 5,000 封/用户/月 | | 超出邮件 | 停止通知 | ¥0.0018/封 | ¥0.0018/封 | | Webhook | 不限 | 不限 | 不限 | 免费版额度用尽后将**停止发送**该渠道的通知。标准版和专业版额度用尽后按量计费，如账户余额不足也会停止通知。 ### 客户支持 | 版本 | 支持方式 | 服务时间 | | --- | ------- | ------ | | 免费版 | 无 | — | | 标准版 | 邮件 / 工单 | 5×8 小时 | | 专业版 | 专属服务群 | 7×8 小时 | ### License 模式详解 与 PagerDuty 等产品对**所有用户**收费不同，Flashduty 采用 **License（活跃用户）** 计费模式——只有需要**查看和处理故障**的成员才需要 License，其他成员无需付费也能接收告警通知。 #### 谁需要 License？ | 角色 | 是否需要 License | 说明 | | ----------- | :----------: | --------------------- | | 值班工程师 | ✅ | 需要查看故障详情、认领和处理故障 | | 团队 Leader | ✅ | 需要查看故障、配置分派策略和值班表 | | 被通知的开发 / 运维 | ❌ | 只需被动接收通知，无需登录平台操作 | | 管理层 | ❌ | 通过分析看板或状态页了解全局状态即可 | | 外部协作方 | ❌ | 通过 Webhook、邮件或状态页获取信息 | **大团队成本优势**：在实际场景中，100 人的技术团队通常只有 10~~20 人需要日常参与故障处理，其余成员只需接收通知。这意味着您可能只需购买 10~~20 个 License，而不是为全部 100 人付费——**成本可降低 80%\~90%**。 #### 为什么选择 License 模式？ 传统的按人头收费（如 PagerDuty）要求所有需要接收通知的用户都购买席位，这在实践中造成了两个问题： 1. **成本浪费**：大部分团队成员只需要在故障发生时收到通知，不需要登录平台查看或处理故障，但仍需为每人支付全额席位费 2. **通知覆盖不足**：为控制成本，企业往往限制通知范围，导致关键信息无法触达相关人员 Flashduty 的 License 模式将**故障处理能力**和**通知接收能力**解耦： * **持有 License 的成员**：拥有完整的故障查看、处理、配置等权限 * **无 License 的成员**：可以被动接收所有告警通知（邮件、短信、电话、IM），共享租户通知额度，确保信息触达不受限制 这样既保证了通知的全面覆盖，又显著降低了总拥有成本。 #### License 类型 * 在购买有效期内**长期有效** * **不会被抢占** * **管理者** 可以授予成员固定 License * 适用于需要参与处理故障、配置业务的成员 * 在购买有效期内**长期有效** * 每个周期结束时**自动释放** * **管理者** 可以授予成员临时 License * 在有足够 License 时，可通过分配或抢占方式占用 * 适用于临时参与或偶尔使用的成员 #### 无 License 成员权限 没有 License 的成员功能受限，仅能被动接收告警消息。 | 能力 | 说明 | | ------- | ------------------------ | | 查看故障 | ❌ 不可查看故障列表/详情 | | 处理故障 | ❌ 不可认领、关闭等操作 | | 接收通知 | ✅ 可被动接收告警消息（邮件、短信、电话、IM） | | 被分派策略引用 | ✅ 可作为通知对象加入分派策略 | | 通知额度 | ✅ 共享租户的邮件、短信、电话套餐额度 | *** ## RUM 定价 *** RUM 采用 **按量付费**模式，根据实际使用的会话数量计费。 ### 版本对比 **¥0** / 永久免费 适用于测试体验场景 **按量付费** 适用于生产环境，各类型应用 ### 功能与定价明细 | 功能 | 免费版 | 专业版 | | ------------------- | ------------- | ---------------- | | **会话分析**（视图、资源、异常等） | 每应用 1,000 次/月 | 无限制，¥9.0 / 千次会话 | | **会话重放**（用户行为记录） | 每应用 500 次/月 | 无限制，¥12.0 / 千次会话 | | **Web 性能监控** | ❌ | ✅ | | **AI 错误追踪** | ❌ | ✅ | | **高级预置看板** | ❌ | ✅ | | **前后端关联**（Tracing） | ❌ | ✅ | ### 数据保留 | 数据类型 | 免费版 | 专业版 | | ----------------- | ---- | ---- | | 会话 / 视图 / 异常 / 操作 | 30 天 | 30 天 | | 资源 / 长任务 | 15 天 | 15 天 | 免费版适合评估产品功能，专业版按实际用量计费，无需预付大额费用。 *** ## 常见问题 *** 当月使用商业化功能（查看或处理故障）的用户即为活跃用户。**仅接收告警通知不算作活跃用户**。每个月度周期结束后： * 固定 License 保持有效 * 临时 License 自动释放 * 成员被删除时，其 License 自动释放 只有需要**登录平台查看故障详情、认领和处理故障**的成员才需要 License。仅需接收告警通知的成员无需 License。 **估算方法**：统计您团队中参与日常值班和故障响应的核心人员数量，通常为： * 一线值班工程师 * 参与故障处理的团队 Leader * 需要在平台上配置分派策略、值班表的管理员 **实际案例**：以 100 人技术团队为例，通常只有 10~~20 人需要日常登录平台处理故障，其余 80~~90 人只需在相关故障发生时收到通知。因此只需购买 10\~20 个 License，**相比全员付费可节省 80%\~90% 的费用**。 * **可以**：被动接收告警消息（邮件、短信、电话、IM），被分派策略引用为通知对象，共享租户通知额度 * **不可以**：查看/处理故障，进行任何平台配置操作 在分派策略中可以选择将故障通知给没有 License 的成员，但该成员无法对故障进行操作。这意味着您可以将整个团队纳入通知范围，而无需为每个人购买 License。 * **会话分析**：每次用户访问应用的完整会话，包含页面浏览、资源加载、异常等数据 * **会话重放**：记录用户操作行为的会话，用于回放用户交互过程 两者独立计费，按实际产生的会话数量统计。 支持。Flashduty 提供**私有化部署版**（On-Premises），功能与专业版一致，并额外支持： * 数据本地存储 * 内部系统集成 * 无公网依赖 私有化部署有较高的维护成本，收费模式与 SaaS 不同。如无特殊需求，推荐使用云服务。 如需私有化版本，请联系我们获取报价。 支持。On-call 专业版提供免费试用，试用期间可体验全部专业版功能。如需申请试用，请联系销售团队。 *** ## 联系销售 *** 如需了解更多定价细节或获取企业报价，欢迎联系我们的销售团队。 📧 [contact-us@flashcat.cloud](mailto:contact-us@flashcat.cloud)\ 📞 010-53675832 # 组织管理 Source: https://docs.flashduty.com/zh/platform/team-members 团队和成员的创建、配置与管理 ## 团队介绍 *** 团队是成员的集合，可以将不同职责或项目的成员归纳到一个团队里，用于管理**协作空间、分派通知、值班安排以及服务日历**等场景。 ## 团队管理 *** ### 团队查询 * 默认展示全部团队，可以选择只显示"我"的团队 * 支持按团队名称模糊搜索，不支持按成员搜索 ### 创建与编辑 进入团队管理页面，点击**创建团队**按钮 输入团队名称和描述，选择初始成员 确认信息后保存，团队创建完成 * 团队数量和成员数量目前无限制 * 同一个成员可以属于多个团队 * 可以随时修改团队的名称、描述和成员 ### 团队详情 点击团队名称即可进入团队详情页，在详情页中你可以： * **查看成员**：查看该团队下的所有成员列表 * **添加成员**：点击 **添加成员** 按钮，从组织成员中选择并添加到该团队 * **移除成员**：在成员列表中点击对应成员的 **移除** 按钮，将其从团队中移除 * **退出团队**：如果你是该团队的成员，可以点击 **退出团队** 主动退出 * **删除团队**：拥有团队管理权限的成员可以在详情页中删除团队 ### 删除团队 * 删除前请先确认是否有协作空间、分派策略等与该团队有关联 * 删除后关联的配置将即刻失效且不可恢复，请谨慎操作 ## 成员管理 *** 成员列表中，未验证的邮箱或手机号旁会显示警告图标。未验证的联系方式无法接收告警通知，请提醒成员及时完成验证。 ### 邀请方式 控制台支持邮件邀请，用户昵称默认为邮箱前缀，可在激活后修改。 1. 进入成员管理页面 2. 点击**邀请成员** 3. 选择邀请方式为**邮箱** 4. 输入邮箱地址和成员名称 5. 选择角色（可选） 6. 发送邀请 你可以在同一次操作中添加多个邀请成员条目，一次性批量邀请。 控制台同样支持通过手机号邀请成员。 1. 进入成员管理页面 2. 点击**邀请成员** 3. 选择邀请方式为**手机** 4. 输入手机号（支持选择国际区号）和成员名称 5. 选择角色（可选） 6. 发送邀请 通过 [Open API](/zh/api-reference/platform/members/member-invite) 进行邀请，支持邮箱和手机号邀请。 联系管理员配置[单点登录](/zh/platform/configure-sso)，新成员登录时自动创建账号。 * 系统会向被邀请人发送短信或邮件通知 * 每天邀请上限为 200 人，单次邀请至多 20 人，重新发送邀请每天至多 5 次 * 未激活账号无法接收告警相关通知 ### 变更角色 * 账户管理员可以变更成员的角色 * 成员自己可以向下变更角色，不能向上变更 了解更多角色和权限信息，请参阅[权限设计](/zh/platform/permission-design)。 ### License 管理 License 决定了成员是否可以查看和处理故障。在成员管理列表中，你可以查看和管理每位成员的 License 状态。 | License 类型 | 说明 | | ---------- | -------------------------------------------------- | | **固定** | 长期有效，不会被抢占。适用于需要持续处理故障的核心成员 | | **临时** | 每个计费周期结束时自动释放，新周期开始时重新抢占分配 | | **无** | 该成员未持有 License，无法查看和处理故障。如果存在空闲 License，可在下一周期重新抢占 | 你可以在成员列表的 License 列中执行以下操作： * **授予固定 License**：为成员分配一个固定 License，前提是当前仍有可用 License 额度 * **取消 License**：释放成员的 License，释放后该成员将无法查看和处理故障 License 总数取决于你的订阅版本。当所有 License 已分配完毕时，需要先释放其他成员的 License 或升级订阅才能为新成员分配。 ### 删除成员 * 成员一经删除，不可恢复，请谨慎操作 * 成员被删除后，该成员的历史数据不会被删除 ## 常见问题 *** 请依次检查： 1. 邮箱地址是否填写正确 2. 垃圾收件箱是否有收到 3. 邮箱是否设置了拦截策略 如果都正常，可以尝试让邀请人重新下发邀请，或联系官方技术支持。 请依次检查： 1. 手机号是否填写正确 2. 手机是否设置了拦截策略 如果都正常，可以尝试让邀请人重新下发邀请，或联系官方技术支持。 可以。如果成员 A 属于多个主体，那么在登录时会让其选择要登录的主体。 不可以。手机号或邮箱需要保证全局唯一。 手机号或邮箱是故障通知和登录控制台的重要渠道。为防止在本人不知晓的情况下被修改导致不可预期的事故，只允许本人修改且修改时需要验证。 ## 延伸阅读 *** 了解功能权限和数据权限的设计 配置 SSO 实现统一身份认证 # RUM 真实用户监控 Source: https://docs.flashduty.com/zh/rum RUM 真实用户监控能够帮您从终端用户视角出发，直观地分析和了解 Web 应用的实时性能和用户体验。 ## 什么是真实用户监控？ *** 真实用户监控（RUM）是一项创新技术，它能够追踪并分析真实用户在使用您 Web 应用时的实际体验。与传统的模拟测试不同，RUM 直接从用户浏览器采集数据，为您呈现应用在真实环境中的运行状况。 Flashduty RUM 让开发人员、运维工程师和业务相关方能够直观地了解应用性能，及时发现问题并持续优化用户体验。 ## 核心能力 *** 实时掌握页面加载时间、资源加载效率和 JavaScript 运行状况等关键性能指标，快速定位影响用户体验的瓶颈。 * **页面性能**：LCP、FID、CLS 等核心 Web 指标 * **资源分析**：图片、脚本、样式表加载耗时 * **接口监控**：API 请求响应时间和成功率 自动捕获 JavaScript 报错、网络故障等影响用户的问题，并提供丰富的上下文信息，助力快速定位和解决问题。 * **错误聚合**：相似错误自动归类 * **堆栈还原**：支持 Source Map 反解析 * **影响分析**：受影响用户数和会话数 深入分析图片、脚本、接口调用等资源的性能表现，助力优化加载速度，洞察数据变化趋势。 * **趋势分析**：性能指标随时间变化 * **维度下钻**：按浏览器、设备、地域分析 * **对比分析**：版本间性能对比 还原用户操作路径，以视频形式回放用户会话，快速复现和定位问题。 * **操作回放**：点击、滚动、输入等操作还原 * **错误定位**：直接跳转到错误发生时刻 * **隐私保护**：敏感信息自动脱敏 ## 为什么选择 Flashduty RUM？ *** 从用户视角出发，全面了解应用在不同浏览器、设备和地域下的性能表现 在问题大规模爆发前及时发现并解决，全面提升应用的稳定性 基于真实用户数据制定优化策略，告别主观臆测 与 Flashduty 监控体系深度集成，实现前后端全链路问题定位 JavaScript SDK 采用轻量化设计，gzip 后仅约 30KB，在保证数据采集的同时将性能影响降至最低。 ## 工作原理 *** Flashduty RUM 通过在您的 Web 应用中植入轻量级 JavaScript SDK 来实现数据采集： 在应用中引入 RUM SDK，配置应用 ID 和采集参数 SDK 自动采集页面访问、资源加载、用户交互、异常信息等数据 采集的数据实时传输到 Flashduty 后台进行处理和分析 通过直观的仪表盘和报表，全面掌握应用性能和用户体验状况 ### 采集数据类型 | 数据类型 | 说明 | | ---- | ------------------------- | | 页面访问 | 页面加载过程、导航耗时、用户环境信息 | | 资源加载 | 图片、脚本、样式表、接口调用的加载情况 | | 用户交互 | 点击、表单提交等操作及自定义事件 | | 异常信息 | JavaScript 异常、网络故障、控制台错误 | | 长任务 | 可能造成页面卡顿的耗时 JavaScript 任务 | ## 快速开始 *** 从零搭建用户监控体系，快速优化用户体验 了解如何在您的应用中集成 RUM SDK 深入了解性能监控相关功能 深入了解异常追踪相关功能 # 状态页 Source: https://docs.flashduty.com/zh/stsatuspage 查看 Flashduty 各服务组件的实时运行状态和历史可用性记录 # AppDynamics 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/appdynamics 通过 webhook 的方式同步 AppDynamics 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **AppDynamics** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **AppDynamics** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 AppDynamics ***
## 一、AppDynamics 告警推送配置 ### 步骤1：配置 FlashDudy 告警通道 1. 登录您的 AppDynamics 控制台。 2. 找到 `Alert Respond` ，选择 `HTTP Request Templates` 并点击 `New` 新建告警通道。 drawing 3. 在模版配置中，`Name` 填写 **Flashduty** 。 4. 在 `Request URL` 部分，`Method` 选择 **POST** ，`Raw URL` 填写集成的推送地址（当前页面填写集成名称，保存后即可生成地址）。 drawing 5. 在 `Payload` 部分，`MIME Type` 选择 `application/json`，`Payload Encoding` 选择 `UTF-8`。 6. 在 `Payload` 文本框中，粘贴一下内容： ``` { "policy_name":"${policy.name}", "message": "${latestEvent.eventMessage}", "application_name": "${latestEvent.application.name}", "link": "${latestEvent.deepLink}", "incident_id": "${latestEvent.incident.id}", "details": { "event_id": "${latestEvent.id}", "event_name": "${latestEvent.displayName}", "event_time": "${latestEvent.eventTime}", "event_type": "${latestEvent.eventType}", "health_rule_name":"${latestEvent.healthRule.name}", "node_name": "${latestEvent.node.name}", "severity": "${latestEvent.severity}" } } ``` drawing **特别说明（可选配置）** 配置：`Custom Templating Variables` drawing 如果需要配置 `Custom Templating Variables` ，可以参考以下 JSON 模版，其中 custom\_variables 是固定写法，custom\_variables 中的变量是自定义的 `Variables`，页面中定义的名称需要与 JSON 模版中引用的变量名保持一致。 ``` { "policy_name":"${policy.name}", "message": "${latestEvent.eventMessage}", "application_name": "${latestEvent.application.name}", "link": "${latestEvent.deepLink}", "incident_id": "${latestEvent.incident.id}", "details": { "event_id": "${latestEvent.id}", "event_name": "${latestEvent.displayName}", "event_time": "${latestEvent.eventTime}", "event_type": "${latestEvent.eventType}", "health_rule_name":"${latestEvent.healthRule.name}", "event_type_key": "${latestEvent.eventTypeKey}", "node_name": "${latestEvent.node.name}", "severity": "${latestEvent.severity}" }, "custom_variables":{ "host":"${host}" } } ``` 7. 在 `Response Handling Criteria` 部分，将 `Failure Criteria` 状态代码设置为 400，将 `Success Criteria` 状态代码设置为 201。 drawing 8. 点击 `Save` 保存即可。 ### 步骤2：创建 Action 1. 在左侧导航栏中选择 `Actions`，选择要为哪个应用类型创建，并点击 `Create`。 2. 在弹出的 `Create Action` 框中，选择 `Make an HTTP Request` 并点击 `OK`。 drawing 3. 在弹出的 `Create HTTP Action` 框中，输入 Name，`HTTP Request Template` 选择 `步骤1` 创建的 **Flashduty** 并点击 `SAVE`。 drawing ### 步骤3：在告警策略中使用步骤2创建的 Action 1. 在左侧导航栏中选 `Policies`。 2. 创建或编辑已有的策略（告警规则按需配置即可，此处省略告警规则的配置）。 3. 在弹出的配置策略页面的 `Actions` 处，点击添加并选择 `步骤2` 创建的 Action 。 drawing 4. 其他配置完成后，点击 `Save` 保存即可。
## 二、状态对照
| AppDynamics | Flashduty | 状态 | | ----------- | --------- | -- | | ERROR | Critical | 严重 | | WARN | Warning | 警告 | | INFO | Info | 提醒 |
# 蓝鲸智云集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/blueking 通过 webhook 的方式同步蓝鲸智云监控事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **蓝鲸智云** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **蓝鲸智云** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在蓝鲸智云 *** 以下内容已经在`蓝鲸V6/7版本`完成验证，V5 及以下版本官方已不再支持，建议您升级。 蓝鲸告警策略可以触发`处理套餐`，处理套餐可与周边系统打通，来完成复杂功能。我们首先创建一个处理套餐，配置 Flashduty 的回调地址，然后编辑告警策略，关联动作到该处理套餐，实现告警变更自动推送到 Flashduty。具体步骤如下： #### 步骤 1、创建处理套餐
1. 登录您的蓝鲸智云桌面，进入`监控平台`； 2. 进入`配置-处理套餐`页面，单击`添加套餐`按钮，开始创建处理套餐； 3. 填写名称为`Send To Flashduty`，套餐类型选择`HTTP回调`，推送方式选择`POST`，并填写集成的推送地址（保存集成后获得），如下图所示： drawing 4. 切换到`主体`，选择`JSON`类型，消息体复制并填入以下信息（实际产生告警时，蓝鲸会渲染变量内容作为 Payload 推送到目标回调地址）： ``` {{alarm.callback_message}} ``` 5. 保存套餐，完成创建。
#### 步骤 2、编辑告警策略
1. 进入`配置-告警策略`页面，选择一个已有的策略进行编辑，或新建一个告警策略； 2. 下拉到`告警处理`部分，三种场景均选择`Send To Flashduty`处理套餐，并关闭`防御规则`，如下图： drawing 3. 提交保存，完成； 4. 对于其他想要推送到 Flashduty 的告警，重复以上步骤。
## 状态对照 ***
蓝鲸智云到 Flashduty 告警等级映射关系： | 蓝鲸智云 | Flashduty | 状态 | | ---- | --------- | -- | | 致命 | Critical | 严重 | | 预警 | Warning | 警告 | | 提醒 | Info | 提醒 |
# Cloudflare 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/cloudflare 通过 webhook 的方式同步 Cloudflare 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Cloudflare** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Cloudflare** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 Cloudflare ***
## 一、告警推送配置 1. 登录您的 `Cloudflare` 控制台，转到 `通知` 菜单中，。 2. 在`Webhooks` 中点击创建。 3. 在编辑页面中，名称填写 `Flashduty` ，`URL` 处填写告警集成的推送地址。 4. 点击 `保存和测试` 完成配置。 配置 Webhook 通道后，即可在通知策略中使用。
## 二、状态对照
当前 Cloudflare 集成推送到 Flashduty 的告警等级均为 Warning，但您可以通过[告警处理 Pipeline](/zh/on-call/integration/alert-integration/alert-pipelines) 来自定义严重程度。
# Dynatrace 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/dynatrace 通过 webhook 的方式同步 Dynatrace 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理。
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Dynatrace** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Dynatrace** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 Dynatrace ***
## 一、Dynatrace 告警推送配置 1. 登录您的 Dynatrace 控制台。 2. 在左侧导航栏选择 `Apps`，在 `Manage` 区域找到 `Settings`。 drawing 3. 找到 `Integration`，选择 `Problem notifications`。
drawing
4. 点击 `Add notifycation`。 drawing 5. 在 `Notification type` 处，选择 `Custom Integraion`。 6. `Display name` 填写 `Flashduty`。 7. `Webhook URL` 填写集成的推送地址（当前页面填写集成名称，保存后即可生成地址）。 8. `Call webhook if problem is closed` 保持开启状态。 drawing 9. `Custom payload` 处，填写以下内容： ``` { "State":"{State}", "PID":"{PID}", "ProblemTitle":"{ProblemTitle}", "ProblemImpact":"{ProblemImpact}", "ProblemDetails":"{ProblemDetailsText}", "ProblemURL":"{ProblemURL}", "ProblemSeverity":"{ProblemSeverity}", "ImpactedEntityNames":"{ImpactedEntityNames}", "Tags":"{Tags}" } ``` drawing 10. 点击 `Save changes` 保存即可 。
## 二、状态对照
| Dynatrace | Flashduty | 状态 | | -------------------- | --------- | -- | | AVAILABILITY | Critical | 严重 | | ERROR | Warning | 警告 | | PERFORMANCE | Info | 提醒 | | RESOURCE\_CONTENTION | Info | 提醒 | | CUSTOM\_ALERT | Info | 提醒 |
# 观测云告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/guance 通过 webhook 的方式同步观测云告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **观测云** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **观测云** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在观测云 ***
## 一、告警推送配置 ### 步骤1：创建通知对象 1. 登录您的 `观测云` 控制台，在 `监控` 中，选择 `通知对象管理`。 2. 点击 `新建通知对象` ，选择 `Webhook`。 3. 在编辑页面中填写名称为 `Flashduty` ，`Webhook 地址` 填写告警集成的 推送地址。 4. 其他按需选择，点击 `确定` 完成创建。 drawing ### 步骤2：创建告警策略 1. 登录您的 `观测云` 控制台，在 `监控` 中，选择 `告警策略管理` 。 2. 在 `告警策略` 页面， 新建或修改告警策略。 3. 在告警策略编辑页面的通知配置部分，选择 `等级`，`通知对象` 选择步骤1中创建的 `Flashduty`。 4. 其他按需配置，点击 `保存` 完成创建。 drawing
## 二、状态对照
| 观测云 | Flashduty | 状态 | | ---- | --------- | -- | | 紧急 | Critical | 严重 | | 重要 | Warning | 警告 | | 警告 | Warning | 警告 | | 信息 | Info | 提醒 | | 数据断档 | Info | 提醒 |
# Harbor 告警集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/harbor 通过 webhook 的方式同步 Harbor 的告警事件到 Flashduty，实现告警事件自动化降噪处理 通过 webhook 的方式同步 Harbor 的告警事件到 Flashduty，实现告警事件自动化降噪处理。
## 在 Flashduty ### 创建 Harbor 告警集成 您可通过以下2种方式，获取一个 Harbor 告警集成地址，任选其一即可。 #### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Harbor** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **Harbor 告警集成地址**，复制备用，完成。 #### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Harbor** 集成： * **集成名称**：为当前集成定义一个名称。 * **推送模式**：选择告警在何种情况下触发或恢复告警。 3. 复制当前页面的 **Harbor 告警集成地址** 备用。 4. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 5. 完成。
## 在 Harbor ### 配置 Webhook 通道 1. 使用至少具有项目管理员权限的帐户登录 Harbor 界面。 2. 转到`项目`，选择一个项目，然后选择 `Webhook`。 3. 选择通知类型 `HTTP`，以便 webhook 将发送到 HTTP 端点。 4. 当选择 HTTP 通知类型时，选择有效负载格式为 `Default 或 CloudEvents`。 5. 选择您要`订阅的事件`。 6. `Endpoint URL` 输入告警集成的推送地址。 7. 单击 添加 以创建 webhook。 ## 严重程度映射关系 当前 Harbor 告警集成推送到 Flashduty 的严重程度均为 Warning，但您可以通过[告警处理 Pipeline](/zh/on-call/integration/alert-integration/alert-pipelines) 来自定义严重程度。 # 图片上传 API Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/image-upload 通过图片上传接口上传图片并获得 image_key，可在上报标准告警时通过 images 字段引用，用于在前端及飞书、钉钉应用通知中展示告警相关截图。 ## 一、功能概述 上报告警时，您可以在 [标准告警](/zh/on-call/integration/alert-integration/alert-sources/standard-alert) 的 `images` 字段中携带图片，用于在前端及飞书、钉钉应用通知中展示告警相关截图。`images` 中每张图片的 `src` 支持两种取值： * `http`/`https` 开头的公网可访问图片链接； * 通过本接口上传图片后返回的 `image_key`。 当图片没有公网链接时，可先调用图片上传接口上传图片，拿到 `image_key`，再在上报告警时引用。工作流程如下： 1. 调用图片上传接口，上传图片文件，获得 `image_key`； 2. 上报标准告警时，将 `image_key` 填入 `images[].src`； 3. Flashduty 在处理告警时解析 `image_key`，将图片关联到告警并持久化展示。 图片上传与标准告警上报共用同一个集成秘钥（`integration_key`）。请使用您在 [标准告警](/zh/on-call/integration/alert-integration/alert-sources/standard-alert) 等集成中获取的推送秘钥，无需单独申请。 ## 二、接口说明 ### 请求方式
POST，Content-Type: `multipart/form-data`
### 请求地址
``` {api_host}/push/image/upload?integration_key={integration_key} ``` 其中 `{api_host}` 为 Flashduty 的接入域名，公有云默认为 `https://api.flashcat.cloud`，与您的告警推送地址保持一致。
### 请求参数 **Query 参数：** | 参数 | 必含 | 类型 | 释义 | | :--------------: | :-: | :----: | :-------------------------------- | | integration\_key | 是 | string | 集成秘钥，用于确定账户。添加集成后获得，与告警推送共用同一个秘钥。 | **Form-Data 参数：** | 参数 | 必含 | 类型 | 释义 | | :---: | :-: | :--: | :------------------------------------------------- | | image | 是 | file | 待上传的图片文件，单文件最大 `5MB`。系统根据文件内容（而非扩展名）识别格式，支持的格式见下表。 | **支持的图片格式：** | 格式 | Content-Type | | :--: | :------------------------------------ | | JPEG | image/jpeg、image/jpg | | PNG | image/png | | WebP | image/webp | | GIF | image/gif | | TIFF | image/tiff、image/tif | | BMP | image/bmp | | ICO | image/x-icon、image/vnd.microsoft.icon | ### 请求响应 | 字段名称 | 必选 | 类型 | 描述 | | :---------: | :-: | :-------------: | :------------- | | request\_id | 是 | string | 请求 ID，用于链路追踪 | | error | 否 | [Error](#Error) | 错误描述，仅当出现错误时返回 | | data | 否 | [Data](#Data) | 上传结果 | Data： | 字段名称 | 必选 | 类型 | 描述 | | :--------: | :-: | :----: | :------------------------------------------------------ | | image\_key | 是 | string | 图片标识，形如 `img_`。在上报标准告警时填入 `images[].src` 即可引用该图片。 | Error： | 字段名称 | 必选 | 类型 | 描述 | | :-----: | :-: | :----: | :---------------------- | | code | 是 | string | 错误码，枚举值参考 [Code](#Code) | | message | 否 | string | 错误描述 | Code： | 错误码 | HTTP Status | 描述 | | :------------------: | :---------: | :--------------------------------- | | InvalidParameter | 400 | 参数错误，如缺少 image 文件、图片格式不支持或文件超过 5MB | | Unauthorized | 401 | integration\_key 缺失或无效，或集成、账户已被禁用 | | RequestTooFrequently | 429 | 请求过于频繁，超过频率限制 | | InternalError | 500 | 内部或未知错误 | ### 频率限制 为保护服务稳定，图片上传按账户限流： * 每账户每秒最多 `5` 次； * 每账户每分钟最多 `50` 次。 超过限制时返回 `RequestTooFrequently`（HTTP 429）。 ## 三、请求示例 请求： ```bash theme={null} curl -X POST '{api_host}/push/image/upload?integration_key={integration_key}' \ -F 'image=@/path/to/screenshot.png' ``` 成功响应： ```json theme={null} { "request_id": "0ace00116215ab4ca0ec5244b8fc54b0", "data": { "image_key": "img_8f3a9c2b1e4d5f6a7b8c9d0e1f2a3b4c" } } ``` ## 四、在告警中引用图片 拿到 `image_key` 后，在上报 [标准告警](/zh/on-call/integration/alert-integration/alert-sources/standard-alert) 时，将其填入 `images` 数组中某张图片的 `src` 字段即可： ```json theme={null} { "event_status": "Warning", "title_rule": "cpu idle low than 20%", "labels": { "service": "engine" }, "images": [ { "alt": "CPU 使用率截图", "src": "img_8f3a9c2b1e4d5f6a7b8c9d0e1f2a3b4c" } ] } ``` `images` 与 `image` 结构体的完整字段说明，请参考 [标准告警 - image 结构体](/zh/on-call/integration/alert-integration/alert-sources/standard-alert#image)。 * `image_key` 在 `images[].src` 中的长度限制为 `256` 字符，超长会被丢弃。 * 上传后的图片先临时存储，被告警引用后才会转为长期存储。请在上传后及时将 `image_key` 用于告警上报。 ## 五、常见问题 1. **重复上传同一张图片会怎样？** * 系统按图片内容去重。上传内容完全相同的图片会返回相同的 `image_key`，不会重复占用存储。 2. **可以直接使用图片的公网链接吗？** * 可以。如果图片已有 `http`/`https` 公网可访问链接，无需上传，直接将链接填入 `images[].src` 即可。图片上传接口仅用于没有公网链接的场景。 3. **image\_key 可以跨账户使用吗？** * 不可以。`image_key` 与上传时所用 `integration_key` 归属的账户绑定，仅在同一账户内有效。 # 京东云监控集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/jdcloud 通过 webhook 的方式同步京东云监控告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **京东云监控** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **京东云监控** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在京东云 *** 1. 登录京东云控制台，检索 **云监控** 产品，进入对应控制台 2. 在左侧菜单选择 **告警管理 → 通知模版**，创建或编辑通知模版 3. 勾选 **告警回调**，在 `URL` 中输入集成的推送地址 4. 在 `POST` 编辑框中输入以下模版内容： ```json theme={null} { "resource_id": "${resourceId}", "request_id": "${requestId}", "metric": "${metric}", "current_value": "${currentValue}", "times": "${times}", "tags": "${tags}", "alert_time": "${alertTime}", "region": "${region}", "threshold": "${threshold}", "service_code": "${serviceCode}", "as_group_id": "${asGroupId}", "unhealthy_instance": "${unhealthyInstance}", "rule_policy_id": "${rulePolicyId}", "service_code_en": "${serviceCodeEN}", "service_code_cn": "${serviceCodeCN}", "level": "${level}", "resource_name": "${resourceName}", "ip_address": "${ipAddress}", "status": "${status}" } ``` 5. 其他选项按需配置，点击 **保存** 完成 1. 在左侧菜单选择 **告警管理 → 全部告警规则**，创建或编辑告警规则 2. 在规则配置页面的 **通知策略** 处，选择 **使用模版** 并选择上一步创建的模版 3. 其他选项按需配置，点击 **保存** 完成 回到 Flashduty 控制台集成列表页面，如果展示了最新事件时间，说明配置成功且收到事件。 ## 状态对照 ***
京东云监控到 Flashduty 告警等级映射关系： | 京东云监控 | Flashduty | 状态 | | :---- | :-------- | :- | | 紧急 | Critical | 严重 | | 严重 | Warning | 警告 | | 一般 | Info | 提醒 |
# 监控宝告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/jiankongbao 通过 webhook 的方式同步监控宝告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **监控宝** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **监控宝** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在监控宝 ***
## 一、监控宝告警推送配置 ### 步骤1：配置告警通道 1. 登录监控宝控制台。 2. 点击右上方的个人配置。 drawing 3. 点击左侧导航栏中的 Webhooks 设置，并点击添加以及选择 URL 回调。 drawing 4. 自定义名称输入 Flashduty，回调 URL 输入复制集成的推送地址。 5. 回调方式选择 **POST**，数据格式选择 **JSON**。 6. 勾选**开启 URL 回调**，其他按需选择即可，参考下图配置。 drawing 7. 点击保存。 ### 步骤2：在监控任务使用 Flashduty 告警通道 1. 创建或编辑已有的监控任务。 2. 此处省略其他告警配置。 3. 在 Webhook 通知处，选择 Flashduty 通道。 drawing 4. 保存监控任务即可。
## 二、状态对照
| 监控宝 | Flashduty | 状态 | | --- | --------- | -- | | 1 | Warning | 警告 | | 2 | Info | 提醒 |
# 标签映射 API Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/label-mapping-api 配置标签映射 API，当告警事件到达时，Flashduty 将自动调用您配置的外部 API 获取增强标签，实现告警信息的动态丰富和关联。通过此功能，您可以将 CMDB、HR 系统等外部数据源的信息自动附加到告警上。 ## 一、功能概述 标签映射 API 允许您构建自定义的外部服务来增强告警标签。工作流程如下： 1. Flashduty 接收到告警事件 2. 系统根据配置，将事件信息和期望获取的标签列表发送到您的 API 3. 您的 API 查询外部数据源（如 CMDB、数据库等） 4. API 返回计算得到的增强标签 5. Flashduty 将返回的标签附加到告警上 ## 二、API 规范 ### 请求方式
POST, Content-Type:"application/json"
### 请求 Payload：
| 字段 | 类型 | 必含 | 释义 | | :-----------------: | :-------------: | :-: | :-------------------------------- | | result\_label\_keys | \[]string | 是 | 期望返回的标签 Key 列表，由用户在 Flashduty 中配置 | | event | [Event](#Event) | 是 | 当前告警事件的完整信息 | **Event**: | 字段 | 类型 | 必含 | 释义 | | :----------------: | :----------------: | :-: | :-------------------------------- | | account\_id | int64 | 是 | 账户 ID | | channel\_id | int64 | 是 | 协作空间 ID | | data\_source\_id | int64 | 是 | 数据源 ID | | data\_source\_type | string | 是 | 数据源类型，如 prometheus、zabbix 等 | | title | string | 是 | 告警标题 | | title\_rule | string | 否 | 标题规则 | | description | string | 否 | 告警描述 | | alert\_key | string | 是 | 告警唯一标识 | | alert\_id | string | 是 | 告警 ID | | event\_severity | string | 是 | 事件严重程度，枚举值：Critical、Warning、Info | | event\_status | string | 是 | 事件状态，枚举值：Critical、Warning、Info、Ok | | event\_time | int64 | 是 | 事件时间，Unix 秒时间戳 | | labels | map\[string]string | 否 | 告警原始标签 KV | | images | \[]string | 否 | 告警关联图片列表 |
### 请求示例
```json theme={null} { "result_label_keys": ["owner_team", "service_tier", "host_ip"], "event": { "account_id": 1, "channel_id": 20, "data_source_id": 15, "data_source_type": "prometheus", "description": "CPU usage for instance '10.0.1.101:9100' is over 95%", "title": "High CPU Usage on instance 10.0.1.101:9100", "title_rule": "", "alert_key": "d41d8cd98f00b204e9800998ecf8427e", "alert_id": "62d6c0f6b8f1b2b3c4d5e6f7", "event_severity": "Critical", "event_status": "Critical", "event_time": 1678886400, "labels": { "region": "us-east-1", "service": "service-A", "env": "production", "instance": "10.0.1.101:9100" }, "images": [] } } ```
### 响应规范
**成功响应：** | 字段 | 类型 | 必含 | 释义 | | :------------: | :----------------: | :-: | :------------ | | result\_labels | map\[string]string | 是 | 返回的增强标签 KV 对象 | * HTTP 状态码：`200 OK` * 响应体必须是包含 `result_labels` 字段的 JSON 对象 * `result_labels` 的 Key 必须是请求中 `result_label_keys` 指定的标签名 * 如果某个标签无法获取，**不应**在响应中包含该 Key **成功响应示例：** ```json theme={null} { "result_labels": { "owner_team": "team-database", "service_tier": "tier-1", "host_ip": "10.0.1.101" } } ``` **失败响应：** | 状态码 | 含义 | | :-------------: | :------------------------ | | 404 Not Found | 根据 event 信息无法找到任何可用于增强的数据 | | 400 Bad Request | 请求体格式错误或 event 对象缺少关键字段 | | 5xx | API 内部发生非预期的错误（如数据库连接失败） | > **提示：** 返回 `200 OK` 状态码 + 空的 `result_labels: {}` 对象也会被视为"无结果"，但使用 `404` 状态码是更规范的做法。
## 三、配置映射服务 在 Flashduty 中配置标签映射时，您需要先创建一个映射服务，然后在标签增强规则中引用该服务。 ### 映射服务字段说明
| 字段名 | 类型 | 必填 | 释义 | | :--------------------: | :----------------: | :-: | :------------------------------------------------ | | api\_name | string | 是 | 服务的可读名称，用于在 UI 中选择和引用，例如 "CMDB 资产查询 API" | | description | string | 否 | 对该服务的详细描述 | | url | string | 是 | API 的请求 URL，支持使用模板变量 | | headers | map\[string]string | 否 | HTTP 请求头，用于传递自定义认证信息，受[安全黑名单](#HeaderBlacklist)限制 | | timeout | int | 否 | 请求超时时间（单位：秒），可取值：1\~3 | | retry\_count | int | 否 | 请求失败后的重试次数，可取值：0\~1 | | insecure\_skip\_verify | bool | 否 | 请求 HTTPS 时跳过证书验证 | | status | string | 否 | 服务状态，如 enabled、disabled |
### 标签增强规则配置 配置标签增强规则时，只需要关注以下配置： 1. **result\_label\_keys**：指定期望从 API 获取的标签列表，Flashduty 会自动将此列表和当前的 `event` 对象组合成请求体发送给您的 API 2. **映射服务**：选择或配置 API 服务的 URL、Headers 等信息 ## 四、Header 安全约束 为了防止安全绕过、请求走私、IP 伪造及缓存污染，在自定义 API 请求头时，**禁止**使用以下 Header。系统网关将自动过滤或拒绝包含这些 Header 的请求。
| 分类 | 禁用 Header | 风险说明 | | :------------- | :------------------------------------------------------------------------------ | :--------------------------- | | **认证与授权** | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` | 防止凭证泄露或非法劫持已有的认证上下文 | | **IP 与地理位置伪造** | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` | 防止客户端伪造来源 IP 以绕过频率限制或黑白名单 | | **主机与路由操控** | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` | 防止 Host 注入攻击、重定向循环或伪造内部系统 ID | | **协议与请求走私** | `transfer-encoding`, `upgrade`, `connection` | 防止利用 HTTP 协议差异进行的请求走私攻击 |
### Header 最佳实践 1. **白名单模式**：建议仅允许以 `X-Custom-` 或 `X-Enrich-` 为前缀的自定义 Header 2. **长度限制**：单个 Header 的 Key 或 Value 长度不应超过 1024 字节 3. **格式校验**：Header 的 Value 严禁包含换行符（`\r`、`\n`），以防止 Header 注入攻击 ## 五、最佳实践 1. **性能优先：** 此 API 位于告警处理的关键路径上，必须保证低延迟。对外部数据源的查询应尽可能快，建议实现缓存机制。 2. **明确的错误处理：** 善用 HTTP 状态码（特别是 `404`）来传递清晰的执行结果。 3. **幂等性：** API 的设计应尽可能幂等。对于同一个 `event`，多次调用应返回相同的结果。 4. **安全性：** API 必须通过认证和授权机制进行保护，推荐使用自定义 Header（如 `X-Custom-Auth`）传递认证信息。 ## 六、常见问题 1. **服务是否有响应超时时间？** * 服务需要在配置的超时时间内返回响应，超时则认为响应失败 2. **如果 API 返回失败会怎样？** * 告警会正常处理，但不会附加增强标签 * 根据配置的重试次数，系统可能会重试请求 3. **result\_label\_keys 可以动态变化吗？** * 是的，您可以在 Flashduty 中随时修改期望获取的标签列表，无需修改 API 代码 # Meraki 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/meraki 通过 webhook 的方式同步 Meraki 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Meraki** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Meraki** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 Meraki ***
## 一、Meraki 告警推送配置 1. 登录您的 `Meraki` 控制台，选择需要配置告警的设备。 2. 在 `Alerts` 页面中，按需配置 `Cellular gateway` 和其他部分。 3. 在 `Webhooks` 处，配置 `HTTPS receivers`。 4. `Name` 填写 `Flashduty`，`URL` 填写**告警集成的推送地址**。 5. `Shared secret` 留空，`Payload template` 保持默认的 `Meraki(included)` 即可。 6. 点击 `Save` 保存。 drawing
## 二、状态对照
| Meraki | Flashduty | 状态 | | ------------- | --------- | -- | | critical | Critical | 严重 | | warning | Warning | 警告 | | informational | Info | 提醒 |
# Monit 告警集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/monit Flashduty Monit 告警集成，Monit 服务通过此集成上报告警 当您开通 Monit 服务时，系统会自动为您创建此集成。此集成用于收集 Monit 服务产生的告警事件。 :::tips 您无法修改或删除此集成。但您可以管理集成下的标签增强、告警处理以及路由等规则。 ::: ## 如何开启 Monit 告警 前往`Monit`-`告警规则`-`规则详情`页面，配置监控指标和阈值等条件，并开启告警。您可以选择将告警投递至多个协作空间。告警的通知规则遵循协作空间下的分派策略，您可以为团队设定值班人员，在告警发生时分派给值班人。 ![2025-08-19-20-35-45](https://docs-cdn.flashcat.cloud/images/png/59c9d2566db9a0482fb2eabb729ea739.png) 某些情况下，您可能希望将同一个告警规则产生的告警，按条件路由到不同的协作空间，这个时候您可以选择将告警直接投递到集成，而非协作空间列表。并在当前集成下，设置路由规则。 # Nagios 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/nagios 通过 webhook 的方式同步 Nagios 告警事件到 Flashduty，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Nagios** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Nagios** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 Nagios ***
不同的系统和安装方式，Nagios 的安装路径可能不同，请根据实际情况调整以下配置中的路径。 ### 一、下载通知脚本 登录 Nagios Server 所在服务器，下载通知脚本到 Nagios 插件目录： * **Debian/Ubuntu 系统**（通常为 `/usr/lib/nagios/plugins/`）： ```bash theme={null} cd /usr/lib/nagios/plugins/ wget --header="Referer: https://console.flashcat.cloud" https://download.flashcat.cloud/flashduty/integration/nagios/send_to_flashduty.sh chmod +x send_to_flashduty.sh ``` * **RHEL/CentOS 系统**（通常为 `/usr/lib64/nagios/plugins/`）： ```bash theme={null} cd /usr/lib64/nagios/plugins/ wget --header="Referer: https://console.flashcat.cloud" https://download.flashcat.cloud/flashduty/integration/nagios/send_to_flashduty.sh chmod +x send_to_flashduty.sh ``` * **源码安装**（通常为 `/usr/local/nagios/libexec/`）： ```bash theme={null} cd /usr/local/nagios/libexec/ wget --header="Referer: https://console.flashcat.cloud" https://download.flashcat.cloud/flashduty/integration/nagios/send_to_flashduty.sh chmod +x send_to_flashduty.sh ``` 脚本中使用了 `curl` 命令，请确保 Nagios Server 上已安装 curl。 ### 二、创建 Flashduty 配置文件 下载 Flashduty 配置文件到 Nagios 配置目录： * **Debian/Ubuntu 系统**（通常为 `/etc/nagios3/conf.d/`）： ```bash theme={null} cd /etc/nagios3/conf.d/ wget --header="Referer: https://console.flashcat.cloud" https://download.flashcat.cloud/flashduty/integration/nagios/flashduty.cfg ``` * **RHEL/CentOS 系统**（通常为 `/etc/nagios/objects/`）： ```bash theme={null} cd /etc/nagios/objects/ wget --header="Referer: https://console.flashcat.cloud" https://download.flashcat.cloud/flashduty/integration/nagios/flashduty.cfg ``` * **源码安装**（通常为 `/usr/local/nagios/etc/objects/`）： ```bash theme={null} cd /usr/local/nagios/etc/objects/ wget --header="Referer: https://console.flashcat.cloud" https://download.flashcat.cloud/flashduty/integration/nagios/flashduty.cfg ``` ### 三、修改配置文件 编辑下载的 `flashduty.cfg` 文件，修改以下内容： 1. 将 `pager` 字段的值替换为你在 Flashduty 控制台获取的集成推送地址 2. 根据你的 Nagios 安装路径，修改 `command_line` 中脚本的路径 配置文件内容示例： ``` define contact { contact_name Flashduty alias Flashduty Alert Receiver service_notification_commands notify-service-by-Flashduty host_notification_commands notify-host-by-Flashduty service_notification_options w,u,c,r host_notification_options d,u,r service_notification_period 24x7 host_notification_period 24x7 pager } define command { command_name notify-host-by-Flashduty command_line /send_to_flashduty.sh type=HOST WEBHOOK_URL="$CONTACTPAGER$" hostname="$HOSTNAME$" state="$HOSTSTATE$" output="$HOSTOUTPUT$" notification_type="$NOTIFICATIONTYPE$" time="$LONGDATETIME$" host_address="$HOSTADDRESS$" host_alias="$HOSTALIAS$" check_command="$HOSTCHECKCOMMAND$" } define command { command_name notify-service-by-Flashduty command_line /send_to_flashduty.sh type=SERVICE WEBHOOK_URL="$CONTACTPAGER$" hostname="$HOSTNAME$" state="$SERVICESTATE$" output="$SERVICEOUTPUT$" notification_type="$NOTIFICATIONTYPE$" time="$LONGDATETIME$" host_address="$HOSTADDRESS$" service_desc="$SERVICEDESC$" host_alias="$HOSTALIAS$" max_attempts="$MAXSERVICEATTEMPTS$" } ``` 参数说明： * `pager`：Flashduty 推送地址，即你在 Flashduty 控制台获取的集成推送地址 * ``：需要替换为实际的脚本路径，如 `/usr/local/nagios/libexec` * `service_notification_options`：服务告警通知选项，w=警告，u=未知，c=严重，r=恢复 * `host_notification_options`：主机告警通知选项，d=宕机，u=不可达，r=恢复 如需在告警中携带更多信息，可以在 `command_line` 末尾按照 `key=value` 格式追加参数，例如：`environment="production" region="$_HOSTREGION$"`。这些参数将作为标签（labels）推送到 Flashduty。 ### 四、引入配置文件 如果你使用的是 **RHEL/CentOS 系统** 或 **源码安装**，需要在 Nagios 主配置文件中引入 Flashduty 配置文件。 * **RHEL/CentOS 系统**：编辑 `/etc/nagios/nagios.cfg`，添加： ``` cfg_file=/etc/nagios/objects/flashduty.cfg ``` * **源码安装**：编辑 `/usr/local/nagios/etc/nagios.cfg`，添加： ``` cfg_file=/usr/local/nagios/etc/objects/flashduty.cfg ``` Debian/Ubuntu 系统通常会自动加载 `/etc/nagios3/conf.d/` 目录下的所有配置文件，无需手动引入。 ### 五、将 Flashduty 添加到联系人组 编辑联系人配置文件，将 Flashduty 联系人添加到 `admins` 联系人组（或你使用的其他联系人组）： * **Debian/Ubuntu 系统**：编辑 `/etc/nagios3/conf.d/contacts_nagios2.cfg` * **RHEL/CentOS 系统**：编辑 `/etc/nagios/objects/contacts.cfg` * **源码安装**：编辑 `/usr/local/nagios/etc/objects/contacts.cfg` 找到联系人组定义，将 Flashduty 添加到成员列表： ``` define contactgroup { contactgroup_name admins alias Nagios Administrators members nagiosadmin,Flashduty } ``` ### 六、验证配置并重启服务 1. 验证 Nagios 配置文件： * **Debian/Ubuntu 系统**： ```bash theme={null} /usr/sbin/nagios3 -v /etc/nagios3/nagios.cfg ``` * **RHEL/CentOS 系统**： ```bash theme={null} /usr/sbin/nagios -v /etc/nagios/nagios.cfg ``` * **源码安装**： ```bash theme={null} /usr/local/nagios/bin/nagios -v /usr/local/nagios/etc/nagios.cfg ``` 2. 如果验证通过，重启 Nagios 服务： ```bash theme={null} # Debian/Ubuntu systemctl restart nagios3 # RHEL/CentOS/源码安装 systemctl restart nagios ``` 3. 完成配置后，当 Nagios 检测到告警时，将自动推送到 Flashduty。
## 状态对照 ***
Nagios 到 Flashduty 告警等级映射关系： | Nagios | Flashduty | 状态 | | ----------- | --------- | -- | | CRITICAL | Critical | 严重 | | DOWN | Critical | 严重 | | UNREACHABLE | Critical | 严重 | | WARNING | Warning | 警告 | | OK | Ok | 恢复 | | UP | Ok | 恢复 | | UNKNOWN | Info | 提醒 |
# OceanBase 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/oceanbase 通过 webhook 的方式同步 OceanBase 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **OceanBase** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **OceanBase** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 OceanBase ***
## 一、OceanBase告警推送配置 ### 步骤1：配置告警通道 1. 登录您的OceanBase控制台，选择告警中心。 2. 进入**告警通道** ，单击**新建通道**按钮，开始新建。 3. 通道类型选择 **自定义脚本** 。 4. 基本配置内容，如下图所示： drawing 5. 配置通道中复制以下脚本内容，同时**请将脚本中的 integration\_key 参数补充上 Flashduty 推送地址中的 integration\_key 值**。 ``` #!/usr/bin/env bash function sendToFlashduty() { URL="${address}/event/push/alert/standard?integration_key=${integration_key}" curl -s -X POST ${URL} -H 'Content-Type: application/json' -d '{ "event_status": "'${alert_level}'", "alert_key": "'${alarm_id}'", "description": "'"${alarm_description//\"/\\\"}"'", "title_rule": "$app_types::$name::$alarm_targets", "event_time":'${timestamp}', "labels": { "app_types":"'${app_type}'", "id":"'${alarm_id}'", "name":"'${alarm_name}'", "alarm_level":"'${alarm_level}'", "alarm_status":"'${alarm_status}'", "alarm_active_at":"'${alarm_active_at}'", "alarm_threshold":"'${alarm_threshold}'", "alarm_type":"'${alarm_type}'", "alarm_targets":"'${alarm_target}'", "ob_cluster_group":"'${ob_cluster_group}'", "ob_cluster":"'${ob_cluster}'", "hostIP":"'${host_ip}'", "app_cluster":"'${app_cluster}'", "alarm_description":"'"${alarm_description//\"/\\\"}"'", "alarm_url":"'${alarm_url}'" } }' return $? } alarm_name=$(echo ${alarm_name} | sed "s/ /_/g") alarm_target=$(echo ${alarm_target} | sed "s/ /_/g") #使用告警更新时间作为告警产生时间 timestamp=$(TZ=UTC date -d "${alarm_updated_at}" +%s) #OceanBase告警通知的状态和级别是中文，所以先转Md5，再做判断 levelMd5=$(echo ${alarm_level} | md5sum | awk '{print$1}') statusMd5=$(echo ${alarm_status} | md5sum | awk '{print$1}') #状态Md5 active="048d106318302b41372b4292b5696ad4" Inactive="bf7da164d431439fe9668fbc964110c4" #告警级别Md5 down="2e1558b0a152fae2dd15884561b1508d" critical="59b9b38574ca2ee4f5e264b56f49a83f" alert="723931b03a5d1cec59eac40cf0703580" caution="abf4d55ba8926eff32cb44065e634ed3" info="6aae3f4254789d72aa0cc8ed55b8f11f" address="https://api.flashcat.cloud" integration_key="" #将OceanBase的告警级别定义做转换 if [[ ${statusMd5} == ${Inactive} ]];then alert_level="Ok" timestamp=$(TZ=UTC date -d "${alarm_resolved_at}" +%s) elif [[ ${statusMd5} == "${active}" ]];then if [[ ${levelMd5} == ${down} || ${levelMd5} == ${critical} ]];then alert_level="Critical" elif [[ ${levelMd5} == ${alert} ]];then alert_level="Warning" elif [[ ${levelMd5} == ${caution} || ${levelMd5} == ${info} ]];then alert_level="Info" fi fi #只有状态是告警中或恢复告警才发通知，屏蔽或抑制的不发通知 if [[ ${statusMd5} == ${active} || ${statusMd5} == ${Inactive} ]];then sendToFlashduty fi ``` 6. Response 校验信息填写 即可。 7. 消息配置中的告警消息格式选择 Markdown。 8. 告警消息模板 **选择简体中文**，并填写以下内容并提交。 ``` OCP告警通知-单条告警 - 告警ID： ${alarm_id} - 名称：${alarm_name} - 级别：${alarm_level} - 告警对象：${alarm_target} - 服务： ${service} - 概述：${alarm_summary} - 生成时间：${alarm_active_at} - 更新时间： ${alarm_updated_at} - 恢复时间：${alarm_resolved_at} - 详情：${alarm_description} - 状态： ${alarm_status} - 告警类型： ${alarm_type} - 告警阈值： ${alarm_threshold} - 集群组： ${ob_cluster_group} - 集群： ${ob_cluster} - 主机： ${host_ip} - 应用集群： ${app_cluster} - OCP链接：${alarm_url} ``` ### 步骤2：配置告警推送 1. 新建推送配置，路径：**告警中心=>告警推送=>新建推送配置**。 2. 推送类型、指定对象按需配置即可。 drawing 3. 推送语言选择 **简体中文**。 4. 告警通道选择 **Flashduty** 。 5. 开启 **恢复通知**。 6. 提交。 drawing
## 二、状态对照
| OceanBase | Flashduty | 状态 | | --------- | --------- | -- | | 停服 | Critical | 严重 | | 严重 | Warning | 严重 | | 警告 | Warning | 警告 | | 注意 | Info | 提醒 | | 提醒 | Info | 提醒 |
## 状态对照 ***
| OceanBase | Flashduty | 状态 | | --------- | --------- | -- | | 停服 | Critical | 严重 | | 严重 | Warning | 严重 | | 警告 | Warning | 警告 | | 注意 | Info | 提醒 | | 提醒 | Info | 提醒 |
# Opmanager 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/opmanager 通过 webhook 的方式同步 Opmanager 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **OpManager** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **OpManager** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 OpManager ***
## 一、OpManager 告警推送配置 1. 登录您的 `OpManager` 控制台，在导航菜单中选择 `Settings => Notification Profiles`。 2. 在 `Notifications` 页面中，点击 `Add` 后选择 `Invoke a Webhook` 添加配置文件。 drawing 3. 开始在 Webhook 编辑页面进行配置具体内容。 4. `Hook URL` 中的请求方法选择 `POST`，`URL` 填写**告警集成的推送地址**。 5. `Data Type` 选择 `raw`，`Payload Type` 选择 `JSON`。 6. `Body Content` 填写以下内容： ``` { "alarmid":"$alarmid", "message":"$message", "displayName":"$displayName", "category":"$category", "severity":"$stringseverity", "strModTime":"$strModTime", "eventType":"$eventType", "entity":"$entity", "lastPolledValue":"$lastPolledValue", "Intf_ifDescr":"$IntfField(ifDescr)", "Intf_displayName":"$IntfField(displayName)", "Intf_ifAlias":"$IntfField(ifAlias)", "Intf_ifName":"$IntfField(ifName)", "Intf_ipAddress":"$IntfField(ipAddress)", "Intf_physMedia":"$IntfField(physMedia)", "Intf_ifIndex(ifIndex)":"$IntfField(ifIndex)", "Intf_ifCircuitID(ifCircuitID)":"$IntfField(ifCircuitID)", "Intf_ifSpeedIn(ifSpeedIn)":"$IntfField(ifSpeedIn)", "Intf_ifSpeedOut(ifSpeedOut)":"$IntfField(ifSpeedOut)", "Intf_lineID":"$IntfCustomField(Circuit ID)", "Intf_note":"$IntfCustomField(Comments)", "Intf_contacts":"$IntfCustomField(Contact Name)", "Intf_SLA":"$IntfCustomField(SLA)", "Custom_BuildingNo":"$CustomField(Building)", "Custom_cabinet":"$CustomField(Cabinet)", "Custom_note":"$CustomField(Comments)", "Custom_contacts":"$CustomField(Contact Name)", "Custom_department":"$CustomField(Department)", "Custom_RoomNo":"$CustomField(Floor)", "Custom_serial":"$CustomField(SerialNumbe)", "Monitor_monitorName":"$MonitorField(monitorName)", "Monitor_instance":"$MonitorField(instance)", "Monitor_protocol":"$MonitorField(protocol)", "Device_type":"$DeviceField(type)", "Device_ipAddress":"$DeviceField(ipAddress)", "Device_isSNMP":"$DeviceField(isSNMP)", "Device_dependent":"$DeviceField(dependent)", "Device_hardDiskSize":"$DeviceField(hardDiskSize)", "Device_ramSize":"$DeviceField(ramSize)" } ``` **特殊说明** ：暂不支持添加额外的自定义字段，即使在 Body Content 中引用了自定义字段，也不会生效。 7. `Request Headers` 保持默认的即可。 8. `Time Out` 填写 1-300 之间的任意值，并点击下一步。 drawing 9. 在 `Choose the criteria` 配置条件页面中勾选 `Notify when the alarm is cleared`，其他按需配置即可。 drawing 10. 选择希望应用此配置文件的设备，使用右箭头将它们移动到选定设备窗口，然后点击下一步。 11. Time Window/Delayed Trigger/Recurring Trigger 可按需配置，然后点击下一步。 12. 为该配置文件添加名称 `Flashduty`，然后点击 `Save` 保存即可完成配置。
## 二、状态对照
| OpManager | Flashduty | 状态 | | ------------ | --------- | -- | | Critical | Critical | 严重 | | Service Down | Critical | 严重 | | Trouble | Warning | 警告 | | Attention | Info | 提醒 |
# PagerDuty集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/pagerduty 使用兼容 PagerDuty Events API 的协议向 Flashduty On-call 推送告警，实现告警接入与自动降噪。 Flashduty 实现了 PagerDuty Events API，输入和响应完全兼容。因此您可以通过 PagerDuty 协议推送告警事件到 Flashduty On-call，实现告警事件自动化降噪处理。 同样的，对于已经支持推送事件到 PagerDuty 的告警系统（如 ElastAlert），你仅需要修改目的推送地址，即可利用 PagerDuty 协议推送事件到 Flashduty 。
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **PagerDuty** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **PagerDuty** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 PagerDuty *** ### 请求地址 ``` {api_host}/event/push/alert/pagerduty ``` 该地址同时支持 PagerDuty V1 和 V2 Events API。**您必须修改 PagerDuty 地址为该地址。** ### Pagerduty V2 Events
#### 参考文档： [PagerDuty V2 Events](https://developer.pagerduty.com/api-reference/368ae3d938c9e-send-an-event-to-pager-duty) #### 鉴权方式： 两种方式任选其一： * 方式 1：在 QueryString 中包含参数 integration\_key * 方式 2：将 integration\_key 作为 routing\_key 参数传入 Payload
### Pagerduty V1 Events
#### 参考文档： [PagerDuty V1 Events](https://developer.pagerduty.com/api-reference/f0037990796c8-send-an-event-to-pager-duty) #### 鉴权方式： 两种方式任选其一： * 方式 1：在 QueryString 中包含参数 integration\_key * 方式 2：将 integration\_key 作为 service\_key 参数传入 Payload
### 配置示例 以 [ElastAlert2](https://github.com/jertel/elastalert2) 为例:
1. 步骤 1：获得推送地址 在当前页面填写集成名称并保存，重新打开集成详情，复制推送地址，如： ``` {api_host}/event/push/alert/pagerduty?integration_key=xxx ``` 2. 步骤 2：修改推送地址 修改已经部署好的 ElastAlert 实例对应源码，[查看 diff ](https://github.com/jertel/elastalert2/commit/e815a62a6b1eecef6e1fef13afd99d905b67fc34)： drawing 3. 步骤 3：上报告警事件 遵循 [ElastAlert PagerDuty 推送配置文档](https://elastalert2.readthedocs.io/en/latest/ruletypes.html#pagerduty) 步骤，配置告警： ``` name: "b" type: "frequency" index: "pgy_audit*" is_enabled: true num_events: 1 realert: minutes: 1 terms_size: 50 scan_entire_timeframe: true timeframe: minutes: 60 timestamp_field: "created_at" timestamp_type: "unix_ms" use_strftime_index: false alert_subject: "Test {0} 123 aa☃ {1}" alert_subject_args: - "account_id" - "operation" alert_text: "Test {0} 123 bb☃ {1}" alert_text_args: - "request_id" - "operation_name" filter: - query: query_string: query: "created_at:*" # ------- Flashduty ---------------- alert: pagerduty pagerduty_service_key: xxx pagerduty_client_name: wahaha pagerduty_api_version: v2 pagerduty_v2_payload_class: ping failure pagerduty_v2_payload_component: mysql pagerduty_v2_payload_group: app-stack pagerduty_v2_payload_severity: error pagerduty_v2_payload_source: mysql.host.name # ------- Flashduty ---------------- ``` 4. 步骤 4：重启 ElastAlert，等待告警触发
# Sentry 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/sentry 通过 webhook 的方式同步 Sentry 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Sentry** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Sentry** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 Sentry ***
## 一、前置说明 Sentry 提供了两类告警机制：Issue Alerts 和 Metric Alerts。Issue Alerts 支持通过 Integrations 中的 WebHooks 实现通知功能，而 Metric Alerts 则限定于使用 Internal Integration 进行告警通知。值得注意的是 Internal Integration 不仅适用于 Metric Alerts，也兼容 Issue Alerts。鉴于 Internal Integration 的广泛适用性，我们决定统一采用这一方式，不再单独依赖 WebHooks，以此来简化告警通知的配置。 ## 二、Sentry 告警推送配置 ### 步骤1：添加 Flashduty Custom Integrations 1. 登录 Sentry 管理控制台。 2. 在左侧导航栏，找到 **Settings => Custom Integrations**。 3. 点击 Create New Integration 并选择 **Internal Integration**。 4. 在编辑页面。**Name 处填写 Flashduty，WebhookURL 处复制写入集成的推送地址**。 5. 开启 **Alert Rule Action**，参考如下图配置： drawing 5. 在 PERMISSIONS 配置中为 **Issue & Event 配置 Read 权限** 。 6. 在 WEBHOOKS 配置中，勾选 **issue** ，**请不要勾选 error 和 comment**。 7. 配置完成后，点击 Save Changes 完成创建。 drawing **关于 WEBHOOKS 配置的特殊说明：** 1. 勾选 **issue** 后 Flashduty On-call 可以接收 issue 的 resolved 事件，即在 issue 列表中对某个问题进行手动触发 resolved 时，我们会自动恢复 Flashduty On-call 中关联的故障。 2. 不支持 issue 的其他事件，如 create、assigned、archived 和 unresolved。 3. 如果同时勾选了 error 和 comment ，Flashduty 并不会接收和处理这类事件。 ### 步骤2：在 Alerts 中使用 Flashduty Integration 1. 在左侧导航栏，找到 **Alerts => Create Alert**。 2. 选择要创建的 Alert 类型，如 Issue 。 drawing 3. 触发条件请按需配置。 4. 在 **THEN perform these actions 处 Add action** 并选择 **Send a notification via**。 drawing 5. 通知渠道选择上面添加的 **Flashduty**。 drawing 6. 配置好其他选项后，点击 **Save Rule** 保存即可。
## 三、状态对照
| Sentry | Flashduty | 状态 | | --------- | --------- | -- | | critical | Critical | 严重 | | warning | Warning | 警告 | | triggered | Warning | 警告 | | resolved | Ok | 恢复 |
# SolarWinds 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/solarwinds 通过 webhook 的方式同步 SolarWinds 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **SolarWinds** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **SolarWinds** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 SolarWinds ***
## 一、SolarWinds 告警推送配置 ### 步骤1：配置 FlashDudy 告警通道 **前提说明** 1. SolarWinds 的告警类型有五种（Anomaly、Entity、Event、Log、Metric Group），每种类型对应不同的告警通道，所以需要创建五个告警通道，以便在不同告警类型中使用。 2. 在创建 Webhook 通道过程中，其中 Name 字段建议使用： 类型\_Flashduty 组合的形式，例如：Anomaly\_Flashduty。 3. 在选择 **Select Custom Body Template Based On The Alert Types** 时，系统会默认生成相应的 **HTTP POST Body**， **生成的模版内容请不要修改**。 **开始创建** 1. 登录您的 SolarWinds 控制台。 2. 在左侧导航栏找到 `Settings` ，选择 `Notification Services` 并点击 `Webhook` 进入到新建告警通道页面。 drawing 3. 点击 `CREATE CONFIGURATION` 进行创建相应的告警通道。 4. 在 `Method` 处选择 **POST** ，`Name` 处可以根据前提说明中的建议进行命名，例如：Anomaly\_Flashduty。 5. `Destination URL` 填写集成的推送地址（当前页面填写集成名称，保存后即可生成地址）。 6. `Content Type` 选择 **application/json**。 7. `Select Custom Body Template Based On The Alert Types` 选择需要创建的类型，例如：Anomaly Based Alert。 8. `HTTP POST Body` 不需要修改，使用系统默认生成的即可。 9. 配置完成后，点击 `CREATE` 保存即可。 drawing 10. 如需创建其他类型的 Webhook 通道，重复以上步骤即可。 ### 步骤2：在告警策略中使用步骤1创建的告警通道 1. 在左侧导航栏找到 `Alerts`，选择 `Alert Settings`。 2. 创建或编辑已有的策略（告警规则按需配置即可，此处省略告警规则的配置）。 3. 在配置策略页面的 `Actions` 部分中，`Services` 选择 **Webhook** 。 4. `Configuration` 选择步骤1创建的 Anomaly\_Flashduty 通道。 5. `Send an additional notification when the Alert is cleared` 保持开启状态。 drawing 6. 其他配置完成后，点击 `Save` 保存即可。
## 二、状态对照
| SolarWinds | Flashduty | 状态 | | ---------- | --------- | -- | | Critical | Critical | 严重 | | Warning | Warning | 警告 | | Info | Info | 提醒 |
# Splunk 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/splunk 通过 webhook 的方式同步 Splunk 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Splunk** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Splunk** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 Splunk ***
## 一、Splunk 告警推送配置 1. 登录您的 Splunk 控制台。 2. 在 `Search adn Report` 应用中，搜索想要监控的关键字，比如 error 关键字。 3. 在右上角的另存为处，选择 `Alerts`，将搜索的关键字配置为监控项。 drawing 4. 在弹出的配置框中输入相关信息，`set up` 和 `Triggering conditions` 部分，按实际情况配置。 5. 在 `Trigger Action` 部分，点击 `Add Action` 并选择 `Webhook`。 drawing 6. 在 `Webhook` 中的 `URL` 处填写集成的推送地址（当前页面填写集成名称，保存后即可生成地址）并保存，即可完成告警配置。 drawing
## 二、状态对照
由于 Splunk 的告警事件没有区分严重程度，所以 Splunk 推送到 Flashduty的所有告警事件状态都为 Warning 且没有恢复事件。
# UCloud CloudWatch 告警集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/ucloud-cloudwatch 通过 webhook 的方式同步 UCloud CloudWatch 的告警事件到 Flashduty，实现告警事件自动化降噪处理 通过 webhook 的方式同步 Ucloud CloudWatch 的告警事件到 Flashduty，实现告警事件自动化降噪处理。
## 在 Flashduty *** ### 创建 Ucloud CloudWatch 告警集成 您可通过以下2种方式，获取一个企微机器人告警集成地址，任选其一即可。 #### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。
展开 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **Ucloud CloudWatch** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **火山引擎 RTC 告警集成地址**，复制备用，完成。
#### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。
展开 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **Ucloud CloudWatch** 集成： * **集成名称**：为当前集成定义一个名称。 * **推送模式**：选择企微告警在何种情况下触发或恢复告警。 3. 复制当前页面的 **Ucloud CloudWatch 告警集成地址** 备用。 4. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 5. 完成。
## 在 Ucloud ***
### 步骤1：配置通知模版 1. 登录您的 Ucloud 控制台，检索 `CloudWatch` 产品，并进入对应产品控制台。 2. 在菜单中选择 `通知管理`，并转到 `通知模版` 页面。 3. 创建或编辑通知模版，在模版页面中勾选 `接口回调`。 4. **回调语言**选择 `英文`，输入框中输入告警集成的推送地址。 5. 模版名称输入 `Flashduty` 或其他。 6. 其他选项按需配置。 7. 点击 `提交` 完成配置。 ![2026-02-05-17-31-12](https://docs-cdn.flashcat.cloud/images/png/7243d6686265fd95da85f88efc1feab5.png) ### 步骤2：配置告警策略 1. 登录您的 Ucloud 控制台，检索 `CloudWatch` 产品，并进入对应产品控制台。 2. 在菜单中选择 `告警管理`，并转到 `告警策略` 页面。 3. 新建或编辑告警策略，找到策略配置页面的**通知设置**，选择**步骤1** 创建的通知模版。 4. 其他选项按需配置。 5. 点击 `提交` 完成配置。 ## 严重程度映射关系 *** 当前 Ucloud CloudWatch 告警集成推送到 Flashduty 的严重程度均为 Warning，但您可以通过[告警处理 Pipeline](https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-pipelines) 来自定义严重程度。 # 火山引擎 RTC 告警集成 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/volcengine-rtc 通过 webhook 的方式同步火山引擎 RTC 的告警事件到 Flashduty，实现告警事件自动化降噪处理 通过 webhook 的方式同步火山引擎 RTC 的告警事件到 Flashduty，实现告警事件自动化降噪处理。
## 在 Flashduty *** ### 创建火山引擎 RTC 告警集成 您可通过以下2种方式，获取一个企微机器人告警集成地址，任选其一即可。 #### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。
展开 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **火山引擎 RTC** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **火山引擎 RTC 告警集成地址**，复制备用，完成。
#### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。
展开 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **火山引擎 RTC** 集成： * **集成名称**：为当前集成定义一个名称。 * **推送模式**：选择企微告警在何种情况下触发或恢复告警。 3. 复制当前页面的 **火山引擎 RTC 告警集成地址** 备用。 4. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 5. 完成。
## 在火山引擎 ***
### 配置告警规则 1. 登录您的火山引擎控制台，检索 `实时音视频` 产品，并进入对应产品控制台。 2. 在左侧菜单中选择 `监控台->告警通知`，并转到 `告警规则` 页面。 3. 创建或编辑告警规则，在规则页面中勾选 `告警回调` 并输入告警集成的推送地址。 4. 其他选项按需配置。 5. 点击 `确定` 完成配置。 ![2026-02-05-17-32-39](https://docs-cdn.flashcat.cloud/images/png/21908f6a040f61ad2e8091226874fe97.png) ## 严重程度映射关系 *** | 火山引擎RTC | Flashduty | 状态 | | ------- | --------- | -- | | 严重 | Critical | 严重 | | 警告 | Warning | 警告 | | 通知 | Info | 提醒 | 您可以通过[告警处理 Pipeline](/zh/on-call/integration/alert-integration/alert-pipelines) 来自定义严重程度。 # 火山引擎日志服务 TLS 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/volcengine-tls 通过 webhook 的方式同步火山引擎日志服务 TLS 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **火山引擎 TLS** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **火山引擎 TLS** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在火山引擎 ***
## 一、火山引擎日志服务 TLS 告警推送配置 ### 步骤1：创建 Flashduty 告警通道 1. 登录您的火山引擎控制台，检索 `TLS`日志服务产品，并进入对应产品控制台。 2. 在左侧导航栏选择 `日志告警=>通知管理`。 3. 选择 `webhook 告警集成`，并点击 `创建 webhook 告警集成`。 drawing 4. 在弹出的编辑框中填写相应的信息，名称填写 `Flashduty`。 5. 类型选择 `自定义 Webhook`，请求方法选择 `POST`。 6. 请求地址填写**集成的推送地址**（当前页面填写集成名称，保存后即可生成地址）。 7. 请求头保持默认的即可，配置完成点击 `创建`。 drawing ### 步骤2：创建内容模版 1. 回到 `通知管理` 页面。 2. 选择 `内容模版`，并点击 `创建内容模版`。 3. 在创建模版页面中填写相关信息，模版名称填写 `Flashduty`。 4. 其他类型的通道内容可为空，在 `自定义Webhook` 的通知内容处，填写以下模版内容。 ``` { "AccountID":"{{AccountID}}", "ProjectName":"{{ProjectName}}", "AlarmTopicName":"{{AlarmTopicName}}", "Region":"{{Region}}", "Alarm":"{{Alarm}}", "AlarmID":"{{AlarmID}}", "Duration":"{{Duration}}", "Condition":"{{Condition}}", "HappenThreshold":"{{HappenThreshold}}", "Topics":"{{Topics|join:','}}", "NotifyTimeUnix":"{{NotifyTimeUnix}}", "NotifyType":"{{NotifyType}}", "Severity":"{{Severity}}", "ConsecutiveAlertNums":"{{ConsecutiveAlertNums}}", "TriggerParams":{{toJson(TriggerParams)|safe}}, "ExecuteQuery":{{toJson(ExecuteQuery)|safe}}, "DetailUrl":"{{DetailUrl}}", "FireResultsCount":"{{FireResultsCount}}" } ``` 5. 点击 `确认` 即可完成内容模版的创建。 drawing ### 步骤3：创建通知组 1. 回到 `通知管理` 页面。 2. 选择 `通知组`，并点击 `创建通知组`。 3. 在编辑通知组页面中填写相关信息，通知组名称填写 `Flashduty`。 4. 通知规则和其他配置可按需配置（此处略过）。 5. 在通知渠道配置中，接收渠道的 `自定义webhook` 保持勾选状态。 6. `Webhook` 选择**步骤1**创建的 **FlahDuty** 通道。 7. `内容模版` 选择**步骤2**创建的 **FlahDuty** 模版。 8. 其他配置完成后点击 `保存` 即可。 drawing ### 步骤4：配置告警策略 1. 在左侧导航栏选择 `日志告警=>告警策略`。 2. 创建或编辑已有的告警策略。 3. 告警规则可按需配置（此处略过）。 4. 在 `通知组` 处，点击 `关联通知组`。 5. 在弹出的选择框中，选择**步骤3**创建的 **Flashduty** 通知组，选择好后，点击 `关联`。 6. 配置好其他内容后，点击 `创建/保存` 即可完成。 drawing
## 二、状态对照
| TLS | Flashduty | 状态 | | --- | --------- | -- | | 严重 | Critical | 严重 | | 警告 | Warning | 警告 | | 通知 | Info | 提醒 |
# zilliz 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/zilliz 通过 webhook 的方式同步 zilliz 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **zilliz** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **zilliz** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 zilliz ***
## 一、告警推送配置 1. 登录您的 `zilliz` 控制台，在 `Project Alerts` 中，创建或修改 `Alert`。 2. 在 `Alert` 编辑页面中的 `Send to` 部分，选择 `Webhook`，Webhook URL 填写告警集成的推送地址。 3. 选中 `Alert Resolution Notification`，其他按需选择。 4. 点击 `Save` 或 `Create` 完成配置。 drawing
## 二、状态对照
| zilliz | Flashduty | 状态 | | -------- | --------- | -- | | CRITICAL | Critical | 严重 | | WARNING | Warning | 警告 |
# zstack 告警事件 Source: https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-sources/zstack 通过 webhook 的方式同步 zstack 告警事件到 Flashduty On-call，实现告警事件自动化降噪处理
## 在 Flashduty On-call *** 您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 ### 使用专属集成 当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 3. 选择 **ZStack** 集成，点击 **保存**，生成卡片。 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 ### 使用共享集成 当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 2. 选择 **ZStack** 集成： * **集成名称**：为当前集成定义一个名称。 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 5. 完成。
## 在 ZStack ***
## 一、告警推送配置 ### 步骤1：创建通知对象 1. 登录您的 `ZStack` 控制台，在 `平台运维` 菜单中，找到 `云平台监控`。 2. 点击左侧的 `通知对象`，点击`创建通知对象`或编辑已有的通知对象。 3. 在编辑页面中，名称填写 `Flashduty` ，类型选择 `Webhook`，`地址` 处填写告警集成的推送地址。 4. 点击 `发送测试消息`，如果消息发送成功，则说明配置成功。 5. 点击 `确定` 完成配置。 drawing ### 步骤2：在告警策略中使用通知对象 1. 登录您的 `ZStack` 控制台，在 `平台运维` 菜单中，找到 `云平台监控`。 2. 点击左侧的 `报警器`，点击`创建资源报警器` 或 `创建事件报警器`，或编辑已有的报警器。 3. 在编辑页面中，`通知对象` 处选择创建的 `Flashduty` 通知对象（资源报警器建议打开恢复通知）。 4. 其他按需配置即可，点击 `确定` 完成配置。 drawing
## 二、状态对照
| ZStack | Flashduty | 状态 | | ------ | --------- | -- | | 紧急 | Critical | 严重 | | 严重 | Warning | 警告 | | 提示 | Info | 信息 |
# 自定义变更事件 Source: https://docs.flashduty.com/zh/on-call/integration/change-integration/custom-event 通过标准协议推送自有系统变更事件到 Flashduty On-call，大部分故障由变更导致，变更和告警事件联动有助于快速定位故障原因 **版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) Flashduty On-call 已适配部分常用工单、部署系统的 webhook 协议，对于这些系统您应该首先使用对应的集成。本集成提供了一个标准的 HTTP 接口，需要您开发适配，好处是可以与任何部署系统集成。 ## 操作步骤 进入 Flashduty 控制台，选择 **集成中心 => 变更事件**，进入集成选择页面。 选择 **自定义事件** 集成，为当前集成定义一个名称。 点击 **保存** 后，复制当前页面新生成的 **推送地址** 备用。 ## 实现协议 ### 请求描述 请求方式： ```http theme={null} POST, Content-Type: application/json ``` 请求地址为集成详情页展示的 **推送地址**，格式如下： ```text theme={null} {api_host}/event/push/change/standard?integration_key={integration_key} ``` ### 请求参数 #### Headers | 字段 | 必含 | 类型 | 说明 | | :----------- | :-: | :----- | :---------------------- | | Content-Type | 是 | string | 固定值：`application/json`。 | #### Query Strings | 字段 | 必含 | 类型 | 说明 | | :--------------- | :-: | :----- | :-------------------------- | | integration\_key | 是 | string | 集成秘钥，用于访问控制。创建集成后可在推送地址中获取。 | #### Payload | 字段 | 必含 | 类型 | 说明 | | :------------- | :-: | :------ | :------------------------------------------------------------------------------------------ | | title | 是 | string | 变更标题，例如发布单标题、工单标题或部署任务名称。 | | change\_key | 是 | string | 变更标识。相同 `change_key` 会被识别为同一个变更，后续事件会更新该变更的状态、标签和链接。 | | change\_status | 是 | string | 变更状态。枚举值（首字母大写）：`Planned` 计划中、`Ready` 待执行、`Processing` 执行中、`Canceled` 已取消、`Done` 已完成。 | | event\_time | 否 | integer | 事件发生时间，Unix 时间戳。支持秒级或毫秒级时间戳；未传时使用 Flashduty 接收事件的时间。 | | description | 否 | string | 变更描述，例如变更内容、影响范围、执行步骤或回滚方案。 | | link | 否 | string | 变更详情链接，例如发布单、工单或 CI/CD 任务地址。 | | labels | 否 | map | 变更标签集合，key 和 value 均为 string 类型。建议 key 遵循 Prometheus 标签命名规范；系统会将 key 中的空格、点号、斜杠等特殊字符替换为下划线。 | 当 `change_status` 为 `Done` 或 `Canceled` 时，Flashduty 会将该事件时间记录为变更结束时间；再次上报非结束状态时，结束时间会被清空。 ### 请求响应 | 字段 | 必含 | 类型 | 说明 | | :---------- | :-: | :-------------- | :-------------- | | request\_id | 是 | string | 请求 ID，用于链路追踪。 | | error | 否 | [Error](#error) | 错误描述，仅当出现错误时返回。 | | data | 否 | object | 上报成功时返回空对象。 | #### Error | 字段 | 必含 | 类型 | 说明 | | :------ | :-: | :----- | :----------------------- | | code | 是 | string | 错误码，枚举值参考 [Code](#code)。 | | message | 否 | string | 错误描述。 | #### Code | 错误码 | HTTP Status | 说明 | | :------------------- | :---------: | :----------------------------- | | InvalidParameter | 400 | 参数错误，例如缺少必填字段、状态枚举值不合法或集成秘钥无效。 | | InvalidContentType | 400 | `Content-Type` 不支持。 | | MethodNotAllowed | 405 | HTTP Method 不支持。 | | Unauthorized | 401 | 登录认证未通过。 | | AccessDenied | 403 | 权限认证未通过。 | | RequestTooFrequently | 429 | 请求过于频繁。 | | RouteNotFound | 404 | 请求 Method 和 Path 未匹配。 | | ResourceNotFound | 400 | 账户未购买资源，请先前往费用中心下单。 | | NoLicense | 400 | 账户无充足订阅 License，请先升级或购买订阅。 | | InternalError | 500 | 内部或未知错误。 | ### 请求示例 请求： ```bash theme={null} curl -X POST '{api_host}/event/push/change/standard?integration_key={integration_key}' \ -H 'Content-Type: application/json' \ -d '{ "title": "order-service v1.12.0 production release", "change_key": "deploy-order-service-202607231030", "change_status": "Processing", "event_time": 1784773800, "description": "Deploy order-service v1.12.0 to production cluster cn-shanghai-prod.", "link": "https://deploy.example.com/releases/deploy-order-service-202607231030", "labels": { "service": "order-service", "env": "prod", "cluster": "cn-shanghai-prod", "owner": "sre" } }' -v ``` 成功响应： ```json theme={null} { "request_id": "0ace00116215ab4ca0ec5244b8fc54b0", "data": {} } ``` 失败响应： ```json theme={null} { "request_id": "0ace00116215abc0ba4e52449bd305b0", "error": { "code": "InvalidParameter", "message": "Key: 'ChangeEvent.ChangeStatus' Error:Field validation for 'ChangeStatus' failed on the 'oneof' tag" } } ``` ## 最佳实践 标签是事件的描述，应尽量丰富标签内容： * **变更的应用范围**：如 host、cluster 等 * **变更的归属信息**：如 team、owner 等 * **变更的生命周期**：同一个变更在计划、执行、完成或取消时，使用相同 `change_key` 持续上报不同 `change_status`，便于在故障时间线上还原变更过程 ## 常见问题 **在 Flashduty On-call 排查** 查看集成是否展示了 **最新事件时间**？如果没有，代表 Flashduty 没有收到推送，请优先排查您的系统。 **在您的系统排查** 1. 确认您请求的地址与集成详情中的地址完全一致 2. 确认您的服务可以访问外网 `api.flashcat.cloud` 域名。如果不可以，您需要为 server 开通外网，或单独针对 Flashduty On-call 的域名开通外网访问 3. 打印 Flashduty 服务的响应结果，查看是否有明确信息 如果以上步骤执行后仍未找到问题根因，请 **携带请求响应中的 request\_id** 联系我们。 # 钉钉 Source: https://docs.flashduty.com/zh/on-call/integration/instant-messaging/dingtalk 通过集成钉钉自建应用，实现在钉钉端内接收和响应告警的能力 **版本要求**：IM 集成需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 本文档以钉钉开放平台新版为例。 ## AISRE 所需权限 以下为钉钉 IM 集成在开启 AISRE（包含基础通知、作战室、AI SRE 对话和 AI 生成复盘）时需要授予的完整权限清单。进入钉钉开放平台 **权限管理** 页面时，请逐项申请以下官方权限名称。 | 官方权限名称 | 用途 | | :--------------------------- | :------------------------------------------------- | | `qyapi_chat_manage` | 获取群聊信息，用于普通通知、酷应用和机器人消息投递 | | `qyapi_robot_sendmsg` | 发送机器人消息，用于基础通知、会话机器人回复、普通版互动卡片、作战室消息，以及下载机器人接收到的文件 | | `qyapi_chat_read` | 读取群聊信息，用于作战室群状态确认和群成员处理 | | `qyapi_chat_base_read` | 读取群聊基础信息，用于作战室群查询 | | `qyapi_get_member_by_mobile` | 根据手机号获取钉钉用户 ID，用于一键关联用户和邀请成员进入作战室 | | `Card.Instance.Write` | 创建并投放 AI SRE 流式卡片；仅在启用钉钉 AI 流式卡片模板时需要 | | `Card.Streaming.Write` | 更新 AI SRE 流式卡片内容；仅在启用钉钉 AI 流式卡片模板时需要 | 如果未配置钉钉 AI 流式卡片模板，AI SRE 会降级使用普通版互动卡片或会话机器人消息回复，此时仍需要保留 `qyapi_robot_sendmsg`。 ## 一、创建钉钉应用与添加钉钉集成 ### 1. 创建自建应用 访问 [钉钉开发者后台](https://open-dev.dingtalk.com/fe/app) → 应用开发 → **企业内部开发**，创建应用。 详见钉钉开发文档 [创建企业内部应用-H5 微应用](https://open.dingtalk.com/document/orgapp/microapplication-creation-and-release-process#title-ovn-666-1ty)。 ![2025-09-18-15-02-55](https://docs-cdn.flashcat.cloud/images/png/3a66cc08c2a9ecb5669c985e05deb129.png) 应用图标可使用 [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png)。 ### 2. 复制企业 `CorpId` 点击页面右上角企业头像，在下拉菜单中复制 `CorpId`。 ![2025-09-18-15-03-12](https://docs-cdn.flashcat.cloud/images/png/3abe7ce647a78264290a8d311b62a842.png) 回到 Flashduty On-call 集成配置页面，在表单中填入对应的 `CorpId`。 ### 3. 复制应用凭证信息 进入创建的应用详情界面，通过左侧菜单栏前往 应用能力 → **凭证与基础信息** 页面，复制 `AgentId`、`Client ID` 和 `Client Secret`。 ![2025-09-18-15-04-39](https://docs-cdn.flashcat.cloud/images/png/075fc5989770ef3e76aa39320fe55bdf.png) 回到 Flashduty On-call 集成配置页面，在表单中填入对应的 `AgentId`、 `Client ID` 和 `Client Secret`。 ### 4. 复制事件订阅信息 前往 开发配置 → **事件与回调** 页面。设置推送方式为 `HTTP推送`，然后点击按钮生成 `加密 aes_key` 和 `签名 Token`，并复制保存。 ![2025-09-18-15-05-10](https://docs-cdn.flashcat.cloud/images/png/0369b205a2fcf0f798267a4573e54996.png) 回到 Flashduty On-call 集成配置页面，在表单中填入对应的 `加密 aes_key` 和 `签名 Token`，点击 **保存** 按钮。 ### 5. 配置事件订阅 进入 开发配置 → **事件订阅** 页面。 根据 Flashduty 集成详情中的 `事件订阅请求地址`，配置 **事件订阅请求网址**。配置完成后 **保存**。 ![2025-09-18-15-05-34](https://docs-cdn.flashcat.cloud/images/png/4f2f07c6bfd852b5c47ce2ae63559212.png) 在 **保存** 按钮下方，选中 `群会话更换群名称`、`群内安装酷应用` 和 `群内卸载酷应用` 三种群会话事件，配置完成后点击 **保存**。 ![2025-09-18-15-08-07](https://docs-cdn.flashcat.cloud/images/png/e4fadf912cdad71dbfcc8c3d678f3277.png) ### 6. 添加应用能力 创建酷应用。进入 开发配置 → 添加应用能力 → 酷应用 → **酷应用列表** 页面，点击 **创建酷应用** 按钮，选择 **扩展到群会话**。 进入 **编辑酷应用** 页面，完成以下步骤： 1. 填写基本信息。图标可使用 [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png)。 ![2025-09-18-15-11-03](https://docs-cdn.flashcat.cloud/images/png/d5191000378f4df25bb96bc1f19b0db2.png) 2. 配置功能设计。在左侧选中 **群快捷入口** 和 **消息卡片**。群快捷入口图标可使用 [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png)，桌面和移动端访问地址请复制集成详情里的 **酷应用网页地址**。 ![2025-09-18-15-13-08](https://docs-cdn.flashcat.cloud/images/png/88385f8c5aa382d13bc9f5c0d0b8b18f.png) 3. 跳过第三步功能开发，进入第四步 **预览发布**，点击 **发布** 按钮并确认。 ### 7. 配置机器人与消息推送 进入 应用能力 → **机器人** 页面，打开机器人配置，填写名称并上传图标，然后点击 **保存**。图标可使用 [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png)。 ![2025-09-18-15-17-17](https://docs-cdn.flashcat.cloud/images/png/62f4d4582baa0b446876e41e1a9d8eca.png) ### 8. 配置应用地址 进入 应用能力 → **网页应用** 页面。 根据 Flashduty 集成详情中的 `应用首页地址` 和 `PC 端首页地址`，配置 **应用首页地址** 和 **PC 端首页地址**。完成后点击 **保存**。 ![2025-09-18-15-20-13](https://docs-cdn.flashcat.cloud/images/png/9c430307d54f27eaedb009235540f6c5.png) ### 9. 申请应用权限 进入 开发配置 → **权限管理** 页面，为先前步骤创建的群应用申请以下权限： * `qyapi_chat_manage`：获取群聊信息 * `qyapi_robot_sendmsg`：向群聊或个人发送消息 如果需要开启 AISRE，请同时确认页面开头的 [AISRE 所需权限](#aisre-permissions) 已全部申请。 ![2025-09-18-15-20-36](https://docs-cdn.flashcat.cloud/images/png/4417440194002a011e2feca5fa5c9469.png) 如果需要继续配置作战室，请先发布一次自建应用。应用发布后，才能在场景群的 **可选应用** 列表中选择该应用。发布路径请参考 [应用发布与使用](#publish)。 ## 二、配置作战室 若您无需配置作战室功能，可跳过本步骤，直接进入 [**应用发布与使用**](#publish)。 > 配置作战室前，请确认应用已获得页面开头列出的 [AISRE 所需权限](#aisre-permissions)。 ### 1. 申请应用权限 进入 开发配置 → **权限管理** 页面，为先前步骤创建的群应用申请以下权限： * `qyapi_chat_read`：获取群聊信息 * `qyapi_chat_base_read`：获取群聊信息 * `qyapi_get_member_by_mobile`：允许当前应用根据手机号获取钉钉用户以便邀请用户加入群聊 ![2025-09-18-15-21-28](https://docs-cdn.flashcat.cloud/images/png/39142395390ce09726e3a95991549116.png) ### 2. 配置群模板 通过钉钉开放平台顶部菜单栏，前往 开放能力 → **场景群**。 1. 配置 **群机器人**。在左侧菜单栏中选择 **机器人**，然后点击 **创建群机器人**。 本步骤中配置的 **群机器人** 和 **应用机器人** 是两个不同的概念。群机器人被用于在生成群聊时自动创建群机器人。群机器人和应用机器人拥有不同的 **机器人 ID**。若要为钉钉开启作战室功能，必须额外配置 **群机器人**。 填写群机器人配置。若需要使用 AISRE，请按下表配置 **消息回调地址**、**消息回调 token** 和 **信息来源网站**。这三项用于 AISRE 的钉钉消息回调。 钉钉当前对消息回调地址的证书校验不兼容 `api.flashcat.cloud` 使用的 ACME 自动签发证书。为保证钉钉能够正常校验并回调消息，请将 Flashduty 集成配置页提供的消息地址中的域名替换为 `dingtalk-message.flashcat.cloud`。 **示例配置**： | **配置项** | **值** | | ---------- | ------------------------------------------------------------------------------------------------------ | | 机器人名称 | Flashduty | | 机器人头像 | [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png) | | 简介 | Flashduty | | 消息预览图 | [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png) | | 详细描述 | Flashduty 消息推送机器人。 | | 消息回调地址 | Flashduty 集成配置页提供的消息地址，并将域名 `api.flashcat.cloud` 替换为 `dingtalk-message.flashcat.cloud` | | 消息回调 token | 步骤 4 在 开发配置 → **事件与回调** 中生成的 `签名 Token` | | 信息来源网站 | `https://www.flashduty.com` | 完成配置后，点击 **创建**，然后点击 **审批**。右上角弹出 “提交成功” 后，钉钉已自动完成群机器人的审批。 ![2025-09-18-15-22-05](https://docs-cdn.flashcat.cloud/images/png/75e853ae6c420d69916e17f5d8922945.png) 2. 配置 **群模板**。在左侧菜单栏中选择 **群模板**，点击 **创建群模板**。 将 **企业类型** 设置为 `企业内部`，将 **可选应用** 设置为先前步骤中已发布的自建应用。然后，在下一步骤中填写模板信息。 **模板名称**、**图标**、**描述**、**文案介绍**、**模板描述**、**图片介绍** 等介绍性信息不会影响群模板功能的使用，您可选择任意满足要求的值进行配置。 **示例配置**： | **配置项** | **值** | | ------- | ------------------------------------------------------------------------------------------------------ | | 模板名称 | Flashduty 作战室 | | 图标 | [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png) | | 描述 | 为活跃故障一键创建作战室。 | | 文案介绍 | 为活跃故障一键创建作战室。 | | 模板描述 | 为活跃故障一键创建作战室。 | | 图片介绍 | [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png) | 在 **选择机器人** 配置项中，点击 **选择已创建的机器人**，选择上一步骤中创建的群机器人。其他配置项保持默认。最后点击 **保存编辑**。 ![2025-09-18-15-22-35](https://docs-cdn.flashcat.cloud/images/png/9292a8418a96fcb3fee1d424a41d33a2.png) ![2025-09-18-15-23-06](https://docs-cdn.flashcat.cloud/images/png/c76433b0962fb0f0531b4f56b60ce903.png) 在 **填写灰度群** 步骤中，点击 **创建灰度群**，然后点击 **发布灰度**。 最后，再次点击左侧菜单栏的 **群模板**，然后点击进入刚才创建的群模板。点击 **提交审核**，待钉钉自动通过审核后，最后点击 **发布**。 3. 在已经发布的群模板详细信息页，复制 **模板 ID** 和 **机器人 ID**。 ![2025-09-18-15-23-46](https://docs-cdn.flashcat.cloud/images/png/315acf0b5951100781f96cd4d854d0c6.png) 回到 Flashduty On-call 集成配置页面，在表单中填入对应的 `模版 ID` 和 `机器人 ID`，点击 **保存** 按钮。 同一时间仅支持在一个 IM 集成中开启作战室功能。如果你已在其他 IM 集成（如飞书、Slack、企业微信）中启用了作战室，需要先在该集成中关闭后，才能在当前钉钉集成中开启。 ### AI SRE 控制项 开启 **作战室** 后，配置页会显示以下 AI SRE 控制项，默认均为开启： * **自动发起 AI 故障分析**：作战室创建成功后，自动发起一次 AI 故障分析。 * **允许群聊 @ AI SRE**：允许在此集成已接入的群聊中 @ AI SRE 发起对话；关闭后不会响应该入口。 如果账户尚未启用 AI SRE，以上配置暂不生效。 ## 三、应用发布与使用 完成上述步骤后，请确认自建应用已发布最新版本。若尚未发布，或发布后又调整了应用配置，请前往 应用发布 → **版本管理与发布**，创建新版本并发布。 为了确保所有人可以使用应用，需将应用 **可见范围** 调整为全部员工，再进行应用发布。 ![2025-09-18-16-08-17](https://docs-cdn.flashcat.cloud/images/png/86df5b6148cf1264745d957bd2d43fcf.png) 应用发布后，即可通过 **手机端** 或 **PC 端** 访问应用。首次访问需要登录并关联钉钉与 Flashduty 账号，后续可以免登录使用。 钉钉 → 工作台 → 搜索应用名称 → **打开应用** 钉钉 → 工作台 → 搜索应用名称 → **打开应用** ## 四、关联用户 在集成详情页的 **关联用户** 页签中，你可以查看团队成员与钉钉账号的关联状态，并快速完成批量关联。 ### 查看关联状态 关联用户列表展示所有团队成员及其关联状态。你可以通过以下方式筛选： | 筛选项 | 说明 | | :------ | :-------------- | | **全部** | 查看所有团队成员 | | **已关联** | 仅查看已完成钉钉账号关联的成员 | | **未关联** | 仅查看尚未关联钉钉账号的成员 | 支持通过名称或邮箱搜索成员。 ### 一键关联 当存在未关联的成员时，可以点击 **一键关联** 按钮。系统将尝试通过手机号换取钉钉开放平台的账号 ID 并自动关联，效果等同于成员使用相同手机号在钉钉平台登录 Flashduty。 成员完成关联后，系统才能向其推送钉钉消息通知。如果关联失败，请确认成员的手机号是否与钉钉账号一致。 ## 五、常见问题 前往 钉钉 → 工作台 → 搜索应用名称 → **打开应用**，完成一次登录以关联钉钉与 Flashduty 账号，系统才能获取用户身份并推送消息。 * 前往 钉钉 → 工作台 → 搜索应用名称 → **打开应用**，完成一次登录以关联钉钉与 Flashduty 账号。如果已经登录过，尝试点击右上角菜单，切换账户，重新登录来绑定账号 * 确保您已购买足够的 License。已使用 License 情况，可以在 控制台 → [**费用中心**](https://console.flashcat.cloud/wallet) 查看 1. 前往钉钉，选择群聊会话安装酷应用，否则无法获取群聊列表 ![2025-09-18-15-34-37](https://docs-cdn.flashcat.cloud/images/png/7f1e931df0ae740a37ce6615ac3b18ba.png) ![2025-09-18-15-35-44](https://docs-cdn.flashcat.cloud/images/png/367dfd391bf4d57c22088d20a4844e33.png) 2. 回到分派策略配置页面，刷新后重新选择群聊列表 3. 如果仍然无法获取群聊列表，请尝试在群内卸载酷应用后，重试以上步骤。如果问题依旧，请联系客户或专属技术支持 * 请再次检查是否为应用配置了作战室功能[所需权限](#war-room-scope) * 请参考 [作战室介绍文档](/zh/on-call/advanced/war-room) 的 **常见问题** 部分 | **钉钉版本** | **调用总量/月** | **QPS** | **刷新时间** | | :------: | :--------: | :-----: | :------: | | 标准版 | 10,000 次 | 20 | 每月 1 日 | | 专业版 | 50 万次 | 40 | 每月 1 日 | | 专属版 | 550 万次 | 60 | 每月 1 日 | 超出 API 调用量限制后，钉钉应用将无法正常推送消息。建议合理使用通知渠道。详见 [钉钉官方文档](https://open.dingtalk.com/document/orgapp/descriptions-about-adjusting-limit-and-frequency-of-api-calls?spm=ding_open_doc.document.0.0.6f6b21d9WtkxJI)。 # 飞书/Lark Source: https://docs.flashduty.com/zh/on-call/integration/instant-messaging/lark 通过集成飞书自建应用，您可以在飞书端内接收和响应告警 **版本要求**：IM 集成需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) ## AISRE 所需权限 以下为飞书/Lark IM 集成在开启 AISRE（包含基础通知、作战室、AI SRE 对话和 AI 生成复盘）时需要授予的完整权限清单。进入飞书/Lark 开放平台 **权限管理** 页面时，请逐项申请以下官方权限名称。 | 官方权限名称 | 用途 | | :--------------------------------- | :------------------------------------ | | `im:chat` | 创建和管理作战室群、获取群信息、添加群成员 | | `im:message` | 读取和发送单聊、群组消息 | | `im:message.p2p_msg:readonly` | 接收用户发给机器人的单聊消息；缺少该权限时，AI SRE 无法收到单聊提问 | | `im:message.group_at_msg:readonly` | 接收群聊中 @ 机器人的消息；群聊 AI SRE 对话需要该权限 | | `im:message:send_as_bot` | 以机器人身份发送 AI SRE 回复和作战室消息 | | `im:message:update` | 更新应用已发送的消息，用于 AI SRE 流式回复更新 | | `im:message.group_msg` | 读取群聊历史消息；AI SRE 上下文和 AI 生成复盘报告需要该权限 | | `im:message.reactions:read` | 查询消息表情反应，用于 AI SRE 处理状态确认 | | `im:message.reactions:write_only` | 添加或删除消息表情反应，用于 AI SRE 处理状态确认 | | `im:resource` | 上传和下载消息中的图片、文件等资源 | | `cardkit:card:write` | 创建和更新 CardKit 卡片，用于 AI SRE 流式回复 | | `contact:user.id:readonly` | 通过手机号或邮箱获取用户 ID，用于自动关联和邀请成员 | | `contact:contact.base:readonly` | 获取通讯录基本信息，用于读取用户和部门基础资料 | | `contact:user.base:readonly` | 获取用户基础信息，用于显示发送者名称 |
## 一、创建飞书应用 *** ### 1. 创建自建应用 访问 [飞书开发者后台](https://open.feishu.cn/app)，创建企业内自建应用。应用图标可使用 [Flashduty 官方 icon](https://flashduty-public.oss-cn-beijing.aliyuncs.com/icons/flashduty-20251216.png)。 详见飞书开发文档 [创建企业自建应用](https://open.feishu.cn/document/uYjL24iN/uMTMuMTMuMTM/development-guide/step1#132c1aac)。 ![2025-09-18-10-37-08](https://docs-cdn.flashcat.cloud/images/png/d456a3be638252127dde907617d63fb7.png) ### 2. 复制凭证信息 前往 **凭证与基础信息** 页面，复制 `App ID` 和 `App Secret` 备用。 ![2025-09-18-10-38-52](https://docs-cdn.flashcat.cloud/images/png/69f98fad9e5a076aac5f9b0058ebd8dc.png) ### 3. 复制事件回调的 Token 信息 前往 开发配置 → 事件与回调 → **加密策略** 页面，生成并复制 `Encrypt Key`（推荐启用，更安全）和 `Verification Token` 备用。 ![2025-09-18-10-42-01](https://docs-cdn.flashcat.cloud/images/png/ac558d48464310fe27ef97912b298df1.png) ## 二、添加飞书集成 *** 回到 Flashduty On-call **集成中心** 页面，选择 即时消息 → **飞书**，在表单中填入 `名称` 以及上一步复制的 `App ID`、`App Secret`、`Verification Token` 和 `Encrypt Key` 后，点击 **保存** 完成创建。 创建成功后，您将在列表中看到已添加的飞书集成。点击其名称进入详情页面，即可查看 **网页配置** 地址、**重定向 URL** 和 **消息卡片请求网址**，这些信息将在后续步骤中使用。 ![2025-09-18-10-44-00](https://docs-cdn.flashcat.cloud/images/png/1e8ffb6c39f99ef12bd85ae49992ebad.png) ## 三、配置飞书应用 *** ### 1. 开通并配置应用能力 1. 回到飞书开发者后台，进入刚才创建的飞书应用，进入 添加应用能力 → **按能力添加** 页面，同时开通 **网页应用** 和 **机器人** 能力。 ![2025-09-18-10-45-48](https://docs-cdn.flashcat.cloud/images/png/5ab84aec1593c7118782765676a51c6a.png) 2. 前往 **网页应用** 页面，配置 `桌面端主页` 和 `移动端主页`，内容均为集成详情中的 **网页配置** 地址。详见飞书开发文档 [配置应用主页地址](https://open.feishu.cn/document/uYjL24iN/uMTMuMTMuMTM/development-guide/step1#8366b844)。 ![2025-09-18-10-47-46](https://docs-cdn.flashcat.cloud/images/png/d91efc598bda17e1bfcb367aec47c779.png) 3. 前往 事件回调 → **事件配置** 页面，配置 `订阅方式`（内容为集成详情中的 **消息卡片请求网址**）。然后，添加以下两项事件： * `im.chat.disbanded_v1` * `im.message.receive_v1` ![2025-09-18-11-06-05](https://docs-cdn.flashcat.cloud/images/png/71910d8af8d60b5f30baf009081646df.png) 4. 前往 事件回调 → **回调配置** 页面，配置 `订阅方式`（内容为集成详情中的 **消息卡片请求网址**）。然后，订阅以下两项回调： * `card.action.trigger` * `card.action.trigger_v1` ![2025-09-19-18-43-03](https://docs-cdn.flashcat.cloud/images/png/f58b20e52fc53f428bc493e18f0a567f.png) ### 2. 添加重定向 URL 到飞书应用 进入 **安全设置** 页面，配置 `重定向URL`，内容为集成详情中的 **重定向 URL**。 详见飞书开发文档 [配置重定向 URL](https://open.feishu.cn/document/uYjL24iN/uYjN3QjL2YzN04iN2cDN?lang=zh-CN#c863e533)。 ![2025-09-18-10-53-24](https://docs-cdn.flashcat.cloud/images/png/00a7cdd10c09c90c2d7b2f0a99ee4d8d.png) ### 3. 申请应用权限 进入 **权限管理** 页面，为先前步骤创建的应用申请页面开头 [AISRE 所需权限](#aisre-permissions) 中列出的全部权限。请特别确认已开通 `im:message.p2p_msg:readonly` 和 `im:message.group_at_msg:readonly`，否则飞书不会向 Flashduty 推送单聊消息或群聊 @ 机器人消息。权限或事件配置变更后，需要重新发布应用后才会在线上生效。 ![2025-09-18-10-55-14](https://docs-cdn.flashcat.cloud/images/png/d919be62107f6b9d0c662f440d620e61.png) ## 四、应用发布与使用 完成上述所有配置后，请发布应用。待管理员审核通过后即可使用。详见飞书开发文档 [应用发布与使用](https://open.feishu.cn/document/uYjL24iN/uMTMuMTMuMTM/development-guide/step-4)。 为了确保所有人可以使用应用，需将应用 **可见范围** 调整为全部员工，再进行应用发布。 ![2025-09-18-10-56-20](https://docs-cdn.flashcat.cloud/images/png/6bbc285986808af14c29d0eb633a2bf7.png) 应用发布后，即可通过 **手机端** 或 **PC 端** 访问应用。首次访问需要登录并关联飞书与 Flashduty 账号，后续可以免登录使用。 飞书 → 工作台 → 搜索应用名称 → **打开应用** 飞书 → 工作台 → 搜索应用名称 → **打开应用** ![2025-09-18-10-57-46](https://docs-cdn.flashcat.cloud/images/png/eed8557808874a0c488b958c4049ea72.png) ## 五、配置作战室 > 确保应用已被授权使用页面开头列出的 [AISRE 所需权限](#aisre-permissions)。 完成先前步骤后，在 Flashduty On-call 集成配置页面的 **增强功能** 模块，勾选 **开启作战室** 即可启用该功能，无需额外配置。 同一时间仅支持在一个 IM 集成中开启作战室功能。如果你已在其他 IM 集成（如钉钉、Slack、企业微信）中启用了作战室，需要先在该集成中关闭后，才能在当前飞书集成中开启。 ### AI SRE 控制项 在 **增强功能** 中分别配置以下 AI SRE 控制项，默认均为开启： * **自动发起 AI 故障分析**：开启作战室后可配置；作战室创建成功后，自动发起一次 AI 故障分析。 * **允许群聊 @ AI SRE**：无需开启作战室即可配置，允许在此集成已接入的群聊中 @ AI SRE 发起对话；关闭后不会响应该入口。 * **普通群聊中 AI SRE 使用话题回复**：无需开启作战室即可配置。开启后，普通群聊中的每个话题对应一个独立 Session；作战室仍直接在群内回复。 如果账户尚未启用 AI SRE，以上配置暂不生效。 ## 六、关联用户 在集成详情页的 **关联用户** 页签中，你可以查看团队成员与飞书账号的关联状态，并快速完成批量关联。 ### 查看关联状态 关联用户列表展示所有团队成员及其关联状态。你可以通过以下方式筛选： | 筛选项 | 说明 | | :------ | :-------------- | | **全部** | 查看所有团队成员 | | **已关联** | 仅查看已完成飞书账号关联的成员 | | **未关联** | 仅查看尚未关联飞书账号的成员 | 支持通过名称或邮箱搜索成员。 ### 一键关联 当存在未关联的成员时，可以点击 **一键关联** 按钮。系统将尝试通过手机号或邮箱换取飞书开放平台的账号 ID 并自动关联，效果等同于成员使用相同信息在飞书平台登录 Flashduty。 成员完成关联后，系统才能向其推送飞书消息通知。如果关联失败，请确认成员的手机号或邮箱是否与飞书账号一致。 ## 七、常见问题 前往 飞书 → 工作台 → 搜索应用名称 → **打开应用**，完成一次登录以关联飞书与 Flashduty 账号，系统才能获取用户身份进行消息推送。 * 确保账户已经完成关联。您可以前往 飞书 → 工作台 → 搜索应用名称 → **打开应用**，完成一次登录。如果已经登录过，请尝试点击右上角菜单，切换账户后重新登录以绑定账号 * 确保已购买足够的 License。已使用 License 情况，可以在 控制台 → **费用中心** 查看 * 前往飞书，在指定群聊会话中添加已创建的 Flashduty 机器人 * 回到分派策略配置页面，刷新后重新选择群聊列表 ![2025-09-18-14-24-40](https://docs-cdn.flashcat.cloud/images/png/0e21e9e689855d9a636fb94848f58c13.png) **调用量限制：** | **飞书版本** | **调用总量/月** | **刷新时间** | | :------: | :--------: | :------: | | 基础免费版 | 10,000 次 | 每月 1 日 | | 其他版本 | 不限制 | - | **频控限制：** | **场景** | **限制** | | :------------: | :----------------- | | 所有接口 | 每个应用最高频率 50 次/秒 | | 发消息接口 | 每个应用最高频率 1000 次/分钟 | | 群机器人 Webhook | 最高频率 100 次/分钟 | | 给同一个用户或同一个群发消息 | 最高频率 5 次/秒 | 超出 API 调用量限制后，飞书应用将无法正常推送消息，建议合理使用通知渠道。详见 [飞书官方文档](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/platform-updates-/custom-app-api-call-limit)。 * 请再次检查是否为应用配置了页面开头列出的 [AISRE 所需权限](#aisre-permissions) * 请参考 [作战室介绍文档](/zh/on-call/advanced/war-room) 的 **常见问题** 部分 # Microsoft Teams Source: https://docs.flashduty.com/zh/on-call/integration/instant-messaging/microsoft-teams 通过集成 Microsoft Teams 第三方应用，您可以在 Microsoft Teams 内接收和响应告警 **版本要求**：IM 集成需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 如果您的组织限制第三方应用，请先联系 Microsoft Teams 管理员允许使用 Flashduty。 如需了解 Teams 应用处理 Teams 用户、团队、频道、群聊和故障卡片数据的规则，请参阅《[Flashduty Microsoft Teams 应用隐私政策](/zh/compliance/microsoft-teams-app-privacy-policy)》和《[Flashduty Microsoft Teams 应用使用条款](/zh/compliance/microsoft-teams-app-terms-of-use)》。 ## 一、数据和权限说明 Flashduty Teams 应用只在发送告警通知、完成关联配置和处理故障卡片操作所需的范围内处理 Teams 数据。 | 数据或能力 | 使用场景 | | ---------------------------------------------- | ------------------------------------------------------------------- | | Teams 用户 ID、Microsoft Entra ID（AAD Object ID） | 关联 Teams 用户与 Flashduty 用户；校验故障卡片操作人；向关联用户发送个人通知或操作反馈 | | Team ID、Team 名称、Channel ID | 关联 Teams 团队或频道；把告警和故障通知发送到指定 Teams 频道；查询指定 Team 的详情和频道列表 | | Group Chat ID、用户输入的 Chat 名称 | 关联 Teams 群聊；把告警和故障通知发送到指定群聊 | | Conversation ID、Activity ID、Bot Framework 会话引用 | 在应用安装后发送、更新或回复 Teams 通知卡片 | | Bot 指令和卡片动作 | 处理 `help`、`linkUser`、`linkTeam`、`linkChat` 指令，以及认领、解决、暂缓、自定义操作等卡片按钮 | | Flashduty 告警和故障卡片数据 | 在 Teams 中展示告警或故障详情，并把卡片操作结果同步回 Flashduty | Flashduty Teams 应用不会读取与 Flashduty 功能无关的普通 Teams 聊天内容。它只处理个人聊天中发送给 bot 的消息、团队或群聊中 @ bot 的消息、卡片按钮动作、应用安装和会话所需的引用信息，以及发送或更新 Flashduty 通知所需的数据。 当前应用包不申请用于读取全组织聊天内容的 Microsoft Graph 权限。如后续版本引入新的 Teams 权限或数据处理场景，Flashduty 将更新本文档和相关隐私说明。 ## 二、从 Microsoft Teams 获取应用 在 Microsoft Teams 中选择 **Apps**，搜索 **Flashduty**，然后打开应用详情页。 选择 **Add**。根据使用场景，选择添加到团队/频道、群聊或个人聊天。 以下指令中的 `{ID}` 请替换为 Flashduty Microsoft Teams 集成 ID；`{ChatName}` 请替换为群聊名称。 ## 三、关联团队 (Team) 在 Teams 中打开 **Apps**，找到 **Flashduty**，然后选择 **Add to a team**。 如果无法找到或添加应用，请联系 Microsoft Teams 管理员。 将应用添加到目标 Team。 此步骤必须选择目标 Team 的 General Channel，否则将无法发送故障到 Team 中。 ![2025-09-18-17-11-29](https://docs-cdn.flashcat.cloud/images/png/01fa86b63d01d2735aa6c4a53efb3c69.png) 在 Team 的 General Channel 中 @Flashduty 并发送 `linkTeam {ID}`，然后选择 **立即关联**。 ![2025-09-18-13-55-05](https://docs-cdn.flashcat.cloud/images/png/3192b5481b0595fcb58e5cc43abad125.png) 如需解除该 Team 的关联，请在同一频道中发送 `@Flashduty unlinkTeam {ID}`。在响应卡片中选择 **Unlink in FlashDuty** 后，Flashduty 会自动解除关联并显示成功提示。 ## 四、关联群聊 (Chat) 在 Teams 中打开 **Apps**，找到 **Flashduty**，然后选择 **Add to a chat**。 如果无法找到或添加应用，请联系 Microsoft Teams 管理员。 将应用添加到目标 Chat。 ![2025-09-18-17-14-23](https://docs-cdn.flashcat.cloud/images/png/6e56d7de341737fe495e5ff18eb1af34.png) 在群聊中 @Flashduty 并发送 `linkChat {ID} {ChatName}`，然后选择 **立即关联**。 ![2025-09-18-13-56-17](https://docs-cdn.flashcat.cloud/images/png/d0beee141db63714ccecb095affee79b.png) 如需解除该群聊的关联，请在同一群聊中发送 `@Flashduty unlinkChat {ID}`。在响应卡片中选择 **Unlink in FlashDuty** 后，Flashduty 会自动解除关联并显示成功提示。 ## 五、消息卡片操作 当故障通知推送到 Microsoft Teams 后，通知卡片可包含以下交互操作；具体可用按钮以您收到的 Flashduty 卡片和后台配置为准： * **认领（Acknowledge）**：标记您已开始处理该故障 * **解决（Resolve）**：将故障标记为已解决并关闭 * **暂缓（Snooze）**：暂时挂起故障，在指定时间后重新提醒 * **自定义操作（Custom Actions）**：触发您预先配置的自定义操作（如重启服务、回滚变更等） 作战室（War Room）功能目前不支持 Microsoft Teams。如果您需要使用作战室功能，请考虑使用 Slack、飞书、钉钉或企业微信集成。 ## 六、关联用户 在 Teams 中打开 **Apps**，找到 **Flashduty**，然后选择 **Open**。 如果无法找到或打开应用，请联系 Microsoft Teams 管理员。 点击 **打开应用**。 ![2025-09-18-13-56-55](https://docs-cdn.flashcat.cloud/images/png/2e6862103d718a913d2b3c449cbf2366.png) 在与 Flashduty 的个人聊天中发送 `linkUser {ID}`，然后选择 **立即关联**。 ![2025-09-18-13-57-13](https://docs-cdn.flashcat.cloud/images/png/671ae7883bbba839419e539762db99de.png) 如需解除您的 Teams 账号关联，请在同一个人聊天中发送 `unlinkUser {ID}`。在响应卡片中选择 **Unlink in FlashDuty** 后，Flashduty 会自动解除关联并显示成功提示。已关联的当前用户也可以前往 **集成中心 → 即时消息 → Microsoft Teams → 关联用户**，点击 **解除我的关联**，再在确认框中选择 **确认**。 ## 七、常见问题 请前往 集成中心 → 即时消息 → **Microsoft Teams**，检查团队和用户是否已成功关联。 请前往 集成中心 → 即时消息 → **Microsoft Teams**，在 **关联 Teams** 和 **关联用户** 中查看。 请在原始 Teams 上下文中使用对应指令：在 Team 频道中使用 `unlinkTeam {ID}`，在群聊中使用 `unlinkChat {ID}`，或在个人聊天中使用 `unlinkUser {ID}`。在响应卡片中选择 **Unlink in FlashDuty** 后，Flashduty 会自动解除对应关联。已关联的当前用户也可以在 **关联用户** 中点击 **解除我的关联**，再在确认框中选择 **确认**。 # Slack Source: https://docs.flashduty.com/zh/on-call/integration/instant-messaging/slack 通过集成 Slack 第三方应用，您可以在 Slack 内接收和响应告警 **版本要求**：IM 集成需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) ## AISRE 所需权限 以下为 Slack IM 集成在开启 AISRE（包含基础通知、作战室、AI SRE 对话、AI 生成复盘和故障通知分派）时需要授予的完整权限清单。进入 Slack 应用 **OAuth & Permissions** 页面时，请确认已授权以下官方 scope 名称。对于已授权的 Slack 集成，如缺少权限，请重新授权。 ### Bot Token Scopes | 官方 scope 名称 | 用途 | | :--------------------- | :------------------------------------ | | `app_mentions:read` | 接收群聊中 @ 应用的消息，用于 AI SRE 对话入口 | | `im:history` | 读取私聊历史消息，用于 AI SRE 上下文 | | `chat:write` | 发送基础通知、作战室消息和 AI SRE 回复 | | `chat:write.public` | 向应用尚未加入的公开频道发送通知和作战室消息 | | `channels:read` | 读取公开频道信息和频道列表 | | `channels:history` | 读取公开频道消息历史；AI SRE 上下文和 AI 生成复盘报告需要该权限 | | `groups:read` | 读取私有频道信息和频道列表 | | `groups:history` | 读取私有频道消息历史；AI SRE 上下文和 AI 生成复盘报告需要该权限 | | `groups:write` | 创建和管理私有频道作战室 | | `groups:write.invites` | 邀请成员加入私有频道作战室 | | `users:read` | 读取用户基础信息，用于用户关联、展示和邀请 | | `users:read.email` | 读取用户邮箱，用于用户关联 | | `reactions:write` | 添加或删除消息表情反应，用于 AI SRE 处理状态确认 | | `files:read` | 读取消息中的文件，用于 AI SRE 上下文和附件处理 | ### User Token Scopes | 官方 scope 名称 | 用途 | | :-------------- | :-------------------------- | | `channels:read` | 读取授权用户可见的公开频道，用于频道列表和分派策略配置 | 如果您使用的是 Slack Incoming Webhook 方式的 Slack 机器人通知，而不是本页的 Slack App 集成，请在对应 Slack 应用中开启 Incoming Webhooks，并在 OAuth 流程中包含 `incoming-webhook` scope。 ## 一、安装应用 访问 Flashduty On-call 集成中心 → 即时消息 → **Slack**，点击 **添加**。 在跳转的 Slack 页面，于右上角选择 **工作区**，然后点击 **允许**。 ![2025-09-18-15-03-58](https://docs-cdn.flashcat.cloud/images/png/01a96bb9a8bf1d6c4c6f176542f12722.png) 输入数据源名称，点击 **保存**。 ## 二、配置作战室 > 确保应用已被授权使用页面开头列出的 [AISRE 所需权限](#aisre-permissions)。 完成先前步骤后，在 Flashduty On-call 集成配置页面的 **增强功能** 模块，勾选 **开启作战室** 即可启用该功能，无需额外配置。 ### AI SRE 控制项 在 **增强功能** 中分别配置以下 AI SRE 控制项，默认均为开启： * **自动发起 AI 故障分析**：开启作战室后可配置；作战室创建成功后，自动发起一次 AI 故障分析。 * **允许群聊 @ AI SRE 和 /fd 命令**：无需开启作战室即可配置，允许在此集成已接入的 Slack 群聊中 @ AI SRE 或使用 `/fd` 命令；关闭后两个入口都不会响应。 * **普通群聊中 AI SRE 使用话题回复**：无需开启作战室即可配置。开启后，普通群聊中的每个话题对应一个独立 Session；作战室仍直接在群内回复。 如果账户尚未启用 AI SRE，以上配置暂不生效。 ## 三、关联用户 在集成详情页的 **关联用户** 页签中，你可以查看团队成员与 Slack 账号的关联状态，并快速完成批量关联。 ### 查看关联状态 关联用户列表展示所有团队成员及其关联状态。你可以通过以下方式筛选： | 筛选项 | 说明 | | :------ | :------------------- | | **全部** | 查看所有团队成员 | | **已关联** | 仅查看已完成 Slack 账号关联的成员 | | **未关联** | 仅查看尚未关联 Slack 账号的成员 | 支持通过名称或邮箱搜索成员。 ### 一键关联 当存在未关联的成员时，可以点击 **一键关联** 按钮。系统将尝试通过手机号或邮箱换取 Slack 开放平台的账号 ID 并自动关联，效果等同于成员使用相同信息在 Slack 平台登录 Flashduty。 成员完成关联后，系统才能向其推送 Slack 消息通知。如果关联失败，请确认成员的邮箱是否与 Slack 账号一致。 ## 四、常见问题 * 同一时间仅支持在一个 IM 集成中开启作战室功能。如果您已在其他 IM 集成（如钉钉、飞书、企业微信）中启用了作战室，需要先在该集成中关闭后，才能在当前 Slack 集成中开启 * 开启作战室时，系统会自动验证当前 Slack 应用是否具备作战室所需的全部权限。如果检测到缺少必要权限，页面会显示一条警告提示，并提供 **重新授权** 链接 * 点击 **重新授权** 链接后，系统会跳转到 Slack 授权页面，请求页面开头列出的 [AISRE 所需权限](#aisre-permissions)。完成授权后，页面会自动返回 Flashduty * 如果您的 Slack 集成是在作战室功能上线之前完成授权的，首次开启时通常需要重新授权以补充新增权限。重新授权不会影响已有的集成配置和用户关联 * 确保 [**安装应用**](#install-app) 步骤已成功完成且未报错 * 进入相关的 Slack 频道，执行 `/invite @Flashduty` 命令 * 当看到 `已加入` 或 `已由 xxx 添加至 xxx` 的提示时，即表示添加成功 * 将应用授权人添加到公共频道中 * 参考上一问题的方法，将应用添加到频道中 请重新操作。这可能是由于服务器与 Slack 通信异常导致授权失败。请返回添加数据源页面重试。如果重试后仍然报错，请联系客服。 请重新操作。这可能是由于 Flashduty 服务器在获取永久授权码时与 Slack 通信异常。请返回添加数据源页面重试。如果重试后仍然报错，请联系客服。 请重新操作，这可能是 Slack 服务暂时出现问题。如果重试后仍然报错，请联系客服。 请重新操作。这可能是服务器与 Slack 通信超时。如果重试后仍然报错，请联系客服。 请重新操作。这可能是 Flashduty On-call 服务端出现错误（例如，数据源被关闭）。如果重试后仍然报错，请联系客服。 请重新操作。如果重试后仍然报错，请联系客服以记录和解决新问题。 * 请再次检查是否为应用配置了页面开头列出的 [AISRE 所需权限](#aisre-permissions) * 对于之前授权的 Slack IM 集成，需要您在 Flashduty On-call 集成配置页中对 Slack 手动进行重新授权，以使应用获得 AISRE 所需权限 * 请参考 [作战室介绍文档](/zh/on-call/advanced/war-room) 的 **常见问题** 部分 # 企业微信 Source: https://docs.flashduty.com/zh/on-call/integration/instant-messaging/wecom 通过集成企业微信第三方应用，实现在企业微信端接收和响应告警的能力 **版本要求**：IM 集成需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 本文档支持 [集成第三方应用](#third-party) 或 [集成企业自建应用](#self) 两种方式。
**集成第三方应用** 和 **集成自建应用** 两种方式只需按需配置其中一种。 ## 一、集成第三方应用 Flashduty 作为企业微信服务商，为您提供 Flashduty 应用的长期免费版本。该应用需要获得企业微信接口调用许可才能使用（免密登录 + 消息发送）。该许可目前支持 **最多 60 天** 免费，超出该使用时长后，Flashduty 需要为您购买企业微信许可，您方可继续使用。 1. 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，进入 应用管理 → **应用** 页面，点击 **添加第三方应用**。 ![2025-09-18-11-36-22](https://docs-cdn.flashcat.cloud/images/png/ae4d35a354aaf22dd41b7493200517bc.png) 2. 在搜索栏输入 `Flashduty`，检索到应用后，点击 **添加** 按钮。 ![2025-09-18-11-38-57](https://docs-cdn.flashcat.cloud/images/png/77347db478c45f4c9d238d587d323a78.png) 3. 修改应用 **可见范围**，推荐选择全员或具体部门节点，以避免新增企业成员时仍需修改。然后，点击 **同意以上授权并添加** 完成安装。 ![2025-09-18-12-05-07](https://docs-cdn.flashcat.cloud/images/png/0821d1afdeb5db34c4c9b5548d5c8ca1.png) 4. 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，进入 **我的企业** 页面，获取 `企业 ID`。 ![2025-09-18-11-44-54](https://docs-cdn.flashcat.cloud/images/png/c032dc755a72550d57658dd5962dafe4.png) 5. 返回 Flashduty On-call 集成配置页面，填写上一步获取的 `企业 ID`，点击 **保存** 完成集成。 ## 二、集成企业自建应用 1. 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，进入 应用管理 → **应用** 页面，点击 **创建应用**。 ![2025-09-18-11-46-44](https://docs-cdn.flashcat.cloud/images/png/ed274f6a897b808678a5a29b23adcb66.png) 2. 配置 **应用 Logo**、**应用名称** 和 **应用可见范围**。 ![2025-09-18-11-49-18](https://docs-cdn.flashcat.cloud/images/png/26ec124891e580a6d1e1035ba52636ba.png) 3. 返回 Flashduty On-call 集成配置页面，根据您的实际情况选择企业微信是否为 `非私有化部署版本`。 若您的企业微信为私有化部署版本，则需要在配置页面中填写 `Endpoint`。此地址需要能够被 Flashduty 服务访问，您可以考虑为其设置 **白名单授权**。 4. 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，进入 **我的企业** 页面，获取 `企业 ID`，并将其填写至 Flashduty On-call 集成配置页面。 5. 返回 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，进入 **应用管理** 页面，点击您所创建的应用进入详情页。获取页面中的 `AgentId`，并将其填写至 Flashduty On-call 集成配置页面。 6. 在应用详情页，获取 `Secret`，并将其填写至 Flashduty On-call 集成配置页面。 7. 在应用详情页，进入 **网页授权及 JS-SDK** 页面，点击 **设置可信域名**，并按要求配置。 可信域名需要指向 Flashduty On-call 的后端地址 `{api_host}`（可通过 CNAME 或代理转发实现）。关于可信域名的要求，详见企业微信官方文档 [《企业内部开发配置域名指引》](https://open.work.weixin.qq.com/wwopen/common/readDocument/40754)。 ![2025-10-15-10-30-56](https://docs-cdn.flashcat.cloud/images/png/09a91d682198d1c8f830b5ed523965ef.png) 返回 Flashduty On-call 集成配置页面，填写该域名，并完成验证。 8. 在应用详情页，进入 **接收消息** 页面，并 **设置 API 接收**。分别对 `Token` 和 `EncodingAESKey` 点击 **随机获取**，然后复制并保存所生成的值。 ![2025-09-18-11-58-45](https://docs-cdn.flashcat.cloud/images/png/919bd2722c75513ce1d301779b39c3bf.png) 返回 Flashduty On-call 集成配置页面，填写已保存的 `Token` 和 `EncodingAESKey`，点击 **保存** 完成集成。 9. 复制 Flashduty On-call 集成详情页中的 `回调地址`，返回企业微信刚才的 **接收消息** 页面。在 **API 接收** 设置中，填入该 `回调地址` 以及上一步保存的 `Token` 和 `EncodingAESKey`，然后点击 **保存**。 ![2025-09-18-11-56-43](https://docs-cdn.flashcat.cloud/images/png/c990c27f7ad90af172e159fc4acfead7.png) 10. 配置**前端可信域名** 可信域名需要指向 Flashduty On-call 的前端地址 `console.flashcat.cloud`（可通过 CNAME 或代理转发实现）。关于可信域名的要求，详见企业微信官方文档 [《企业内部开发配置域名指引》](https://open.work.weixin.qq.com/wwopen/common/readDocument/40754)。 前端可信域名校验通过后将生成的**主页地址**配置到企微应用的**工作台应用主页** ![2025-10-14-19-51-01](https://docs-cdn.flashcat.cloud/images/png/595a71dd5624a37312676e83c45d79c4.png) 11. 配置**可信 IP 地址**：`47.93.12.134` ![2025-10-14-20-26-45](https://docs-cdn.flashcat.cloud/images/png/fe3b2b788dda5d331148ba0946631b91.png) ## 三、配置作战室 作战室功能仅支持在 **企业自建应用** 模式下开启。 完成先前步骤后，在 Flashduty On-call 集成配置页面的 **增强功能** 模块，勾选 **开启作战室** 即可启用该功能，无需额外配置。 同一时间仅支持在一个 IM 集成中开启作战室功能。如果你已在其他 IM 集成（如钉钉、飞书、Slack）中启用了作战室，需要先在该集成中关闭后，才能在当前企业微信集成中开启。 ### AI SRE 控制项 开启 **作战室** 后，配置页会显示以下 AI SRE 控制项，默认均为开启： * **自动发起 AI 故障分析**：作战室创建成功后，自动发起一次 AI 故障分析。 * **允许群聊 @ AI SRE**：允许在此集成已接入的群聊中 @ AI SRE 发起对话；关闭后不会响应该入口。 如果账户尚未启用 AI SRE，以上配置暂不生效。 ## 四、配置 AISRE 如需在企业微信中使用 AISRE，请先在 Flashduty 企业微信集成中开启 **作战室** 功能，然后额外创建一个智能机器人，并使用 API 模式接入 Flashduty。 1. 在企业微信应用左侧进入 **工作台**，找到 **智能机器人**，进入机器人管理页面。 2. 创建一个新的智能机器人，创建方式选择 **手动创建**，然后选择 **使用 API 模式创建**。 建议由企业内部成员创建智能机器人。即使可见范围设置为 **企业内部全体成员**，其他成员仍需要创建者通过分享后才能看到该机器人。 3. 在智能机器人的 **API 配置** 页面，连接方式选择 **使用 URL 回调**，并填入 Flashduty 集成配置页提供的 `URL`。 4. 在企业微信智能机器人的 API 配置页中生成 `Token` 和 `Encoding-AESKey`，并将相同的值填写到 Flashduty 企业微信集成配置页。请确保企业微信和 Flashduty 中的 `Token`、`Encoding-AESKey` 完全一致，然后分别保存两边配置。 企业微信暂不支持在创建作战室后自动将智能机器人拉入群聊。使用 AISRE 时，需要手动将智能机器人添加到对应作战室群聊中。 ## 五、关联用户 在集成详情页的 **关联用户** 页签中，你可以查看团队成员与企业微信账号的关联状态，并快速完成批量关联。 ### 查看关联状态 关联用户列表展示所有团队成员及其关联状态。你可以通过以下方式筛选： | 筛选项 | 说明 | | :------ | :---------------- | | **全部** | 查看所有团队成员 | | **已关联** | 仅查看已完成企业微信账号关联的成员 | | **未关联** | 仅查看尚未关联企业微信账号的成员 | 支持通过名称或邮箱搜索成员。 ### 一键关联 当存在未关联的成员时，可以点击 **一键关联** 按钮。系统将尝试通过手机号或邮箱换取企业微信开放平台的账号 ID 并自动关联，效果等同于成员使用相同信息在企业微信平台登录 Flashduty。 成员完成关联后，系统才能向其推送企业微信消息通知。如果关联失败，请确认成员的手机号或邮箱是否与企业微信账号一致。 ## 六、集成企微智能体（AI SRE） 企微智能体（AI Bot）是企业微信提供的 AI 对话机器人功能。通过将 Flashduty AI SRE 与企微智能体对接，您的团队可以在企微单聊或群聊中直接通过 @ 智能体发起 AI 故障排查会话，无需离开企业微信。 智能体集成使用**独立于普通应用的凭据**（Bot Token 和 Bot EncodingAESKey）。请勿将 [集成企业自建应用](#self) 步骤 8 中生成的 Token / EncodingAESKey 填入此处——两套凭据彼此独立，混用将导致签名验证失败。 AI SRE 功能需要账户开通对应权限。如未开通，企微智能体收到消息后将不作任何响应。 ### 配置步骤 访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，进入 **应用管理 → AI 助理** 页面，点击 **创建 AI 助理**（智能体），完成基础信息配置（名称、头像、可见范围）。 进入已创建智能体的详情页，找到 **接收消息** 配置区域，分别对 `Token` 和 `EncodingAESKey` 点击 **随机生成**，然后复制并妥善保存这两个值。 这两个值仅属于该智能体，与您在企业微信自建应用中配置的 Token / EncodingAESKey **完全不同**。 返回 Flashduty On-call 企业微信集成详情页，在 **AI SRE 智能体** 配置区域，将上一步获得的 `Bot Token` 和 `Bot EncodingAESKey` 分别填入对应字段，点击 **保存**。 保存成功后，页面会显示该集成的 `integration_key`（即集成密钥）。 复制 Flashduty On-call 集成详情页中的 **智能体回调地址**，格式为： ``` https:///event/push/wecom/bot?integration_key= ``` 返回企业微信管理后台，进入该智能体的 **接收消息** 设置，将回调地址、Token 和 EncodingAESKey 填入对应字段，点击 **保存**。 企业微信会向该地址发送一次 GET 请求进行 URL 验证（echostr 校验），Flashduty 服务器会自动完成验证应答。 ### 使用方式 配置完成后，在企微单聊或群聊中 **@ 您的智能体**，输入问题或故障描述，即可触发 AI SRE 会话。智能体支持以下消息类型： | 类型 | 说明 | | :------- | :--------------------- | | **文本** | 直接提问或描述问题 | | **图片** | 发送截图，AI 将解析图片内容进行分析 | | **文件** | 发送日志或配置文件，AI 将读取内容辅助排查 | | **引用回复** | 引用上一条消息追问，AI 会结合上下文作答 | 企业微信智能体采用**拉取式流式响应**（stream polling）：AI 生成回复时，企业微信客户端会定期向回调地址发送 `msgtype=stream` 请求拉取最新内容，直到 AI 回复完成。这是企业微信智能体的平台机制，用户无需额外配置。 ### 常见问题 请按以下顺序排查： 1. 确认账户已开通 AI SRE 功能权限 2. 确认回调地址中的 `integration_key` 与 Flashduty 集成详情页显示的值完全一致 3. 确认 Flashduty 集成配置页中填写的 `Bot Token` 和 `Bot EncodingAESKey` 与智能体详情页 **接收消息** 中的值一致，而非来自企业微信自建应用 4. 在企业微信管理后台查看智能体的回调日志，确认请求是否到达以及是否有错误码 * 确认 Flashduty 服务能够被企业微信服务器正常访问（公网可达） * 确认填写的 `Token` 和 `EncodingAESKey` 与 Flashduty 集成配置页中保存的值完全一致 * 确认回调地址中的 `integration_key` 参数正确，且对应的集成处于启用状态 这通常意味着 Bot Token 或 Bot EncodingAESKey 填写有误。请注意：智能体的 Token / EncodingAESKey 与企业微信自建应用（普通 IM 集成）的 Token / EncodingAESKey **是两套独立凭据**，请在智能体详情页的 **接收消息** 区域重新生成并更新至 Flashduty 集成配置。 ## 七、常见问题 * 请检查您是否已完成应用的安装步骤。例如，您是否可以在企业微信工作台中看到 Flashduty On-call 应用 * 请检查您是否正确配置了 `Corp ID` 1. 登录企业微信客户端（桌面端和移动端均可），进入 **工作台**，找到并打开 Flashduty 应用 2. 首次进入应用需要登录。选择您的成员账号，通过密码或单点登录方式登入成功后，即可完成 Flashduty 账号与企业微信账号的关联 3. 后续进入应用将自动免密登录 1. 发送通知前，必须参照上一问题完成账户关联 2. 进入指定协作空间，导航至 `分派策略` → **个人渠道**，选择 `企业微信` 作为通知方式即可 3. Flashduty On-call 支持对企业微信通知内容进行自定义。您可以前往 **模板管理** 页面，设定自定义模板 自定义区域最多可展示 8 行，超出部分将被企业微信截断。 ![2025-09-18-12-02-26](https://docs-cdn.flashcat.cloud/images/png/9cb6a325b4b16875fec3e0c5054be25b.png) * 点击卡片消息，可直接进入告警详情页面 * 点击 **开始处理**，可直接将告警置为 `处理中` 状态 * 点击 **直接关闭**，可直接将告警置为 `已关闭` 状态 * 点击 **屏蔽 2 小时**，可直接将告警屏蔽 2 小时。如果想屏蔽更长时间，可点击卡片右上角的 `...` 查看更多屏蔽选项 根据企业微信的限制，一次卡片交互后，72 小时内只可更新一次。每一次按钮操作，都视为一次交互。 当告警状态发生变化时，Flashduty On-call 会请求更新卡片内容。当告警状态频繁变化时，可能因超出更新次数限制导致卡片无法实时更新。此时，您可以点击 **刷新** 按钮，手动获取一次更新卡片状态的机会。 Mac 桌面端默认使用企业微信的内置浏览器打开链接。您可以尝试使用快捷键 `ctrl` + `command` + `shift` + `d` 开启调试模式，然后选择 **调试** → **浏览器、webView 相关** → **系统浏览器打开网页**，来更改链接的打开方式。使用相同的快捷键可以关闭调试模式，设置将会保留。 请联系 Flashduty 客服或您的专属技术支持，为您购买并开通许可。 请参考 [作战室介绍文档](/zh/on-call/advanced/war-room) 的 **常见问题** 部分。 请确认**应用主页**的 URL 中的 `redirect_uri` 参数中的域名是否完成企业微信要求的域名归属认证，详见企业微信官方文档 [《企业内部开发配置域名指引》](https://open.work.weixin.qq.com/wwopen/common/readDocument/40754)。 # Link 集成 Source: https://docs.flashduty.com/zh/on-call/integration/other-integration/link 通过 Link 集成，可直接从故障属性、标签等信息中获取访问外部链接所需的关键参数，实现快速访问 通过 Link 集成，可直接从故障属性、标签等信息中获取访问外部链接所需的关键参数，实现快速访问。 ## 配置说明 Link 集成功能支持从故障属性、标签等信息中提取关键参数，实现与外部系统的快速跳转。通过自动化填充和跳转，避免了手动输入，提高了问题定位与处理的效率。该功能适用于故障排查、性能监控和系统调试等场景，有助于优化运维流程，提升响应速度与准确性。 ### 打开方式 #### 1. 弹窗 在故障详情的当前页面中弹出窗口，保持原有界面状态，适合快速查看或操作后返回。 #### 2. 新标签页 在浏览器新标签中打开链接，适用于需要保留当前操作上下文并同时访问外部内容的场景。 ### URL 配置 URL 的参数引用内容为标签时以 `labels.` 开头；引用内容为自定义字段时，以 `fields.` 开头；引用内容为故障属性时，直接引用即可，如 `title`、`severity` 等。 #### 故障标签中获取 支持通过 的方式从参数中动态取值，用于构造请求地址。例如参数值从故障标签中自动填充，无需手动输入： ```text theme={null} https://cmdb.com/vm?sn=${labels.sn} ``` 在上述示例中， 表示将故障中的 `sn` 标签值动态注入至 URL 中。如果故障数据中包含 `sn=VM123456`，则最终请求地址为： ```text theme={null} https://cmdb.com/vm?sn=VM123456 ``` #### 自定义字段中获取 支持通过 的方式从参数中动态取值，用于构造请求地址。例如参数值从自定义字段中自动填充，无需手动输入： ```text theme={null} https://cmdb.com/vm?sn=${fields.sn} ``` 在上述示例中， 表示将故障中的 `sn` 自定义字段值动态注入至 URL 中。如果自定义字段数据中包含 `sn=VM123456`，则最终请求地址为： ```text theme={null} https://cmdb.com/vm?sn=VM123456 ``` ### 注意事项 1. 当引用的内容不存在时，Link 集成会正常生成对应的链接，但无法获取到值 2. 同一个协作空间至多绑定三个 Link 集成 3. 注意引用语法，如未按照要求进行书写引用变量，会导致无法正常获取对应值 # Authing Source: https://docs.flashduty.com/zh/on-call/integration/sso/authing 通过 Authing 平台配置 OIDC、SAML2.0 或 CAS 协议实现单点登录 [Authing](https://www.authing.cn/) 是一家提供身份识别和访问控制管理的供应商，通过 Authing 平台，可实现以 OIDC、SAML2.0 或 CAS 协议的方式登录 Flashduty 管理控制台。 ## 准备工作 如果是新注册用户，需先创建用户池，根据提示创建即可。 * 选择标准 web 应用 * 填写应用名称 * 填写认证地址（SSO 登录时跳转的地址） ![创建应用](https://api.apifox.com/api/v1/projects/4169655/resources/436934/image-preview) ![应用信息](https://api.apifox.com/api/v1/projects/4169655/resources/436952/image-preview) | 字段 | 描述 | | ---------- | ---------------------------- | | App ID | 对应 Flashduty 的 Client ID | | APP Secret | 对应 Flashduty 的 Client Secret | | Issuer | 对应 Flashduty 的 Issuer | | 认证地址 | 通过 SSO 登录时跳转的地址 | ## 协议配置 ### 1. 开启单点登录配置 打开 [Flashduty](https://console.flashcat.cloud) 控制台并开启单点登录配置。 ![开启SSO](https://api.apifox.com/api/v1/projects/4169655/resources/436946/image-preview) ### 2. 配置相关信息 将 Authing 应用的相关信息复制到对应的填写框中： ![配置信息](https://api.apifox.com/api/v1/projects/4169655/resources/436951/image-preview) 将 Redirect URL 域名复制到 Authing 的登录回调 URL 中： ![回调URL](https://api.apifox.com/api/v1/projects/4169655/resources/436957/image-preview) ### 3. 更改 Authing 配置 将 id\_token 签名算法更改为 **RS256**： ![签名算法](https://api.apifox.com/api/v1/projects/4169655/resources/436961/image-preview) 配置登录控制： ![登录控制](https://api.apifox.com/api/v1/projects/4169655/resources/436964/image-preview) 更改权限： ![权限配置](https://api.apifox.com/api/v1/projects/4169655/resources/436967/image-preview) ### 4. 创建用户并测试登录 Flashduty 默认通过邮箱关联成员，建议用邮箱创建用户。新建 SSO 配置也可以配置稳定用户 ID 字段进行关联，详见 [单点登录配置](/zh/platform/configure-sso)。 在 Authing 中创建用户： ![创建用户](https://api.apifox.com/api/v1/projects/4169655/resources/436973/image-preview) 使用 SSO 地址测试登录： ![测试登录](https://api.apifox.com/api/v1/projects/4169655/resources/436976/image-preview) 您也可以访问 `console.flashcat.cloud` 通过 SSO 的方式登录。 SSO 地址跳转到登录页面后，使用在 Authing 创建的用户登录 Flashduty 控制台： ![登录页面](https://api.apifox.com/api/v1/projects/4169655/resources/436980/image-preview) 可以新创建应用或者在已有的应用中修改，这里通过修改应用进行演示。 ### 1. 协议配置 选择 SAML2.0： ![选择SAML](https://api.apifox.com/api/v1/projects/4169655/resources/436984/image-preview) 将 Flashduty 的单点登录协议改成 SAML 协议，并复制 ACS 地址： ![复制ACS](https://api.apifox.com/api/v1/projects/4169655/resources/436987/image-preview) 将 ACS 地址复制到 Authing 应用中后，点击保存并修改协议类型： ![保存配置](https://api.apifox.com/api/v1/projects/4169655/resources/436989/image-preview) ### 2. 在 Flashduty 中配置 下载 metadata 数据，点击链接并保存到本地： ![下载metadata](https://api.apifox.com/api/v1/projects/4169655/resources/436990/image-preview) 上传到 Flashduty 的单点登录配置中并保存： ![上传metadata](https://api.apifox.com/api/v1/projects/4169655/resources/436991/image-preview) ### 3. 测试登录 参考 OIDC 协议的登录流程进行测试： ![测试登录](https://api.apifox.com/api/v1/projects/4169655/resources/436980/image-preview) 两个平台在配置时有穿插，请务必小心不要遗忘关键信息。如在配置过程中有任何问题，可以联系 Flashduty 技术支持协助。 ### 1. 开启单点登录配置 打开 [Flashduty](https://console.flashcat.cloud) 控制台并开启单点登录配置。 ![开启SSO](https://api.apifox.com/api/v1/projects/4169655/resources/436946/image-preview) ### 2. 配置相关信息 将 Authing 应用的相关信息复制到对应的填写框中： ![CAS配置](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/kb/cas-duty-conf.jpg) 将 Redirect URL 复制到 Authing 的登录回调 URL 中： ![回调URL](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/kb/cas-auth-callback.jpg) ### 3. 更改 Authing 配置 按图配置： ![Authing配置](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/kb/cas-auth-conf.jpg) 配置登录控制： ![登录控制](https://api.apifox.com/api/v1/projects/4169655/resources/436964/image-preview) 更改权限： ![权限配置](https://api.apifox.com/api/v1/projects/4169655/resources/436967/image-preview) ### 4. 创建用户并测试登录 Flashduty 默认通过邮箱关联成员，建议用邮箱创建用户。新建 SSO 配置也可以配置稳定用户 ID 字段进行关联，详见 [单点登录配置](/zh/platform/configure-sso)。 在 Authing 中创建用户： ![创建用户](https://api.apifox.com/api/v1/projects/4169655/resources/436973/image-preview) 使用 SSO 地址测试登录： ![测试登录](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/kb/cas-login.jpg) SSO 地址跳转到登录页面后，使用在 Authing 创建的用户登录 Flashduty 控制台： ![登录页面](https://api.apifox.com/api/v1/projects/4169655/resources/436980/image-preview) # Keycloak Source: https://docs.flashduty.com/zh/on-call/integration/sso/keycloak 通过 Keycloak 配置 SAML2.0 或 OIDC 协议实现单点登录 Keycloak 是一个开源的身份和访问管理解决方案，提供了一套全面的工具和功能，帮助开发人员快速实现安全的用户身份验证和授权机制。 本篇文章不涉及部署和讲解 Keycloak 相关内容，如需了解更多信息，请参考 [官方文档](https://www.keycloak.org/)。 ## 协议配置 ### 1. 获取 ACS 地址 登录 Flashduty 控制台，获取 ACS 地址（后续步骤会用到）。 路径：**访问控制 => 单点登录 => 设置 => SAML2.0 协议 => Flashduty 服务提供商信息 => Assertion Consumer Service URL** ![获取ACS地址](https://api.apifox.com/api/v1/projects/4169655/resources/437194/image-preview) ### 2. 创建 Client 登录 Keycloak 控制台，路径：**Clients => Create client** * **Client Type**：选择 SAML 协议 * **Client ID**：填写 `flashcat.cloud`（固定值，不可更改） ![创建Client](https://api.apifox.com/api/v1/projects/4169655/resources/437197/image-preview) **Valid redirect URIs**：填写从 Flashduty 获取的 ACS 地址 ![配置redirect](https://api.apifox.com/api/v1/projects/4169655/resources/437029/image-preview) ### 3. 配置 Client 相关信息 **Name ID format** 更改为 email 类型： ![Name ID format](https://api.apifox.com/api/v1/projects/4169655/resources/437031/image-preview) **Client signature required** 设置为关闭状态： ![关闭签名](https://api.apifox.com/api/v1/projects/4169655/resources/437195/image-preview) **创建 Client scope**： 创建之前需要先删除之前 OpenID Connect 协议的用户，创建完成设置为 Default。 参考下图依次创建 email/phone/username 三种类型： ![创建scope](https://api.apifox.com/api/v1/projects/4169655/resources/437033/image-preview) 创建完成的效果： ![scope效果](https://api.apifox.com/api/v1/projects/4169655/resources/437034/image-preview) **将添加的用户加入到 Client 中**： ![添加用户1](https://api.apifox.com/api/v1/projects/4169655/resources/437037/image-preview) ![添加用户2](https://api.apifox.com/api/v1/projects/4169655/resources/437038/image-preview) **配置 email/phone/username 映射器**（以 email 为例，其他按照相同步骤配置）： ![映射器1](https://api.apifox.com/api/v1/projects/4169655/resources/437057/image-preview) ![映射器2](https://api.apifox.com/api/v1/projects/4169655/resources/437058/image-preview) ![映射器3](https://api.apifox.com/api/v1/projects/4169655/resources/437060/image-preview) ### 4. 下载 XML 文件 下载的文件是一个压缩包，在本地解压后会有两个 xml 文件，只需要 `idp-metadata.xml` 文件即可。 在 **Client => Action** 中下载到本地： ![下载XML](https://api.apifox.com/api/v1/projects/4169655/resources/437039/image-preview) 上传 XML 文件到 Flashduty 的单点登录配置中： ![上传XML](https://api.apifox.com/api/v1/projects/4169655/resources/437040/image-preview) ### 5. 创建用户并测试登录 创建用户（一定要绑定一个邮箱地址）： ![创建用户](https://api.apifox.com/api/v1/projects/4169655/resources/437041/image-preview) **登录测试**：访问 `console.flashcat.cloud`，选择 SSO 登录，在域名处填写单点登录配置中的登录域名前缀。 ![测试登录](https://api.apifox.com/api/v1/projects/4169655/resources/437062/image-preview) ### 1. 获取 Redirect URL 登录 Flashduty 控制台，获取 Redirect URL（后续步骤会用到）。 路径：**访问控制 => 单点登录 => 设置 => OIDC 协议 => Flashduty 服务提供商信息 => Redirect URL** ![获取Redirect URL](https://api.apifox.com/api/v1/projects/4169655/resources/437183/image-preview) ### 2. 创建 Client 登录 Keycloak 控制台，创建新 Client： * **Client Type**：选择 OIDC 协议 * **Client ID**：没有特殊要求 ![创建Client](https://api.apifox.com/api/v1/projects/4169655/resources/437179/image-preview) **Client authentication**：保持开启状态 ![Client authentication](https://api.apifox.com/api/v1/projects/4169655/resources/437180/image-preview) **Valid redirect URIs**：填写第 1 步获取的 Redirect URL 地址 ![配置redirect](https://api.apifox.com/api/v1/projects/4169655/resources/437184/image-preview) ### 3. 获取 Client 相关信息 * **Client ID**：创建 Client 时填写的 ID * **Client Secret**：在 **Client 详情 => Credentials** 卡片中查看 ![Client Secret](https://api.apifox.com/api/v1/projects/4169655/resources/437186/image-preview) * **Issuer**：在 **Realm settings => Endpoints => OpenID Endpoint Configuration** 中查看 ![Issuer](https://api.apifox.com/api/v1/projects/4169655/resources/437187/image-preview) ### 4. 配置 Flashduty 单点登录 将上述信息填入 Flashduty 单点登录配置： ![Flashduty配置](https://api.apifox.com/api/v1/projects/4169655/resources/437188/image-preview) 配置完成后，登录测试参考 SAML2.0 协议的第 5 步即可。 # OpenLDAP Source: https://docs.flashduty.com/zh/on-call/integration/sso/openldap 通过 Docker Compose 搭建 OpenLDAP 并集成到 Flashduty LDAP 集成登录仅 **私有化版本** 支持。 ## 快速了解 LDAP（Lightweight Directory Access Protocol，轻量级目录访问协议）是一种基于 X.500 标准的协议，用于访问和维护分布式目录服务。LDAP 使得用户和应用程序能够查询、浏览和搜索存储在目录中的信息，如用户身份信息、网络资源等。 LDAP 通常运行在 TCP/IP 协议栈上，特别是使用 TCP 端口 389（未加密通信）和 636（加密通信，使用 LDAPS）。 **LDAP 的核心特性：** * **树状结构**：LDAP 数据组织成树状结构，称为 DIT（Directory Information Tree），便于进行层次化的搜索和浏览 * **条目和属性**：LDAP 中的每个条目（Entry）包含多个属性（Attribute），属性有类型和值，例如 `cn` 代表通用名称（Common Name），`mail` 代表电子邮件地址 OpenLDAP 是一个开源的 LDAP 实现，由于其开源和灵活性，成为了许多企业和组织的首选。 本文基于环境中已经支持 Docker 和 Docker Compose，如果环境不支持，请先自行安装。 ## Docker Compose 配置 ```yaml docker-compose.yml theme={null} version: '1' networks: go-ldap-admin: driver: bridge services: openldap: image: osixia/openldap:1.5.0 container_name: go-ldap-admin-openldap hostname: go-ldap-admin-openldap restart: always environment: TZ: Asia/Shanghai LDAP_ORGANISATION: "flashduty.com" LDAP_DOMAIN: "flashduty.com" LDAP_ADMIN_PASSWORD: "password" volumes: - ./openldap/ldap/database:/var/lib/ldap - ./openldap/ldap/config:/etc/ldap/slapd.d ports: - 389:389 networks: - go-ldap-admin phpldapadmin: image: osixia/phpldapadmin:0.9.0 container_name: go-ldap-admin-phpldapadmin hostname: go-ldap-admin-phpldapadmin restart: always environment: TZ: Asia/Shanghai PHPLDAPADMIN_HTTPS: "false" PHPLDAPADMIN_LDAP_HOSTS: go-ldap-admin-openldap ports: - 8088:80 volumes: - ./openldap/phpadmin:/var/www/phpldapadmin depends_on: - openldap links: - openldap:go-ldap-admin-openldap networks: - go-ldap-admin ``` 请将 `password` 替换成您想要设置的密码。 ## 服务启动 将上述配置文件保存为 `docker-compose.yml`，在配置文件所在的目录，打开终端运行以下命令： ```bash theme={null} docker-compose up ``` ```bash theme={null} docker-compose up -d ``` **查看服务状态：** ```bash theme={null} docker-compose ps ``` **停止服务：** ```bash theme={null} docker-compose down ``` ## 登录 OpenLDAP 在浏览器中访问 `http://ip:8088/`，使用以下凭据登录： | 字段 | 值 | | --- | ------------------------------ | | 用户名 | `cn=admin,dc=flashduty,dc=com` | | 密码 | 您设置的密码 | ## OpenLDAP 配置 ### 添加组和用户 ![添加组和用户](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/kb/ldap-add-group-user.png) 在 **用户路径**（例如上图 `ou=people` 下的 `cn=flash duty`）=> **Add new attribute** => 选择 **Email**，为用户添加 Email 属性。若已存在请忽略。 ## Flashduty 集成 结合上述 OpenLDAP 配置，Flashduty 集成信息如下图所示： ![Flashduty集成配置](https://fcpub-1301667576.cos.ap-nanjing.myqcloud.com/flashduty/kb/ldap-duty-config.png) 上述字段的含义与描述请参考 [配置单点登录](/zh/platform/configure-sso)。 配置完成后，点击设置抽屉底部的 **连接检测** 按钮，验证 Flashduty 能否成功连接到 OpenLDAP 服务器。连接成功后再点击 **保存**。 # 告警 Webhook Source: https://docs.flashduty.com/zh/on-call/integration/webhooks/alert-webhook 配置告警 Webhook，当告警发生特定操作时，系统通过 HTTP 回调您配置的地址 **版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 配置告警 Webhook，当告警发生特定操作（如触发、关闭）时，系统通过 HTTP 回调您配置的地址。回调内容将包含告警最新关键信息，您可以与自研工具进行集成。 ## 一、事件类型 目前支持以下事件类型，未来可能会增加。
| 事件类型 | 释义 | | :-------: | :------------------------------------------ | | a\_new | 集成推送新事件，触发一条新告警 | | a\_update | 集成推送新事件，合并到一条告警，并更新告警信息（严重程度、状态、labels、描述等） | | a\_merge | 合并告警至故障 | | a\_close | 手动关闭告警（系统事件，当告警被手动关闭时由系统自动触发，无法在 UI 中勾选） |
## 二、推送描述 ### 请求方式
POST, Content-Type:"application/json"
### 请求 Payload：
| 字段 | 类型 | 必含 | 释义 | | :---------: | :---------------: | :-: | :----------------------------------- | | event\_time | int64 | 是 | 事件发生`毫秒时间戳` | | event\_type | string | 是 | 事件类型，枚举值见[事件类型](#EventTypes) | | event\_id | string | 是 | 事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重` | | person | [Person](#Person) | 否 | 操作人，仅人为动作时存在 | | alert | [Alert](#Alert) | 是 | 告警详情 | **Person**: | 字段 | 类型 | 必含 | 释义 | | :----------: | :----: | :-: | :---- | | person\_id | int64 | 是 | 人员 ID | | person\_name | string | 是 | 人员名称 | | email | string | 是 | 邮件地址 | **Alert**: | 字段 | 类型 | 必含 | 释义 | | :----------------: | :-------------------: | :-: | :------------------------------------------------------ | | alert\_id | string | 是 | 告警 ID | | data\_source\_id | int64 | 是 | 集成 ID | | data\_source\_name | string | 是 | 集成名称 | | data\_source\_type | string | 是 | 集成类型 | | channel\_id | int64 | 是 | 协作空间 ID | | channel\_name | string | 是 | 协作空间名称 | | title | string | 是 | 告警标题 | | title\_rule | string | 否 | 标题生成规则 | | description | string | 否 | 告警描述 | | alert\_key | string | 是 | 告警关联依据 | | alert\_severity | string | 是 | 严重程度，枚举值：Critical，Warning，Info | | alert\_status | string | 是 | 告警状态，枚举值：Critical，Warning，Info，Ok | | progress | string | 是 | 处理进度，枚举值：Triggered，Closed | | created\_at | int64 | 是 | 创建时间 | | updated\_at | int64 | 是 | 更新时间 | | start\_time | int64 | 是 | 首次触发时间（平台接收到的首个事件的时间），Unix 秒时间戳 | | last\_time | int64 | 是 | 最新事件时间（平台接收到的最新事件时间），Unix 秒时间戳 | | end\_time | int64 | 否 | 告警恢复时间（平台上一次接收到结束类型事件的时间），Unix 秒时间戳，默认为 0 | | close\_time | int64 | 否 | 关闭时间，不同于 end\_time，这个是处理进度的关闭，不代表告警真的恢复。Unix 秒时间戳，默认为 0 | | labels | map\[string]string | 否 | 标签 KV，Key 和 Value 均为字符串 | | event\_cnt | int64 | 否 | 关联事件个数 | | incident | [Incident](#Incident) | 否 | 所属故障 | **Incident**: | 字段 | 类型 | 必含 | 释义 | | :----------: | :----: | :-: | :---- | | incident\_id | string | 是 | 故障 ID | | title | string | 是 | 故障标题 |
### 请求响应 HTTP status code 为 200，认为推送成功。 ### 请求示例 ``` curl -X POST 'https://example.com/alert/webhook?a=a' \ -H 'Content-Type: application/json' \ -H 'X-Customize-Header-A: a' \ -d '{ "alert":{ "alert_id":"645c3affd2b92d989a0bd824", "alert_key":"d21d9e3126f5ae94", "alert_severity":"Warning", "alert_status":"Warning", "channel_id":1163577812973, "channel_name":"订单系统", "close_time":0, "created_at":1683766015, "data_source_id":1571358104973, "data_source_name":"阿里云 SLS", "data_source_ref_id":"", "data_source_type":"aliyun-sls.alert", "description":"测试发送到Flashduty告警触发", "end_time":0, "event_cnt":1, "incident":{ "incident_id":"645db17c9759374196929314", "title":"123123123" }, "labels":{ "a":"a", "alert_type":"sls_alert", "alert_url":"https://sls.console.aliyun.com/lognext/project/sls-api-testing/alert/alert-1683548531-071659", "aliuid":"1082109605037616", "check":"测试发送到Flashduty", "fire_results":"{\"_col0\":\"true\"}", "fire_results_count":"1", "project":"sls-api-testing", "raw_condition":"Count:__count__ \u003e 0; Condition:", "region":"cn-beijing", "resource":"d18195cd567c6e8b-5fb6a5e6fb8ad-1f269e0", "severity":"6" }, "last_time":1683809153, "progress":"Triggered", "start_time":1683766013, "title":"测试发送到Flashduty告警触发", "title_rule":"$resource::$check", "updated_at":1683809170 }, "event_id":"ffcf1d47a8d853dc800d000c87e5568b", "event_time":1683890681639, "event_type":"a_merge", "person":{ "email":"zhangsan@flashcat.cloud", "person_id":82138731581973, "person_name":"快猫星云" } }' -v ``` ## 三、配置指南 进入 **集成中心** → **Webhook** → 添加或编辑 **告警 Webhook** 集成。 ### 基础设置 填写集成名称和描述，便于后续管理。 ### Webhook 设置 | 配置项 | 说明 | | :----------- | :---------------------------------------------------- | | **管理团队** | 选择管理该集成的团队，只有团队成员可以编辑此集成配置 | | **Endpoint** | 接收回调的 HTTP/HTTPS 地址，必须以 `http://` 或 `https://` 开头 | | **TLS 验证** | 默认启用。关闭后将跳过目标服务器的 TLS 证书验证，适用于测试环境或自签名证书场景 | | **Headers** | 自定义请求头，以 Key-Value 形式添加，支持添加多个 | | **协作空间** | 选择 **全部空间** 或 **部分空间**。选择部分空间时，仅该空间下的告警事件会触发回调 | | **事件类型** | 勾选需要订阅的事件类型（参见[事件类型](#EventTypes)），支持全选。仅选中的事件类型会触发回调 | 关闭 TLS 证书验证可能存在中间人攻击风险，建议仅在测试环境或使用自签名证书时关闭。 ## 四、调用历史 告警 Webhook 提供完整的调用历史记录，方便你排查推送是否成功以及调试回调接口。 ### 查看调用历史 进入告警 Webhook 集成详情页，切换到 **调用历史** 页签即可查看。 ### 筛选与搜索 | 筛选项 | 说明 | | :-------- | :----------------------------------------------- | | **时间范围** | 支持选择最近 1 小时、6 小时、1 天、7 天，或自定义时间范围（最多查看最近 7 天的数据） | | **告警 ID** | 输入告警 ID 进行精确搜索 | | **事件类型** | 按事件类型筛选记录 | | **请求状态** | 按成功或失败筛选 | ### 历史记录字段 | 字段 | 说明 | | :-------- | :------------------------------ | | **触发时间** | 事件触发的时间 | | **事件类型** | 触发的事件类型（如 `a_new`、`a_update` 等） | | **告警 ID** | 关联的告警 ID，可点击跳转到告警详情 | | **事件 ID** | 本次回调的唯一标识，可用于去重 | | **请求状态** | 成功或失败，附带 HTTP 状态码 | | **耗时** | 请求往返耗时 | | **请求次数** | 包括首次请求和重试次数 | ### 查看调用详情 点击某条记录的 **查看详情**，可查看完整的请求和响应信息： * **Request**：包括 Endpoint、Request Headers 和 Request Payload * **Response**：成功时显示 Response Headers 和 Response Body；失败时显示 Error Message ## 五、常见问题 1. **服务是否有响应超时时间？** * 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败 2. **推送失败后是否会持续推送？** 针对特定的网络错误，会进行重试，最多重试1次: * context deadline exceeded (排除 awaiting headers) * i/o timeout * eof 3. **如何保证推送顺序？** * 理论上同一个告警的事件是按照时间顺序进行推送，但是重试等情况可能会导致乱序 * 服务可以根据 event\_time 进行过滤，如果已经收到了更晚的事件，可以直接过滤掉更早的事件，每一次推送都会携带最新的、完整的信息，偶尔丢失事件是可以容忍的 4. **推送来源可信 IP 白名单？**
* `47.94.95.118`、`123.56.8.183`、`47.94.193.81` 和 `1.13.19.96`（SaaS 版本；私有化部署的推送来源为您自有环境的出口地址，请向您的基础设施团队确认） * 未来可能会更新，请定期查验
# Webhook 自定义操作 Source: https://docs.flashduty.com/zh/on-call/integration/webhooks/custom-actions 配置自定义操作，当故障发生特定操作时，系统通过 HTTP 回调您配置的地址 配置故障 自定义操作，允许您在故障排查期间，快速调用外部接口，实现故障自愈、信息丰富等任何自定义操作。 ## 一、创建操作 1. 登录 Flashduty 控制台，进入【集成中心-Webhook】 2. 点击添加 自定义操作 集成 3. 配置 操作名称，此名称将以按钮的形式体现在故障详情中 4. 配置 协作空间，可以配置多个，但每个协作空间至多添加三个 自定义操作 5. 配置 Endpoint、自定义 Headers 6. 保存，完成 ## 二、推送描述 ### 请求方式
POST, Content-Type:"application/json"
### 请求 Payload
| 字段 | 类型 | 必含 | 释义 | | :---------: | :-------------------: | :-: | :----------------------------------- | | event\_time | int64 | 是 | 事件发生`毫秒时间戳` | | event\_type | string | 是 | 事件类型，固定值`i_custom` | | event\_id | string | 是 | 事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重` | | person | [Person](#Person) | 否 | 操作人，仅人为动作时存在 | | incident | [Incident](#Incident) | 是 | 故障详情 | **Person**: | 字段 | 类型 | 必含 | 释义 | | :----------: | :----: | :-: | :---- | | person\_id | int64 | 是 | 人员 ID | | person\_name | string | 是 | 人员名称 | | email | string | 是 | 邮件地址 | **Responder**: | 字段 | 类型 | 必含 | 释义 | | :--------------: | :----: | :-: | :---- | | person\_id | int64 | 是 | 人员 ID | | person\_name | string | 是 | 人员名称 | | email | string | 是 | 邮件地址 | | assigned\_at | int64 | 否 | 分派时间 | | acknowledged\_at | int64 | 否 | 认领时间 | **Incident**: | 字段 | 类型 | 必含 | 释义 | | :----------------: | :------------------------: | :-: | :---------------------------------------------------------------------------------------------------------------------- | | incident\_id | string | 是 | 故障 ID | | title | string | 是 | 故障标题 | | description | string | 否 | 故障描述 | | impact | string | 否 | 故障影响 | | root\_cause | string | 否 | 故障根本原因 | | resolution | string | 否 | 故障解决办法 | | incident\_severity | string | 是 | 严重程度，枚举值：Critical，Warning，Info | | incident\_status | string | 是 | 故障状态，枚举值：Critical，Warning，Info，Ok | | progress | string | 是 | 处理进度，枚举值：Triggered，Processing，Closed | | created\_at | int64 | 是 | 创建时间 | | updated\_at | int64 | 是 | 更新时间 | | start\_time | int64 | 是 | 触发时间，Unix 秒时间戳 | | last\_time | int64 | 否 | 最新事件时间，关联告警中的最新事件推送时间，Unix 秒时间戳，默认为 0 | | end\_time | int64 | 否 | 恢复时间，关联的告警全部恢复时，故障也会自动恢复，Unix 秒时间戳，默认为 0 | | ack\_time | int64 | 否 | 首次认领时间，故障可被多人认领，此时间为最早的认领时间。Unix 秒时间戳，默认为 0 | | close\_time | int64 | 否 | 关闭时间，end\_time代表故障恢复时间，close\_time代表处理进度的关闭时间，故障恢复时会同时关闭，故障关闭时不影响故障恢复。Unix 秒时间戳，默认为 0 | | snoozed\_before | int64 | 否 | 暂缓截止时间 | | labels | map\[string]string | 否 | 标签 KV，Key 和 Value 均为字符串。手动创建时无此信息，自动创建时为聚合的第一条告警的标签信息 | | fields | map\[string]interface | 否 | 自定义字段 KV，Key 为字符串，Value 可能为任意类型，取决于字段类型 | | creator | [Person](#Person) | 否 | 创建人员信息，仅手动创建故障时存在 | | closer | [Person](#Person) | 否 | 关闭人员信息，仅手动关闭故障时存在 | | responders | \[][Responder](#Responder) | 否 | 处理人员信息列表 | | alerts | [Alert](#Alert) | 否 | 关联告警 | | alert\_cnt | int64 | 否 | 关联告警个数 | | num | string | 是 | 故障短标识，取故障 ObjectID 最后 6 位十六进制并大写，例如 `054D57`，在控制台界面中显示。可作为查询故障详情 API 的替代参数（与 `incident_id` 二选一），同一账号下不唯一，查询时返回最新创建的匹配记录 | | channel\_id | int64 | 否 | 协作空间ID，为0代表不属于任何空间 | | channel\_name | string | 否 | 协作空间名称 | | team\_id | int64 | 否 | 协作空间所属团队 ID，无归属团队时为 0 | | detail\_url | string | 是 | 详情地址 | | group\_method | string | 否 | 聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合 | **Alert**: | 字段 | 类型 | 必含 | 释义 | | :--------------: | :----------------: | :-: | :------------------------------------------------------ | | alert\_id | string | 是 | 告警 ID | | data\_source\_id | int64 | 是 | 集成 ID | | title | string | 是 | 告警标题 | | description | string | 否 | 告警描述 | | alert\_key | string | 是 | 告警关联依据 | | alert\_severity | string | 是 | 严重程度，枚举值：Critical，Warning，Info | | alert\_status | string | 是 | 告警状态，枚举值：Critical，Warning，Info，Ok | | progress | string | 是 | 处理进度，枚举值：Triggered，Closed | | created\_at | int64 | 是 | 创建时间 | | updated\_at | int64 | 是 | 更新时间 | | start\_time | int64 | 是 | 首次触发时间（平台接收到的首个事件的时间），Unix 秒时间戳 | | last\_time | int64 | 是 | 最新事件时间（平台接收到的最新事件时间），Unix 秒时间戳 | | end\_time | int64 | 否 | 告警恢复时间（平台上一次接收到结束类型事件的时间），Unix 秒时间戳，默认为 0 | | close\_time | int64 | 否 | 关闭时间，不同于 end\_time，这个是处理进度的关闭，不代表告警真的恢复。Unix 秒时间戳，默认为 0 | | labels | map\[string]string | 否 | 标签 KV，Key 和 Value 均为字符串 |
### 请求响应 HTTP status code 为 200，认为推送成功。 ### 请求示例 ``` curl -X POST 'https://example.com/incident/action?a=a' \ -H 'Content-Type: application/json' \ -H 'X-Customize-Header-A: a' \ -d '{ "event_time": 1700208013988, "event_type": "i_custom", "incident": { "event_id":"fac0599a2a25529ba2362c0c184b6cfb", "account_id": 74058170041504, "account_name": "头铁科技", "ack_time": 0, "alert_cnt": 1, "alerts": [ { "account_id": 74058170041504, "alert_id": "6551f37f8713372ad1054d54", "alert_key": "asdflasdfl2xzasd112621", "alert_severity": "Critical", "alert_status": "Critical", "close_time": 0, "created_at": 1699869567, "data_source_id": 2398086111504, "description": "cpu.idle < 20%", "end_time": 0, "event_cnt": 0, "labels": { "a": "a", "check": "自定义字段测试", "cluster": "nj", "metric": "node_cpu_seconds_total", "resource": "es.nj.01", "service": "engine", "v": "v" }, "last_time": 1699869562, "progress": "Triggered", "responder_email": "", "responder_id": 0, "responder_name": "", "start_time": 1699869562, "title": "nj / es.nj.01 - 自定义字段测试", "title_rule": "$cluster::$resource::$check", "updated_at": 1699869576 } ], "assigned_to": { "assigned_at": 1699869576, "escalate_rule_id": "6509344bc1d50d723ca04986", "escalate_rule_name": "策略5", "id": "VobpBqvTuXgQ7BZzJ2Qu94", "layer_idx": 0, "type": "assign" }, "channel_id": 1973372625504, "channel_name": "lim_test", "close_time": 0, "created_at": 1699869576, "data_source_id": 2398086111504, "dedup_key": "asdflasdfl2xzasd112621", "description": "cpu.idle < 20%", "detail_url": "http://10.206.0.17:8567/incident/detail/6551f3888713372ad1054d57", "end_time": 0, "equals_md5": "", "fields": { "impacted_services": [ "passport", "order" ], "priority": "P3" }, "group_method": "p", "impact": "", "incident_id": "6551f3888713372ad1054d57", "incident_severity": "Critical", "incident_status": "Critical", "labels": { "a": "a", "check": "自定义字段测试", "cluster": "nj", "metric": "node_cpu_seconds_total", "resource": "es.nj.01", "service": "engine", "v": "v" }, "creator":{ "email":"toutie@flashcat.cloud", "person_id":1552048792504, "person_name":"头铁" }, "last_time": 1699869562, "num": "054D57", "progress": "Triggered", "resolution": "", "responders": [ { "acknowledged_at": 0, "assigned_at": 1699869576, "email": "zhangsan@toutie.com", "person_id": 1234648032504, "person_name": "zhangsan" } ], "root_cause": "", "snoozed_before": 0, "start_time": 1699869562, "title": "nj / es.nj.01 - 自定义字段测试", "updated_at": 1699929113 }, "person": { "email": "zhangsan@toutie.com", "person_id": 1999632289504, "person_name": "zhangsan" } }' -v ``` ## 三、自定义请求体与值映射 ### 自定义请求体 默认情况下，系统会按照上述 [Payload 结构](#请求-payload)推送完整的 JSON 数据。如果您的接收方对数据格式有特殊要求，可以通过**自定义请求体**来重新组织推送内容。 使用 `{{字段路径}}` 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。 **变量语法：** * 用 `.` 分隔路径层级，如 `{{incident.title}}` 引用故障标题 * 支持数组索引访问，如 `{{incident.responders.0.email}}` 引用第一个处理人的邮箱 * 当整个值只有一个变量时（如 `"{{incident.labels}}"`），会保留原始数据类型（对象、数组、数字等） * 当变量与其他文本混合时（如 `"故障：{{incident.title}}"`），变量会被转为字符串拼接 **示例：** ```json theme={null} { "action": "{{event_type}}", "incident_id": "{{incident.incident_id}}", "title": "{{incident.title}}", "severity": "{{incident.incident_severity}}", "url": "{{incident.detail_url}}", "operator": "{{person.person_name}}", "labels": "{{incident.labels}}" } ``` 如果变量路径在默认 Payload 中不存在，系统会保留原始的 `{{...}}` 文本不做替换。建议先通过测试推送查看实际的默认 Payload，确认可用的字段路径。 ### 值映射 通过值映射，可以在自定义请求体的变量解析时自动转换字段值。值映射按**字段路径**分组配置。 **示例：** ```json theme={null} { "incident.incident_severity": { "Critical": "P0", "Warning": "P1", "Info": "P2" } } ``` 配合自定义请求体中的 `"severity": "{{incident.incident_severity}}"` 使用，当故障严重程度为 `Critical` 时，推送结果中 `severity` 字段的值为 `P0`。未匹配到映射的值将保持原样。 ## 四、使用场景 ### 重启主机 当主机内存或CPU打满，触发主机重启脚本，快速完成主机重启。 ### 信息丰富 当故障发生时，回调您的服务，根据告警详情调取 Tracing、Logging、拓扑等信息，主动调用 Flashduty Open API 来更新故障信息，比如增加标签或设定自定义字段，辅助排障。 ### 回滚变更 当发生故障时，如果确定故障由变更导致，可以直接触发回调到您的部署平台，开启回滚进程，加速故障恢复。 ### 更新 status page 当确定故障影响到线上服务，可以触发外部 status page 更新，及时的通知到您的客户或上下游。 ## 五、常见问题 1. **服务是否有响应超时时间？** * 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败 2. **推送失败后是否会持续推送？** 针对特定的网络错误，会进行重试，最多重试1次: * context deadline exceeded (排除 awaiting headers) * i/o timeout * eof 2. **推送来源可信 IP 白名单？**
* `47.94.95.118`、`123.56.8.183`、`47.94.193.81` 和 `1.13.19.96`（SaaS 版本；私有化部署的推送来源为您自有环境的出口地址，请向您的基础设施团队确认） * 未来可能会更新，请定期查验
# 故障 Webhook Source: https://docs.flashduty.com/zh/on-call/integration/webhooks/incident-webhook 配置故障 Webhook，当故障发生特定操作时，系统通过 HTTP 回调您配置的地址 配置故障 Webhook，当故障发生特定操作（如触发、关闭）时，系统通过 HTTP 回调您配置的地址。回调内容将包含故障最新关键信息，您可以与自研工具进行集成。 ## 一、事件类型 目前支持以下事件类型，未来可能会增加。
| 事件类型 | 释义 | | :------------: | :------------ | | i\_new | 创建故障（自动或手动创建） | | i\_assign | 分派故障（自动或手动分派） | | i\_a\_rspd | 添加处理人 | | i\_snooze | 手动暂缓故障 | | i\_wake | 取消暂缓故障 | | i\_ack | 手动认领故障 | | i\_unack | 取消认领故障 | | i\_storm | 触发风暴提醒 | | i\_custom | 触发自定义操作 | | i\_rslv | 关闭故障（自动或手动关闭） | | i\_reopen | 重新打开故障 | | i\_merge | 手动合并故障 | | i\_comm | 添加评论 | | i\_r\_title | 更新故障标题 | | i\_r\_desc | 更新故障描述 | | i\_r\_impact | 更新故障影响 | | i\_r\_rc | 更新故障根因 | | i\_r\_rsltn | 更新故障解决办法 | | i\_r\_severity | 更新故障严重程度 | | i\_r\_field | 更新故障自定义字段 |
## 二、推送描述 ### 请求方式
POST, Content-Type:"application/json"
### 请求 Payload
| 字段 | 类型 | 必含 | 释义 | | :---------: | :-------------------: | :-: | :----------------------------------- | | event\_time | int64 | 是 | 事件发生`毫秒时间戳` | | event\_type | string | 是 | 事件类型，枚举值见[事件类型](#EventTypes) | | event\_id | string | 是 | 事件 ID，`同一个事件可能因为超时等原因重试多次，接收方需要能够去重` | | person | [Person](#Person) | 否 | 操作人，仅人为动作时存在 | | incident | [Incident](#Incident) | 是 | 故障详情 | **Person**: | 字段 | 类型 | 必含 | 释义 | | :----------: | :----: | :-: | :---- | | person\_id | int64 | 是 | 人员 ID | | person\_name | string | 是 | 人员名称 | | email | string | 是 | 邮件地址 | **Responder**: | 字段 | 类型 | 必含 | 释义 | | :--------------: | :----: | :-: | :---- | | person\_id | int64 | 是 | 人员 ID | | person\_name | string | 是 | 人员名称 | | email | string | 是 | 邮件地址 | | assigned\_at | int64 | 否 | 分派时间 | | acknowledged\_at | int64 | 否 | 认领时间 | **Incident**: | 字段 | 类型 | 必含 | 释义 | | :----------------: | :------------------------: | :-: | :---------------------------------------------------------------------------------------------------------------------- | | incident\_id | string | 是 | 故障 ID | | title | string | 是 | 故障标题 | | description | string | 否 | 故障描述 | | impact | string | 否 | 故障影响 | | root\_cause | string | 否 | 故障根本原因 | | resolution | string | 否 | 故障解决办法 | | incident\_severity | string | 是 | 严重程度，枚举值：Critical，Warning，Info | | incident\_status | string | 是 | 故障状态，枚举值：Critical，Warning，Info，Ok | | progress | string | 是 | 处理进度，枚举值：Triggered，Processing，Closed | | created\_at | int64 | 是 | 创建时间 | | updated\_at | int64 | 是 | 更新时间 | | start\_time | int64 | 是 | 触发时间，Unix 秒时间戳 | | last\_time | int64 | 否 | 最新事件时间，关联告警中的最新事件推送时间，Unix 秒时间戳，默认为 0 | | end\_time | int64 | 否 | 恢复时间，关联的告警全部恢复时，故障也会自动恢复，Unix 秒时间戳，默认为 0 | | ack\_time | int64 | 否 | 首次认领时间，故障可被多人认领，此时间为最早的认领时间。Unix 秒时间戳，默认为 0 | | close\_time | int64 | 否 | 关闭时间，end\_time代表故障恢复时间，close\_time代表处理进度的关闭时间，故障恢复时会同时关闭，故障关闭时不影响故障恢复。Unix 秒时间戳，默认为 0 | | snoozed\_before | int64 | 否 | 暂缓截止时间 | | labels | map\[string]string | 否 | 标签 KV，Key 和 Value 均为字符串。手动创建时无此信息，自动创建时为聚合的第一条告警的标签信息 | | fields | map\[string]interface | 否 | 自定义字段 KV，Key 为字符串，Value 可能为任意类型，取决于字段类型 | | creator | [Person](#Person) | 否 | 创建人员信息，仅手动创建故障时存在 | | closer | [Person](#Person) | 否 | 关闭人员信息，仅手动关闭故障时存在 | | responders | \[][Responder](#Responder) | 否 | 处理人员信息列表，仅故障被分派后存在。对于i\_new事件，此值可能为空 | | alert\_cnt | int64 | 否 | 关联告警个数 | | num | string | 是 | 故障短标识，取故障 ObjectID 最后 6 位十六进制并大写，例如 `56E25B`，在控制台界面中显示。可作为查询故障详情 API 的替代参数（与 `incident_id` 二选一），同一账号下不唯一，查询时返回最新创建的匹配记录 | | channel\_id | int64 | 否 | 协作空间ID，为0代表不属于任何空间 | | channel\_name | string | 否 | 协作空间名称 | | team\_id | int64 | 否 | 协作空间所属团队 ID，无归属团队时为 0 | | detail\_url | string | 是 | 详情地址 | | group\_method | string | 否 | 聚合方式，枚举值：n：不聚合，p：按规则聚合，i：智能聚合 |
### 请求响应 HTTP status code 为 200，认为推送成功。 ### 请求示例 ``` curl -X POST 'https://example.com/incident/webhook?a=a' \ -H 'Content-Type: application/json' \ -H 'X-Customize-Header-A: a' \ -d '{ "event_id":"fac0599a2a25529ba2362c0c184b6cfb", "event_time":1689335086948, "event_type":"i_new", "incident":{ "account_id":74058170041504, "account_name":"头铁科技kk", "ack_time":0, "alert_cnt":0, "assigned_to":{ "assigned_at":1689335086, "escalate_rule_id":"64abb8a687e7984845822139", "escalate_rule_name":"默认分派", "id":"NBRbNwDSTSMijKXdLtBU3T", "layer_idx":0, "type":"assign" }, "channel_id":1840312623504, "channel_name":"Reduce Noise", "close_time":0, "created_at":1689335086, "creator":{ "email":"toutie@flashcat.cloud", "person_id":1552048792504, "person_name":"头铁" }, "creator_id":1552048792504, "data_source_id":0, "dedup_key":"", "description":"", "detail_url":"http://10.206.0.17:8567/incident/detail/64b1352e376e32c85c56e25b", "end_time":0, "equals_md5":"", "group_method":"n", "impact":"", "incident_id":"64b1352e376e32c85c56e25b", "incident_severity":"Critical", "incident_status":"Critical", "labels":{ "check": "cpu idle low" }, "last_time":1689335086, "num":"56E25B", "progress":"Triggered", "resolution":"", "responder_ids":[ 1552048792504 ], "responders":[ { "acknowledged_at":0, "assigned_at":1689335086, "email":"toutie@flashcat.cloud", "person_id":1552048792504, "person_name":"头铁" } ], "root_cause":"", "snoozed_before":0, "start_time":1689335086, "title":"ysy028", "updated_at":1689335086 }, "person":{ "email":"toutie@flashcat.cloud", "person_id":1552048792504, "person_name":"头铁" } }' -v ``` ## 三、配置指南 进入 **集成中心** → **Webhook** → 添加或编辑 **故障 Webhook** 集成。 ### 基础设置 填写集成名称和描述，便于后续管理。 ### Webhook 设置 | 配置项 | 说明 | | :----------- | :---------------------------------------------------- | | **Endpoint** | 接收回调的 HTTP/HTTPS 地址，必须以 `http://` 或 `https://` 开头 | | **TLS 验证** | 默认启用。关闭后将跳过目标服务器的 TLS 证书验证，适用于测试环境或自签名证书场景 | | **Headers** | 自定义请求头，以 Key-Value 形式添加，支持添加多个 | | **协作空间** | 选择 **全部空间** 或 **部分空间**。选择部分空间时，仅该空间下的故障事件会触发回调 | | **事件类型** | 勾选需要订阅的事件类型（参见[事件类型](#EventTypes)），支持全选。仅选中的事件类型会触发回调 | 关闭 TLS 证书验证可能存在中间人攻击风险，建议仅在测试环境或使用自签名证书时关闭。 ### 自定义请求体 默认情况下，系统会按照上述 [Payload 结构](#请求-payload)推送完整的 JSON 数据。如果你的接收方对数据格式有特殊要求，可以通过**自定义请求体**来重新组织推送内容。 使用 `{{字段路径}}` 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。 **变量语法：** * 用 `.` 分隔路径层级，如 `{{incident.title}}` 引用故障标题 * 支持数组索引访问，如 `{{incident.responders.0.email}}` 引用第一个处理人的邮箱 * 当整个值只有一个变量时（如 `"{{incident.labels}}"`），会保留原始数据类型（对象、数组、数字等） * 当变量与其他文本混合时（如 `"故障：{{incident.title}}"`），变量会被转为字符串拼接 **示例：** 将默认 Payload 转为自定义格式推送到企业内部系统： ```json theme={null} { "msg_type": "incident", "event": "{{event_type}}", "content": { "id": "{{incident.incident_id}}", "name": "{{incident.title}}", "severity": "{{incident.incident_severity}}", "status": "{{incident.progress}}", "channel": "{{incident.channel_name}}", "url": "{{incident.detail_url}}", "labels": "{{incident.labels}}", "responders": "{{incident.responders}}" } } ``` 如果变量路径在默认 Payload 中不存在，系统会保留原始的 `{{...}}` 文本不做替换。建议先通过调用历史查看实际推送的默认 Payload，确认可用的字段路径。 ### 值映射 在自定义请求体中，您可能需要将 Flashduty 的字段值转换为接收方系统所期望的格式。通过 **值映射** 可以在变量解析时自动完成值的转换。 值映射按**字段路径**分组配置，每个路径下是一个 `源值 → 目标值` 的映射表。 **示例：** 将严重程度和处理进度转换为接收方系统的自定义值： ```json theme={null} { "incident.incident_severity": { "Critical": "P0", "Warning": "P1", "Info": "P2" }, "incident.progress": { "Triggered": "open", "Processing": "in_progress", "Closed": "resolved" } } ``` 配合如下自定义请求体使用： ```json theme={null} { "severity": "{{incident.incident_severity}}", "status": "{{incident.progress}}", "title": "{{incident.title}}" } ``` 当故障严重程度为 `Critical` 时，推送结果中 `severity` 字段的值为 `P0`。未匹配到映射的值将保持原样。 ## 四、调用历史 故障 Webhook 提供完整的调用历史记录，方便你排查推送是否成功以及调试回调接口。 ### 查看调用历史 进入故障 Webhook 集成详情页，切换到 **调用历史** 页签即可查看。 ### 筛选与搜索 | 筛选项 | 说明 | | :-------- | :----------------------------------------------- | | **时间范围** | 支持选择最近 1 小时、6 小时、1 天、7 天，或自定义时间范围（最多查看最近 7 天的数据） | | **故障 ID** | 输入故障 ID 进行精确搜索 | | **事件类型** | 按事件类型筛选记录 | | **请求状态** | 按成功或失败筛选 | ### 历史记录字段 | 字段 | 说明 | | :-------- | :--------------------------- | | **触发时间** | 事件触发的时间 | | **事件类型** | 触发的事件类型（如 `i_new`、`i_ack` 等） | | **故障 ID** | 关联的故障 ID，可点击跳转到故障详情 | | **事件 ID** | 本次回调的唯一标识，可用于去重 | | **请求状态** | 成功或失败，附带 HTTP 状态码 | | **耗时** | 请求往返耗时 | | **请求次数** | 包括首次请求和重试次数 | ### 查看调用详情 点击某条记录的 **查看详情**，可查看完整的请求和响应信息： * **Request**：包括 Endpoint、Request Headers 和 Request Payload * **Response**：成功时显示 Response Headers 和 Response Body；失败时显示 Error Message ## 五、常见问题 1. **服务是否有响应超时时间？** * 服务需要在 2 秒内返回响应，超过 2 秒则认为响应失败 2. **推送失败后是否会持续推送？** 针对特定的网络错误，会进行重试，最多重试1次: * context deadline exceeded (排除 awaiting headers) * i/o timeout * eof 3. **如何保证推送顺序？** * 理论上同一个故障的事件是按照时间顺序进行推送，但是重试等情况可能会导致乱序 * 服务可以根据 event\_time 进行过滤，如果已经收到了更晚的事件，可以直接过滤掉更早的事件，每一次推送都会携带最新的、完整的信息，偶尔丢失事件是可以容忍的 4. **推送来源可信 IP 白名单？**
* `47.94.95.118`、`123.56.8.183`、`47.94.193.81` 和 `1.13.19.96`（SaaS 版本；私有化部署的推送来源为您自有环境的出口地址，请向您的基础设施团队确认） * 未来可能会更新，请定期查验
# Jira 同步 Source: https://docs.flashduty.com/zh/on-call/integration/webhooks/jira-sync 通过 Jira 同步 Webhook，实现故障与 Jira Issue 的关联。 **版本要求**：此功能需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 通过 Jira 同步 Webhook，将 Flashduty 的故障与 Jira Issue 进行关联同步，实现 Flashduty 与 Jira 的联动。 ## 前提说明 * 该集成兼容 Jira Cloud 以及 Jira Server 和 Jira Data Center 的 7.x 和 8.x 版本。 * 目前仅支持将故障相关信息或状态单向同步到 Jira 中，Jira 中的信息不会同步到 Flashduty 中。 * 对于 Jira Cloud，请在授权配置的密码处填写 API Token；而对于Jira Server 或 Data Center，则使用您的 Jira 账户登录密码即可。 ## 在 Jira Cloud 中获取 API Token （Jira Server 和 Data Center 请跳过） * 登录 Jira Cloud 后，点击右上角头像，选择 **管理账户**。 * 在 **管理账户** 页面中，选择 **安全性** 选项卡。 * 在 **安全性** 页面中，点击 **创建并管理 API 令牌** 按钮。 * 在 **创建并管理 API 令牌** 弹窗中，填写 API token 名称，并选择过期时间。 * 点击 **创建** 按钮，创建 API token。 * 创建完成后，复制 API token 值，并粘贴到 Flashduty 授权配置中的 API 令牌处。 ## 在 Flashduty On-call 中配置集成 ### 1. 创建并认证 Jira 集成
在集成中心，选择 **Webhook** ，选择 **Jira 同步** 集成，并填写以下认证信息。
* **Jira 平台类型**：根据您使用的版本进行选择，如果是 Data Center 版本的请选择私有化（Server） 即可。 * **服务地址**：Cloud 版本请填写您的实际访问地址，例如： [https://your-domain.atlassian.net，Server](https://your-domain.atlassian.net，Server) 版本请填写您的服务访问地址，例如： [https://your-jira-server-url.com。](https://your-jira-server-url.com。) * **用户名**：您的 Jira 账户名，Cloud 版本请填写您的邮箱，Server 版本请填写您的 Jira 账户名。 * **API令牌/密码**：您的 Jira 账户密码，Cloud 版本请填写 API Token，Server 版本请填写您的 Jira 账户密码。 * 填写完成后，点击 **下一步** 按钮，进行相关配置。 **关于权限**：请确保您的 Jira 账户拥有获取相关项目、事务类型以及创建 Issue 等权限，建议使用管理员账户。 ### 2. Jira 集成配置 * **集成名称**：为当前集成定义一个名称。 * **管理团队**：选择管理该集成的团队，只有团队成员可以编辑此集成配置。 * **触发模式**： * 自动触发：需要配置相应的条件，Flashduty On-call 会自动将符合条件的故障同步到 Jira 中。 * 手动触发：需要在故障详情页的更多操作中手动触发 Jira 同步（该集成配置的名称为触发器名称）。 * **项目 ID**：选择需要同步至 Jira 的项目。 * **事务类型**：选择需要同步至 Jira 的事务类型。 * **协作空间**：选择该集成生效的协作空间，只有该协作空间内的故障才可以同步至 Jira 中。 * **严重程度映射**：如果选择的事务类型不支持优先级字段，则无法配置该映射关系。 * **自定义字段映射**：可以选择将故障的某些标签或所有标签以及自定义字段内容同步至 Jira 的字段中（仅支持文本类型的字段）。 ### 3. 关于更新 * 已经创建 Issue 的故障，如果您更新了故障的严重程度、状态，Jira 中会自动更新，但 Jira 中的更新不会同步到 Flashduty 中。 * 评论信息会同步到 Jira 中，但 Jira 中更新的内容不会同步到 Flashduty 中。 * 更新故障中的标题、描述、标签等字段的信息，Jira 中不会更新。 ### 4. Flashduty 与 Jira 的映射关系 #### 字段映射 | Jira | Flashduty | | ---- | --------- | | 摘要 | 标题 | | 描述 | 描述 | | 优先级 | 严重程度 | | 报告人 | 集成配置的用户 | | 评论 | 评论 | #### 状态映射 | Jira | Flashduty | | ----------- | --------- | | Todo | 待处理 | | In Progress | 处理中 | | Done | 已解决 | ### 5. 注意事项 * Flashduty On-call 会按照默认的字段映射以及您配置的自定义字段映射进行同步信息，如果您的 Jira 事务类型中有必选的字段且没有配置映射关系，则会遇到创建 Jira Issue 失败的情况。 * Jira 的 Issue 详情是基于项目 KEY + 编号的格式进行访问的，如果您修改了项目 KEY，可能无法通过 Flashduty 中保存的 Issue 地址进行访问，请谨慎修改项目 KEY。 # ServiceDesk Plus 同步 Source: https://docs.flashduty.com/zh/on-call/integration/webhooks/servicedesk-plus-sync 通过 ServiceDesk Plus 同步 Webhook，实现故障与 ServiceDesk Plus request 的关联。 **版本要求**：此功能需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 通过 ServiceDesk Plus 同步 Webhook，将 Flashduty 的故障与 ServiceDesk Plus request 进行关联同步，实现 Flashduty 与 ServiceDesk Plus 的联动。 本集成基于 ServiceDesk Plus 官方提供的 v3 API 协议，兼容其接口规范。若您使用私有化部署版本，请确认其 API 是否支持 v3 版本。此外，ServiceDesk Plus 的云版本与私有化版本在授权配置方式上存在差异，具体配置请参考相关文档说明。 * [云版本](#云版本) * [私有化](#私有化) 在配置此集成时，如果您选择的同步方向是 From\_ServiceDesk\_Plus，您可以直接跳过授权相关配置，直接参考[配置同步](#配置同步)即可。 ## 云版本 ### 在 ServiceDesk Plus #### 步骤1 创建授权应用 请根据您的 ServiceDesk Plus 服务区域选择对应的 Developer Console 地址：[Data Centres](https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html) 1. 登录 Developer Console，选择 `Self Client` 类型的 Client 并创建。 2. 点击 `Generate Code`，在 `Scope` 中填写：**SDPOnDemand.requests.ALL,SDPOnDemand.setup.READ,SDPOnDemand.custommodule.READ**。权限范围参考[官方文档](https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/oauth-2.0.html#scopes)。 3. `Time Duration` 选择最大的 **10 minutes**，`Scope Description` 填写内容可自定义，比如： Flashduty 同步使用，并创建。 4. 将生成的 **Code** 和 **Client ID** 以及 **Client Secret** 复制备用。 ![2025-09-24-14-59-28](https://docs-cdn.flashcat.cloud/images/png/793fa15bd6e919e81fd3baaaab591275.png) ![2025-09-24-15-00-56](https://docs-cdn.flashcat.cloud/images/png/3b1b9d7a9c4bcc93ddf4cd73e47713f5.png) ###### 注意：Code 的有效期只有 10 分钟且只能使用一次，所以在获取到 Code 后，请在有效期内尽快完成[集成授权](#集成授权) ### 在 Flashduty On-call #### 步骤2 集成授权 请根据您的 ServiceDesk Plus 服务区域选择对应的 API Endpoint 和 Accounts Server URL：[Data Centres](https://www.manageengine.com/products/service-desk/sdpod-v3-api/getting-started/data-centers.html) 1. `平台类型` 选择**云版本**，填写`API Endpoint` 和 `Accounts Server URL`。 2. 将**创建授权应用**步骤中生成的 `Code` 和 `Client ID` 以及 `Client Secret` 填写到对应的编辑框并点击下一步完成[集成配置](#集成配置)（如果报错请重新获取 Code，或联系技术支持排查问题）。 ## 私有化版本 ### 在 ServiceDesk Plus #### 步骤1 生成 API 密钥 1. 登录 ServiceDesk Plus 控制台，在个人中心点击 `生成 API 密钥`。 2. `令牌过期时间` 选择 **永不过期**，将生成的 **Token** 复制备用，并完成[集成授权](#私有化版本集成授权)。 ###### 注意：生成 API 密钥的用户需要具备相关权限，比如创建/更新请求、获取模版/优先级/自定义字段列表等权限，如果权限不足，会导致无法完成集成配置，建议使用管理员角色生成。 ### 在 Flashduty On-call #### 步骤2 集成授权 1. `平台类型` 选择**私有化版本**，填写`API Endpoint`。 2. 将生成的 **Token** 填写到对应的编辑框并点击下一步完成[集成配置](#集成配置)。 ## 通用配置 ### 在 Flashduty On-call #### 步骤1 集成配置 1. **集成名称：** 为当前集成定义一个名称。 2. **管理团队：** 当选择管理团队后，只有该团队成员以及租户管理员可以编辑此集成。 3. **同步方向：** * To\_ServiceDesk\_Plus：将 Flashduty 的故障同步至 ServiceDesk Plus。 * From\_ServiceDesk\_Plus：将 ServiceDesk Plus 的 Request 同步至 Flashduty。 * Two-way：Flashduty 和 ServiceDesk Plus 互相同步。 4. **触发模式**： * 自动触发：需要配置相应的条件，Flashduty On-call 会自动将符合条件的故障同步到 ServiceDesk Plus 中。 * 手动触发：需要在故障详情页的更多操作中手动触发 ServiceDesk Plus 同步（该集成配置的名称为触发器名称）。 5. **协作空间**：选择该集成生效的协作空间。 6. **请求模版**：选择创建 request 时使用的模版，为空时使用默认模版创建工单。 7. **严重程度映射**：可以选择使用严重程度、故障标签、自定义字段的值与 ServiceDesk Plus 的优先级字段进行映射，如果为空，在创建工单时不传该字段。 8. **自定义字段映射**：可以将故障中的标签或自定义字段，映射到 ServiceDesk Plus 工单中的对应文本字段，实现信息自动填充。该功能支持将常见上下文信息（如服务名、实例地址、指标名称等）同步至 ServiceDesk Plus，便于后续排查与跟踪。 * 仅支持目标为单行文本或多行文本类型的字段。 * 支持从故障标签（如 service、instance）或自定义属性中提取值。 * 若源字段为空，目标字段也将保持为空，不会覆盖原有内容。 9. **指派对象映射**：当 Flashduty 的故障同步至 ServiceDesk Plus 并需要自动指派到 Technician 或 Group 时，可以获取 Flashduty 故障标签的值作为指派对象（如果对应的指派对象不存在，会导致同步失败，请谨慎选择）。 10. **请求者**：创建工单时指定的 requester，如果工单在创建时该字段是必须，则需要配置。 11. 点击`保存`完成配置。 ### 在 ServiceDesk Plus #### 步骤2 配置同步 要实现 ServiceDesk Plus 的 Request 向 Flashduty 的同步，请参考此配置项。**注意:** 不同版本的路径可能略有不同，但配置方法相同。 ##### 创建 Webhook 1. 登录 ServiceDesk Plus 控制台，找到 `Setup` 配置页面。 2. 选择 `Automation` 之后，进入到 `Custom Actions` 页面，并选择 `Webhooks`。 3. 点击 `New Webhook`，在编辑页面中 `Webhook Name` 填写 **to\_Flashduty**。 4. `URL` 填写集成的推送地址。 5. `Applies to` 选择 **Requsts**，`Method` 选择 **POST**，`Headers` 中填写 **Content-Type application/json**。 6. `Message Body` 的 Type 选择 **JSON**，并填写以下内容： ``` # 云版本 { "subject":"${subject}", "request_id":"${id}", "description":"${udf_fields.txt_destination}", "priority":"${priority.name}", "status":"${status.name}", "txt_test_field":"${udf_fields.txt_test_field}" } ``` ``` # 私有化版本 { "suject":"${{request.subject}}", "request_id":"${{request.id}}", "description":"${{request.description}}", "status":"${{request.status.name}}", "priority":"${{request.priority.name}}", "udf_sline_301":"${{request.udf_fields.udf_sline_301}}" } ``` 7. 点击 `Save` 完成配置。 ![2025-09-23-13-32-32](https://docs-cdn.flashcat.cloud/images/png/94ca1d094ed38ebcaf299364eddfd0ac.png) ##### 步骤3 创建触发器 1. 登录 ServiceDesk Plus 控制台，找到 `Setup` 配置页面。 2. 选择 `Automation` 之后，进入到 `Triggers` 页面，并选择 `Request`。 3. 点击 `New Trigger`，在编辑页面中 `Name` 填写 **to\_Flashduty**。 4. `Trigger applies to` 选择 **Request**，`Execute when a request is` 勾选 **Create 和 Edited**。 5. `Execute during` 选择 **Any time**，并勾选 **Enable Trigger**。 6. `Conditions` 选择 `Without condition` 或按实际需求配置。 7. 在 `Actions` 中选择 **Webhook** 并勾选 **to\_Flashduty** 通道。 8. 点击 `Save` 完成配置。 ![2025-09-23-13-42-20](https://docs-cdn.flashcat.cloud/images/png/9573d79763af656e0e08c5bdc3649a14.png) ## 同步信息映射关系 ### 表单字段 | ServiceDesk Plus | Flashduty | 备注 | | ---------------- | ------------- | ----- | | Subject | Title | 标题 | | Description | Description | 描述信息 | | Status | Progress | 状态 | | Priority | Severity | 严重程度 | | Others | Custom Fields | 自定义字段 | ### 状态映射 | ServiceDesk Plus | Flashduty | 备注 | | -------------------- | ---------- | --------- | | Open | Triggered | 触发 | | In Progress | Processing | 待处理 | | Assigned | Processing | 待处理 | | Pending Verification | Processing | 待处理 | | Staging | Processing | 待处理 | | On Hold | Snoozed | 默认暂缓 2 小时 | | Resolved | Closed | 关闭 | | Closed | Closed | 关闭 | | Canceled | Closed | 关闭 | | Rejected | Closed | 关闭 | ## 调用历史 ServiceDesk Plus 同步集成提供完整的调用历史记录，方便你排查同步是否成功以及调试接口问题。 ### 查看调用历史 进入 ServiceDesk Plus 同步集成详情页，切换到 **调用历史** 页签即可查看。 ### 筛选与搜索 | 筛选项 | 说明 | | :-------- | :----------------------------------------------- | | **时间范围** | 支持选择最近 30 分钟、6 小时、1 天、2 天、7 天、14 天、30 天，或自定义时间范围 | | **故障 ID** | 输入故障 ID 进行精确搜索 | | **协作空间** | 按协作空间筛选记录 | | **请求状态** | 按成功或失败筛选 | ### 历史记录字段 | 字段 | 说明 | | :------------- | :---------------------------------------------------- | | **触发时间** | 事件触发的时间 | | **故障标题** | 关联的故障标题，可点击跳转到故障详情 | | **Request ID** | ServiceDesk Plus 工单 ID，可点击跳转到 ServiceDesk Plus 查看工单详情 | | **协作空间** | 关联的协作空间，可点击跳转 | | **请求状态** | 成功或失败 | ### 查看调用详情 点击某条记录的 **查看详情**，可查看完整的请求信息： * **故障 ID**：关联的故障 ID * **协作空间**：关联的协作空间 * **故障标题**：可点击跳转到故障详情页 * **触发时间**：请求触发的时间 * **请求状态**：成功或失败 * **Error Message**：失败时显示错误信息 ## 常见问题
Scope 是否可以更改 不可以，目前所使用的 Scope 已经是最小单元了，Flashduty 在与 ServiceDesc Plus 进行同步 request 时，需要做获取/创建/更新操作，以及在配置集成时，需要获取优先级/自定义字段列表，所以需要相应的权限支持。
# ServiceNow 同步 Source: https://docs.flashduty.com/zh/on-call/integration/webhooks/servicenow-sync 通过 ServiceNow 同步 Webhook，实现故障与 ServiceNow Incident 的关联。 **版本要求**：此功能需要 On-call 专业版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/) 通过 ServiceNow 同步 Webhook，将 Flashduty 的故障与 ServiceNow Incident 进行关联同步，实现 Flashduty 与 ServiceNow 的联动。 ## 在 ServiceNow ### 创建用户 需创建一个用户以连接 ServiceNow 实例，用于 Incident 的同步与更新。如果已有可用用户，请直接跳过本步骤。 1. 登录 ServiceNow 实例控制台，通过选择 `ALL` ，输入 `USERS` 选择`Organization`-`Users` 。 2. 点击 `New` 新建用户。 3. 在编辑页面中，`User ID` 输入：flashduty 。 4. `Password needs reset` 和 `Web service access only` 以及 `Internal Integration User` 保持取消勾选状态。 5. 提交保存。 ![2025-09-24-16-19-47](https://docs-cdn.flashcat.cloud/images/png/3db86d07758819d61f4e7d2fc714347b.png) ### 配置用户 > **用户角色说明** > **itil：** 该角色在 Flashduty 中的主要使用范围仅限于在同步 ServiceNow Incident 时，进行获取、创建、更新 ServiceNow Incident，不涉及其他任何操作。 > > **personalize\_dictionary：** 该角色在 Flashduty 中的主要使用范围仅限于 ServiceNow Incident Table 的字段获取，不涉及其他任何操作。 > > 关于以上两个角色更多权限范围，可以参考 ServiceNow [官方文档](https://www.servicenow.com/docs/bundle/washingtondc-platform-administration/page/administer/roles/reference/r_BaseSystemRoles.html#d130465e3182) 1. 在用户列表页面，找到新创建的 `flashduty` 用户并进到配置页面。 2. 在编辑页面中，点击 `Set Password` 设置一个密码。 3. 点击 `Roles` 添加 **personalize\_dictionary 和 itil** 角色（如果不需要配置自定义字段映射关系，可以不授予 personalize\_dictionary 权限）。 4. 点击 `Update` 更新配置。 ![2025-09-24-16-29-05](https://docs-cdn.flashcat.cloud/images/png/a4416dff926e89b505224e03a4f774c6.png) ![2025-09-24-16-29-58](https://docs-cdn.flashcat.cloud/images/png/19371c16f4c516c095752f2a8e0d45bf.png) ## 在 Flashduty On-call ### 配置集成 将以上配置的用户名/密码以及实例名称输入到左侧集成信息中并点击下一步进行配置。 1. **集成名称：** 为当前集成定义一个名称。 2. **管理团队：** 当选择管理团队后，只有该团队成员以及租户管理员可以编辑此集成。 3. **协作空间**：选择该集成生效的协作空间，。 4. **同步方向：** * To\_ServiceNow：将 Flashduty 的故障同步至 ServiceNow。 * From\_ServiceNow：将 ServiceNow 的 Incident 同步至 Flashduty。 * Two-way：Flashduty 和 ServiceNow 互相同步。 5. **触发模式**： * 自动触发：需要配置相应的条件，Flashduty On-call 会自动将符合条件的故障同步到 ServiceNow 中。 * 手动触发：需要在故障详情页的更多操作中手动触发 ServiceNow 同步（该集成配置的名称为触发器名称）。 6. **严重程度映射**： * ServiceNow 的 Priority 是由 Impact 和 Urgency 的值共同决定的，所以可以参考 ServiceNow 的 `Priority Lookup Rules` 进行配置。 * 当 ServiceNow Incident 的 Urgency 发生变化时，才会触发 Flashduty 故障严重程度的更新。 * 由于 Flashduty 在遵循最小权限的情况下，无法获取 ServiceNow 的 Impact 和 Urgency 列表，所以只提供了默认值，如果您需要自定义映射关系时，可以联系技术支持。 7. **自定义字段映射**：可以将故障中的标签或自定义字段，映射到 ServiceNow 工单中的对应文本字段，实现信息自动填充。该功能支持将常见上下文信息（如服务名、实例地址、指标名称等）同步至 ServiceNow，便于后续排查与跟踪。 * 仅支持目标为单行文本或多行文本类型的字段。 * 支持从故障标签（如 service、instance）或自定义属性中提取值。 * 若源字段为空，目标字段也将保持为空，不会覆盖原有内容。 * 映射配置在集成设置中统一管理，无需每次手动填写。 ## 在 ServiceNow 当同步方向选择 From\_ServiceNow 或 Two-way 时，还需要在 ServiceNow 中做相应的配置，以便将 ServiceNow Incident 同步至 Flashduty， 在同步至 Flashduty 时，有以下两种方式，可根据实际需求选择即可。 ### 手动同步 该方式依赖 ServiceNow 提供的 UI Action 和 Script Include 的配置，根据以下步骤配置完成的效果：当新建 Incident 或更新 Incident 时，可以在功能区看到发送同步请求的按钮，触发该按钮，可以将当前 Incident 的内容同步至 Flashduty。需要注意的是，如果触发请求时遇到失败的情况，请重试（重试时间间隔需大于 10 秒）。 #### 配置 UI Action 1. 登录 ServiceNow 实例控制台，通过选择 `ALL` ，输入 `UI Actions` 选择`System Definition`-`UI Actions` 。 2. 点击 `New` 新建 Action。 3. `Name` 输入： **Send To Flashduty**， `Table` 选择 **Incident** 。 4. `Form button` ，`Active` ，`Show insert` ，`Show update` ，`Client`， `List v2/3 Compatible` 保持勾选状态。 5. `Onclick` 输入：**onClick();**。 6. `Script` 输入： ```js theme={null} function onClick() { g_form.save(); var ga = new GlideAjax("IncidentWebhookHelperAjax"); ga.addParam("sysparm_name", "sendWebhook"); ga.addParam("sysparm_sys_id", g_form.getUniqueValue()); ga.getXMLAnswer(function (response) { alert("Webhook Triggered: " + response); }); } ``` 7. 提交保存。 #### 配置 Script Include 1. 登录 ServiceNow 实例控制台，通过选择 `ALL` ，输入 `Script Includes` 选择`System Definition`-`Script Includes` 。 2. 点击 `New` 新建 Script Include。 3. `Name` 输入：**IncidentWebhookHelper** ， `Accessible from` 选择 **All application scopes**。 4. `Client callable` 和 `Active` 保持勾选状态。 5. `Script` 输入以下内容，其中 **request.setEndpoint** 中需要补充集成的推送地址：
注意： body 中配置的是默认接收字段，如果有自定义字段需要同步至 Flashduty ，需要额外手动补充内容到 body 中，比如希望添加一个字段名为：test\_001 的字段（该字段名可以在配置集成中添加自定义字段的时候获取，不要使用 ServiceNow Inident 表单中显示的字段名），那么需要在 body 中补充：test\_001: current.getDisplayValue("test\_001")。
```js theme={null} var IncidentWebhookHelper = Class.create(); IncidentWebhookHelper.prototype = { initialize: function() {}, sendIncidentWebhook: function(current) { function getLastComment(sysId) { var journalGR = new GlideRecord('sys_journal_field'); journalGR.addQuery('element_id', sysId); journalGR.addQuery('element', 'comments'); journalGR.orderByDesc('sys_created_on'); journalGR.setLimit(1); journalGR.query(); if (journalGR.next()) { return journalGR.getValue('value'); } return ''; } var body = { action_type: current.isNewRecord() ? 'insert' : 'update', number: current.getValue("number"), sys_id: current.getUniqueValue(), short_description: current.getValue("short_description"), description: current.getValue("description"), impact: current.getDisplayValue("impact"), urgency: current.getDisplayValue("urgency"), comments: getLastComment(current.getUniqueValue()), }; try { var request = new sn_ws.RESTMessageV2(); request.setHttpMethod("POST"); request.setEndpoint("PUSH URL"); request.setRequestHeader("Content-Type", "application/json"); request.setRequestBody(JSON.stringify(body)); request.executeAsync(); } catch (ex) { gs.error("Webhook Call failed: " + ex.message); } }, type: 'IncidentWebhookHelper' }; ``` 6. 提交保存。 7. 回到 Script Includes 列表，继续创建。 8. 点击 `New` 新建 Script Include。 9. `Name` 输入：**IncidentWebhookHelperAjax** ， `Accessible from` 选择 **All application scopes**。 10. `Client callable` 和 `Active` 保持勾选状态。 11. `Script` 输入以下内容： ```js theme={null} var IncidentWebhookHelperAjax = Class.create(); IncidentWebhookHelperAjax.prototype = Object.extendsObject( global.AbstractAjaxProcessor, { sendWebhook: function () { var sysId = this.getParameter("sysparm_sys_id"); var gr = new GlideRecord("incident"); if (gr.get(sysId)) { var helper = new IncidentWebhookHelper(); helper.sendIncidentWebhook(gr); return "Success"; } return "Request failed"; }, } ); ``` 12. 提交保存。 ### 自动同步 该方式依赖 ServiceNow 提供的 Business Rules 的配置，使用该方式可以实现当有新建或更新事件时，自动将 Incident 同步至 Flashduty。 #### 配置 Business Rules 1. 登录 ServiceNow 实例控制台，通过选择 `ALL` ，输入 `Business Rules` 选择`System Definition`-`Business Rules` 。 2. 点击 `New` 新建 Business Rule。 3. `Name` 输入：**Send To Flashduty** ， `Table` 选择 **Incident**。 4. `Advanced` 和 `Active` 保持勾选状态。 5. 在 `When to run` 区域中，`When` 选择 **async**，`Insert` 和 `Upsert` 保持勾选状态，其他按需配置。 6. 在 `Advanced` 区域中，`Script` 填写以下内容，其中 **endpoint** 中需要补充集成的推送地址
注意： body 中配置的是默认接收字段，如果有自定义字段需要同步至 Flashduty ，需要额外手动补充内容到 body 中，比如希望添加一个字段名为：test\_001 的字段（该字段名可以在配置集成中添加自定义字段的时候获取，不要使用 ServiceNow Inident 表单中显示的字段名），那么需要在 body 中补充：test\_001: current.getDisplayValue("test\_001")。
```js theme={null} (function executeRule(current, previous) { function getLastComment(recordSysId) { var journalGR = new GlideRecord("sys_journal_field"); journalGR.addQuery("element_id", recordSysId); journalGR.addQuery("element", "comments"); journalGR.orderByDesc("sys_created_on"); journalGR.setLimit(1); journalGR.query(); if (journalGR.next()) { var comment = journalGR.getValue("value"); return comment; } return ""; } var operation = current.operation() || "unknown"; var isPreviousNull = previous === null; var createdOn = current.getValue("sys_created_on"); var updatedOn = current.getValue("sys_updated_on"); var isNewRecord = createdOn === updatedOn; var action = "update"; if (isPreviousNull && isNewRecord) { action = "insert"; } var body = { action_type: action, number: current.getValue("number"), sys_id: current.getUniqueValue(), short_description: current.getValue("short_description"), description: current.getValue("description"), state: current.getDisplayValue("state"), impact: current.getDisplayValue("impact"), urgency: current.getDisplayValue("urgency"), comments: getLastComment(current.getUniqueValue()), }; try { var endpoint = ""; var request = new sn_ws.RESTMessageV2(); request.setHttpMethod("POST"); request.setEndpoint(endpoint); request.setRequestHeader("Content-Type", "application/json"); request.setRequestBody(JSON.stringify(body)); request.executeAsync(); } catch (ex) { gs.error("Error sending webhook: " + ex.message); } })(current, previous); ``` 7. 提交保存。 ## 同步信息 ### 表单字段 | ServiceNow | Flashduty | 备注 | | ------------------- | ------------- | ----- | | Short\_description | Title | 标题 | | Description | Description | 描述信息 | | Additional comments | Comments | 评论 | | State | Progress | 状态 | | Urgency | Severity | 严重程度 | | Others | Custom Fields | 自定义字段 | ### 状态映射 | ServiceNow | Flashduty | 备注 | | ----------- | ---------- | --------- | | New | Triggered | 触发 | | In Progress | Processing | 待处理 | | On Hold | Snoozed | 默认暂缓 2 小时 | | Resolved | Closed | 关闭 | | Closed | Closed | 关闭 | | Canceled | Closed | 关闭 | ### 优先级映射 只有 ServiceNow 的 Urgency 值变化时，才会影响 Flashduty 的 Severity | ServiceNow | Flashduty | 备注 | | ---------- | --------- | -- | | Low | Info | 提示 | | Medium | Warning | 警告 | | High | Critical | 灾难 | ## 常见问题
新建 ServiceNow 用户时，UserID 是否可以自定义？ 可以自定义，文档指引中使用 flashduty 作为 UserID，是为了更好的标识该用户用于 Incident 同步
配置集成时提示 401 错误 提示 401 一般是密码错误导致的，请检查密码是否正确，或者重新设置新的密码(在配置密码时，请勿勾选 Password needs reset 选项)
# 结合外部数据实现动态分派 Source: https://docs.flashduty.com/zh/on-call/practices/dynamic-dispatch-with-external-data 通过标签映射与动态分派，让告警自动路由到正确的处理人，无需频繁修改分派策略 ## 为什么需要动态分派 在企业运维中，监控对象（主机、服务、数据库等）成千上万，且负责人随组织架构调整频繁变化。如果为每个对象单独维护分派策略，成本极高且容易出错。 **动态分派** 解决的正是这个问题：您只需配置一条分派策略作为"模板"，系统会根据告警携带的特定标签，自动替换或追加该策略中的通知对象。这样，无论负责人如何变更，您只需更新标签数据，无需修改分派策略本身。 ## 工作原理 动态分派的核心流程分为三步： 告警通过集成接入后，进入协作空间，匹配到已配置的分派策略。 系统检测到告警携带了特定标签（如 `layer_person_reset_0_emails=bob@corp.com` 或 `layer_person_append_0_emails=bob@corp.com`），自动替换或追加分派策略中环节 1 的通知对象。 按照调整后的分派策略进行通知。分派完成后，系统自动移除这些控制类标签，保持告警详情页整洁。 动态分派并不是独立工作的，它依赖于协作空间中已有的分派策略。您需要预先配置一条分派策略作为"模板"——动态标签只会替换或追加其中的通知对象（人员、团队或群聊机器人），策略中的其他配置（如通知方式、超时时间、升级规则等）保持不变。 详细的标签参数说明请参考 [动态分派](/zh/on-call/advanced/dynamic-notifications)。 ## 如何生成动态标签 动态分派的关键在于告警需要携带正确的标签。以下两种方式都可以实现，您可以根据实际情况选择。 本文以 `reset` 替换模式为例。如果您希望保留模板分派策略中的原有对象，并额外加入负责人、团队或群聊机器人，可使用 `append` 追加模式。完整参数请参考 [动态分派](/zh/on-call/advanced/dynamic-notifications)。 ### 方式一：在监控系统中直接打标 如果您拥有监控系统的配置权限，且监控系统支持自定义标签（如 Prometheus、Nightingale、Zabbix），直接在告警规则中添加标签即可： * **标签键**：`layer_person_reset_0_emails` * **标签值**：`bob@corp.com` 此方式配置最简单，适合负责人相对固定的场景。但人员变更时需要同步修改监控系统的告警规则。 ### 方式二：通过标签映射自动生成 如果您无法修改监控配置，或者希望将"监控对象 → 负责人"的对应关系集中管理（例如从 CMDB、配置平台或任何外部数据源同步），推荐使用 **标签映射** 功能。 此方式通过建立一张映射表，将告警中已有的基础标签（如 `host`）自动"翻译"为动态分派标签，无需修改监控系统。 梳理监控对象与负责人的对应关系。小规模数据可以在页面中手动输入；大规模数据建议整理为 CSV 文件。 CSV 中的目标列名必须使用动态分派的专用参数名（如 `layer_person_reset_0_emails`）。 | host（源标签） | layer\_person\_reset\_0\_emails（目标标签） | | :------------ | :-------------------------------------- | | web-server-01 | [bob@corp.com](mailto:bob@corp.com) | | db-server-02 | [alice@corp.com](mailto:alice@corp.com) | 数据来源不限——CMDB、配置管理平台、运维系统或 Excel 表格均可，满足上述格式即可。 将数据录入系统，建立一个可复用的映射"字典"。 1. 进入 **集成中心 → 标签映射**。 2. 点击 **创建标签映射**。 3. 录入数据： * **上传文件**：上传 CSV 文件，适合批量操作。 * **手动输入**：在页面上逐条添加，适合少量数据维护。 4. 保存后，您将获得一个可供集成引用的映射表。 如需与外部系统保持实时同步，推荐使用 [Flashduty API](https://developer.flashcat.cloud/flashduty/enrichment/mapping-data-upsert) 自动更新映射表，实现全自动的配置同步。 在告警集成中引用映射表，让系统在告警接入时自动补全动态标签。 1. 进入 **集成中心 → 标签增强**。 2. 找到目标告警集成（如 Zabbix 集成），进入详情。 3. 选择 **标签增强** 页签，动作类型选择 **标签映射**。 4. **选择映射表**：选择上一步创建的映射表。 5. **配置映射关系**： * **源标签**：选择 `host`。 * **目标标签**：选择 `layer_person_reset_0_emails`。 完成后，系统会在告警接入时自动根据 `host` 的值查表，生成对应的动态分派标签。 在目标协作空间中配置一条分派策略。此策略中的通知对象可以设为任意值（例如一个默认团队），它仅作为"模板"——实际分派时，通知对象会被动态标签替换或追加。 策略中的其他配置项（通知方式、超时升级等）会正常生效。 详细配置方法请参考 [分派策略](/zh/on-call/channel/escalation-rule)。 ## 验证效果 完成配置后，触发一条测试告警来验证： 1. **查看分派过程**：在 **故障详情 → 时间线** 中，您会看到类似日志："基于动态标签，分派对象已重置为 [bob@corp.com](mailto:bob@corp.com)"。 2. **检查告警标签**：在告警详情页，您**不会**看到 `layer_person_reset_xxx` 标签——这些控制指令在生效后会被系统自动清理。 ## 延伸阅读 查看完整的动态标签参数说明和推送示例 了解如何根据已有标签自动生成新标签 # 企微机器人 @ 提醒处理人 Source: https://docs.flashduty.com/zh/on-call/practices/wecom-bot-mention 配置企微群聊机器人在推送告警通知时 @ 提醒对应的处理人员，确保关键告警不被遗漏 ## 为什么需要 @ 提醒 企微群聊中消息量大，处理人员容易忽略告警通知。通过开启 **@ 提醒**，机器人推送故障通知时会自动 @ 对应的处理人员，确保相关负责人第一时间收到提醒。 Flashduty 支持两种方式实现企微机器人的 @ 提醒，二者的区别如下： | 对比项 | 默认方式（手机号匹配） | 映射表方式（user\_id 匹配） | | :--------- | :-------------------------- | :---------------------------- | | **匹配原理** | 通过 Flashduty 成员绑定的手机号查找企微成员 | 通过映射表中的邮箱与企微 user\_id 对应关系查找 | | **@ 提醒位置** | 通知消息底部单独展示 | 通知消息内容中内联展示 | | **维护成本** | 无需额外维护，只要手机号一致即可 | 需要维护邮箱与企微 user\_id 的映射表 | | **适用场景** | 手机号在 Flashduty 和企微中保持一致 | 手机号不一致，或希望 @ 提醒与通知内容在同一条消息中展示 | ## 方式一：默认方式（手机号匹配） 这是最简单的方式，无需额外配置。系统通过成员在 Flashduty 中绑定的手机号，自动匹配企微中对应的成员。 ### 前提条件 * 成员在 Flashduty 中绑定的手机号与企微账号的手机号 **完全一致** ### 配置步骤 确保 Flashduty 成员的手机号与企微账号的手机号相同。您可以在 **平台管理 → 成员管理** 中查看和修改成员手机号。 进入目标协作空间的 **分派策略**，找到企微机器人通知渠道，展开 **高级配置**，开启 **@ 提醒** 开关。 此方式下，如果成员的手机号在两个平台中不一致，@ 提醒将不会生效。请优先确认手机号的一致性。 ## 方式二：映射表方式（user\_id 匹配） 如果成员手机号在两个平台中不一致，或者您希望 @ 提醒与通知内容在同一条消息中内联展示，可以使用映射表方式。 此方式需要您维护一张 Flashduty 成员邮箱与企微 user\_id 的对应关系表。 ### 前提条件 * 已获取企微成员的 user\_id（可通过企业微信管理后台或 API 获取） ### 配置步骤 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#contacts)，进入 **通讯录**，点击目标成员查看详情，找到 **账号** 字段，即为该成员的 user\_id。 您也可以通过企业微信 API 批量获取。 1. 进入 Flashduty **平台管理 → 映射表管理**。 2. 点击 **创建映射表**，类型选择 **企微**。 3. 录入 Flashduty 成员邮箱与对应的企微 user\_id： | email | wecom\_userid | | :-------------------------------------- | :------------ | | [bob@corp.com](mailto:bob@corp.com) | bob\_wecom | | [alice@corp.com](mailto:alice@corp.com) | alice\_wecom | 进入目标协作空间的 **分派策略**，找到企微机器人通知渠道： 1. 展开 **高级配置**，开启 **@ 提醒** 开关。 2. 在 **用户信息映射表** 下拉框中，选择上一步创建的映射表。 映射表需要您自行维护。当团队成员发生变动时，请及时更新映射表中的对应关系，否则新成员将无法被 @ 到。 ## 验证效果 完成配置后，触发一条测试告警来验证 @ 提醒是否生效： 1. 确认目标协作空间已配置企微机器人作为群聊通知渠道。 2. 触发测试告警，观察企微群聊中的通知消息。 3. 确认处理人员被正确 @ 到。 如果 @ 提醒未生效，请参考以下排查清单： * 确认已开启 **@ 提醒** 开关 * 确认成员在 Flashduty 中绑定的手机号与企微账号手机号 **完全一致**（包括国际区号） * 确认该成员在企微机器人所在的群聊中 * 确认已开启 **@ 提醒** 开关，且已选择正确的 **用户信息映射表** * 确认映射表中 Flashduty 成员邮箱和企微 user\_id 的对应关系正确 * 确认企微 user\_id 填写无误（可在企微管理后台通讯录中核实） * 确认该成员在企微机器人所在的群聊中 ## 延伸阅读 了解所有机器人类型的配置方法和高级选项 了解分派策略的通知方式和群聊配置 # 微信小程序 Source: https://docs.flashduty.com/zh/rum/analytics/miniprogram 深入了解 Flashduty 微信小程序 RUM 分析看板的核心功能，掌握小程序性能监控、setData 调优和启动耗时分析的关键指标 Flashduty 微信小程序 RUM 分析看板提供开箱即用的可视化仪表板，自动采集并分析小程序的用户会话、启动耗时、页面渲染、setData 调用等多维度数据，帮助您全面洞察小程序真实运行状况，快速定位性能瓶颈与异常问题，持续优化用户体验。 分析看板包含 2 个核心分析维度：**概览**、**性能分析** ## 概览 — 关键指标一目了然 概览模块聚焦于小程序多维度的核心指标，帮助您快速把握整体健康状况。 #### 流量与会话 * **UV**：去重后的独立访客数。结合趋势图可洞察用户活跃规律。 * **会话数**：小程序被打开使用的会话总数，点击卡片可下钻查看具体会话列表。 * **用户访问趋势**：以时序图同时展示 UV 与 Session 的变化趋势，识别访问高峰与异常波动。 #### 核心指标 * **错误数（error\_count）**：监控小程序错误事件的总数与时序趋势，及时发现异常峰值。 * **会话错误率（session error rate）**：发生错误的会话占总会话的比例，反映小程序整体稳定性。 * **应用启动时长 P75（appLaunchTime P75）**：监控小程序冷启动 + 热启动整体耗时的 P75 分位值，评估启动性能表现。启动时长直接影响用户的第一印象。 * **首次渲染 P75（firstRender P75）**：监控页面从开始加载到首次渲染完成耗时的 P75 分位值，反映页面"白屏"时间。 * **setData 调用次数（setDataCount 平均值）**：监控页面平均每次访问的 `setData` 调用次数。过高的调用频次会增加 JS 与渲染线程的通信开销。 * **setData 耗时 P75（setDataDuration P75）**：监控单次 `setData` 调用耗时的 P75 分位值。 #### 会话分析 * **平均会话时长**：会话总时长除以会话总数，评估用户粘性与使用深度。结合时序图可识别活跃用户行为变化。 ## 性能分析 — 全面掌控小程序体验 性能分析模块专注于小程序启动、页面渲染、`setData` 等核心体验指标的全链路监控。 #### 核心性能指标 顶部展示 5 个关键性能指标卡片，点击任一卡片可切换下方趋势图与样本分布的统计维度： | 指标 | 采集字段 | 说明 | | --------------------- | ------------------ | -------------------------- | | **应用启动时长 P75** | `app_launch` | 小程序启动耗时的 P75 分位值 | | **首次渲染 P75** | `first_render` | 页面首次渲染完成耗时的 P75 分位值 | | **页面加载时长 P75** | `loading_time` | 页面从打开到完全加载完成耗时的 P75 分位值 | | **setData 调用次数（平均值）** | `setdata_count` | 单次页面访问内 `setData` 调用次数的平均值 | | **setData 耗时 P75** | `setdata_duration` | 单次 `setData` 调用耗时的 P75 分位值 | 每个卡片左上角显示健康状态徽标（良好 / 中等 / 差），基于内置阈值评估当前指标。 #### 趋势分析 下方的趋势图支持选择 **趋势模式**，按不同维度展开当前指标： | 趋势模式 | 说明 | | --------- | ------------------------------------ | | **整体** | 不分维度，展示当前指标的整体时序趋势 | | **按版本** | 按应用版本号（version）分组，对比新旧版本性能差异 | | **按环境** | 按环境变量（env）分组，对比不同环境的性能表现 | | **按加载类型** | 按 `view_loading_type` 分组，对比冷启动与热启动性能 | | **按操作系统** | 按 `os_name` 分组，识别系统级兼容性差异 | 切换 **按版本** 时可对比新版本灰度阶段的性能数据，验证发版质量；切换 **按加载类型** 时可单独观察冷启动（`initial_load`）和热启动（`route_change`）的耗时差异。 #### 样本分布 样本分布柱状图按时间区间统计当前指标的样本数量分布，识别长尾问题。例如观察应用启动时长时，分布图能清晰展示有多少用户的启动耗时落在 1s 以内、1-2s、2s 以上等区间。 #### 页面性能明细 按页面（视图名称）统计各项性能指标，识别加载缓慢或 `setData` 过于频繁的页面： | 列 | 说明 | | ---------------- | ----------------------------------- | | 视图名称 | 小程序页面路由路径 | | 访问次数 | 该页面的 view 事件总数，附直方图条形展示相对热度 | | 应用启动时长 | 落在该页面会话内的启动耗时 P75 | | 首次渲染 | 该页面首次渲染耗时 P75 | | 页面加载时长 | 该页面完全加载耗时 P75 | | setData 调用次数 | 该页面平均 setData 调用次数 | | setData 耗时 | 该页面单次 setData 耗时 P75 | | onLoad → onShow | 该页面从 `onLoad` 到 `onShow` 之间的耗时 P75 | | onShow → onReady | 该页面从 `onShow` 到 `onReady` 之间的耗时 P75 | 点击表格中的任一行可跳转到该页面的详细分析视图。 #### 启动类型趋势 底部两张图分别展示冷启动（`initial_load`）与热启动（`route_change`）的对比情况： * **启动类型趋势**：冷启动与热启动次数随时间的变化趋势，识别业务流量结构变化。 * **启动耗时趋势**：冷启动与热启动耗时的时序对比，冷启动通常显著长于热启动；如果两者差距异常缩小或拉大，往往意味着启动逻辑发生了变化。 **冷启动 vs 热启动** * **冷启动（initial\_load）**：用户首次进入小程序或小程序被微信回收后重新打开，需要完整初始化运行时和加载首页。 * **热启动（route\_change）**：小程序在后台短时间被唤回，无需重新初始化，耗时显著更短。 ## 常见问题 * **应用启动时长（app\_launch）**：从用户点击小程序图标或入口到 `App.onLaunch` 执行完成的总耗时，包含运行时初始化、首页代码包加载、`App.onLaunch` 执行等阶段。 * **首次渲染（first\_render）**：从页面开始加载到该页面首次完成渲染的耗时，反映页面"白屏"时间。 * 一次冷启动通常 = 应用启动时长 + 首页首次渲染时间，二者从不同角度衡量启动体验。 `setData` 是小程序逻辑层向渲染层通信的核心 API，每次调用都会触发跨线程通信和差量计算。常见问题： * **频繁调用**：在循环或事件中高频调用 `setData`，导致渲染线程持续繁忙 * **数据体积过大**：一次 `setData` 传递的数据过大，跨线程序列化耗时显著 * **更新无关数据**：把整个 `data` 传给 `setData`，而不是仅传递变化的字段 **优化建议：** * 合并多次 `setData` 调用，使用局部对象传参 * 使用路径表达式更新嵌套字段，如 `this.setData({ 'list[0].name': value })` * 避免在频繁触发的事件（scroll、input）中直接调用 `setData`，使用节流/防抖 * 关注页面明细表中 `setData 调用次数` 和 `setData 耗时` 列异常高的页面，优先优化 分位数（Percentile）是统计学中衡量数据分布的重要指标： | 分位数 | 含义 | | ------------ | --------------------------- | | **P50（中位数）** | 50% 的用户体验优于此值，50% 的用户体验劣于此值 | | **P75** | 75% 的用户体验优于此值，25% 的用户体验劣于此值 | | **P90** | 90% 的用户体验优于此值，10% 的用户体验劣于此值 | **为什么使用 P75 而不是平均值？** * 平均值容易被极端值影响，可能不能代表大多数用户的真实体验 * P75 更能反映大部分用户的体验情况，是业界常用的性能评估标准 关注 **应用启动时长 P75** 指标，并通过样本分布柱状图识别长尾。切换趋势模式为 **按加载类型** 单独观察冷启动表现。 减少首包体积，使用分包加载（subpackages）和分包预下载，避免一次性加载所有页面代码。 把第三方 SDK 初始化、埋点上报、远程配置拉取等非关键任务延迟到首屏渲染之后执行。 * 减少首屏依赖的网络请求数量，合并接口 * 使用本地缓存或骨架屏，避免长时间白屏 * 控制首屏 `setData` 的数据体积 切换趋势模式为 **按版本**，对比新旧版本启动耗时，及时发现回退。 这些是小程序页面生命周期内部各阶段的耗时，可用于精确定位渲染慢的环节： * **onLoad → onShow**：页面收到 `onLoad` 到 `onShow` 之间的耗时，主要反映 `onLoad` 中同步逻辑（参数解析、首屏数据预处理等）的耗时。 * **onShow → onReady**：页面 `onShow` 到 `onReady` 之间的耗时，反映首次渲染完成所需的时间，包含模板编译和首批 `setData` 的渲染。 如果首次渲染时间偏长，可结合这两个分段指标判断是 `onLoad` 中的逻辑阻塞，还是首次渲染本身耗时过长。 Flashduty RUM 通常在数据产生后的 **1-3 分钟**内完成采集和展示。在网络状况良好的情况下，大部分数据可实现准实时更新。 ## 延伸阅读 了解如何在微信小程序中接入 RUM SDK，完成应用初始化 了解 SDK 自动采集的事件类型与 view 字段口径 深入配置代理、分布式追踪、采样率与手动上报 查看 SDK 支持的小程序基础库版本与平台 API 要求 # Native Source: https://docs.flashduty.com/zh/rum/analytics/native 深入了解 Flashduty Native（Android/iOS）RUM 分析看板的核心功能，掌握移动应用性能监控、异常追踪和资源分析的关键指标 Flashduty Native RUM 分析看板提供开箱即用的可视化仪表板，自动采集并分析用户会话、应用性能、崩溃异常、网络请求等多维度数据，帮助您全面洞察移动应用真实运行状况，快速定位性能瓶颈与异常问题，持续优化用户体验。 分析看板包含 4 个核心分析维度：**概览**、**性能分析**、**异常分析**、**资源分析** **平台差异** Native 看板适用于 Android、iOS、HarmonyOS 和 Flutter 应用，不同平台存在以下差异： * **Flutter**：一个 Flutter 应用同时覆盖 Android 和 iOS 两端，筛选栏会额外常驻 `os_name` 筛选项，便于按设备系统切片分析；概览与异常分析中，**ANR 率**（来自 Android 设备）与 **App Hang 率**（来自 iOS 设备）两张卡片并列展示。 * **HarmonyOS**：SDK 暂未上报性能与卡顿指标，因此不展示卡顿相关卡片，也不提供「性能」页签。 * **Electron**：不使用 Native 看板——Electron 应用复用 **Web 分析看板**，但 UV 改用匿名 ID 口径（Electron SDK 不上报 `usr_id`），详见下方「指标口径参考」。 ## 概览 — 关键指标一目了然 Native RUM 分析看板概览界面，展示 UV、会话数、崩溃率等核心健康指标 概览模块聚焦于移动应用多维度的核心指标： * **流量指标** - 监控 UV（独立访客数）、会话数，帮助您把握整体用户活跃趋势 * **核心健康指标** - 突出显示三个移动应用核心指标：崩溃次数、无崩溃率、应用卡顿率，快速识别应用稳定性问题 * **用户访问趋势** - 通过时序图追踪 UV 和 Session 的变化趋势，洞察用户活跃规律 * **用户分布** - 结合地理位置分析用户来源，了解区域用户活跃情况 * **会话分析** - 统计会话平均时长分布趋势，评估用户粘性与使用深度 * **版本分布** - 监控不同系统版本（Android/iOS）和应用版本的用户占比，为兼容性优化与版本迭代提供数据支撑 ## 性能分析 — 全面掌控应用体验 性能分析看板展示启动时间、帧率、CPU 和内存使用等关键性能指标 性能分析模块专注于应用启动、页面渲染、交互流畅度等核心体验指标的全链路监控。 #### 核心性能指标 顶部展示四个关键性能指标的 P75 分位值： * **应用启动时间（P75）**：监控应用启动耗时的 P75 分位数，评估启动性能表现。启动时间直接影响用户的第一印象和使用意愿。 * **帧率（P75）**：展示应用运行时帧率的 P75 分位数，衡量画面流畅度。目标为 60fps，数值越高表示交互越流畅。 * **CPU 消耗（P75）**：追踪 CPU 占用率的 P75 分位数，识别计算密集型操作。过高的 CPU 消耗会导致设备发热和耗电增加。 * **内存使用（P75）**：监控应用内存占用的 P75 分位数，及时发现内存泄漏或异常增长。 #### APP 启动时间分析 * **启动时间趋势图**：展示应用启动时间随时间的变化趋势，帮助您评估启动优化效果，及时发现性能退化。 * **样本分布柱状图**：按时间区间统计启动耗时的分布情况（如 0.9425s-0.9642s、1.1162s-1.1379s 等），了解用户真实启动体验的分布特征，识别性能长尾问题。 #### 视图性能明细 按视图名称（页面/Activity/ViewController）统计各项性能指标： * **访问次数**：展示各视图的访问量，识别核心高频页面。 * **启动时间**：监控各视图的加载耗时，定位加载缓慢的页面。 * **帧率**：追踪各视图运行时的帧率表现，识别渲染性能问题。 * **CPU 消耗**：统计各视图的 CPU 占用情况，优化计算密集型页面。 * **内存使用**：监控各视图的内存占用，发现内存泄漏风险。 #### 流畅度分析 按视图名称统计应用流畅度相关指标： * **慢帧数**：统计渲染耗时超过阈值的帧数（通常为 16.67ms，即低于 60fps），识别卡顿问题。慢帧会导致用户感知到明显的界面不流畅。 * **冻结帧数**：记录界面完全冻结的帧数（通常超过 700ms），这些是严重影响用户体验的性能问题。 * **长任务数**：追踪主线程长时间运行的任务数量（通常阈值为 100ms 或更长），定位性能瓶颈。长任务会阻塞用户交互和界面更新。 * **卡顿频率**：统计应用卡顿的发生频率（次/秒），评估整体流畅度表现。 #### 内存分析 按视图名称统计内存使用详情： * **平均内存**：展示各视图的平均内存占用，了解常规内存消耗水平。 * **峰值内存**：记录各视图运行期间的内存使用峰值，识别内存压力高峰，预防因内存不足导致的系统终止（OOM）。 * **P75 内存**：显示内存占用的 P75 分位数，反映大部分用户的内存使用情况，比平均值更能代表真实体验。 ## 异常分析 — 快速定位与诊断错误 异常分析看板展示崩溃次数、无崩溃率、ANR 率和应用卡顿率 异常分析模块为您提供全方位的错误监控与诊断能力。 #### 核心稳定性指标 * **崩溃次数**：监控应用崩溃的发生总数和趋势，及时发现异常峰值。崩溃会导致应用强制退出，严重影响用户体验。 * **无崩溃率**：跟踪无崩溃会话占比，评估应用整体稳定性表现。行业标准建议无崩溃率应保持在 99.5% 以上。 * **ANR 率**：统计 Android 应用无响应（Application Not Responding）的发生比例。ANR 表示应用主线程被阻塞超过 5 秒，用户会看到"应用无响应"对话框。 * **应用卡顿率**：监控发生卡顿的会话占总会话的比例，用于评估应用流畅度问题的影响范围。卡顿通常指主线程长时间阻塞导致的界面冻结、响应延迟或帧率下降，影响用户交互体验。 #### 错误数据统计 * **错误数**：展示错误总数和时序趋势，了解应用健康状况的整体变化。 * **错误类型分布趋势图**：通过堆叠面积图展示崩溃错误（crash\_count）与非崩溃错误（non\_crash\_count）随时间的分布变化，快速识别异常时段和错误类型变化趋势。 * **崩溃错误（crash\_count）**：导致应用强制退出的严重错误 * **非崩溃错误（non\_crash\_count）**：被捕获的异常，应用可继续运行但功能可能受影响 #### 页面 Crash 排行（Top10） 列出崩溃次数最多的页面或视图控制器，每条记录包含： * **错误类型**：崩溃的异常类型（如 java.lang.RuntimeException、SIGTRAP 等） * **错误信息**：错误的详细描述，帮助快速定位问题 * **错误数**：该错误在该页面发生的总次数 * **会话数**：受该错误影响的会话（用户访问）数量 此排行帮助您优先处理影响最大的页面崩溃问题。 #### 热门 Issue（Top10） 展示影响用户最多的问题排行，每个 Issue 是经过聚合的错误集合，包含： * **错误类型**：Issue 的主要错误类型（如 java.lang.RuntimeException、TypeError、ReferenceError 等） * **错误信息**：Issue 的典型错误描述，点击可查看详细堆栈和会话信息 * **错误数**：该 Issue 包含的错误总次数 * **会话数**：受该 Issue 影响的会话数量 **注意**：一个 Issue 可能聚合了多次相同根因的错误。关于 Issue 聚合策略，可查看[异常聚合](https://docs.flashduty.com/zh/flashduty/rum/error-grouping)。 #### 错误类型分布 * **错误类型占比（饼图）**：展示不同错误类型的占比（如 ReferenceError、java.lang.RuntimeException 等），快速识别主要错误来源。 * **错误类型分布趋势（堆叠面积图）**：监控各错误类型随时间的变化趋势，及时发现新增错误类型或某类错误的异常增长。 #### 版本 Crash 分布 * **版本 Crash 分布（饼图）**：统计不同应用版本的崩溃分布情况，识别高风险版本。 * **版本 Crash 分布趋势（堆叠面积图）**：监控各版本崩溃随时间的变化，评估新版本质量，必要时进行热修复或回滚。 #### 系统版本异常分布 * **系统版本异常分布（饼图）**：统计不同操作系统版本（如 Android 11、Android 12、iOS 15 等）的异常分布情况，识别系统兼容性问题。 * **系统版本异常趋势（堆叠面积图）**：监控各系统版本异常随时间的变化，为系统兼容性优化提供数据支撑。 如需深入分析具体错误，可参阅[错误跟踪](https://docs.flashduty.com/zh/flashduty/rum/error-tracking)了解如何调查关键错误、查看错误堆栈、追踪新错误的出现，以及如何在问题修复后验证效果。 ## 资源分析 — 精细化网络性能优化 资源分析看板展示请求数、成功率、响应时间和资源耗时排行 资源分析模块帮助您深入了解应用的网络请求性能，识别优化机会： * **请求数**：监控网络请求总量的变化趋势，了解应用网络活跃度。 * **请求成功率**：跟踪请求成功的比例，及时发现网络异常。 * **中位数请求时间**：展示请求耗时的中位数变化（如 p50、p75、p95），评估整体网络性能水平。 * **慢请求**：统计响应时间超过阈值的慢请求趋势，定位性能瓶颈。 * **异常请求**：监控失败或错误请求的发生情况，快速识别接口问题。 * **资源请求状态分布**： * **请求状态码占比**：通过饼图展示不同 HTTP 状态码的分布（如 200、404、500），识别异常请求类型。 * **请求状态码趋势**：监控各状态码随时间的变化，及时发现异常峰值。 * **请求方式分布**： * **请求方法占比**：展示不同 HTTP 方法（GET、POST 等）的使用分布。 * **请求方法趋势**：分析各请求方法的时序变化。 * **静态资源**： * **静态资源调用排行**：列出调用频率最高的静态资源（如图片、字体、配置文件等），了解资源使用热度。 * **静态资源响应排行**：识别响应最慢的静态资源，优化资源加载性能。 * **网络调用排行**： * **Host 排行**：按请求来源（Host）统计请求数，识别主要依赖的服务端点。 * **资源耗时排行**：列出耗时最长的网络请求，包含耗时详情（DNS 解析、TCP 连接、SSL 握手、首字节时间、响应时间等），精准定位性能瓶颈。 ## 常见问题 状态码为 0 通常由以下原因导致： * **请求被取消** - 用户在请求完成前离开页面或取消操作，导致请求中断 * **网络中断或超时** - 请求在发送过程中遇到网络中断、超时等异常情况，可能导致状态码无法正常返回 * **证书验证失败** - HTTPS 请求的 SSL 证书验证失败，连接建立前就被中断 * **SDK 兼容性** - 在极少数情况下，特定系统版本或设备可能存在兼容性问题，导致数据采集不完整 * **错误数** - 指原始错误事件的总数，包括每一次错误发生的记录 * **Issue 数量** - 指经过聚合后的问题数量。Flashduty 会根据错误堆栈、错误类型、发生位置等信息，将相似的错误聚合为同一个 Issue **示例：** ``` 错误总数：100 次 Issue 数量：5 个 ``` 这表示 100 次错误被聚合成了 5 个不同的 Issue，每个 Issue 可能由不同的根因导致。 聚合的优势： * 便于定位问题根因：相同根因的错误归为一个 Issue，避免重复处理 * 优先级排序：通过影响范围（错误数、会话数）识别最需要修复的问题 * 追踪修复效果：修复一个 Issue 后，可观察该 Issue 下所有错误是否消失 详细了解 [异常聚合策略](https://docs.flashduty.com/zh/flashduty/rum/error-grouping)。 通过"页面 Crash 排行"和"热门 Issue"快速定位影响最大的崩溃问题。 点击具体 Issue 查看详细的错误堆栈和用户环境信息，精准定位问题代码。 通过"系统版本 Crash 分布"识别特定系统版本的兼容性问题。 通过"版本 Crash 分布"评估新版本质量，必要时进行热修复或回滚。 合理使用 try-catch、全局异常处理器，避免未捕获异常导致崩溃。 分位数（Percentile）是统计学中衡量数据分布的重要指标： | 分位数 | 含义 | | ------------ | --------------------------- | | **P50（中位数）** | 50% 的用户体验优于此值，50% 的用户体验劣于此值 | | **P75** | 75% 的用户体验优于此值，25% 的用户体验劣于此值 | | **P90** | 90% 的用户体验优于此值，10% 的用户体验劣于此值 | | **P95** | 95% 的用户体验优于此值，5% 的用户体验劣于此值 | **为什么使用 P75 而不是平均值？** * 平均值容易被极端值影响，可能不能代表大多数用户的真实体验 * P75 更能反映大部分用户的体验情况，是业界常用的性能评估标准 * Google 推荐使用 P75 作为核心性能指标 **示例：** ``` 应用启动时间 P75 = 1.7s → 表示 75% 的用户启动时间在 1.7s 以内，25% 的用户超过 1.7s 内存使用 P75 = 233MB → 表示 75% 的场景下内存占用在 233MB 以内 ``` 这些都是衡量应用流畅度的重要指标： | 指标类型 | 阈值 | 用户体验影响 | 优先级 | | --------------------- | ------------------------ | ------------- | ---------------- | | **慢帧（Slow Frame）** | 渲染耗时 > 16.67ms（60fps 标准） | 轻微卡顿 | 偶尔出现可接受，频繁出现需要优化 | | **冻结帧（Frozen Frame）** | 渲染耗时 > 700ms | 界面完全冻结，用户无法交互 | 严重影响体验，必须修复 | | **长任务（Long Task）** | 主线程执行 > 100ms | 阻塞用户交互和界面更新 | 需要优化 | **长任务常见原因：** * 复杂计算 * 大数据处理 * 同步 I/O 操作 **优化建议：** * 将耗时操作移至后台线程 * 分批处理大量数据 * 优化算法复杂度 * 避免在主线程进行同步网络请求或磁盘 I/O 通过"页面加载耗时排行"识别加载最慢的页面，优先优化。 * 采用分页加载或虚拟列表技术，避免一次性加载大量数据 * 使用数据预加载和缓存策略，减少等待时间 * 优化网络请求，合并接口调用 * 减少视图层级嵌套，降低布局计算复杂度 * 避免过度使用透明视图和圆角效果 * 延迟加载非首屏内容 * 使用合适的图片格式和尺寸 * 采用渐进式加载或占位图 * 对图片进行压缩和缓存 将复杂视图的渲染操作放到后台线程执行。 **ANR（Application Not Responding）** 是 Android 系统的应用无响应机制： * 当应用主线程被阻塞超过 5 秒时，系统会弹出"应用无响应"对话框 * 用户可以选择"等待"或"关闭应用" * ANR 严重影响用户体验，可能导致用户卸载应用 ANR 常见原因： * **主线程执行耗时操作**：同步网络请求、大文件读写、复杂计算、数据库操作 * **主线程等待锁**：多线程死锁、等待其他线程释放锁 * **系统资源不足**：CPU 被其他应用占用、内存不足导致频繁 GC **降低 ANR 率的方法：** 1. **避免主线程阻塞** - 将耗时操作移至后台线程（使用 AsyncTask、Coroutines、RxJava 等） 2. **优化锁使用** - 减少锁的持有时间，避免嵌套锁，使用无锁数据结构 3. **优化生命周期方法** - onCreate/onResume 等方法要快速返回 4. **监控和分析** - 使用 StrictMode 发现主线程违规，通过 RUM 看板定位问题 通过"长任务监控"和"卡顿时长分布"识别导致卡顿的具体代码。 将耗时操作（如网络请求、数据库读写、复杂计算、大文件 I/O）移至后台线程。 * 减少视图层级，降低布局复杂度 * 避免在主线程进行复杂的视图计算 * 使用 RecyclerView（Android）或 UITableView/UICollectionView（iOS）的优化技巧 * 合理使用硬件加速 * 实现视图复用机制 * 优化 item 布局复杂度 * 避免在 item 绑定时执行耗时操作 结合性能分析看板和系统工具（Android Profiler、Xcode Instruments）定位具体卡顿代码。 建议根据业务特点和用户预期，设置合理的卡顿检测阈值（建议 200-500ms）。 **登录态用户识别** 对于需要用户登录的应用（如电商、社交、金融等），您可以在用户登录后调用 SDK 的用户标识方法： * Android: 参考 [Android 用户会话配置](/zh/rum/sdk/android/advanced-config#追踪用户会话) * iOS: 参考 [iOS 用户会话配置](/zh/rum/sdk/ios/advanced-config#追踪用户会话) **设备指纹识别** 对于无登录态的应用，推荐基于设备信息生成稳定的设备指纹并上报用户标识： | 平台 | 可用标识符 | | ----------- | --------------------------------------- | | **Android** | Android ID、IMEI（需权限）、广告 ID | | **iOS** | IDFV（Identifier for Vendor）、IDFA（需用户授权） | 通过"资源耗时排行"定位响应时间最长的接口。 查看 DNS 解析、TCP 连接、SSL 握手、首字节时间等各阶段耗时，精准定位瓶颈。 | 优化方向 | 具体措施 | | ---------- | ------------------------ | | **DNS 优化** | 使用 DNS 缓存、HTTPDNS | | **连接优化** | 启用 HTTP/2、连接复用、减少重定向 | | **传输优化** | 启用 GZIP 压缩、优化数据格式、减少请求体积 | | **接口优化** | 优化后端接口性能、使用 CDN 加速静态资源 | * 查看"应用启动时间（P75）"指标，了解大部分用户的启动体验 * 通过"启动时间趋势图"评估优化效果，避免性能退化 * 查看"样本分布柱状图"识别长尾问题 将非必要的初始化操作延迟到首屏渲染后执行，缩短启动时间。 减少启动期间加载的第三方 SDK 和库，采用懒加载策略。 降低首页视图层级复杂度，减少首次渲染耗时。 * **Android**: 使用 App Startup Library 管理组件初始化顺序 * **iOS**: 利用 Lazy Initialization 延迟初始化非关键组件 Flashduty RUM 通常在数据产生后的 **1-3 分钟**内完成采集和展示。在网络状况良好的情况下，大部分数据可实现准实时更新。 ## 指标口径参考 ### 概览指标 | 指标 | 采集字段 | 说明 | | ------ | ---------------------------- | ----------------- | | UV | usr\_anonymous\_id / usr\_id | 去重后的用户总数，详见下方口径说明 | | 会话数 | session\_id | 应用被打开使用的总会话数量 | | 会话平均时长 | - | 会话总时长除以会话总数 | | 使用频次 | - | 会话总数除以活跃用户数 | **UV 口径说明**：Native（Android/iOS/HarmonyOS/Flutter）看板与应用卡片的 UV 以设备稳定的匿名 ID 为口径，即 `COUNT(DISTINCT COALESCE(NULLIF(usr_anonymous_id, ''), NULLIF(usr_id, '')))`。匿名 ID 在用户登录后保持不变，因此匿名会话与同一用户后续的登录会话会计为同一用户；未开启匿名用户追踪时回退为 `usr_id` 口径。Web（浏览器）与小程序看板保持 `usr_id` 口径不变；**Electron 应用同样使用 Web 分析看板，但 UV 与 Native 看板一样以匿名 ID 为口径**——Electron SDK 不上报 `usr_id`（恒为空），稳定标识由主进程注入为 `usr_anonymous_id`。 ### 性能指标阈值 | 指标 | 采集字段 | 良好 | 中等 | 差 | | ------ | ----------------------------- | ------------- | ------------- | ------------- | | 应用启动时间 | view\_app\_start\_time | 2s 以内 | 4s 以内 | 超过 4s | | 帧率 | view\_refresh\_rate\_average | 55 FPS 以上 | 50 FPS 以上 | 低于 50 FPS | | CPU 消耗 | view\_cpu\_ticks\_per\_second | 低于 40 ticks/s | 低于 60 ticks/s | 60 ticks/s 以上 | | 内存使用 | view\_memory\_average | 低于 100 MB | 低于 200 MB | 200 MB 以上 | | 峰值内存 | view\_memory\_max | 低于 200 MB | 低于 400 MB | 400 MB 以上 | ### 流畅度指标 | 指标 | 定义 | 采集字段 | | ---- | ------------------ | -------------------- | | 慢帧数 | 渲染耗时超过 16ms 的帧数 | - | | 冻结帧数 | 渲染耗时超过 700ms 的帧数 | - | | 长任务数 | 执行时间超过 100ms 的任务数量 | long\_task\_duration | | 卡顿频率 | 平均每秒发生冻结的次数 | - | ### 稳定性指标 | 指标 | 计算方式 | 说明 | | ----- | ------------- | ------------------------- | | 崩溃次数 | 直接统计 | 由未处理的异常或信号引起的崩溃总次数 | | 无崩溃率 | 1 减去崩溃会话占比 | 建议保持在 99% 以上 | | ANR 率 | ANR 会话数除以总会话数 | UI 线程阻塞超过 5 秒时触发（Android） | | 应用卡顿率 | 卡顿会话数除以总会话数 | 主线程无响应超过 250ms 时计入（iOS） | ## 延伸阅读 ### SDK 接入与配置 了解如何在 Android 应用中集成 RUM SDK 了解如何在 iOS 应用中集成 RUM SDK 深入配置 Android RUM SDK 高级功能 深入配置 iOS RUM SDK 高级功能 了解 Android RUM SDK 收集的数据类型 了解 iOS RUM SDK 收集的数据类型 ### 数据分析与监控 学习如何使用 RUM Explorer 深入分析数据 掌握错误追踪和调试技巧 理解错误聚合机制 # Web RUM 分析 Source: https://docs.flashduty.com/zh/rum/analytics/web 本文档详细介绍 Flashduty RUM 分析看板的功能和使用方法 ## 概述 Flashduty RUM 分析看板提供了开箱即用的可视化仪表板，自动采集并分析用户会话、性能、资源、错误等多维度数据，助力您全面洞察应用真实运行状况，快速定位性能瓶颈与异常问题，持续优化用户体验。 分析看板主要包含以下四个分析维度： 关键指标一目了然 全面掌控应用体验 快速定位与诊断错误 精细化资源优化 ## 概览 RUM 分析看板概览 概览模块聚焦于应用多维度的核心指标： | 指标类型 | 说明 | | ----------- | ----------------------------------------------- | | **流量指标** | 监控 PV（页面浏览量）、UV（独立访客数）、会话数，把握整体访问趋势 | | **用户分布** | 结合地理位置、设备类型等信息，洞察用户来源与活跃区域 | | **健康与性能指标** | 显示核心 Web 指标：LCP（最大内容绘制）、FID（首次输入延迟）、CLS（累积布局偏移） | | **异常与错误** | 统计各类型错误率，快速发现潜在风险点 | ## 性能分析 RUM 性能分析 性能分析模块专注于应用加载与交互体验的全链路监控： * **页面性能**：监控 FCP、LCP、CLS 等页面加载核心指标的趋势与样本分布 * **长任务**：[长动画帧](https://developer.chrome.com/docs/web-platform/long-animation-frames#long-frames-api)渲染更新延迟超过 50 毫秒的情况 * **XHR 和 Fetch 请求**：分析接口的加载性能，定位慢接口 * **静态资源**：分析静态资源的加载耗时，定位应用加载时的性能瓶颈 有关显示数据的更多信息，请参阅 [数据收集](/zh/rum/others/data-collection)。 ## 异常分析 RUM 异常分析 异常分析模块提供全方位的错误监控与诊断能力： * **页面错误率**：发生错误最多的页面，帮助您定位优先需要关注的页面 * **热门 Issue**：影响用户最多的 Issue 排行，详见 [异常聚合](/zh/rum/error-tracking/error-aggregation) * **代码错误**：分类展示错误类型，详见 [异常追踪](/zh/rum/error-tracking/overview) * **接口和资源错误**：监控哪些接口和静态资源产生的错误最多 ## 资源分析 RUM 资源分析 资源分析模块帮助您识别对应用影响最大的资源： * **资源排行**：监控加载最多与最重的资源，识别优化重点 * **资源加载时序**：监控资源耗时趋势（DNS 解析、TCP 连接、加载耗时等） * **XHR 和 Fetch 请求**：区分不同请求类型、方法和错误状态码的分布趋势 * **第三方资源**：资源地址（host）与当前页面地址（host）不匹配的资源被识别为第三方资源 ### 流量分布 流量分布模块帮助您分析自有资源与第三方资源的请求情况，识别外部依赖对应用性能的影响。 该模块包含以下三个部分： | 部分 | 说明 | | -------- | ---------------------------------------------------------------------------- | | **资源列表** | 按域名（Host）聚合展示资源的请求数量、P90/P50 耗时、请求成功率和资源提供商类别（自有资源或第三方）。支持按域名正则筛选和按资源提供商类别筛选 | | **耗时趋势** | 以折线图展示自有资源与第三方资源的 P90 耗时对比趋势，帮助您判断第三方资源是否拖慢了整体加载速度 | | **流量占比** | 以饼图展示各第三方域名的请求量占比，直观了解流量在第三方服务间的分布情况 | 您可以在资源列表中点击全屏按钮查看更详细的数据，并通过排序功能快速定位耗时最长或请求量最大的域名。 ## 常见问题 可能有以下原因： 1. **连接复用 (Keep-Alive)**：当资源请求采用 keep-alive 方式保持连接时，DNS 查询和 TCP 连接过程只会在首次请求时发生，后续请求复用同一连接 2. **跨域加载资源**：如果资源以跨域方式加载且未配置相关头部信息，浏览器无法采集完整的性能数据（主要原因） 3. **浏览器兼容性**：极少数情况下，某些浏览器可能不支持 Performance API 1. **跨域加载资源**：如果资源以跨域方式加载且未设置跨域访问权限，浏览器将无法获取资源状态信息 2. **浏览器兼容性**：某些浏览器可能不支持 Performance API（极少见） **1. 采集跨域资源的时序数据** 在跨域资源的 HTTP 响应头中添加： ``` Timing-Allow-Origin: * ``` 详见 MDN 文档 [Resource Timing API](https://developer.mozilla.org/zh-CN/docs/Web/API/Performance_API/Resource_timing#cross-origin_timing_information)。 **2. 采集跨域资源的状态码** 在跨域资源的 HTTP 响应头中添加： ``` Access-Control-Allow-Origin: * ``` 在引用资源的 HTML 标签中添加 `crossorigin="anonymous"`： ```html theme={null} ``` 详见 MDN 文档 [Access-Control-Allow-Origin](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) 和 [crossorigin 属性](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Reference/Attributes/crossorigin)。 **登录态用户识别** 对于需要用户登录的应用（如 SaaS 产品、会员系统、电商平台等），参考 [用户会话](/zh/rum/sdk/web/advanced-config#用户会话)。 **设备指纹识别** 对于无登录态的应用（如企业官网、营销页面等），推荐基于浏览器特征、设备信息等多维数据生成稳定的指纹并上报用户标识。 # Android Source: https://docs.flashduty.com/zh/rum/error-tracking/erro-reporting/android 掌握 Android RUM SDK 的异常捕获机制，包括 Java/Kotlin 崩溃、NDK 崩溃、ANR 报告、手动上报和符号化配置 本文档介绍 Android RUM SDK 的异常捕获机制，帮助您监控和诊断 Android 应用中的崩溃和错误问题。 SDK 支持自动捕获 Java/Kotlin 崩溃、NDK 原生崩溃、ANR（应用无响应），同时提供手动错误上报和符号化堆栈跟踪功能。 ## 异常类型 Android RUM 可以监控以下类型的异常： ### Java/Kotlin 崩溃 SDK 自动捕获未处理的 Java/Kotlin 异常，包括： * 运行时异常（如 `NullPointerException`、`IndexOutOfBoundsException`） * 未捕获的异常 * 应用崩溃 ### NDK 崩溃（Native Crash） 若您的应用使用了原生代码（C/C++），SDK 支持捕获 NDK 崩溃并将其纳入异常追踪。 ### ANR（应用无响应） SDK 可以检测并报告 ANR 问题，帮助您发现主线程阻塞导致的用户体验问题。 ### 自定义错误 除了自动捕获的异常外，您还可以使用 RUM SDK 手动上报自定义异常，用于跟踪业务逻辑错误等特定问题。 ## 配置崩溃报告 ### 基础配置 崩溃报告功能默认启用。确保您已按照 [SDK 接入指南](https://docs.flashduty.com/zh/flashduty/rum/android-sdk-integration) 完成基础 SDK 集成后，SDK 会自动捕获应用中的未处理异常。 ### 添加 NDK 崩溃报告 若您的应用包含原生代码（C/C++），需要添加 NDK 崩溃报告模块来捕获原生崩溃。 在您的应用模块的 `build.gradle` 文件中添加 NDK 崩溃报告依赖： ```groovy build.gradle theme={null} dependencies { implementation "cloud.flashcat:dd-sdk-android-ndk:" } ``` 在 SDK 初始化后启用 NDK 崩溃报告： ```kotlin theme={null} import com.datadog.android.ndk.NdkCrashReports // 在 Datadog.initialize() 之后调用 NdkCrashReports.enable() ``` ### 添加 ANR 报告 ANR（Application Not Responding）是指应用主线程被阻塞超过一定时间，导致应用无法响应用户输入的情况。 #### 启用 ANR 检测 在 RUM 配置中启用 ANR 检测： ```kotlin theme={null} import com.datadog.android.rum.RumConfiguration val rumConfig = RumConfiguration.Builder(applicationId) .trackNonFatalAnrs(true) // 追踪非致命 ANR .build() ``` ANR 检测会监控主线程的响应性。当检测到主线程阻塞超过阈值时，SDK 会自动记录 ANR 事件。 ## 手动错误上报 通过 `addError` API，您可以手动上报已处理的异常、自定义错误或其他未被自动捕获的错误。 ### 上报错误示例 ```kotlin theme={null} import com.datadog.android.rum.GlobalRumMonitor import com.datadog.android.rum.RumErrorSource // 上报带有上下文的错误 try { riskyOperation() } catch (e: Exception) { GlobalRumMonitor.get().addError( message = "操作失败", source = RumErrorSource.SOURCE, throwable = e, attributes = mapOf( "operation" to "riskyOperation", "userId" to "12345" ) ) } ``` ### 错误来源类型 `RumErrorSource` 可选值： | 值 | 描述 | | ------------------------ | ---------- | | `RumErrorSource.NETWORK` | 网络错误 | | `RumErrorSource.SOURCE` | 源码错误 | | `RumErrorSource.CONSOLE` | 控制台错误 | | `RumErrorSource.LOGGER` | 日志错误 | | `RumErrorSource.AGENT` | Agent 错误 | | `RumErrorSource.WEBVIEW` | WebView 错误 | | `RumErrorSource.CUSTOM` | 自定义错误 | ### 上报网络错误示例 ```kotlin theme={null} import com.datadog.android.rum.GlobalRumMonitor import com.datadog.android.rum.RumErrorSource fun onNetworkError(url: String, statusCode: Int, error: Throwable) { GlobalRumMonitor.get().addError( message = "网络请求失败: $url", source = RumErrorSource.NETWORK, throwable = error, attributes = mapOf( "url" to url, "status_code" to statusCode, "method" to "GET" ) ) } ``` ## 获取脱混淆的堆栈跟踪 如果您的应用启用了代码混淆（ProGuard/R8），上报的崩溃堆栈将被混淆。通过上传 mapping 文件，可以将混淆后的堆栈还原为原始的类名、方法名和行号。 ### 配置 Gradle 插件 在应用模块的 `build.gradle` 文件中添加 Flashcat Android Gradle 插件： ```groovy build.gradle theme={null} plugins { id("cloud.flashcat.android-gradle-plugin") version "1.1.0" } ``` 配置上传任务所需的应用标识和上传目标。未配置时，插件会从 Android 构建配置读取应用版本和包名： ```groovy build.gradle theme={null} flashcat { site = "CN" // 可选，可选值：CN、STAGING，默认 CN serviceName = "" // 可选，默认使用应用包名 versionName = "1.0.0" // 可选，默认读取 android.defaultConfig.versionName } ``` API Key 通过 `FC_API_KEY` / `FLASHCAT_API_KEY` 环境变量、同名 Gradle 属性，或项目根目录的 `flashcat-ci.json` 提供。更多配置项请参阅 [源码映射 - 上传 Android 符号文件](/zh/rum/error-tracking/source-mapping#上传-android-符号文件)。 ### 上传 Mapping 文件 配置完成后，在构建完成后手动运行上传任务，或将任务加入您的 CI 发布流程： ```bash theme={null} ./gradlew uploadMapping ``` 例如，对于 `release` 变体： ```bash theme={null} ./gradlew uploadMappingRelease ``` ### 上传 NDK 符号文件 如果您使用了 NDK 崩溃报告，还需要上传 NDK 符号文件以获取可读的原生堆栈： ```bash theme={null} ./gradlew uploadNdkSymbolFiles ``` ### 插件配置选项 | 属性名 | 描述 | | -------------------------------- | ------------------------------------------------------------- | | `versionName` | 应用版本名称，默认读取 Android 构建配置中的 `versionName` | | `serviceName` | 服务名称，默认使用应用包名 | | `site` | 上传站点，可选值：`CN`、`STAGING`，默认 `CN` | | `mappingFilePath` | 自定义 ProGuard/R8 mapping 文件路径，默认使用当前 variant 的 Android 构建产物 | | `nonDefaultObfuscation` | 使用 DexGuard 等非默认混淆工具时设为 `true`，插件会为所有 variant 创建上传任务 | | `additionalSymbolFilesLocations` | 额外 NDK 符号目录，目录结构需类似 `/path/to/location/obj/{arch}/libname.so` | | `checkProjectDependencies` | 控制是否检查 Flashcat SDK 依赖。可选值：`none`、`warn`、`fail`；未配置时不检查 | ### Mapping 文件大小限制 Mapping 文件大小限制为 **500 MB**。如果文件过大，可以使用以下选项减小文件大小： ```groovy build.gradle theme={null} flashcat { mappingFileTrimIndents = true // 移除缩进，平均减少约 5% 的文件大小 mappingFilePackageAliases = [ "kotlinx.coroutines": "kx.cor", "com.google.android.material": "material", "com.google.gson": "gson" ] } ``` 使用 `mappingFilePackageAliases` 时，Flashcat 异常追踪中的堆栈将使用别名替代原始包名。建议仅对第三方依赖使用此选项。 ## 追踪后台事件 默认情况下，只有在视图处于活动状态时发生的崩溃才会被追踪。如果您希望追踪应用在后台时发生的崩溃，可以启用后台事件追踪： ```kotlin theme={null} import com.datadog.android.rum.RumConfiguration val rumConfig = RumConfiguration.Builder(applicationId) .trackBackgroundEvents(true) .build() ``` 追踪后台事件可能会产生额外的会话，这可能会影响计费。如有疑问，请联系 Flashcat 支持团队。 ## 限制与注意事项 ### 崩溃检测限制 * **SDK 初始化时机**：崩溃只有在 SDK 初始化之后才能被检测到。建议在 `Application.onCreate()` 中尽早初始化 SDK。 * **视图关联**：崩溃必须与一个 RUM 视图关联。若在视图显示前或应用被置于后台后发生崩溃，该崩溃可能不会被报告。可通过 `trackBackgroundEvents(true)` 缓解这一问题。 * **采样率影响**：只有被采样的会话中的崩溃才会被保留。如果会话采样率不是 100%，部分崩溃可能不会被报告。 ### 符号化限制 * 确保 mapping 文件在每次发布新版本时都正确上传。 * 不同构建变体（如 debug/release）需要分别上传对应的 mapping 文件。 * NDK 符号文件需要包含调试信息才能正确符号化。 ## 测试验证 ### 验证 Java/Kotlin 崩溃 1. 在应用中添加测试代码触发崩溃： ```kotlin theme={null} fun onEvent() { throw RuntimeException("测试崩溃") } ``` 2. 运行应用并触发崩溃 3. 重启应用，等待 SDK 上传崩溃报告 4. 在 Flashcat 控制台的异常追踪模块中查看崩溃报告 ### 验证 NDK 崩溃 1. 在原生代码中添加测试崩溃： ```cpp theme={null} void crash() { int* ptr = nullptr; *ptr = 42; // 触发空指针崩溃 } ``` 2. 从 Java/Kotlin 代码调用该原生方法 3. 重启应用，等待 SDK 上传崩溃报告 4. 确认堆栈是否已被正确符号化（显示函数名、文件名和行号） ### 验证 ANR 1. 在主线程执行耗时操作： ```kotlin theme={null} fun blockMainThread() { Thread.sleep(10000) // 阻塞主线程 10 秒 } ``` 2. 触发该操作后尝试与应用交互 3. 检查 Flashcat 控制台是否收到 ANR 报告 ## 错误数据结构 每条错误数据包含以下属性： | 属性 | 类型 | 描述 | | ---------------- | ------- | ---------------------------------------- | | `error.source` | string | 错误来源（如 `source`、`network`、`custom`） | | `error.type` | string | 错误类型或错误码（如 `NullPointerException`） | | `error.message` | string | 错误消息 | | `error.stack` | string | 错误堆栈跟踪 | | `error.is_crash` | boolean | 是否为崩溃 | | `context` | Object | 自定义上下文信息，通过 `addError` 的 `attributes` 传入 | ## 最佳实践 1. **尽早初始化 SDK**：在 `Application.onCreate()` 中初始化 SDK，确保能捕获尽可能多的崩溃。 2. **启用后台事件追踪**：如果您的应用有大量后台操作，建议启用 `trackBackgroundEvents`。 3. **正确上传符号文件**： * 为每个发布版本上传对应的 mapping 文件 * 如果使用 NDK，同时上传 NDK 符号文件 * 在 CI/CD 流程中集成符号文件上传 4. **丰富错误上下文**：在手动上报错误时，附加业务相关的上下文信息（如用户 ID、操作类型）。 5. **过滤无关错误**：使用 `setErrorEventMapper` 过滤第三方 SDK 或无关的错误，减少噪音。 ## 下一步 了解如何在异常追踪模块查看和分析 Issue 配置 Android SDK 的高级功能 # iOS Source: https://docs.flashduty.com/zh/rum/error-tracking/erro-reporting/ios 掌握 iOS RUM SDK 的异常捕获机制，包括崩溃捕获、App Hangs、Watchdog 终止、手动上报和 dSYM 符号化 本文档介绍 iOS RUM SDK 的异常捕获机制，帮助您监控和诊断 iOS 应用中的崩溃和错误问题。 SDK 支持自动捕获应用崩溃、App Hangs（应用挂起）、Watchdog 终止，同时提供手动错误上报和 dSYM 符号化功能。 ## 异常类型 iOS RUM 可以监控以下类型的异常： ### 应用崩溃 SDK 自动捕获未处理的异常和致命信号，包括： * 未捕获的 Swift/Objective-C 异常 * 致命信号（如 `SIGSEGV`、`SIGABRT`） * Mach 异常 ### App Hangs（应用挂起） 当主线程被阻塞超过指定阈值时，SDK 会检测并报告 App Hang 事件，帮助您发现影响用户体验的卡顿问题。 ### Watchdog 终止 iOS 系统的 Watchdog 机制会终止长时间无响应的应用。SDK 可以检测这类终止并报告为崩溃事件。 ### 自定义错误 除了自动捕获的异常外，您还可以使用 RUM SDK 手动上报自定义异常，用于跟踪业务逻辑错误等特定问题。 ## 配置崩溃报告 ### 添加 Crash Reporting 模块 要启用崩溃报告功能，需要添加 `FlashcatCrashReporting` 模块。 #### Swift Package Manager 在 Xcode 中添加包依赖时，同时添加以下模块： * `FlashcatCore`：核心 SDK * `FlashcatRUM`：RUM 功能模块 * `FlashcatCrashReporting`：崩溃报告模块 ### 初始化崩溃报告 在 SDK 初始化后启用崩溃报告： ```swift AppDelegate.swift theme={null} import FlashcatCore import FlashcatRUM import FlashcatCrashReporting @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { // 初始化 Flashcat SDK Flashcat.initialize( with: Flashcat.Configuration( clientToken: "", env: "" ), trackingConsent: .granted ) // 启用崩溃报告 CrashReporting.enable() // 启用 RUM RUM.enable( with: RUM.Configuration( applicationID: "" ) ) return true } } ``` 建议在 `application(_:didFinishLaunchingWithOptions:)` 中尽早初始化 SDK 和崩溃报告，以确保能捕获应用启动阶段的崩溃。 ## 配置 App Hangs 检测 App Hang 是指主线程被阻塞导致应用无法响应用户输入的情况。SDK 可以检测这类问题并上报。 ### 启用 App Hangs 追踪 在 RUM 配置中设置 `appHangThreshold` 参数： ```swift theme={null} import FlashcatRUM RUM.enable( with: RUM.Configuration( applicationID: "", appHangThreshold: 0.25 // 250 毫秒 ) ) ``` ### App Hang 阈值说明 | 阈值设置 | 描述 | 适用场景 | | ------ | -------------- | ----------- | | `0.25` | 250 毫秒，检测轻微卡顿 | 对流畅度要求极高的应用 | | `1.0` | 1 秒，检测明显卡顿 | 一般应用推荐值 | | `nil` | 禁用 App Hang 检测 | 默认设置 | **配置建议：** * 设置过低的阈值可能会产生大量报告，建议根据应用实际情况调整 * 如果 App Hang 导致应用被 Watchdog 终止，该事件会被标记为崩溃类型 ## 配置 Watchdog 终止追踪 iOS 的 Watchdog 机制会终止长时间无响应的应用。SDK 可以在下次应用启动时检测并报告这类终止。 ### 启用 Watchdog 终止追踪 ```swift theme={null} import FlashcatRUM RUM.enable( with: RUM.Configuration( applicationID: "", trackWatchdogTerminations: true ) ) ``` ### Watchdog 终止检测条件 SDK 会在以下条件全部满足时将上次应用终止判定为 Watchdog 终止： * 应用不是被用户强制退出 * 上次运行未发生崩溃或 fatal error * 应用未进行升级 * 应用在前台且正在响应事件 ## 手动错误上报 通过 `addError` API，您可以手动上报已处理的异常、自定义错误或其他未被自动捕获的错误。 ### 上报错误示例 ```swift theme={null} import FlashcatRUM // 上报带有上下文的错误 RUMMonitor.shared().addError( message: "网络请求失败", type: "NetworkError", source: .network, attributes: [ "url": "https://api.example.com", "status_code": 500, "userId": "12345" ] ) ``` ### 错误来源类型 | 来源 | 描述 | | ---------- | ---------- | | `.source` | 源码错误 | | `.network` | 网络错误 | | `.webview` | WebView 错误 | | `.console` | 控制台错误 | | `.custom` | 自定义错误 | ### 上报异常对象示例 ```swift theme={null} import FlashcatRUM do { try riskyOperation() } catch { RUMMonitor.shared().addError( error: error, source: .source, attributes: [ "operation": "riskyOperation", "timestamp": Date().timeIntervalSince1970 ] ) } ``` ## 获取符号化的堆栈跟踪 崩溃报告中的堆栈默认为内存地址。通过上传 dSYM 符号文件，可以将这些地址转换为可读的函数名、文件名和行号。 ### 什么是 dSYM 文件 dSYM（Debug Symbol）文件包含了应用的调试符号信息，用于将崩溃堆栈中的内存地址映射到源代码位置。 ### 使用命令行工具上传 dSYM ```bash theme={null} npm install -g @flashcat/flashcat-ci ``` ```bash theme={null} export FLASHCAT_API_KEY="" flashcat-ci dsyms upload /path/to/dSYMs ``` **支持的文件格式：** * `.dSYM` 目录 * `.dSYM.zip` 压缩包 * 包含多个 dSYM 的 `.zip` 压缩包 ### 在 CI/CD 中集成 dSYM 上传 #### Xcode Build Phase 脚本 在 Xcode 项目的 Build Phases 中添加 Run Script： ```bash theme={null} #!/bin/bash if [ "$CONFIGURATION" = "Release" ]; then export FLASHCAT_API_KEY="" flashcat-ci dsyms upload "${DWARF_DSYM_FOLDER_PATH}" fi ``` #### Fastlane 集成 在 `Fastfile` 中添加上传步骤： ```ruby theme={null} lane :upload_dsyms do ENV["FLASHCAT_API_KEY"] = "" sh("flashcat-ci dsyms upload #{lane_context[SharedValues::DSYM_OUTPUT_PATH]}") end ``` ### Bitcode 应用的 dSYM 如果您的应用启用了 Bitcode，Apple 会在 App Store 处理时重新编译应用，生成新的 dSYM 文件。您需要从 App Store Connect 下载这些 dSYM 并上传。 #### 下载 Bitcode dSYM 访问 [App Store Connect](https://appstoreconnect.apple.com) 并登录您的账号。 进入您的应用 → 活动 → 选择需要下载 dSYM 的构建版本。 点击「下载 dSYM」按钮，下载完成后使用 flashcat-ci 工具上传。 ### dSYM 文件限制 * 每个 dSYM 文件大小限制为 **2 GB** * 仅真实设备上的崩溃支持符号化，模拟器生成的崩溃不支持 ## 追踪后台事件 默认情况下，只有在视图处于活动状态时发生的崩溃才会被追踪。如果您希望追踪应用在后台时发生的崩溃，可以启用后台事件追踪： ```swift theme={null} import FlashcatRUM RUM.enable( with: RUM.Configuration( applicationID: "", trackBackgroundEvents: true ) ) ``` 追踪后台事件可能会产生额外的会话，这可能会影响计费。如有疑问，请联系 Flashcat 支持团队。 ## 限制与注意事项 ### 崩溃检测限制 * **SDK 初始化时机**：崩溃只有在 SDK 和 `CrashReporting.enable()` 调用之后才能被检测到。建议尽早初始化。 * **调试器干扰**：在 Xcode 调试器连接时，崩溃会被调试器捕获而非 SDK。测试崩溃报告时，请在不连接调试器的情况下运行应用。 * **崩溃报告上传时机**：崩溃报告会在应用下次启动时上传，因此崩溃发生后需要重新启动应用才能看到报告。 ### 符号化限制 * 仅真实设备上的崩溃支持符号化，模拟器生成的崩溃不支持。 * 每个发布版本都需要上传对应的 dSYM 文件。 * 如果使用 Bitcode，需要从 App Store Connect 下载并上传重新生成的 dSYM。 ### App Hang 检测限制 * App Hang 检测仅在应用处于前台时有效。 * 检测精度取决于阈值设置，过低的阈值可能产生大量误报。 ## 测试验证 ### 验证崩溃报告 1. **不连接调试器运行应用**：从 Xcode 停止应用，然后从设备上直接启动。 2. **触发测试崩溃**： ```swift theme={null} func triggerTestCrash() { fatalError("测试崩溃") } ``` 3. **重启应用**：崩溃发生后，从设备上重新启动应用，等待 SDK 上传崩溃报告。 4. **查看报告**：在 Flashcat 控制台的异常追踪模块中查看崩溃报告。 ### 验证 App Hang 1. 在主线程执行耗时操作： ```swift theme={null} func blockMainThread() { Thread.sleep(forTimeInterval: 5) // 阻塞主线程 5 秒 } ``` 2. 触发该操作后尝试与应用交互。 3. 检查 Flashcat 控制台是否收到 App Hang 报告。 ### 验证符号化 1. 确保已上传对应版本的 dSYM 文件。 2. 触发崩溃并查看报告。 3. 确认堆栈中显示的是函数名、文件名和行号，而非纯内存地址。 ## 错误数据结构 每条错误数据包含以下属性： | 属性 | 类型 | 描述 | | ---------------- | ------- | ---------------------------------------- | | `error.source` | string | 错误来源（如 `source`、`network`、`custom`） | | `error.type` | string | 错误类型（如 `NSException`、`Signal`） | | `error.message` | string | 错误消息 | | `error.stack` | string | 错误堆栈跟踪 | | `error.is_crash` | boolean | 是否为崩溃 | | `context` | Object | 自定义上下文信息，通过 `addError` 的 `attributes` 传入 | ## 最佳实践 1. **尽早初始化 SDK**：在 `application(_:didFinishLaunchingWithOptions:)` 中尽早调用 `Flashcat.initialize()` 和 `CrashReporting.enable()`。 2. **正确上传 dSYM**： * 为每个发布版本上传对应的 dSYM 文件 * 在 CI/CD 流程中集成 dSYM 上传 * 如果使用 Bitcode，及时从 App Store Connect 下载并上传 dSYM 3. **合理设置 App Hang 阈值**：根据应用性能要求设置合适的阈值，避免过多误报。 4. **丰富错误上下文**：在手动上报错误时，附加业务相关的上下文信息（如用户 ID、操作类型）。 5. **测试时断开调试器**：验证崩溃报告功能时，确保不连接 Xcode 调试器。 ## 下一步 了解如何在异常追踪模块查看和分析 Issue 配置 iOS SDK 的高级功能 # Web 异常上报 Source: https://docs.flashduty.com/zh/rum/error-tracking/erro-reporting/web 了解 RUM 的异常上报机制 本文档介绍异常类型、捕获机制、手动上报方法、React 集成以及上报的异常数据结构定义。 ## 异常类型 RUM 可以监控以下类型的异常： 包括代码语法错误、运行时异常和未处理的 Promise 异常等。这些问题可能导致页面功能失效，严重影响用户体验。 监控与后端服务或第三方 API 的通信问题： * XHR/Fetch 请求失败 * 请求超时 * 跨域（CORS）错误 * HTTP 4xx/5xx 状态码 监控网页资源加载失败的情况： * 图片加载失败 * 脚本加载失败 * 样式表加载失败 * 字体文件加载失败 除了自动捕获的异常外，您还可以使用 RUM SDK 手动上报自定义异常，用于跟踪业务逻辑错误等特定问题。 ## 上报方式 ### 自动错误捕获 RUM SDK 自动捕获以下类型的浏览器错误： | 错误类型 | 说明 | | --------------- | ---------------------------------------------------- | | 未捕获的异常 | 运行时抛出的 JavaScript 异常（如 `TypeError`、`ReferenceError`） | | 未处理的 Promise 拒绝 | 未被 `.catch()` 处理的 Promise 错误 | | 网络错误 | XHR 或 Fetch 请求失败（如 4xx、5xx 状态码或网络中断） | | React 渲染错误 | React 组件渲染期间的异常（需配合错误边界） | * 自动捕获的错误默认包含堆栈跟踪、错误消息和来源信息。 * 来自浏览器扩展或第三方脚本的错误（如 `network` 来源）会被过滤，避免数据污染。 ### 手动错误上报 通过 `addError` API，您可以手动上报已处理的异常、自定义错误或其他未被自动捕获的错误。 **适用场景：** * 记录业务逻辑中的已处理错误 * 附加上下文信息（如用户 ID、页面状态）以便问题排查 * 监控第三方服务或异步操作的异常 ```javascript 上报自定义错误 theme={null} // 上报带有上下文的自定义错误 const error = new Error("登录失败"); window.FC_RUM.addError(error, { pageStatus: "beta", userId: "12345", action: "login_attempt", }); ``` ```javascript 上报网络错误 theme={null} fetch("https://api.example.com/data").catch((error) => { window.FC_RUM.addError(error, { requestUrl: "https://api.example.com/data", method: "GET", }); }); ``` ```javascript 上报已处理异常 theme={null} try { // 可能抛出异常的业务逻辑 riskyOperation(); } catch (error) { window.FC_RUM.addError(error, { operation: "riskyOperation", timestamp: Date.now(), }); } ``` ### React 错误边界集成 RUM 支持通过 React [错误边界](https://legacy.reactjs.org/docs/error-boundaries.html)捕获组件渲染错误，并将错误信息上报。您可以在 `componentDidCatch` 中调用 `addError` API，附加组件堆栈信息以便调试。 ```javascript theme={null} class ErrorBoundary extends React.Component { componentDidCatch(error, info) { const renderingError = new Error(error.message); renderingError.name = "ReactRenderingError"; renderingError.stack = info.componentStack; // 组件堆栈 renderingError.cause = error; // 原始错误 window.FC_RUM.addError(renderingError, { component: this.props.componentName || "Unknown", version: "1.0.0", }); } render() { return this.props.children; } } ``` ```jsx theme={null} ``` ## 错误数据结构 每条错误数据包含以下属性，用于描述错误详情和上下文： 错误来源（如 `console`、`network`、`custom`、`source`、`report`）。微信小程序 SDK 还会上报 `app`（来自 `wx.onError`）和 `promise`（来自 `wx.onUnhandledRejection`）两个值，详情见[微信小程序数据采集](/zh/rum/sdk/wechat-miniprogram/data-collection)。 错误类型或错误码（如 `TypeError`、`NetworkError`） 简洁的可读性强的错误消息 错误堆栈跟踪或补充信息 提供额外上下文的关联错误列表（可选） 自定义上下文信息（如页面状态、用户 ID），通过 `addError` 传入 ## 错误过滤与配置 为确保错误数据的准确性和相关性，RUM 应用以下过滤规则： * 仅处理 `source` 为 `custom`、`source`、`report` 或 `console` 的错误 * 忽略来自浏览器扩展、第三方脚本或 `network` 来源的无关错误 错误必须包含堆栈跟踪信息，否则可能被忽略 使用 `beforeSend` 回调自定义错误处理逻辑，过滤或修改错误数据 ### 自定义错误过滤示例 ```javascript theme={null} window.FC_RUM.init({ beforeSend: (event) => { if (event.type === "error") { // 忽略特定错误消息 if (event.error.message.includes("ThirdPartyScript")) { return false; // 丢弃该错误 } // 添加全局上下文 event.context = { ...event.context, appVersion: "2.1.0" }; } return true; }, }); ``` ## 常见问题 * 确认堆栈跟踪是否完整，或自定义指纹是否冲突 * 检查 `sourcemap` 是否正确上传，若未上传，堆栈可能无法正确解析 使用 `beforeSend` 回调过滤特定错误来源或消息： ```javascript theme={null} beforeSend: (event) => { if (event.error.source === "network") return false; return true; }; ``` * 确保 `fingerprint` 属性正确设置，且值为字符串 * 检查 `beforeSend` 回调是否被正确调用 ## 最佳实践 在 `addError` 中附加业务相关上下文（如用户 ID、操作类型），便于问题定位。 示例：`{ userId: "12345", action: "submit_form" }` 为关键 React 组件配置错误边界，确保渲染错误被捕获。记录组件名称和版本，便于追踪问题。 使用采样率或 `beforeSend` 过滤低价值错误，避免数据过载。优先监控影响用户体验的关键错误。 在「分析看板」-「异常分析」Tab 查看错误数据趋势和分布，解决重点异常问题。 ## 下一步 了解如何在异常追踪模块查看和分析 Issue # 异常聚合 Source: https://docs.flashduty.com/zh/rum/error-tracking/error-aggregation 了解 Flashduty RUM 的异常聚合机制，提高 Issue 定位效率。 当新错误事件发生时，Flashduty 采用三步聚合策略将错误聚合为 Issue，有效减少需要处理的错误数量。 ## 聚合流程 获取错误事件的指纹，并与现有 Issue 的指纹比较 如果新事件与现有某个 Issue 共享相同指纹，则自动归入该 Issue 如果指纹未匹配，则利用机器学习模型分析错误相似度，将事件归入相似度最高的 Issue，或在相似度过低时创建新的 Issue。 **Android NDK 原生崩溃例外：** NDK 原生崩溃（`source_type` 含 `ndk` 或堆栈中存在应用层原生帧）会跳过此步骤的机器学习相似度分析，完全依赖步骤一的确定性指纹进行聚合。这是因为 NDK 崩溃的错误消息（如 `signal: SIGSEGV`）几乎完全相同，若走相似度分析会将来自不同代码位置的崩溃错误地合并为同一 Issue；而帧感知指纹能够精确区分不同的崩溃点。 **Flutter 原生崩溃按真实平台处理：** Flutter 应用上报的原生崩溃 `source` 为 `flutter`，聚合时会按 `source_type`（`ndk`、`android`、`ios`）解析出真实平台。其中 `source_type` 为 `ndk`（或堆栈中存在应用层原生帧）的崩溃与 Android NDK 崩溃一致，同样跳过机器学习相似度分析、使用原生帧指纹聚合；`source_type` 为 `ios` 的崩溃仍走消息指纹，与独立 iOS 应用的行为相同。 ## 默认指纹 Flashduty 默认启用异常聚合，无需额外配置即可开始工作。Browser SDK 会自动收集错误数据并进行聚合。 在 HTML 文件中引入 Flashduty Browser SDK： ```html theme={null} ``` 初始化 SDK 时，指定应用 ID 和环境： ```javascript theme={null} window.FLASHCAT_RUM.init({ applicationId: "rum-application-id", environment: "production", version: "1.0.0", }); ``` ### 指纹计算规则 当错误事件没有携带指纹时，Flashduty 基于以下错误属性自动计算指纹： | 属性 | 说明 | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `service` | 错误发生的服务 | | `env` | 错误发生的环境 | | `error.type` | 错误的类型分类 | | `error.message` | 错误的描述文本。对于 Android NDK 原生崩溃，此分量会附加堆栈中最顶层的应用层原生帧信息，格式为 `\|native::`（例如 `signal: SIGSEGV\|native:libmyapp.so:crash_func+48`）。系统库帧（`libc.so`、`libart.so` 等）和伪映射（`[vdso]`、`[stack]`）会被跳过，以确保同一崩溃位置在不同运行时始终产生相同指纹。 | 为提高聚合准确性，Flashduty 会去除堆栈帧中的变量属性，如版本号、ID、日期等动态参数。 ## 自定义指纹 若默认聚合无法满足需求，您可以通过提供自定义指纹（fingerprint）完全控制错误的聚合行为。 自定义指纹的优先级高于默认指纹。 在手动报告错误时，通过 `addError` 添加自定义指纹： ```javascript theme={null} window.FLASHCAT_RUM.addError(new Error("My error message"), { source: "custom", fingerprint: "my-custom-grouping-fingerprint", }); ``` 通过 `beforeSend` 回调动态设置指纹： ```javascript theme={null} window.FLASHCAT_RUM.init({ applicationId: "rum-application-id", environment: "production", beforeSend: (event) => { if (event.type === "error") { event.error.fingerprint = "my-custom-grouping-fingerprint"; } return true; }, }); ``` * 自定义 fingerprint 必须为字符串类型 * 相同服务中具有相同 fingerprint 的错误将被归入同一 Issue * 不同服务的错误即使 fingerprint 相同也会被归入不同 Issue * `beforeSend` 回调还可用于过滤无关错误（如第三方脚本错误） ## Web 特定注意事项 上传 `sourcemap` 文件以解码压缩后的堆栈跟踪，确保聚合后的错误堆栈可映射到原始源代码。 ```bash theme={null} flashcat-cli sourcemaps upload \ --service my-service \ --release-version 1.0.0 \ --minified-path-prefix /assets \ --api-key your-api-key \ ./dist ``` 默认情况下，Flashduty 会过滤来自浏览器扩展或第三方脚本的错误（如 `network` 来源），以减少噪声。 可通过 `beforeSend` 进一步自定义过滤规则： ```javascript theme={null} beforeSend: (event) => { if ( event.error.source === "network" && event.error.message.includes("ThirdPartyScript") ) { return false; // 丢弃该错误 } return true; }; ``` ## 查看聚合结果 在 Flashduty 平台，导航至「异常追踪」，查看聚合后的 Issue 列表。 也可以从应用列表直达：应用卡片上的 **Issue** 数字可以点击，点击后跳转到该应用的异常追踪列表，并自动锁定与卡片一致的口径——最近 24 小时、状态为「全部」，同时清除上次遗留的筛选条件，因此列表里的条数与卡片上的数字一致。 每个 Issue 包含： | 内容 | 说明 | | --------- | --------------------------- | | 错误消息和堆栈跟踪 | 若上传了 `sourcemap`，会显示原始源代码位置 | | 用户会话时间线 | 触发错误的操作路径 | | 元数据 | 浏览器类型、版本号等 | ## 下一步 了解 Issue 状态流转机制 # Issue 概览与详情 Source: https://docs.flashduty.com/zh/rum/error-tracking/error-viewing 了解 Flashduty RUM 如何将相似错误聚合为 Issue，并查看发生记录、堆栈、影响用户和关联上下文。 错误上报后可在异常追踪模块查看 Issue。在 Flashduty RUM 中，一个 Issue 是由一组相似错误组成的，这些错误通常与同一个 bug 相关。 Issue 列表 详细的聚合规则请参阅 [异常聚合](./error-aggregation)。 ## Issue 信息概览 Issue 信息概览 Issue 浏览器中列出的每个条目包含以下信息： | 信息项 | 描述 | | ----------- | ------------- | | 错误类型和错误消息 | Issue 的核心标识信息 | | 错误发生的文件路径 | 定位错误来源 | | 服务名称 | 关联的服务 | | 错误原因 | 系统推断的可能根因 | | 问题是否有复现 | 标识已解决问题是否再次出现 | | 首次和最后出现时间 | Issue 生命周期信息 | | 发生次数图表 | 随时间变化的趋势 | | 所选时间段内的发生次数 | 统计数据 | ## Issue 状态 Issue 有 4 种状态，流转方式如下： Issue 状态流转 | 状态 | 说明 | | ------- | ----------- | | **待处理** | 新发现的问题，需要关注 | | **处理中** | 已确认并正在修复的问题 | | **已解决** | 问题已修复 | | **已忽略** | 无需处理的问题 | 问题复现相关流转逻辑请参阅 [Issue 状态](./issue-status)。 ## 筛选与排序 浏览器右上角显示时间轴，允许您显示在选定时间段内发生错误的 Issue。您可以： * 从下拉菜单中选择预设范围 * 直接修改时间 * 输入自然语言进行筛选 | 排序选项 | 说明 | | ----- | ------------------- | | 更新时间 | 根据问题更新时间排序（默认） | | 创建时间 | 根据首次发现时间排序 | | 发生次数 | 根据所选时间范围内错误的总发生次数排序 | | 影响会话数 | 根据受影响的 RUM 会话数量排序 | Flashduty RUM 自动为您的 Issue 建立预定义的属性索引，并创建对应的筛选器。 筛选器 支持的属性包括： | 属性 | 描述 | | ------- | ---------------------------------- | | 错误原因 | 错误发生时可能的根因类型 | | 环境 | Issue 上报时的 env 字段 | | 服务 | Issue 上报时的 service 字段 | | 错误类型 | 上报的 error 事件中的 error.type 字段 | | 错误信息 | error 事件中的 error.message 字段，支持模糊匹配 | | IssueID | Issue 聚合时的 ID，多个 ID 之间可用逗号分割 | | 问题复现 | 已解决的问题如果再次发生，则 Issue 会被标记为复现 | | 指纹 | Issue 聚合时的指纹信息，多个指纹之间可用逗号分割 | ## 错误原因分类 Flashcat 在每次创建 Issue 时会为其添加错误发生可能产生的错误原因分类，帮助提升故障定位的效率。 | 错误原因 | 说明 | | -------- | ------------------------- | | 代码错误 | 由代码缺陷导致的错误 | | 非法对象访问 | 代码访问了 null 或 undefined 对象 | | 无效参数 | 使用无效参数调用函数 | | 网络错误 | 服务器响应时间过长或网络速度慢 | | API 请求失败 | API 端点返回了错误状态码 | | 未知错误 | 无法定位该错误类型 | 当鼠标在错误原因分类上 hover 时，系统会结合 AI 能力进一步给出推断的根因和修复建议。 ### 分类原理 系统采用两层分析机制对错误进行分类： **第一层：模式匹配** 系统首先通过规则引擎按优先级依次检查错误类型和错误消息，首个匹配的规则决定分类结果： | 检查顺序 | 匹配条件 | 分类结果 | | ---- | ------------------------------------------------------------------ | -------- | | 1 | 错误消息包含 "Unexpected token ... is not valid JSON" | 无效参数 | | 2 | 关联资源的 HTTP 状态码为 4xx 或 5xx | API 请求失败 | | 3 | 错误类型包含 "Network" 或 "AbortError" | 网络错误 | | 4 | 错误类型包含 "Syntax"、"Reference"、"Range"、"URI" 或 "Eval" | 代码错误 | | 5 | 错误类型为 TypeError 且消息匹配空值访问模式（如 "Cannot read property of undefined"） | 非法对象访问 | | 6 | 错误消息匹配无效参数模式（如 "invalid argument"、"unexpected token"） | 无效参数 | | 7 | 错误消息包含 "API ERROR:" 或许可证相关错误 | API 请求失败 | | 8 | 错误消息包含网络连接相关关键词（如 "timeout"、"connection"、"dns"） | 网络错误 | | 9 | 以上均未匹配 | 未知错误 | **第二层：AI 推断** 当模式匹配结果为「未知错误」时，系统会调用 AI 模型进行深度分析。AI 模型会结合以下信息进行判断： * **错误消息**：错误的描述文本 * **堆栈信息**：完整的调用堆栈 * **平台类型**：浏览器/JavaScript、Android/Kotlin/Java、iOS/Swift/Objective-C、微信小程序等 AI 会输出错误分类和简要的原因解释（不超过 100 字）。推断结果在 Issue 卡片上以 hover 提示的形式展示，帮助您快速理解错误的根因。 ## 问题复现 问题复现（Regression）指的是之前修复的 bug 再次出现。 问题复现 如果一个错误被标记为已解决，但在后续（version 不同）又产生了相同的错误，则该 Issue 的状态会从结束态重新打开，并标记为「问题复现」。 ## Issue 详情 Issue 列表支持两种查看模式：侧栏模式和全屏模式。默认以侧栏方式打开详情面板，您也可以点击展开按钮切换到全屏模式，获得更宽敞的查看空间和更完整的数据展示。 点击任何 Issue 可以打开详情面板，查看更多信息。 Issue 详情 面板上部显示 Issue 的基础信息，如状态、错误原因等。您还可了解 Issue 的生命周期：首次和最后出现日期、持续时间，以及时间内的错误发生次数（按照一定时间粒度聚合）。 在标签分布区块可按照各种维度查看该 Issue 下不同标签所占比重，从而快速判断问题影响范围，辅助定位根因。 目前支持 `view_name`、`browser_name`、`version`、`env` 等标签。 默认展示当前 Issue 发生期间最近一次上报的错误信息作为错误样例，您也可通过导航条进行切换。 对于 Native 崩溃，样例导航列表中的每条样例都会标注符号化状态（「已解析」/「未解析」徽标）。当最新一条样例尚未解析、而更早的样例可以符号化时，详情会自动切换到可符号化的样例，并提示「已自动切换到可符号化的样例（最新一条尚未解析）」；点击「回到最新」可切回最新上报的样例。 查看错误的上下文信息和堆栈信息。如果已上传对应的 SourceMap、Android mapping 文件、iOS dSYM 文件或 Flutter 符号文件，您可以看到映射还原后的原始源码位置和代码片段。 错误堆栈 在「应用管理」-「源码管理」可查看已上传的源码信息，详见 [源码映射](./source-mapping)。 Native 平台（Android/iOS）的错误堆栈展示针对移动端特点进行了专门设计，提供以下能力： **Pretty / Raw 模式切换** * **Pretty 模式**：结构化展示堆栈信息，自动区分应用帧（app frames）和第三方帧（third-party frames），第三方帧默认折叠，突出显示您自己的代码 * **Raw 模式**：展示原始堆栈文本，方便复制和在外部工具中分析 **符号化状态** 如果已上传对应版本的符号文件（Android mapping 或 iOS dSYM），堆栈中的混淆地址会被自动还原为可读的函数名、文件名和行号。未符号化时，系统会提示您上传符号文件，并提供直达「源码管理」和上传工具的链接。 符号化结果会被缓存。如果为一条已经出现过的崩溃补传了符号文件，点击提示条或「本条崩溃所需符号」区块中的「重新解析」按钮，即可跳过缓存强制重新执行符号化（重新拉取 dSYM 并完整还原），并刷新当前堆栈，无需等待新的崩溃上报。 **线程堆栈（Threads）** Native 崩溃通常涉及多个线程。线程面板展示崩溃时所有线程的堆栈信息，支持： * 查看线程总数和当前展示的线程数 * 展开/折叠所有线程 * 每个线程内独立区分应用帧和第三方帧，第三方帧可按需展开查看 * 崩溃线程的堆栈会被优先展示 **Binary Images（iOS）** 对于 iOS 崩溃，还可以查看崩溃时加载的 Binary Images（二进制镜像）列表，包含镜像名称、地址范围和 UUID 等信息，用于辅助离线符号化分析。 **本条崩溃所需符号（非系统库）** 当崩溃事件携带非系统二进制镜像时（iOS、Electron 等通过二进制镜像还原地址的 Native 崩溃，含 Flutter 的 iOS 原生崩溃），堆栈上方会展示「本条崩溃所需符号（非系统库）」区块，列出本条崩溃引用的所有非系统二进制镜像及其符号化状态： * 区块标题汇总为「已解析数/总数 已解析」；全部已解析时默认折叠为一行摘要，存在未解析镜像时默认展开 * 每个镜像一行，展示镜像名称、UUID 以及「已解析」/「未解析」徽标，并提供复制 UUID 的按钮 * 点击「在符号表中查找」跳转到「源码映射」页面，并按该镜像的 UUID 预筛选符号表 * 未解析的镜像提供「去上传」链接，直达「源码映射」页面的上传入口 * 未解析时也可以点击区块中的「重新解析」按钮，强制重新符号化并刷新堆栈 **Flutter 支持** Flutter 原生崩溃（`source_type` 为 `ndk`、`android` 或 `ios`）携带线程堆栈和 Binary Images，与 Android/iOS 原生崩溃一样使用上述 Native 渲染展示；Dart 异常则按堆栈中的 build\_id 匹配已上传的 Flutter 符号文件，进行符号化还原。 详细的符号文件上传流程请参阅 [源码映射](./source-mapping)。 查看当前错误示例所属的 Session 事件总数，以及该异常发生前后用户的资源访问情况和操作情况。 当前最多展示包含当前 Error 事件在内的 20 条上下文信息，后续您可在 Session 查看器模块查看更多日志信息。 如果该会话已采集了回放数据，您可以直接点击「查看回放」按钮跳转到会话重放页面，从用户视角重现错误发生时的完整操作路径。 异常事件在上报时会携带一系列属性，您可在属性区块查看当前的 Session、视图、用户等各类信息，方便排查问题。 ## 异常告警 在问题发生时立即发现它，让您有机会在问题变得严重之前主动识别和修复它。 异常告警配置 选中应用卡片后进行编辑 打开「告警」开关 选择通知的协作空间 具体告警配置说明请参阅 [Issue 告警](./issue-alerts)。 ## 最佳实践 便于在生产环境定位问题 配置用户相关信息，提供更好的错误上下文 为错误配置合理的协作空间和分派策略 定期检查错误报告，发现潜在问题 利用团队所有权功能确保问题能够快速分配给相关团队 密切关注已解决问题的潜在回归 ## 下一步 配置源码映射 了解聚合机制 管理 Issue 状态 # Issue 告警 Source: https://docs.flashduty.com/zh/rum/error-tracking/issue-alerts 了解 Flashduty RUM Issue 如何触发告警，以及如何配置告警分级和数据过滤 Flashduty RUM 自动将 SDK 上报的错误事件聚合为 Issue，帮助您优先处理最具影响力的问题，减少服务停机时间和用户沮丧感。 您可以在控制台每日巡检 Issue，也可以配置告警通知，在问题发生时第一时间感知。Flashduty RUM 的告警能力包括： * **告警通知**：将 Issue 以告警事件投递到 Flashduty 协作空间，通过分派策略通知值班人员 * **Webhook 投递**：将 Issue 告警直接 POST 到您的接收端，适合不启用 On-call 的 RUM 私有化环境或自建通知链路 * **告警分级**：根据错误属性（如用户、页面、环境等）自定义告警优先级 * **数据过滤**：在 Error 聚合为 Issue 之前过滤噪音数据，减少无效告警 ## 开启告警 前往「应用管理」，选择目标应用，点击左侧「告警设置」 开启告警开关，并选择投递方式：Flashduty 协作空间或 Webhook 如果选择 Flashduty 协作空间，告警的通知规则遵循协作空间下的分派策略，您可以为团队设定值班人员，在告警发生时分派给值班人 如果选择 Webhook，填写您的接收端 URL。保存前可以点击「发送测试事件」验证地址是否可访问、接收端是否能解析示例告警事件 告警设置 只有选择「Flashduty 协作空间」投递时才需要开通 On-call 服务。选择 Webhook 投递时，RUM 会直接向您配置的 URL 发送告警事件，不会创建或使用 On-call 集成。 ## 投递方式 | 投递方式 | 适用场景 | 配置要求 | 后续处理 | | -------------- | --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------- | | Flashduty 协作空间 | 需要在 Flashduty 内完成故障协同、值班分派、通知升级和告警处理 Pipeline | 选择一个或多个协作空间；如果未选择协作空间，告警不会被投递 | Issue 告警进入对应协作空间，继续走集成配置、降噪配置和分派策略 | | Webhook | RUM-only 私有化部署、自建通知系统，或希望把 Issue 告警直接送到外部接收端 | 填写可访问的 Webhook 地址。开启告警并选择 Webhook 时，地址不能为空 | RUM 直接向该 URL POST 示例或真实告警事件；钉钉、企业微信等机器人需要您的接收端做格式转换后再转发 | Webhook 配置区提供「发送测试事件」按钮。测试会向当前填写的 URL 发送一条示例告警事件，并返回 HTTP 状态码和结果信息，便于您在保存前确认网络连通性和接收端解析逻辑。 ## 告警触发条件 | 触发条件 | 说明 | | --------------- | ------------------------------------------------------------------------------------------------ | | **新的 Issue** | 错误事件导致新的 Issue 出现，会触发告警事件 | | **Issue 更新** | 持续有错误事件合入一个未关闭（待处理、处理中）的 Issue，且距离上一个触发告警事件超过 24 小时，将会重新触发告警事件 | | **Issue 重开** | 新的错误合入已关闭的 Issue，导致 Issue 被重新打开，即问题复现 | | **Issue 优先级升级** | 当高优先级的错误事件进入低优先级的 Issue 时，Issue 优先级会自动升级并触发新的告警事件。例如，一个 P2 级别的 Issue 收到匹配 P0 规则的错误，会升级为 P0 并触发告警 | * Issue 触发的是一个告警事件，实际投递位置取决于您在告警设置中选择的投递方式 * 选择 Flashduty 协作空间时，是否触发通知取决于协作空间下的集成配置、降噪配置以及分派策略 * 选择 Webhook 时，RUM 直接向 Webhook URL 投递事件；后续通知、格式转换和重试策略由您的接收端负责 * 当 Issue 关闭时，系统会触发关闭类型的告警事件；如果走协作空间投递，其关联的故障可能会自动恢复 ## 告警严重程度 ### 默认分级规则 如果未配置自定义告警分级规则，Issue 触发的告警严重程度由系统自动判定： | 条件 | 严重程度 | | ---------------- | -------- | | Issue 存在时间超过 7 天 | Info | | 崩溃问题 | Critical | 通过累积分数确定等级： | 分数范围 | 严重程度 | | ------ | ------------ | | ≥70 分 | Critical（严重） | | ≥40 分 | Warning（警告） | | \<40 分 | Info（提示） | | 因素 | 评分规则 | | ---------- | ------------------------------------ | | **环境影响** | 生产环境（50分）、预发环境（30分）、其他环境（10分） | | **错误关键词** | 包含严重关键词（+30分）或警告关键词（+15分） | | **可疑原因** | API 失败（+20分）、代码异常（+15分）、未知/网络错误（+5分） | | **问题持续时间** | 超过 24 小时（+20分）、超过 12 小时（+10分） | ### 自定义告警分级 您可以在「告警设置」中配置自定义告警分级规则，根据错误的属性特征设定告警优先级（P0 / P1 / P2），实现更精细的告警控制。 自定义分级规则在 Error 上报时评估，得到「预置优先级」。当 Error 聚合到 Issue 时： * **新建 Issue**：Issue 的优先级由首个 Error 的预置优先级决定 * **匹配已有 Issue**：如果 Error 的预置优先级更高，Issue 优先级自动升级（只升不降） * **未匹配任何规则**：使用默认优先级 P2 每条分级规则包含以下要素： | 要素 | 说明 | | -------- | --------------------------------------------- | | **规则名称** | 便于识别和管理的名称 | | **匹配条件** | 基于 Error 属性的筛选条件，同一规则内多个条件为 AND 关系 | | **告警级别** | 匹配后设定的优先级：P0（Critical）/ P1（Warning）/ P2（Info） | 规则按优先级顺序从上到下逐条评估，**首个匹配的规则立即生效**，后续规则不再检查。您可以通过拖拽调整规则顺序来改变优先级。 每个应用最多可配置 **6 条**告警分级规则。每条规则最多支持 **2 组** OR 条件组，每组最多 **3 个** AND 条件，每个条件最多可填写 **8 个**匹配值。 #### 支持的匹配字段 | 字段 | 说明 | 示例 | | ------------------------------ | ----------- | ------------------------- | | 用户 ID（`error.usr_id`） | 上报错误的用户标识 | `vip_001` | | 用户邮箱（`error.usr_email`） | 用户邮箱地址 | `*@vip.com` | | 页面 URL（`error.view_url`） | 错误发生的页面完整地址 | 包含 `/payment` | | 错误类型（`error.error_type`） | 错误的类型分类 | `TypeError`、`SyntaxError` | | 错误消息（`error.error_message`） | 错误的描述文本 | 包含 `Cannot read property` | | 堆栈（`error.error_stack`） | 错误的堆栈信息 | 包含 `at handleClick` | | 环境（`error.env`） | 错误发生的环境 | `production`、`staging` | | 服务（`error.service`） | 错误所属的服务 | `payment` | | 版本（`error.version`） | 应用版本号 | `1.2.0` | | 浏览器（`error.browser_name`） | 浏览器名称 | `Chrome`、`Safari` | | 浏览器版本（`error.browser_version`） | 浏览器版本号 | `120.0` | | 是否崩溃（`error.is_crash`） | 是否为崩溃错误 | `true` | 匹配方式支持「包含」和「不包含」两种操作。 #### 配置示例 为 VIP 用户的错误设置最高优先级，确保第一时间响应： * 匹配条件：用户 ID 包含 `vip` * 告警级别：P0（Critical） 支付页面是核心业务流程，相关错误需要优先处理： * 匹配条件：页面 URL 包含 `/payment` * 告警级别：P1（Warning） 生产环境的崩溃需要立即响应： * 匹配条件：环境 包含 `production`，且 是否崩溃 包含 `true` * 告警级别：P0（Critical） * Issue 的优先级只升不降，确保重要问题不会被后续低优先级的错误降级 - 如需根据 Issue 的影响范围（如影响用户数、错误数量等）调整优先级，请在 Flashduty 集成的[告警处理 Pipeline](/zh/on-call/integration/alert-integration/alert-pipelines) 中配置 ## 数据过滤 数据过滤允许您在 Error 聚合为 Issue **之前**过滤掉不需要关注的噪音数据。被过滤的 Error 不会参与 Issue 聚合，也不会产生告警。 您可以在「告警设置」中添加过滤规则。每条规则可设置多个匹配条件，同一规则内的条件为 AND 关系。支持的匹配字段与[自定义告警分级](#自定义告警分级)一致。 | 场景 | 示例规则 | | --------- | ----------------------------- | | 排除第三方脚本错误 | 错误堆栈 包含 `cdn.third-party.com` | | 排除已知无害错误 | 错误消息 包含 `ResizeObserver loop` | | 排除调试页面错误 | 页面 URL 包含 `/debug` | * 被过滤的 Error 不会参与 Issue 聚合和告警，但数据仍然保留，可在查看器中通过筛选条件查看 - 如果只是想暂时屏蔽某类告警但保留 Issue 数据，建议使用 Flashduty 告警处理 Pipeline 中的「告警丢弃」功能 ## 与 Flashduty 协同 RUM 告警与 Flashduty 深度协同，形成完整的告警处理链路： | 层级 | 配置位置 | 核心能力 | 适用场景 | | ---- | -------------- | ---------------- | ------------------- | | 数据过滤 | RUM 告警设置 | 过滤噪音 Error | 永久忽略第三方脚本错误、调试页面错误等 | | 告警分级 | RUM 告警设置 | 根据 Error 属性设定优先级 | VIP 用户告警、核心页面告警等 | | 告警处理 | Flashduty 集成配置 | 标题定制、优先级调整、丢弃/抑制 | 根据影响用户数调整级别、抑制重复告警等 | | 告警分派 | Flashduty 协作空间 | 路由、值班排班、通知渠道 | 分派到不同团队、配置通知方式等 | 选择 Flashduty 协作空间投递时，您可以在 Flashduty 的[告警处理 Pipeline](/zh/on-call/integration/alert-integration/alert-pipelines) 中进一步处理 RUM 告警，例如根据影响用户数调整告警级别、按时间窗口抑制重复告警、自定义告警标题格式等。选择 Webhook 投递时，RUM 告警不会进入这条 On-call 处理链路，请在您的接收端完成格式转换、路由和通知。 ## 延伸阅读 典型场景配置方案，快速减少无效告警干扰 在集成层对告警进行清洗、转换和过滤 在协作空间层面聚合和抑制告警 配置分派策略，将告警路由到正确的值班人员 # Issue 状态 Source: https://docs.flashduty.com/zh/rum/error-tracking/issue-status 了解 Flashduty RUM Issue 状态流转情况 在异常追踪中，所有 Issue 都有一个状态，帮助您对问题进行分类和优先级排序。 ## 状态类型 | 状态 | 标识 | 说明 | | ------- | ------------ | -------------------- | | **待处理** | `for_review` | 需要关注的新问题或回归问题 | | **处理中** | `reviewed` | 已分类且需要修复的问题，可立即或稍后处理 | | **已忽略** | `ignored` | 不需要进一步调查或处理的问题 | | **已解决** | `resolved` | 已修复且不再发生的问题 | 所有新发现的 Issue 初始状态为**待处理（for\_review）**。Flashduty 会根据特定条件自动更新状态，您也可以手动调整。 ## 自动解决 Issue Flashduty 会自动将不活跃或已解决的 Issue 标记为**已解决（resolved）**： 如果 Issue 最后一次报告的版本已超过 14 天，且新版本中未再次出现该错误，系统会自动将其解决。 如果未设置 `version` 标签，当 Issue 在过去 14 天内没有新错误报告时，系统会自动将其解决。 正确配置应用程序的 `version` 标签对于准确识别已解决的 Issue 至关重要。 ## 自动重新打开 Issue Flashduty 具备 Issue 检测功能，当已解决的 Issue 再次出现时，系统会自动重新打开并标记为\*\*待处理（for\_review）\*\*状态，同时在活动时间线中记录该事件为「问题复现」状态。 ### 什么是问题复现？ 复现指的是先前已修复的问题在代码更新后意外重新出现。Flashduty 的回归检测可自动识别这些情况，将相关 Issue 重新打开，而不是创建重复的 Issue，从而保留问题的完整上下文和历史记录。 ### 复现检测机制 当满足以下任一条件时，复现检测将被触发： * 如果\*\*已解决（resolved）\*\*的错误在代码的更新版本中重新出现 * 如果在未设置版本标签的情况下，\*\*已解决（resolved）\*\*状态的错误再次出现 一旦检测到问题复现，Flashduty 会： 自动将 Issue 状态变更为**待处理（for\_review）** 为 Issue 添加**问题复现**标签，便于快速识别 ### 关联版本配置 复现检测会考虑错误发生的服务版本信息，只有在 Issue 标记为\*\*已解决（resolved）\*\*后的新版本中才会触发检测。 ```javascript theme={null} window.FLASHCAT_RUM.init({ applicationId: "rum-application-id", environment: "production", version: "1.0.0", // 确保设置正确的版本号 }); ``` 如果不设置版本标签，当已解决的 Issue 再次发生错误时，系统仍会将其标记为「问题复现」，但无法确定是否在新版本中发生。 ## 手动更新状态 您可以在任何显示 Issue 的地方手动更新其状态，包括 Issue 列表或详情面板。 手动更新状态 只需点击当前状态，然后从下拉菜单中选择新状态即可。 ## 最佳实践 定期检查\*\*待处理（for\_review）\*\*状态的 Issue，确保新问题和回归问题得到及时处理 始终为应用程序配置正确的版本标签，以便系统能准确识别已解决的问题 通过有效管理 Issue 状态，您的团队可以更专注于解决重要问题，减少处理噪声的时间，提升整体开发效率。 ## 下一步 了解如何查看和分析异常详情 # 异常追踪 Source: https://docs.flashduty.com/zh/rum/error-tracking/overview 掌握 Flashduty RUM 的异常追踪功能，快速发现并解决网站问题。 Flashduty RUM（Real User Monitoring）是一款强大的用户体验监控工具，专注于帮助开发者快速发现并解决网站和应用中的问题，确保系统稳定性和用户体验的流畅性。它通过自动捕获各类异常信息，并提供详细的上下文数据，让您能够精准定位问题根源，及时采取措施进行修复。 ## 核心功能 自动捕获 JavaScript 异常、网络请求失败、资源加载异常等各类问题，并提供详细的错误堆栈信息和上下文数据 支持自动错误捕获和手动错误上报两种方式，允许您记录业务逻辑中的已处理错误，并附加上下文信息 将相似的异常事件归类为同一个 Issue，减少重复告警，帮助开发团队更高效地识别和处理问题 通过上传 SourceMap 文件，将压缩后的代码映射到原始源代码，直接定位到原始代码的具体位置 ## 价值与优势 | 优势 | 描述 | | ------------ | ---------------------------------- | | **提高问题解决效率** | 快速定位问题根源，减少故障排查时间，提高开发和运维团队的工作效率 | | **优化用户体验** | 及时发现并解决影响用户体验的问题，提升用户满意度和忠诚度 | | **降低业务风险** | 避免因系统故障导致的业务损失，保障业务的稳定运行 | | **提供数据支持** | 详细的异常数据和上下文信息为业务决策提供有力支持，帮助您不断优化产品 | ## 使用场景 在开发过程中，快速定位和解决 JavaScript 代码中的错误，提高开发效率。 实时监控生产环境中的异常情况，及时发现并处理潜在问题，保障系统的稳定性。 了解用户在使用过程中遇到的问题，针对性地改进产品，提升用户体验。 ## 异常追踪流程 Flashduty RUM 的异常追踪分为两个关键阶段：**问题发现** 和 **问题定位**。 快速发现异常问题的触发点是诊断的第一步。Flashduty RUM 提供以下方式帮助您识别问题： * **数据分析**：通过**分析看板**的「异常」Tab，查看错误率、异常类型等数据趋势 * **告警通知**：通过在应用中开启告警，与**协作空间**联动，可在异常发生时及时感知 * **主动巡检**：在**异常追踪**模块观察异常趋势，如 JavaScript 错误、网络错误等 Flashduty RUM 提供丰富的异常数据和上下文信息，帮助您精准定位问题根因。 ### 核心异常数据 | 异常类型 | 说明 | | ------------- | ------------------ | | JavaScript 错误 | 运行时错误、语法错误等 | | 网络请求错误 | API 调用失败、超时等 | | 资源加载错误 | 图片、脚本等资源加载失败 | | 框架相关错误 | React、Vue 等框架的组件错误 | ### 上下文信息 * **用户环境**：浏览器类型、设备型号、操作系统 * **错误堆栈**：详细的调用栈信息 * **会话时间线**：触发错误的操作路径 ### 问题分类与定位 | 问题类型 | 典型表现 | 可能原因 | 关键指标 | | ----------------- | ---------- | --------------- | ---------- | | **JavaScript 错误** | 功能失效、控制台报错 | 代码逻辑错误、浏览器兼容性问题 | 错误率、错误类型 | | **网络请求错误** | 请求超时、连接中断 | API 响应慢、网络质量差 | 请求延迟、连接成功率 | | **资源加载错误** | 图片/脚本加载失败 | CDN 配置错误、资源路径错误 | 资源加载失败率 | | **框架相关错误** | 组件渲染失败 | 组件逻辑错误、状态管理问题 | 组件错误率 | ## 问题定位工具 通过错误分析面板，您可以查看聚合后的 Issue 列表、错误趋势和详细信息。 错误分析面板 上传 SourceMap 后，可以直接在堆栈信息中查看原始源代码位置。 源码映射 问题解决后，可在系统中流转 Issue 状态，并持续关注异常数据的变化趋势。 ## 下一步 了解异常上报规则和方式 查看和分析异常详情 配置源码映射提升调试效率 了解异常聚合机制 # 源码映射与异常追踪 Source: https://docs.flashduty.com/zh/rum/error-tracking/source-mapping 本文档详细介绍如何使用 RUM 进行源码映射管理，以及如何通过源码映射进行异常追踪和调试。 Flashduty 支持多平台的符号文件上传与源码映射，帮助开发者将混淆或压缩后的错误堆栈还原为可读的原始源代码。 * **Web（JavaScript）**：通过 [Flashduty CLI](https://github.com/flashcatcloud/flashcat-cli) 上传 `sourcemap` 文件 * **微信小程序**：通过 Flashduty CLI 上传 `miniprogram-ci get-dev-source-map` 生成的 `sourcemap.zip` * **HarmonyOS**：通过 `@flashcatcloud/hvigor-plugin` 上传 ArkTS `sourceMaps.map`、可选 `nameCache.json` 和 Native `.so` 符号文件 * **Android**：通过 Gradle 插件自动上传 ProGuard/R8 mapping 文件和 NDK 符号文件 * **iOS**：通过 Flashduty CLI 上传 dSYM 符号文件 * **Flutter**：通过 Flashduty CLI 上传 `--split-debug-info` 生成的 Dart AOT 符号文件（`.symbols`），还原 Android 上混淆后的 Dart 异常堆栈；iOS 原生崩溃与原生 iOS 应用一样走 dSYM * **Electron**：通过 Flashduty CLI 上传 Breakpad `.sym` 符号文件，按模块 Debug ID 匹配原生崩溃堆栈；详见 [Electron 错误还原](/zh/rum/sdk/electron/error-symbolication) 用户可在「应用管理」-「源码管理」菜单查看已上传的符号文件，并通过上传面板生成脚本在本地执行上传操作。 ## 为什么需要源码映射？ 在现代应用开发中，代码通常会被压缩、混淆或编译，以优化加载速度和性能。无论是 Web 端的 JavaScript 压缩、微信小程序的发布包转换、HarmonyOS 的 ArkTS 构建产物、Android 的 ProGuard/R8 混淆，还是 iOS 的编译优化，这些处理都会导致错误堆栈中的代码位置信息无法直接映射到原始源代码，增加了调试难度。 `SourceMap` 记录了压缩代码与原始代码之间的映射关系，允许开发者在调试时查看未压缩的源代码 通过 `SourceMap` 可以在异常追踪中直接定位到原始源代码中的具体位置 开发者无需手动解码压缩文件，节省排查问题的时间 ## 生成 SourceMap 大多数现代构建工具（如 Webpack、Rollup 或 Vite）都支持生成 `SourceMap`。 在 `webpack.config.js` 中启用 `SourceMap` 生成： ```javascript theme={null} module.exports = { mode: "production", devtool: "source-map", // 生成独立的 .map 文件 output: { filename: "bundle.js", path: path.resolve(__dirname, "dist"), }, }; ``` 构建后，`dist` 目录中会生成 `bundle.js` 和对应的 `bundle.js.map` 文件。 在 `vite.config.js` 中配置： ```javascript theme={null} export default { build: { sourcemap: true, // 生成 sourcemap }, }; ``` 在 `rollup.config.js` 中配置： ```javascript theme={null} export default { output: { sourcemap: true, }, }; ``` ## 上传 SourceMap 使用 Flashduty CLI 将 `sourcemap` 文件上传至 Flashduty 服务器。 确保已安装 Node.js，然后通过 npm 安装： ```bash theme={null} npm install -g @flashcatcloud/flashcat-cli ``` 上传源码配置 在「应用管理」-「源码管理」菜单中，点击「上传源码」面板，填写以下信息： 用于认证您的身份 应用的服务名（例如 `my-service`） 应用的发布版本（例如 `1.0.0`） 压缩文件的路径前缀（例如 `/assets`） 仅私有化部署需要填写。私有化部署时面板会自动填入部署下发的上报地址，可手动覆盖（协议 + 域名，不带路径，例如 `https://rum.example.com`）；留空则默认上传到 Flashcat SaaS。 在项目根目录下运行生成的脚本： ```bash theme={null} flashcat-cli sourcemaps upload \ --service my-service \ --release-version 1.0.0 \ --minified-path-prefix /assets \ --api-key your-api-key \ ./dist ``` 私有化部署时，在命令前加上 `FLASHCAT_SOURCEMAP_INTAKE_URL` 环境变量即可将符号文件上传至自定义入口，例如 `FLASHCAT_SOURCEMAP_INTAKE_URL=https://rum.example.com flashcat-cli sourcemaps upload ...`（协议 + 域名，不带路径）；未设置时默认上传到 Flashcat SaaS。填写「自定义上传 Endpoint」后，面板生成的命令会自动带上该变量。 * 确保 `minified-path-prefix` 与实际部署的压缩文件路径一致 * 上传成功后，可在「应用管理」-「源码管理」中查看已上传的 `sourcemap` 文件 ## 上传微信小程序 SourceMap 微信小程序发布后，线上错误堆栈通常只包含转换后的文件路径和行列号。你可以先使用 `miniprogram-ci get-dev-source-map` 生成 `sourcemap.zip`，再通过 Flashduty CLI 上传。上传后，Flashduty 会按服务名、版本和文件路径匹配小程序错误堆栈，并在异常详情中展示还原后的源码位置。 在小程序项目中运行 `miniprogram-ci get-dev-source-map`，生成可上传的 `sourcemap.zip` 文件。该文件路径会作为上传命令的 `--sourcemap-zip` 参数。 `miniprogram-ci get-dev-source-map` 默认输出的 zip 结构即满足以下要求，通常无需手动调整： * 主包的 `.js.map` 条目放在 `__FULL__/` 目录下，例如 `__FULL__/app-service.js.map` * 分包的 `.js.map` 条目放在以分包名命名的目录下，例如 `subpkg-a/chunk_0.appservice.js.map`，目录名会作为分包标识写入元数据 * 只有 `.js.map` 后缀的条目会被采纳，其他文件（README、source 文件等）会被忽略 * 若 zip 中找不到任何 `.js.map` 条目，上传会返回错误 `No .js.map entries found in the sourcemap archive` 单个 `.js.map` 解压后不超过 50 MB；整个 zip 解压后聚合不超过 500 MB；zip 内总条目数不超过 5000。超出限制时上传会返回 HTTP 413。 在「应用管理」-「源码管理」菜单切换到「微信小程序」标签页，点击「上传源码」。上传面板会根据表单内容生成命令。 用于认证上传请求。页面会优先展示当前账户可访问的 API Key。 小程序应用的服务名，例如 `my-mp`。异常解析时会使用该值与错误事件中的 `service` 匹配。 小程序发布版本，例如 `1.2.3`。异常解析时会使用该值与错误事件中的版本匹配。 `miniprogram-ci get-dev-source-map` 输出的压缩包路径，例如 `./sourcemap.zip`。 微信小程序 appid，例如 `wxbad3e0a65782821c`。多小程序场景下用于区分不同小程序的同名 service + version 上传记录；只有一个小程序时可省略。 在项目根目录下运行生成的命令；`--appid` 为可选参数，未填写时上传命令中不会出现这一行： ```bash theme={null} FLASHCAT_API_KEY=your-api-key flashcat-cli sourcemaps upload-miniprogram \ --service my-mp \ --release-version 1.2.3 \ --sourcemap-zip ./sourcemap.zip \ --appid wxbad3e0a65782821c ``` ## 上传 HarmonyOS 符号文件 HarmonyOS 崩溃栈可能同时包含 **ArkTS / JS 帧** 和 **Native `.so` 帧**。要在控制台中同时还原这两类堆栈，请上传以下构建产物： * `sourceMaps.map`：ArkTS sourcemap 主文件 * `nameCache.json`：可选，用于还原混淆后的标识符名称 * 未 strip 的 Native `.so`：用于符号化 C/C++ 崩溃栈 控制台的 **应用管理 → 源码管理 → HarmonyOS** 上传面板会要求你填写 **Service**、**Version** 和 **API Key**，并生成对应的 `hvigor` 配置和上传命令。`service` 与 `version` 必须和应用实际上报的值保持一致，否则服务端无法匹配到对应符号文件。 在 HarmonyOS 工程中安装上传插件： ```bash theme={null} npm install -D @flashcatcloud/hvigor-plugin@^0.1.3 ``` 把控制台面板生成的 `service`、`version` 与 `apiKey` 配置写入 `hvigorfile.ts`： ```ts hvigorfile.ts theme={null} import { hapTasks } from '@ohos/hvigor-ohos-plugin'; import { flashcatSymbolUploadPlugin } from '@flashcatcloud/hvigor-plugin'; export default { system: hapTasks, plugins: [ flashcatSymbolUploadPlugin({ apiKey: process.env.FLASHCAT_API_KEY ?? '', service: 'my-app', version: '1.0.0', enabled: process.env.FLASHCAT_UPLOAD === '1' }) ] }; ``` 在构建产物生成后执行上传任务： ```bash theme={null} FLASHCAT_UPLOAD=1 FLASHCAT_API_KEY=your-api-key \ hvigorw uploadFlashcatSymbols --mode module -p module=entry@default -p product=default ``` * 公有云省略 `endpoint` 时，**hvigor-plugin ≥ 0.1.3** 默认上传到 `https://ci.flashcat.cloud`。不要用 RUM 上报域名 `browser.flashcat.cloud`（会 404）。私有化设置 `FLASHCAT_SOURCEMAP_INTAKE_URL`（需 ≥ 0.1.3）或显式传 `endpoint` * Native `.so` 需要保留 GNU build-id；HarmonyOS NDK 默认开启，如你的构建链路关闭了它，请显式添加 `-Wl,--build-id` * 更完整的 HarmonyOS 接入、符号上传和兼容性说明，请继续阅读 [HarmonyOS SDK 高级配置](/zh/rum/sdk/harmony/advanced-config) ## 上传 Android 符号文件 Android 应用使用 ProGuard/R8 进行代码混淆后，错误堆栈中的类名和方法名会被替换为无意义的短名称。通过上传 mapping 文件，Flashduty 可以将混淆后的堆栈还原为原始代码。 对于包含 NDK 原生代码的应用，还需要上传 NDK 符号文件以还原 C/C++ 层的堆栈。 在应用模块的 `build.gradle` 中添加 Flashcat Android Gradle 插件： ```groovy theme={null} plugins { id("cloud.flashcat.android-gradle-plugin") version "1.2.0" } ``` Kotlin DSL 使用相同的插件 ID： ```kotlin theme={null} plugins { id("cloud.flashcat.android-gradle-plugin") version "1.2.0" } ``` 通过 Gradle 属性、环境变量或项目配置文件提供 API Key。发布流水线中通常使用环境变量： ```bash theme={null} # 二选一 export FC_API_KEY=your-api-key export FLASHCAT_API_KEY=your-api-key # 可选：私有化部署时指定自定义上传入口 export FLASHCAT_SOURCEMAP_INTAKE_URL=https://rum.example.com ``` 也可以在项目根目录创建 `flashcat-ci.json`： ```json theme={null} { "apiKey": "your-api-key", "flashcatSite": "ci.flashcat.cloud", "sourcemapEndpoint": "https://rum.example.com" } ``` API Key 可在控制台的「API Key 管理」页面创建和管理。 在应用模块的 `build.gradle` 中添加 `flashcat` 配置块。未显式配置时，插件会从 Android 构建配置读取 `versionName`、`versionCode` 和应用包名。 ```groovy theme={null} flashcat { versionName = "1.3.0" // 可选，默认读取 Android 配置中的 versionName serviceName = "my-service" // 可选，默认使用应用包名 site = "CN" // 可选，可选值：CN、STAGING，默认 CN sourcemapEndpoint = "https://rum.example.com" // 可选，私有化自定义上传入口；未带 /sourcemap/upload 时会自动补全 checkProjectDependencies = "none" // 可选：none、warn、fail；默认不检查 mappingFilePath = "path/to/mapping.txt" // 可选，自定义 mapping 文件路径 nonDefaultObfuscation = false // 可选，使用 DexGuard 等非默认混淆工具时设为 true ignoreFlashcatCiFileConfig = false // 可选，是否忽略 flashcat-ci.json additionalSymbolFilesLocations = ["/path/to/location/obj"] // 可选，额外 NDK 符号目录 } ``` 默认情况下插件会根据 `site` 选择上传入口：`CN` 对应 `ci.flashcat.cloud`，`STAGING` 对应 `ci-dev.flashcat.cloud`。私有化部署可通过 `sourcemapEndpoint` 指定自定义上传入口（自 `1.2.0` 起支持）；该值未带 `/sourcemap/upload` 路径时会自动补全。三种配置方式的优先级为：`flashcat {}` 扩展配置 > `flashcat-ci.json` > `FLASHCAT_SOURCEMAP_INTAKE_URL` 环境变量。配置自定义入口后，`site` 仅用于回退，不再影响实际上传地址。 在构建完成后，执行 Gradle 任务上传符号文件： ```bash theme={null} # 上传 ProGuard/R8 mapping 文件 ./gradlew uploadMappingRelease # 如果项目包含 NDK 原生代码，上传 NDK 符号文件 ./gradlew uploadNdkSymbolFilesRelease ``` 插件会为启用混淆的 variant 创建 `uploadMapping` 任务。NDK 符号上传任务会在项目存在 native build，或配置了 `additionalSymbolFilesLocations` 时创建。若项目使用多个 flavor，请为每个发布 variant 分别执行对应任务。 **NDK 符号文件必须是未剥离（unstripped）的 ELF 文件，且包含 GNU build-id 节。** 上传服务器会读取每个 `.so` 文件的 `.note.gnu.build-id` ELF 节以提取 build-id，并以此作为符号化寻址的唯一键。若文件缺少该节，上传立即返回 HTTP 400，错误信息为： ``` libfoo.so: .note.gnu.build-id section not found. Build the .so with -Wl,--build-id and upload the unstripped file ``` **常见原因及修复：** * **CMake Release 构建默认剥离符号**：CMake 在 `CMAKE_BUILD_TYPE=Release` 时会在链接后执行 `strip`，移除 `.note.gnu.build-id` 节。需在 `CMakeLists.txt` 中显式添加链接标志： ```cmake theme={null} target_link_options(mylib PRIVATE -Wl,--build-id) ``` 或对整个项目生效： ```cmake theme={null} add_link_options(-Wl,--build-id) ``` * **手动 strip 脚本**：如果 CI 流水线在上传前对 `.so` 运行了 `strip` 命令，需确保上传的是 `obj/` 目录下的原始未剥离文件，而不是 `libs/` 目录下已剥离的发布产物。`additionalSymbolFilesLocations` 参数用于指定此路径。 NDK 原生符号文件在 API 中以 `event.type=ndk_symbol_file` 标识，区别于 ProGuard mapping 文件的 `event.type=jvm_mapping_file`。自定义上传集成（不使用 Gradle 插件）时需传入正确的类型字段。 ## 上传 iOS dSYM 文件 iOS 应用在编译时会生成 dSYM（Debug Symbol）文件，其中包含将内存地址映射回源代码位置所需的调试符号信息。上传 dSYM 文件后，Flashduty 可以将崩溃堆栈中的地址还原为可读的函数名、文件名和行号。 确保已安装 Node.js，然后通过 npm 安装： ```bash theme={null} npm install -g @flashcatcloud/flashcat-cli ``` dSYM 文件可从以下位置获取： * **Xcode 本地构建**：在 Xcode 的 Build Products 目录中找到 `.dSYM` 文件 * **Xcode Archive**：通过 Organizer 窗口导出 dSYMs * **App Store Connect**：从 App Store Connect 下载 dSYMs（需要在构建设置中启用符号上传） 使用 Flashduty CLI 上传 dSYM 文件： ```bash theme={null} FLASHCAT_API_KEY=your-api-key flashcat-cli dsyms upload ./app.dSYM # 可选：私有化部署时指定自定义上传入口（协议 + 域名，不带路径）；未设置时默认上传到 Flashcat SaaS FLASHCAT_API_KEY=your-api-key FLASHCAT_SOURCEMAP_INTAKE_URL=https://rum.example.com flashcat-cli dsyms upload ./app.dSYM ``` 您也可以在控制台的「源码管理」面板中，填写参数后自动生成上传命令。 ## 上传 Flutter 符号文件 Flutter 应用使用 `--obfuscate` 混淆构建后，Dart 异常堆栈中的符号会被剥离，只剩地址信息。通过上传 `--split-debug-info` 生成的 Dart AOT 符号文件（`app.-.symbols`），Flashduty 会读取符号文件的 ELF GNU build-id，与堆栈中携带的 build ID 匹配，还原 Android 上的 Dart 异常堆栈。Flutter 符号文件在上传 API 中以 `event.type=flutter_symbol_file` 标识。 Android 构建时开启混淆并指定符号输出目录： ```bash theme={null} flutter build apk --obfuscate --split-debug-info=./debug-symbols ``` 在「应用管理」-「源码管理」菜单切换到「Flutter」标签页，点击「上传源码」。上传面板会根据表单内容生成命令。 用于认证上传请求，对应命令中的 `FLASHCAT_API_KEY` 环境变量。 `--split-debug-info` 指定的符号目录，例如 `./debug-symbols`。 应用的服务名，例如 `my-app`。建议与 SDK 初始化时设置的 `service` 保持一致，便于在控制台按服务归类筛选。 应用的发布版本，例如 `1.0.0`。建议与 SDK 初始化时设置的 `releaseVersion` 保持一致。 在项目根目录下运行生成的命令： ```bash theme={null} FLASHCAT_API_KEY=your-api-key flashcat-cli flutter-symbols upload ./debug-symbols \ --service my-app \ --release-version 1.0.0 ``` **iOS 的 Dart 堆栈暂不支持符号化。** Flutter 为 Apple 平台生成的符号文件是 Mach-O 格式，平台当前只能解析 Android 侧的 ELF 格式，因此 iOS 的 `.symbols` 上传会被拒绝。iOS 原生崩溃（Objective-C / Swift / C / C++）不受影响，与原生 iOS 应用一样上传 dSYM 即可符号化。 如果你的应用同时发布 iOS 和 Android，`--obfuscate` 仍可开启：Android 的 Dart 堆栈会正常还原，iOS 的 Dart 堆栈则保持混淆状态。若 iOS 的可读堆栈更重要，则该端构建时不要开启 `--obfuscate`。 符号文件与崩溃事件通过 build ID 匹配，`service` 与 `release-version` 不参与解析，仅影响控制台列表的归类与筛选。符号文件支持 `arm`、`arm64`、`x64` 架构，由 `.symbols` 文件名自动识别。每次改动 Dart 代码都会生成新的 build ID，因此符号上传必须纳入每一次发布构建。更完整的 Flutter 符号化说明请参阅 [Flutter SDK 高级配置](/zh/rum/sdk/flutter/advanced-config)。 ## 符号文件管理 在 Flashduty 平台上，符号文件的管理通过「应用管理」-「源码管理」菜单完成： | 功能 | 说明 | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 查看已上传的符号文件 | 列出所有已上传的文件（SourceMap、小程序 SourceMap、ProGuard mapping 文件、dSYM、NDK 原生符号文件、Flutter 符号文件），包括路径、服务名、版本号、大小和上传时间。Android 标签页同时展示 ProGuard mapping 文件和 NDK 原生符号文件，NDK 行会显示 build\_id、arch 和 lib\_name 列 | | 按平台筛选 | 在 Web、iOS、Android、微信小程序、HarmonyOS、Flutter 和 Electron 标签页之间切换，查看不同平台的符号文件 | | 版本管理 | 通过 `service` 和 `release-version` 参数为不同版本的应用分别管理 | | 小程序维度 | 微信小程序列表会展示符号文件元数据中的 AppID（取自 `metadata.appid`）和分包（取自 `metadata.subpackage`）两列；主包没有分包标识时显示「主包」，AppID 未上传时显示 `-` | | 权限控制 | 通过 `API Key` 确保只有授权用户可以上传或管理 | ## 在异常追踪中查看源码 RUM 异常追踪支持结合 Web `sourcemap`、微信小程序 SourceMap、Android mapping 文件和 iOS dSYM 还原错误堆栈，在异常详情中查看原始源码位置，精确定位问题。 RUM SDK 会自动捕获应用错误，并将错误堆栈信息发送至服务器。Web 场景通常包括 JavaScript 异常、Promise 拒绝和网络错误；Native 场景则包括崩溃、异常和符号化所需的堆栈信息。 ```javascript theme={null} throw new Error("Something went wrong"); ``` 当错误堆栈中的文件路径、行号或地址信息与已上传的 Web `sourcemap`、微信小程序 SourceMap、Android ProGuard mapping 文件、Android NDK 原生符号文件或 iOS dSYM 文件匹配时，Flashduty 会自动将压缩、混淆或编译后的错误位置映射到原始源代码。 **压缩文件堆栈：** ``` Error: Something went wrong at Object. (/assets/index-5e0391ac.js:1:123) ``` **映射后的源代码：** ``` Error: Something went wrong at App.render (src/components/App.js:45:10) ``` 在异常追踪模块中，点击具体的错误记录，可以查看： * **错误消息**：如 `Something went wrong` * **原始堆栈**：映射后的源代码文件路径、行号和列号 * **上下文代码**：显示错误位置附近的源代码片段 如果小程序错误堆栈尚未解析，异常详情中的提示会跳转到「源码管理」的小程序类型，并可直接打开上传面板补充对应版本的 `sourcemap.zip`。 根据映射后的源代码位置，直接在本地开发环境中找到对应代码，分析问题根因并修复。 ## 最佳实践 在 CI/CD 流水线中集成上传命令，确保每次发布时自动上传 Web `sourcemap` 或微信小程序 `sourcemap.zip`。 **GitHub Actions 示例：** ```yaml theme={null} - name: Upload SourceMaps run: | flashcat-cli sourcemaps upload \ --service my-service \ --release-version ${{ github.sha }} \ --minified-path-prefix /assets \ --api-key ${{ secrets.FLASHCAT_API_KEY }} \ ./dist ``` 使用 `--release-version` 参数与应用版本号保持一致，便于追踪特定版本的 `sourcemap`。 在资源上传 CDN 之前删除 `sourcemap` 文件，避免将源码信息带入生产环境。 上传 `sourcemap` 后，主动抛出测试错误，验证异常追踪模块是否能正确映射到源代码。 ## 常见问题 * 确认 `sourcemap` 是否成功上传，且 `minified-path-prefix` 与实际部署路径一致 * 检查 `service` 和 `release-version` 是否与错误发生时的应用版本匹配 * 如果是微信小程序，确认已上传对应版本的 `sourcemap.zip` * 确保 `sourcemap` 文件仅上传至 Flashduty 服务器，不直接暴露在公网 * 在生产环境中，移除对 `sourcemap` 文件的直接访问（如通过 Nginx 配置） * 检查 `API Key` 是否有效 * 确保网络连接正常，CLI 版本是最新的 可以。对于早期版本 SDK 把堆栈塞进 message 字段的小程序错误，Flashduty 会自动从 message 中识别堆栈并参与 SourceMap 还原与异常分组。升级到新版 SDK 后，已存在的历史错误也会按这一规则重新归类，可能与升级前的分组不完全一致。 ## 下一步 了解异常聚合机制 管理 Issue 状态流转 # 数据查询语法指南 Source: https://docs.flashduty.com/zh/rum/explorer/data-query 掌握 Flashduty RUM 查看器的搜索语法，通过灵活的查询条件快速定位和分析用户数据。 Flashduty RUM 查看器提供了强大的检索能力，允许您通过灵活的查询语法快速定位和分析 RUM 数据。查询由**词项**（terms）和**操作符**（operators）组成，支持复杂的搜索条件组合。 ## AI 自然语言查询 如果您还不熟悉查询语法，可以直接用自然语言描述想要查找的数据，AI 会自动将其转换为查询语句。 点击查询输入框中的**魔法棒**图标进入 AI 自然语言查询模式。进入后输入框边框会高亮，与普通查询模式明确区分。 用自然语言描述您想查找的数据（支持中英文），然后按**回车**转换。例如： ``` 来自 Chrome 浏览器、耗时超过 2 秒的 5xx 资源请求 ``` AI 会将其转换为： ``` browser_name:Chrome resource_status_code:>=500 resource_duration:>2s ``` AI 生成对应的查询语句并展示预览。确认无误后点击**应用**，查询立即生效；若结果不理想，可继续修改描述后再次回车重新生成，或点击**撤销**回退到应用前的状态。 AI 生成的是标准查询语句（DQL），使用的字段与语法与手动查询完全一致（详见下文）。您无需记住字段名称，AI 会根据当前事件类型自动选择可查询的字段。 ### 追加而非替换 当输入框中已有查询条件时，AI 生成的条件会**追加**到现有查询之后，而不会覆盖它。因此您可以在已有查询的基础上，用自然语言逐步补充筛选条件。若当前为空查询，则直接应用生成结果。 如果您的描述更适合其他事件类型，AI 会提示切换（如「将切换事件类型为 错误」），并在该事件类型的可查询字段范围内生成查询。 在 AI 输入框中用**自然语言**描述意图即可，无需手写查询语句（如 `browser_name:Chrome`）——直接输入查询语法反而会降低转换准确率。需要精确控制查询条件时，请改用下方的查询语法。 ## 查询基础 查询支持两种类型的词项： | 类型 | 说明 | 示例 | | ------- | ---------- | ------------------- | | **单词项** | 单个词汇 | `test`、`hello` | | **短语** | 用双引号包围的词汇组 | `"hello flashduty"` | ### 布尔操作符 | 操作符 | 描述 | 示例 | | ----- | ------------------------------- | -------------------- | | `AND` | 交集：两个词项都必须在选定的视图中（默认操作符） | `error AND timeout` | | `OR` | 并集：任一词项包含在选定的视图中，需要使用 `()` 包裹起来 | `(error OR warning)` | | `-` | 排除：后面的词项不在视图中 | `error -timeout` | ## AI 自然语言查询 如果你不想手写 DQL，可以让 AI 将自然语言请求转换为查询条件。在 RUM 查看器的查询框左侧点击 **AI 自然语言查询** 图标；也可以在普通查询模式下按 ⌘ + Enter（Windows 和 Linux 为 Ctrl + Enter）。 用自然语言描述你想查看的数据，例如“Chrome 浏览器上的报错”“耗时超过 2 秒的资源请求”或“过去 24 小时的 checkout 页面”。按 Enter 生成预览。 预览会显示将要加入的 DQL 条件；当请求更适合其他事件类型或时间范围时，也会显示事件类型或时间范围的变更。 点击 **应用**、**追加到查询** 或 **切换并应用** 确认变更。应用后，提示消息中会提供 **撤销**，用于恢复应用前的查询、事件类型和时间范围。 “最近 1 小时”“昨天”“过去 7 天”等时间表达会更新查看器的时间选择器，不会被写成 `client_time` 等 DQL 条件。性能时长条件仍然属于 DQL，例如 `view_loading_time:>2s`。 AI 自然语言查询的时间范围最长为 **14 天**。如果请求的范围更长，预览会提示已截取最近 14 天；应用后时间选择器会使用截取后的范围。相对时间范围会改为过去 14 天，绝对时间范围会保留请求的结束时间，并向前取 14 天。 ## 全文检索 全文检索仅部分字段支持，如未查询到结果，请转为字段查询。 | 查询语句 | 描述 | | --------------- | ------------------------ | | `hello` | 精确匹配 `hello` 的字段 | | `hello*` | 匹配以 `hello` 开头的字段 | | `*hello` | 匹配以 `hello` 结尾的字段 | | `*hello*` | 匹配含有 `hello` 的字段 | | `"hello world"` | 精确匹配 `"hello world"` 的字段 | ## 转义特殊字符 检索包含特殊字符的字段值时，需要使用反斜杠 `\` 转义或者双引号。 以下字符被视为特殊字符：`:`, `"`, `*`, `-`, `>`, `<`, `,`, `(`, `)`, `[`, `]`, `\` 和空格 ## 属性检索 使用 `attribute:term` 语法检索特定属性： | 查询语句 | 描述 | | ------------------------- | ----------------------- | | `browser_name:Chrome` | 检索值为 `Chrome` 的浏览器 | | `view_name:*/detail` | 检索以 `/detail` 结尾的视图名称 | | `-resource_status_code:0` | 检索状态码不为 `0` 的资源 | | `os_name:"Mac OS X"` | 检索值为 `"Mac OS X"` 的系统名称 | ## 数值检索 对于数值类型的属性，可以使用比较操作符： | 查询语句 | 描述 | | ----------------------------- | ------------------------ | | `session_error_count:>5` | 检索错误数大于 `5` 的会话 | | `view_time_spent:>=1.00min` | 检索停留时间大于 `1min` 的视图 | | `session_view_count:[2 TO 8]` | 检索视图访问量在 `2` 和 `8` 之间的会话 | ## 复杂检索示例 检索钱包页面中发生的 Warning 类型的错误： ``` error_message:Warning\:* view_url_path:/wallet/* ``` 检索加载时间超过 5 秒，且以 `/incident/detail/` 开头的视图： ``` view_loading_time:>=5s view_url_path:/incident/detail/* ``` 检索请求类型为 `fetch` 或者 `xhr`，且状态码不为 `200` 的资源： ``` -resource_status_code:200 resource_type:(fetch OR xhr) ``` 检索 URL 为 `/incident`，且操作数大于 `2` 或者错误数大于 `3` 的视图： ``` view_url_path:/incident (view_action_count:>=2 OR view_error_count:>=3) ``` ## 微信小程序专属属性 针对微信小程序平台采集的 View 事件，除通用的 `view_*` 字段外，还支持以下可查询属性，便于排查小程序页面冷启动、`setData` 调用和生命周期阶段耗时： | 属性 | 说明 | | ------------------------ | -------------------------- | | `view_first_render` | 首屏渲染耗时 | | `view_app_launch` | 小程序启动耗时 | | `view_loading_time` | 页面加载耗时 | | `view_setdata_count` | 页面 `setData` 调用次数 | | `view_setdata_duration` | 页面 `setData` 累计耗时 | | `view_onload_to_onshow` | `onLoad` 到 `onShow` 之间的耗时 | | `view_onshow_to_onready` | `onShow` 到 `onReady` 之间的耗时 | 例如，检索首屏渲染超过 2 秒的小程序页面： ``` source:miniprogram view_first_render:>2s ``` ## 高级检索技巧 结合时间范围进行精确检索： ``` view_loading_time:>2s client_time:>1758253826081 ``` 检索结账页面的用户点击行为： ``` action_type:click view_url_path:/checkout/* ``` 检索移动设备上加载时间超过 3 秒的视图： ``` device_type:mobile view_loading_time:>3s ``` 检索中国地区发生错误的会话： ``` geo_country:China session_error_count:>0 ``` ## 最佳实践 确保多词短语的精确匹配 避免过于宽泛的检索条件 通过 AND/OR 操作符构建精确查询 减少输入错误，提高检索准确性 保存常用检索条件，提高重复查询的效率。 ## 下一步 了解查看器核心功能 了解分布式追踪最佳实践 # RUM 查看器功能概览 Source: https://docs.flashduty.com/zh/rum/explorer/overview 掌握 Flashduty RUM 查看器的强大功能，通过可视化界面深入分析用户数据、性能指标和应用行为。 Flashduty RUM **查看器**（RUM Explorer）是一款强大的数据分析工具，旨在帮助开发者深入检查从应用程序收集的数据，并获取关于 RUM 事件的详细信息。通过直观的可视化界面，您可以全面了解用户行为、应用性能和系统健康状况。 ## 核心功能 浏览和分析用户的完整会话路径，了解用户在应用中的行为模式 深入分析影响页面视图、资源加载或用户操作的性能问题 快速定位和诊断应用程序错误以及长时间运行的任务 通过搜索栏和可视化类型选择，对 RUM 事件进行精确过滤和筛选 ## 价值与优势 | 优势 | 描述 | | ---------- | ---------------------- | | **数据驱动决策** | 基于真实用户数据做出产品优化和性能改进决策 | | **问题快速定位** | 通过可视化界面快速识别性能瓶颈和用户体验问题 | | **用户行为洞察** | 深入了解用户如何与您的应用交互，发现改进机会 | | **全面监控覆盖** | 从页面加载到用户操作的全链路监控和分析 | ## 使用场景 分析页面加载时间、资源加载效率，识别性能瓶颈。 了解用户操作路径，发现交互设计中的问题。 快速定位应用错误发生的具体场景和上下文。 分析用户行为模式，为产品功能优化提供数据支持。 ## 主要功能详解 使用顶部导航栏的应用选择器，可以选择特定应用程序并查看其所有 RUM 数据。 通过应用选择器，您可以快速切换不同应用的数据视图，专注于特定应用的性能和用户行为分析。 在 RUM 查看器中，您可以通过在搜索栏输入查询条件并选择可视化类型来搜索和过滤 RUM 事件。 搜索与过滤 点击数据项可查看数据详情，可将 RUM 事件以各种角度展示，帮助您发现关键信息。 * 查看数据关系，进行数据下钻或者查看数据父节点详情 * 通过查看资源的 trace，和已有的监控系统进行 trace 关联 数据详情 ## 按平台显示的视图指标 打开任一 View 的详情面板时，「性能」标签页的指标卡片会根据该 View 所属平台自适应展示，确保看到的是该平台真正具备的核心指标。 | 平台 | 性能指标卡片 | | --------------------- | ----------------------------------------------------------------- | | **浏览器（Web）** | `LCP`、`FCP`、`INP`、`CLS` | | **原生（Android / iOS）** | `refresh_rate`、`cpu_ticks`、`memory` | | **微信小程序** | `first_render`、`lcp`、`fcp`、`onload_to_onshow`、`onshow_to_onready` | 平台由 View 事件自身的 `source` 字段决定，无需手动切换。微信小程序场景下，`onload_to_onshow` 和 `onshow_to_onready` 对应小程序页面生命周期的两段耗时，可用于排查页面冷启动慢的原因。 EventTable 的列选择器也已经支持以下小程序专属字段作为可查询列：`view_first_render`、`view_onload_to_onshow`、`view_onshow_to_onready`。 ## 保存视图 保存视图功能允许您将当前的查询状态保存为可复用的视图，方便快速切换不同的分析场景。每个账户最多可创建 **20 个**保存视图，视图仅您自己可见。 ### 视图保存的内容 每个保存视图包含以下信息： | 保存项 | 说明 | | -------- | -------------------------------------------- | | **时间范围** | 当前选择的时间筛选条件 | | **查询类型** | 当前选择的事件类型（如 Sessions、Views、Actions、Errors 等） | | **查询语句** | 搜索栏中的 DQL 筛选条件 | | **自定义列** | 数据表格的列配置 | ### 视图操作 点击查看器顶部的视图菜单，选择「保存为新视图」，输入视图名称后确认即可创建。视图名称不可重复。 点击视图菜单，在视图列表中点击目标视图即可切换。切换后，查看器会自动恢复该视图保存的时间范围、查询类型、查询语句和列配置。 在视图列表中，点击目标视图右侧的操作菜单，选择「编辑视图」可修改视图名称。如果您修改了当前视图的查询条件，还可以通过「保存修改」将最新状态更新到视图中。 在视图列表或操作菜单中选择「删除视图」，确认后即可删除。删除当前正在使用的视图后，查看器会自动切换回默认视图。 在视图列表中，点击目标视图右侧的操作菜单，选择「复制链接」可获取该视图的分享链接。将链接分享给团队成员后，他们可以直接打开相同的查询视图。 通过操作菜单选择「切换默认视图」，查看器会清空所有筛选条件，恢复到初始状态。 ## 下一步 掌握查询语法，精准定位数据 了解分布式追踪最佳实践 # 诊断指南 Source: https://docs.flashduty.com/zh/rum/performance/diagnosis-optimization 本文档详细介绍如何使用 Flashduty RUM 进行性能问题诊断和优化。 优化页面有助于根据真实用户流量数据识别浏览器性能问题的根本原因。通过浏览器指标（如核心网页指标和 Flashduty 自定义加载时间指标）排查页面加载缓慢的原因，这些指标可以从用户的角度评估完整页面的加载时间。 为了进行更深入的分析，优化页面提供了按用户人口统计（例如浏览器、地区和应用版本）的核心网页指标的详细拆分。您可以利用这些信息跟踪性能趋势，了解受影响最多的用户群体，精准优化。 ## 诊断优化流程 您可导航至优化页面，该页面位于性能监控菜单下，选取待洞察的指标即可。您也可以通过在分析看板中查看对应的性能数据跳转至此功能。 选择页面和指标后，便可开始做性能数据洞察： 1. 点击指标卡片选择要洞察的指标（目前支持 LCP、FCP、INP、CLS） 2. 在「显示筛选细分」中选择一个组 3. 在不同的百分位数处评估指标（例如 p75 表示第 75 个百分位数值） 您可通过调整数据聚合方式或修改筛选条件，查看该指标在不同条件下的数据表现情况，从而推进诊断优化工作。 数据查看 在问题诊断部分，您可以看到用户在页面上遇到的可能影响指标性能的资源和错误。 问题诊断 例如，对于最大内容绘制（LCP），您可以查看在触发 LCP 之前加载的资源。由于 LCP 是最大元素在页面上加载所需时间的指标，您可以从资源加载和解决错误两个方面进行问题诊断。 如果在资源分析阶段无法更准确地定位到关键信息，您可在事件样本区块中选取合适的事件样本进行更详细的上下文分析。 事件样本 ## 优化方向 资源加载分析面板展示当前视图下所有资源的详细加载信息，帮助您识别性能瓶颈。 您可以通过「全部资源」和「阻塞资源」两个选项卡切换查看范围： * **全部资源**：展示视图中加载的所有资源 * **阻塞资源**：仅展示标记为 `blocking` 的渲染阻塞资源，这些资源会延迟页面的首次渲染 资源列表包含以下字段： | 字段 | 说明 | | ----------------- | ---------------------------------------------- | | URL GROUP | 资源的 URL 路径分组 | | TYPE | 资源类型（如 JS、CSS、Image 等） | | AVG CLIENT SIZE | 平均客户端资源大小 | | AVG TRANSFER SIZE | 平均传输大小（如传输大小明显小于客户端大小，说明部分采样命中了缓存） | | AVG START TIME | 平均开始加载时间 | | AVG DURATION | 平均加载耗时，并以色条可视化展示 DNS 解析、连接建立、首字节等待和下载四个阶段的耗时占比 | 将鼠标悬停在耗时色条上，可查看各阶段的具体耗时数值，帮助您判断是网络连接、服务器响应还是资源大小导致的加载缓慢。 * 关注可能导致问题的重复错误，这些异常也会影响页面性能 * 瀑布图显示了在捕获指标时事件的时间线 * 向下滚动可查看页面活动其余部分的上下文 * 使用左上角的下拉菜单选择另一个示例事件 * 单击展开瀑布中的任何事件以查看侧边面板 * 通过筛选事件类型和各筛选项来选取合适的事件集合进行问题分析 # 指标收集与上报 Source: https://docs.flashduty.com/zh/rum/performance/metrics-reporting 了解 Flashduty RUM 性能指标的收集方法、上报机制及配置说明。 Flashduty RUM 支持收集和上报 Web Vitals 相关的性能指标，帮助您全面监控和优化网站性能。通过这些指标，您可以了解用户在访问网站时的实际体验，并针对性地进行优化。 ## Web Vitals 指标概览 Flashduty RUM 支持以下 [核心 Web Vitals 指标](https://web.dev/articles/vitals?hl=zh-cn)： | 指标 | 全称 | 说明 | | -------- | -------- | --------------- | | **LCP** | 最大内容绘制 | 衡量页面主要内容的加载性能 | | **INP** | 交互到下一帧延迟 | 衡量整体交互响应性能 | | **CLS** | 累计布局偏移 | 衡量视觉稳定性 | | **FCP** | 首次内容绘制 | 衡量首次内容渲染时间 | | **FID** | 首次输入延迟 | 衡量页面交互性能（辅助指标） | | **TTFB** | 首次字节时间 | 衡量服务器响应速度（辅助指标） | 这些指标会在用户访问页面时自动收集，并通过 SDK 上报到 Flashduty 平台，您可以在分析看板中查看详细的性能数据。 对于在后台打开的页面（例如，在新标签页或无焦点的窗口中），不会收集到 INP 和 LCP 的数据。 ## 指标计算方法 **计算方法：** 从页面开始加载（`navigationStart`）到最大可见内容元素（如图片、文本块）渲染完成的时间。 **用例：** 监控主页或关键页面内容加载速度，识别资源加载瓶颈。 **计算方法：** 测量从用户第一次导航到页面到页面内容的任何部分在屏幕上呈现的时间。 **用例：** 用于测量感知加载速度，有助于向用户保证某些事情正在发生。 **计算方法：** 测量所有用户交互（点击、轻触、键盘输入）到下一帧渲染的延迟时间。 **用例：** 评估页面整体交互响应性能，优化高延迟交互场景。 **计算方法：** 统计所有意外布局偏移的分数（偏移距离 × 影响区域）。 **用例：** 识别动态内容或广告导致的页面跳动问题。 **计算方法：** 从用户第一次交互开始到浏览器处理事件的时间差。 **用例：** 优化交互密集型页面（如表单、导航菜单）的响应速度。 ## 监控单页应用 (SPA) 对于单页应用程序，RUM 浏览器 SDK 通过 `loading_type` 属性区分 `initial_load` 和 `route_change` 两种导航类型。 如果网页上的某个交互操作导致 URL 发生变化，但页面并未完全刷新，RUM SDK 会使用 `loading_type:route_change` 启动一个新的 `view`。 RUM 使用 [History API](https://developer.mozilla.org/zh-CN/docs/Web/API/History) 来跟踪 URL 的变化。 RUM SDK 会自动监控依赖哈希（`#`）导航的框架。SDK 会监听 `HashChangeEvent` 并发出一个新的 `view`。 来自 HTML 锚点且不影响当前视图上下文的事件将被忽略。 对于 SPA 应用，如需监控路由切换后的性能，建议使用自定义性能监控功能来测量特定组件或交互的性能指标。 ## 自定义性能监控 ### 组件级性能测量 使用 `customVital` API 监控特定组件或交互的性能，适用于： * 关键组件渲染时间 * 用户交互响应时间 * 业务流程耗时 ```javascript 测量组件渲染 theme={null} // 开始计时 const ref = window.FC_RUM.startDurationVital("componentRendering", { description: "login-form", context: { clientId: "xxx", componentVersion: "1.0.0" }, }); // 结束计时 window.FC_RUM.stopDurationVital(ref); ``` ```javascript 直接报告耗时 theme={null} window.FC_RUM.addDurationVital("dropdownRendering", { startTime: 1707755888000, // UNIX 时间戳（毫秒） duration: 10000, // 耗时（毫秒） }); ``` ### 性能时间点记录 使用 `addTiming` API 记录关键时间点，适用于： * 关键元素加载（如首屏图片） * 用户首次交互（如首次滚动） * 业务节点时间戳 ```javascript 记录首次滚动 theme={null} document.addEventListener("scroll", function handler() { document.removeEventListener("scroll", handler); window.FC_RUM.addTiming("first_scroll"); }); ``` ```javascript 异步场景 theme={null} document.addEventListener("scroll", function handler() { document.removeEventListener("scroll", handler); const timing = Date.now(); window.FC_RUM.onReady(() => { window.FC_RUM.addTiming("first_scroll", timing); }); }); ``` ## 注意事项 * 指标名称避免空格、特殊字符 * 使用描述性命名（如 `login_form_render`） * 保持命名一致性 * 控制自定义指标数量 * 避免频繁计时 * 合理设置采样率 ## 常见问题 * 检查慢加载资源（图片、脚本） * 排查第三方脚本阻塞 * 分析长时间运行的 JavaScript * 确认是否存在频繁的后台请求 * 检查长连接或流式请求的处理 * 使用 `excludedActivityUrls` 排除干扰 * 验证指标名称是否符合规范 * 确保计时器正确启停 * 检查异步场景的时间戳准确性 | 原因 | 说明 | | -------- | ------------------------------------------------------ | | 后台页面 | 页面在新标签页或无焦点窗口中打开，导致 INP 和 LCP 无法收集 | | SPA 路由切换 | 在 `loading_type:route_change` 时，核心 Web Vitals 指标不会重新收集 | | 引入方式 | 页面在 SDK 完全初始化前就已加载完成 | | 页面生命周期 | 页面在指标收集完成前就被关闭或导航离开 | | 浏览器兼容性 | 旧版本浏览器不支持某些 Web Vitals API | | 页面无内容 | 页面没有可测量的内容元素（如空白页面） | ## 下一步 深入分析性能数据 学习问题诊断与优化方法 # 核心概念 Source: https://docs.flashduty.com/zh/rum/performance/overview 了解 Flashduty RUM 性能监控的核心概念、关键性能指标及计算方法，优化用户体验。 Flashduty RUM（真实用户监控）提供强大的工具，帮助您快速诊断和优化前端性能问题。通过性能监控模块可快速识别性能瓶颈、定位根因并实施优化措施，确保为用户提供流畅的体验。 ## 核心功能 自动收集并分析关键性能指标（如 FCP、LCP、CLS、FID 等），提供全面的性能数据视图 监控和分析静态资源（如 JS、CSS、图片等）的加载性能，识别加载缓慢的资源 追踪和分析后端 API 调用的性能表现，包括响应时间、成功率等指标 提供全面的性能问题诊断能力，包括性能瓶颈分析、资源加载优化建议等 ## 价值与优势 | 优势 | 描述 | | ---------- | ------------------------- | | **提升用户体验** | 通过优化网站性能，减少页面加载时间，提高用户满意度 | | **提高转化率** | 改善网站性能，提升用户留存率和转化率 | | **数据驱动决策** | 基于性能数据做出优化决策，持续改进产品性能 | ## 使用场景 识别并解决网站性能瓶颈，提升整体性能表现。 分析并优化静态资源加载，提高页面加载速度。 监控和优化后端 API 性能，提升接口响应速度。 通过性能数据了解用户使用体验，针对性地改进产品。 ## 性能监控流程 Flashduty RUM 的性能优化分为三个关键阶段： 快速发现性能问题的触发点是诊断的第一步。Flashduty RUM 提供以下方式帮助您识别问题： * **数据分析**：通过「应用管理 - 数据分析」模块，查看核心性能指标的数据趋势 * **用户反馈**：通过用户报告（如页面加载缓慢或交互卡顿）发现潜在问题 * **异常检测**：观察异常趋势，如资源加载失败率升高或 API 响应时间延长 问题识别 **初步评估：** * **影响范围**：确定问题影响的用户群体（例如特定地区、设备或浏览器） * **严重程度**：评估问题对用户体验的直接影响 * **业务影响**：分析问题对关键业务指标（如转化率或用户留存）的影响 Flashduty RUM 提供丰富的性能数据和上下文信息： **核心性能数据：** * **页面加载指标**：包括 LCP、FCP、TTI * **资源加载时间**：分析图片、脚本、CSS 等资源的加载耗时 * **JavaScript 性能**：监控脚本执行时间和阻塞渲染的脚本 * **网络请求**：记录 API 请求的延迟、成功率和错误率 **上下文信息：** * **用户环境**：浏览器类型、设备型号、操作系统和网络状况 * **错误日志**：捕获 JavaScript 错误、网络错误和资源加载失败的详细信息 * **系统资源**：分析 CPU 使用率、内存占用和 DOM 操作频率 通过可视化工具和分析功能，将性能问题分类并精准定位根因。 ### 常见问题分类 | 问题类型 | 典型表现 | 可能原因 | 关键指标 | | ----------------- | ------------ | -------------------------------- | ------------- | | **页面加载缓慢** | 白屏时间长、首屏渲染慢 | 资源体积过大、阻塞渲染的脚本或 CSS、服务器响应慢 | LCP, FCP, TTI | | **交互响应延迟** | 点击无反应、操作卡顿 | JavaScript 执行时间长、事件监听过多、DOM 操作频繁 | FID, INP, TBT | | **资源加载异常** | 图片/脚本加载失败、超时 | CDN 配置错误、网络不稳定、资源路径错误 | 资源加载时间, 失败率 | | **JavaScript 错误** | 功能失效、控制台报错 | 代码逻辑错误、浏览器兼容性问题、内存泄漏 | 错误率, 内存使用 | | **网络连接问题** | 请求超时、连接中断 | API 响应慢、网络质量差、跨域配置错误 | 请求延迟, 连接成功率 | ## 问题定位工具 性能瀑布图展示页面加载的完整时间线，帮助您识别瓶颈。 性能瀑布图 **关键时间点：** * **导航开始**：用户发起页面请求的时间 * **DNS 查询**：域名解析耗时 * **TCP 连接**：建立服务器连接的耗时 * **首字节时间（TTFB）**：接收服务器响应的第一个字节的耗时 * **DOM 完成**：页面 DOM 结构加载完成的时间 **资源加载分析：** * **关键路径**：识别影响页面渲染的关键资源 * **阻塞资源**：发现阻塞渲染的脚本或样式表 * **加载顺序**：优化资源加载优先级 * **资源大小**：检查是否存在体积过大的资源 Flashduty RUM 捕获并分类前端错误，提供详细的上下文信息。 **错误类型：** * JavaScript 运行时错误（如未捕获的异常或语法错误） * 网络请求错误（如 API 超时或 4xx/5xx 错误） * 资源加载错误（如图片或脚本加载失败） * 框架相关错误（如 React 或 Vue 的组件渲染错误） **错误上下文：** * **错误堆栈**：提供详细的调用栈信息 * **用户操作序列**：重现触发错误的操作路径 * **环境信息**：包括浏览器、设备和网络状态 * **相关性能数据**：关联错误与性能指标的变化 ## 优化建议 定位问题根因后，您可以根据分析结果实施优化： 压缩资源、优化 critical CSS、启用 CDN 减少 JavaScript 执行时间、优化事件监听器 检查 CDN 配置、确保资源路径正确 修复代码逻辑、添加错误边界、优化内存使用 ## 下一步 了解指标收集与上报机制 深入分析性能数据 学习问题诊断与优化方法 # 数据分析指南 Source: https://docs.flashduty.com/zh/rum/performance/performance-analysis 了解如何分析和利用 Flashduty RUM 收集的性能数据，包括性能指标分析、用户体验评估和性能优化建议。 性能数据分析页面通过分析真实用户流量数据来帮助识别浏览器性能问题的根本原因。使用核心网页指标（Core Web Vitals）和自定义加载时间指标等浏览器指标来排查页面加载缓慢的原因。这些指标从用户角度评估完整的页面加载时间。 ## 访问性能分析 导航至性能监控菜单，您可以通过列表或树状视图，从不同的视角分析性能体验。 切换至列表视图，通过页面排序查看 Top 页面下各指标的数据情况： * 通过指标数据前面的颜色标识可快速查看指标全貌，定位到待提升指标 * Hover 至每个指标可查看该指标在标准下所处的当前水位 * 点击每一行记录，可查看该页面下的指标详情 资源视角 切换至树状视图，可以从某个指标视角下查看待优化的资源列表： * 切换不同的指标，查看其分布情况 * 查看「良好」、「较差」、「一般」分类下的资源分布与占比，快速定位问题资源 * 点击区块所代表的页面后，可查看该页面下的指标详情，方便进一步做问题诊断 指标视角 ## 数据分析维度 通过全局筛选器，可以从不同维度对页面性能进行分析，从而洞察性能数据趋势变化： | 维度 | 说明 | | ---- | --------- | | 浏览器 | 按浏览器类型筛选 | | 连接状态 | 按网络连接状态筛选 | | 设备情况 | 按设备类型筛选 | | 地理位置 | 按地理位置信息筛选 | 数据分析维度 性能分析页面同样支持侧栏和全屏两种查看模式。点击某个页面记录后，默认以侧栏形式展示指标详情；您可以点击展开按钮切换到全屏模式，获得更完整的数据展示和诊断空间。 ## 下一步 学习问题诊断与优化方法 # 应用管理 Source: https://docs.flashduty.com/zh/rum/quickstart/app-management 学习如何在 Flashduty 平台创建和管理 RUM 应用，包括应用创建、配置和权限管理 ## 概述 RUM 应用是承载前端性能监控数据的容器，用于采集、存储和分析用户在前端应用中的真实体验数据。一个应用代表一个被监控的前端项目，可以是网站、移动应用或单页应用等。 我们建议按照业务系统或应用来创建 RUM 应用，例如：官网、商城、管理后台等。 每个应用拥有独立的 `applicationId` 和 `clientToken`，用于识别数据来源并确保数据安全。应用创建后，您需要将 SDK 集成到您的前端代码中，以开始数据采集和监控。 ## 应用权限 为了满足不同业务场景的数据安全需求，RUM 应用提供了灵活的访问级别设置： | 访问级别 | 可见范围 | 适用场景 | | ------ | ------------------------ | ------ | | **公开** | 账户内所有用户可见，可查看数据和处理 Issue | 通用业务应用 | | **私有** | 仅创建者、账户管理员和主体账户可见 | 敏感业务数据 | 私有应用中，其他成员若需查看内容，可以通过分享故障链接的方式临时授权访问。 ## 创建应用 RUM 应用创建界面 通过 RUM 产品引导页面，您可以快速创建一个应用： 选择应用对应的前端技术类型，目前支持 **JavaScript (JS)、Android、iOS、HarmonyOS、Flutter、微信小程序、Electron**。 指定该应用的管理团队。 团队所属成员对该应用拥有全部操作权限，非团队成员对该应用的配置仅可只读访问。 默认情况下，自动启用用户地理位置数据采集。如需禁用客户端 IP 或地理位置数据的自动采集，请关闭地理信息收集开关。 详见 [数据收集](/zh/rum/others/data-collection)。 默认情况下，自动开启告警通知，方便您及时处理错误。 详见 [Issue 告警](/zh/rum/error-tracking/issue-alerts)。 ## SDK 配置