观测云故障中心 × 飞书联动：群内触发 OnCall 故障闭环最佳实践
背景与价值
在客户服务群中，客户反馈问题后，真正关键的不是“群里有人看见了”，而是系统能够把这条反馈快速转成一次标准 OnCall 响应：自动创建故障、电话通知当前值班人，并在无人确认时按照升级策略继续通知二线、三线，直到有人接手处理。
通过飞书机器人联动观测云，客户或一线同学只需要在飞书群里 @机器人并描述问题，Func 会把消息推送到观测云外部事件。真正的故障响应由观测云故障中心承接：它会创建标准 Incident，关联值班表，触发 OnCall 电话通知，并在无人确认或需要更高层级介入时按升级策略继续通知二线、三线。飞书交互卡片负责把状态同步回原群，让协作入口保持轻量，而故障处理、升级和复盘沉淀在观测云内统一完成。
本文围绕三个部分展开：
| 部分 | 职责 | 结果 |
|---|---|---|
| 观测云 | 接收外部事件，生成故障，执行电话通知和升级策略 | 形成标准 Incident 和 OnCall 升级闭环 |
| Func | 连接飞书与观测云，承接事件回调、按钮回调和升级回调 | 完成消息解析、故障创建、状态修改和卡片刷新 |
| 飞书 | 群内触发、卡片展示、值班人确认和状态同步 | 让一线协作留在原群内完成 |
观测云
观测云是这套方案里的 OnCall 承载平台。Func 将飞书群里的客户反馈转成外部事件后，观测云故障中心会基于事件创建 Incident，并将它纳入统一的故障生命周期管理。
故障中心不仅负责记录故障状态，也负责把故障真正通知到人：当故障进入待分配状态后，可以按照值班表和升级策略进行电话通知；如果一线值班人未在预期时间内确认，系统会继续升级到二线、三线，直到有人接手处理。
飞书机器人不替代故障中心，而是把群内自然语言反馈接入故障中心，并把故障状态回写到飞书群里。这样既保留观测云的电话告警和升级能力，也让客户群里的协作状态保持透明。
| 能力 | 说明 |
|---|---|
| 外部事件接入 | 将飞书群内 @机器人消息转成观测云事件 |
| 故障中心 | 根据外部事件生成 Incident，并维护故障状态、处理人和确认时间 |
| 电话告警 | 按值班策略对当前值班人发起电话通知，确保故障不是只停留在群消息里 |
| 升级策略 | 当一线未确认或需要升级时，继续通知二线、三线值班人 |
| 通知对象 | 将升级动作回调到 Func API，刷新飞书群卡片 |
| OpenAPI | 支持查询故障、修改故障状态、读取值班策略 |
故障中心在方案中的定位：飞书负责把客户群里的反馈变成入口，Func 负责做协议转换和回调编排，观测云故障中心负责把入口事件变成可响应、可升级、可分析、可复盘的标准故障流程。
故障中心能力如何支撑 OnCall 闭环
| 能力 | 在本实践中的作用 | 带来的价值 |
|---|---|---|
| 值班表 | 维护一线、二线、三线的当日值班人与通知顺序 | 减少人工判断当前该找谁，保证责任人明确 |
| OnCall 升级 | 按确认超时、未接听或升级规则继续通知下一层级 | 避免故障停留在单个值班人，提升关键问题触达率 |
| 故障生命周期 | 统一维护待分配、处理中、已解决等状态 | 让群内反馈进入标准 Incident 管理，而不是散落在聊天记录中 |
| 通知对象 | 在故障升级或状态变化时回调 Func | 让飞书卡片能够跟随故障状态和当前值班层级同步刷新 |
| 故障分析看板 | 沉淀故障量、级别分布、响应效率、升级次数和处理结果 | 支持团队复盘 OnCall 质量，识别高频问题和流程瓶颈 |
Func
Func 是飞书与观测云之间的连接层，建议拆成两个函数 API，分别处理飞书回调和观测云故障升级回调。
| Func API | 用途 | 配置位置 |
|---|---|---|
| oncall-event | 接收飞书事件回调和卡片按钮回调 | 飞书开放平台事件与回调 |
| oncall-incident-hook | 接收观测云故障升级 Webhook | 观测云故障中心通知对象 |
两个 API 的职责必须区分清楚：
- 飞书开放平台的 URL Verification、群消息事件、卡片按钮回调，都配置到
oncall-event； - 观测云故障升级通知对象的 Webhook，配置到
oncall-incident-hook； - 两个地址不要混用，否则会出现 URL Verification 不返回、卡片无法刷新或升级回调无法处理的问题。
关键实现可以抽象为以下伪代码：
def oncall_event(request):
# 入口 1：飞书开放平台会先做 URL Verification，用于确认回调地址可用。
event = parse_feishu_callback(request)
if event.type == "url_verification":
return {"challenge": event.challenge}
# 入口 2：用户点击飞书卡片按钮，例如“待分配”或“处理中”。
if event.type == "card.action.trigger":
action = parse_card_action(event)
check_oncall_permission(action.operator) # 只允许当前值班人操作。
update_guance_incident_status(action.incident_uuid, action.target_status)
return update_feishu_card(action.message_id) # 更新同一张卡片，不重复发新卡片。
# 入口 3：飞书群里有人 @机器人，并描述客户问题。
if event.type == "im.message.receive_v1":
message = normalize_message(event)
if not mentioned_target_bot(message):
return skip("bot mention not found") # 普通 @成员或普通聊天不创建故障。
payload = build_guance_external_event(message) # 生成观测云外部事件。
incident = push_event_and_resolve_incident(payload) # 推送事件并反查 Incident。
return send_feishu_incident_card(message.chat_id, incident)
def oncall_incident_hook(request):
# 入口 4：观测云故障中心升级策略触发后，通过通知对象回调这里。
incident = parse_guance_incident_webhook(request)
card_state = load_card_state(incident) # 找到这次故障对应的飞书卡片。
latest = query_guance_incident(incident.uuid) # 以观测云 Incident 最新状态为准。
return update_feishu_card(card_state.message_id, latest)
这段逻辑的重点不是代码量，而是三件事：只处理真正 @目标机器人的消息、用观测云 Incident 作为状态源、始终更新同一张飞书卡片。
飞书
飞书侧负责用户触发和状态展示。用户只需要在目标群中 @机器人并描述问题，后续故障创建、状态流转和升级刷新由 Func 与观测云自动完成。
飞书机器人至少需要具备以下能力：
| 能力 | 用途 |
|---|---|
| 接收群内 @机器人消息 | 识别用户是否在目标群触发故障 |
| 发送消息 | 向原群发送故障交互卡片 |
| 更新消息 | 在状态变化或故障升级后更新同一张卡片 |
| 读取必要用户标识 | 判断卡片按钮操作者是否为当前值班人 |
生产环境建议只保留必要权限，不要一次性开放文档、云盘、通讯录全量权限。
示例场景
用户在指定飞书群中发送：
@TW bot 线上登录接口异常，多个客户反馈无法登录，请协助排查
系统应自动完成以下动作：
- 判断消息来自目标群，并且确实包含目标机器人 @ 信息；
- 将消息摘要推送为观测云外部事件；
- 解析外部事件对应的故障和 Incident ID；
- 在原群发送故障交互卡片；
- 值班人点击卡片按钮，将状态从待分配推进到处理中，再推进到已解决；
- 如果故障升级到二线或三线，观测云升级 Webhook 回调 Func API，刷新飞书群里的同一张卡片。
推荐卡片内容如下，避免暴露观测云内部敏感字段：
Incident：INC-20260525-0501
级别：P0
来源：飞书：Oncall测试
当前值班人：一线：xxx
摘要：线上登录接口异常，多个客户反馈无法登录，请协助排查
状态：待分配
确认时间：待确认
关联ID：ONCALL-6635095FC0C1
操作流程
整体链路可以理解为三条闭环：消息触发闭环、卡片操作闭环和故障升级刷新闭环。
| 闭环 | 流程 |
|---|---|
| 消息触发闭环 | 飞书群消息 -> Func 事件回调 -> 观测云外部事件 -> Incident -> 飞书群卡片 |
| 卡片操作闭环 | 值班人点击按钮 -> Func 卡片回调 -> 修改 Incident 状态 -> 更新飞书卡片 |
| 升级刷新闭环 | 观测云故障升级 -> 通知对象 Webhook -> Func 升级回调 -> 更新飞书卡片值班层级 |
必须特别注意触发条件：只有消息中包含目标机器人 @，才允许触发外部事件。普通 @群成员、@其他机器人、或者没有 @目标机器人的消息，都应该被跳过。
应该触发：@TW bot 客户反馈登录异常
不应触发：@guance 客户反馈登录异常
不应触发：客户反馈登录异常
推荐配置模板
生产环境建议把配置分为三类：观测云配置、Func 运行配置、飞书机器人配置。以下示例只展示变量结构，不展示真实密钥和真实 Webhook。
观测云配置
# 必填：观测云 OpenAPI Key，用于查询/修改 Incident、读取值班策略等。
DF_API_KEY=<观测云 OpenAPI Key>
# 必填：观测云外部事件 Webhook，Func 会把飞书群消息推送到这里创建故障。
GUANCE_WEBHOOK_URL=<观测云外部事件 Webhook>
# 可选：观测云 OpenAPI 地址，私有化或海外站点时再调整。
GUANCE_OPENAPI_BASE_URL=https://openapi.guance.com
Func 运行配置
# 必填：允许触发故障的机器人名称，只有消息中 @这个机器人 才会创建外部事件。
ONCALL_TRIGGER_BOT_NAMES=["TW bot"]
# 推荐：限制哪些飞书群可以触发故障，避免其他群误触发。
ONCALL_TARGET_CHAT_IDS=<允许触发故障的飞书群 ID 列表>
# 必填：观测云账号与飞书用户 ID 的映射，用于判断谁可以点击卡片按钮。
ONCALL_GUANCE_ACCOUNT_MAP=<观测云账号到飞书用户 ID 的映射>
# 展示用：卡片中“当前值班人”的显示文案，不参与真实权限判断。
ONCALL_LEVEL1_DISPLAY=一线：xxx
ONCALL_LEVEL2_DISPLAY=二线：xxx
ONCALL_LEVEL3_DISPLAY=三线：xxx
# 推荐开启：开启后，只有映射中的当前值班人可以操作卡片按钮。
ONCALL_STRICT_CARD_PERMISSION=true
飞书机器人配置
# 必填：飞书应用 App ID，用于获取 tenant_access_token、发送和更新卡片。
FEISHU_APP_ID=<飞书应用 App ID>
# 必填：飞书应用 App Secret，请作为敏感变量保存，不要写入文档正文或日志。
FEISHU_APP_SECRET=<飞书应用 App Secret>
# 可选：飞书事件回调 Verify Token；如果配置了，Func 会校验回调来源。
FEISHU_VERIFY_TOKEN=<飞书事件回调 Verify Token，可选>
# 默认即可：飞书开放平台地址，私有化环境才需要调整。
FEISHU_OPENAPI_BASE_URL=https://open.feishu.cn
其中 ONCALL_LEVEL1_DISPLAY、ONCALL_LEVEL2_DISPLAY、ONCALL_LEVEL3_DISPLAY 只负责卡片展示，不参与真实权限判断。真实权限仍应以 ONCALL_GUANCE_ACCOUNT_MAP 中的用户标识为准。
系统会自动完成什么
用户只需要在飞书群里 @机器人描述问题，后续动作由 Func 脚本和观测云自动完成。
| 自动动作 | 说明 |
|---|---|
| 创建标准故障 | 外部事件进入观测云后，故障中心自动生成 Incident，记录级别、来源、关联 ID 和当前状态。 |
| 匹配值班表 | 系统按照当前值班表确定一线值班人，避免临时人工确认今天该找谁。 |
| 电话通知与升级 | 故障进入待分配后触发电话通知；若未及时确认，按 OnCall 升级策略继续通知二线、三线。 |
| 同步处理状态 | 值班人确认、处理中、已解决等动作回写到观测云，并同步刷新飞书卡片。 |
| 沉淀分析数据 | 故障中心分析看板可用于观察故障量、响应效率、升级次数和处理闭环情况。 |
本次实践的验证结果
当前飞书侧已经完成端到端闭环验证，建议在文档中保留以下几张效果图，读者可以直观看到故障从触发到升级再到解决的全过程。
这些验证结果不只是飞书卡片的展示效果，也能体现观测云故障中心的关键能力：自动创建 Incident、按值班表触达当前值班人、按 OnCall 策略升级到二线和三线，并把状态流转沉淀为后续分析和复盘数据。
待分配状态
客户在飞书群中 @机器人后，观测云故障中心创建 Incident，并通过 OnCall 策略电话通知当前一线值班人。此时飞书卡片展示为待分配，提示值班人需要确认。
处理中状态
值班人点击卡片按钮后，Func 调用观测云 OpenAPI 将故障状态更新为处理中，并刷新飞书群内同一张卡片，表示故障已经有人接手。
已解决状态
故障处理完成后，值班人再次通过卡片更新状态。观测云 Incident 进入已解决状态，飞书卡片同步展示最终结果，不再提供继续流转按钮。
升级通知与卡片刷新
当故障未被及时确认或触发升级策略时，观测云会继续通知二线、三线值班人，并通过通知对象回调 Func，刷新飞书卡片中的当前值班层级。
用户需要检查什么
上线前建议按以下清单验收。
1. 检查观测云配置
2. 检查 Func 配置
3. 检查飞书配置
最佳实践
为了让飞书 × 观测云 OnCall 联动流程稳定运行，建议遵循以下原则。
| 原则 | 建议做法 | 价值 |
|---|---|---|
| 值班表先行 | 在观测云中维护一线、二线、三线值班表，Func 只读取结果或接收回调。 | 让当天责任人由平台统一管理，减少脚本和人工维护成本。 |
| 升级策略明确 | 将未确认、未处理、超时等升级条件配置在观测云 OnCall 策略中。 | 确保电话通知和层级升级可配置、可审计、可复用。 |
| 状态口径收敛 | 以观测云故障中心的 Incident 状态作为唯一事实源，飞书卡片只做展示和操作入口。 | 避免群消息、脚本状态和故障状态不一致。 |
| 通知对象解耦 | 用观测云通知对象回调 Func，再由 Func 刷新飞书卡片。 | 让升级、状态变化和群内反馈保持同步，但不把业务规则写死在机器人里。 |
| 看板复盘 | 定期查看故障中心分析看板，关注故障量、升级次数、响应耗时和解决效率。 | 从一次性处理走向持续优化 OnCall 质量和客户响应体验。 |
总结
通过飞书机器人联动观测云外部事件，可以把群内自然语言反馈转化为标准 OnCall 故障，并通过观测云完成电话通知和升级策略，通过飞书交互卡片完成确认、处理、解决和状态同步。
对用户来说，使用方式保持简单：在目标飞书群中 @机器人描述问题。对运维和客户成功团队来说，后续的故障创建、值班通知、状态流转、升级刷新和权限校验都由系统自动完成。
这套实践的核心不是单个机器人能力，而是用观测云故障中心把飞书群里的客户反馈转化为可触达、可升级、可追踪、可分析的标准 OnCall 流程。飞书负责让触发入口足够轻，Func 负责连接两端，观测云负责承载值班表、电话通知、升级策略、故障状态和分析看板，最终形成可运营、可复盘的故障响应闭环。
