OneUptime 自定义探针（Custom Probe）部署与断连诊断完全指南

OneUptime 自定义探针Custom Probe部署与断连诊断完全指南【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读OneUptime 的自定义探针Custom Probe允许你在自己的内网或防火墙之后部署一个专属监控探针用于探测私有网络内的资源、或位于防火墙后面的服务这是 OneUptime 从公网探测到内网可观测性的关键桥梁。本文将基于仓库文档与packages/Probe源码完整讲解探针的创建、Docker / Docker Compose / Kubernetes 三种部署方式、代理配置、全部环境变量以及当探针显示Disconnected时如何借助源码级诊断信息stalledAt、连接性自测等快速定位故障。一、什么是自定义探针何时需要它OneUptime 默认由全局探针Global Probe从公网发起监控请求因此无法触及私有网段。自定义探针则是由你自行部署在目标网络内部的一个轻量级服务镜像为oneuptime/probe:release它扮演内网监控代理的角色监控私有网络中的 Web 服务、API、数据库、网络设备等监控位于防火墙之后的外部不可达资源作为 SNMP Trap、Syslog、NetFlow 等设备遥测的接收端可选能力。从源码看探针镜像基于 Node.js 26 构建Dockerfile.tpl内置了 Ping、traceroute、dig、ODBC SQL 驱动、Kerberos 以及 Playwright 的 Chromium / Firefox 浏览器因此可执行包括网站、API、SSL、Ping、端口、数据库、DNS、合成Synthetic浏览器脚本等几乎所有监控类型。二、第一步在 OneUptime 控制台创建自定义探针部署之前你需要先在 OneUptime 控制台完成探针的身份注册登录你的 OneUptime 控制台导航到Monitors监控 Settings设置 Probes探针创建一个Custom Probe自定义探针创建成功后控制台会为你生成两个关键凭据凭据说明PROBE_ID探针的唯一 ID用于标识这台探针PROBE_KEY探针密钥探针向 OneUptime 服务器注册与上报时使用的认证凭据这两个值将作为探针容器的必需环境变量。从源码看探针进程在启动时若缺失这两个值会直接退出PROBE_KEY未设置时调用process.exit(1)Config.tsPROBE_INGEST_URL与ONEUPTIME_URL均未设置时同样退出Config.ts。三、部署自定义探针3.1 使用 Docker 部署确保目标机器已安装 Docker然后执行docker run --name oneuptime-probe --network host \ -e PROBE_KEYprobe-key \ -e PROBE_IDprobe-id \ -e ONEUPTIME_URLhttps://oneuptime.com \ -d oneuptime/probe:release说明--network host让探针直接使用宿主机网络栈这既是内网探测的需要也是 SNMP Trap / Syslog 等 UDP 接收端口可达的前提。如果你自托管self-hostOneUptime请把ONEUPTIME_URL换成你自己的实例地址。Docker 代理配置当探针需要经过代理服务器才能访问 OneUptime或需要代理去探测外部资源时通过环境变量注入代理设置# HTTP 代理 docker run --name oneuptime-probe --network host \ -e PROBE_KEYprobe-key \ -e PROBE_IDprobe-id \ -e ONEUPTIME_URLhttps://oneuptime.com \ -e HTTP_PROXY_URLhttp://proxy.example.com:8080 \ -e NO_PROXYlocalhost,.internal.example.com \ -d oneuptime/probe:release # HTTPS 代理 docker run --name oneuptime-probe --network host \ -e PROBE_KEYprobe-key \ -e PROBE_IDprobe-id \ -e ONEUPTIME_URLhttps://oneuptime.com \ -e HTTPS_PROXY_URLhttp://proxy.example.com:8080 \ -e NO_PROXYlocalhost,.internal.example.com \ -d oneuptime/probe:release # 带认证的代理 docker run --name oneuptime-probe --network host \ -e PROBE_KEYprobe-key \ -e PROBE_IDprobe-id \ -e ONEUPTIME_URLhttps://oneuptime.com \ -e HTTP_PROXY_URLhttp://username:passwordproxy.example.com:8080 \ -e HTTPS_PROXY_URLhttp://username:passwordproxy.example.com:8080 \ -e NO_PROXYlocalhost,.internal.example.com \ -d oneuptime/probe:release3.2 使用 Docker Compose 部署创建docker-compose.ymlversion: 3 services: oneuptime-probe: image: oneuptime/probe:release container_name: oneuptime-probe environment: - PROBE_KEYprobe-key - PROBE_IDprobe-id - ONEUPTIME_URLhttps://oneuptime.com network_mode: host restart: always需要代理时追加代理环境变量version: 3 services: oneuptime-probe: image: oneuptime/probe:release container_name: oneuptime-probe environment: - PROBE_KEYprobe-key - PROBE_IDprobe-id - ONEUPTIME_URLhttps://oneuptime.com # 代理配置可选 - HTTP_PROXY_URLhttp://proxy.example.com:8080 - HTTPS_PROXY_URLhttp://proxy.example.com:8080 - NO_PROXYlocalhost,.internal.example.com # 带认证的代理 # - HTTP_PROXY_URLhttp://username:passwordproxy.example.com:8080 # - HTTPS_PROXY_URLhttp://username:passwordproxy.example.com:8080 # - NO_PROXYlocalhost,.internal.example.com network_mode: host restart: always然后启动docker compose up -d自托管 OneUptime 时同样将ONEUPTIME_URL替换为你的实例地址。3.3 使用 Kubernetes 部署创建oneuptime-probe.yamlapiVersion: apps/v1 kind: Deployment metadata: name: oneuptime-probe spec: selector: matchLabels: app: oneuptime-probe template: metadata: labels: app: oneuptime-probe spec: containers: - name: oneuptime-probe image: oneuptime/probe:release env: - name: PROBE_KEY value: probe-key - name: PROBE_ID value: probe-id - name: ONEUPTIME_URL value: https://oneuptime.com带代理配置的版本apiVersion: apps/v1 kind: Deployment metadata: name: oneuptime-probe spec: selector: matchLabels: app: oneuptime-probe template: metadata: labels: app: oneuptime-probe spec: containers: - name: oneuptime-probe image: oneuptime/probe:release env: - name: PROBE_KEY value: probe-key - name: PROBE_ID value: probe-id - name: ONEUPTIME_URL value: https://oneuptime.com # 代理配置可选 - name: HTTP_PROXY_URL value: http://proxy.example.com:8080 - name: HTTPS_PROXY_URL value: http://proxy.example.com:8080 - name: NO_PROXY value: localhost,.internal.example.com # 带认证的代理 # - name: HTTP_PROXY_URL # value: http://username:passwordproxy.example.com:8080 # - name: HTTPS_PROXY_URL # value: http://username:passwordproxy.example.com:8080 # - name: NO_PROXY # value: localhost,.internal.example.com应用清单kubectl apply -f oneuptime-probe.yaml自托管场景下同样替换ONEUPTIME_URL。四、探针环境变量详解探针的完整环境变量定义与校验逻辑集中在 packages/Probe/Config.ts所有数值型变量均通过NumberUtil.parseNumberWithDefault解析超出边界值时会自动回退到默认值或钳制在合法区间。4.1 必需变量变量说明PROBE_KEYOneUptime 控制台生成的探针密钥缺失时进程直接退出PROBE_IDOneUptime 控制台生成的探针 ID缺失时进程直接退出ONEUPTIME_URLOneUptime 实例的地址默认https://oneuptime.com。自托管时改为你的实例地址也可以使用PROBE_INGEST_URL直接指定探针上报端点源码细节ONEUPTIME_URL缺省时回退到PROBE_INGEST_URL若两者都未设置则启动失败当 URL 末尾没有/probe-ingest路径时代码会自动拼接该路由Config.ts。4.2 可选变量监控核心变量默认值说明PROBE_NAME空探针的自定义名称PROBE_DESCRIPTION空探针的描述信息PROBE_MONITORING_WORKERS1监控 worker 数量最小值 1提高并发监控能力PROBE_MONITOR_FETCH_LIMIT10每次从服务器批量拉取的监控项数量最小值 1PROBE_MONITOR_RETRY_LIMIT3某个监控步骤未自定义重试次数时失败后首次尝试之外的重试次数即最多 4 次尝试最小值 0PROBE_SYNTHETIC_MONITOR_SCRIPT_TIMEOUT_IN_MS60000合成监控浏览器脚本脚本执行的超时时间毫秒PROBE_CUSTOM_CODE_MONITOR_SCRIPT_TIMEOUT_IN_MS60000自定义代码监控脚本的超时时间毫秒PROBE_API_REQUEST_TIMEOUT_IN_MS45000探针发往 OneUptime 服务器的每个控制面请求的硬性截止时间毫秒最小值 1000。源码注释特别指出axios 默认超时为 0无限没有该截止时间时服务器接受 TCP 但不响应会让请求永久挂起导致探针被判为DisconnectedConfig.tsPROBE_API_SLOW_REQUEST_THRESHOLD_IN_MS10000超过该耗时的成功请求会记录慢请求警告用于提前暴露即将超时的趋势最小值 100PROBE_MONITOR_CHECK_TIMEOUT_IN_MS900000单个监控项一次完整检查含所有步骤、重试与结果上报的硬性截止时间超时则放弃并进入下一周期。默认值会随合成脚本超时等设置自动抬升下限4.3 网络发现Discovery扩展变量这部分变量来自该文档族较新版本英文版同文档新增的网络设备发现Network Discovery能力控制发现扫描的并发与资源预算变量默认值说明PROBE_DISCOVERY_SCAN_TIMEOUT_IN_MS540000090 分钟单次网络发现扫描的硬性截止时间超时则放弃并把扫描标记为失败。源码注释说明其取值夹在最慢的正常扫描与服务端 2 小时废弃窗口之间Config.tsPROBE_DISCOVERY_PROGRESS_INTERVAL_IN_MS30000扫描进行中向上汇报已发现主机的间隔最小值 5000让长扫描在完成前即可展示进度并可被自动导入PROBE_DISCOVERY_SCAN_CONCURRENCY0自动单次扫描内并发探测的主机数量0 表示由扫描目标规模自动推算。调高时需同步提高容器的进程数与文件描述符上限最大 1024PROBE_DISCOVERY_REVERSE_DNS_BUDGET_IN_MS0自动反向 DNSPTR查询的时间预算自动模式下约 860 台主机配 60 秒随主机数增长至最多 10 分钟合法范围 1000–1200000 毫秒PROBE_DISCOVERY_NETBIOS_MAX_HOSTS0内置上限 2000单次扫描中 NetBIOS 名称查询的最大主机数可上调至 4000需注意 NBSTAT 报文可能触发入侵检测规则PROBE_DISCOVERY_MAX_CONCURRENT_SCANS4同一探针上可并行运行的独立发现扫描数范围 1–16。调为 1 可串行执行扫描升级提醒使用并发发现能力前应先升级 OneUptime 服务器端如果新探针连接的是旧版服务器请先设置PROBE_DISCOVERY_MAX_CONCURRENT_SCANS1。4.4 代理相关变量变量说明HTTP_PROXY_URL用于 HTTP 请求的代理服务器 URLHTTPS_PROXY_URL用于 HTTPS 请求的代理服务器 URLNO_PROXY逗号分隔的主机/域名列表匹配的主机绕过代理直连注意为了兼容性探针同时支持大写HTTP_PROXY_URL、HTTPS_PROXY_URL、NO_PROXY与小写http_proxy、https_proxy、no_proxy两种写法Config.ts。五、代理配置原理源码级解析代理的核心实现在 packages/Probe/Utils/ProxyConfig.ts理解它有助于排查代理相关问题统一入口探针发往 OneUptime 的所有控制面请求都经由 ProbeAPIRequest.ts 的getDefaultRequestOptions()构造该函数自动叠加代理 agent 与超时因此代理对所有请求类型心跳、监控列表拉取、结果上报、注册全局生效。协议选择HTTP_PROXY_URL对应http-proxy-agentHTTPS_PROXY_URL对应https-proxy-agent两者可以同时配置请求按目标 URL 的协议自动选择。认证支持代理 URL 采用http://[username:password]proxy.server.com:port格式用户名密码内嵌在 URL 中即可完成代理认证。NO_PROXY 匹配逻辑NO_PROXY列表支持精确主机名、带端口example.com:8080、前导点号子域.example.com、*.通配子域、*全部绕过以及 IPv6 字面量并做了规范化小写、去括号与端口补齐HTTP 默认 80、HTTPS 默认 443处理。请求级覆盖当调用方需要接受自签名证书rejectUnauthorized: false或携带客户端证书时会临时构造独立的代理 agent而非常用缓存 agent。代理 URL 示例基础代理http://proxy.example.com:8080带认证http://username:passwordproxy.example.com:8080代理能力特性一览支持 HTTP / HTTPS 代理、支持代理认证、HTTP 与 HTTPS 代理之间自动回退、支持NO_PROXY选择性绕过、对所有监控类型网站、API、SSL、合成等均生效。六、验证探针状态探针正常启动并完成注册后在 OneUptime 控制台的 Probes 页面中应显示为Connected。如果显示未连接请依次检查容器日志查看探针容器日志中是否有启动失败、注册失败或请求超时记录凭据与地址确认PROBE_KEY、PROBE_ID与ONEUPTIME_URL正确无误网络与代理确认探针能访问 OneUptime 服务器自托管时为你的实例地址配置了代理时确认代理可达、NO_PROXY未误伤 OneUptime 域名。探针每次启动都会打印一行 JSON 环境信息块包含正在使用的 OneUptime URL、请求截止时间、代理配置、继承的 DNS 解析器、Node 与操作系统版本以及 TLS 校验是否被禁用Index.ts 与 ProbeApiDiagnostics.ts。报告问题时请附带该信息块。七、诊断断开连接的探针Disconnected当探针对 OneUptime 的请求连续失败时控制台会将其标记为Disconnected。得益于 ProbeApiDiagnostics.ts 的实现探针日志会明确告诉你在哪个阶段卡住了通常无需猜测。7.1 读取启动时的环境信息块每次启动探针都会打印一个 JSON 块包含使用的 OneUptime URL、请求截止时间、代理设置、继承的 DNS 解析器、Node/OS 版本、是否禁用了 TLS 校验等。提交问题报告时务必包含该块。7.2 定位失败报告中的stalledAt每次对 OneUptime 的失败请求都会记录一个包含stalledAt与whatThisMeans字段的报告块。stalledAt表示请求从未越过的阶段其判定逻辑会读取真实 socket 状态ProbeApiDiagnostics.tsstalledAt含义SocketAssignment请求根本没有离开本机socket 池被并发请求占满或配置的代理从未完成 CONNECT 隧道TcpConnect本机发出了 SYN 但没有任何回应防火墙或安全设备在丢包或目标主机不可达TlsHandshakeTCP 已连通但 TLS 握手未完成通常是路径上存在 TLS 深度检测中间盒RequestSend已建立连接但请求体从未完整写出对端停止读取WaitingForServerResponse请求已送达但服务器未返回任何数据。此时探针侧网络是正常的——请检查 OneUptime 服务器、其负载均衡器与反向代理ResponseBody服务器开始响应但在中途停滞同一报告块还包含deadlineOverrunInMs。如果 45000ms 的截止时间却消耗了远超 45000ms 的真实墙钟时间说明探针进程自身被阻塞了事件循环繁忙或机器被挂起/限流此时应先查看块中的probeProcess.eventLoopMaxDriftInMs字段而不是先怀疑网络。7.3 阅读连接性自测结果在连续 3 次失败之后探针会对同一服务器逐层自测并记录各阶段耗时DNS → TCP → TLS → 真实 HTTP 往返。第一个失败的阶段就是答案。当配置了代理时探针只测试到代理这一跳因为那是它实际建立的唯一一跳ProbeApiDiagnostics.ts。自测受频率限制每 5 分钟最多一次避免离线探针刷屏。7.4 关注慢请求的预警趋势成功但耗时超过PROBE_API_SLOW_REQUEST_THRESHOLD_IN_MS默认 10000ms的请求会被记录耗时。当探针开始出现 20 秒的请求日志时说明它正走在跨越 45 秒截止时间的路上这是故障发生前的提前预警。7.5 结合服务端日志双向定位在 OneUptime 服务端探针发来的响应缓慢的请求或探针在响应发出前放弃的请求也会被记录并带有探针 ID。探针端日志 服务端日志两份记录放在一起即可判断连接故障发生在哪一侧。八、探针启动流程速览源码视角探针的完整启动序列见 Index.ts初始化代理配置ProxyConfig.configure()在任何 HTTP 请求发出之前完成初始化遥测与性能分析可选打印运行时参数日志worker 数、拉取上限、合成并发、脚本超时、重试次数等打印私有网络监控策略、环境信息块并启动事件循环漂移采样器startProcessMonitor启动内部 HTTP 服务与可选入口监听PROBE_INGRESS_PORT用于私网心跳IncomingRequest监控注册探针Register.registerProbe()依次启动各定时任务心跳上报AliveJob、监控列表拉取与检查FetchMonitorList、监控测试、网络发现扫描FetchDiscoveryScans、网络设备轮询与诊断可选启动 SNMP Trap 接收器、Syslog 接收器、NetFlow v5 接收器。九、常见问题速查探针启动即退出多为PROBE_KEY或ONEUPTIME_URL/PROBE_INGEST_URL未设置源码强制校验。控制台始终显示 Disconnected先看失败报告的stalledAt定位阶段WaitingForServerResponse时应检查 OneUptime 服务端而非探针网络。配置了代理但请求未走代理确认变量名大小写、代理 URL 格式并检查目标是否命中NO_PROXY。内网监控被拒绝探针对私有地址的监控策略由PROBE_ALLOW_PRIVATE_NETWORK_MONITORS控制Config.ts默认关闭需由探针部署方显式开启无论开关如何回环地址、链路本地地址与云元数据端点始终被禁止。磁盘/内存受限的小容器可降低PROBE_MONITORING_WORKERS、PROBE_DISCOVERY_MAX_CONCURRENT_SCANS等并发类变量。以上部署命令、变量与诊断步骤均与当前仓库 packages/Probe 的实现一一对应可在部署与排障时对照源码深入验证。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考