为什么我会把 AI-Infra-Guard 部署在 Docker 里先说结论AI-Infra-Guard 这套东西如果你还在手动装依赖、配环境、逐个模块起服务那真的是在浪费生命。这个项目本质上是一个面向 AI 基础设施的“体检 技能摸底”工具它要扫描的不只是机器资源还有你整个 AI 底座上跑着的模型服务、推理框架、向量库、调度器这些组件到底健不健康、支不支持你接下来要做的事。Docker 一键起不是为了炫技是为了让你把精力花在扫描结果上而不是花在“为什么我本地能跑、服务器上跑不起来”这种破事上。我接触这个项目是因为团队最近在梳理内部 AI 平台的组件清单需要快速评估各节点的能力水位——比如有没有装 CUDA、推理框架版本够不够新、有没有暴露不必要的调试端口。手工去逐台机器敲命令能敲到怀疑人生。AI-Infra-Guard 的价值就在于把“技能扫描”这件事自动化而且它的扫描项设计是冲着 AI 基础设施的真实痛点去的不是那种 ping 一下 IP 就算完事的玩具。这篇文章我会从部署方案选型讲起然后完整拆解一次实战扫描过程最后单独用一节复盘我踩过的一次“漏报”事故——准确说是误判差点让团队把一个健康的节点当成僵尸节点处理掉。整个过程我都会给出具体的命令、参数和排查思路方便你直接照着复现。适合谁来参考这篇文章如果你正在做 AI 平台运维、模型服务部署前的环境预检、或者想给团队搞一套基础设施健康度巡检体系那 AI-Infra-Guard 的这套玩法非常值得借鉴。如果你只是对 Docker 部署感兴趣也能从里面看到一套完整的多服务编排实践。1. 部署方案选型为什么必须用 Docker 一键起1.1 手动部署的痛点我替你踩过了在我决定用 Docker 之前先在一台干净的 Ubuntu 22.04 上试过手动部署 AI-Infra-Guard。过程怎么说呢就是典型的“你以为你在装软件其实你在给环境排雷”。首先 Python 版本就有讲究项目要求 3.10 以上但系统自带的可能是 3.8 或者 3.9。用 pyenv 装 Python 不是不行但 pyenv 本身又依赖一堆编译工具链什么 build-essential、libssl-dev、zlib1g-dev缺一个编译就报错。装完 Python 还得处理 pip 源的网络问题然后项目管理工具 poetry 或 pdm 又得单独装。这些还只是前置准备。真正的痛点在于 AI-Infra-Guard 依赖的底层扫描库。比如要用到 psutil 来采集系统指标需要编译部分 C 扩展要用到某些 GPU 检测模块就得保证本机有完整的 NVIDIA 驱动开发头文件否则编译直接失败。这些库装完之后还得面对版本冲突——项目要求的某个依赖版本和系统已有的包冲突一 upgrade 又把别的服务搞挂了。我当时在一台还跑着其他业务的机器上操作战战兢兢。这些时间成本其实完全可以避免。容器化的核心价值就是“环境隔离 依赖打包”AI-Infra-Guard 的 Docker 镜像把 Python 版本、依赖库、系统级工具全部固化在一个镜像里宿主机只需要有 Docker Engine其他的乱七八糟全靠镜像内部自包含。1.2 Docker Compose 编排带来的额外收益AI-Infra-Guard 不只是一个单体服务它分成了扫描器Scanner、服务端Server、前端控制台Web UI这几个核心组件。这种架构天然适合用 Docker Compose 来编排。手动部署的时候你得分别启动这三个进程还要手工处理它们之间的网络通信、配置文件同步、日志收集。一旦机器重启这三个进程不会自动恢复你还得写 systemd service 或者 supervisor 配置来守护。说实话为了跑一个扫描工具去写 systemd 配置性价比太低了。用 Docker Compose 的话整个应用被定义在一个docker-compose.yml文件里设置好依赖关系后一条docker compose up -d就能把服务端、扫描器、控制台全部按顺序拉起。而且 Compose 会创建自定义网络容器之间通过服务名互相访问解决了手动部署时最容易出错的“地址配置错”问题。注意宿主机网络和 Compose 网络是隔离的。如果你想在浏览器里打开控制台记得把 Web UI 服务的端口映射到宿主机这也是我在下面的部署步骤里重点强调的。1.3 Docker Desktop 和 Linux 环境的选择这里要单独提一下 Docker Desktop。如果你用的是 Windows 或者 macOS 开发机Docker Desktop 是最省事的方案但有两个坑要先排掉。第一个坑是 “Virtualization support not detected” 这类报错。这不是 Docker 的问题而是 Windows 的 WSL2 或 Hyper-V 虚拟化没有被正确启用。处理方法很固定控制面板 - 程序 - 启用或关闭 Windows 功能 - 勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”然后重启再打开 Docker Desktop 一般就能起来。第二个坑是 Docker Desktop 的资源限制。默认配置下它只会给虚拟机分配 2 个 CPU 和 2GB 内存。如果你要扫描的 AI 基础设施规模比较大或者扫描任务本身要并行跑很多探针这个资源配额很可能导致扫描超时。我建议在 Docker Desktop 的 Settings - Resources 里把 CPU 调到 4 核以上内存至少 4GB。实测下来这个配置对 AI-Infra-Guard 的日常扫描已经足够。如果你用的是 Linux 服务器那就没有 Docker Desktop 这层虚拟化开销了直接装 Docker Engine 就行。Ubuntu 上装 Docker 的标准姿势是把官方源配好然后apt install docker-ce docker-ce-cli containerd.io。装完记得把当前用户加入 docker 组否则每条命令都要加 sudo。提示不建议在 Windows 上手动部署 AI-Infra-Guard。它的扫描探针涉及很多系统级调用Windows 下的兼容性测试做得并不充分你大概率会撞上一堆莫名其妙的坑。直接用 Docker Desktop 跑容器省心得多。2. 部署实操从头到尾带你跑通2.1 获取项目与镜像准备部署前先确认宿主机满足两个基本条件Docker Engine 版本在 20.10 以上Compose 插件已安装。查询方法很简单docker version --format {{.Server.Version}} docker compose version如果 compose 提示没有这个命令Ubuntu 上用apt install docker-compose-plugin补上。然后克隆项目代码git clone https://github.com/your-repo/AI-Infra-Guard.git cd AI-Infra-Guard/deploy项目提供了三种镜像获取方式本地构建、拉取官方镜像、离线导入。我这边因为内网环境访问 Docker Hub 不方便直接用了本地构建。如果你能访问外网推荐直接用官方编排脚本里定义的镜像名省去构建时间。本地构建也很简单项目根目录下有写好的 Dockerfile在deploy目录里执行docker compose build如果你网络好也可以直接用现成镜像把docker-compose.yml里的build字段注释掉换成image: your-registry/ai-infra-guard:latest。两种方式殊途同归。构建过程中如果因为网络问题拉取基础镜像失败建议配置 Docker daemon 的镜像加速器这个下文避坑部分会展开。2.2 修改核心配置代码拿到手别急着起服务先把配置改对。AI-Infra-Guard 的配置文件主要是config/guard.yaml里面定义了扫描目标范围、技能检查项、告警阈值三个核心部分。扫描目标范围这部分需要你把要扫描的 AI 基础设施节点 IP 或网段填进去例如scan: targets: - 192.168.1.10 - 192.168.1.0/24 exclude: - 192.168.1.200注意exclude是用来排除某些运维保留地址的用网段扫描的时候特别有用。技能检查项这部分默认配置已经覆盖了 CPU、内存、磁盘、GPU、容器运行时、Python 环境、常见 AI 框架等按需增删。告警阈值我建议先用默认值跑两轮真实数据后再根据实际情况调整。另外docker-compose.yml里需要关注几个端口映射。默认情况下 Web UI 映射到宿主机的 8080服务端 API 是 9090。如果你的宿主机端口被占用直接改ports字段左侧的宿主机端口。实际部署时我还发现项目默认把扫描器部署为单实例扫描大批量节点时耗时较长。如果后续需要横向扩容可以通过docker compose up --scale scanner3来扩展扫描器数量但注意这会触发并发扫描目标节点上有防火墙的话容易误判为攻击行为需要谨慎操作。2.3 一键启动与验证配置完成后执行docker compose up -d第一次启动会自动构建镜像并创建容器耐心等一下。启动完成后用docker compose ps查看状态三个服务的状态都应该是 Up。接着验证服务端接口是否响应curl -s http://localhost:9090/api/v1/health正常情况下会返回{status:ok}之类的 JSON。Web UI 直接浏览器打开http://localhost:8080能看到登录页说明整套系统已经跑通了。默认账号密码在项目的.env文件里首次登录后强制修改。这里我要强调一个细节扫描器容器的网络模式。默认配置下扫描器和宿主机共享网络模式这样扫描器能拿到宿主机完整的网络权限不至于扫描本机服务时被容器网络挡在门外。但如果你用的是 Docker Desktop for Windows共享宿主机网络这个配置可能是失效的因为容器实际上跑在虚拟机里。这种情况建议加一条 Docker Desktop 的路由规则或者把宿主机 IP 通过环境变量传给扫描器。登录前端控制台后第一步就是把扫描目标加进去。这里的目标可以是 IP、网段也可以是一个域名。加完之后点击“立即扫描”就能看到任务进入队列。3. 技能扫描实战我拿真实 AI 节点做了次体检3.1 准备一个标准的 AI 推理节点这次扫描的目标是一台承载着模型推理服务的 GPU 节点配置大概是这样双路 Intel Xeon、256GB 内存、一张 NVIDIA A100 80GB、系统是 Ubuntu 20.04、装的是 CUDA 11.8、推理框架是 Triton Inference Server。为什么会选这个节点因为它承载了团队里一个比较重要的在线推理服务最近频繁被算法团队反馈“响应变慢”我正好借这次扫描看看是不是基础设施层面出了问题。扫描之前我先在节点上手工确认了几个关键信息NVIDIA 驱动版本、Triton Inference Server 的进程状态、GPU 利用率。这些信息是用来和 AI-Infra-Guard 的扫描结果做交叉验证的。确认完毕后我在 AI-Infra-Guard 控制台新建扫描任务扫描目标填这台节点的 IP扫描模板选择 “AI Inference Node Full Check”。这个模板是项目自带的包含的技能检查项非常全基础资源、GPU 栈、推理框架、网络模块、系统安全配置都有覆盖。3.2 扫描任务发起与实时观察点击开始扫描后任务状态从 Pending 变成 Running。整个扫描过程大概持续了几分钟具体耗时取决于目标节点开了多少探针。我在另一个终端窗口里用docker logs -f ai-infra-guard-scanner实时盯着日志可以看到扫描器正在逐项检查目标的各个技能点。这里科普一下 AI-Infra-Guard 的扫描逻辑它的探针是分层的。第一层是基础探测先确认目标节点的网络连通性和 SSH 可达性第二层是系统级扫描通过 SSH 执行一组预定义命令来采集 CPU 核数、内存大小、磁盘分区、内核版本等第三层是技能专检尝试探测目标节点上是否运行了特定的 AI 服务比如检查 GPU 驱动是否加载、是否有推理框架的默认端口在监听、是否有模型仓库目录存在。这种分层设计的好处是效率高如果第一层都过不去就不会浪费时间往下扫。坏处是如果目标节点开了严格的 SSH 白名单除特定用户外其他用户无法登录那扫描器可能连门都进不去直接返回不可达看起来像是节点挂了。这个坑后面复盘部分我会详说。扫描结束后控制台的报告页展示了一份结构化的扫描结果。3.3 扫描结果解读哪些是绿灯哪些是红灯这份报告按检查项分类每项都有状态通过/未通过/告警、实测值、参考建议三项信息。我捡几个关键的说GPU 栈检查这一项是绿灯驱动版本 525.105.17CUDA 版本 11.8和预期一致。推理框架检测同样是绿灯Triton 的 8000 端口在监听进程状态正常。但 CPU 负载检查这一项红色告警显示过去 15 分钟平均负载是 12.7而这款 CPU 的逻辑核是 32 核按常规经验负载不应该这么高。我根据报告里的建议字段先去目标节点上用了top和iotop排查。一通操作下来发现是某个数据预处理任务在疯狂读磁盘占了大量 IO 带宽服务端响应慢的根源基本锁定在这个 IO 争抢上。AI-Infra-Guard 虽然没有直接告诉我瓶颈是 IO但它提示了 CPU 负载异常这个线索让我少走了不少弯路。另一个有意思的发现是扫描报告提示目标节点开放了一个管理端口 8088但团队内部并没有登记这个端口。顺着线索查下去发现是某位同事为了调试便利临时起的一个 Web 服务没设认证就暴露在内网。这个发现让安全团队多了一个排查任务。这个案例也说明AI-Infra-Guard 虽然不是专职安全工具但它的端口探测能力在资产管理层面确实能帮上忙。3.4 扫描报告的自动化落库与通知AI-Infra-Guard 的扫描结果是可落库的。它内置的存储层会按时间戳保存每次扫描的原始数据方便后续做趋势分析和对比。我个人比较推荐把报告导出成 JSON 格式然后通过项目自带的 webhook 模块把结果同步到内部工单系统。这里给一个小建议扫描任务一定要配置调度周期。AI-Infra-Guard 支持 cron 表达式我设置为每天凌晨 2 点跑一轮全量扫描覆盖所有生产 AI 节点。这样每天早上到工位打开控制台就能看到一份昨夜的基础设施健康速报。遇到状态变化能第一时间发现比出事之后再去翻日志强太多。4. 一次“漏报”事故的完整复盘健康节点差点被误判成僵尸4.1 事故现场明明活着扫描器却说挂了使用 AI-Infra-Guard 的第二周我安排了一次针对所有 GPU 节点的例行扫描。扫描完成后报告里有一个节点被标记为“不可达”状态是红色探针显示“SSH 认证失败”加“网络超时”。这个节点是我们团队压箱底的另一个推理节点上周还在正常跑着定时任务完全没有要宕机的预兆。按照报告的状态下一步常规处理就是拉起告警、让值班同事去机房做硬件排查或者直接考虑重建节点。但我心里犯嘀咕因为这个节点上周我还在上面跑过脚本不可能说挂就挂。我决定先不按“节点宕机”预案走而是亲自连上去看看。结果非常打脸——我用同一个 SSH 密钥手动连接秒连而且uptime显示这台机器已经稳定运行了 87 天。CPU、内存、磁盘都没有异常监听端口全部正常Triton 推理服务还在对外响应请求。健康得不能再健康了。这个结果让人有点懵如果节点是健康的那 AI-Infra-Guard 为什么会报“不可达”如果扫描器报告错了那以后还怎么信任它的结论带着这个疑问我开始了这次事故的完整排查。4.2 排查过程日志逐字段比对第一步是看扫描器日志目标节点在扫描任务里确实被标记为失败错误信息是 “Failed to establish SSH connection: handshake timeout”。第二步我在扫描器容器里手动执行了一次 SSH 连接测试用的命令和配置与扫描脚本完全一致结果依然提示超时。这说明问题不是偶然的网络抖动而是扫描器在特定网络环境下持久存在的问题。第三步是关键——我尝试在宿主机非容器里执行同样的 SSH 命令结果竟然通了。至此问题从“节点挂了”变成“容器内网络到节点不通”。继续查容器网络配置发现扫描器容器被分配了一个 IP 段而这个 IP 段和目标节点处于不同的 VLAN。宿主机到目标节点能通是因为宿主机有往那个 VLAN 的正确路由而容器跑在 Docker 的默认 bridge 网络上根本不知道那条路由该走哪里。这就是经典的容器网络路由缺失问题。容器内ip route里没有去往目标 VLAN 的静态路由默认网关指向 Docker 的 bridge 网关而这个网关不会把包转发到目标 VLAN于是连接请求在超时之后被判定为不可达。4.3 根因确认网络路由表的宿主机与容器差异为了证实这个判断我在容器里和目标节点上分别抓包对比 TCP SYN 包的走向。抓包结果显示扫描器容器发出的 SYN 包到了宿主机之后并没有被转发到目标节点所在 VLAN 的网关而是直接丢掉了。而宿主机自己发出的 SYN 包能看到正确的路由路径网关成功转发。这个现象的根本原因在于 Docker 默认 bridge 网络的隔离性。容器内的网络栈和宿主机是隔离的它只知道自己的网段和 docker0 的网关地址。如果你要扫描的目标和宿主机不在同一个广播域或路由域内就得显式告诉容器网络如何到达那个目标否则所有数据包都会掉进黑洞。确认根因后修复方案很明确在 Compose 文件中把扫描器指向宿主机网络模式或者给容器自定义网络添加一条静态路由。考虑到这台机器上还有其他容器服务直接用 host 网络模式会带来端口冲突风险所以我选择了自定义网络加静态路由的方案针对性解决扫描器到目标 VLAN 的通讯问题。在docker-compose.yml里我给扫描器服务新增了自定义网络配置并往该网络里注入了一条路由规则。改完后重启扫描器容器再次发起扫描目标节点的状态从红色变成绿色。4.4 复盘总结为什么这不算工具“漏报”排查结束之后团队里有人开玩笑说“AI-Infra-Guard 有漏报问题应该反馈给开发者修 bug”。但我不这么看。准确地说这次事件是部署拓扑缺陷导致的误报不是扫描器本身的漏报。所谓“漏报”通常指目标确实有问题但工具没有发现。而这次是工具把健康节点误判为不可达属于配置层面的误报。AI-Infra-Guard 的扫描探针本身没有问题它只是忠实地记录了“从这个容器视角看目标节点不可达”这一事实。扫描器没有魔法戒指去感知全局网络它只能反映自己所在网络环境能感知到的东西。这次事故真正的教训是部署扫描器之前必须先把目标网络的拓扑摸清楚。如果你要扫描的节点分散在多个 VLAN 里那务必确保扫描器所在容器的网络能和所有目标 VLAN 路由打通否则“漏报”的根本不在扫描器身上而在网络规划的人身上。提示正式部署前建议先用docker exec -it scanner-container bash进入容器手动 ping 或 nc 测一下目标节点的端口连通性。这一步能提前挡掉 90% 的网络误配问题。5. 实战中的避坑清单与进阶玩法5.1 高频问题速查表现象可能原因解决办法docker compose up提示镜像拉取超时网络问题或镜像源被墙配置 Docker 镜像加速器或改为本地构建Web UI 打不开宿主机端口被占用或映射错误修改 compose 文件中的端口映射检查端口占用扫描任务一直 Pending服务端队列未消费或扫描器未注册查看服务端日志确认 scanner 是否正常启动并注册到服务端扫描结果全是 Unreachable容器网络与目标节点不通检查路由、防火墙、VLAN 隔离SSH 认证失败密钥未挂载到扫描器容器在 compose 文件中正确挂载宿主机 SSH 密钥并设置好权限GPU 技能检测失败目标节点近期更新过驱动扫描器内置驱动指纹表过旧更新扫描器镜像或手动添加新的驱动指纹规则磁盘检查提示空间不足但实际还有空间扫描器默认阈值配置过严在配置文件中调整磁盘剩余空间告警阈值这几个是实战里最容易碰到的高频项。尤其是 SSH 密钥挂载这一项很多第一次部署的人会忽略导致扫描器无法以预期的用户权限去对目标执行命令。权限不够的话很多检测项都会失败或降级但日志里看起来又像“正常超时”非常迷惑。5.2 我踩过的其他坑镜像构建失败项目里某些底层依赖包体积很大构建时经常超时。解决方案是给 Docker daemon 配置国内可用的镜像加速器同时把构建过程中的基础镜像改为私有 registry 里的缓存版本构建速度快了不止一倍。端口冲突默认的控制台端口 8080 比较抢手很多机器上已经跑了别的 Web 服务。建议使用 18080、28080 这类高位端口来做宿主机映射降低冲突概率。扫描深度不够如果目标节点有启动 agent 权限可以部署 AI-Infra-Guard 的 Agent 模式。Agent 模式能采集到更多系统层面的信息比如 Docker 容器列表、进程级 GPU 使用率这是纯 SSH 探针模式看不到的。数据库存储膨胀扫描结果长期积累之后PostgreSQL 或 SQLite 的数据量会变得有点大。建议配置定时任务定期清理三个月前的历史扫描数据只保留统计摘要以控制存储成本。误报处理机制建议在收到告警时先通过工单系统发起确认流程由人工快速验证再决定是否触发后续响应。纯粹依赖告警自动化处理网络类问题会有一大批因为安全策略或路由策略导致的麻烦事。5.3 进阶玩法AI-Infra-Guard 还能这样用跑通基础的技能扫描之后我慢慢把它往更多场景延伸了。第一个进阶用法是“变更前基线扫描”。每次升级推理框架、调整 GPU 驱动之前先让 AI-Infra-Guard 跑一次全量扫描把当前环境的技能基线存下来变更完成后再跑一次对比两份报告能一眼看出哪些能力变了、哪些依赖出现了回归。有几次就是靠这份对比报告在模型版本升级后立刻发现了框架版本不兼容的问题避免带病上线。第二个进阶用法是“资产台账自动更新”。AI-Infra-Guard 的扫描结果里有很多元数据比如主机名、操作系统版本、CPU 核数、内存容量等。把这些数据同步到 CMDB 系统之后资产台账的准确性提升了不少。内网的资产管理审计需求也能顺带覆盖掉一举两得。第三个进阶用法是“多环境对比”。把测试环境、预发环境、生产环境的扫描结果放在一张表里粘贴对比环境一致性一目了然。某次大版本升级的时候就是靠这个对比发现测试环境 GPU 驱动比生产环境新了两个版本立刻拉平了版本号再放流量规避了一次潜在的推理结果不一致问题。第四个进阶用法是“AI 就绪度评估”。如果团队在评估是否要上一个新的 AI 工作负载我会先在目标节点上跑一轮 AI-Infra-Guard 的专项扫描根据报告里的能力矩阵去判断“这个节点适合不适合跑这一类的负载”。项目内置的 AI 技能矩阵输出实际评估效率比手动逐项验证高出几个数量级。6. 写在最后的个人体会AI-Infra-Guard 本身不是那种复杂得离谱的项目但它非常精准地解决了一个实际痛点AI 基础设施不像普通 Web 服务它的组件太杂、版本太乱、依赖太深靠人工巡检基本不可能做到全面覆盖。而 Docker 部署又把使用门槛压低了一大截。真正的好工具就是这样不是功能越多越牛而是能让人一扫就知道“我现在这套东西到底行不行、哪里不行”。我个人在实际操作中体会最深的一点是不要把扫描报告当成“圣旨”要把它当成“线索”。任何自动化扫描工具都可能因为网络环境、配置差异、安全策略产生误判但 AI-Infra-Guard 已经把大量重复性的检测工作做掉了我们就该把精力集中在它标出来的那些异常项上逐个人工确认、定位根因、形成闭环。这次复盘的那次“漏报”说到底不是工具骗了我而是我当初部署的时候少看了一眼路由表多花了半小时排查而已。最后再分享一个小技巧AI-Infra-Guard 的扫描报告默认是存在容器里的如果容器重建历史数据可能就没了。我在 compose 文件里给数据目录加了一个宿主机卷挂载确保扫描历史不会因为容器生命周期而丢失。这个细节看起来不起眼真遇到需要回溯“三个月前这个节点的 GPU 驱动版本是多少”这种问题时你就会明白它有多值钱。