如果让我用一句话概括最近几个月做的最有“烟火气”的工具大概就是Agent-Reach一个用来回答“我到底能不能从这台机器真正摸到那台机器上装的 agent”的命令行小工具。坐标变了环境变了版本换了网络策略改了agent 照样显示“在线”但真正要调它干活的时候经常石沉大海。我把这些年在机房和云上踩过的问题归拢到一起做了这个小东西。它不打算替代监控平台只解决一个非常具体的痛点——agent 的可达性而不是 agent 的心跳状态。这篇东西不写高大上的架构图就聊聊 Agent-Reach 是什么、为什么是现在这个样子、我在落地过程中摔过的跟头以及最终怎么把它塞进自己的运维环境里。后面如果你也想维护一堆 agent或者正在被“明明全绿、一调就挂”折磨那这篇文章应该能帮你省下至少一个通宵的排查时间。1. 为什么会有 Agent-Reach混乱的 agent 遍布节点1.1 名不副实的“全面监控”我最早遇到的问题并不是某个监控平台不好用而是监控平台太好用了。它自动发现主机自动安装 agent自动录入资产然后自动给你画出一张全绿的拓扑图。最开始看着这张图心理上是很爽的。第一次告警需要远程执行一条命令才发现节点上根本没有 agent或者 agent 版本老得连消息格式都不兼容。再查一下原来监控平台记录的“在线”只是几分钟前 agent 曾经上报过一次心跳不代表现在网络路径通、端口可达、进程还活着、消息还能被正常消费。这种“全绿但是摸不到”的状态很坑。真正到了故障窗口期所有人盯着告警页面以为 agent 链路都正常结果真正下发指令时要么连接超时要么协议错乱要么被安全策略挡在半路。后面我翻了一些大厂的实践资料他们管这种问题叫agent fleets reachability也就是“代理舰队触达能力”。这个概念和单纯的在线状态是两码事它关心的是客户端、服务端、网络路径、协议版本、身份校验这些因素叠加之后的真实可用性。1.2 大平台有清单却没有“有效触达”不少监控平台其实提供了“主动探测”或“手动下发命令”的功能看上去能做这件事。但我用下来它们的探测往往长得太像平台自己的架构。检测的是“Agent 管理通道”不是通用 TCP 端口或业务层接口一旦这台机器跑的不是平台官方的 agent而是自研采集器、云厂商的 cloud agent、或者容器里的 sidecar 进程平台就无能无力了。另一个问题是大平台的探测范围一般是平台其已纳管的列表裸奔的、没被纳管但必须承认同样依赖 agent 的节点反而成了盲区。更重要的是这些平台都把自己定义为“持续监控系统”按分钟级别定时探测。但我当时的场景是变更前要快速给运维同学一张能够直接说明“这批节点是否 Reachable”的清单扩容后要看一组新机器是否已经满足 agent 通信条件故障时要在接下来十分钟里反复对同一批目标做高并发探测。这种短促、高频率、按批次、按组的探测需求大平台的界面根本没法满足。1.3 我想要的其实很简单我想要的其实很简单一条命令进去给我一批 IP 或域名工具自己决定用什么方式去探然后输出一张矩阵哪些主机通了、哪些端口挂了、哪些 agent 心跳接口有响应但返回值不对、哪些虽然活着但版本太老。最好还能顺手判断连接耗时给我把分布情况画出来。Agent-Reach 这个名字就是这么来的Agent 是否在 Reach 的范围之内——既包括网络可达也包括 agent 的接口语义可达。从做这个工具的第一天开始我就没打算让它长得像一个新监控系统。它只是一个命令行工具一个跑完就退出的探针。不过它也不是又一次“ping 一下完事”的玩具而是把我在不同 Agent 协议上积累的探测经验收敛到了统一的入口里。2. Agent-Reach 的核心设计探测目标、协议与覆盖矩阵2.1 数据模型先理解要探测的是什么Agent-Reach 内部把要探测的东西抽象成三个层次节点、agent 实例、check 项。节点是 IP 或域名也可能是云主机实例 IDAgent-Reach 会根据配置进行解析。agent 实例是运行在节点上的具体进程态对象比如 systemd 服务名、进程名、容器名它有一个独立的端口或管理接口。check 项才是真正要探测的逻辑单元可能是“这个端口 22 是不是通”“这个 9100 端口的 metrics 是否能正常出数据”“这个 4318 端口是不是能拿到 span”。这个模型说起来很抽象举个例子就容易理解了。我有一台 OpenTelemetry Collector 的节点它的 agent 实例叫 otelcol跑在 4318 端口。我要探测的事实上并不是“这台机器有没有联网”而是“4318 端口有没有进程在监听”“HTTP 请求能不能拿到健康响应”。如果第三个 check 挂了那这个节点在网络上是通的但 agent 对 Agent-Reach 来说就是不可达。这个“网络通但业务不通”的差别是 Agent-Reach 存在的核心价值。所以你会看到Agent-Reach 的配置不是传统的“主机清单加端口”那么简单而是一组嵌套结构targets: - name: 生产网关组 hosts: - 10.10.1.11 - 10.10.1.12 checks: - type: tcp port: 9100 timeout: 3000 - type: http url: http://10.10.1.11:4318/health expect: status: ok这种设计一开始会显得有点繁琐但真正用起来非常舒服。你在同一个目标上可以同时跑多种 check不用为了“验证 agent 是否可达”单独配三遍。结果输出的时候也会按这个结构聚合节点层给了整体结论agent 实例层给了状态check 项给了具体失败原因。2.2 探测模式怎么选ICMP、TCP、HTTPAgent-Reach 支持三类探测模式每一类对应的语义不一样我花了不少时间理顺这三者之间的关系。第一类是 ICMP Ping这类探测解决的是“这台主机在网络层到底存活不存活”的问题。它能验证路由可达、防丢包、主机在线但没法证明业务逻辑正常。而且现在很多云环境默认禁 ping结果会导致误判。所以我只把它当作最基础的信号绝对不会单独依赖 ICMP 判断 agent 是否 Reachable。第二类是 TCP 端口探测这是最核心的 agent 可达性判据。所谓 TCP 探测就是主动向目标 IP 的某个端口发起 TCP 连接能连上基本说明这个端口上有一个进程在监听网络路径上也没有被防火墙拦死。Agent 的通信端口千奇百怪有 9100、9102、4318、8080也有各种高端口TCP 探测是最通用的方式。这一层最怕的就是安全组策略只允许特定源 IP 访问这点我会在后面的实战环节里仔细展开。第三类是 HTTP 探测专门针对有 HTTP 健康接口的 agent。很多采集器、agent 都有自己的/health或/status端点HTTP 探测不仅能证明 TCP 端口活着还能继续往深走一步验证 agent 进程响应快不快、返回状态码正不正常、响应体里有没有预期的关键字。Agent-Reach 会把响应体拉回来做非常轻量的匹配匹配不到就判定为“agent 语义不可达”。三者的关系和选择逻辑我整理成一张表探测方式回答的问题典型场景局限ICMP Ping主机在网络层是否存在快速初筛大批节点云环境默认禁 ping无法覆盖业务端口TCP 连接目标端口是否有进程监听agent 端口可达性检查能证明有进程在监听但无法证明业务正常HTTP 请求agent 健康接口是否正常有 Web 管理接口的 agent只能覆盖 HTTP 协议的 agent实际使用中大部分 check 项我会做成TCP HTTP 组合。先 TCP 连一把如果连不上直接记失败连得上再考虑是不是要调一次 HTTP 接口。如果请求在超时时间内返回 200 并且响应体里出现预期关键字才算这条 agent 链路是真正的 Reached。2.3 扫描的并发控制与超时模型这里有一个容易被新手忽略的点对 5000 台机器做探测如果一个个串行来每条链接假设平均 100ms总时长是 500 秒完全没法接受。如果一口气开 5000 个 goroutine 去并发连又可能把本地连接池打满或者被目标端的安全设备判定为扫描行为。Agent-Reach 最终采用的方案是固定并发窗口加指数退避。核心参数有三个concurrency同时进行的探测 routines 数量默认 100。timeout单次探测的超时时间默认 2000ms。retry失败后的重试次数默认 1 次。假设你给我 1000 个目标、每个目标 3 个 check 项那实际探测任务是 3000 个。并发 100 的情况下单条平均耗时 50ms理论总耗时是 3000 / 100 × 0.05 1.5 秒左右。但现实里超时的目标往往会占十分之一超时时间一拉长整体就变成 3000 / 100 × 2 60 秒。所以我经常把timeout调到 1000ms宁可让一部分慢目标被判为“超时”也要保证整轮扫描在可接受的时间窗口内完成。关于探测失败的重试我特意把它做成可配置的。很多监控类工具默认会自动重试但在故障排查时重试反而耽误时间。当我明确知道某个端口已经挂了我要的是立刻得到结果而不是等它试了 3 次之后再来告诉我。所以 Agent-Reach 默认值是不重试只有配置里显式指定了retry才会重试。用完你会发现这种“不积极”的默认值其实很适合排查场景。3. 从零部署 Agent-Reach配置文件与实操命令3.1 编译与环境准备Agent-Reach 是用 Go 写的。选择 Go 的原因很简单单二进制、静态编译、没依赖拿到任何 Linux 服务器上就能跑连 glibc 版本都不用关心。它不需要单独的 agent 端也不依赖服务端组件——本身就只是一个执行探活的客户端跑完就退出。如果要从源码编译你的环境需要 Go 1.21 以上步骤非常常规git clone https://github.com/example/agent-reach cd agent-reach make build编译产物是一个名为agent-reach的可执行文件。如果你不想自己编译也可以直接下载 release 页面里对应架构的压缩包解压之后放进/usr/local/bin/。它支持 Linux amd64、arm64 和 mac 的本地二进制。部署这台探活机器本身不需要多高的配置我把探活端放在一台 2C4G 的轻量云服务器上连续跑几万次检查都没有遇到瓶颈瓶颈反而都在远端目标上。严格来说探活端不需要和 agent 部署在同一个内网。但如果你要探测的是内网地址探活端需要能路由到目标网段这一步一定要提前确认。我见过有人把探活端放在办公楼下的办公网去探生产内网地址结果当然是全部失败。第一次跑全红还以为是工具写错了后来才发现路由根本不通。3.2 一个最小可直接运行的配置我在这里写一个我能直接跑的配置样例。假设我有一组 Consul 服务节点agent 暴露的检查端口是 8500同时有一个健康接口/v1/status。我的config.yaml长这样global: concurrency: 50 timeout: 2000 output: table groups: - name: consul-prod targets: - 192.168.10.21 - 192.168.10.22 - 192.168.10.23 checks: - type: tcp port: 8500 - type: http url: http://192.168.10.21:8500/v1/status expect: consul这段配置的含义很直接探活端以 50 并发、单次超时 2 秒的标准对三台主机做 TCP 8500 端口探测再对其中一台做 HTTP 健康检查。你可能会问为什么健康检查的 URL 只写 192.168.10.21这样不是只测试了其中一台吗是的这是刻意的。在生产里我通常会给每一台单独配置 HTTP check因为健康接口一般是按主机 IP 访问的。如果你图省事也可以用变量替换Agent-Reach 支持{host}占位符例如checks: - type: http url: http://{host}:8500/v1/status expect: consul这样就会自动把目标 IP 填充进 URL每个目标都会独立进行 HTTP 探测。这个特性后面救了我很多次因为手写几百台主机的 URL 非常容易出错。3.3 命令行操作与报告生成部署完配置执行命令的方式非常朴素:agent-reach check -f config.yaml默认输出的是一张表格类似下面这样GROUP HOST CHECK_TCP CHECK_HTTP RESULT consul-prod 192.168.10.21 OK (12ms) OK (45ms) REACHABLE consul-prod 192.168.10.22 OK (15ms) FAIL TIMEOUT PARTIAL consul-prod 192.168.10.23 FAIL TIMEOUT SKIP UNREACHABLEPARTIAL 这个状态很有意思。它指的是 TCP 通了但 HTTP 健康检查超时或者响应不符合预期。在这个场景里网络层面是可达的agent 的 HTTP 服务层却是异常的。如果你只看 TCP 结果会以为服务正常如果只看 HTTP又会以为网络断了。只有把两个结果合在一起才能立刻定位到“问题出在 agent 进程层面”。如果嫌表格不好解析可以直接把结果导出成 JSONagent-reach check -f config.yaml --json report_20250601.jsonJSON 里会包含每个 check 的原始耗时、错误原因、延迟分布方便后续写脚本继续加工。我习惯在变更流程里跑一趟 Agent-Reach然后把 JSON 归档到对象存储这样后续出问题时有据可查。3.4 接入现有告警体系的 JSON 输出很多同学学会命令行之后第一反应是那告警怎么办其实很简单Agent-Reach 不是用来长期监控的它适合在特定时间点做高频率探测。但如果你确实想让它周期性地跑就用 cron 或者 systemd timer 拉起。我自己的典型做法是在变更方案里加入一步agent-reach check -f config.yaml --json --out summary这个--out summary会输出一个统计摘要比如TOTAL: 300, REACHABLE: 291, PARTIAL: 5, UNREACHABLE: 4, PASS_RATE: 97.0%把这一行文本扔给自研的告警机器人由它对通过率做阈值判断。如果低于 95% 就发钉钉/企业微信通知这种轻量做法已经稳定跑了很久没有引入任何新的长驻服务。4. 真实环境里踩过的大坑与对应解决4.1 端口扫描把所有交换机吓坏之后第一次拿 Agent-Reach 扫描 2000 台设备时设置并发 200结果被网络团队投诉了。当时业务网点比较多安全交换机对大量不同 IP 的 9100 端口连接非常敏感直接触发了流量异常告警甚至有一台交换机的 CPU 飙到 80%。排查了很久才发现是本机并发太高连接请求密集轰炸了同一网段的网关设备。这个教训让我把默认并发定在了 50并且给每个探测目标之间加了一层轻微抖动。用 Go 写代码时在每次探测前随机 sleep 一个几毫秒的间隔这样扫描特征的“整齐感”就会大大降低。不要小看这一点很多网络设备看重的是“连接的规律性”随机抖动之后触发安全告警的概率小了一个数量级。另外目标端口的范围尽量收敛。能只探测 8500 就不要连 8500 和 22 一起探。业务上不需要的端口扫了不仅容易出告警还可能被人误认为渗透行为。这是我一开始没注意到的风险借着和大家分享的机会也提醒所有使用 Agent-Reach 或类似工具的人探活行为要克制不要变成了真攻击。4.2 Agent 混装版本导致的误判第二个让我头疼的问题是版本混装。某次扩容一半机器装的是 v1.7.0另一半装的是 v2.1.0。v2.1.0 的健康接口路径变了从/health改成了/v2/health。Agent-Reach 用旧路径去探 v2 节点拿到 404判定为不可达。从工具的角度看结果没错但实际上是 agent 活得很好只是我配置错了 URL。这个问题启发我在配置里加入了agent-version元数据字段。这样输出的结果里会带上该节点的 agent 版本方便统一核对。哪怕探测到 404也能立刻发现“咦这个节点版本是 v2我的 URL 还是 v1 的”然后去修正配置。这事说起来很小但在大规模混装环境里几乎每天都会碰到。所以我的建议是如果在同一组目标里出现了“其他节点全绿就某几台全红”的现象先去看 agent 版本是不是一致再去看探测条件是不是按版本分叉了。Agent-Reach 现在已经支持在 group 里配置多个 check 集合并且可以用match_version做条件判断但前提是你的资产数据里有版本信息。没有版本信息就盲目去优化工具配置等于瞎猜。4.3 心跳接口偶发抖动带来的误告警有段时间Agent-Reach 对某一组 Consul 节点探测时HTTP 健康检查经常报 TIMEOUT但 TCP 一直 OK。我熬夜排查了好几次最后发现问题是 Consul 的健康接口在集群 leader 切换期间响应时间会飙到 3 秒以上而我的 timeout 是 2000ms。只要一轮扫描刚好撞上切换窗口就会被判定为 UNREACHABLE。这让我更深刻地体会到超时参数不是一个可以随便拍脑袋决定的数字。短了误报长了拖慢整个扫描批次。Agent-Reach 的解决方案是为 HTTP 请求单独设置一个http_timeout和 TCP 的 timeout 分离。默认情况下 TCP 超时是 2000msHTTP 超时是 5000ms。因为 TCP 握手如果 2 秒都不成功大概率是网络或防火墙问题但 HTTP 请求涉及 agent 内部逻辑可能要做各种校验和状态检查给 5 秒是合理的。如果你碰到偶发超时建议先把http_timeout调宽再观察一轮而不是急着改代码。我把整个扫描结果输出到文件之后再用脚本统计连续三次扫描中的失败率只有连续失败次数超过阈值才触发告警。这种“2-of-3”甚至“3-of-5”的判定模式在真实监控场景里远比“一次失败就告警”靠谱。4.4 扫描窗口与业务高峰重叠最后还有一个很容易被忽视的问题扫描时间窗口。Agent-Reach 默认是“任务开始后立即并发扫”但如果你在业务高峰时段进行大批量扫描哪怕只是建立 TCP 连接、获取一条健康响应也会给数据库、网关带来额外的连接压力。第一次在白天高峰扫了 3000 个 MySQL 节点的 agent 健康接口数据库长连接没爆但网络入口的流量曲线被顶出一个明显尖峰。解决办法其实很土把扫描任务放进 schedule 队列里控制扫描窗口。业务低峰时跑全量高峰时只跑最小必要集。如果一定要在高峰期执行变更验证就把并发砍到 10并且只对变更涉及的目标探测不要顺手把全集群都扫了。Agent-Reach 为此提供了--only参数可以只跑某个 group也可以按主机名过滤。这个能力看起来很简单实际救场率极高。5. 我还会接着往下做的几个小改动工具做到现在基本满足了我自己日常的需求。但有几个方向我觉得还能继续打磨。技术上我准备把延迟直方图输出到文件里配合自研图表工具画一张“延迟分布在哪个区间”的热力图。因为很多时候仅知道快慢是没用的分布形态比平均值更能暴露问题。比如大量节点都在 50ms 内响应突然有 50 个节点在 400ms 以上这种尾部延迟往往预示着 agent 实例的工作负载已经偏高。功能上我也考虑给 Agent-Reach 增加一个“反向探测”模式让探活端不主动连 target而是等 target 上的 agent 反向上报。这样可以在严格隔离网络环境下使用比如只有目标机器能访问探活端探活端无法主动访问目标机器。这种模式下 Agent-Reach 会退化成一台轻量接收端通过定时收心跳来判定可达性。这听起来很美好但需要额外在目标端安装上报脚本和最初“零部署、零依赖”的初心有点冲突所以暂时没做。最后想说的其实是一个很朴素的体会做 tools 的时候不要急着堆功能先把自己的真实流程走一遍哪里疼就先把那里治好。Agent-Reach 从最早只探测 TCP 端口的 100 行代码长到现在支持多协议、多组、并发控制、JSON 输出每一步都是因为实际工作里被某个问题卡住了才把对应能力补上。这套工具现在也还没完全成功但已经足够让我在开周会时说“这批节点我们验证过硬性可达性”而不只是“心跳是绿的”。对长期维护各种 agent 的人来说这就是最踏实的一层底。