OneUptime Runbook 代理（Agent）完全指南：在自建基础设施内安全执行 Bash 与 JavaScript 步骤-北京尧图网络

OneUptime Runbook 代理Agent完全指南在自建基础设施内安全执行 Bash 与 JavaScript 步骤【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本指南基于 OneUptime 官方文档中 Runbook Agents西班牙语版章节并结合仓库源码展开系统讲解 OneUptime Runbook 代理的架构原理、安装部署、步骤绑定、超时与 lease 机制、环境变量、权限模型与底层 API。读完本文你将掌握如何在自有主机上部署 Runbook 代理把 Bash/JavaScript 步骤安全地下放到自己的基础设施中执行并理解其Worker 只排队、代理负责执行的完整调度链路。什么是 Runbook 代理Runbook 代理Agente de Runbook / Runner Agent是一个小型自托管进程负责在你的基础设施内部执行 runbook 中的 Bash 与 JavaScript 步骤。它的核心设计原则是OneUptime 的 Worker 从不直接执行你的脚本——它只负责把步骤入队由步骤作者选定的 Runbook 代理去认领claim任务、执行脚本并回报结果。其中 JavaScript 步骤依然运行在isolated-vm沙箱中与旧版在服务端执行时的隔离机制相同区别仅在于沙箱从 OneUptime 的服务器迁移到了你代理所在的主机上。这一设计在仓库代码中有直接印证在 Runner/Config.ts 的文件头注释中Runner 被明确定义为 the single agent a customer installs承载两类工作——RUNBOOKS认领 runbook 的 Bash/JavaScript 步骤并在客户自己的基础设施中执行默认开启与 CODE FIXES认领 AI 代码修复任务默认关闭。为什么需要代理旧架构的两大痛点旧版 OneUptime 在 Worker 上直接执行 Bash 与 JavaScript 步骤。JavaScript 通过isolated-vm沙箱隔离而 Bash 完全没有隔离。这两种方案在超出单租户自托管场景后都存在问题痛点说明信任边界Trust boundary任何有权限编写 runbook 的人都可以在 Worker 上执行代码并访问 Worker 的环境变量和文件系统。JavaScript 沙箱能挡住明显的越权却无法阻止一个执意的用户探测 OneUptime 网络内可达的资源。作用范围Scope大多数有用的步骤操作对象是客户自己的基础设施重启这个服务、在集群里执行 kubectl、查我们内部数据库的日志而不是 OneUptime 自己的系统。Runbook 代理彻底扭转了这一点Bash 和 JavaScript 步骤不再运行在 OneUptime 侧而是运行在你完全控制的主机上由你决定这台主机能做什么、不能做什么。正如 Runner/README.md 所述One self-hosted agent that does the work OneUptime cannot do from the outside.工作原理Worker 入队、代理认领整个调度链路分六步在 OneUptime 中创建一个 Runbook 代理OneUptime 为其生成一个ID和一个密钥key。在你自己基础设施中的某台主机上用该 ID/密钥加上你的 OneUptime URL 启动代理容器。代理每隔几秒轮询pollOneUptime询问有没有工作给我。当你编写 Bash 或 JavaScript 步骤时从下拉菜单中选择一个代理——该步骤就与这个具体代理绑定。步骤执行时Worker 插入一行带targetAgentId的 job 记录指向该代理只有该代理能认领它。代理在本地执行脚本——Bash 通过bash -c scriptJavaScript 通过isolated-vm沙箱——捕获结果并回传Worker 据此继续推进 runbook。关键约束代理只需要对 OneUptime 实例的 HTTPS 出站连接不监听任何入站连接。这意味着代理主机不需要暴露任何端口天然适合放在 NAT 之后或安全组严格限制的网络中。这一只有目标代理能认领的机制在 RunnerJob 数据模型中有完整对应每个 job 记录包含targetAgentId步骤配置为在其上运行的代理仅该代理可认领、assignedAgentId实际认领的代理通常与 target 相同、claimDeadlineAt认领截止时间与leaseExpiresAt租约过期时间。模型注释明确写道Only this agent may claim the job.安装部署四步上手1. 创建代理注册进入Runbooks → Ajustes → AgentesRunbooks → 设置 → 代理新建一个代理填写两个字段字段说明Nombre名称一个友好的名称——惯例是在哪里运行能做什么例如prod-eu-west-1。它会显示在编写步骤时的下拉菜单中。Descripción描述可选。用一句话说明这台主机能访问什么。2. 复制安装命令创建代理后点击其所在行的Mostrar instrucciones de configuración显示配置说明会看到一个已预填该代理 ID 和密钥的docker run命令。立即保存密钥——之后可以重新生成新密钥但一旦关闭该弹窗你将无法再次看到同一个密钥值。3. 在基础设施内的主机上运行在满足以下条件的主机上执行 Docker 命令能通过 HTTPS 访问你的 OneUptime 实例能执行你希望 Bash/JavaScript 步骤做的事情例如 SSH 到其他主机、运行kubectl、连接数据库。docker run --name oneuptime-runner --restart unless-stopped \ -e ONEUPTIME_RUNNER_IDagent-id \ -e ONEUPTIME_RUNNER_KEYagent-key \ -e ONEUPTIME_URLhttps://oneuptime.yourdomain.com \ -d oneuptime/runner:release4. 验证代理已连接回到Runbooks → Ajustes → Agentes。大约 60 秒内代理所在行应变为Connected状态并带有新鲜的Last seen时间戳。若仍显示Disconnected按以下顺序排查查看容器日志docker logs oneuptime-runner确认是否存在认证或网络错误用curl验证主机能否访问你的 OneUptime URL检查 ID 和密钥是否被复制时带入多余空白字符。源码侧的一个细节代理注册时ONEUPTIME_RUNNER_ID、ONEUPTIME_RUNNER_KEY与ONEUPTIME_URL均为必需变量缺失任一变量都会导致进程启动失败。见 Runner/Config.ts缺失时打印明确错误并process.exit(1)。其中还提到另一种cluster-scoped集群级模式——OneUptime 自部署时通过集群密钥自动注册代理以服务所有项目该模式仅供平台内部的runner服务使用绝不能交给客户安装客户安装的代理是project-scoped项目级只能看到并认领自己项目的工作。将步骤绑定到代理在 runbook 中添加 Bash 或 JavaScript 步骤时表单中有一个Agente de RunbookRunbook 代理下拉菜单列出当前项目的所有代理并显示连接/离线状态指示器选择应由哪个代理执行该步骤在下方编辑器中编写你的脚本。当 runbook 运行到该步骤时Worker 会入队一个指向该代理 ID 的 job只有它才能认领。Bash 通过bash -c执行JavaScript 在代理上的isolated-vm沙箱中运行——没有文件系统、没有网络源码注释澄清该沙箱并非网络沙箱宿主会主动把一个 HTTP 客户端桥接进 isolate因此脚本可以访问代理主机能访问的任何网络资源、没有Function/eval。如果需要多个代理创建多个并把每个步骤指向最合适的那一个。若追求冗余可以编写两个 runbook每个代理一个或将步骤分散到多个代理上。运维要点超时Timeouts每个 Bash 或 JavaScript 步骤应用两个超时超时默认值控制内容Claim timeout认领超时2 分钟Worker 等待所选代理认领 job 的最长时间。若代理未及时领取步骤以TimedOut失败runbook 继续或停止取决于Continuar en caso de error / 出错时继续设置。Execution timeout执行超时30 秒代理允许脚本运行的最长时间超时即终止Bash 收到SIGKILLJavaScript 的 isolate 被拆除。两者均可按步骤配置打开Runbooks → 你的 runbook → Pasos步骤展开某个 Bash/JavaScript 步骤在脚本下方设置Execution timeout与Claim timeout单位秒。留空则使用默认值。每个值接受 1 秒到 1 小时超出范围的值在执行时会被钳制到边界值。Worker 的总等待窗口为claim timeout execution timeout 几秒余量请选择与步骤耗时匹配的数字。降低 claim timeout 时需注意两点代理按轮询周期领取工作ONEUPTIME_RUNNER_POLL_INTERVAL_MS默认 5 秒。若 claim timeout 短于一个轮询周期一个完全健康的代理可能还没来得及看到 job 就已超时步骤会以与代理离线完全相同的没有代理认领该 job信息失败。每个代理默认同时只执行一个 jobONEUPTIME_RUNNER_CONCURRENCY。当某个长步骤占用代理时指向同一代理的其他步骤正在消耗各自的 claim timeout。如果把 execution timeout 调到分钟级请同步调高共享该代理的步骤的 claim timeout——或者给它们分配不同代理。Lease 与心跳Heartbeat代理认领 job 后获得一个短租约lease默认 30 秒。脚本运行期间代理每 10 秒续租一次。若代理在脚本执行中途宕机或断网lease 到期后 Worker 会将 job 标记为TimedOut而不是永远等待。lease 机制在服务端源码中有清晰实现在 RunnerJobService 中定义DEFAULT_LEASE_MS 30_00030 秒注释要求代理至少每隔DEFAULT_LEASE_MS / 2毫秒调用一次 job 心跳端点以续租认领时以 SQL 原子操作设置leaseExpiresAt NOW() leaseMs只有持有当前租约的代理才被允许写入终态结果。代理侧则由 RunbookExecutor 在executeAndReport中用setInterval按JOB_HEARTBEAT_INTERVAL_MS周期调用AgentClient.jobHeartbeat(jobId)并在finally中清理定时器防止长脚本被误判为超时。需要特别留意的是Bash 的子进程在 lease 过期后不会自动被取消JavaScript isolate 也会在能结束时自然结束但 Worker 已不再等待它们而且一旦有其他认领接管旧代理的结果将无法提交。如果在意 exactly-once 语义请把脚本设计成可安全重跑。没有代理在线若步骤执行时选中的代理处于离线状态job 将保持Pending直到 claim timeout 到期然后以明确的没有代理认领该 job信息失败。在正式运行 runbook 前代理页面是确认覆盖度的最佳位置。输出大小限制每个步骤的 stdout stderr 合计限制为50 KB超出部分会被截断并加标记。如果需要完整日志请在脚本内写入 S3 或你的日志存储然后echo出 URL。这一上限与代理侧源码中的MAX_OUTPUT_BYTES 50_000完全一致见 Runner/Config.ts。取消Cancelación从执行视图或 API 取消一次 runbook 执行会立即把所有处于Pending/Claimed/Running状态的 Bash/JavaScript job 标记为Cancelled。已在脚本执行中途的代理会完成手头工作但服务端不会接受其结果。并发Concurrencia每个代理默认同时执行一个 job。如需提升在代理容器中设置ONEUPTIME_RUNNER_CONCURRENCY——但请记住代理与宿主机上的其他负载共享资源。环境变量参考代理在启动时读取以下环境变量见 Runner/Config.ts变量必需默认值说明ONEUPTIME_URL是—你的 OneUptime 实例基础 URL例如https://oneuptime.yourdomain.com。缺失时进程直接退出。ONEUPTIME_RUNNER_ID是—代理配置弹窗中显示的 UUID。项目级代理缺失时进程直接退出。ONEUPTIME_RUNNER_KEY是—代理配置弹窗中显示的密钥。缺失时进程直接退出。ONEUPTIME_RUNNER_POLL_INTERVAL_MS否5000代理轮询新 job 的间隔源码下限 1000ms。ONEUPTIME_RUNNER_HEARTBEAT_INTERVAL_MS否60000代理上报存活的间隔源码下限 5000ms。ONEUPTIME_RUNNER_JOB_HEARTBEAT_INTERVAL_MS否10000代理为进行中的 job 续租的间隔源码下限 1000ms。ONEUPTIME_RUNNER_CONCURRENCY否1该代理上可同时执行的 job 数上限源码下限 1。除文档表格外源码还额外支持一些覆盖变量ONEUPTIME_RUNNER_NAME/ONEUPTIME_RUNNER_DESCRIPTION可选名称与描述、ONEUPTIME_RUNNER_ENABLE_RUNBOOKS、ONEUPTIME_RUNNER_ENABLE_CODE_FIXES、ONEUPTIME_RUNNER_ENABLE_AI_COMMANDS三态本地能力覆盖开关只有false/0/no/off字样会生效用于在本地强制关闭某类工作以及PORT健康检查与队列深度指标端口默认 3875供自托管场景的 KEDA 读取。轮换代理密钥如果密钥泄露在 OneUptime 中打开该代理并重新生成密钥旧密钥立即失效。然后用新密钥更新代理容器并重启它。权限模型代理管理位于现有的 Runbooks 权限组之下CreateRunner、EditRunner、DeleteRunner、ReadRunner——管理代理注册记录RunbookAdmin、RunbookMember、RunbookViewer角色——可分配给团队分别授予完全控制、日常使用与只读访问RunbookAdmin聚合了前述所有细粒度权限。触发 runbook从而引发 Bash/JavaScript 步骤派发的权限依然是CreateRunbookExecution/EditRunbookExecution。从数据模型侧看RunnerJob 的读写权限同样收敛在 Runbook 相关权限组内且该表由 Worker 与代理管理用户不可写create: []、update: []、delete: []从数据层杜绝了越权写入 job 记录的可能。面向代理的 API对好奇的读者——代理使用以下挂载在/runner-ingest下的端点通过 JSON body 中的代理 ID 密钥或x-agent-id/x-agent-key请求头进行认证端点用途POST /heartbeat存活上报更新lastAlive、connectionStatus、hostInfo、agentVersion。POST /claim-next-job原子认领指向本代理 ID 的最老的Pendingjob无任务时返回{ job: null }。POST /job/:jobId/heartbeat刷新该 job 的租约lease 已过期或 job 已进入终态时返回 404。POST /job/:jobId/result提交最终结果lease 已过期则忽略。这组端点在 Runner/Config.ts 中以RUNNER_INGEST_URL ONEUPTIME_BASE_URL /runner-ingest的方式被代理引用。正常情况下你无需手工调用它们——打包好的代理会自动完成——此处列出是为了满足需要自建代理以适配特殊限制的场景。写在最后Runbook 代理把 OneUptime 从代执行运维操作转变为只做调度编排Worker 负责 runbook 的编排、入队、租约与结果校验代理负责在客户自己的主机上以受控的方式执行脚本。信任边界因此回到你手中——你决定代理主机能访问什么、能运行什么而 OneUptime 永远不直接触碰你的生产环境。对任何自托管 OneUptime 的团队来说这既是安全边界也是把 runbook 延伸到真实基础设施的唯一通道。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OneUptime Runbook 代理（Agent）完全指南：在自建基础设施内安全执行 Bash 与 JavaScript 步骤

相关推荐

Glances MPP 插件详解：监控 Rockchip 平台硬件视频编解码引擎（RKVENC / RKVDEC / RKJPEGD）

Taro H5 端路由系统解析：从 `@tarojs/router` 看小程序路由规范在 Web 端的落地

aclnnMoeTokenPermuteV2 算子深度指南：CANN ops-transformer 中 MoE Token Permute 的量化扩展与两段式调用

更多资讯

Flutter适配OpenHarmony：stringr纯Dart库的字符串处理实战

基于AT89C51的八路抢答器设计与Keil/Proteus仿真调试

DeepSeek Harness 会话表层架构简化：为每个 Session 只保留一个 SurfaceManager 的增量状态设计与实现

Pandoc `--id-prefix` 选项深度解析：为 HTML/DocBook 输出统一添加标识符前缀，杜绝锚点冲突

Cherry Studio 流式 API 启动错误改用 HTTP 状态码：原理、影响与客户端适配指南

mas 测试体系拆解：Swift Testing 与 @TaskLocal 依赖注入如何写可靠的 CLI 测试

今日更新

校园网认证计费模式详解：AAA与代拨架构、原理及排障

Spring Boot+Vue垃圾分类毕设：分层、权限与排错实战

把 Cline 的 Base URL 改到 TaoToken 之后，DeepSeek 仍能修调试配置

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？