OneUptime Runbook 编写指南从步骤设计到 AI 辅助自动修复的完整实战【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本指南以 OneUptime 官方文档 Runbook 编写指南德语版 为核心骨架结合仓库内的类型定义、执行器与超时解析源码系统讲解如何编写一条可投入事故响应的 Runbook。你将掌握步骤的字段含义、六种步骤类型手动、JavaScript、HTTP、Bash、AI 等的适用场景与配置要点、失败处理与审批门控机制以及如何用一条完整示例把数据库主库失联的修复流程自动化。Runbook 的创建入口与步骤编辑器在 OneUptime 控制台中通过Runbooks → Runbook 新建Runbook erstellen创建 Runbook打开后切换到步骤Schritte标签页即可开始编排。Runbook 与告警、事件Incident等实体的关联、触发规则与运行方式可分别参考 rules.md 与 running.md。单个步骤的通用字段每个步骤都由以下几类通用字段构成它们是所有步骤类型共享的骨架字段用途标题Titel显示在步骤清单Checklisten-UI中的简短名称必填。描述Beschreibung给值班人员看的可选上下文支持 Markdown 文本。出错时继续Bei Fehler fortfahren开启后某个步骤失败不会终止整个运行下一个步骤照常执行。需要批准Freigabe erforderlich开启后Runbook 在该步骤完成后暂停等待用户批准后才继续执行下一步。类型专属配置Typspezifische Konfiguration脚本、URL、Agent 等因步骤类型而异见下文各节。步骤严格按顺序执行。在步骤编辑器中通过上/下箭头即可调整它们的先后顺序。这些字段在数据模型 RunbookStep.ts 中一一对应title必填、description可选、continueOnFailure、requireApproval与联合类型config按步骤类型区分的配置对象。从源码注释可以确认continueOnFailure与requireApproval只对自动化步骤JavaScript、HTTP、Bash、AI有意义手动步骤没有失败语义。步骤类型详解手动步骤Manuell一个由值班人员手动勾选的复选框。当执行到达手动步骤时会暂停运行状态停留在WaitingForManualStep直到有人将其标记为完成或跳过。它适用于只有人能验证的事项例如确认负载均衡器仪表盘上的流量已切换至次要区域Region。执行状态枚举 RunbookExecutionStatus.ts 中可见WaitingForManualStep这一正式状态步骤级别的状态则定义在 RunbookStepExecutionStatus.tsPending、Running、WaitingForUser、Completed、Skipped、Failed、Cancelled。JavaScript 步骤一段运行在isolated-vm沙箱中的 JavaScript 代码。关键点沙箱运行在你自己基础设施中的 Runbook Agent 上而不是 OneUptime Worker 上。JavaScript 步骤需要配置Runbook-Agent——从下拉框选择执行该步骤的 Agent只有被选中的 Agent 才允许认领claim该任务。脚本Skript——要执行的 JavaScript 代码。执行超时Ausführungs-Timeout——Agent 允许代码运行多久超时后销毁隔离环境Isolate。默认 30 秒。认领超时Claim-Timeout——Worker 等待 Agent 认领任务的时长。默认 2 分钟。文档给出的脚本骨架const start Date.now(); // ... Ihre Logik ... return { durationMs: Date.now() - start };步骤的返回值会被记录到步骤执行记录中console.log输出会被记录为日志行执行超时默认 30 秒认领超时默认 2 分钟两者都可在步骤的执行超时 / 认领超时字段中单独调整。从源码看JavaScript 与 Bash 步骤共享同一条派发链路StepExecutors.ts 中的dispatchToAgent会向RunnerJobService.enqueue投递一条定向到指定 Agent 的任务然后轮询直到任务进入终态。超时值的解析统一收敛在 RunbookStepTimeout.ts执行超时默认 30 秒DEFAULT_STEP_EXECUTION_TIMEOUT_IN_MS上下限为 1 秒至 1 小时认领超时默认 2 分钟DEFAULT_AGENT_CLAIM_TIMEOUT_IN_MS同样限 1 秒至 1 小时。任何非法值空、非数字、小于等于 0都会回退到默认值而非让步骤报错——因为事故期间按文档默认值照常运行比拒绝运行更有用合法但越界的值则会被钳制clamp进合法区间。HTTP 请求步骤发起一次出站 HTTP 调用。可配置方法MethodGET / POST / PUT / PATCH / DELETE / HEADURL目标地址请求头Headers可选的 JSON 格式请求头请求体Body可选请求超时Anfrage-Timeout默认 30 秒。响应状态、响应头与响应体会被完整记录总量上限 50 KB。典型用途包括触发 PagerDuty 事件、向 Slack 发消息、调用你自己的管理 API 等。HTTP 步骤直接在 OneUptime Worker 上运行无需 Agent。源码层面StepExecutors.ts 的runHttpStep还有两个值得注意的实现细节输出统一经过truncate截断硬上限MAX_OUTPUT_BYTES 50_000字节超出部分以... [output truncated]结尾请求在发出前会通过DataSourceEgressGuard.assertUrlAllowedAndPin校验目标并锁定解析后的地址、同时maxRedirects: 0拒绝重定向避免步骤配置被攻击者利用来做 SSRF 类请求axios 对 3xx 会绕过地址锁定因此被显式禁用非 2xx/3xx 状态码会以HTTP status作为错误信息标记步骤失败。Bash 步骤一个在 Runbook Agent 上以bash -c skript方式运行的 Bash 脚本。Bash 永远不会在 OneUptime Worker 上执行。Bash 步骤需要配置Runbook-Agent——执行该步骤的 Agent仅被选中的 Agent 可认领任务脚本Skript——要执行的 Bash 命令stdout stderr 最多记录 50 KB超时后进程会被终止执行超时——Agent 运行脚本的时限超时以SIGKILL结束进程默认 30 秒对真正需要数分钟的步骤请调大该值认领超时——Worker 等待 Agent 认领任务的时长默认 2 分钟。Agent 离线时的行为如果 Runbook 执行到该步骤时选中的 Agent 处于离线状态步骤会一直等待到认领超时默认 2 分钟随后以TimedOut状态失败。因此在依赖 Bash 步骤之前请先在设置 → Runbook-Agents中添加 Agent。AI 步骤让大语言模型在运行中途执行分析、总结或决策。Prompt 会被发送到项目的 LLM Provider配置位置设置 → 人工智能 → LLM-Anbieter模型的回答会成为执行时间线上的步骤输出。AI 步骤在 OneUptime Worker 上运行无需 Agent。AI 步骤可配置提示词Prompt——让 AI 做什么。例如检查前面步骤的输出判断是否可以安全地继续执行修复。包含先前步骤的上下文Kontext vorheriger Schritte einbeziehen——开启后AI 可以看到在此之前运行的所有步骤信息标题、类型、状态、输出与错误信息。包含触发上下文Auslöser-Kontext einbeziehen——开启后AI 可以看到是什么触发了本次执行关联的事件Incident、告警或计划维护描述、严重级别、当前状态、受影响的监控项、根因、状态时间线、公开备注或者是手动执行该 Runbook 的用户。人机协作Human-in-the-Loop将 AI 步骤与需要批准Freigabe erforderlich组合使用即可把人放进环路——AI 先分析值班人员阅读其回答并批准然后才执行下一个修复步骤。AI 永远不会看到的内容。由于 AI 步骤的回答会作为步骤输出保存在执行记录中而执行记录对所有拥有 Runbook 读取权限的人可见范围比事件本身的 ACL 更广因此触发上下文会有意排除私密内部备注与 Slack/Teams 频道消息——它们留在事件内部由既有的 Postmortem 与备注生成器处理其派生文本。此外前序步骤的输出在发送给模型之前会先做密钥检测与脱敏令牌、密钥、凭据等会被遮蔽。从 AIStepExecutor.ts 可以看到这套机制的完整实现前序步骤上下文buildPreviousStepsContext会把标题、类型、状态、时间、错误与输出逐条整理并先ToolResultSerializer.redact脱敏再截断顺序有讲究先脱敏再截断避免密钥被截断线切断而逃过正则脱敏触发上下文buildTriggerContext会按事件/告警/计划维护分别构建资料并做租户归属复核belongsToProject防止跨项目泄露对事件资料调用stripPrivateIncidentData清空内部备注与工作区消息Prompt 采用系统提示 用户消息结构来自被监控系统与先前步骤的数据一律包进untrusted_context标签并转义/untrusted_context分隔符防止提示注入上下文设有总量上限单个步骤输出 4000 字符、前序步骤合计 24000 字符、触发上下文 30000 字符maxTokens默认 4096、钳制在 256–16384temperature固定 0.2若项目未启用 AI 功能步骤会以清晰的错误信息失败若为步骤固定pin了某个 LLM Provider每次运行都会重新校验该 Provider 对项目可用——不可用时失败而不是悄悄回退到默认模型无人值守的步骤静默换模型是没人会发现的变化。计费与失败AI 步骤与其它 AI 功能一样按用量计量计费。如果项目未配置 LLM Provider步骤会以明确错误失败——如果剩余步骤仍需执行请在步骤上开启出错时继续Bei Fehler fortfahren。其它步骤类型源码补充从当前仓库的类型定义 RunbookStepType.ts 与 RunbookStep.ts 可以看出Runbook 步骤类型还包括SSH与Kubernetes德语版文档未展开但类型系统已将其纳入 Runner 执行清单SSH 步骤通过凭据RunbookCredential类型 SSH托管加密保存主机、用户与密钥在 Runner 可达的主机上执行命令而不是把私钥散落在 Runner 磁盘上Kubernetes 步骤提供一组封闭的操作动词——RestartWorkload滚动重启、ScaleWorkload扩缩副本数0 也是合法值可用于先缩到零再拉起的排水式修复支持 Deployment / StatefulSet / DaemonSet并限定 namespace 与 workload 名称。RUNNER_EXECUTED_STEP_TYPESJavaScript、Bash、SSH、Kubernetes是执行端的强制点RunnerJobService会拒绝入队任何不在此列表中的类型确保 Runner 永远不会被派发它没有执行器的工作。保存与版本快照编辑完成后点击保存步骤Schritte speichern持久化。正在运行中的旧版本执行不受影响——它们继续使用自己启动时的快照Snapshot。这意味着你可以在事故中途安全地改进 Runbook而不会破坏已在途的执行流程。多步骤编排与失败处理默认行为是某个步骤失败即终止整个运行并将执行标记为Failed对应执行状态枚举中的终态。若在步骤上开启出错时继续Bei Fehler fortfahren失败会被记录但下一个步骤仍会执行——非常适合尝试这三件事然后通知这类模式。结合通用字段可以看出编排模式的三种基本组合纯自动化全部使用 JavaScript / HTTP / Bash / AI 步骤无人值守顺序执行人工确认闸门在关键操作如切换流量、回滚前插入带需要批准的步骤或直接使用手动步骤失败容错对尽力而为的步骤如发通知开启出错时继续避免小失败打断主流程。完整示例数据库主库不可达DB-Primary nicht erreichbar一条简单的 Runbook 可以将主库失联的处理流程串联如下JavaScript——从你的配置服务中取出当前主库Primary主机地址并记录日志手动——确认从库Secondary的复制延迟低于 5 秒HTTP 请求——向故障转移编排器的 API 发送 POST 请求手动——确认写入现已切换到新的主库HTTP 请求——向 Slack 发送一条 POST 消息已解除警报。值班人员看到的效果是自动化步骤自动运行 → 手动步骤打勾确认 → 下一个自动化步骤继续运行如此交替推进。每个步骤的输出都会被记录下来供事后的 Post-Mortem 复盘使用。这也正是 Runbook 的核心价值把易错的手工操作固化为可重复、可审计、可交接的标准流程。编写 Runbook 的实践要点先补 Agent 再写脚本型步骤JavaScript、Bash以及 SSH、Kubernetes步骤都依赖你自己基础设施中的 Runner/Agent参见 agents.md未选择 Agent 或 Agent 离线时步骤会等待认领超时默认 2 分钟后以TimedOut失败。超时按步骤真实耗时设置执行超时默认 30 秒长时间任务要主动调大上限 1 小时非法值会自动回退默认值越界值会被钳制。人工环节用对字段需要人验证用手动步骤需要在 AI 判断后加人把关用AI 步骤 需要批准。AI 上下文按需开启includePreviousStepContext与includeTriggerContext都会消耗上下文窗口与 token只有确实需要模型基于历史输出或触发事件做判断时才开启。敏感信息边界AI 步骤的回答对拥有 Runbook 读取权限的所有人可见因此不要期待模型能看到私密内部备注也不要在步骤输出中打印未脱敏的密钥。保存即快照随时可以保存新版本正在运行的执行继续用旧快照安全迭代无需等待事故结束。上述字段语义、超时默认值与状态机均可对照 RunbookStep.ts、RunbookStepTimeout.ts、RunbookExecutionStatus.ts 等源码进一步验证Runbook 的全局配置Agent、凭据等见 configuration.md。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考