OneUptime 端口监控Port Monitor实战指南从创建配置到探针底层原理【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime端口监控Port Monitor是 OneUptime 中用于验证目标主机上特定 TCP/UDP 端口可用性的核心监控类型。本文以官方 Port Monitor 文档为主体结合仓库中探针Probe的源码实现、类型定义与测试用例系统讲解如何在 OneUptime 中创建并配置端口监控、理解各项监控条件Criteria与过滤器的语义并深入剖析连接超时、重试、分阶段计时与错误分类等底层工作机制。读完本文你将能够独立搭建一套覆盖数据库、邮件服务器、应用服务等端口可用性与响应延迟的可观测监控并能够读懂探针侧返回的每一个字段。Port Monitor 是什么Port Monitor 通过周期性尝试与目标主机上的指定端口建立 TCP 连接UDP 场景亦受支持以此判断端口是否开放、是否能够响应连接请求从而反映依赖该端口的服务是否正常运行。根据官方文档它支持以下能力监控特定端口上的服务可用性跟踪端口连接响应时间验证数据库、邮件服务器、应用服务器等关键服务是否在运行在服务故障影响到最终用户之前提前发现并触发告警。从源码结构看端口监控的每次探测由独立的探针Probe节点执行核心实现位于 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts。其ping方法接受主机Hostname/IPv4/IPv6/URL、端口号以及可选的超时、重试等参数通过 Node.js 的net.Socket建立连接并返回结构化结果。创建一个 Port Monitor在 OneUptime 控制台中创建端口监控的步骤如下进入 OneUptime Dashboard 的Monitors监控页面点击Create Monitor创建监控选择Port作为监控类型填写目标主机的Hostname 或 IP 地址以及需要监控的端口号按需配置监控条件Monitoring Criteria保存后监控将按预设计划由探针周期性执行。核心配置选项主机名或 IP 地址填写目标主机的域名或 IP例如example.com、192.168.1.1或 IPv6 地址。从 PortMonitor.ts 的实现可以看到探针会优先从Hostname或URL对象中提取主机名若其中携带端口信息如host:port该端口会覆盖配置中的端口值若最终未解析到端口则会抛出BadDataException(Port is not specified)并将该错误归类为用户配置错误而不是探针代码缺陷。端口号填写 1–65535 范围内的端口号。仓库中的 Common/Types/Port.ts 对端口做了严格校验isValid方法接受数字或字符串校验区间为0 port 65535非法值会抛出BadDataException(Port is not in valid format.)其 Zod Schema 同样限制为整数且在0..65535之间。常见端口示例如下端口服务22SSH25SMTP80HTTP443HTTPS3306MySQL5432PostgreSQL6379Redis27017MongoDB监控计划与执行保存后监控进入调度队列由部署在各地的探针按频率执行连接检查。探针侧还通过OnlineCheck.canProbeMonitorPortMonitors()在失败时确认探针自身是否在线避免将探针离线误判为目标端口故障见 PortMonitor.ts。监控条件Monitoring Criteria详解监控条件决定了端口在什么情况下被判定为在线Online、受限Degraded或离线Offline。每个条件由「检查项Check On」「过滤器类型Filter Type」「阈值Value」以及可选的「时段聚合」组成。对应的类型定义集中在 Common/Types/Monitor/CriteriaFilter.ts。可用的检查项CheckOn端口监控可用的检查项与文档对应如下检查项说明Is Online在线端口是否开放并接受连接Response Time (in ms)响应时间完成连接建立所耗费的毫秒数Is Request Timeout请求超时连接尝试是否发生了超时除此之外源码中的CheckOn枚举还暴露了更细粒度的端口检查项Port DNS Lookup Time (in ms)DNS 解析耗时与Port TCP Connect Time (in ms)TCP 建连耗时它们与探针返回的portTimings字段一一对应可用于更精准的延迟分析详见下文分阶段计时。过滤器类型FilterType对于Is Online与Is Request Timeout这类布尔型检查项过滤器类型为True真与False假对于Response Time这类数值型检查项过滤器类型为Greater Than大于、Less Than小于、Greater Than Or Equal To大于等于、Less Than Or Equal To小于等于。这与源码中 CriteriaFilter.ts 定义的FilterType枚举一致。同时CriteriaFilterUtil.hasValueField明确指出布尔型检查项IsOnline、IsRequestTimeout以及True/False过滤器不提供阈值输入框只有数值型过滤器才需要填写阈值。时段聚合评估Evaluate Over Time「Evaluate this criteria over a period在时段内评估该条件」是条件表单中的一个复选框而非过滤器类型。勾选后系统不再与单次检查的最新值比较而是对「For the last (in minutes)最近 N 分钟」窗口内的检查结果做聚合后再与阈值比较。可选的聚合方式Evaluate包括Average平均值Sum求和Maximum Value最大值Minimum Value最小值All Values所有值Any Value任意值源码层面的支撑来自 CriteriaFilter.tsEvaluateOverTimeType枚举定义了上述六种聚合方式源码中MunimumValue即 Minimum ValueEvaluateOverTimeMinutes枚举定义了可选窗口2、3、5、10、15、20、30、45、60 分钟EvaluateOverTimeOptions接口包含timeValueInMinutes窗口分钟数与evaluateOverTimeType聚合方式CriteriaFilterUtil.getEvaluateOverTimeTypeByCriteriaFilter特别指出对于IsOnline这类布尔序列求平均或求和没有意义因此只开放All Values与Any Value两种集合型聚合。此外EvaluateOverTimeOptions还包含onNoDataPolicy选项默认Ignore用于控制评估窗口内没有数据时如何处理避免监控刚启动数据不足时产生误报。源码级原理一次端口探测是如何完成的要正确解读监控结果理解探针的执行流程至关重要。以下逻辑全部来自 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts。绝对超时Absolute Deadline探针为每次连接尝试设置了一个绝对截止时间setTimeout于socket.connect之前启动默认超时值为5000 毫秒pingOptions.timeout?.toNumber() || 5000。这个定时器覆盖 DNS 解析 所有地址族的连接尝试而不仅仅是套接字空闲计时。超时后抛出UnableToReachServer(Ping timeout)响应中isTimeout true该结果会被Is Request Timeout检查项捕获。重试机制探针默认最多进行5 次尝试首次尝试 源码中DEFAULT_RETRIES_WHEN_UNSET 4次重试见 PortMonitor.ts。每次重试前会等待 1 秒Sleep.sleep(1000)。两条特殊规则连接失败时若仍可重试则递增重试计数并再次尝试连接成功但响应时间超过 10 秒时也会额外再尝试一次以排除偶发慢速干扰。最终结果中probeAttempts数组记录每一次尝试的序号、发起时间、响应时间与成败totalAttempts给出总尝试次数。分阶段计时Per-Phase Timing成功建连后探针通过process.hrtime.bigint()高精度计时并返回portTimings字段其结构定义在 Common/Types/Monitor/PortMonitor/PortMonitorTimings.ts字段含义dnsLookupInMsDNS 解析耗时目标为 IP 时不存在该字段tcpConnectInMsTCP 建连耗时totalConnectionInMs连接总耗时含 DNSResponse Time (in ms)、Port DNS Lookup Time (in ms)、Port TCP Connect Time (in ms)三个检查项即分别对应这些计时值。错误分类Request Failed Phase当连接失败时探针会依据错误码与错误信息将失败原因归类为四个阶段对应 PortMonitor.ts 的getRequestFailedDetails失败阶段触发条件错误码示例DNS ResolutionDNS 解析失败ENOTFOUND、EAI_AGAIN、EAI_FAIL、getaddrinfoRequest Timeout请求超时ETIMEDOUT、UnableToReachServer(Ping timeout)TCP ConnectionTCP 建连失败ECONNREFUSED、ECONNRESET、EHOSTUNREACH、ENETUNREACH、EPIPE等Network Error网络错误其他未归类错误ECONNREFUSED即端口拒绝连接通常意味着端口关闭或服务未监听这是端口离线最常见的直接证据。典型监控条件示例以下示例与官方文档一致可直接用于实际配置。示例一端口关闭时标记为离线检查项Check OnIs Online过滤器类型Filter TypeFalse条件为假即端口不在线说明当连接尝试被拒绝或失败时触发离线。示例二连接时间超过 500ms 时触发通知检查项Check OnResponse Time (in ms)过滤器类型Filter TypeGreater Than大于值Value500说明适用于对延迟敏感的服务如数据库连接池的健康水位。示例三连接缓慢时标记为受限Degraded检查项Check OnResponse Time (in ms)过滤器类型Filter TypeGreater Than大于值Value200说明将 200ms 以上视为性能劣化配合在线与离线条件构成三级状态判定。更进阶的做法是为Port DNS Lookup Time设置阈值例如大于 300ms 告警用于区分 DNS 解析慢与 TCP 建连慢从而快速定位瓶颈在域名解析层还是网络传输层。边界行为与部署注意事项SMTP 端口25的特殊策略部分云厂商会阻断出站 SMTP 流量。为规避误报探针内置了一条窄策略当端口为 25 且 ICMP/Ping 监控不可用时将 25 端口的连接超时视为在线见 PortMonitor.ts。该判断依赖Register.isPingMonitoringEnabled()——若部署环境禁用了 Ping 监控典型云环境则 25 端口超时不会触发离线告警。端口监控不经过 SSRF Egress 防护与 HTTP 类监控不同端口监控直接打开 TCP 连接不会经过DataSourceEgressGuard的出口地址校验。这一点在 PortMonitorEgressBoundary.test.ts 中被明确钉死为当前边界端口检查可以访问回环地址如127.0.0.1这正是 E2E 测试 ProbeExecution.spec.ts 能够通过本机回环端口验证探针执行链路的前提。因此在设计端口监控的目标时应确保探针网络与目标网络之间的可达性策略符合自身安全要求。探针离线保护当端口连接失败且重试耗尽后探针会先调用OnlineCheck.canProbeMonitorPortMonitors()确认探针自身是否在线若探针离线则返回null而不是一个端口离线的假结论避免把基础设施问题误报为业务故障见 PortMonitor.ts。测试验证仓库为端口监控提供了完善的测试覆盖可作为理解行为与回归保障的参考Probe/Tests/Utils/Monitors/MonitorTypes/PortMonitor.test.ts通过 Mock 的net.Socket模拟连接成功、拒绝、超时等场景验证重试次数、probeAttempts记录、响应时间计算与requestFailedDetails分类Probe/Tests/Utils/Monitors/MonitorTypes/PortMonitorEgressBoundary.test.ts验证端口监控不经 Egress Guard 的边界行为并说明该行为与端到端测试的依赖关系。小结Port Monitor 是 OneUptime 监控体系中结构最简单、适用面最广的一类监控只需主机 端口两个核心参数即可覆盖数据库、缓存、邮件、SSH 等几乎所有基础设施服务的可用性探测。理解其底层实现——5 秒绝对超时、最多 5 次尝试、分阶段计时、四类错误分类、SMTP 25 端口的云环境策略以及探针离线保护——能够帮助你更准确地解读每次检查结果并据此设计出在线/受限/离线三级状态与延迟阈值相结合的精细化监控策略。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime 端口监控（Port Monitor）实战指南：从创建配置到探针底层原理
OneUptime 端口监控Port Monitor实战指南从创建配置到探针底层原理【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime端口监控Port Monitor是 OneUptime 中用于验证目标主机上特定 TCP/UDP 端口可用性的核心监控类型。本文以官方 Port Monitor 文档为主体结合仓库中探针Probe的源码实现、类型定义与测试用例系统讲解如何在 OneUptime 中创建并配置端口监控、理解各项监控条件Criteria与过滤器的语义并深入剖析连接超时、重试、分阶段计时与错误分类等底层工作机制。读完本文你将能够独立搭建一套覆盖数据库、邮件服务器、应用服务等端口可用性与响应延迟的可观测监控并能够读懂探针侧返回的每一个字段。Port Monitor 是什么Port Monitor 通过周期性尝试与目标主机上的指定端口建立 TCP 连接UDP 场景亦受支持以此判断端口是否开放、是否能够响应连接请求从而反映依赖该端口的服务是否正常运行。根据官方文档它支持以下能力监控特定端口上的服务可用性跟踪端口连接响应时间验证数据库、邮件服务器、应用服务器等关键服务是否在运行在服务故障影响到最终用户之前提前发现并触发告警。从源码结构看端口监控的每次探测由独立的探针Probe节点执行核心实现位于 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts。其ping方法接受主机Hostname/IPv4/IPv6/URL、端口号以及可选的超时、重试等参数通过 Node.js 的net.Socket建立连接并返回结构化结果。创建一个 Port Monitor在 OneUptime 控制台中创建端口监控的步骤如下进入 OneUptime Dashboard 的Monitors监控页面点击Create Monitor创建监控选择Port作为监控类型填写目标主机的Hostname 或 IP 地址以及需要监控的端口号按需配置监控条件Monitoring Criteria保存后监控将按预设计划由探针周期性执行。核心配置选项主机名或 IP 地址填写目标主机的域名或 IP例如example.com、192.168.1.1或 IPv6 地址。从 PortMonitor.ts 的实现可以看到探针会优先从Hostname或URL对象中提取主机名若其中携带端口信息如host:port该端口会覆盖配置中的端口值若最终未解析到端口则会抛出BadDataException(Port is not specified)并将该错误归类为用户配置错误而不是探针代码缺陷。端口号填写 1–65535 范围内的端口号。仓库中的 Common/Types/Port.ts 对端口做了严格校验isValid方法接受数字或字符串校验区间为0 port 65535非法值会抛出BadDataException(Port is not in valid format.)其 Zod Schema 同样限制为整数且在0..65535之间。常见端口示例如下端口服务22SSH25SMTP80HTTP443HTTPS3306MySQL5432PostgreSQL6379Redis27017MongoDB监控计划与执行保存后监控进入调度队列由部署在各地的探针按频率执行连接检查。探针侧还通过OnlineCheck.canProbeMonitorPortMonitors()在失败时确认探针自身是否在线避免将探针离线误判为目标端口故障见 PortMonitor.ts。监控条件Monitoring Criteria详解监控条件决定了端口在什么情况下被判定为在线Online、受限Degraded或离线Offline。每个条件由「检查项Check On」「过滤器类型Filter Type」「阈值Value」以及可选的「时段聚合」组成。对应的类型定义集中在 Common/Types/Monitor/CriteriaFilter.ts。可用的检查项CheckOn端口监控可用的检查项与文档对应如下检查项说明Is Online在线端口是否开放并接受连接Response Time (in ms)响应时间完成连接建立所耗费的毫秒数Is Request Timeout请求超时连接尝试是否发生了超时除此之外源码中的CheckOn枚举还暴露了更细粒度的端口检查项Port DNS Lookup Time (in ms)DNS 解析耗时与Port TCP Connect Time (in ms)TCP 建连耗时它们与探针返回的portTimings字段一一对应可用于更精准的延迟分析详见下文分阶段计时。过滤器类型FilterType对于Is Online与Is Request Timeout这类布尔型检查项过滤器类型为True真与False假对于Response Time这类数值型检查项过滤器类型为Greater Than大于、Less Than小于、Greater Than Or Equal To大于等于、Less Than Or Equal To小于等于。这与源码中 CriteriaFilter.ts 定义的FilterType枚举一致。同时CriteriaFilterUtil.hasValueField明确指出布尔型检查项IsOnline、IsRequestTimeout以及True/False过滤器不提供阈值输入框只有数值型过滤器才需要填写阈值。时段聚合评估Evaluate Over Time「Evaluate this criteria over a period在时段内评估该条件」是条件表单中的一个复选框而非过滤器类型。勾选后系统不再与单次检查的最新值比较而是对「For the last (in minutes)最近 N 分钟」窗口内的检查结果做聚合后再与阈值比较。可选的聚合方式Evaluate包括Average平均值Sum求和Maximum Value最大值Minimum Value最小值All Values所有值Any Value任意值源码层面的支撑来自 CriteriaFilter.tsEvaluateOverTimeType枚举定义了上述六种聚合方式源码中MunimumValue即 Minimum ValueEvaluateOverTimeMinutes枚举定义了可选窗口2、3、5、10、15、20、30、45、60 分钟EvaluateOverTimeOptions接口包含timeValueInMinutes窗口分钟数与evaluateOverTimeType聚合方式CriteriaFilterUtil.getEvaluateOverTimeTypeByCriteriaFilter特别指出对于IsOnline这类布尔序列求平均或求和没有意义因此只开放All Values与Any Value两种集合型聚合。此外EvaluateOverTimeOptions还包含onNoDataPolicy选项默认Ignore用于控制评估窗口内没有数据时如何处理避免监控刚启动数据不足时产生误报。源码级原理一次端口探测是如何完成的要正确解读监控结果理解探针的执行流程至关重要。以下逻辑全部来自 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts。绝对超时Absolute Deadline探针为每次连接尝试设置了一个绝对截止时间setTimeout于socket.connect之前启动默认超时值为5000 毫秒pingOptions.timeout?.toNumber() || 5000。这个定时器覆盖 DNS 解析 所有地址族的连接尝试而不仅仅是套接字空闲计时。超时后抛出UnableToReachServer(Ping timeout)响应中isTimeout true该结果会被Is Request Timeout检查项捕获。重试机制探针默认最多进行5 次尝试首次尝试 源码中DEFAULT_RETRIES_WHEN_UNSET 4次重试见 PortMonitor.ts。每次重试前会等待 1 秒Sleep.sleep(1000)。两条特殊规则连接失败时若仍可重试则递增重试计数并再次尝试连接成功但响应时间超过 10 秒时也会额外再尝试一次以排除偶发慢速干扰。最终结果中probeAttempts数组记录每一次尝试的序号、发起时间、响应时间与成败totalAttempts给出总尝试次数。分阶段计时Per-Phase Timing成功建连后探针通过process.hrtime.bigint()高精度计时并返回portTimings字段其结构定义在 Common/Types/Monitor/PortMonitor/PortMonitorTimings.ts字段含义dnsLookupInMsDNS 解析耗时目标为 IP 时不存在该字段tcpConnectInMsTCP 建连耗时totalConnectionInMs连接总耗时含 DNSResponse Time (in ms)、Port DNS Lookup Time (in ms)、Port TCP Connect Time (in ms)三个检查项即分别对应这些计时值。错误分类Request Failed Phase当连接失败时探针会依据错误码与错误信息将失败原因归类为四个阶段对应 PortMonitor.ts 的getRequestFailedDetails失败阶段触发条件错误码示例DNS ResolutionDNS 解析失败ENOTFOUND、EAI_AGAIN、EAI_FAIL、getaddrinfoRequest Timeout请求超时ETIMEDOUT、UnableToReachServer(Ping timeout)TCP ConnectionTCP 建连失败ECONNREFUSED、ECONNRESET、EHOSTUNREACH、ENETUNREACH、EPIPE等Network Error网络错误其他未归类错误ECONNREFUSED即端口拒绝连接通常意味着端口关闭或服务未监听这是端口离线最常见的直接证据。典型监控条件示例以下示例与官方文档一致可直接用于实际配置。示例一端口关闭时标记为离线检查项Check OnIs Online过滤器类型Filter TypeFalse条件为假即端口不在线说明当连接尝试被拒绝或失败时触发离线。示例二连接时间超过 500ms 时触发通知检查项Check OnResponse Time (in ms)过滤器类型Filter TypeGreater Than大于值Value500说明适用于对延迟敏感的服务如数据库连接池的健康水位。示例三连接缓慢时标记为受限Degraded检查项Check OnResponse Time (in ms)过滤器类型Filter TypeGreater Than大于值Value200说明将 200ms 以上视为性能劣化配合在线与离线条件构成三级状态判定。更进阶的做法是为Port DNS Lookup Time设置阈值例如大于 300ms 告警用于区分 DNS 解析慢与 TCP 建连慢从而快速定位瓶颈在域名解析层还是网络传输层。边界行为与部署注意事项SMTP 端口25的特殊策略部分云厂商会阻断出站 SMTP 流量。为规避误报探针内置了一条窄策略当端口为 25 且 ICMP/Ping 监控不可用时将 25 端口的连接超时视为在线见 PortMonitor.ts。该判断依赖Register.isPingMonitoringEnabled()——若部署环境禁用了 Ping 监控典型云环境则 25 端口超时不会触发离线告警。端口监控不经过 SSRF Egress 防护与 HTTP 类监控不同端口监控直接打开 TCP 连接不会经过DataSourceEgressGuard的出口地址校验。这一点在 PortMonitorEgressBoundary.test.ts 中被明确钉死为当前边界端口检查可以访问回环地址如127.0.0.1这正是 E2E 测试 ProbeExecution.spec.ts 能够通过本机回环端口验证探针执行链路的前提。因此在设计端口监控的目标时应确保探针网络与目标网络之间的可达性策略符合自身安全要求。探针离线保护当端口连接失败且重试耗尽后探针会先调用OnlineCheck.canProbeMonitorPortMonitors()确认探针自身是否在线若探针离线则返回null而不是一个端口离线的假结论避免把基础设施问题误报为业务故障见 PortMonitor.ts。测试验证仓库为端口监控提供了完善的测试覆盖可作为理解行为与回归保障的参考Probe/Tests/Utils/Monitors/MonitorTypes/PortMonitor.test.ts通过 Mock 的net.Socket模拟连接成功、拒绝、超时等场景验证重试次数、probeAttempts记录、响应时间计算与requestFailedDetails分类Probe/Tests/Utils/Monitors/MonitorTypes/PortMonitorEgressBoundary.test.ts验证端口监控不经 Egress Guard 的边界行为并说明该行为与端到端测试的依赖关系。小结Port Monitor 是 OneUptime 监控体系中结构最简单、适用面最广的一类监控只需主机 端口两个核心参数即可覆盖数据库、缓存、邮件、SSH 等几乎所有基础设施服务的可用性探测。理解其底层实现——5 秒绝对超时、最多 5 次尝试、分阶段计时、四类错误分类、SMTP 25 端口的云环境策略以及探针离线保护——能够帮助你更准确地解读每次检查结果并据此设计出在线/受限/离线三级状态与延迟阈值相结合的精细化监控策略。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考