OneUptime Port Monitor 使用指南TCP 端口可用性监控、连接分阶段计时与告警条件配置【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读Port Monitor 是 OneUptime 中用于监控指定主机上某个 TCP 端口是否开放并可连接的监控类型。它通过周期性地尝试与该端口建立 TCP 连接来判断服务的可用性并可测量 DNS 解析、TCP 建连两阶段的耗时用于配置在线/降级/离线判定与阈值告警。读完本文你将掌握 Port Monitor 的创建流程、连接计时原理、监控条件Criteria的完整配置方法以及底层的探测实现机制。OverviewPort Monitor 能做什么Port Monitor 的核心任务是探测某个网络端口是否在接受连接从而实现对特定服务可用性的监控。它带来的能力包括监控特定端口上的服务可用性记录完整的连接耗时含 DNS 解析与 TCP 建连过程验证数据库、邮件服务器、应用服务器等服务是否正常运行在服务故障影响用户之前提前发现中断。在 OneUptime 的整体监控体系中Port 是 Common/Types/Monitor/MonitorType.ts 中MonitorType.Port对应的一种内置监控类型实际探测工作由分布在各地或自托管部署的 Probe 执行。创建 Port Monitor在 OneUptime Dashboard 中创建 Port Monitor 的步骤如下进入 Dashboard 的Monitors页面点击Create Monitor监控类型选择Port填写目标主机的主机名或 IP 地址以及端口号按需配置监控条件Monitoring Criteria。创建完成后OneUptime 会调度 Probe 按设定间隔对该端口发起 TCP 连接探测。配置项Hostname / IP 与 PortHostname or IP Address填写目标主机的主机名或 IP 地址例如example.com或192.168.1.1。该值决定了探测的目标地址也直接影响计时阶段目标是主机名时需要先做 DNS 解析目标是 IP 时则跳过 DNS 阶段。Port填写要监控的端口号取值范围 1–65535。常用端口与服务对照端口服务22SSH25SMTP80HTTP443HTTPS3306MySQL5432PostgreSQL6379Redis27017MongoDB从源码实现看端口校验与探测入口位于 Probe/Utils/Monitors/MonitorTypes/PortMonitor.tsPortMonitor.ping接受Hostname | IPv4 | IPv6 | URL类型的目标与Port类型的端口若目标中携带端口号如Hostname或URL带 port会覆盖显式传入的端口若最终端口缺失会抛出BadDataException(Port is not specified)并将其标记为用户配置错误而非代码缺陷。连接计时DNS Lookup 与 TCP Connect 两阶段当目标是主机名时OneUptime 将一次端口检查的耗时拆分为两个阶段DNS Lookup从检查开始到第一次 TCP 连接尝试开始之间的时间TCP Connect从第一次 TCP 连接尝试到连接成功之间的时间包含需要 IPv6/IPv4 回退fallback时尝试另一个地址所花费的时间。总连接时间DNS TCP从检查开始一直计量到 TCP 连接成功并继续作为端口监控原有的响应时间response time字段保留因此已有的判定条件、告警与历史图表无需改动即可继续使用同一字段。当目标是 IP 地址时无需 DNS 解析DNS 阶段被省略在分阶段计时功能上线之前收集的旧检查结果则只有总连接时间。以上分阶段数据在代码中以 Common/Types/Monitor/PortMonitor/PortMonitorTimings.ts 定义的PortMonitorTimings结构表示包含可选的dnsLookupInMs、tcpConnectInMs、totalConnectionInMs三个字段字段可选使得连接失败时也能表达部分计时证据。底层实现原理Probe 探测过程在 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts 中可以确认上述计时的真实来源探测使用 Node.js 原生net.Socket发起socket.connect(portNumber, hostAddress)并让 Node 自行完成主机名解析与地址族选择/回退而不是预解析后连接单个地址通过监听 socket 的lookup、connectionAttempt、connect事件配合process.hrtime.bigint()高精度时钟分别记录首次成功 DNS 查找、首次 TCP 建连尝试、连接成功的时刻进而计算出dnsLookupInMs、tcpConnectInMs与totalConnectionInMs代码注释明确指出connectionAttempt事件可能被 Node 跳过当 lookup 只返回一个地址时因此首次成功 lookup 时刻会作为 TCP 起始时间的兜底超时使用一个绝对截止计时器setTimeout(onDeadline, timeout)默认 5000ms它从connect()之前开始计时覆盖 DNS 与所有地址族连接尝试而不是空闲 socket 计时器每次失败会通过getRequestFailedDetails将底层错误归类为 DNS 解析失败ENOTFOUND/EAI_AGAIN/EAI_FAIL等、请求超时ETIMEDOUT/UnableToReachServer、TCP 建连失败ECONNREFUSED/ECONNRESET/EHOSTUNREACH等或一般网络错误这些错误码直接对应监控条件中是否请求超时等判定一个值得注意的细节是当目标端口为 25SMTP且当前环境未启用 ICMP ping 监控时某些云厂商会封锁出站 SMTP代码会将端口 25 的超时视为在线处理避免误报。针对上述计时与回退逻辑仓库在 Probe/Tests/Utils/Monitors/MonitorTypes/PortMonitor.test.ts 中通过 mocknet.Socket的方式覆盖了大量场景包括 IPv4/IPv6 回退、DNS 失败、超时、重试等可作为理解行为边界的参考。重试与额外尝试源码中还实现了失败/慢响应的重试机制默认重试次数为 4DEFAULT_RETRIES_WHEN_UNSET即最多 5 次尝试当响应时间超过 10 秒或连接失败时在重试额度内会间隔 1 秒后重新探测PortMonitor.ts。每次尝试的attemptedAt、responseReceivedAt、responseTimeInMs、isOnline、failureCause都会记录到probeAttempts数组中。监控条件Monitoring Criteria监控条件决定了端口何时被判定为在线Online、降级Degraded或离线Offline。条件基于以下可用的过滤类型Filter Type其枚举定义见 Common/Types/Monitor/CriteriaFilter.ts 中的CheckOn。可用的过滤类型过滤类型说明Is Online端口是否开放并接受连接Total Connection Time (DNS TCP) (in ms)总连接时间目标是主机名时包含 DNS 解析时间Port DNS Lookup Time (in ms)首次 TCP 尝试之前的 DNS 解析时间目标是 IP 时不可用Port TCP Connect Time (in ms)从首次 TCP 尝试到连接成功的时间包含 IP 回退耗时Is Request TimeoutDNS 解析或 TCP 连接尝试是否超过配置的时间限制过滤条件Filter Condition对于Is Online与Is Request TimeoutTrue— 条件为真False— 条件为假。对于Total Connection Time (DNS TCP)、Port DNS Lookup Time与Port TCP Connect TimeGreater Than— 响应时间超过阈值Less Than— 响应时间低于阈值Greater Than or Equal To— 响应时间大于等于阈值Less Than or Equal To— 响应时间小于等于阈值。上述条件类型对应源码中 CriteriaFilter.ts 的FilterType枚举。注意布尔型过滤类型Is Online、Is Request Timeout使用True/False不提供值输入框hasValueField返回 false且CriteriaFilterUtil.isBooleanSeries会把它们标记为布尔序列参与跨时间段求值时会被限制为 All Values / Any Value 两种聚合方式。跨时间段求值Evaluate 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)设置可选 2、3、5、10、15、20、30、45、60 分钟见 EvaluateOverTimeMinutes。需要特别理解的两个语义All Values只有在窗口内数据真正覆盖满之后才匹配。刚创建的监控或检查记录中断的监控并不具备最近 N 分钟的完整历史此时该条件会等待数据攒满而不是仅凭已有的单条读数就匹配Any Value则是只要单次检查一越界就立刻告诉我的设置仍然会立即触发。If No Data控制当窗口无法支撑该条件例如窗口内没有任何记录或监控运行时间还不够覆盖窗口时的行为对应源码 NoDataPolicyIgnore默认— 条件不匹配。适用于普通阈值告警Trigger— 将缺失数据本身视为问题。适用于心跳式检查——沉默本身就是故障Treat As Zero— 将整个窗口当作单个 0 参与比较。适用于计数器类指标——没有事件确实意味着 0。此外DNS 解析类条件在目标已经是 IP 地址时没有可求值的对象。因此需要同时兼容主机名与 IP 目标的条件请使用总连接时间或 TCP 连接时间。示例条件端口关闭时标记为离线Filter TypeIs OnlineFilter ConditionFalse总连接时间超过 500ms 时告警Filter TypeTotal Connection Time (DNS TCP) (in ms)Filter ConditionGreater ThanValue500总连接偏慢时标记为降级Filter TypeTotal Connection Time (DNS TCP) (in ms)Filter ConditionGreater ThanValue200DNS 解析慢时告警Filter TypePort DNS Lookup Time (in ms)Filter ConditionGreater ThanValue100TCP 建连慢时告警Filter TypePort TCP Connect Time (in ms)Filter ConditionGreater ThanValue250实战建议结合文档与源码配置 Port Monitor 时有几点值得留意优先使用主机名还是 IP若你同时关心 DNS 解析质量例如检测解析缓慢或 DNS 故障使用主机名若只关心端口本身是否可达使用 IP 可省去 DNS 阶段条件配置也更简单。阈值要与探测环境匹配探测由 OneUptime Probe 从特定网络位置发起跨公网探测的基线延迟通常高于内网建议先用历史响应时间分布确定阈值如 500ms/200ms 示例避免把网络正常抖动误判为故障。组合使用分阶段条件DNS 阶段慢与 TCP 建连慢往往指向不同问题——前者可能是解析服务异常后者可能是目标主机负载或网络路径问题。分别设置Port DNS Lookup Time与Port TCP Connect Time条件有助于故障定位。心跳类检查使用 Trigger对于必须持续上报的服务将If No Data设为Trigger让数据消失本身触发告警。充分理解 All Values 的等待语义新创建的监控若配置了基于窗口的 All Values 条件需要等待窗口被数据填满后才会开始匹配这是设计行为而非故障。小结Port Monitor 是 OneUptime 监控体系中面向 TCP 服务可用性的一类监控核心能力包括周期性 TCP 连接探测、DNS 与 TCP 两阶段连接计时、基于Is Online、总连接时间、DNS 解析时间、TCP 建连时间与超时状态的五类过滤条件以及支持跨时间段聚合与空数据处理策略的监控条件框架。通过 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts 的源码可以确认其实现基于 Node 原生net.Socket的事件驱动计时而 Common/Types/Monitor/CriteriaFilter.ts 则完整定义了条件与聚合语义两者共同构成了从探测到告警判定的完整链路。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考