OneUptime 自定义探针（Custom Probe）部署实战：私网监控、代理配置与断连排障全指南

可观测性后端运维前端云原生微服务AI Agent【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址https://gitcode.com/GitHub_Trending/on/oneuptime点击查看免费下载自定义探针Custom Probe是 OneUptime 监控体系中的关键组件它将一个轻量的 Node.js 探针容器部署到你自己的网络内部用于监控私有网络资源或防火墙之后的内部服务。本文基于仓库官方文档 fr/probe/custom-probe.md及同源英文版 en/probe/custom-probe.md完整覆盖探针的创建、Docker / Docker Compose / Kubernetes 三种部署方式、HTTP(S) 代理配置、全部环境变量语义并深入源码讲解探针注册、代理路由与断连自诊断的底层原理帮助你从能跑起来进阶到能自己排障。什么是自定义探针为什么需要它OneUptime 官方托管的全局探针位于公网无法访问你的内网。自定义探针就是解决这个问题的方案把它部署在你的网络内部或防火墙之后它就能代表你的环境去执行网站、API、TCP 端口、Ping、SSL、合成监控Synthetic等各类检查并将结果上报回 OneUptime 服务端。从源码看探针是一个独立服务进程入口在 packages/Probe/Index.ts启动时先初始化代理配置与遥测随后依次执行注册Register、心跳AliveJob、拉取监控任务列表FetchMonitorList等 Job并可选启动 SNMP Trap、Syslog、NetFlow 接收器。它的镜像定义在 packages/Probe/Dockerfile.tpl镜像名称为oneuptime/probe官方发布标签为release。前置准备在 Dashboard 创建探针并获取凭据在部署前需要先在 OneUptime Dashboard 中创建自定义探针进入Moniteurs监控 Paramètres设置 Sondes探针菜单创建一个新的自定义探针创建成功后你会得到两个关键凭据PROBE_ID— 探针 IDPROBE_KEY— 探针密钥。这两个值将作为环境变量注入到探针容器中用于向 OneUptime 服务端完成身份认证。在 packages/Probe/Config.ts 中可以看到PROBE_ID会被解析为ObjectID而PROBE_KEY是必填项——缺失时探针进程会直接以错误日志退出process.exit(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探针使用宿主机网络栈便于访问内网资源、执行 Ping/端口探测无需发布端口ONEUPTIME_URL指向你的 OneUptime 实例。使用官方云服务时保持https://oneuptime.com自托管 OneUptime 时将其改为你自己的实例地址。带代理配置的 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:release部署探针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启动命令docker compose up -d带代理配置的 Docker Composeversion: 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同样地自托管 OneUptime 时请将ONEUPTIME_URL改为你自己的实例地址。部署探针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带代理配置的 Kubernetes 部署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 时同样需将ONEUPTIME_URL修改为你自己的实例地址。环境变量全解探针支持的环境变量分为必选与可选两类默认值与取值范围与 packages/Probe/Config.ts 中的解析逻辑一一对应均通过NumberUtil.parseNumberWithDefault做下限/上限钳制。必选变量变量说明PROBE_KEY来自 OneUptime Dashboard 的探针密钥PROBE_ID来自 OneUptime Dashboard 的探针 IDONEUPTIME_URLOneUptime 实例地址默认https://oneuptime.com从 packages/Probe/Config.ts 可以看到ONEUPTIME_URL还支持PROBE_INGEST_URL作为替代输入若两者都未设置进程会直接报错退出。URL 末尾会自动补上/probe-ingest路径探针的所有控制面请求心跳、任务拉取、结果上报都发往该 ingest 端点。可选变量变量默认值说明HTTP_PROXY_URL—HTTP 请求使用的 HTTP 代理服务器 URLHTTPS_PROXY_URL—HTTPS 请求使用的 HTTP 代理服务器 URLNO_PROXY—逗号分隔的、应绕过代理的主机或域名列表PROBE_NAME—探针自定义名称PROBE_DESCRIPTION—探针描述PROBE_MONITORING_WORKERS1最小 1监控 worker 数量PROBE_MONITOR_FETCH_LIMIT10最小 1每次拉取的监控任务数量PROBE_MONITOR_RETRY_LIMIT3最小 0首次失败后的重试次数即最多 4 次尝试用于未单独设置重试次数的监控步骤PROBE_SYNTHETIC_MONITOR_SCRIPT_TIMEOUT_IN_MS60000合成监控脚本超时毫秒上限受合成运行时限制PROBE_CUSTOM_CODE_MONITOR_SCRIPT_TIMEOUT_IN_MS60000自定义代码监控脚本超时毫秒PROBE_API_REQUEST_TIMEOUT_IN_MS45000最小 1000探针发给 OneUptime 的每个请求的截止时间毫秒PROBE_API_SLOW_REQUEST_THRESHOLD_IN_MS10000最小 100慢请求告警阈值超过该值的请求会记录耗时警告PROBE_MONITOR_CHECK_TIMEOUT_IN_MS900000最小 1000单个监控项完整检查的硬性截止时间超时后放弃并在下一周期重试PROBE_DISCOVERY_SCAN_TIMEOUT_IN_MS540000090 分钟单次网络发现扫描的截止时间PROBE_DISCOVERY_PROGRESS_INTERVAL_IN_MS30000最小 5000发现扫描向服务端增量上传已发现主机的间隔PROBE_DISCOVERY_SCAN_CONCURRENCY00 表示自动按目标规模计算单次扫描并发探测的地址数小容器可调低PROBE_DISCOVERY_REVERSE_DNS_BUDGET_IN_MS0自动范围 1000–1200000反向 DNSPTR解析的时间预算PROBE_DISCOVERY_NETBIOS_MAX_HOSTS0内置上限 2000范围 1–4000单次扫描 NetBIOS 查询的最大主机数PROBE_DISCOVERY_MAX_CONCURRENT_SCANS4范围 1–16探针上同时运行的最大独立发现扫描数设为1可串行执行几点值得注意的源码细节PROBE_MONITOR_CHECK_TIMEOUT_IN_MS的默认值并非写死的常量。在 Config.ts 中它以 15 分钟为基线并与PROBE_SYNTHETIC_MONITOR_SCRIPT_TIMEOUT_IN_MS 合成 worker 启动宽限时间 PROBE_API_REQUEST_TIMEOUT_IN_MS取较大者同时被 Node 定时器最大可表示延迟钳制。这样做的原因是如果运维者调高了合成脚本超时探针的整体检查截止时间必须同步放宽否则合成长脚本会被这个外层超时误杀。PROBE_API_REQUEST_TIMEOUT_IN_MS是对抗假断开的关键。Config.ts 注释指出axios 默认超时为 0无限等待若服务端接受了 TCP 连接却永不响应请求会无限挂起探针的lastAlive心跳逐渐过期Dashboard 会把一台健康探针误标为Disconnected。设置一个有界的超时让失败响亮而快速比无声挂起好得多。官方文档en 版特别提示先升级 OneUptime 服务端再升级自定义探针以使用并发发现扫描。若用新版探针连接旧服务端应设PROBE_DISCOVERY_MAX_CONCURRENT_SCANS1。代理配置机制与兼容性探针同时支持 HTTP 与 HTTPS 代理。配置后探针会把所有监控流量路由到指定代理服务器并通过逗号分隔的NO_PROXY列表对内部主机/网段选择性绕过代理。代理 URL 格式http://[username:password]proxy.server.com:port示例基础代理http://proxy.example.com:8080带认证http://username:passwordproxy.example.com:8080支持的特性HTTP 与 HTTPS 代理代理认证用户名/密码HTTP/HTTPS 代理间的自动回退通过NO_PROXY选择性绕过代理适用于所有监控类型Website、API、SSL、Synthetic 等兼容性说明标准变量名HTTP_PROXY_URL、HTTPS_PROXY_URL、NO_PROXY与其小写变体http_proxy、https_proxy、no_proxy均受支持。源码视角代理如何生效代理的实现在 packages/Probe/Utils/ProxyConfig.tsconfigure()在探针任何 HTTP 请求发出前被调用见 Index.ts分别基于HTTP_PROXY_URL/HTTPS_PROXY_URL构造HttpProxyAgent/HttpsProxyAgent在 Config.ts 中HTTP_PROXY_URL依次回退到http_proxy、HTTP_PROXYNO_PROXY会被按逗号和空白拆分并清理为空条目shouldBypassProxy()实现了NO_PROXY匹配支持*、.example.com及*.example.com子域名通配、可选端口example.com:8080、IPv6 括号写法并按目标协议推断默认端口http→80、https→443、ws→80、wss→443当调用方显式要求接受自签名证书或提供客户端证书时会按请求临时构造新的代理 agent而不复用缓存 agent因为缓存 agent 的 TLS 选项在构造时已固定。验证探针是否运行成功探针运行成功后它应在其 Dashboard 中显示为Connected已连接状态。如果未显示为已连接请检查容器日志docker logs oneuptime-probe断连诊断一步步定位问题探针被标记为Disconnected说明它发往 OneUptime 的请求开始失败。好消息是探针日志会明确指出每个失败请求卡在了哪个阶段通常无需猜测。以下是官方文档给出的四个排查步骤全部有 packages/Probe/Utils/ProbeApiDiagnostics.ts 源码支撑。1. 阅读启动时打印的环境块每个探针在启动时都会打印一个 JSON 块包含正在使用的 OneUptime URL、请求截止时间、代理设置、继承的 DNS 解析器、Node 与操作系统版本、TLS 校验是否被禁用NODE_TLS_REJECT_UNAUTHORIZED0等。对应源码为logStartupEnvironment()ProbeApiDiagnostics.ts。上报问题时请务必附带这个块。2. 找到失败报告中的stalledAt每个发往 OneUptime 的失败请求都会记录一个包含stalledAt和whatThisMeans的 JSON 块。stalledAt表示请求从未越过的那一阶段stalledAt含义SocketAssignment没有任何数据离开本机。socket 池被占满或已配置的代理始终未完成 CONNECT 隧道。TcpConnect本机发出了 SYN 但没有收到任何回应——防火墙或安全设备在丢弃数据包或目标主机不可达。TlsHandshakeTCP 已建立但 TLS 握手从未完成通常是中间设备在检查 TLS 流量。RequestSend连接已建立但请求体从未被完整写出——对端停止了读取。WaitingForServerResponse请求已完整送达但服务器未返回任何字节。探针的网络是正常的——请检查 OneUptime 服务器、其负载均衡器和反向代理。ResponseBody服务器已开始响应但中途停滞。同一块还报告deadlineOverrunInMs如果 45000ms 的截止时间实际耗掉了远超 45000ms 的真实时间说明是探针进程自身被阻塞事件循环被占满或机器被挂起/限流此时应先查看块中的probeProcess.eventLoopMaxDriftInMs再去怀疑网络。源码中buildFailureReport()ProbeApiDiagnostics.ts通过读取真实 socket 的bytesWritten/bytesRead/tcpHandshakeStillPending/ TLS 协商状态等来判定所处阶段其阶段枚举定义在ProbeRequestStallPhase中。3. 阅读连通性自测结果连续 3 次失败后探针会对同一台服务器逐层测试DNS → TCP → TLS → 真实 HTTP 往返并记录每层耗时第一个失败的层就是答案。配置了代理时探针测试的是到代理的这一跳——因为那才是它真正建立的连接源码见runConnectivitySelfTest()ProbeApiDiagnostics.ts。自测有节流限制离线探针不会刷屏日志至少 5 分钟一次。4. 在失败发生前盯住慢请求成功但耗时超过PROBE_API_SLOW_REQUEST_THRESHOLD_IN_MS的请求会被记录实际耗时。一台开始出现 20 秒请求的探针正走在跨越 45 秒截止时间、被标记为Disconnected的路上。源码中logSlowSuccess()ProbeApiDiagnostics.ts明确把慢但成功视为失败的前兆信号并给出警告日志。在 OneUptime 服务端一侧被慢速响应、或被探针在响应发出前放弃的探针请求也会在服务端日志中记录带探针 ID。这两份日志合在一起就能判断问题出在连接的哪一侧。探针注册与心跳背后的源码链路理解断连诊断还需知道探针上线时发生了什么。在 packages/Probe/Services/Register.ts 中registerProbe()会以 30 秒间隔、最多重试 10 次完成注册全部失败则抛出带明确提示的错误检查PROBE_KEY/REGISTER_PROBE_KEY/ 到PROBE_INGEST_URL的连通性对于自定义探针没有REGISTER_PROBE_KEY注册走/alive端点用PROBE_KEYPROBE_ID做校验注册成功后探针进程随即启动 AliveJob、Monitor 任务拉取、Discovery 扫描、网络设备轮询等 Job见 Index.ts并可选启动 SNMP Trap / Syslog / NetFlow 接收器。启动时的环境块正是这套流程的体检报告——当探针无法连接时它几乎总能被环境块或失败报告中的某一项解释清楚这也是 ProbeApiDiagnostics.ts 文件头注释所强调的设计初衷把45000ms 超时这一个笼统的错误拆解成防火墙、代理、TLS 拦截、服务器过载这四种完全不同的工单。小结自定义探针是 OneUptime 私网监控的基石。按照本文的 Docker、Docker Compose 或 Kubernetes 任一种方式配合正确的PROBE_ID/PROBE_KEY/ONEUPTIME_URL即可上线在内网出口受限时通过HTTP_PROXY_URL/HTTPS_PROXY_URL/NO_PROXY完成代理路由一旦探针显示Disconnected优先按环境块 → stalledAt 失败报告 → 连通性自测 → 慢请求日志四步走并借助服务端日志双向定位。更深入的参数语义如各超时默认值的推导逻辑可以直接阅读仓库中的 packages/Probe/Config.ts 与 packages/Probe/Utils/ProbeApiDiagnostics.ts 源码注释。赞分享可观测性后端运维前端云原生微服务AI Agent【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址https://gitcode.com/GitHub_Trending/on/oneuptime点击查看免费下载相关推荐OneUptime 自定义探针Custom Probe部署实战私有网络监控、代理配置与 Disconnected 故障诊断OneUptime 自定义探针Custom Probe部署实战私有网络监控、代理配置与 Disconnected 故障诊断 自建监控平台时最棘手的问题之可观测性后端运维前端云原生微服务AI AgentOneUptime 自定义探针Custom Probe部署、配置与断连诊断完全指南OneUptime 自定义探针Custom Probe部署、配置与断连诊断完全指南 自定义探针是 OneUptime 监控体系中用于覆盖 私有网络与防火墙后可观测性后端运维前端云原生微服务AI AgentOneUptime 自定义探针Custom Probe完整部署与断连排查指南OneUptime 自定义探针Custom Probe完整部署与断连排查指南 本篇技术指南围绕 OneUptime 开源监控平台的自定义探针展开它解决了可观测性后端运维前端云原生微服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考