OneUptime Port Monitor 使用指南：TCP 端口可用性监控、连接分阶段计时与告警条件配置

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）的完整配置方法，以及底层的探测实现机制。

Overview：Port Monitor 能做什么

Port Monitor 的核心任务是探测某个网络端口是否在接受连接，从而实现对特定服务可用性的监控。它带来的能力包括：

• 监控特定端口上的服务可用性；
• 记录完整的连接耗时（含 DNS 解析与 TCP 建连过程）；
• 验证数据库、邮件服务器、应用服务器等服务是否正常运行；
• 在服务故障影响用户之前提前发现中断。

在 OneUptime 的整体监控体系中，Port 是 Common/Types/Monitor/MonitorType.ts 中MonitorType.Port对应的一种内置监控类型，实际探测工作由分布在各地（或自托管部署）的 Probe 执行。

创建 Port Monitor

在 OneUptime Dashboard 中创建 Port Monitor 的步骤如下：

1. 进入 Dashboard 的Monitors页面；
2. 点击Create Monitor；
3. 监控类型选择Port；
4. 填写目标主机的主机名或 IP 地址，以及端口号；
5. 按需配置监控条件（Monitoring Criteria）。

创建完成后，OneUptime 会调度 Probe 按设定间隔对该端口发起 TCP 连接探测。

配置项：Hostname / IP 与 Port

Hostname or IP Address

填写目标主机的主机名或 IP 地址，例如example.com或192.168.1.1。该值决定了探测的目标地址，也直接影响计时阶段：目标是主机名时需要先做 DNS 解析，目标是 IP 时则跳过 DNS 阶段。

Port

填写要监控的端口号（取值范围 1–65535）。常用端口与服务对照：

从源码实现看，端口校验与探测入口位于 Probe/Utils/Monitors/MonitorTypes/PortMonitor.ts：PortMonitor.ping接受Hostname | IPv4 | IPv6 | URL类型的目标与Port类型的端口，若目标中携带端口号（如Hostname或URL带 port），会覆盖显式传入的端口；若最终端口缺失，会抛出BadDataException("Port is not specified")并将其标记为用户配置错误而非代码缺陷。

连接计时：DNS Lookup 与 TCP Connect 两阶段

当目标是主机名时，OneUptime 将一次端口检查的耗时拆分为两个阶段：

1. DNS Lookup：从检查开始到第一次 TCP 连接尝试开始之间的时间；
2. 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等）或一般网络错误，这些错误码直接对应监控条件中"是否请求超时"等判定；
• 一个值得注意的细节是：当目标端口为 25（SMTP）且当前环境未启用 ICMP ping 监控时（某些云厂商会封锁出站 SMTP），代码会将端口 25 的超时视为在线处理，避免误报。

针对上述计时与回退逻辑，仓库在 Probe/Tests/Utils/Monitors/MonitorTypes/PortMonitor.test.ts 中通过 mocknet.Socket的方式覆盖了大量场景，包括 IPv4/IPv6 回退、DNS 失败、超时、重试等，可作为理解行为边界的参考。

重试与额外尝试

源码中还实现了失败/慢响应的重试机制：默认重试次数为 4（DEFAULT_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。

可用的过滤类型

过滤条件（Filter Condition）

对于Is Online与Is Request Timeout：

• True— 条件为真；
• False— 条件为假。

对于Total Connection Time (DNS + TCP)、Port DNS Lookup Time与Port TCP Connect Time：

• Greater 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 time）

Evaluate 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控制当窗口无法支撑该条件（例如窗口内没有任何记录，或监控运行时间还不够覆盖窗口）时的行为（对应源码 NoDataPolicy）：

• Ignore（默认）— 条件不匹配。适用于普通阈值告警；
• Trigger— 将缺失数据本身视为问题。适用于心跳式检查——沉默本身就是故障；
• Treat As Zero— 将整个窗口当作单个 0 参与比较。适用于计数器类指标——"没有事件"确实意味着 0。

此外，DNS 解析类条件在目标已经是 IP 地址时没有可求值的对象。因此，需要同时兼容主机名与 IP 目标的条件，请使用总连接时间或 TCP 连接时间。

示例条件

端口关闭时标记为离线

• Filter Type：Is Online
• Filter Condition：False

总连接时间超过 500ms 时告警

• Filter Type：Total Connection Time (DNS + TCP) (in ms)
• Filter Condition：Greater Than
• Value：500

总连接偏慢时标记为降级

• Filter Type：Total Connection Time (DNS + TCP) (in ms)
• Filter Condition：Greater Than
• Value：200

DNS 解析慢时告警

• Filter Type：Port DNS Lookup Time (in ms)
• Filter Condition：Greater Than
• Value：100

TCP 建连慢时告警

• Filter Type：Port TCP Connect Time (in ms)
• Filter Condition：Greater Than
• Value：250

实战建议

结合文档与源码，配置 Port Monitor 时有几点值得留意：

1. 优先使用主机名还是 IP？若你同时关心 DNS 解析质量（例如检测解析缓慢或 DNS 故障），使用主机名；若只关心端口本身是否可达，使用 IP 可省去 DNS 阶段，条件配置也更简单。
2. 阈值要与探测环境匹配：探测由 OneUptime Probe 从特定网络位置发起，跨公网探测的基线延迟通常高于内网，建议先用历史响应时间分布确定阈值（如 500ms/200ms 示例），避免把网络正常抖动误判为故障。
3. 组合使用分阶段条件：DNS 阶段慢与 TCP 建连慢往往指向不同问题——前者可能是解析服务异常，后者可能是目标主机负载或网络路径问题。分别设置Port DNS Lookup Time与Port TCP Connect Time条件，有助于故障定位。
4. 心跳类检查使用 Trigger：对于必须持续上报的服务，将If No Data设为Trigger，让"数据消失"本身触发告警。
5. 充分理解 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