AI-Infra-Guard 这个工具我是在一次交付任务里第一次接触的。当时要部署一套完整的 AI 服务栈服务起来之后第一个需求就是给我一份技能扫描清单说清楚每台服务器上到底跑了什么、暴露了哪些端口、提供了哪些能力。用 Docker 一键部署 AI-Infra-Guard 之后的确很快就拿到了资产清单但也在一次真实环境里踩了“漏报”的坑。这篇文章把部署过程和这次排障复盘完整记录下来希望对正在做 AI 基础设施交付、运维的朋友有帮助。1. 项目概述AI-Infra-Guard 到底解决什么问题先别急着聊操作我们花两分钟搞清楚这个工具的定位。现在做 AI 平台交付最怕的不是模型效果不行而是服务部署完了一堆却没人能说清楚哪台机器上跑着什么、暴露了什么端口、有没有成功启动。尤其当你同时部署了模型推理服务、向量库、Agent 编排服务、网关、监控组件之后整个环境就像一个大杂烩。传统的运维手段只告诉你某个进程还活着但说不清这个服务到底提供什么能力、它是不是真的健康。AI-Infra-Guard 就是为解决这个痛点出现的。它可以理解为一个面向 AI 基础设施的自动化观测与盘点工具核心能力是自动发现环境里的 AI 服务并扫描出它们各自具备的技能最终形成一份可搜索、可审计的资产清单。1.1 核心需求解析我在实际使用中体会下来AI-Infra-Guard 真正解决的问题集中在三个层面。第一个是资产发现。AI 服务普遍采用容器化部署服务之间通过 Docker 网络互联端口经常是随机映射的。如果你靠手工记端口来维护资产清单那隔两天就会失效。AI-Infra-Guard 通过挂载 docker.sock 和做网段探测把“环境里有哪些 AI 相关容器、宿主机上开放了哪些端口”给自动盘出来。第二个是健康巡检。它能对每个已发现的服务发起主动探测观察关键端点是否可达、响应时间是否正常。这比单纯依赖容器状态running/exit靠谱得多。很多 AI 服务即使容器是 running 状态内部依赖已经挂了比如连接不上向量库、模型文件加载失败这时候传统探活是完全无感的。第三个是技能扫描。这是 AI-Infra-Guard 最有别于普通监控工具的地方。它不只是判断“服务在不在”还会识别“这个服务会什么”。比如探测到某个端口响应了 /v1/models并且返回的模型列表里有 llama 类的模型名那它会给出“本地大模型推理服务”的标签如果发现某服务同时暴露了 embedding 接口它还会在技能清单里补上“向量嵌入”这一项。我理解的“技能扫描”本质上是对 AI 服务开放能力的自动化盘点。它把服务从黑盒变成了带标签的白盒资产。1.2 为什么技能扫描是刚需聊一个真实场景。我手上有一次交付客户要求对 AI 平台做安全审计其中有一项很头疼需要列出所有对外开放接口的能力清单。以前人工整理需要逐个容器看端口映射、进容器看进程、翻配置才知道每个端口是什么服务。这个工作量在几十个服务规模下根本做不完。技能扫描解决的就是这个问题。它通过一系列特征探针主动识别每个开放端口对应的服务类型和技能范围然后输出一份结构化报告。比如/v1/chat/completions 说明具备对话生成能力/v1/embeddings 说明具备向量嵌入能力/api/search 且响应体里带 chunks 字段大概率是 RAG 检索服务/metrics 说明有 Prometheus 监控指标暴露这份清单的用途很广。安全审计可以按图索骥交付验收可以快速核对需求项日常运维则拿它当“服务地图”哪台机器挂了资源不足、哪个服务多暴露了一个端口一眼就能看出来。我甚至遇到过一次技能扫描扫出某个服务意外的 /v1/embeddings 接口而这个接口本意是不对外开放的因为防火墙规则没写全导致资产暴露面比预期大。从这个角度看AI-Infra-Guard 已经不再只是运维工具它在某种意义上承担了 AI 服务安全收敛的职责。2. Docker 一键部署全流程实战部署这个工具本身不复杂但有几个关键点需要注意否则容易在后续使用中埋雷。这章节我会把每一步都写清楚包括环境检查、配置解释、启动验证。2.1 部署前的环境检查AI-Infra-Guard 的部署形态很轻本质上就是一个容器化应用对宿主机没有侵入式的依赖。官方推荐的部署方式是 Docker Compose 一键启动所以部署前只需要确认几件事。第一Docker 版本。我建议 Docker Engine 版本在 20.10 以上因为新版 Compose 插件docker compose 而不是 docker-compose在 20.10 之后用起来更稳定。检查命令很简单docker version --format {{.Server.Version}} docker compose version第二确认 docker.sock 可以被挂载。AI-Infra-Guard 需要读取 Docker 守护进程的 socket 来做容器发现所以在 Linux 上部署时你要确认 /var/run/docker.sock 存在且有权限。这个环节常见的问题就是权限不足后面常见问题部分我会专门说。第三资源规划。AI-Infra-Guard 本身的资源占用不大我跑过几十个节点的扫描单容器内存消耗在 256MB 以内。但要注意如果你同时扫描的网段很大比如 /16 全量扫会产生不小的探测流量建议部署在离目标服务网络路径近的节点上。第四规划端口。默认情况下 Web UI 端口是 9090如果你已经占用了需要提前改掉避免端口映射冲突。2.2 写一份能直接落地的 docker-compose我习惯先建一个独立的部署目录方便管理配置和数据。mkdir -p /opt/aiguard/{config,data} cd /opt/aiguard然后创建 docker-compose.yml下面这是我实际用下来的一个可用版本services: infra-guard: image: registry.example.com/aiguard/aiguard:2.8.1 container_name: aiguard restart: unless-stopped ports: - 9090:9090 volumes: - /var/run/docker.sock:/var/run/docker.sock - ./config:/etc/aiguard - ./data:/var/lib/aiguard environment: AIGUARD_SCAN_INTERVAL: 60 AIGUARD_TARGET_CIDRS: 172.16.0.0/12,192.168.50.0/24 AIGUARD_TIMEOUT_MS: 8000 AIGUARD_WORKERS: 16 AIGUARD_PORT_RANGES: 80,443,8000-8080,9000-9100,11434,3000 networks: - scan-net networks: scan-net: name: aiguard-scan这个配置文件里每一行都不是随便写的我逐个解释一下。挂载 docker.sock 的作用是让容器内的 AI-Infra-Guard 能调用 Docker API 列出本机所有容器这是自动发现的根基。没有这个挂载它只能靠纯网段扫描来存活能力会弱很多。AIGUARD_SCAN_INTERVAL 是扫描周期单位秒。我设置为 60意思是每分钟做一轮资产基线对比。如果你环境里的服务会频繁扩缩容可以改小到 30如果服务相对稳定改成 300 都行。太高的频率除了增加探测流量没有实际收益。AIGUARD_TARGET_CIDRS 是自定义扫描网段这个变量在初期很容易被忽略。AI-Infra-Guard 默认只扫描自己所在网络里的可路由地址但实际环境里服务可能分布在多个 bridge 网络、甚至独立网卡上如果不把这个网段列表填全就会漏掉大量服务。我这次漏报复盘根子就在这个参数没配全后面细说。AIGUARD_TIMEOUT_MS 是单个探测请求的超时时间。这里我特意给了 8000 毫秒比默认值大。因为 AI 服务经常要做冷启动尤其是 LLM 推理服务加载权重动辄几十秒第一次探测如果超时太短服务明明在跑也会被判为不可达形成误报或漏报。AIGUARD_WORKERS 是并发探测线程数。16 是个比较保守的值既不会把网卡打满也能保证 /24 网段几分钟内扫完。如果你目标环境上千台机器可以适当调大。volumes 部分config 目录用来放自定义规则文件或黑白名单data 目录用来持久化资产库和扫描记录。我建议把这两个目录放到宿主机上不然容器重建一次历史资产数据就全丢了。2.3 启动服务与功能验证配置写完后启动就很简单了docker compose up -d docker compose logs -f第一次启动时如果看到日志里出现类似 startup complete 或者 begin scan cycle 的信息基本就说明服务起来了。接着做两个健康检查。第一个检查 API 是否正常curl http://localhost:9090/api/v1/health正常会返回服务状态 JSON。第二个检查 Web UI 是否可访问。直接在浏览器打开 http://服务器IP:9090能看到资产大盘页面。首次打开时资产列表可能是空的因为扫描需要跑完第一轮。按 60 秒间隔算最多等两分钟左右就能看到结果。我第一次部署时就在这一步踩了坑docker compose up -d 后 Web UI 一直打不开日志里也没有报错。排查了半天发现是宿主机防火墙没放行 9090 端口。所以如果你也遇到同样问题先检查防火墙和安全组别只知道看容器日志。还有一个小建议镜像使用固定版本号不要写 latest。因为 AI-Infra-Guard 迭代很快latest 在跨大版本升级后配置格式可能不兼容固定版本能保证行为可控。3. 技能扫描功能的核心机制与使用要点部署只是第一步真正要用好 AI-Infra-Guard你得理解技能扫描是怎么工作的。这个工具的核心逻辑不复杂但理解它之后你就能解释为什么某些服务会漏报、某些服务会被误识别。3.1 扫描流程拆解AI-Infra-Guard 的每个扫描周期可以拆成四个阶段。第一阶段容器发现。它通过 docker.sock 向 Docker 守护进程发起请求拿到当前宿主机上所有容器的列表和网络归属。如果配置了 AIGUARD_TARGET_CIDRS它还会把自定义网段并入扫描池。第二阶段候选地址拼接。拿到容器信息后它会根据容器 IP、端口映射关系、以及你配置的端口范围生成一批候选探测地址。这里有个要点端口映射会扫描宿主机端口容器 IP 会直接扫描容器内部端口两者都会被覆盖。第三阶段HTTP 探活。AI-Infra-Guard 会对候选地址发起 HTTP/HTTPS 请求访问的路径是一套内置的探针列表包含几个常见端点/health、/v1/models、/metrics、/api/search 等。它不一定每个端口都试全部路径而是先做一次快速 find根据端口的常见用途决定优先探测顺序。第四阶段指纹识别与资产建模。这部分是技能扫描的核心。探活拿到响应后工具会解析响应体匹配内置特征库确定服务类型和技能标签。我用一步实际例子说明。某容器暴露端口 8001AI-Infra-Guard 探测发现 /v1/models 返回了包含 Qwen2.5-14B 的 JSON于是它会给这个资产打上标签字段识别结果服务类型LLM 推理服务技能标签文本生成、对话补全兼容协议OpenAI 兼容如果同一个服务再探测到 /v1/embeddings 也返回 200技能列表里就会追加“向量嵌入”。这个能力对资产管理来说很有价值。3.2 探针识别与技能标签的匹配逻辑很多朋友好奇AI-Infra-Guard 怎么判断一个服务是 RAG 还是 Agent其实它就是靠特征匹配。我总结了一下大概有三类探针第一类是路径特征。比如 /v1/chat/completions 这个路径几乎只出现在 OpenAI 兼容的推理 API 上路径本身就有强区分度。第二类是响应体特征。比如 /health 返回的 JSON 里如果带 model_size 或 device 字段大概率是推理服务如果带 chunks_count 或 vector_db_name大概率是 RAG 服务。第三类是行为特征。比如一次探测发出后响应头里带 x-agent-id 这类自定义字段AI-Infra-Guard 会把该特征作为 Agent 编排服务的标识。这套逻辑并不是万能的。如果服务用了自定义路径且关闭了默认探针端点指纹识别就会失败该服务可能被标记为“未知服务”。这个时候不用慌AI-Infra-Guard 支持在 config 目录下加自定义探针规则把响应体特征写进规则文件就能让后续扫描正确识别。如果你在配置文件里做了自定义规则改完记得手动触发一次扫描或者等下一轮扫描周期自动生效然后在 Web UI 里确认资产标签是否更新。我见过有人配了规则但忘记刷新扫描在页面上干瞪眼等了一个小时其实工具早按新规则重扫完了只是页面缓存。3.3 让扫描结果更准的三个参数根据自己使用经验我总结出让技能扫描结果变准的三个关键参数。第一个是 AIGUARD_TIMEOUT_MS我上面已经提过。AI 服务冷启动慢是常态如果超时太短会有大量假漏报。我目前生产环境固定用 8000如果某台机器的推理服务经常需要重新加载模型我会单独调高到 15000。第二个是 AIGUARD_TARGET_CIDRS。这个参数是解决跨网络漏报的关键。很多部署环境里服务跑在不同的 docker bridge 网络里AI-Infra-Guard 如果不主动补全这些网段就探测不到。这个参数应该写全你环境中所有服务可能所在的网段。比如网关在网桥 172.20.0.0/16向量库在 172.21.0.0/16你就把两个网段都加进去。第三个是自定义探针规则。内置特征库再全也无法覆盖你使用的私有协议。我强烈建议在首次部署后先观察一轮扫描结果把识别为“未知服务”的资产单独挑出来写几条自定义规则让它们拥有正确的技能标签。这个过程不算复杂本质就是固定特征字符串的匹配。参数 / 行为影响我的推荐AIGUARD_TIMEOUT_MS影响慢启动服务是否漏报8000 起步AIGUARD_TARGET_CIDRS影响跨网段服务是否被发现写全所有服务网段自定义探针规则影响私有协议的识别准确率首轮扫描后补齐4. 一次漏报问题的完整复盘接下来聊聊我承诺的这次“漏报”复盘。这是 AI-Infra-Guard 落地过程中我印象最深的一次排障经历也直接让我对自动发现工具建立了更清醒的认知。4.1 问题现场服务正常却在清单里消失当时环境里部署了四组关键服务AI 网关服务 gw-ai-core提供统一 API 接入端口映射在宿主机 8002大模型推理服务 vllm-llama使用 OpenAI 兼容协议端口 8001RAG 检索服务 rag-worker端口 8040AI-Infra-Guard 本身端口 9090第一批扫描结果出来后vllm-llama 和 rag-worker 都正常出现在资产清单里而且技能标签识别得很准。但网关 gw-ai-core 完全没有出现不是被标记为未知而是干脆消失在清单里。我第一时间检查了网关容器状态进程正常运行日志显示服务健康宿主机上 curl 一下 /health 也是立即返回 200。也就是说服务本身确实没有故障。这个现象很有迷惑性服务活着但监控工具发现不了它。我当时第一反应是怀疑 AI-Infra-Guard 的端口探测范围没覆盖到 8002因为我配置的 AIGUARD_PORT_RANGES 里虽然写了 9000-9100但没写 8002 端口段。4.2 定位过程从服务自身到网络拓扑我先检查端口范围配置。刚才不是怀疑漏配端口吗我看了下 AIGUARD_PORT_RANGES 默认值里面包含了 8000-8080所以端口 8002 本身是在扫描范围里的。那问题就不在端口层。接着我做了第二步排查直接进入 AI-Infra-Guard 容器内部去请求网关的 /health 接口。docker exec -it aiguard sh curl http://172.18.0.5:8002/health这个请求直接超时了。但我在宿主机上访问同一个端口是正常的。这就把问题定位到网络层了。我当时第一个困惑是为什么 AI-Infra-Guard 能看到 vllm 和 rag-worker唯独看不到网关按道理它通过 docker.sock 应该能列出所有容器网关容器也算是它的“可见对象”。后来我检查了 Docker 网络拓扑才明白问题本质。4.3 根因确认与两个叠加因素我用 docker network inspect 看了两个关键网络的信息docker network inspect aiguard-scan docker network inspect myapp_gateway结果发现AI-Infra-Guard 跑在 aiguard-scan 这个自定义 bridge 网络上而网关 gw-ai-core 跑在 myapp_gateway 网络上。vllm-llama 和 rag-worker 则碰巧和 AI-Infra-Guard 在同一个网络里。问题就出在这里AI-Infra-Guard 的容器发现阶段虽然能通过 docker.sock 看到环境里所有容器但它的探测阶段是用容器 IP 直连的。从 aiguard-scan 网络发出的包根本路由不到 myapp_gateway 网络内的容器 IP因此探测自然失败。更讽刺的是网关映射在宿主机的 8002 端口虽然可用但 AI-Infra-Guard 默认对宿主机端口扫描的范围依赖我配置的 AIGUARD_PORT_RANGES而它的“宿主机端口探活”也必须走一层额外的探测逻辑。在我当时没有配置 TARGET_CIDRS、也没有把宿主机网段显式加入扫描池的情况下这层探测没有被正确触发。还有一个叠加因素。当时我给网关设置的探活超时是默认值 3000 毫秒。网关在不断发布会上线版本冷启动时健康检查接口要在加载完一批过滤规则后才返回 200这个初始化时间超过了 3 秒。所以就算我把它加进同网络首次扫描也有可能因为慢启动而漏报。两层原因叠加形成了我看到的“服务明明在跑扫描结果里却没有”的怪象。4.4 修复方案与事后验证修复分两步。第一步把网关加入 aiguard-scan 网络先解决当前网络不可达的问题docker network connect aiguard-scan gw-ai-core第二步修改 AI-Infra-Guard 的环境变量把宿主机所在的 192.168.50.0/24 网段和 myapp_gateway 网段都加入 TARGET_CIDRS同时把探活超时从默认 3000 上调到 8000environment: AIGUARD_TARGET_CIDRS: 192.168.50.0/24,172.18.0.0/16,172.20.0.0/16 AIGUARD_TIMEOUT_MS: 8000改完配置后重启容器docker compose up -d --force-recreate手动触发一轮扫描等结果刷新。这次 gw-ai-core 成功出现在资产清单里并且被正确识别为 AI 网关服务技能标签包括“路由转发”“协议转换”“请求审计”。修复后我做了个小实验把网关从 aiguard-scan 网络断开但保留 TARGET_CIDRS 配置重新扫描仍然能发现它。说明长期方案的效力不依赖临时的网络变更。这次复盘给我最大的教训是自动发现工具不是真的“全自动”它也有自己预设的视野。如果你的服务分布在多个网络里、或者存在慢启动场景你必须在配置里主动把这些维度补全。工具可以替你省掉手工盘点的时间但前提是你把它该知道的上下文物料都准备好。5. 常见问题速查与避坑经验最后把我在使用 AI-Infra-Guard 过程中遇到过的“坑位”整理成一份速查表。这些事大多不复杂但每一个都真实发生过而且翻车的姿势很有代表性。5.1 部署环境常见拦路虎第一个坑是 docker.sock 权限不足。容器内进程访问 docker.sock 时如果报 permission denied多半是因为宿主机 socket 的权限组和容器内用户不匹配。你可以把 socket 权限放开给 docker 组或者在 docker-compose 里用 gid 映射解决。注意不要随意检查 socket 文件权限我见过有人图省事 chmod 777短期内没问题但安全上非常不可取。第二个坑是端口映射冲突。AI-Infra-Guard 默认占用 9090如果你已经有监控系统用了这个端口启动时容器会直接退出。解决方式是显式改宿主机侧端口比如改写成 19090:9090。第三个坑是容器重启后数据丢失。如果没把 data 目录持久化容器重建一次资产库和扫描历史就全没了。我建议从一开始就把 data 目录映射出来并且定期备份这个目录。第四个坑是镜像拉取失败。这在大环境里很常见如果公共仓库访问不稳定最好提前把镜像推送到内网仓库或者配置内网镜像源。我在部署配置里使用 registry.example.com/aiguard/aiguard 这样的占位地址实际使用时应替换成你组织内可达的仓库地址。5.2 扫描不准时的排查顺序如果你发现扫描结果里某些服务缺失或者识别错误按下面的顺序排查基本能把八成问题定位出来现象可能原因处理建议服务在跑但整个缺失跨网络不可达检查网络归属配全 TARGET_CIDRS服务出现但标记未知内置指纹未命中写自定义探针规则服务识别错误端口段重叠、指纹相似在自定义规则里配置优先级扫描结果为旧数据扫描周期未到等待或手动触发扫描容器内探测正常、宿主机探测失败防火墙阻断检查宿主机防火墙和安全组排查的时候我建议遵循一个原则先网络后配置最后再看指纹规则。因为网络层问题的影响面最大如果网段配置错了后面一切努力都是在白费功夫。另外补充一个小技巧AI-Infra-Guard 的日志里会记录每次探测失败的原因比如 timeout、refused、dns_error。你可以用 log 关键字过滤快速定位是“连不上”还是“被拒绝”。我曾经就靠一条 timeout 日志在半小时内锁定了漏报服务所在的网络问题省去了大量猜测时间。还有一个体验上的建议先跑一轮最小范围扫描验证工具本身的工作逻辑正常再逐步扩大网段范围。我在新环境里通常先只配一个 /28 小网段扫一轮确认资产上报、探针识别、UI 展示都符合预期后再放开到全量网段。这样可以避免一开始就把大量误报和漏报资讯混在一起干扰判断。AI-Infra-Guard 这个工具抛开具体的探针数量和指纹规则不谈最值钱的地方在于它提供了一个资产视角。每次扫描不只是回答“服务在不在”而是回答“环境里有什么、每个东西会什么、暴露了什么”。我这位曾经手工维护 Excel 资产表的人第一次看到自动生成的资产清单时确实有很长一段时间觉得它解决了我 80% 的工作量。但那次漏报经历之后我对所有自动发现工具都保留了一份清醒自动发现依赖网络可达和配置完善配置的盲区就是工具的盲区。现在我在交付任何 AI 服务时都会顺手做一件小事——部署完 AI-Infra-Guard 后把周围环境里所有服务和网络先手工盘一遍与自动扫描结果做一次对比。这份对比表往往会成为项目交付时最有力的验收证据。如果你也在做 AI 基础设施这类工作强烈建议你也把这套“先盘后扫”的流程落下来会少踩很多坑。