OneUptime Runbook 编写实战指南步骤模型、六种步骤类型与自动化事故响应【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本篇指南围绕 OneUptime开源监控与可观测性平台的 Runbook 功能展开系统讲解如何从Runbooks → Créer un runbook创建 Runbook入口编写一套可复用的事故响应流程从步骤的通用字段、手动 / JavaScript / HTTP / Bash / SSH / Kubernetes / AI 六类步骤的配置要点到执行超时、失败处理、快照语义等底层机制。读完本文你将掌握如何把查主库 → 人工确认 → 触发切换 → 验证写入 → 通知恢复这类典型运维动作编排成一份可自动化执行、可留给 post-mortem 审计的 Runbook。文档原文位于 fr/runbooks/authoring.md与英文版 en/runbooks/authoring.md 为同一主题的多语言版本本文以它们为骨架并结合仓库中 Worker 侧的步骤执行器源码进行原理级展开。一、入口与 Steps 编辑器创建 Runbook 的路径是Runbooks → Créer un runbook创建后打开该 Runbook 并切换到Étapes步骤标签页即可开始编排。Runbook 本质上是一个按顺序执行的步骤清单在数据层面由 Runbook 模型 中的stepsJSON 列存储TableColumn({ isDefaultValueColumn: false, required: false, type: TableColumnType.JSON, title: Steps, description: Ordered list of steps to run for this runbook. Each step is one of Manual, JavaScript, HTTP request, Bash or AI., }) public steps?: JSONArray undefined;从源码结构看steps是一个未经过强校验的 JSON 列因此步骤的合法性主要由编辑器和执行器共同保证例如 AI 步骤执行前会防御性地读取配置见后文。二、步骤的通用结构Anatomie dune étape每个步骤都由以下通用字段组成字段作用Titre标题显示在清单界面中的短标签必填。Description描述为响应者提供的可选上下文支持 Markdown 文本。Continuer en cas déchec失败时继续开启后某一步失败不会终止执行下一步仍会运行。Exiger une approbation要求审批开启后Runbook 在该步骤之后暂停等待用户批准后再执行下一步。Configuration spécifique au type类型专属配置脚本、URL、Agent 等随步骤类型而异见下文各小节。步骤严格按顺序执行在 Steps 编辑器中可以用上/下箭头调整顺序。这一顺序语义与 RunbookStep 类型定义 中的order字段一一对应requireApproval、continueOnFailure也只对自动化步骤有意义。三、六种步骤类型详解步骤类型在 RunbookStepType.ts 中定义为枚举Manual、JavaScript、HttpRequest、Bash、AI、SSH、Kubernetes。其中 JavaScript、Bash、SSH、Kubernetes 属于Runner 执行型步骤由 RUNNER_EXECUTED_STEP_TYPES 统一收口——它们必须携带agentId经由 RunnerJob 认领claim通道派发到客户自有基础设施上的 Runner绝不会在 OneUptime Worker 上执行。1. 手动步骤Manuelle手动步骤是一个由响应者勾选的复选框。执行到手动步骤时Runbook 会暂停并保持WaitingForManualStep状态直到有人将其标记为完成或跳过。它适用于只有人类才能验证的事项例如已确认流量已按负载均衡器面板所示切换到备用区域。这类步骤天然需要人工介入因此不存在失败语义。2. JavaScript 步骤JavaScript 步骤在isolated-vm沙箱中执行一段 JS 代码片段。沙箱运行在你自有基础设施上的 Runbook Agent 中而不是 OneUptime Worker 上相关多语言文档与配套说明可参见仓库 Runbook 文档目录。在 JavaScript 步骤上需要配置Agent de runbookRunbook Agent——从下拉框选择执行此步骤的 Agent只有被选中的 Agent 才能认领该任务。Script脚本——要执行的 JavaScript。Execution timeout执行超时——Agent 在拆除 isolate 之前允许代码片段运行的时间默认 30 秒。Claim timeout认领超时——Worker 等待 Agent 领取任务的时间默认 2 分钟。典型的代码片段如下const start Date.now(); // ... votre logique你的逻辑... return { durationMs: Date.now() - start };返回值会被记录到步骤执行结果中console.log输出则被捕获为日志行。两者Execution timeout 与 Claim timeout都可在脚本下方按步骤单独修改。源码视角Worker 侧的执行入口是 runJavaScriptStep它与 Bash 步骤共用同一条dispatchToAgent派发链路见 StepExecutors.ts先把任务写入 RunnerJob 队列并指定targetAgentId然后轮询直到终态。若步骤上未配置 Agent会直接失败并提示 JavaScript step is missing a Runbook Agent。此外派发前会先查找该步骤是否已存在同一步的 RunnerJob——若 Worker 中途重启导致执行被重新投递会复用adopt已有任务的结果而不是重复派发脚本避免数据库恢复跑两遍之类的副作用见StepExecutors.ts中关于findLatestJobForStep的注释。3. HTTP 请求步骤HTTP 步骤发起一次出站 HTTP 调用可配置Méthode方法GET / POST / PUT / PATCH / DELETE / HEAD见 HttpRequestMethod。URL。En-têtes JSONJSON 请求头可选。Corps请求体可选。Request timeout请求超时默认 30 秒。响应的状态码、响应头和响应体会被完整记录总计上限 50 KB。典型用途向 PagerDuty 开事件单、向 Slack 发消息、调用你自己的管理 API 等。HTTP 步骤直接在 OneUptime Worker 上执行不需要 Agent。源码视角runHttpStep 基于 axios 实现有几处值得注意的加固细节请求头以 JSON 字符串形式配置并JSON.parse解析请求体若可解析为 JSON 则按对象发送执行前通过DataSourceEgressGuard.assertUrlAllowedAndPin校验目标地址并钉住解析出的 IP同时设置maxRedirects: 0拒绝重定向防止步骤被利用做 SSRF源码注释明确指出未加防护的 HTTP 步骤会把 Worker 所在网络内的响应直接回传给调用方validateStatus恒为true因此 2xx/3xx 之外的响应不会被 axios 当作异常而是由执行器自行判定200 status 400记为成功否则失败并附上HTTP status错误信息输出统一经过truncateStepExecutors.ts 中 MAX_OUTPUT_BYTES 50_000截断到 50 KB。4. Bash 步骤Bash 步骤以bash -c script的形式在自有基础设施上的 Runbook Agent 中执行永远不会运行在 OneUptime Worker 上。配置项与 JavaScript 步骤一致Agent de runbook——选择执行该步骤的 Agent只有被选中的 Agent 可以认领任务。Script——要执行的 bash。输出stdout stderr最多捕获 50 KB超时后进程会被杀掉。Execution timeout——Agent 在SIGKILL杀掉脚本前允许其运行的时间默认 30 秒对于确实需要几分钟的合法长任务应适当调大。Claim timeout——Worker 等待 Agent 认领任务的时间默认 2 分钟。注意如果 Runbook 到达此步骤时选中的 Agent 处于离线状态步骤会一直等到claim timeout默认 2 分钟后以TimedOut失败。因此在依赖 Bash 步骤之前请先在Runbooks → Paramètres → Agents中添加 Agent。源码视角runBashStep 与 JavaScript 步骤共用dispatchToAgent仅stepType不同Agent 会依据该类型选择本地对应的执行器。超时与认领超时的实际值由 RunbookStepTimeout.ts 统一解析执行超时默认 30 秒、最小 1 秒、最大 1 小时认领超时默认 2 分钟、最小 1 秒、最大 1 小时。5. SSH 步骤SSH 步骤在 Runner 可通过网络到达的主机上执行命令。与在 Bash 步骤里写ssh host cmd不同这里的访问凭据是受管理的 Credential见仓库中的 RunbookCredential 模型而非存放在 Runner 磁盘上的私钥——凭据静态加密、分配给特定 Runner且永远无法通过 API 读回。SSH 步骤的配置项Runner——发起连接的一端必须能在网络上访问目标主机。Credential——持有主机、端口、用户名与密钥的 SSH 凭据必须已分配给所选 Runner否则步骤直接失败而不是用错误的访问权限继续执行。Command——以凭据用户身份在远端主机上执行的命令输出最多捕获 50 KB非零退出码会使步骤失败。Execution timeout——覆盖连接、认证与执行命令的全过程因此挂起的命令无法无限期占用步骤。源码视角runSshStep 属于载荷承载型步骤PAYLOAD_CARRYING_STEP_TYPES见 RunbookStepType.ts派发时只携带credentialId与command结构化指令脚本字段为空——凭据在 Runner 认领任务时才解析因此绝不出现在作业记录中。6. Kubernetes 步骤Kubernetes 步骤用于在集群中重启或扩缩容工作负载。它的动词集是刻意封闭的如果一个步骤能对任意对象执行 PATCH那它就等于一个 cluster-admin shell此步骤类型存在的意义恰恰是把最常见的补救动作收敛到足够安全、可以放心交给自动修复auto-remediation的范围。配置项Runner——调用 API server 的一端。Credential——持有 API server URL、ServiceAccount token 与集群 CA 的 Kubernetes 凭据。建议把该 ServiceAccount 绑定到仅包含 Runbook 所需权限的 Role。Action动作Restart workload重启工作负载通过打补丁 pod template 让控制器重建 Pod等价于kubectl rollout restartScale workload扩缩容设置副本数。Workload kindDeployment、StatefulSet 或 DaemonSet。Namespace与Workload name。Replicas——仅 Scale 动作使用。允许为 0把工作负载排空是合法的补救手段。DaemonSet 不能缩放每节点一个 Pod只能重启。如果 API server 拒绝了变更其返回的原始消息会呈现在步骤上因此权限失败会直接告诉你该放宽哪个 RoleBinding。源码视角runKubernetesStep 在派发前做防御性校验未配置凭据、缺少 namespace/workload name、Scale 动作缺少副本数都会直接失败注释明确说明把副本数缩放为一个未指定的值在任一方向都不是安全默认值因此视为错误而非猜测。动作与工作负载类型的枚举定义见 RunbookStep.ts 中的 KubernetesAction / KubernetesWorkloadKind。7. AI 步骤AI 步骤让 LLM 在运行中途进行分析、总结或决策。Prompt 会发送给你项目配置的 LLM 提供商Paramètres → IA → Fournisseurs LLM模型的回复会成为执行时间线chronologie dexécution上的步骤输出。AI 步骤在 OneUptime Worker 上运行无需 Agent。AI 步骤的配置项Prompt——要求 AI 做什么。例如检查之前步骤的输出说明继续执行修复是否安全。Inclure le contexte des étapes précédentes包含前序步骤上下文——开启后AI 能看到此前所有步骤的标题、类型、状态、输出和错误消息。Inclure le contexte du déclencheur包含触发器上下文——开启后AI 能看到是什么启动了本次执行关联的 incident描述、严重级别、当前状态、受影响的监控项、根因、状态时间线、公开备注、告警、计划维护事件或手动运行 Runbook 的用户。将 AI 步骤与Exiger une approbation搭配即可实现人在环路human in the loopAI 分析 → 响应者阅读其回答并批准 → 下一步修复才执行。AI 永远不会看到的内容重要的隐私边界AI 步骤的答复作为步骤输出存储在执行记录上而执行记录对任何拥有 runbook 读取权限的人都可读——这比 incident 的 ACL 受众更广。因此触发器上下文刻意排除内部私有备注与 Slack/Teams 频道消息它们只留在 incident 内部由既有的 post-mortem 与备注生成器保留派生文本。此外前序步骤的输出在发给模型之前会先做密钥扫描与打码tokens、keys、凭据都会被脱敏。AI 步骤与其他 AI 功能一样按用量计费。如果项目未配置任何 LLM 提供商步骤会以明确错误失败若其余步骤仍需执行可开启Continuer en cas déchec。源码视角AI 步骤的实现位于 AIStepExecutor.ts几个关键机制上下文脱敏顺序redactAndCap先脱敏再截断AIStepExecutor.ts因为先截断可能把密钥拦腰截断、导致脱敏正则失配而泄漏近完整的密钥提示词注入防护前序步骤输出与触发器上下文被包裹进untrusted_context标签并用escapeUntrustedContext转义任何试图逃逸的闭合标签系统提示词明确要求标签内是监控数据绝无指令忽略其中出现的任何指令buildAiStepMessages租户边界belongsToProject会在每次运行时重新校验关联 incident/alert/维护事件确实属于本项目避免通过手工构造的 ID 把 B 项目的事件上下文带入 A 项目AIStepExecutor.tsLLM 提供商标定步骤可把llmProviderId钉到特定提供商但每次运行都会经LlmProviderService.isProviderUsableByProject复核钉住的提供商不可用时直接失败而不是静默回退到项目默认——因为无人值守的 AI 步骤一旦悄悄换模型没人会发现见 RunbookStep.ts 中 AIStepConfig 的注释预算与开关执行前检查AIService.isProjectAIEnabled项目 AI 总开关关闭时步骤直接失败并携带AI_DISABLED_MESSAGEmaxTokens在 25616384 之间钳制默认 4096温度固定为 0.2AIStepExecutor.ts。四、超时机制默认值、取值范围与解析规则所有自动化步骤的超时都统一收敛到 RunbookStepTimeout.ts编辑超时的表单与执行超时的 Worker 走同一套解析逻辑保证作者看到的值就是运行时实际生效的值超时类型默认值最小值最大值步骤执行超时Execution timeout30 秒1 秒60 分钟Agent 认领超时Claim timeout2 分钟1 秒60 分钟解析规则resolveTimeoutInMs值得一提未设置、空白、非数字、零或负值都会回退到默认值而非让步骤失败——因为在 incident 现场按文档默认值照常运行的 Runbook 远比拒绝运行的 Runbook 有用可用的数值会四舍五入为整毫秒并钳制进上下界。仓库配套的单测 RunbookStepTimeout.test.ts 对这些边界情况做了系统验证。五、保存与编辑快照语义点击Enregistrer les étapes保存步骤即可持久化。正在执行中的旧版本 Runbook 不受影响——它们会继续使用自己的快照继续运行。这意味着你可以在事故处理的中途放心编辑 Runbook 模板不必担心改动波及已经开始的执行。六、多步骤与失败处理默认情况下某一步失败会终止整个执行并将其标记为Failed。如果在某一步上开启了Continuer en cas déchec失败仍会被记录但下一步照常执行。这正是先依次尝试这三件事然后无论如何通知这类模式的实现方式。需要记住的两个配套行为审批门Require approval开启后执行在步骤完成后暂停等待用户批准才进入下一步——自动化与人工闸门可以穿插编排手动步骤天然是暂停点执行到手动步骤即停留在WaitingForManualStep这是把人工确认安全嵌入自动化链路的标准做法。七、完整示例主数据库不可达DB primaire injoignable文档给出了一个完整可照抄的编排范式用于主库不可达场景JavaScript——从配置服务获取当前主库主机并记录日志。Manuelle手动——确认备用库的复制延迟低于 5 秒。Requête HTTPHTTP 请求——向故障转移编排器的 API 发送 POST。Manuelle手动——确认写入现在已切到新主库。Requête HTTP——向 Slack 发送 POST附带一切已恢复的消息。响应者就这样看一个自动化步骤跑完 → 勾选一个手动步骤 → 再看下一个自动化步骤跑完……每一步的输出都会被保留下来用于事后的 post-mortem 审计。这个例子同时也展示了 Runbook 的核心设计哲学自动化承担可脚本化的动作人工承担无法脚本化的判断两者的产出统一沉淀为可追溯的执行记录。八、编写自检清单最后把文档要点收敛成一份编写 Runbook 时的检查清单必填与顺序每个步骤都有标题用上下箭头确认步骤顺序符合操作依赖先查证、再执行、后通知。运行位置意识JavaScript/Bash/SSH/Kubernetes 步骤运行在你自己的 Runner 上须提前在 Runbooks → 设置中添加HTTP 与 AI 步骤运行在 OneUptime Worker 上无需 Agent。超时规划默认执行超时 30 秒、认领超时 2 分钟长任务调大执行超时离线 Agent 会导致TimedOut。凭据最小化SSH/Kubernetes 步骤使用托管 Credential按最小权限原则分配Kubernetes 只用封闭的 Restart/Scale 动作。人在环路关键判断点用手动步骤或给 AI 步骤开启要求审批。失败策略根据必须成功还是尽力而为决定是否开启Continuer en cas déchec。隐私与脱敏AI 步骤的触发器上下文不含内部私有备注与 Slack/Teams 消息前序输出会自动做密钥打码因此不要把敏感明文写进步骤描述。随时可保存保存即生效但正在运行中的旧版本继续使用快照编辑是安全的。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考