企业官网建设流程全解析

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent

事件（Incident）申报是 OneUptime 一切事件管理的起点：创建一条记录、分配事件编号、触发值班策略、并按需通知状态页订阅者。本文以 OneUptime 官方文档《Declarar un incidente》为主体，结合仓库源码深入讲解四种申报方式（手动向导、模板、监控条件自动申报、API）、每一步表单字段的语义、事件编号机制，以及服务端在事件创建瞬间执行的完整规则链，帮助你掌握从"手工敲入"到"全自动声明"的完整实战方案。

四种申报方式一览

OneUptime 中事件只有四种进入方式，且殊途同归——最终都会在Incident表中写入一行数据，带有严重级别（severity）、当前状态（current state）和受影响资源列表。区别只在于"谁在填字段"：

这四种方式写入的是同一个模型（Incident 模型定义），因此由探针自动申报的事件与值班人员手工申报的事件完全一致，唯一的差别是少量由服务端填充的控制列（如isCreatedAutomatically、createdCriteriaId、createdByProbe）。

方式一：手工申报事件

进入Incidentes → Todos los Incidentes（事件 → 全部事件），点击事件列表右上角的Declarar incidente（申报事件）按钮，会打开一张标题为Declarar nuevo incidente（申报新事件）的卡片，表单分五步：Detalles del incidente（事件详情）、Recursos afectados（受影响资源）、Roles de Incidente（事件角色）、De guardia（值班）和Más（更多）。底部提交按钮同样叫Declarar incidente。

只有第一步包含必填字段。如果时间紧迫，填完事件详情直接提交即可——资源、角色、值班策略都可以稍后在事件页面上再补充。

第一步：事件详情

• Título（标题）— 必填。所有人都会在列表、Slack，以及（若事件可见）状态页上看到的单行摘要。占位符为Incident Title。
• Descripción（描述）— 可选，使用 Markdown 编写。该字段会展示在状态页上，因此应面向客户而非团队内部撰写。可稍后在事件侧边菜单的Descripción处编辑。
• Declarado el（申报时间）— 表单中必填，默认值为当前时间。它是整个事件持续时间的计时起点，因此补录已发生的事件时请把它回拨到实际开始时间。对应的数据列是declaredAt，模型层面定义为必填且默认now()（见 Incident.ts）。
• Gravedad del Incidente（事件严重级别）— 必填。从项目已配置的严重级别中选择；新项目自带Incidente crítico（严重事件）、Incidente mayor（重大事件）和Incidente menor（轻微事件）。对应外键incidentSeverityId。
• Estado del Incidente（事件状态）— 可选。留空则事件落在标记为isCreatedState的状态上，新项目默认是Identificado（已识别）。仅当补录一个已越过该阶段的事件时才需要手动修改。对应currentIncidentStateId外键。

状态下拉框异常：如果项目没有任何带isCreatedState标记的状态，创建调用会失败并提示前往设置添加创建状态。这通常只发生在状态被大量编辑过的项目中，可参考 Estados y severidades de incidentes（事件状态与严重级别）。

第二步：受影响资源

• Recursos afectados（受影响资源）— 一个统一的搜索框，可附加监控器（monitors）、主机（hosts）、Kubernetes 集群、Docker 主机、Podman 主机和服务等。底层它们是事件的不同关联关系（monitors、hosts、kubernetesClusters、dockerHosts、podmanHosts、services等），表单将其合并为一个选择器。从模型源码可以看到这些多对多关系表（如IncidentMonitor、IncidentHost、IncidentKubernetesCluster、IncidentDockerHost、IncidentPodmanHost）均定义在 Incident.ts 中。
• Change Monitor Status to（将监控器状态改为）— 可选。选择一个监控器状态，应用于本事件附加的所有监控器，从而把"申报事件"和"标记监控器降级"合并为一次操作。对应changeMonitorStatusToId外键。

即使看似多余也要附加监控器：事件与状态页之间的关联正是通过事件上的监控器建立的——当某个状态页的资源是本事件的监控器之一时，该状态页才会展示这个事件。如果事件未附加任何监控器，发送给订阅者的状态变更通知会被直接跳过。详见 Recursos y grupos de la página de estado。

第三步：事件角色

• Asignar roles del incidente（分配事件角色）— 为团队成员分配项目定义的角色，部分角色允许多个用户。

角色在Incidentes → Ajustes → Roles de Incidente（事件 → 设置 → 事件角色）中配置，可定义响应期间可分配的角色，例如 Incident Commander（事件指挥官）、Responder（响应人）等。跳过此步时，若首次状态变更时无人占据 Incident Commander 角色，系统会自动分配一位。

第四步：值班

• Política de guardia（值班策略）— 多选，选择在本事件创建时执行的值班策略，对应事件上的onCallDutyPolicies字段。

这是值班策略直接附加到事件的唯一位置。严重级别本身不携带值班策略：严重级别只是一个标签，只在值班规则中作为匹配条件影响通知。在Incidentes → Reglas → Reglas de guardia（事件 → 规则 → 值班规则）中配置的规则会把它们的策略叠加到此处选择的策略之上，最终执行集合是两者去重后的并集。

第五步：更多

• Etiquetas（标签）— 可选，高级功能：拥有这些标签访问权限的团队成员才能访问该事件。
• Notificar a suscriptores de la página de estado（通知状态页订阅者）— 复选框，默认勾选。控制是否在事件创建时向订阅者发送邮件，对应shouldStatusPageSubscribersBeNotifiedOnIncidentCreated字段。内部噪音类记录请取消勾选。
• Incidente privado（私有事件）— 复选框，默认不勾选，对应isPrivate字段。私有事件仅对其属主用户、属主团队成员、项目管理员和项目属主可见，并在所有状态页上隐藏，不受其它设置影响。事件列表会用红色Private徽标标记它。

Should be visible on status page?（是否显示在状态页上，对应isVisibleOnStatusPage）不在此向导中，默认值为true。稍后可在事件侧边菜单的Ajustes（设置）中修改，界面中标记为Visible en la página de estado（在状态页上可见）。

方式二：从模板申报

如果反复申报同类型事件（同样的标题模式、同样的严重级别、同样的值班策略），把它保存为模板只需一次。

点击Crear desde plantilla（从模板创建，位于Declarar incidente旁边的轮廓按钮），打开Crear incidente a partir de plantilla（从模板创建事件）模态框，内含Seleccionar plantilla de incidente（选择事件模板）下拉框。选择模板后，创建表单会以预填方式打开，提交前可修改任何内容。若项目还没有模板，则会看到No Incident Templates（无事件模板）模态框，其中的Create Template（创建模板）按钮会带你到Incidentes → Ajustes → Plantillas de Incidentes（事件 → 设置 → 事件模板）。

模板用自有的六步向导构建——Información de la plantilla（模板信息）、Detalles del incidente（事件详情）、Recursos afectados（受影响资源）、De guardia（值班）、Propietarios（属主）、Etiquetas（标签）：

几条快速规则：

• 模板不在模板列表中直接编辑：创建后打开它才能修改。
• 模板只填充留空的字段。在创建页面上，模板作为可覆盖的预填值应用；在 API 中，只有当请求把某个字段留为undefined时，服务端才从模板填充该字段。调用方传入的值永远优先。

方式三：从监控条件自动申报

大多数事件不应需要人工输入。在监控器的条件编辑器中，打开When filters match, declare an incident.（过滤器匹配时声明事件）开关，会出现一个Crear incidente（创建事件）区域和Añadir incidente（添加事件）按钮——同一个条件过滤器可以声明多个事件。

每条记录包含：

• Título del incidente（事件标题）— 支持模板变量，占位符示例：{{monitorName}} is down。
• Gravedad（严重级别）— 必填。
• Descripción del incidente（事件描述）— 同样支持模板变量。
• De guardia → Políticas de guardia（值班策略）— 事件创建时执行的策略。
• Roles de Incidente（事件角色）— 预分配团队成员到角色。
• Propiedad y etiquetas → Equipos propietarios（属主团队）、Usuarios propietarios（属主用户）、Etiquetas（标签）。
• Opciones avanzadas（高级选项）→ Resolver incidente automáticamente（条件不再匹配时自动解决事件）、Mostrar incidente en la página de estado（在状态页显示事件）、Incidente privado（私有事件）和Notas de Remediación（补救说明）。

标题、描述和补救说明中可用的完整{{variable}}标记列表见 Plantillas de incidentes y alertas（事件与告警模板）。

此类事件会被服务端打上标记：isCreatedAutomatically被设置为true，createdCriteriaId记录是哪个条件过滤器触发的，createdByProbe记录是哪个探针观察到的（对应模型中的createdByProbeId外键与isCreatedAutomatically、createdCriteriaId字段，见 Incident.ts）。除此之外，它们与手工申报的事件行为完全一致。

方式四：通过 API 申报

事件模型暴露了标准 CRUD 端点，因此POST /api/incident即可创建事件。使用在Ajustes del proyecto → Claves API（项目设置 → API 密钥）生成的 API 密钥进行认证，放在apikey请求头中发送——密钥本身标识了项目，因此无需单独传项目 ID：

curl -X POST https://oneuptime.com/api/incident \ -H "apikey: $ONEUPTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": { "title": "Checkout latency above SLO", "description": "Investigating elevated p99 latency on the checkout service.", "incidentSeverityId": "<incident-severity-id>" } }'

请求体中常用字段：

• title— 唯一真正必须提供的字段。
• declaredAt— 此处可选（虽然表单必填）。省略时服务端使用当前时间。
• incidentSeverityId与currentIncidentStateId— 服务端会校验两者与 API 密钥属于同一项目，否则拒绝请求。Change Monitor Status to背后的监控器状态也执行同样的校验。从 IncidentService.ts 的创建前校验链可以看到，服务端在分配事件编号之前会先行校验事件严重级别、事件状态、监控器状态、SLO 等引用是否都属于该项目。
• createdIncidentTemplateId— 应用保存的模板。省略的字段从模板填充，显式传入的字段保持不变。

关联端点为/api/incident-state、/api/incident-severity和/api/incident-state-timeline。仓库自带的 API 参考文档 包含每个端点的精确请求/响应格式，包括如何表达监控器等关系字段。

事件编号与前缀

每个事件在创建时都会从项目级计数器获得一个顺序编号。它存储在两列中：incidentNumber（纯整数）和incidentNumberWithPrefix（实际展示的值）。未配置前缀时，展示值为#42这种形式。

修改方法：进入Incidentes → Ajustes → Más Ajustes（事件 → 设置 → 更多设置）。Prefijo de número（编号前缀）卡片中有Prefijo de número de incidente（事件编号前缀）字段（最多 20 个字符，占位符INC-）：设置后同一事件将显示为INC-42。留空则保持默认的#。该卡片还包含Prefijo de número de episodio de incidente（事件情节编号前缀），用于情节（episode）编号。

在服务端，编号通过ProjectService.incrementAndGetIncidentCounter(projectId)获取，并在创建前逻辑中写入incidentNumber与incidentNumberWithPrefix（无前缀时形如#42，有前缀时形如INC-42），见 IncidentService.ts。

编号显示为事件列表的第一列（可点击进入事件）、事件Vista General（概览）中的Número de incidente（事件编号），事件动态（feed）中的创建消息也会使用incidentNumberWithPrefix || "#" + incidentNumber作为展示名（见 IncidentService.ts）。

事件创建瞬间发生了什么

创建调用所做的工作远不止写入一行。按顺序展开：

1. 服务端补齐空缺。declaredAt取当前时间，当前状态取项目的isCreatedState状态，事件编号与前缀编号从项目计数器分配。
2. 应用模板。若传入了createdIncidentTemplateId，仅填充调用方未定义的字段。
3. 执行隐私规则。匹配的隐私规则将事件标记为私有。这是最先运行的规则引擎，确保后续所有步骤看到的是正确的隐私设置。对应IncidentPrivacyRuleEngineService.applyRulesToIncident（见 IncidentService.ts）。
4. 执行属主规则。添加匹配规则点名的属主用户与属主团队。
5. 执行标签规则。添加与事件匹配的标签。
6. 执行值班规则。在Incidentes → Reglas → Reglas de guardia中启用且条件匹配的所有规则，都把其策略添加到事件上。没有优先级顺序，也不短路：所有匹配规则都会触发，策略会去重。
7. 执行 runbook 规则。附加并启动匹配的 runbook。详见 Runbooks。
8. 执行值班策略。事件上的所有策略——来自向导、模板继承或规则添加——以IncidentCreated事件类型并行执行。某个策略失败不会阻断其它策略。
9. 订阅者入队。若通知状态页订阅者保持开启且事件在状态页上可见，则进入队列。投递由后台任务处理，不占用你的请求线程。服务端会依据shouldStatusPageSubscribersBeNotifiedOnIncidentCreated将订阅者通知状态置为Pending或Skipped（见 IncidentService.ts）。
10. 触发工作流。On Create Incident（创建事件）触发器启动基于它构建的任何工作流。详见 Visión general de los flujos de trabajo。

从源码看，onCreateSuccess中以 Promise 链顺序执行了隐私规则、工作区操作、事件动态创建、状态变更处理、属主添加、监控器状态变更、禁用主动监控、属主规则、标签规则、值班规则、runbook 规则、值班策略执行、事件分组、SLA 创建、提醒调度、AI 事件调查（AI SRE）与自动补救规则等步骤，每一步都有独立的 try/catch，单步失败不会阻断整条链（见 IncidentService.ts）。

至此事件"活着"了：计入侧边栏事件菜单的Incidentes Activos（活跃事件）徽标（任何不带isResolvedState标记的状态都算活跃），出现在包含其任一监控器的状态页上，Línea de Tiempo de Estado（状态时间线）开始记录。

继续阅读

• Visión general de los incidentes — 事件模型如何融入整体。
• Estados y severidades de incidentes — 状态标记的作用及如何添加自定义状态。
• Notas, responsables y actividad de incidentes — 公开/私有备注、属主与活动动态。
• Configuración y automatización de incidentes — 模板、自定义字段、角色、规则与工作流触发器。
• Suscriptores y anuncios — 谁会知道你刚申报的事件。
• Plantillas de incidentes y alertas — 自动申报事件可用的模板变量。

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent