OneUptime Runbook 执行完全指南三种触发方式、执行视图与审计追溯【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文基于 OneUptime 开源仓库中的 Runbook 运行文档英文原版 / 法文版撰写。Runbook运行手册是 OneUptime 平台中可复用的响应流程——由有序的「手动步骤 自动化步骤」组成可挂接到事件Incident、告警Alert或计划维护Scheduled Maintenance上。阅读本文后你将掌握 Runbook 执行的三种触发路径、执行视图的界面要素、手动与自动化步骤的交织运行机制、取消与重跑的正确姿势以及如何利用快照语义与 50KB 输出上限构建可审计、可追溯的应急响应流程。一、Runbook 执行的三种触发路径在 OneUptime 中一条 Runbook 执行Execution只会通过以下三种方式被创建通过规则自动触发——在事件、告警或计划维护的Rules → Runbook Rules菜单中配置规则当实体的标题或描述匹配正则时自动启动 Runbook。详细规则语义见 Runbook 规则文档。从 Runbook 页面手动触发——在某个 Runbook 的概览页点击Run Now立即运行。这种执行不挂接到任何事件、告警或计划维护属于临时性ad-hoc运行。从实体流Entity Feed手动触发——在某个事件、告警或计划维护上点击Run Runbook运行 Runbook。这种执行会**挂接attached**到该实体并出现在该实体的页面中。从源码结构看第三种路径体现得尤为直接RunbookExecution数据模型为每次执行预留了incidentId、alertId、scheduledMaintenanceId三个可空外键以及记录触发人的triggeredByUserId字段见 RunbookExecution.ts。执行创建时这些外键被写入执行便天然地关联到来源实体。提示规则触发的执行同样会写入来源实体外键——规则文档中明确说明规则触发后「执行被链接到来源实体它会出现在事件/告警/计划维护的页面以及 Runbook 的 Executions 列表中」。二、执行视图一次运行的完整检查清单打开任意一条执行你会看到一个检查清单ChecklistUI。每个步骤显示以下要素状态徽标Status Pill——Pending待处理、Running运行中、Waiting for you等待你操作、Done已完成、Skipped已跳过、Failed失败。标题与描述——在执行时从 Runbook 复制而来快照语义见下文第六节。输出Output可折叠——stdout、返回值、HTTP 响应等。错误信息——仅当步骤失败时显示。对于处于WaitingForUser状态的手动步骤会显示Mark Complete标记为已完成和Skip跳过两个按钮。一个值得注意的细节只要执行尚未进入终态页面每 3 秒轮询刷新一次因此你可以近乎实时地看到自动化步骤完成。这在人工值守大屏或共享排查页面上非常有用——响应者无需手动刷新即可持续跟踪进度。从源码可以印证这些状态的定义步骤级状态枚举RunbookStepExecutionStatus包含Pending、Running、WaitingForUser、Completed、Skipped、Failed、Cancelled七种见 RunbookStepExecutionStatus.ts而执行级状态RunbookExecutionStatus则包含Scheduled、Running、WaitingForManualStep、Completed、Failed、Cancelled六种见 RunbookExecutionStatus.ts。可以看到「Waiting for you」对应步骤的WaitingForUser而执行整体会停驻在WaitingForManualStep。三、手动与自动化步骤的交织一次执行、一条时间线Runbook 的核心能力在于把「人类判断」和「机器执行」编排进同一条时间线。文档给出的经典故障切换流程如下脚本步骤Script捕获系统当前状态写入 S3。手动步骤Manual「通过状态页横幅通知客户」。由值班响应者确认勾选。HTTP 步骤HTTP通过 PagerDuty 呼叫 DBA。手动步骤Manual「确认从库已切换为主库」。由值班响应者确认勾选。脚本步骤Script向 Slack 发送「一切已恢复」消息。其中步骤 2 和步骤 4 会暂停执行直到有人勾选确认步骤 1、3、5 自动运行。整条流程是一次执行、一条时间线、一个真相源one source of truth——每个步骤的状态、输出、错误与耗时都被永久记录在该执行上事后复盘无需再靠记忆拼凑。源码层面RunbookExecution模型中的stepExecutions字段是一个 JSON 数组每条记录「镜像 Runbook 中的一个步骤并携带其状态、输出与时间戳」见 RunbookExecution.ts 相关的模型注释RunbookExecution.ts。手动步骤被勾选后执行会从下一个步骤继续——这正是「暂停-恢复」机制的落点。四、取消一次执行在执行的页面点击Cancel Execution取消执行即可终止运行。取消的语义很明确当前步骤如果有会正常结束不会被强行中断后续步骤不再启动执行状态变为Cancelled。对应的执行级状态Cancelled已包含在RunbookExecutionStatus枚举中见 RunbookExecutionStatus.ts。对于挂接在事件/告警/计划维护上的执行取消操作同样适用——例如误触发或场景已变化时值班人员可以干净地收尾而不是放任流程继续执行。五、输出保留与 50KB 上限为防止失控脚本撑爆数据库每个步骤的输出被限制为 50KB。超出部分会被截断并在截断处打上标记见 配置与安全文档。如果你需要更大的产物artifacts正确的做法是在脚本中将大文件写入S3 或日志系统然后把URL 存储在返回值return value中。这样既保证了执行记录足够轻量又不丢失可审计的原始数据——复盘时只需点击步骤输出里的 URL 即可拉取完整产物。配置文档中的运维建议也呼应了这一点「捕获 URL而不是数据块Capture URLs, not blobs」——一旦步骤产生超过几 KB 的输出就写入 S3 或日志栈并返回 URL。六、重新运行 Runbook不可变的快照语义一条 Runbook 执行是一次性、不可变的记录one-shot, immutable record。要重新运行请再次点击Run Now——这不会覆盖原执行而是创建一条全新执行携带 Runbook 当前步骤的新鲜快照snapshot原始执行保持原样用于审计追踪。这种快照语义贯穿整个 Runbook 设计步骤的「标题与描述」在执行时被复制到执行记录上见第二节模型中的runbookNameSnapshot字段专门保存「执行创建时的 Runbook 名称」「即使 Runbook 之后被重命名或删除也会保留」见 RunbookExecution.ts运行时编辑 Runbook 模板永远不会篡改在途in-flight的执行——执行继续使用自己的快照。这对事后审计意义重大每次故障处理的记录是「当时真实发生过的步骤与配置」而不是「后来被修改过的模板」。规则文档也强调执行是「步骤被快照到新执行上」且「编辑事件标题不会重新触发规则」。七、检索历史执行Executions 标签页每个 Runbook 都有一个Executions执行记录标签页列出该 Runbook 的全部运行记录支持按以下维度过滤状态status——Scheduled/Running/WaitingForManualStep/Completed/Failed/Cancelled等日期范围date range来源实体source entity——事件、告警或计划维护。反过来从某个事件、告警或计划维护的页面进入Runbooks 标签页会展示挂接在该实体上的所有执行。规则触发的运行也可以在Runbooks → Executions下按状态、Runbook 或日期过滤查看见 规则文档。结合数据模型可以更清晰地理解检索能力RunbookExecution对runbookId、incidentId、alertId、scheduledMaintenanceId都建立了数据库索引Index()注解这正是 Executions 列表按 Runbook 或按来源实体快速过滤的底层支撑见 RunbookExecution.ts 等处的索引声明。八、源码视角执行背后的数据模型与队列8.1 RunbookExecution 表结构核心数据表RunbookExecution的关键字段见 RunbookExecution.ts字段类型说明projectId/runbookIdObjectID所属项目与所属 Runbook必填runbookNameSnapshotShortText执行时的 Runbook 名称快照statusShortText执行级状态RunbookExecutionStatusstepExecutionsJSON步骤级执行状态数组状态、输出、时间戳incidentId/alertId/scheduledMaintenanceIdObjectID可空来源实体外键triggeredByUserIdObjectID可空手动触发的用户startedAt/completedAtDate起止时间failureReasonLongText可空失败原因权限方面该模型的表级访问控制将「创建执行」授予ProjectOwner、ProjectAdmin、CreateRunbookExecution、ProjectMember、RunbookAdmin、RunbookMember「读取执行」额外允许Viewer与RunbookViewer见 RunbookExecution.ts。这与 配置与安全文档 中Runbook权限组的说明一致RunbookAdmin聚合了全部细粒度权限。8.2 队列与执行引擎Runbook 执行运行在RunbookBullMQ 队列上Worker 并发数为25可在部署中调整以应对大量并发运行。手动步骤被勾选后执行会重新入队从下一步继续——让 Worker 保持热状态避免整条链路等待。JavaScript 与 Bash 步骤永远不会在 OneUptime Worker 上执行而是派发为RunnerJob含targetAgentId、脚本、状态机Pending → Claimed → Running → Succeeded/Failed/TimedOut/Cancelled、租约、输出与退出码由你在自建基础设施中安装的 Runbook Agent 领取执行详见 配置与安全文档 与 Agent 文档。这意味着即使执行视图上的脚本步骤「瞬间完成」其实际计算发生在你的主机上Worker 只负责编排与汇总。8.3 超时与失败兜底执行相关的超时配置见 Authoring 文档执行超时Execution timeoutJavaScript、Bash、HTTP 步骤默认30 秒可在步骤上逐条覆盖领取超时Claim timeoutBash/JavaScript 步骤默认2 分钟——Worker 等待所选 Agent 领取任务的时长超时则步骤失败两者的可设范围均为1 秒到 1 小时超出范围的值会在步骤运行时被钳制既不会禁用超时也不会让 Worker 槽位被无限占用。这些限制与 50KB 输出上限一起构成了 Runbook 执行的安全边界脚本再失控也只能拖住自己所在的步骤而无法阻塞平台或数据库。九、实战小结一条可落地的执行工作流综合以上机制一个生产可用的 Runbook 执行流程可以这样设计规则兜底在事件/告警/计划维护的Rules → Runbook Rules中配置标题正则让匹配实体自动启动 Runbook参考 规则文档 中的 DB 故障切换示例。手动补充值班人员需要临场排查时从实体流点击Run Runbook手动挂接一次执行。交织执行脚本步骤捕获状态 → 手动步骤等人工确认 → HTTP 步骤调用外部系统 → 手动步骤再确认 → 脚本步骤收尾发通知全程一条时间线。异常处理误触发时点击Cancel Execution脚本可能被重试时保持步骤幂等Worker 重启或 Agent 租约过期可能导致自动化步骤重复执行。事后审计在 Runbook 的Executions标签页按状态/日期/来源实体筛选结合每次执行快照与步骤输出含 S3 URL撰写复盘报告。至此你已完整掌握 OneUptime Runbook 的「运行」这一环节——从三种触发路径到执行视图从取消/重跑到快照审计再到背后的数据模型与队列机制。下一步可深入阅读 Runbook 编写Authoring、Runbook 规则Rules 与 Runbook Agent 安装构建完整的自动化响应体系。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考