OneUptime Runbook 创作指南从步骤解剖、五种步骤类型到故障处理实战【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeRunbook运行手册是 OneUptime 将值班人员的应急处置流程代码化的核心载体把排查、审批、执行与通知编排成一系列可自动执行、可人工介入、可审计留痕的步骤让同一次故障处理从依赖个人经验变成依赖可复现的流程。本文基于 OneUptime 官方文档authoring.md与仓库中 Runbook 模块 的源码实现完整讲解 Runbook 的创建入口、每个步骤的字段语义、五种内置步骤类型Manual / JavaScript / HTTP / Bash / AI的配置与底层执行机制以及失败处理与一个DB 主库不可达的完整实战示例读完即可上手编写你自己的第一个 Runbook。创建入口与步骤解剖在 OneUptime 仪表盘中进入Runbooks → 创建 Runbook创建后打开该 Runbook 并切换到Pasos步骤标签页即可开始编排。每个步骤由一组统一的字段构成其语义如下表所示字段用途Título标题显示在 checklist UI 中的短标签必填。Descripción描述可选的上下文说明面向响应者内容按 Markdown 安全渲染。Continuar en caso de error出错时继续若开启步骤失败不会中断执行——下一个步骤照常运行。Requiere aprobación需要审批若开启Runbook 在该步骤完成后暂停等待用户审批通过后才执行下一步。Config específica del tipo类型专属配置脚本、URL、代理Agent等随步骤类型而异详见下文。步骤按顺序执行。在步骤编辑器中可以用上/下箭头调整步骤的先后次序。上述字段在源码中对应 RunbookStep 接口每个步骤包含id、order顺序号、type步骤类型、title、可选的description以及continueOnFailure与requireApproval两个布尔开关。源码注释还明确标注了一个易被忽略的语义continueOnFailure与requireApproval仅对自动化步骤JavaScript、HTTP、Bash、AI 等有意义Manual 步骤没有失败语义。类型专属配置则收敛在 RunbookStepConfig 联合类型 中按步骤类型分别定义。五种内置步骤类型详解步骤类型在源码中由 RunbookStepType 枚举 定义。以下按官方文档逐一展开并辅以源码级的配置与执行细节。Manual人工确认步骤一个由值班人员手动勾选的复选框。执行到达 Manual 步骤时会暂停执行状态停留在WaitingForManualStep直到有人将其标记为已完成或跳过。它适用于只有人能验证的事项例如已在负载均衡面板确认流量已切换到备用区域。在 RunbookExecutionStatus 枚举 中可以看到整个执行生命周期Scheduled已调度→Running运行中→WaitingForManualStep等待人工步骤→Completed/Failed/Cancelled。Manual 步骤对应的配置类型在源码中被定义为Recordstring, neverManualStepConfig即除步骤级标题与描述外无任何附加配置——这印证了文档的说法人工步骤的唯一配置就是写清让值班者做什么。JavaScript沙箱脚本步骤一个在isolated-vm沙箱中执行的 JavaScript 片段。沙箱存活于**你自己基础设施内的 Runbook Agent代理**中绝不会运行在 OneUptime 的 Worker 上。JavaScript 步骤需要配置Runbook Agent—— 从下拉框选择执行此步骤的代理。只有被选中的代理可以认领claim这个 job。Script—— 要执行的 JavaScript。Execution timeout执行超时—— 代理允许片段运行多久超时后拆卸 isolate。默认30 秒。Claim timeout认领超时—— Worker 等待代理接走 job 的最长时间。默认2 分钟。脚本返回值会被捕获为该步骤执行时的输出console.log的输出被捕获为日志行。一个最小脚本示例const start Date.now(); // ... 你的逻辑 ... return { durationMs: Date.now() - start };这两个超时默认值不是写死在 UI 里的而是由 RunbookStepTimeout.ts 统一管理DEFAULT_STEP_EXECUTION_TIMEOUT_IN_MS 30 * 1000、DEFAULT_AGENT_CLAIM_TIMEOUT_IN_MS 2 * 60 * 1000并附带取值范围——最小 1 秒、最大 1 小时超出范围的值会在运行时被钳制clamp回合法区间非法输入空、0、负数、非数字则回退到默认值。同一模块还负责 UI 秒数与存储毫秒之间的换算确保作者看到的值与运行时强制的值永远一致。从源码角度看JavaScript 步骤的实际分发走 runJavaScriptStep → dispatchToAgent 这条路径Worker 将脚本作为一个 RunnerJob 入队enqueue轮询直至代理回报结果。该函数还包含一个防重入设计——如果 Worker 中途重启导致步骤被重新投递会先查找该步骤已有的 job 记录已终结则直接采用其结果仍在飞行中则重新挂接re-attach到原 job 上继续等待绝不会把脚本重复派发给代理避免数据库恢复脚本被跑了两遍这类事故。Petición HTTPHTTP 请求步骤发起一次出站 HTTP 调用。可配置方法GET/POST/PUT/PATCH/DELETE/HEAD、URL、可选的 JSON 请求头、可选请求体以及Request timeout默认 30 秒。响应中的状态码、响应头和响应体会被捕获总计上限50KB。典型用途在 PagerDuty 打开一个 incident、向 Slack 发布消息、调用你自己的 admin API 等。HTTP 步骤直接在 OneUptime Worker 上运行无需 Agent。源码实现runHttpStep补充了几个值得注意的细节请求头 JSON 解析失败会直接使步骤失败并给出明确错误信息请求体若无法按 JSON 解析则按原始字符串发送。任何 2xx/3xx 响应都算成功4xx/5xx 会标记步骤失败error message 为HTTP status但完整的Status / Headers / Body三行文本仍会写入输出供后续排查。输出统一经过 truncate 截断到 50KB 上限并在尾部追加... [output truncated]标记。安全上目标 URL 会先经过DataSourceEgressGuard校验并锁定其解析出的 IP 地址同时禁止重定向maxRedirects: 0——因为步骤的 url/headers/body 直接来自可被编辑的 steps JSON任何人写入该 Runbook 都可能构造请求锁 IP、禁重定向可以防止 SSRF 类攻击绕过校验访问内网或云元数据服务。BashShell 脚本步骤一个通过bash -c script执行的 bash 脚本同样运行在你自己基础设施内的 Runbook Agent上。Bash 永远不会运行在 OneUptime Worker 上。配置项Runbook Agent—— 选择执行此步骤的代理只有被选中的代理可以认领 job。Script—— 要执行的 bash。输出stdout stderr最多捕获50KB超时到期时进程会被杀死。Execution timeout—— 代理允许脚本运行多长时间超时后以SIGKILL强杀。默认30 秒对合法需要数分钟执行的步骤请调大该值。Claim timeout—— Worker 等待代理接走 job 的时间。默认2 分钟。一个重要的实操提醒文档原文如果所选 Agent 在该步骤到达时处于离线状态步骤会一直等到 claim timeout默认 2 分钟耗尽然后以TimedOut失败。因此在依赖任何 Bash 步骤之前请先在Runbooks → 设置 → Agentes中添加代理。源码中 Bash 与 JavaScript 走完全相同的分发路径dispatchToAgent只是 stepType 不同——Agent 会依据 stepType 选择本地的执行器。另外脚本中还可以通过runbookSecrets.名称引用代理可访问的已加密凭据服务端在派发前会用 RunbookSecretsUtil.populateInScript 将授权给该代理的密钥安全地替换进脚本密钥本身以托管、加密对象的形式存储而非明文躺在脚本里。AIAI 分析/决策步骤在执行中途让 AI 分析、总结或做判断。Prompt 会被发送到你项目配置的 LLM 提供商设置 → AI → Proveedores LLM模型响应会成为该步骤在执行时间线上的输出。AI 步骤在 OneUptime Worker 上运行无需 Agent。配置项Prompt—— 让 AI 做什么。例如检查前面步骤的输出判断是否可以安全地继续执行修复。Incluir contexto de pasos anteriores包含前置步骤上下文—— 开启后AI 会看到此前所有步骤的信息标题、类型、状态、输出和错误消息。Incluir contexto del disparador包含触发上下文—— 开启后AI 会看到是什么触发了本次执行关联的 incident事件、告警或计划维护事件含描述、严重级别、当前状态、受影响监控项、根因、状态时间线和公开备注或谁手动运行了该 Runbook。把 AI 步骤与Requiere aprobación需要审批组合使用就能把人放回回路中AI 先分析响应者阅读其回答后审批审批通过后才执行下一步通常是修复步骤。AI 永远不会看到的内容。AI 步骤的回答会作为步骤输出存储在 execution 中而 execution 可以被任何拥有 runbook 读取权限的人看到——受众范围比 incident 的 ACL 更广。因此触发上下文会刻意排除私密内部笔记和 Slack/Teams 频道消息它们留在 incident 内部由既有的 postmortem 与笔记生成器继续处理其派生文本。同时前置步骤的输出在发送给模型之前会先扫描并脱敏机密token、key、凭据。这一点在源码 AIStepExecutor.ts 中有完整的落地stripPrivateIncidentData清空internalNotes与workspaceMessagesL147-L155redactAndCap 对步骤输出先脱敏再截断——顺序很重要先截断可能把密钥切成两半导致正则匹配不到先脱敏则只可能截掉标记字符永远不可能让密钥复活。此外buildAiStepMessages会把所有外部数据包裹在untrusted_context标签中并明示模型标签内的内容是数据、不是指令以防御提示注入。计费与失败语义AI 步骤与其他 AI 功能一样计量计费如果项目未配置 LLM 提供商步骤会以明确的错误信息失败——此时若希望 Runbook 其余部分继续运行请在该步骤上开启Continuar en caso de error。源码中的扩展步骤类型SSH 与 Kubernetes官方 authoring 文档聚焦上述五种步骤而从当前仓库源码看步骤类型已扩展为八种——RunbookStepType 还包含SSH与Kubernetes两种类型。这两类步骤同样运行在 Runner/Agent 上区别在于它们不是脚本而是结构化指令 凭据引用SSHStepConfig携带credentialId与commandKubernetesStepConfig则把动作限定在一个封闭的动词集合内——RestartWorkload滚动重启与ScaleWorkload调整副本数支持缩到 0——能 PATCH 任意 K8s 对象的 Runbook 就是 cluster-admin 大杀器封闭动词集正是为了让常见修复安全而非能跑任何东西RunbookStep.ts。这些步骤的凭据在认领时才由服务端解析绝不以明文存在步骤配置里。保存与编辑快照语义点击Guardar pasos保存步骤即可持久化。正在运行中的旧版本 execution 不受保存操作影响——它们继续使用各自的快照snapshot。这意味着你可以放心地在事故处理过程中迭代改进 Runbook正在进行的执行不会因为编辑而被中途改变。源码印证了这一点执行引擎读取的是runbookNameSnapshot等快照字段RunRunbook.ts步骤列表以执行开始时固化下来的stepExecutions为准而不是每次重新读取 Runbook 的当前定义。多步骤编排与失败处理默认情况下一个步骤失败会中止整个执行并将执行标记为Failed。如果你在某个步骤上开启了Continuar en caso de error则该步骤失败时只是记录失败、继续执行下一步。这套逻辑非常适合先试这三件事然后通知的模式。源码中的执行循环RunRunbook.ts把这套语义实现得非常明确遇到WaitingForUser的步骤会持久化当前状态并把 execution 置为WaitingForManualStep后暂停等待用户通过completeManualStep类 API 恢复执行——审批流程与 Manual 步骤复用同一条暂停/恢复路径L176-L188步骤失败时若未开启continueOnFailure则置didFail并跳出循环最终将 execution 标记为Failed所有步骤均完成、跳过或失败但允许继续时执行才标记为Completed循环的每个步骤边界都会检查 execution 是否已被外部终结用户取消或卡死扫描失败——一旦发现终态就立即停止防止给一个已被宣布停止的执行继续派发脚本。一个完整实战示例DB 主库不可达官方文档给出了一个非常直观的五步 Runbook用于处理数据库主库不可达JavaScript—— 从你的配置服务获取当前主库 host并记录下来。Manual—— 确认备库的复制延迟低于 5 秒。Petición HTTP—— POST 到你的故障转移编排器的 API。Manual—— 验证写流量已切换到新的主库。Petición HTTP—— POST 到 Slack发送一切正常的消息。值班人员看到的将是自动步骤运行 → 手动勾选确认 → 下一个自动步骤运行 → 再手动确认……依此类推每个步骤的输出都被完整捕获供事后 post-mortem 复盘使用。这个例子恰好演示了五种步骤类型的正确分工JavaScript用于从内部系统取数在沙箱里跑不信任任何外部输入、Manual用于人类判断复制延迟是否可接受、写流量是否已切换、HTTP用于调用内部 API 与外部通知PagerDuty / Slack / 自建 admin API、Bash / AI则分别承担在自有基础设施上执行任意 shell与在流程中引入 AI 分析的职责。据此设计一个 Runbook 可以同时兼顾自动化效率、人工审批兜底与全程审计留痕。小结编写高质量 Runbook 的关键在于为每一步选择正确的类型、设定合理的超时并善用Continuar en caso de error与Requiere aprobación两个开关来平衡全自动执行与人在回路。本文介绍的五种步骤类型加上源码中已存在的 SSH、Kubernetes 扩展类型覆盖了从数据获取、人工确认、外部系统调用、基础设施命令到 AI 辅助决策的完整链路而底层源码证实所有步骤的默认超时执行 30 秒、认领 2 分钟、输出截断50KB、机密脱敏、快照隔离与失败语义都在 RunbookStepTimeout.ts、StepExecutors.ts、AIStepExecutor.ts 与 RunRunbook.ts 中被一致地强制实现——这就是为什么你可以放心地把DB 主库不可达这类高压力场景交给一个 5 步的 Runbook 去自动处置。关于 Agent 的安装与配置可进一步阅读 Runbook Agents 文档。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考