我在维护内部这套 AI 能力中台时遇到最头疼的问题不是模型调不通而是“线上到底跑了什么”。Agent 技能注册了三四十个模型端点拆成了大小七八个工具插件还在不断往里加表面看一切正常但注册信息和运行时真实状态经常对不上有的技能包升级了注册中心版本号没变有的技能依赖的外部服务改了连接串注册还显示成功一调用就报错还有一些端口映射在发布时被悄悄改掉网关那边全是黑洞流量。传统监控只能告诉我进程活着、CPU 不高、接口延迟还凑合回答不了“这个技能从 Agent 视角发起调用链路到底通不通、元数据到底准不准、依赖到底健不健康”。后来我把 AI-Infra-Guard 部署到了测试环境用它的技能扫描功能做了一轮全量体检整个过程走下来收获很多也踩了不少坑尤其是中间发生的一次“漏报”让我对这类工具的能力边界有了全新的认识。这篇文章就把部署流程和那次漏报的完整复盘记录下来给同样在做 AI 平台运维、Agent 技能管理和模型服务治理的同学做个参考。AI-Infra-Guard 对我们这种小团队来说核心价值就一句话把分散在注册中心、配置文件、API 网关后面的 AI 技能和模型端点统一扫一遍输出一份可读的健康报告再由人来决定哪些服务要重启、哪些技能要重新注册、哪些配置要修。它不替代 Prometheus 或 Zabbix而是在传统监控覆盖不到的那层“AI 能力可见性”上补位。如果你正在维护 Ollama、vLLM 这类推理服务或者管理着一堆 Agent 技能插件又或者刚把 Docker 环境搭好准备做基础设施治理这篇文章值得你花十分钟看完。1. “技能扫描”和传统监控到底差在哪1.1 注册信息与运行时状态之间的断层AI 基础设施和我们熟悉的 Web 服务有一个显著差异多了一层“注册-发现-调用”的抽象。一个技能开发完成后先要把元数据登记到注册中心网关才能将它暴露给 Agent 调用。这层抽象带来便利的同时也制造了一个盲区——注册成功不代表运行时真的可用。我实际遇到过的情况可以列一堆出来技能包升级了新版本镜像 tag 已经更新注册中心的版本号还停在旧值Agent 拿到的全是旧逻辑。技能依赖的向量数据库连接串被人改过技能在注册表里状态是“正常”但每次调用都卡在初始化阶段。服务发布时容器端口变化了网关配置里却还指向旧端口请求进来直接超时。技能依赖的第三方 API 密钥过期了网关做了错误兜底后返回 200监控端看不出任何异常。这些都是传统监控看不到的。监控看的是“这个进程活着、那个端口在听”但技能扫描要看的是“从 Agent 视角发起一次真实调用是否真的返回了符合预期的内容”。如果进程都活着但链路中间断了一截传统监控只会告诉你“一切正常”而技能扫描能直接指出“哪一个环节是断的”。1.2 AI-Infra-Guard 的三类扫描对象用了一段时间之后我总结出 AI-Infra-Guard 的扫描对象主要分成三类第一类是 AI 技能本身。包括技能包的名称、版本号、入口地址、依赖的服务清单、声明的输入输出 schema。扫这些是为了回答“技能库里到底登记了什么版本对不对接口还在不在”。第二类是模型服务端点。包括本地推理服务、远程 API 网关、流式接口。扫这些是为了回答“模型推理链路是不是通的端点的响应时间是否在合理范围”。第三类是运行时环境。包括 Docker 容器状态、进程健康状态、关键依赖库的版本。扫这些是为了回答“底层环境有没有发生静默变化”。我在选型的时候比较过几款类似工具最后选了 AI-Infra-Guard 主要看中四点支持 Docker 一键起开发机、测试机、生产环境都能快速铺。扫描结果能导出 JSON方便接进自己现有的仪表盘。自定义校验规则是 YAML 配置门槛不算高。支持增量扫描模式日常巡检不会把线上服务打到过载。当然工具只是第一步真正让扫描有价值的是你围绕着业务场景把规则调对。这一点在后文的漏报案例里会体现得淋漓尽致。2. Docker 一键部署拆解我的一份可用 Compose 配置2.1 部署前必须确认的三件事我用的环境是一台 Ubuntu 22.04 的测试服务器4 核 8G上面已经跑了 Docker Engine 24.x 和 Docker Compose v2。如果你的机器还没装 Docker官方脚本一条命令就能装好curl -fsSL https://get.docker.com | sh systemctl enable --now docker docker compose version提示AI-Infra-Guard 镜像对 Docker 版本有要求建议至少 Docker Engine 20.10 以上、Compose v2老版本会出现网络模式兼容问题。正式部署之前我建议先确认三件事别急着拉镜像第一网络互通性。扫描器和被扫描的目标之间必须能互相访问。如果目标服务在其他网段提前配好路由或者放行防火墙端口否则扫描结果会大面积报错还会让你误以为服务都挂了。第二目录规划。我给 AI-Infra-Guard 准备了独立的目录/opt/aig下面分成config和reports两个子目录。配置目录和报告目录分开方便后续备份和排查。第三运行模式。决定扫描器用哪种 Docker 网络模式。如果被扫描服务都在同一个 bridge 网络那直接把 compose 网络指过去就行如果目标服务特别分散可能需要 host 模式。我先在测试环境用 bridge 模式跑通再考虑的复杂场景。2.2 编排文件与关键环境变量AI-Infra-Guard 官方提供 Docker 镜像我用 Compose 管理整个生命周。这是我实际在用的编排文件version: 3.8 services: aig-server: image: aig/ai-infra-guard:latest container_name: ai-infra-guard restart: unless-stopped ports: - 8080:8080 volumes: - /opt/aig/config:/etc/aig/config - /opt/aig/reports:/var/lib/aig/reports environment: - AIG_SCAN_MODEincremental - AIG_SCHEDULE0 2 * * * - AIG_LOG_LEVELinfo - AIG_WEBHOOK_URLhttp://your-alert-system:8080/hook networks: - aig-network networks: aig-network: external: true这里面有几个环境变量值得你重点理解AIG_SCAN_MODEincremental增量扫描模式。只扫描上次执行之后发生变化过的技能适合日常巡检时降低对被扫描服务的影响。首次摸底用 full 全量模式。AIG_SCHEDULE0 2 * * *Cron 表达式我设置在每天凌晨两点执行扫描避开业务高峰。AIG_WEBHOOK_URL扫描完成后向告警系统推送结果的地址。如果暂时没有告警系统可以先用 Echo 服务测试确认数据结构没问题再接正式的。配置文件的挂载很关键。扫描范围、技能定义、模型端点列表都放在/etc/aig/config下的 YAML 文件里。镜像首次启动时如果没有挂载配置目录会用内置默认配置运行但这种状态只能用于验证服务存活真正要上线扫描必须自己写好配置文件再挂进去。2.3 启动、验证与首次扫描部署步骤本身不复杂按顺序执行就行把上面这份 Compose 文件保存为docker-compose.yml。创建配置目录并写好第一份skills.yaml。执行docker compose up -d。用docker logs -f ai-infra-guard观察启动日志。打开http://服务器IP:8080访问 Web 控制台。我第一次启动时踩了个小坑镜像默认把配置目录映射到容器内的只读路径我一开始只挂载了reports漏了config结果服务一直起不来日志里反复提示找不到配置目录。把两个目录都挂好之后容器秒级启动成功。启动完毕后控制台首页会显示扫描任务的状态等待调度、扫描中、扫描完成。我第一次跑全量扫描用了大概三分钟扫了三十个技能加八个模型端点。这个速度在可接受范围内。全量扫描完控制台会生成一份总览报告按技能列表逐条列出健康分数、探针结果和耗时。看到报告那一刻我才真正直观感受到“AI 能力可见性”这个词是什么意思。3. 扫描探针的原理它凭什么判断一个技能“活着”3.1 三种探针的职责与配合AI-Infra-Guard 判断一个技能“是否存在、是否可用”不是去注册表翻记录而是通过三类探针实际探测。理解这三类探针是理解整个工具的前提也是后面排查漏报的基础。存活探针向技能入口发送 HTTP HEAD 或 GET 请求确认端口可通、服务有响应。这部分和传统监控差不多但它关注的是 Agent 实际访问路径不是简单的 ping IP。比如技能暴露在网关后面的路径是/api/skill-translate/invoke存活探针就会请求这个具体路径而不是去探测容器的内部 IP。元数据探针请求技能的元数据接口比如/api/skill/info把返回的 name、version、dependencies 字段和配置文件里登记的预期值做比对。这一步能发现版本漂移和依赖变更。比如配置文件里写的是技能包前一天的版本但实际运行的容器已经换成了新镜像元数据探针会立刻标黄。调用链路探针对技能发起一次最小化的真实调用。比如对翻译类技能发一个最简单的短文本请求确认返回结构符合注册声明。这种探针代价最大但有不可替代的价值它能发现“注册正常、服务正常、但实际调用结果不对”的问题。三种探针在配置里可以组合使用。我对核心技能开满三项对边缘工具只开存活加元数据控制探测开销。3.2 报告评分与三种输出每次扫描结束后AI-Infra-Guard 会生成三份报告我就按它们在控制台里的顺序说技能健康报告逐条列出每个技能的探测结果、响应耗时、错误码。这是最常用的一份日常巡检主要看它。配置漂移报告对比注册元数据和实际运行返回的差异。版本不一致、依赖不在列表里、入口路径变了都会出现在这里。风险评估报告把可疑条目按严重程度分类排列从“建议关注”到“需要立即处理”。评分逻辑是扣分制每个技能的初始分是 100存活失败扣 30元数据不匹配扣 40调用链失败扣 50可叠加。分数低于 60 的进入“疑似不可用”名单低于 30 的标红。这种打分的优点是稳定且可解释不像有些系统用玄学权重算出一个让谁都看不懂的数字。我第一次跑完整份报告大部分技能是 90 分以上绿色一片。但有个翻译技能让我非常意外报告显示它 100 分健康三项探针全部通过可是线上真就有人反馈频繁超时。这个“绿标技能实际不可用”的情况就是标题里说的那次漏报。下面完整复盘。4. 一次“漏报”的完整复盘绿标技能为何实际不可用4.1 现象报告 100 分线上却在超时那天早上十点多业务同学在群里反馈翻译技能经常超时有时候点一下要等十几秒才出结果。我第一反应是打开 AI-Infra-Guard 控制台查看昨晚的全量扫描报告。结果让我一愣这个技能的状态是健康的评分 100三项探针全部通过报告里显示“调用链路探针状态 200耗时 2800ms”。注意这个耗时2800 毫秒。它已经不是一个健康服务该有的响应速度但因为阈值默认是 5 秒所以探针判定为通过。我当时没多想先手动用 curl 验证了一下这个技能的真实情况curl -X POST http://gateway/skill-translate/invoke \ -H Content-Type: application/json \ -d {text:hello,target:zh}等了很久返回了一个带deprecated: true字段的兜底错误。这个技能的实际调用链路已经出了问题但扫描报告认为它一切正常。这就是一次典型的“漏报”真实故障存在工具没有识别出来。4.2 排查链路从配置到网关再到抓包遇到“判定正常但实际异常”的情况我第一反应是扫描器探测的地址和我手动请求的地址到底是不是同一个于是开始逐层排查。第一步核查配置文件中的技能地址。打开skills.yaml这个技能登记的入口是http://skill-translate:8000/invoke这是 Docker 容器网络内部的地址。而我手动 curl 用的地址是http://gateway/skill-translate/invoke经过了一次 API 网关转发。中间隔着一层网关问题很可能就出在这个环节。第二步翻扫描日志看探针到底访问了哪个地址。AI-Infra-Guard 的日志会记录每个探针的完整请求路径和响应。我看到存活探针和元数据探针访问的是容器网络内部的skill-translate:8000返回 200一切正常。调用链路探针走的却是网关地址日志里只有一行probe: invoke skill-translate, target: http://gateway/skill-translate/invoke, status: 200, elapsed: 2800ms这里藏着一个关键细节调用链路探针走了网关耗时 2800ms远高于其他探针的几十毫秒。也就是说探针确实发现了异常迹象——慢但因为结果还是 200被放过了。第三步在网关容器上抓包看真实返回内容。为了搞清这 2800ms 里发生了什么我进入网关容器抓包。结果发现请求确实到达了网关网关也向后端发起了调用但后端翻译服务依赖的第三方 API 密钥过期了一直在重试最后在超时前返回了一个兜底响应。这个兜底响应的 HTTP 状态码是 200JSON 结构里也有预期的result字段只是在内部多了一个deprecated: true的标记。网关直接把后端这个 200 响应原样返回了整个链路看起来是通的。4.3 根因拆解与修复思路问题归结下来是三层叠加的结果外层网关对后端错误做了“200 化”兜底处理把真实的密钥过期错误包装成了一路正常的成功响应。中层AI-Infra-Guard 的调用链路探针默认只校验两件事HTTP 状态码是 200返回 JSON 包含预期的result字段。它不检查字段语义自然发现不了deprecated: true这个隐藏的失败信号。内层翻译服务依赖的第三方 API 密钥过期才是根本故障。没有密钥服务每次调用只能重试到超时然后返回一个“看起来成功”的错误。修复分两步。第一步给 AI-Infra-Guard 加一条自定义校验规则把“返回内容里deprecated字段不能为 true”作为这条技能的强制健康条件。配置写法如下response_validators: - name: translate-deprecated-check target: http://gateway/skill-translate/invoke jsonpath: $.deprecated expected: false这条规则表达的意思是如果调用返回的 JSON 中deprecated字段为true就直接判定这个技能异常。加完规则重新触发扫描果然这个技能的评分从 100 掉到了 40控制台标红告警也随之触发。第二步更换翻译服务的第三方 API 密钥并把重试参数调低减少无效重试。密钥换好后再跑一次扫描状态恢复正常。4.4 修复后的验证与新的认知修复完成后我没有立刻把这条规则删掉而是保留在配置里让它继续作为这个技能的长期健康标准。之后连续几天观察没有出现新的误报。这次漏报给我一个很深的教训探针的“通过”只代表“你的服务满足了你定义的健康标准”不代表“服务真的健康”。健康标准本身是否完备取决于你对业务失败信号的理解。像deprecated这种业务层面的标记、慢响应、重试次数、甚至返回内容的长度阈值往往比一个简单的 200 状态码更有诊断价值。所以我现在对 AI-Infra-Guard 的态度是它是一面放大镜帮你把不可见的链路问题暴露出来但放大镜的倍率、焦距和观察角度必须由你根据业务特征自己调。工具给的是框架规则给的是灵魂。5. 技能扫描器落地使用的几条实操经验5.1 先做小范围试点再做全量扫描我强烈建议初次使用 AI-Infra-Guard 的时候不要一上来就扫全量服务。我第一次跑全量扫描前只想着“越快摸底越好”但调用链路探针会真实触发技能的调用逻辑。如果某个技能有副作用比如调用后会发通知、写数据库、调外部接口全量扫描可能造成生产环境的意外影响。我后来把调度时间改到凌晨并且对写操作类技能只开存活和元数据探针调用链路探针只留给只读类技能。这个取舍很重要。5.2 元数据比对要做成每日必扫项版本漂移这类问题靠人眼盯是盯不住的。那次技能包升级后注册中心版本号没跟着变的经历让我发现这类问题往往要过两三天才会被业务反馈发现。把元数据比对纳入每日扫描后版本不一致会在当天报告里标黄。有了自动化的“每日对账”团队在技能发布时也会养成顺手更新注册信息的习惯。这就形成了正面循环。5.3 扫描结果接进告警链路否则等于白扫AI-Infra-Guard 的 Web 控制台适合人来看但人不可能 24 小时盯着。我把它的 Webhook 接到了团队的告警系统凡是评分低于 60 的扫描项自动生成告警。如果你的团队还没有正式的告警平台直接让 Webhook 打到群里也可以本质就是一个 JSON POST 的推送。关键是要让“扫描发现异常”这件事能够主动触达负责的人而不是等下次登录控制台才看到。5.4 维护自定义校验规则的节奏漏报复盘之后我养成了一个习惯每次扫描报告生成后随机抽两三个“绿色”高分项手动调一次接口验证一下。不为别的就想确认“绿色是真的绿”。另外业务逻辑变化后旧的校验规则可能就不再适用了。比如某个技能改了返回格式以前写的 JSONPath 规则就得同步更新。这个复查频率不用太高每周一次每次用得了十几分钟能帮你挡住不少隐藏问题。最后分享一个部署过程中的小验证方法。AI-Infra-Guard 连不上目标服务的时候很多人第一反应是查防火墙其实更常见的原因是容器网络模型不一致。我后来习惯了在正式扫描前先手动进扫描容器里 curl 一下目标地址docker exec ai-infra-guard curl -s -o /dev/null -w %{http_code} http://skill-translate:8000/health如果能返回 200再去查配置和校验规则如果连不通先解决网络连通性不要急着改动校验规则。这样能省下大量无效排查时间。回过头看整个部署和使用的过程AI-Infra-Guard 帮我做的核心事情是把每天手工巡检的技能状态检查变成了凌晨两点自动执行的一份报告。但让它真正有价值的不是工具本身而是那次漏报之后我对校验规则的持续打磨。只要我们还用“健康标准”来定义扫描器漏报和误报就永远存在关键是每次发现边界之后能不能把它固化成一个新的规则条件让下一次扫描变得更敏锐。
我在维护内部这套 AI 能力中台时遇到最头疼的问题不是模型调不通而是“线上到底跑了什么”。Agent 技能注册了三四十个模型端点拆成了大小七八个工具插件还在不断往里加表面看一切正常但注册信息和运行时真实状态经常对不上有的技能包升级了注册中心版本号没变有的技能依赖的外部服务改了连接串注册还显示成功一调用就报错还有一些端口映射在发布时被悄悄改掉网关那边全是黑洞流量。传统监控只能告诉我进程活着、CPU 不高、接口延迟还凑合回答不了“这个技能从 Agent 视角发起调用链路到底通不通、元数据到底准不准、依赖到底健不健康”。后来我把 AI-Infra-Guard 部署到了测试环境用它的技能扫描功能做了一轮全量体检整个过程走下来收获很多也踩了不少坑尤其是中间发生的一次“漏报”让我对这类工具的能力边界有了全新的认识。这篇文章就把部署流程和那次漏报的完整复盘记录下来给同样在做 AI 平台运维、Agent 技能管理和模型服务治理的同学做个参考。AI-Infra-Guard 对我们这种小团队来说核心价值就一句话把分散在注册中心、配置文件、API 网关后面的 AI 技能和模型端点统一扫一遍输出一份可读的健康报告再由人来决定哪些服务要重启、哪些技能要重新注册、哪些配置要修。它不替代 Prometheus 或 Zabbix而是在传统监控覆盖不到的那层“AI 能力可见性”上补位。如果你正在维护 Ollama、vLLM 这类推理服务或者管理着一堆 Agent 技能插件又或者刚把 Docker 环境搭好准备做基础设施治理这篇文章值得你花十分钟看完。1. “技能扫描”和传统监控到底差在哪1.1 注册信息与运行时状态之间的断层AI 基础设施和我们熟悉的 Web 服务有一个显著差异多了一层“注册-发现-调用”的抽象。一个技能开发完成后先要把元数据登记到注册中心网关才能将它暴露给 Agent 调用。这层抽象带来便利的同时也制造了一个盲区——注册成功不代表运行时真的可用。我实际遇到过的情况可以列一堆出来技能包升级了新版本镜像 tag 已经更新注册中心的版本号还停在旧值Agent 拿到的全是旧逻辑。技能依赖的向量数据库连接串被人改过技能在注册表里状态是“正常”但每次调用都卡在初始化阶段。服务发布时容器端口变化了网关配置里却还指向旧端口请求进来直接超时。技能依赖的第三方 API 密钥过期了网关做了错误兜底后返回 200监控端看不出任何异常。这些都是传统监控看不到的。监控看的是“这个进程活着、那个端口在听”但技能扫描要看的是“从 Agent 视角发起一次真实调用是否真的返回了符合预期的内容”。如果进程都活着但链路中间断了一截传统监控只会告诉你“一切正常”而技能扫描能直接指出“哪一个环节是断的”。1.2 AI-Infra-Guard 的三类扫描对象用了一段时间之后我总结出 AI-Infra-Guard 的扫描对象主要分成三类第一类是 AI 技能本身。包括技能包的名称、版本号、入口地址、依赖的服务清单、声明的输入输出 schema。扫这些是为了回答“技能库里到底登记了什么版本对不对接口还在不在”。第二类是模型服务端点。包括本地推理服务、远程 API 网关、流式接口。扫这些是为了回答“模型推理链路是不是通的端点的响应时间是否在合理范围”。第三类是运行时环境。包括 Docker 容器状态、进程健康状态、关键依赖库的版本。扫这些是为了回答“底层环境有没有发生静默变化”。我在选型的时候比较过几款类似工具最后选了 AI-Infra-Guard 主要看中四点支持 Docker 一键起开发机、测试机、生产环境都能快速铺。扫描结果能导出 JSON方便接进自己现有的仪表盘。自定义校验规则是 YAML 配置门槛不算高。支持增量扫描模式日常巡检不会把线上服务打到过载。当然工具只是第一步真正让扫描有价值的是你围绕着业务场景把规则调对。这一点在后文的漏报案例里会体现得淋漓尽致。2. Docker 一键部署拆解我的一份可用 Compose 配置2.1 部署前必须确认的三件事我用的环境是一台 Ubuntu 22.04 的测试服务器4 核 8G上面已经跑了 Docker Engine 24.x 和 Docker Compose v2。如果你的机器还没装 Docker官方脚本一条命令就能装好curl -fsSL https://get.docker.com | sh systemctl enable --now docker docker compose version提示AI-Infra-Guard 镜像对 Docker 版本有要求建议至少 Docker Engine 20.10 以上、Compose v2老版本会出现网络模式兼容问题。正式部署之前我建议先确认三件事别急着拉镜像第一网络互通性。扫描器和被扫描的目标之间必须能互相访问。如果目标服务在其他网段提前配好路由或者放行防火墙端口否则扫描结果会大面积报错还会让你误以为服务都挂了。第二目录规划。我给 AI-Infra-Guard 准备了独立的目录/opt/aig下面分成config和reports两个子目录。配置目录和报告目录分开方便后续备份和排查。第三运行模式。决定扫描器用哪种 Docker 网络模式。如果被扫描服务都在同一个 bridge 网络那直接把 compose 网络指过去就行如果目标服务特别分散可能需要 host 模式。我先在测试环境用 bridge 模式跑通再考虑的复杂场景。2.2 编排文件与关键环境变量AI-Infra-Guard 官方提供 Docker 镜像我用 Compose 管理整个生命周。这是我实际在用的编排文件version: 3.8 services: aig-server: image: aig/ai-infra-guard:latest container_name: ai-infra-guard restart: unless-stopped ports: - 8080:8080 volumes: - /opt/aig/config:/etc/aig/config - /opt/aig/reports:/var/lib/aig/reports environment: - AIG_SCAN_MODEincremental - AIG_SCHEDULE0 2 * * * - AIG_LOG_LEVELinfo - AIG_WEBHOOK_URLhttp://your-alert-system:8080/hook networks: - aig-network networks: aig-network: external: true这里面有几个环境变量值得你重点理解AIG_SCAN_MODEincremental增量扫描模式。只扫描上次执行之后发生变化过的技能适合日常巡检时降低对被扫描服务的影响。首次摸底用 full 全量模式。AIG_SCHEDULE0 2 * * *Cron 表达式我设置在每天凌晨两点执行扫描避开业务高峰。AIG_WEBHOOK_URL扫描完成后向告警系统推送结果的地址。如果暂时没有告警系统可以先用 Echo 服务测试确认数据结构没问题再接正式的。配置文件的挂载很关键。扫描范围、技能定义、模型端点列表都放在/etc/aig/config下的 YAML 文件里。镜像首次启动时如果没有挂载配置目录会用内置默认配置运行但这种状态只能用于验证服务存活真正要上线扫描必须自己写好配置文件再挂进去。2.3 启动、验证与首次扫描部署步骤本身不复杂按顺序执行就行把上面这份 Compose 文件保存为docker-compose.yml。创建配置目录并写好第一份skills.yaml。执行docker compose up -d。用docker logs -f ai-infra-guard观察启动日志。打开http://服务器IP:8080访问 Web 控制台。我第一次启动时踩了个小坑镜像默认把配置目录映射到容器内的只读路径我一开始只挂载了reports漏了config结果服务一直起不来日志里反复提示找不到配置目录。把两个目录都挂好之后容器秒级启动成功。启动完毕后控制台首页会显示扫描任务的状态等待调度、扫描中、扫描完成。我第一次跑全量扫描用了大概三分钟扫了三十个技能加八个模型端点。这个速度在可接受范围内。全量扫描完控制台会生成一份总览报告按技能列表逐条列出健康分数、探针结果和耗时。看到报告那一刻我才真正直观感受到“AI 能力可见性”这个词是什么意思。3. 扫描探针的原理它凭什么判断一个技能“活着”3.1 三种探针的职责与配合AI-Infra-Guard 判断一个技能“是否存在、是否可用”不是去注册表翻记录而是通过三类探针实际探测。理解这三类探针是理解整个工具的前提也是后面排查漏报的基础。存活探针向技能入口发送 HTTP HEAD 或 GET 请求确认端口可通、服务有响应。这部分和传统监控差不多但它关注的是 Agent 实际访问路径不是简单的 ping IP。比如技能暴露在网关后面的路径是/api/skill-translate/invoke存活探针就会请求这个具体路径而不是去探测容器的内部 IP。元数据探针请求技能的元数据接口比如/api/skill/info把返回的 name、version、dependencies 字段和配置文件里登记的预期值做比对。这一步能发现版本漂移和依赖变更。比如配置文件里写的是技能包前一天的版本但实际运行的容器已经换成了新镜像元数据探针会立刻标黄。调用链路探针对技能发起一次最小化的真实调用。比如对翻译类技能发一个最简单的短文本请求确认返回结构符合注册声明。这种探针代价最大但有不可替代的价值它能发现“注册正常、服务正常、但实际调用结果不对”的问题。三种探针在配置里可以组合使用。我对核心技能开满三项对边缘工具只开存活加元数据控制探测开销。3.2 报告评分与三种输出每次扫描结束后AI-Infra-Guard 会生成三份报告我就按它们在控制台里的顺序说技能健康报告逐条列出每个技能的探测结果、响应耗时、错误码。这是最常用的一份日常巡检主要看它。配置漂移报告对比注册元数据和实际运行返回的差异。版本不一致、依赖不在列表里、入口路径变了都会出现在这里。风险评估报告把可疑条目按严重程度分类排列从“建议关注”到“需要立即处理”。评分逻辑是扣分制每个技能的初始分是 100存活失败扣 30元数据不匹配扣 40调用链失败扣 50可叠加。分数低于 60 的进入“疑似不可用”名单低于 30 的标红。这种打分的优点是稳定且可解释不像有些系统用玄学权重算出一个让谁都看不懂的数字。我第一次跑完整份报告大部分技能是 90 分以上绿色一片。但有个翻译技能让我非常意外报告显示它 100 分健康三项探针全部通过可是线上真就有人反馈频繁超时。这个“绿标技能实际不可用”的情况就是标题里说的那次漏报。下面完整复盘。4. 一次“漏报”的完整复盘绿标技能为何实际不可用4.1 现象报告 100 分线上却在超时那天早上十点多业务同学在群里反馈翻译技能经常超时有时候点一下要等十几秒才出结果。我第一反应是打开 AI-Infra-Guard 控制台查看昨晚的全量扫描报告。结果让我一愣这个技能的状态是健康的评分 100三项探针全部通过报告里显示“调用链路探针状态 200耗时 2800ms”。注意这个耗时2800 毫秒。它已经不是一个健康服务该有的响应速度但因为阈值默认是 5 秒所以探针判定为通过。我当时没多想先手动用 curl 验证了一下这个技能的真实情况curl -X POST http://gateway/skill-translate/invoke \ -H Content-Type: application/json \ -d {text:hello,target:zh}等了很久返回了一个带deprecated: true字段的兜底错误。这个技能的实际调用链路已经出了问题但扫描报告认为它一切正常。这就是一次典型的“漏报”真实故障存在工具没有识别出来。4.2 排查链路从配置到网关再到抓包遇到“判定正常但实际异常”的情况我第一反应是扫描器探测的地址和我手动请求的地址到底是不是同一个于是开始逐层排查。第一步核查配置文件中的技能地址。打开skills.yaml这个技能登记的入口是http://skill-translate:8000/invoke这是 Docker 容器网络内部的地址。而我手动 curl 用的地址是http://gateway/skill-translate/invoke经过了一次 API 网关转发。中间隔着一层网关问题很可能就出在这个环节。第二步翻扫描日志看探针到底访问了哪个地址。AI-Infra-Guard 的日志会记录每个探针的完整请求路径和响应。我看到存活探针和元数据探针访问的是容器网络内部的skill-translate:8000返回 200一切正常。调用链路探针走的却是网关地址日志里只有一行probe: invoke skill-translate, target: http://gateway/skill-translate/invoke, status: 200, elapsed: 2800ms这里藏着一个关键细节调用链路探针走了网关耗时 2800ms远高于其他探针的几十毫秒。也就是说探针确实发现了异常迹象——慢但因为结果还是 200被放过了。第三步在网关容器上抓包看真实返回内容。为了搞清这 2800ms 里发生了什么我进入网关容器抓包。结果发现请求确实到达了网关网关也向后端发起了调用但后端翻译服务依赖的第三方 API 密钥过期了一直在重试最后在超时前返回了一个兜底响应。这个兜底响应的 HTTP 状态码是 200JSON 结构里也有预期的result字段只是在内部多了一个deprecated: true的标记。网关直接把后端这个 200 响应原样返回了整个链路看起来是通的。4.3 根因拆解与修复思路问题归结下来是三层叠加的结果外层网关对后端错误做了“200 化”兜底处理把真实的密钥过期错误包装成了一路正常的成功响应。中层AI-Infra-Guard 的调用链路探针默认只校验两件事HTTP 状态码是 200返回 JSON 包含预期的result字段。它不检查字段语义自然发现不了deprecated: true这个隐藏的失败信号。内层翻译服务依赖的第三方 API 密钥过期才是根本故障。没有密钥服务每次调用只能重试到超时然后返回一个“看起来成功”的错误。修复分两步。第一步给 AI-Infra-Guard 加一条自定义校验规则把“返回内容里deprecated字段不能为 true”作为这条技能的强制健康条件。配置写法如下response_validators: - name: translate-deprecated-check target: http://gateway/skill-translate/invoke jsonpath: $.deprecated expected: false这条规则表达的意思是如果调用返回的 JSON 中deprecated字段为true就直接判定这个技能异常。加完规则重新触发扫描果然这个技能的评分从 100 掉到了 40控制台标红告警也随之触发。第二步更换翻译服务的第三方 API 密钥并把重试参数调低减少无效重试。密钥换好后再跑一次扫描状态恢复正常。4.4 修复后的验证与新的认知修复完成后我没有立刻把这条规则删掉而是保留在配置里让它继续作为这个技能的长期健康标准。之后连续几天观察没有出现新的误报。这次漏报给我一个很深的教训探针的“通过”只代表“你的服务满足了你定义的健康标准”不代表“服务真的健康”。健康标准本身是否完备取决于你对业务失败信号的理解。像deprecated这种业务层面的标记、慢响应、重试次数、甚至返回内容的长度阈值往往比一个简单的 200 状态码更有诊断价值。所以我现在对 AI-Infra-Guard 的态度是它是一面放大镜帮你把不可见的链路问题暴露出来但放大镜的倍率、焦距和观察角度必须由你根据业务特征自己调。工具给的是框架规则给的是灵魂。5. 技能扫描器落地使用的几条实操经验5.1 先做小范围试点再做全量扫描我强烈建议初次使用 AI-Infra-Guard 的时候不要一上来就扫全量服务。我第一次跑全量扫描前只想着“越快摸底越好”但调用链路探针会真实触发技能的调用逻辑。如果某个技能有副作用比如调用后会发通知、写数据库、调外部接口全量扫描可能造成生产环境的意外影响。我后来把调度时间改到凌晨并且对写操作类技能只开存活和元数据探针调用链路探针只留给只读类技能。这个取舍很重要。5.2 元数据比对要做成每日必扫项版本漂移这类问题靠人眼盯是盯不住的。那次技能包升级后注册中心版本号没跟着变的经历让我发现这类问题往往要过两三天才会被业务反馈发现。把元数据比对纳入每日扫描后版本不一致会在当天报告里标黄。有了自动化的“每日对账”团队在技能发布时也会养成顺手更新注册信息的习惯。这就形成了正面循环。5.3 扫描结果接进告警链路否则等于白扫AI-Infra-Guard 的 Web 控制台适合人来看但人不可能 24 小时盯着。我把它的 Webhook 接到了团队的告警系统凡是评分低于 60 的扫描项自动生成告警。如果你的团队还没有正式的告警平台直接让 Webhook 打到群里也可以本质就是一个 JSON POST 的推送。关键是要让“扫描发现异常”这件事能够主动触达负责的人而不是等下次登录控制台才看到。5.4 维护自定义校验规则的节奏漏报复盘之后我养成了一个习惯每次扫描报告生成后随机抽两三个“绿色”高分项手动调一次接口验证一下。不为别的就想确认“绿色是真的绿”。另外业务逻辑变化后旧的校验规则可能就不再适用了。比如某个技能改了返回格式以前写的 JSONPath 规则就得同步更新。这个复查频率不用太高每周一次每次用得了十几分钟能帮你挡住不少隐藏问题。最后分享一个部署过程中的小验证方法。AI-Infra-Guard 连不上目标服务的时候很多人第一反应是查防火墙其实更常见的原因是容器网络模型不一致。我后来习惯了在正式扫描前先手动进扫描容器里 curl 一下目标地址docker exec ai-infra-guard curl -s -o /dev/null -w %{http_code} http://skill-translate:8000/health如果能返回 200再去查配置和校验规则如果连不通先解决网络连通性不要急着改动校验规则。这样能省下大量无效排查时间。回过头看整个部署和使用的过程AI-Infra-Guard 帮我做的核心事情是把每天手工巡检的技能状态检查变成了凌晨两点自动执行的一份报告。但让它真正有价值的不是工具本身而是那次漏报之后我对校验规则的持续打磨。只要我们还用“健康标准”来定义扫描器漏报和误报就永远存在关键是每次发现边界之后能不能把它固化成一个新的规则条件让下一次扫描变得更敏锐。
