> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 发布与管理事件

> 了解如何在状态页中发布故障和维护事件，管理事件生命周期与时间线更新

状态页通过**事件**来传达服务状态变化。Flashduty 状态页支持两类事件：**故障**（Incident）和**维护**（Maintenance），分别对应意外中断和计划性维护场景。

## 事件类型与状态

### 故障（Incident）

故障表示意外发生的影响服务可用性的事件。故障具有以下生命周期状态：

| 状态                     | 说明               |
| ---------------------- | ---------------- |
| **排查中**（Investigating） | 团队已知悉问题，正在调查根因   |
| **已定位**（Identified）    | 问题根因已确认，正在制定修复方案 |
| **监控中**（Monitoring）    | 修复措施已实施，正在监控恢复情况 |
| **已恢复**（Resolved）      | 问题已完全修复，服务恢复正常   |

### 维护（Maintenance）

维护表示计划性的服务变更事件，用于提前通知用户可能的服务影响。维护具有以下生命周期状态：

| 状态                 | 说明         |
| ------------------ | ---------- |
| **已排期**（Scheduled） | 维护已安排，尚未开始 |
| **进行中**（Ongoing）   | 维护正在进行     |
| **已完成**（Completed） | 维护已结束      |

组件仅在维护**实际执行窗口**内（状态变为"进行中"到关闭）被标记为"维护中"；尚未开始的计划维护不会标记任何组件，也不影响可用性图表与日历展示。

***

## 发布事件

<Steps>
  <Step title="打开发布入口">
    在状态页详情中，故障与维护有各自独立的发布入口：

    * **发布故障**：进入 **故障** 页，点击 **新的故障**；如需补录历史故障，点击 **回溯故障**
    * **发布维护**：进入 **维护** 页，点击 **计划维护**
  </Step>

  <Step title="填写事件信息">
    配置以下字段：

    | 字段              | 说明                                 |
    | --------------- | ---------------------------------- |
    | **故障名称 / 维护名称** | 事件的简要标题，将在状态页上公开显示（必填）             |
    | **当前状态**        | 事件的初始状态                            |
    | **消息**          | 事件的详细说明（必填），展示在状态页上用于描述事件状态        |
    | **受影响组件**       | 选择受此事件影响的组件，并为每个组件设定影响状态（至少选择 1 个） |
    | **通知订阅者**       | 是否在发布时向订阅者发送通知                     |

    发布维护时还必须填写 **影响时段**（计划开始与结束时间），且结束时间必须晚于开始时间。

    <Note>
      **响应人员**（responders）字段仅支持通过 API / CLI 设置，控制台发布表单中不提供该选项。
    </Note>
  </Step>

  <Step title="添加初始更新">
    每个事件至少包含一条时间线更新。系统会根据你填写的信息自动生成初始更新记录。
  </Step>

  <Step title="发布事件">
    确认信息后，点击 **发布故障** 或 **发布维护** 完成事件创建。
  </Step>
</Steps>

### 组件影响状态

发布事件时，你需要为每个受影响组件指定当前的服务状态：

<Tabs>
  <Tab title="故障影响状态">
    | 状态                          | 说明          |
    | --------------------------- | ----------- |
    | 🟢 **运行正常**（Operational）    | 服务运行正常      |
    | 🟡 **性能下降**（Degraded）       | 服务可用但性能受到影响 |
    | 🟠 **部分中断**（Partial Outage） | 部分功能不可用     |
    | 🔴 **完全中断**（Full Outage）    | 服务完全不可用     |
  </Tab>

  <Tab title="维护影响状态">
    | 状态                            | 说明     |
    | ----------------------------- | ------ |
    | 🟢 **运行正常**（Operational）      | 服务运行正常 |
    | 🔵 **维护中**（Under Maintenance） | 服务正在维护 |
  </Tab>
</Tabs>

<Note>
  当事件进入终止状态（故障的"已恢复"或维护的"已完成"）时，所有受影响组件必须恢复为"运行正常"状态。
</Note>

### 消息支持的 Markdown 格式

事件消息与时间线更新的编辑器支持以下 Markdown 元素，公开状态页会按相同格式渲染：

| 格式     | 语法示例                                 |
| ------ | ------------------------------------ |
| **粗体** | `**重要通知**`                           |
| *斜体*   | `*预计 30 分钟*`                         |
| 链接     | `[查看详情](https://example.com)`，在新窗口打开 |
| 无序列表   | `- 影响范围`                             |
| 有序列表   | `1. 第一步`                             |
| 表格     | 标准 GFM 表格语法，编辑器工具栏提供**插入表格**按钮       |

<Note>
  不支持的元素（如标题、图片）在公开状态页上会渲染为纯文本；出于安全考虑，链接仅接受 `http` / `https` 地址。
</Note>

<Note>
  状态页首页（landing）对事件**最新更新**的描述做了限高截断（约 280px），超出部分以底部渐隐效果提示还有更多内容；完整内容请进入事件详情页查看。
</Note>

***

## 时间线更新

事件发布后，你可以通过添加**时间线更新**来记录事件的进展，让订阅者持续了解最新情况。

每条时间线更新可以包含：

| 内容         | 说明                  |
| ---------- | ------------------- |
| **时间戳**    | 该更新对应的实际发生时间        |
| **状态变更**   | 将事件推进到下一个生命周期状态（可选） |
| **消息**     | 当前进展的说明文字（必填）       |
| **组件状态变更** | 调整受影响组件的服务状态（可选）    |

<Tip>
  时间线更新遵循以下不变量，故障与维护事件统一适用：

  * **追加更新**：新更新的时间戳必须**大于或等于**当前时间线中最后一条更新的时间戳。否则会被拒绝，错误信息形如 `at must be greater than or equal to previous timeline update time (<prev_at>)`。
  * **编辑中间的更新**：新的时间戳必须落在 `[前一条更新的时间戳, 后一条更新的时间戳]` 闭区间内（含两端）。
  * **编辑或删除第一条更新**：系统会自动用新的第一条更新的时间戳同步事件的 `start_time`，无需手动调整。
  * **编辑更新与结束时间**：编辑更新后，新的 `start_time` 不能晚于事件的 `close_time`，否则更新会被拒绝，错误信息为 `close_time must be greater than or equal to start_time`（例如将计划维护的第一条更新改到其计划结束时间之后）。
  * **维护事件 + 按计划自动更新**：若上述操作改变了 `start_time`，系统会同时重新调度待执行的自动开始任务，使其与新的开始时间对齐。
</Tip>

### 关闭事件

将事件状态更新为终止状态即可关闭事件：

* 故障：更新状态为 **已恢复**（Resolved）
* 维护：更新状态为 **已完成**（Completed）

关闭事件时，系统会自动记录关闭时间。所有受影响组件此时必须为"运行正常"状态。

### 重新打开事件

已关闭的事件可以重新打开。添加新的时间线更新并将状态设为非终止状态即可重新激活事件。

***

## 维护自动调度

对于维护事件，你可以设置**计划开始时间**和**计划结束时间**，并启用**按计划自动更新**功能。系统将在指定时间自动推进维护状态：

* **计划开始时间**到达时：自动将状态从"已排期"更新为"进行中"
* **计划结束时间**到达时：自动将状态从"进行中"更新为"已完成"

<Warning>
  自动调度的维护窗口不能超过 **30 天**。如果计划结束时间距当前时间超过 30 天，系统将拒绝创建。
</Warning>

### 手动覆盖

即使启用了自动调度，你仍然可以随时手动更新维护状态：

* 如果你手动将维护推进为"进行中"，系统会取消待执行的自动开始任务
* 如果你手动将维护标记为"已完成"，系统会取消待执行的自动结束任务

删除已启用自动调度的维护事件时，系统会自动取消所有待执行的调度任务。

***

## 回溯事件

当服务状态变化未能及时发布时，你可以创建**回溯事件**（Retrospective Event）来补充历史记录。

回溯事件允许你：

* 声明一次已经发生的故障或维护
* 精确设置事件的发生时间和结束时间
* 按真实时间顺序构建事件时间线
* 准确关联受影响的组件

回溯事件与普通事件在状态页上的展示方式完全一致，且会纳入事件历史和服务可用性统计。

<Note>
  创建回溯故障时，时间线中至少需要一条非「已恢复」状态的更新，用于呈现故障的演进过程。
</Note>

<Tip>
  如果回溯事件创建时即为终止状态，且未指定结束时间，系统会自动将最后一条更新的时间戳作为结束时间。
</Tip>