OneUptime 网站监控器（Website Monitor）完全指南：HTTP 探测、动态占位符与高级 TLS 配置

OneUptime 网站监控器Website Monitor完全指南HTTP 探测、动态占位符与高级 TLS 配置【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文以 OneUptime 官方文档 fr/monitor/website-monitor.md英文原版见 en/monitor/website-monitor.md为主线结合仓库内 Probe 探针的实际实现源码与测试用例系统讲解如何创建网站监控器、配置监控判定标准并深入剖析缓存穿透、重定向策略、自签名证书、mTLS 双向认证与失败重试等高级能力。读完本文你将能够独立完成一个生产级网站可用性监控的完整配置并理解 OneUptime 在探针侧是如何执行这些检查的。一、什么是 OneUptime 网站监控器OneUptime 的网站监控Website Monitoring功能用于监控任意网站或网页的可用性Availability、性能Performance与响应正确性Response。其核心原理是探针Probe周期性向目标 URL 发送 HTTP 请求并对返回结果进行判定从而确定网站当前处于在线Online、降级Degraded还是离线Offline状态。通过网站监控器你可以实现监控网站的正常运行时间Uptime与可用性跟踪响应时间与性能趋势校验 HTTP 状态码是否符合预期如 200、301校验响应头Response Headers是否完整或匹配预期值在真实用户感知故障之前第一时间发现宕机。二、创建网站监控器在 OneUptime 控制台中创建网站监控器的步骤如下进入 OneUptime 控制台的Monitors监控器页面点击Create Monitor创建监控器在监控器类型中选择Website网站输入希望监控的网站 URL按需配置监控判定标准详见下文监控判定标准章节保存后探针即会按设定的频率对该 URL 发起探测。三、基础配置选项3.1 网站 URL输入完整的网站 URL必须包含协议http://或https://例如https://example.com在底层实现中探针会根据 URL 的协议自动决定走 HTTP 还是 HTTPS 通道并会校验 URL 的合法性非法 URL 会被视为配置错误而非网络故障详见 WebsiteMonitor.ts 中的BadDataException处理分支。3.2 动态 URL 占位符缓存穿透当被监控的 URL 位于 CDN 或缓存代理之后时监控器可能每次拿到的都是缓存响应而无法真正触达源站Origin Server。为了在每次检查时强制穿透缓存OneUptime 支持在 URL 中嵌入动态占位符Dynamic URL Placeholders每次探测请求时会被替换为唯一值。支持的占位符占位符说明示例值{{timestamp}}替换为当前 Unix 时间戳秒1719500000{{random}}替换为随机唯一字符串a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5使用示例将监控器 URL 配置为https://example.com/health?cb{{timestamp}}则每次监控检查时URL 会被替换为https://example.com/health?cb1719500000 https://example.com/health?cb1719500005 ...也可以使用{{random}}在每次请求中生成唯一字符串https://example.com/health?nocache{{random}}适用场景当源站根据查询参数Query String或请求头区分缓存时动态占位符能确保每次探测都命中源站从而获得真实的健康状态与性能数据。此外{{timestamp}}占位符的每秒唯一特性也常被用作简单的签名/防重放参数。3.3 高级选项不跟随重定向Do Not Follow Redirects默认情况下OneUptime 会跟随 HTTP 重定向301、302 等最终检查的是最终目的地的响应。启用该选项后监控器将直接检查重定向响应本身而不是跳转后的最终结果。该行为在探针源码中由doNotFollowRedirects选项驱动见 WebsiteMonitor.ts当该选项为true时探测循环在收到第一个响应即重定向响应后立即返回同时源码中还会通过limitRedirectResponseBody: !options.doNotFollowRedirects对跟随重定向时的响应体做预算限制防止恶意超大响应体耗尽资源。允许自签名证书Allow Self-Signed Certificates启用该选项后探针将跳过 TLS 证书校验。当目标服务器使用自签名或其他不受信任的 TLS 证书时例如内部预发布/暂存环境该选项非常实用。需要特别注意的是这一选项在跨域重定向场景下的正确传递OneUptime 有专门的回归测试覆盖见 WebsiteMonitor.selfSignedRedirect.test.ts。该测试的注释明确指出曾经存在一个缺陷——http://host - https://host的跨源重定向会导致自签名证书允许选项被丢弃进而使已获授权的主机仍然报出 Self Signed Certificate. 错误。当前实现通过HttpMonitorRequest.getTlsOptionsForHop对每一跳Hop单独计算 TLS 选项保证自签名证书的允许策略能跨重定向正确延续。客户端证书mTLS 双向认证当目标端点要求双向 TLS 认证mutual TLS时启用Use client certificate (mTLS)并配置以下三项Client Certificate (PEM)— 要出示的 PEM 编码客户端证书Client Private Key (PEM)— 与之匹配的 PEM 编码私钥Client Private Key Passphrase可选— 仅当私钥本身被加密时才需要提供。这等价于 curl 中的--cert与--key参数curl --cert client.crt --key client.key https://api.example.com/health在探针实现中这三个值分别对应tlsClientCertificate、tlsClientKey、tlsClientKeyPassphrase选项见 WebsiteMonitor.ts 的ping方法签名它们会通过 TLS 选项逐跳下发给 HTTP 客户端。仓库中的 WebsiteMonitor.mtls.test.ts 即为该能力的专用测试。敏感信息处理建议证书与私钥属于敏感数据。官方文档建议将其保存为 Monitor Secrets监控器密钥并在配置项中以{{monitorSecrets.name}}的形式引用。Monitor Secrets 在服务端解析渲染后的真实值永远不会出现在控制台中。失败重试Retries on FailureRetries on Failure的计数值是第一次尝试之后的重试次数因此设为0只执行 1 次检查设为2最多执行 3 次1 次初始 2 次重试默认值为 3最大值为 3即最多 4 次尝试。超时Timeout不会被重试因为请求本身的超时时间已经覆盖了该次尝试。源码层面的印证在 WebsiteMonitor.ts 中定义了DEFAULT_RETRIES_WHEN_UNSET: number 4注释明确说明这是与引入重试计数前一致的五次尝试WebsiteMonitor.retries.test.ts 的文件头注释同样确认了重试值统计的是第一次尝试之后的重试次数0 表示只运行一次2 表示最多运行三次未设置重试值的监控器保留其原有的五次尝试。除 4xx/5xx 错误响应外探针还会对响应时间超过 10 秒的检查发起重试源码中responseTimeInMS.toNumber() 10000的判断且每次重试之间会Sleep.sleep(1000)间隔 1 秒。当所有尝试均超时后探针会返回Request was tried X times and it timed out.的失败原因并将isTimeout标记为true便于上层区分超时与其他网络错误。四、监控判定标准Monitoring Criteria你可以配置判定标准决定网站何时被视为在线Online、降级Degraded或离线Offline。可依据以下维度响应状态码Response Status Code— 检查 HTTP 状态码是否匹配预期值如 200、301响应时间Response Time— 监控响应时间是否超过阈值响应体Response Body— 检查响应体是否包含或匹配特定内容响应头Response Headers— 验证特定响应头是否存在或匹配预期值。4.1 在一段时间内评估Evaluating over a period of timeEvaluate this criteria over a period of time是标准表单上的一个独立复选框而非过滤器条件。开启后判定将不再基于最近一次检查的值而是对比过去一段时间窗口内多次检查的聚合结果。聚合方式由Evaluate下拉框选择包括Average平均值Sum总和Maximum Value最大值Minimum Value最小值All Values所有值Any Value任意值窗口大小由For the last (in minutes)设定。几个需要特别理解的行为All Values 只在窗口被真实数据完整覆盖时才会匹配。刚刚创建的监控器或检查记录中断的监控器其历史数据不足以支撑N 分钟的结论此时该标准会等待而非用仅有的那一次读数去匹配。Any Value则是只要单次检查触发就立刻告警的设置它会立即触发。If No Data无数据时控制窗口无法支撑判定时的行为Ignore忽略默认— 标准不匹配。适用于普通阈值告警场景Trigger触发— 将缺少数据本身视为问题。适用于心跳式Heartbeat检查即静默本身就是故障Treat As Zero按零处理— 将窗口视为单个零值进行比较。适用于计数器场景即没有事件在语义上就等于零。4.2 探针侧如何判定在线从源码实现看WebsiteMonitor.ts探针一次完整探测的判定流程大致为构造请求默认使用GET部分场景会先尝试HEAD若服务器拒绝 HEAD 则自动降级为 GET按需逐跳处理重定向每一跳都重新计算 TLS 选项记录完整响应状态码、响应体、响应头、响应时间毫秒、各阶段 HTTP 耗时HttpPhaseTimings对 4xx/5xx 响应与超过 10 秒的慢响应执行重试汇总所有尝试probeAttempts与总尝试次数totalAttempts并返回。此外探针在判定离线之前还会执行一次探针自身健康检查OnlineCheck.canProbeMonitorWebsiteMonitors如果探针自己的网络/解析器已经故障那么它报告监控器离线的结果是不可信的探针会直接放弃本次判定返回null。这一机制保证了监控告警的可靠性。五、安全边界与防护机制网站监控器天然会被配置为访问外部 URLOneUptime 探针侧内置了多重防护SSRF 防护Egress Guard探针对目标 URL 的解析结果DNS 地址做访问策略校验私有网络/内网地址的访问会受到限制相关行为在 WebsiteMonitor.ssrf.test.ts 中有完整覆盖目标解析验证Target Resolution见 WebsiteMonitorTargetResolution.test.ts响应体预算Response Body Budget跟随重定向时对响应体大小做上限限制避免超大响应拖垮探针超时终止Timeout整个探测过程受执行上下文HttpMonitorExecutionContext的剩余超时预算约束默认单次超时 5000ms可在监控器配置中调整。六、实战建议汇总监控源站而非边缘若目标位于 CDN 之后请在 URL 中使用{{timestamp}}或{{random}}占位符穿透缓存确保探测到的是真实源站状态内部环境 TLS对使用自签名证书的内部暂存环境启用Allow Self-Signed Certificates若开启后配合了域名重定向http→https当前实现已保证该选项跨跳生效接口需要双向认证使用mTLS配置客户端证书与私钥并通过 Monitor Secrets 以{{monitorSecrets.名称}}引用避免敏感信息明文落盘或出现在控制台中合理设置重试默认 3 次重试最多 4 次尝试覆盖大多数瞬时抖动场景超时不会触发重试因此对网络抖动敏感的场景应同时关注超时设置用好时间窗口评估对偶发抖动不告警、持续恶化才告警的需求开启Evaluate this criteria over a period of time并选择Average聚合对立即知晓单次失败的需求使用Any Value对心跳类监控静默即故障将If No Data设为Trigger区分离线类型探针返回的超时isTimeout与常规网络错误在告警文案上不同配置告警时可根据Request was tried X times and it timed out.之类的失败原因做分级处理。七、参考文件索引官方文档英文原版en/monitor/website-monitor.md官方文档法语版本文主题文档fr/monitor/website-monitor.md监控器密钥文档en/monitor/monitor-secrets.md探针核心实现packages/Probe/Utils/Monitors/MonitorTypes/WebsiteMonitor.ts重试逻辑测试packages/Probe/Tests/Utils/Monitors/MonitorTypes/WebsiteMonitor.retries.test.ts自签名证书跨重定向测试packages/Probe/Tests/Utils/Monitors/MonitorTypes/WebsiteMonitor.selfSignedRedirect.test.tsmTLS 测试packages/Probe/Tests/Utils/Monitors/MonitorTypes/WebsiteMonitor.mtls.test.tsSSRF 防护测试packages/Probe/Tests/Utils/Monitors/MonitorTypes/WebsiteMonitor.ssrf.test.ts【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考