OneUptime Runbook 编排指南从步骤类型到源码级实现的自动化应急手册编写【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文以 OneUptime 开源可观测平台中的 Runbook应急手册编排功能为主题系统讲解如何在Runbooks → Create Runbook中创建包含多类型步骤的自动化应急流程。读完本文你将掌握 Manual、JavaScript、HTTP、Bash、SSH、Kubernetes 与 AI 七种步骤类型的配置要点、失败处理与审批机制并能结合 RunnerJob 数据模型 与 RunbookStep 类型定义 理解每一步骤在 Worker 与 Runbook Agent 之间的真实调度链路。创建 Runbook 与步骤编辑器在 OneUptime 中进入Runbooks → Create Runbook创建一个新的手册随后打开它并切换到Steps标签页开始编写步骤。Runbook 本身是一个项目内的数据对象其核心结构定义在 Runbook 数据模型 中name短文本按项目唯一与slug全局唯一、由名称自动生成description长文本可选isEnabled布尔值默认truestepsJSON 数组即步骤编辑器中保存的有序步骤列表labels多对多关联 Label用于分类与权限联动。从源码结构看步骤以 JSON 形式持久化在steps列中编辑时整体保存见后文保存与编辑一节这也解释了为什么在途执行使用的是保存时的步骤快照。步骤的基本构成Anatomy of a step每一个步骤都包含以下字段字段作用Title在 checklist UI 中显示的短标签必填。Description可选的给响应人看的上下文说明支持 Markdown 文本。Continue on failure开启后步骤失败不会中断执行下一个步骤仍会继续运行。Require approval开启后运行流程会在该步骤之后暂停等待用户批准后才执行下一步。Type-specific config与步骤类型相关的专属配置脚本、URL、Agent 等详见下文。步骤按顺序执行可以在 Steps 编辑器中使用上/下箭头调整顺序。在类型层面RunbookStep接口Common/Types/Runbook/RunbookStep.ts对每个步骤定义了id、order、type、title、description、continueOnFailure、requireApproval与config字段其中continueOnFailure与requireApproval对自动化步骤JavaScript、HttpRequest、Bash、AI才有实际意义Manual 步骤没有失败语义。步骤类型由枚举 RunbookStepType 定义共七种Manual、JavaScript、HttpRequest、Bash、AI、SSH、Kubernetes。七种步骤类型详解Manual人工确认一个由响应人勾选的复选框。执行流程到达 Manual 步骤时会暂停并停留在WaitingForManualStep状态直到有人将其标记为完成或跳过。适用于只有人类才能验证的事项例如已在负载均衡器面板中确认流量已切换到次要区域。在 RunbookStep.ts 中Manual 步骤的配置类型是ManualStepConfig Recordstring, never即除步骤级别的 Title/Description 外没有任何额外配置——它的全部逻辑就是等待人工动作。JavaScript沙箱脚本一段在isolated-vm沙箱中运行的 JavaScript 代码片段。沙箱运行在你自己基础设施内的Runbook Agent上而不是OneUptime Worker 上。JavaScript 步骤需要配置Runbook Agent—— 从下拉框选择执行该步骤的 Agent只有被选中的 Agent 可以认领该任务Script—— 要运行的 JavaScriptExecution timeout—— Agent 允许脚本运行的最长时间超时后销毁隔离环境默认 30 秒Claim timeout—— Worker 等待 Agent 领取任务的最长时间默认 2 分钟。const start Date.now(); // ... your logic ... return { durationMs: Date.now() - start };返回的值会被记录到该步骤的执行结果中console.log的输出会被捕获为日志行。在类型定义中JavaScriptStepConfig包含script、timeoutInMs、agentId必填——JavaScript 永不运行在 OneUptime Worker 上以及可选的claimTimeoutInMsCommon/Types/Runbook/RunbookStep.ts。HTTP requestHTTP 请求发起一次出站 HTTP 调用。可配置方法GET/POST/PUT/PATCH/DELETE/HEAD、URL、可选的 JSON Headers、可选的 Body以及Request timeout默认 30 秒。响应状态、响应头与响应体会被捕获总大小上限 50KB。典型用途触发 PagerDuty 事件、向 Slack 发消息、调用你自己的管理 API 等。HTTP 步骤直接在 OneUptime Worker 上运行无需 Agent。对应类型HttpRequestStepConfig中方法被约束为HttpRequestMethod联合类型取值即上述六种 HTTP 动词。BashShell 脚本一段以bash -c script方式运行在Runbook Agent上的 shell 脚本。Bash永远不会在 OneUptime Worker 上执行。Bash 步骤需要配置Runbook Agent—— 从下拉框选择执行该步骤的 Agent只有被选中的 Agent 可以认领该任务Script—— 要运行的 bash 脚本输出stdout stderr最多捕获 50KB超时后进程会被杀死Execution timeout—— Agent 允许脚本运行的最长时间超时以SIGKILL杀掉进程默认 30 秒对于确实需要几分钟的步骤请调高Claim timeout—— Worker 等待 Agent 领取任务的最长时间默认 2 分钟。如果选中的 Agent 在该步骤执行时处于离线状态步骤会一直等待到claim timeout默认 2 分钟然后以TimedOut失败。因此在依赖 Bash 步骤之前请先在Settings → Runners中添加 Agent。关于 Bash 与 JavaScript 为何必须运行在 Agent 上Runbook Agents 文档 给出了两个原因一是信任边界——如果脚本运行在 OneUptime Worker 上任何能编写 Runbook 的人都能在 Worker 上执行代码并触及其环境变量与文件系统二是可达性——大多数有用的步骤要操作的是客户自己的基础设施重启这个服务在我们集群上执行 kubectl而不是 OneUptime 的。Agent 只要求能够出站 HTTPS访问你的 OneUptime 实例不接收任何入站连接。SSH远程命令在 Runner 能够通过 SSH 到达的主机上运行命令。与在 Bash 步骤里写ssh host cmd不同这里的访问是托管的凭据credential而不是放在 Runner 磁盘上的私钥——凭据加密存储、分配给指定 Runner且永远无法通过 API 读回。SSH 步骤需要配置Runner—— 建立连接的 Runner它必须能在网络上到达目标主机Credential—— 保存 host、port、user 与 key 的 SSH 凭据。它必须被分配给所选 Runner否则步骤会失败而不是以错误的访问身份运行Command—— 以凭据用户的身份在远程主机上运行的命令输出最多捕获 50KB非零退出码会使步骤失败Execution timeout—— 覆盖连接、认证与运行命令的整个过程因此挂起的命令不会无限期卡住步骤。对应的SSHStepConfig定义Common/Types/Runbook/RunbookStep.ts包含credentialId、command、timeoutInMs、agentId与claimTimeoutInMs。代码注释明确指出把 SSH 做成一级步骤类型而不是在 Bash 步骤里写 ssh意义在于凭据是受管理的加密对象、有自己的权限体系且命令是可校验的值而非不透明的脚本。凭据的详细管理方式见 Runbook Credentials 文档SSH 凭据保存 Hostname、端口默认 22、用户名以及 PEM 私钥可选口令或密码私钥、口令、密码与服务账号 token 均加密存储API永不返回它们——因此没有查看操作只有替换操作重新输入即轮换。Kubernetes工作负载操作重启或扩缩集群中的工作负载。操作动词刻意设计为封闭集合一个能 PATCH 任意对象的步骤等于一个集群管理员 shell而该步骤类型存在的意义恰恰是让常见修复操作足够安全可以交给自动修复auto-remediation使用。Kubernetes 步骤需要配置Runner—— 调用 API server 的 RunnerCredential—— 保存 API server URL、service account token 与集群 CA 的 Kubernetes 凭据。请把该 service account 绑定到只允许你的 Runbook 所需操作的 Role 上Action——Restart workload给 pod 模板打戳让控制器重建 pod等价于kubectl rollout restart或Scale workload设置副本数Workload kind—— Deployment、StatefulSet 或 DaemonSetNamespace与Workload nameReplicas—— 仅 Scale 使用允许为 0把工作负载排空是一种正当修复手段。DaemonSet 无法扩缩——它在每个节点上运行一个 pod——所以对它使用重启。如果 API server 拒绝了变更其自身的错误信息会显示在步骤上因此权限失败会直接告诉你该放宽哪个 RoleBinding。在类型层面KubernetesActionRestartWorkload/ScaleWorkload与KubernetesWorkloadKindDeployment/StatefulSet/DaemonSet都是枚举KubernetesStepConfig中replicas仅对 Scale 必填、其余情况忽略。AI智能分析在流程中途让 AI 分析、总结或做决策。提示词会被发送到项目的 LLM ProviderSettings → AI → LLM Providers模型的响应会成为执行时间线上的步骤输出。AI 步骤在 OneUptime Worker 上运行无需 Agent。AI 步骤需要配置Prompt—— 告诉 AI 要做什么例如Review the output of the previous steps and state whether it is safe to proceed with remediation.Include previous step context—— 开启后AI 能看到此前运行的所有步骤信息标题、类型、状态、输出与错误信息Include trigger context—— 开启后AI 能看到是什么触发了本次执行关联的事件事件描述、严重级别、当前状态、受影响的监控、根因、状态时间线与公开备注、告警或计划维护或者是谁手动运行了该 Runbook。将 AI 步骤与Require approval搭配可以实现人机回环AI 分析 → 响应人阅读其结论并批准 → 才继续执行下一步修复步骤。关于 AI 永不看到的内容。AI 步骤的答案作为步骤输出存储在本次执行中而执行记录对任何拥有 runbook 读取权限的人可见——这个受众范围比事件 ACL 更宽。因此 trigger context刻意排除私有内部备注和Slack/Teams 频道消息它们只留在事件内部。此外之前步骤的输出在发送给模型之前会扫描并脱敏其中的密钥token、key、credential。AI 步骤与其他 AI 功能一样按量计费。如果项目没有配置 LLM Provider步骤会以一个清晰的错误失败如果希望其余 Runbook 继续运行可以设置Continue on failure。从类型定义看AIStepConfig还支持maxTokens响应 token 上限默认 4096服务端会钳制与llmProviderId把步骤固定到指定 LLM Provider固定后若该 Provider 无法解析步骤会失败而不会悄悄回退到默认模型因为无人值守的 AI 步骤在不同模型上静默作答是没人能察觉的变更。步骤的底层执行RunnerJob 与执行状态从源码角度理解步骤执行依赖一个关键数据对象——RunnerJobRunnerJob表REST 端点/runner-job。它的表描述写得很清楚每个被派发到特定 Runner 的步骤一行——Bash 和 JavaScript 携带脚本而 SSH 和 Kubernetes 携带结构化指令。跟踪认领、执行与结果由 Worker 与 agents 管理用户不可写。RunnerJob 中的几个关键字段origin—— 区分任务来自 runbook 执行还是 AI 修复运行RunnerJobOrigin.Runbook/AiRemediation它决定 Runner 认领该任务所需的能力canRunRunbooks还是canRunAiCommandsstepId与stepType—— 在 Runbook 中产生该任务的步骤标识与步骤类型targetAgentId/assignedAgentId—— 步骤配置的目标 Agent 与实际认领的 Agent只有目标 Agent 可以认领status—— 任务生命周期状态RunnerJobStatusscript与payload—— 脚本类步骤携带scriptSSH/Kubernetes 类步骤携带结构化payload。代码注释特别说明payload永远不包含机密材料凭据在认领时由服务端解析并随认领响应下发因此即使某行任务可被读取执行记录的人看到也不会泄露私钥timeoutInMs—— Agent 运行脚本的最长时间output、exitCode、errorMessage—— 执行结果stdout/stderr 合并输出、退出码、错误说明输出在服务端截断claimDeadlineAt—— 认领截止时间若到期无人认领Worker 会以TimedOut失败该任务claimedAt、leaseExpiresAt、startedAt、completedAt—— 认领、租约到期Agent 未按时心跳则 Worker 回收任务、开始与完成时间。哪些步骤类型由 Runner 执行由 RunbookStepType.ts 中的RUNNER_EXECUTED_STEP_TYPES列表强制执行JavaScript、Bash、SSH、Kubernetes注释明确指出该列表是执行强制点——RunnerJobService拒绝为不在列表中的类型入队因此 Runner 永远不会被交付它没有执行器的工作。同时SSH 与 Kubernetes 属于PAYLOAD_CARRYING_STEP_TYPES结构化指令 认领时解析的凭据而不是脚本这正是RunnerJob.script列不设为必填的原因空字符串在必填检查中会被判为假值而这两类任务恰好是空脚本设计。单个步骤的执行状态由枚举 RunbookStepExecutionStatus 定义Pending、Running、WaitingForUser、Completed、Skipped、Failed、Cancelled。Manual 步骤到达时进入WaitingForUser与上文停留在 WaitingForManualStep 直到被标记完成或跳过的描述相互印证。保存与编辑点击Save Steps持久化。正在执行中的旧版本 Runbook 不受影响——它们继续使用自己保存时的快照因为steps是 JSON 列整体保存执行时基于当时版本展开。多步骤与失败处理默认情况下一个步骤失败会中止整个执行并将其标记为Failed。如果对某个步骤设置了Continue on failure失败会被记录但下一步仍然执行。这对于先尝试这三件事然后通知之类的模式非常有用。实战示例数据库主库不可达一个简单的DB primary unreachable数据库主库不可达RunbookJavaScript—— 从你的配置服务获取当前主库主机并记录下来Manual—— 确认次要库的复制延迟低于 5 秒。;HTTP request—— POST 到你的故障切换编排器 APIManual—— 确认写入现在已指向新的主库。;HTTP request—— POST 一条一切正常的消息到 Slack。整个流程中响应人看着一个自动化步骤运行、勾选一个手动步骤、再看着下一个自动化步骤运行如此往复。每一步的输出都会被捕获用于事后复盘post-mortem。结合 RunbookExecution 与 RunnerJob 的模型设计可以推断每一步执行产生的 RunnerJob 都以runbookExecutionId关联到父执行执行结果输出、退出码、错误信息沉淀在时间线上供响应人实时查看与事后归档。更完整的上下文可继续阅读同一目录下的 Runbook Agents、Runbook Credentials、Runbook Rules触发规则、运行 Runbook 与 整体概览 等文档。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考