1. 从一次“漏报”说起我为什么需要 AI-Infra-Guard先说背景。接手这套基础设施巡检工作之前我手里的“家当”是一堆散落的脚本和定时任务有的脚本盯着 CPU 和内存有的脚本检查磁盘余量还有几个用 Python 写的接口连通性检测各自为政互不通信。日常跑起来还算能忍但有两个问题让我越来越头疼。第一告警规则分散在每个脚本里想调整阈值得翻遍所有文件第二脚本能覆盖的检查项有限很多环境层面的异常——比如容器内进程偷偷退出、GPU 显存泄漏、模型服务端口假死——根本没人管。尤其是后者真要出事往往是在半夜用户反馈比监控告警还快。当时正好在给一个内部推理平台做稳定性改造业务方要求新增“服务技能状态扫描”不仅要看节点活没活还要看节点上的原始能力、已激活技能、正在运行的模型服务是否匹配预期。传统监控代理干不了这种偏向业务语义的检查因为它只管指标不管“你该有什么、实际有什么、缺了什么”。我翻了一圈开源方案最后盯上了 AI-Infra-Guard——一套面向 AI 基础设施的轻量守护工具内置了节点注册、技能定义、巡检扫描和告警输出能力而且官方提供了 Docker 一键启动方式。这篇博文就把我的部署过程、技能扫描逻辑拆解、以及一次差点酿成大祸的“漏报”复盘完整写出来。适合谁看正在维护推理服务、训练集群或者 GPU 节点的同学被各种监控脚本折磨、想找一个更结构化的巡检框架的人以及所有打算在自己环境里跑 AI-Infra-Guard 但还没摸清它的坑的朋友。我会把命令、配置、踩坑点都摊开来讲不藏着掖着。2. 部署前必须搞懂的两件事核心组件与技能扫描的设计思路2.1 核心组件Agent、Scanner、Reporter 各管什么开始敲 docker run 之前最好先把 AI-Infra-Guard 的组件模型捋清楚。它不是一个单体服务而是由三个角色配合完成工作Agent部署在每台被纳管节点上负责上报节点状态、执行本地检查命令并把结果回传给中心端。Scanner中心端的扫描引擎它读取节点上报的信息匹配“技能定义”中声明的能力清单再结合运行时状态生成扫描结果。Reporter负责把扫描结果写到存储、触发告警或推送通知是整个工具的出口。这套设计和很多监控系统不太一样。传统监控是“你问我答”——监控端主动拉取节点的 CPU、内存、磁盘指标而 AI-Infra-Guard 更像“你报我判”——节点上的 Agent 主动上报自己的能力和状态中心端 Scanner 负责判断“上报的状态是否符合预期”。好处是节点离线时中心端能立刻感知而不是等拉取超时才怀疑节点挂了。坏处是如果 Agent 本身逻辑写得太轻上报的信息不完整Scanner 就容易“漏判”——这正是后面我要复盘的那次漏报的根源。2.2 技能扫描到底扫的是什么技能扫描这个功能是 AI-Infra-Guard 区别于普通监控工具的最大亮点。它的设计初衷是AI 基础设施上跑的不只是进程而是一个个“技能”——比如文本向量化、目标检测、对话生成、音频转写等。每个技能依赖特定的模型文件、运行时版本、端口和环境变量。传统的“端口存活检查”只能确认服务响应了却无法确认这个服务是不是你期望的那个模型、那个版本。技能扫描做的就是“能力契约校验”。你在节点上声明一个技能需要写明技能名称例如 text-embedding模型标识例如 BAAI/bge-large-zh-v1.5服务协议例如 HTTP监听端口例如 8000健康检查路径例如 /health校验命令例如 curl 或者自定义 Python 探针Scanner 拿到 Agent 上报的进程、端口、模型加载信息后逐一和技能定义比对。匹配上了技能状态为 healthy某个维度不匹配状态变成 degraded完全找不到对应进程或端口未监听状态就是 down。这样设计的好处很明显当你更新了模型版本但忘了更新技能定义中的模型标识扫描结果立刻会显示不匹配从而提醒你“线上模型和预期模型不一致”。这种校验粒度用传统监控脚本去实现非常痛苦——你得自己维护端口到模型的映射表还得处理进程重启后的动态端口变化。2.3 为什么用 Docker 一键起是当前最省心的方案AI-Infra-Guard 支持源码部署和 Docker 部署两种方式。源码部署要求 Python 3.9、Redis、PostgreSQL还要手动初始化数据库表结构对新手不太友好。Docker 部署则把依赖全部打包进镜像只需要映射端口和挂载数据目录就行适合快速验证和灰度环境。我选择 Docker 还有一个原因AI-Infra-Guard 自带一个 Web 控制台和一套数据库迁移脚本Docker Compose 编排能让这些组件的启动顺序自动处理好——先启动数据库和消息队列等它们就绪后再启动 Scanner 和 Reporter避免手工启动时常见的“库还没建好就连接失败”的问题。在生产环境做快速扩容时Docker 的副本机制也能让我们在几秒内拉起来一个新的 Scanner 实例。3. Docker 一键部署实战从拉镜像到控制台可用3.1 环境准备宿主机需要什么先交代一下我用的环境方便大家对照操作系统Ubuntu 22.04 LTSDocker Engine24.0.xDocker Compose v2.20内存8GBAI-Infra-Guard 控制台和数据库加起来约 1.5GB其余留给被纳管节点磁盘20GB 以上空闲空间镜像、日志、扫描结果存储都需要空间如果你的宿主机是 Windows建议先在 Docker Desktop 里把资源调大一点因为后续如果跑多个 Agent 模拟节点内存吃紧会导致容器 OOM。我这边是 Linux 服务器直接用命令行操作。3.2 初始化目录和配置文件部署前创建一个工作目录把 compose 文件和配置模板放进去方便维护mkdir -p /opt/aig cd /opt/aig接下来从官方仓库获取最新发布版本。我这里不贴 git clone 的完整地址了因为版本迭代快大家直接去仓库 Release 页面下载对应的 docker-compose.yml 和 .env.example 即可。下载后cp .env.example .env编辑 .env 里的关键参数AIG_DB_PASSWORDyour-strong-password AIG_REDIS_PASSWORDyour-redis-password AIG_SCANNER_INTERVAL60这里的 SCANNER_INTERVAL 是扫描间隔单位秒。我一开始设的 30结果日志刷得太快数据库写入压力也不小后来改成 60 就舒服多了。对于技能扫描这种带业务语义的检查60 秒完全够用毕竟模型服务状态不会在几十秒内频繁变化。3.3 用 Compose 拉起整套服务确认配置无误后执行docker compose up -d第一次启动会拉取镜像取决于网络环境可能需要几分钟。镜像包括ai-infra-guard/scanner扫描引擎ai-infra-guard/reporter结果上报与告警ai-infra-guard/console-webWeb 控制台postgres:15元数据存储redis:7缓存和队列启动完成后查看容器状态docker compose ps正常情况下所有容器的状态都是 Up。然后访问 http://服务器IP:8080 打开控制台。首次登录需要初始化管理员账号按页面提示填写邮箱和密码即可。这里有一个我踩过的坑如果服务器有防火墙记得放行 8080 端口。否则控制台打不开但容器日志里不会报错很容易让人以为是数据库没起来。初始化管理员账号后进入控制台首页你会看到节点列表是空的扫描任务也是空的。不要慌这是正常的——Nagios 那种工具装完自带一堆 checkAI-Infra-Guard 则是“裸奔”状态所有检查项都需要你根据真实环境去声明。这也呼应了它的设计哲学技能定义应该是业务相关而不是内置一刀切。3.4 容器日志检查确认各组件正常通信部署完不能只看容器状态还得确认内部通信正常。查看 scanner 日志docker compose logs -f scanner正常日志会周期性打印类似 “scan completed” 的记录。如果出现连接 Redis 或 Postgres 失败的信息多半是 .env 里的密码没对上。另外reporter 日志里不应出现“ack timeout”之类的错误否则说明控制台和 reporter 之间的消息通道没打通。3.5 节点 Agent 注册让 Scanner 看得见你的机器AI-Infra-Guard 默认不会自动发现节点需要你手动在每台节点上安装 Agent。Agent 安装很简单在节点上执行控制台生成的安装命令或者用容器方式启动docker run -d --name aig-agent --restartalways \ -e AIG_CENTER_ADDRhttp://中心端IP:9000 \ -e AIG_NODE_NAMEworker-01 \ -e AIG_TOKEN控制台生成的节点令牌 \ ai-infra-guard/agent:latest启动后回到控制台刷新节点页面就能看到 worker-01 出现在列表里状态为 online。到这里部署部分基本收工。接下来进入核心环节技能扫描的配置和实战。4. 技能扫描实战定义技能、下发扫描、解读结果4.1 一个真实的扫描任务检测一个文本向量化服务我在 worker-01 节点上跑了一个文本向量化服务容器映射端口 8000健康检查路径是 /health。为了让 AI-Infra-Guard 认得它需要在控制台“技能管理”页面新增一个技能定义字段名值说明技能名称text-embedding全局唯一模型标识BAAI/bge-large-zh-v1.5用于比对模型版本服务协议HTTP目前支持 HTTP 和 TCP监听端口8000实际监听端口健康检查路径/health返回 200 即视为存活存活判定超时5 秒超过则判定请求失败保存后AI-Infra-Guard 会在下一个扫描周期把任务下发给 scanner。Scanner 会尝试连接 worker-01 的 8000 端口请求 /health并对比响应内容中携带的模型标识。这里告诉大家一个小技巧为了减少误判建议健康检查路径不要只返回 “ok” 这种静态字符串最好让服务在响应里带上模型名称。我写了个轻量的探针脚本放在服务的启动命令里返回 JSON 包含 model 字段{status: alive, model: BAAI/bge-large-zh-v1.5}AI-Infra-Guard 支持在技能定义中指定“响应内容匹配关键字”我填了 BAAI/bge-large-zh-v1.5。这样即使端口通着只要模型加载错了扫描结果也会被标记为 degraded。4.2 扫描结果解读healthy、degraded、down 三态扫描完成后在控制台“扫描记录”页面可以看到每次任务的结果摘要。三个状态分别对应healthy端口通、健康检查通过、响应内容与预期模型匹配。这是理想状态。degraded端口通了健康检查也返回 200但响应内容里的模型标识和技能定义不一致。典型场景是你更新了模型版本但技能定义没同步更新。down端口不通或者健康检查请求超时或者进程根本不存在。可能是容器崩了、节点宕了、或者网络不通。不要小看 degraded 状态。在一次真实事故里我遇到的是“端口通、进程活、但模型因 OOM 退化和回退到了基础版本”响应里的 model 字段变成了 fallback-model。传统监控完全看不出问题因为 TCP 和 HTTP 都正常。而技能扫描一眼就抓到了模型标识不匹配帮我避免了一次特征向量维度错误导致的检索结果异常。这也是我用这个工具最大的收获。4.3 充实技能库从单技能到全链路覆盖跑通一个技能之后我把平台上其他关键服务也都纳了进来。目前库里一共 9 个技能text-embedding文本向量化object-detection目标检测推理chat-completion对话生成audio-transcription音频转写image-generation图像生成vector-search向量检索model-registry模型仓库服务auth-service统一鉴权api-gateway网关每个技能的定义思路一样但注意别把健康检查路径写成静态页面那种路径。比如 object-detection 的 /health 路径我用的是一个空请求也能返回 200 的探针接口避免因为输入校验失败导致误报 down。这个细节如果忽略你会在凌晨三点收到的告警里看到一堆假阳性。扫描任务我改成了每 60 秒一轮并且开启了“连续三次异常才告警”的策略避免瞬时网络抖动导致告警轰炸。这个策略在“告警管理”里配属于 AI-Infra-Guard 比较贴心的设计——虽然工具具备实时扫描能力但异常容忍策略能显著提升告警的有效性。5. 器材归因一次“漏报”复盘问题出在哪5.1 事故回放服务挂了扫描结果却显示 healthy就在我完成技能定义全覆盖后的大约一周半夜两点业务方反馈文本向量化服务响应超时。我赶紧打开 AI-Infra-Guard 控制台结果吓了一跳技能扫描记录里 text-embedding 的状态依然是 healthy而且最近 20 轮扫描全部通过。但实际调用明明已经超时了这不就是标准的“漏报”吗第一反应是工具不可靠差点想换回传统监控。但冷静下来我把 Agent 的本地日志调出来发现了个诡异的细节Agent 上报的进程列表里有 text-embedding 服务但该进程的相关线程状态异常。Agent 上报的 CPU 占用率是 0.1%几乎为空而健康检查却显示 200。这说明问题不在 scanner而在 Agent 上报的数据本身有偏差。5.2 定位根因Agent 的健康检查是“自扫门前雪”深挖之后发现问题出在 Agent 内置的健康检查机制。AI-Infra-Guard Agent 向中心端上报状态时核心依据是本地执行 curl 的结果。它在容器里执行curl -s -o /dev/null -w %{http_code} http://127.0.0.1:8000/health这一步返回 200Agent 就把节点状态标记为正常。问题在于这个 curl 是从 Agent 容器内部发起的而 Agent 容器和业务服务之间的网络路径经过了 Docker 的 bridge 网络。当时业务服务容器因为负载过高工作线程已经全部阻塞但监听端口的 backlog 队列还活着内核协议栈能完成 TCP 握手HTTP 请求也能进入 socket 队列只是没有 worker 线程去处理。curl 的默认超时是 2 秒恰好服务端在队列里积压了少量请求curl 在超时前从队列里拿到了一个“滞留响应”还以为服务正常。这个现象在容器网络环境里特别容易被忽略。传统的进程监控看 PID 存活端口监控看 listen 状态但都无法感知“进程活着但已经放弃治疗”的场景。我的技能扫描虽然做了模型标识匹配但那是建立在健康检查本身有意义的前提下。健康检查探针过于简单刚好给漏报留了后门。5.3 修复方案给健康检查加上业务级探活逻辑根因清楚后我在技能定义里把健康检查路径从 /health 改成了一个自定义探针接口 /debug/health这个接口由业务服务自己实现逻辑是检查内部线程池状态如果活跃线程数超过阈值直接返回 503。检查最近一次模型推理耗时如果推理耗时超过 2 秒返回 503。随机抽取一个测试向量执行 embedding 计算如果失败返回 503。全部通过才返回 200并携带模型标识。这个改动相当于把健康检查从“网络层存活检查”升级为“业务可用性检查”。改完后我故意模拟了一次线程池耗尽在测试节点用脚本占满所有 worker 线程然后观察扫描结果。果然下一轮扫描立刻把状态标记为 degraded而不是 healthy。虽然没能直接看出“线程耗尽”但至少从“假健康”变成了“不健康”触发了告警。所以这次的漏报根因不是 AI-Infra-Guard 的扫描引擎算错了而是我配置的健康检查探针太“浅层”Agent 基于这个浅层探针的结果把业务假死误判为存活。工具只是执行者定义探针策略的人才是真正决定可靠性的因素。5.4 复盘总结三层防线缺一不可这次教训让我总结出一套适用于类似工具的三层防线思路第一层基础设施存活检查端口、进程、系统资源。这层 AI-Infra-Guard 默认就能做到。第二层业务健康检查服务必须响应业务语义的探针确保线程池不阻塞、模型推理正常。这是需要在技能定义里认真设计的。第三层端到端拨测从外部的模拟用户视角发起真实请求验证整体链路。这一点 AI-Infra-Guard 目前不擅长我是另外用了一个拨测脚本每小时跑一次真实文本向量化请求超时就告警。有了这三层即使某一层探针设计有缺陷另外两层也能兜底。我后来把拨测脚本的告警也接入了 AI-Infra-Guard 的通知渠道这样所有告警都在一个入口汇聚不用来回切换看板。6. 避坑指南部署和配置阶段最容易犯的 6 个错误6.1 端口映射错误导致控制台“半通不通”我第一次部署时把控制台端口映射成了 8080但 scanner 的内部端口 9000 没有映射到宿主机结果 Agent 注册时填的中心端地址没法访问。症状是控制台能打开但节点永远显示 offline。后来发现 compose 文件里 scanner 的 ports 少了一行把 9000 端口加上去节点立刻上线。所以部署后一定要检查 scanner 端口是否暴露不要只盯着 Web 控制台。6.2 技能定义中的端口与容器端口混淆在定义技能时监听端口要填“从 Agent 视角访问服务时使用的端口”。如果你的 Agent 和业务服务都跑在同一个宿主机的 Docker 网络里需要区分容器内端口和映射端口。我一开始填了业务容器的内部端口 8000但 Agent 并不在这个容器的网络命名空间里它访问不到 127.0.0.1:8000得通过宿主机映射的 18000 端口。后来我统一改成在 Agent 和业务服务之间共享一个自定义网络技能定义里的地址用容器名:端口 的方式才彻底解决。这个经验建议大家根据实际网络模型来定没有万能答案。6.3 忽略扫描间隔对数据库的压力扫描间隔设得太短比如 10 秒会导致 scanner 频繁写 Postgres时间一长表膨胀控制台查询变慢。我建议初始值设为 60 秒等确定了自己的告警响应需求再调低。对于技能扫描任务我甚至希望它别太频繁因为业务探针本身也会有耗时扫得太勤反而影响业务。6.4 Agent 令牌过期未及时更换AI-Infra-Guard 支持节点令牌默认有效期 30 天。过期后 Agent 不会主动断开但注册接口开始报 401节点状态在控制台会慢慢变成 offline。我因为没注意到这个问题白白排查了半天网络最后才发现是令牌过期。建议大家在控制台开启令牌自动轮换通知或者至少每周检查一次节点列表。6.5 健康检查路径没有做业务校验这就是我漏报事故的直接原因。如果你只是把 /health 当作“存在即合理”的简单探针那你等于没配。建议花半天时间把每个技能的探针改成业务级校验。哪怕只是检查模型冷加载状态、推理队列深度这类轻量指标也比单纯 curl 200 有意义得多。6.6 告警通道只配了一处AI-Infra-Guard 的通知支持 Webhook、Slack、邮件等。我只配了邮件结果半夜邮件服务器恰好网络抖动告警延迟了十分钟。后来我加了一条 Webhook 到钉钉群两条通道并行收到告警的及时性大幅提升。告警通道也是高可用的一部分别在一棵树上吊死。7. 个人经验谈AI-Infra-Guard 后续还能怎么扩展跑通这套平台后我陆续加了几个自定义脚本通过 AI-Infra-Guard 的任务插件机制接入。它能被扩展的地方其实比想象中多这里分享一个我最近在尝试的方向。我自己在做的就是“模型灰度发布辅助验证”把新版本模型部署到一小部分节点后触发一次手动技能扫描Scanner 会通过响应内容的模型标识快速确认新版本是否已生效、老版本是否完全下线。这个过程原来靠人核对现在一条命令就搞掂。另外我还在计划把技能扫描的结果数据导出到时序数据库这样能把“degraded 次数”和“模型切换频率”这类趋势也纳入容量规划里而不仅仅是实时告警。对我个人来说AI-Infra-Guard 最大的价值不只是“能查端口”而是逼着我重新梳理了自己环境里每个服务的能力契约。以前你会觉得“服务端口通着不就完事了吗”实际上很多隐患恰恰发生在端口通但能力不对的时候。在 AI 服务里模型版本不对、推理线程阻塞、向量维度不匹配这些都是端口活着的“假象”。技能扫描把这种假象暴露成了可量化的状态配合我后来改写的业务级探针才算真正做到了心里有底。如果你也准备部署这套工具我的建议是第一遍 Docker Compose 拉起来很简单但千万不要停留在“看到控制台就以为成功了”的状态。花一个下午把你最核心的三四个服务写成技能定义认真设计健康检查探针再加上一条端到端拨测你的 AI 基础设施才算是真的有了保障。后来我每次改模型、扩节点都会主动跑一遍技能扫描看结果显示省下了很多和业务方扯皮确认“到底改了没”的时间。这套流程现在我用了快两个月稳定性比之前纯脚本时代提升了不止一个量级。希望你也能顺利跑通少踩我这些坑。