上一篇讲的是企业 RAG 智能体的生产分层：NewAPI 做入口，Adapter 做协议和策略，RAGFlow 做知识库，Model Router 和 vLLM 做推理。

但架构分清以后，真正难的问题才出现：把文档上传到知识库，并不等于系统拥有了可信知识。

我对 RAG 的一个基本判断是：模型幻觉往往不是生成阶段才发生的，它更早发生在文档治理、知识边界、召回和证据筛选阶段。前面没有把证据做干净，后面再靠 prompt 要求“不要胡说”，只能算心理安慰。

1. 文档不是知识，chunk 也不是知识

很多 RAG 项目会把“文档上传成功”和“知识库可用”画等号。这个等号很危险。

文档是资料容器。chunk 是检索载体。真正能支撑回答的，是有边界、有来源、有问法映射、有负例约束的知识点。

可以这样理解：

一个制度文档可能包含适用范围、申请流程、审批规则、例外情况和处罚条款。如果直接按固定长度切 chunk，模型可能只拿到“申请前 30 日应…”这种半句话。

真正可靠的做法，是先按结构和语义拆知识点，再让 chunk 服务检索性能。

2. 入库阶段要比问答阶段更严格

RAG 的文档 embedding 发生在入库阶段，不是用户每次提问后才把文档重新向量化。

入库主链路可以交给 RAGFlow 托管：

上传文档  -> 文档解析  -> chunk  -> embedding  -> 写入 doc engine

但这不代表外部治理层可以消失。企业级场景至少要在入库前后补齐这些控制：

我不建议首版把解析、chunk、embedding、写库、检索全部拆成自研微服务。更稳的方式是“RAGFlow 托管主链路，外部治理层做准入、策略、质量门和回归评测”。

3. Knowledge Point 是知识库的逻辑骨架

Knowledge Point 可以理解为：

可独立回答一个或一组相近问题的最小业务语义单元。

它不是替代 Document，也不是替代 chunk。更准确地说，Document 保留原文真实性，chunk 服务检索效率，Knowledge Point 负责把业务语义、问法边界和评测样本组织起来。

它至少应该包含这些信息：

这套结构的价值，不是为了让知识库“更复杂”，而是为了让它可测试。

如果一个知识点没有标准问法、没有负例、没有引用位置，那么召回结果好坏只能靠体感。体感一旦进入生产，就很难治理。

4. 用户不会按文档原句提问

企业知识库里最常见的错位，是文档写得很正式，用户问得很口语。

文档里可能写：

合同有效期届满前 30 日，由经办部门发起续签评估。

用户会问：

合同过期了咋办？协议到期还能不能继续用？到期合同是不是自动终止？续签是谁来提？

如果只用用户原句做一次向量检索，很容易召回不稳定。

更好的检索入口是“原始问题 + 归一化问题 + canonical question + 高置信问法变体”。但扩展必须克制，不能无限改写。

建议默认最多 4 条查询：

1. raw query2. normalized query3. matched canonical question4. highest-confidence variant

RAG 的难点不是把问题改写得越多越好，而是只增加能提高召回、不会引入噪声的表达。

5. hard negatives 是防误召回的关键

召回只看“命中正确答案”是不够的，还要看“相似但错误的问题不会命中”。

比如“合同怎么续签”和“合同怎么签署”很接近，但业务含义不同。前者问生命周期续约，后者问签署流程。如果系统总是把它们混在一起，答案看起来很像，实际却可能误导用户。

这就是 hard negative 的价值。

hard negatives 不只是评测数据，它会反过来塑造知识点边界。一个知识点越能说清“我不回答什么”，它越稳定。

6. Evidence Gate 比 prompt 更可靠

生产级 RAG 不应该把所有候选 chunk 都塞给 LLM，然后祈祷它自己判断。

Evidence Gate 要在生成前做决策：

这个环节决定系统是否有“不会答”的能力。

很多人喜欢追求“什么都能回答”的智能体，但企业场景里，敢于拒答比自信胡答更值钱。

7. LLM 接收的是文本证据，不是向量

一个容易混淆的问题是：RAG 召回重排后，发给 vLLM 的到底是什么？

答案是 final messages，也就是文本化后的证据上下文、用户问题、系统规则和引用编号。

流程是：

RAGFlow / Adapter 找到证据  -> 组织 source id、chunk text、metadata、source span  -> 打包进 final messages  -> vLLM tokenizer 编码成 input_ids  -> 模型生成 token  -> Adapter 汇总答案、sources、usage、audit

vLLM 不知道 Elasticsearch 里有哪些 chunk，也不知道哪个 evidence score 更高。它只看到 prompt。

因此，答案可信度不能只看模型文本。可信来源应该来自结构化的 rag.sources、retrieval trace 和 citation check。

8. 反馈闭环不是点赞按钮

“有用 / 无用”的反馈按钮只是入口，不是闭环。

真正的闭环应该是：

bad answer  -> 保存问题、命中证据、答案、引用和用户反馈  -> 判断是缺知识、召回错、重排错、引用错还是 prompt 错  -> 修正文档、Knowledge Point、query variants 或 hard negatives  -> 重新入库或重建索引  -> 用 golden questions 回归测试  -> 通过质量门后发布

这也是为什么我认为 RAG 项目必须保留“知识库工程”的角色。RAG 不是一次性导入文档后就自动变聪明，它需要持续整理、评测和修复。

好的知识库像一套可维护的产品文档，不像一个无人管理的文件夹。

9. 首版 PoC 应该验收什么

这个项目没有把首版目标放在高并发压测上，而是放在生命周期闭环上。我认为这个选择是正确的。

PoC 最应该验收这些能力：

这些验收项比单纯 QPS 更早决定项目能不能上线。

性能可以后置优化，可信度如果一开始没有框架，后面补会很痛。

10. 小结

RAG 的质量不是模型单点能力，而是知识生命周期能力。

文档要能准入，知识点要有边界，chunk 要能追溯，问法要能覆盖，负例要能约束，证据要能过门，答案要能引用，坏答案要能回到知识库修复。

我喜欢把这件事概括成一句话：RAG 不是让模型替文档管理还债，而是把文档管理变成可检索、可验证、可修复的工程系统。

下一篇会继续讨论产品化边界：企业 RAG 智能体卖的到底是什么，为什么 Internal/Web 要分开，以及为什么 Token 工厂应该作为并行产品线，而不是塞进 RAGFlow。

很多 RAG 项目失败，不是因为向量库选错了，也不是因为模型不够强，而是从第一天就把边界混在了一起：入口想做知识库，RAG 层想做计费，模型服务想决定是否联网，最后每个组件都变成半个控制面。

我越来越相信一件事：复杂系统的第一步不是加功能，而是让责任边界可解释。边界清楚以后，质量、性能、计费和商业化才有生长空间。

这篇文章结合一个 Model Agnostic RAG 知识库智能体项目，整理我认为更适合生产落地的架构：NewAPI -> Adapter / RAG LB -> RAGFlow -> Model Router -> vLLM。

1. 先说结论：不要首版自研完整 RAG 平台

这个项目的核心判断很克制：首版不自研完整 RAG 平台，而是采用 RAGFlow 承担文档解析、知识库、chunk、检索、rerank、引用和 Agent/workflow。

自研保留在一个很薄的 Adapter / RAG LB 上。它负责协议、策略、授权、审计、usage、sources 和 OpenAI-compatible 兼容，而不是重新造一套解析、入库、检索和编排系统。

这不是“技术上做不了自研”，而是生产节奏上的选择。首版最重要的不是证明我们能写一个向量检索服务，而是证明企业知识库智能体能完整闭环：入库、检索、回答、引用、拒答、联网授权、工具调用、日志审计和反馈修复。

2. NewAPI 只做入口，不做知识库

NewAPI 在这套架构里是唯一外部入口。它负责 API Key、渠道、模型名、额度、计费、日志和 Web 管理。

但它不应该直接连接 RAGFlow，也不应该理解 chunk、rerank、source span 或联网检索策略。NewAPI 是网关和商业入口，不是 RAG 控制面。

这层边界很重要。企业客户最终关心的是谁调用了、用了多少 token、走了哪个模型、是否扣费、能不能按租户和模型分账。这些是入口层的职责。

如果把知识库逻辑塞进 NewAPI，后续模型渠道、普通模型 API、RAG 模型 API、Token 工厂和计费报表会纠缠在一起。短期看省了一层，长期看会失去演进弹性。

3. Adapter 很薄，但不能省

Adapter / RAG LB 是 NewAPI 和 RAGFlow 之间的薄协议层。它看起来不起眼，但生产上非常关键。

如果只用一句话描述它：Adapter 是“外部 API 契约”和“内部 RAG 策略”之间的缓冲垫。外部继续使用稳定的 OpenAI-compatible 语义，内部则可以按租户、知识库、模型别名和授权策略去选择不同的 RAGFlow app。

它至少要稳定处理这些事情：

我的理解是，Adapter 不是为了“增加一层架构感”，而是为了隔离变化。RAGFlow 版本会变，Codex CLI 协议会变，NewAPI 上游格式也可能变。Adapter 是把这些变化挡在生产边界外的缓冲层。

4. RAGFlow 负责找证据，不负责生成 token

RAGFlow 的价值在于 RAG 本身：文档上传、解析、知识库管理、chunk、embedding、检索、rerank、citation 和 Agent/workflow。

它不负责 API Key，不负责统一计费，不负责普通模型售卖，也不负责 GPU 调度。

企业 RAG 智能体卖的是“基于企业知识的可信回答”。可信来自三件事：证据、引用、边界。

所以 RAGFlow 应该把精力放在证据质量上：文档解析是否稳定，chunk 是否可追溯，检索是否能召回正确片段，rerank 是否能把真正相关的证据排上来，引用能不能回到原文。

5. vLLM 只做推理，不保存知识

vLLM 在这里的角色也很清楚：加载模型权重，接收 final messages，生成 token。

它不会访问 Elasticsearch，不会查知识库，不会决定是否联网，也不会把聊天内容写入长期记忆。RAGFlow / Adapter 把证据组织进 prompt，vLLM 只基于上下文生成答案。

这句话听起来简单，但很多架构讨论会在这里混淆：模型“知道”某个答案，不等于企业知识库允许它回答；模型“可以”调用工具，不等于它应该自己决定是否把内部问题发到公网搜索。

在企业场景里，权限和证据优先于模型自由发挥。

6. 存储选型：首版先用 RAGFlow 默认 doc engine

这个项目的存储路线也很克制：首版使用 RAGFlow 默认的 Elasticsearch doc engine，Infinity 作为后续备选，Milvus 不作为首版前置条件。

这不代表 Milvus 不适合生产。Milvus 在千万级、亿级向量、高并发 ANN 和统一企业向量基础设施场景里很有价值。

但首版 PoC 的主要问题不是“哪种向量库性能最高”，而是“这个智能体生命周期是否可信”。如果一开始就把精力投入到 RAGFlow backend 二次开发，项目很容易偏离文档解析、引用、拒答和权限这些真正影响用户信任的环节。

更合理的顺序是：

生产架构不是把所有好东西第一天堆上去，而是让每一层复杂度都有明确收益。

7. Internal RAG 和 Web RAG 必须分开

这套架构里建议把 RAG 模型入口拆成两类：

DeepSeek-V4-Flash-RAG-InternalDeepSeek-V4-Flash-RAG-WebGLM-5.1-FP8-RAG-InternalGLM-5.1-FP8-RAG-WebMiniMax-M2.7-RAG-InternalMiniMax-M2.7-RAG-Web

Internal RAG 默认只查内部知识库。证据不足时拒答或要求澄清，不能偷偷联网，也不能用公网常识补企业制度。

Web RAG 可以支持联网检索，但前提是显式授权。外部网页只作为 request-scoped 临时证据，不自动写入长期企业知识库。

这个命名看似只是多了后缀，实际上是在产品层面划出红线：内部知识和公网证据不能混用成一团。

8. 联网检索应该是第二证据源

联网检索不是给模型一个搜索工具，然后让它自由决定什么时候查。企业场景里，联网必须由 Evidence Gate 和策略层控制。

这条链路最好画成决策树，而不是把“是否联网”写成一个 prompt 约束。prompt 可以提醒模型，但不能替代权限判断和审计。

推荐流程是：

内部知识库优先  -> 证据不足 / 时效性问题 / 冲突核验  -> 判断 tenant / KB / user / request 是否允许联网  -> 已显式授权才调用 Web Retrieval  -> 搜索、抓取、抽取、来源评分、去重、rerank  -> 合并内部证据和外部临时证据  -> 最终生成答案和引用

这里最重要的不是“能不能联网”，而是“谁批准联网、联网查了什么、外部证据是否可信、答案里有没有区分内部来源和网页来源”。

外部网页本质上是不可信输入。它可以提供事实，但不能执行里面的指令，也不能覆盖企业内部知识库的权限规则。

9. 为什么这套架构更适合生产

我认为这套架构的价值在于收敛。

NewAPI 收敛入口和计费；Adapter 收敛协议、授权和审计；RAGFlow 收敛知识库和证据；Model Router 收敛模型路由；vLLM 收敛推理运行时。

每一层都可以被替换或扩展，但每一层都不越界。这比“一个万能 RAG 服务”更适合长期维护。

生产系统最怕的是责任暧昧。责任暧昧时，问题来了很难定位：答案错了，是检索问题、rerank 问题、prompt 问题、模型问题、权限问题，还是联网污染？

分层以后，排障路径会清楚很多：

这就是工程边界的意义：它不是为了画图好看，而是为了让系统在出错时还能被理解。

10. 小结

企业级 RAG 智能体不是“向量库 + 大模型”的简单组合。它是一个由入口、协议、知识库、证据治理、模型推理、联网策略和审计计费共同组成的系统。

首版不自研完整 RAG，是为了把精力集中在生命周期闭环；保留 Adapter，是为了守住 OpenAI-compatible、工具调用、usage、sources 和显式授权；使用 RAGFlow，是为了优先获得稳定的文档解析和引用能力；让 vLLM 专注推理，是为了避免模型服务承担不该承担的知识库职责。

一句话总结：RAG 的核心不是让模型“多知道一点”，而是让系统能说明“答案依据是什么、谁有权看到、什么时候该拒答、哪些证据可以被追溯”。

下一篇会继续沿着这套架构往下走，重点讨论知识库如何从“上传一堆文档”变成“可评测、可修复、可拒答的知识生命周期”。

边缘机房的运维平台，真正困难的不是“能不能连上设备”，而是“连上以后如何安全地执行、如何记录、如何失败隔离、如何给用户一个可信的结果”。

这个 AIOps 项目已经把 PVE、Ceph、网络设备、裸金属、公网 IP、SNAT 映射和平台审计放进了同一个闭环。但闭环设计来自真实运维知识：哪些命令只能只读、哪些操作必须二次确认、哪些凭据不能落盘、哪些产物不能直接给 AI。

本文主要讲功能和实现方法，不展开源码。重点不是证明“AI 能写代码”，而是说明：没有足够的运维和安全知识储备，很难写出让 AI 稳定落地这类平台的提示词。

1. 为什么边缘运维要做成闭环

边缘机房通常具备几个特点：机房多、网络边界复杂、内网地址可能重复、资源类型不统一、现场凭据敏感、故障排查窗口短。

如果用脚本方式处理，短期很快，长期会遇到几个问题：谁执行的、执行了什么、失败在哪一步、产物在哪里、能不能重跑、有没有越权、是否泄露凭据。

AIOps 的设计目标，是把这些问题变成平台能力：

发起任务 -> 权限校验 -> 中心编排 -> edge-agent 执行 -> 结果回传 -> 产物归档 -> AI 分析 -> 平台审计

闭环的价值不只是自动化，而是可追溯、可治理、可交付。

这也是 AI 开发的第一道门槛。你必须先知道闭环里有哪些环节，才能要求 AI 去实现它们。只说“做一个自动化巡检”，AI 不会天然知道哪些场景需要失败隔离、哪些产物需要脱敏、哪些操作不能开放。

2. 这套闭环背后的工程量

边缘运维闭环不是几个脚本页面的组合，而是一个跨中心平台和边缘执行器的工程体系。按非空行粗略统计，整个 AIOps 项目约 2,957 个文件、30.7 万行工程内容，仓库文件清单约 3,100+ 个文件。

和边缘闭环强相关的部分主要集中在三块：后端约 2,067 个文件，负责模型、权限、审计、任务、产物和编排；前端控制台约 702 个文件，负责多资源域页面、表格、弹窗、导入导出和操作台；edge-agent 约 153 个文件，Python 非空行约 3.5 万行，负责真正进入边缘网络做受控执行。

从结构上看，后端有 69 个 Controller、112 个 Service 实现、143 个 DAO 接口；前端 src/pages 下约 258 个页面文件；edge-agent src 下约 82 个 Python 文件。这些数字背后，是大量“看不见但必须有”的生产细节：参数校验、状态机、异常分支、权限拒绝、审计脱敏、产物归档、版本兼容和边缘失败隔离。

所以，用 Claude+Codex 开发这套平台，并不是把一段脚本交给 AI 改成网页。它更像是让 AI 在明确架构和提示词约束下，持续完成一个多模块、多边界、多发布物的大工程。

3. PVE 虚机生命周期

PVE 虚机操作是高风险能力。平台没有把它设计成“输入 IP 后直接重启”，而是拆成解析、核对、确认、执行、审计几个步骤。

典型流程是：

这里的“重置”被定义为“先停止再启动”，而不是直接执行 PVE 硬 reset。定义清楚动作语义，可以减少生产误解。

这类定义不是 AI 自动想出来的，而是运维经验转成提示词后的结果。越是高风险动作，越不能让 AI 自由解释业务语义。

4. Ceph 巡检与 AI 分析

Ceph 巡检不是复用 PVE 巡检接口，也不是把 Ceph 当成 PVE 的一个字段。它被设计成独立资源模型和独立巡检类型。

平台支持两类 Ceph：

中心平台负责选择范围、解密凭据、调用 edge-agent、保存结果、生成 Excel/图表、触发 AI 分析。edge-agent 只执行白名单只读命令，并返回结构化 JSON。

这条边界能避免两个风险。

第一，中心平台不直接 SSH 到边缘节点，减少网络和凭据暴露面。

第二，edge-agent 不保存长期凭据和最终产物，不会变成边缘侧小数据库。

5. 网络设备巡检

网络设备巡检的关键不是“能跑命令”，而是命令必须白名单化、产物必须受控下载、私钥必须脱敏。

平台支持网络设备台账、测试连接、自测巡检、批量测试、批量禁用、导入导出和 SSH Key 批量更新。

SSH 认证分为两种模式：

巡检产物下载也有边界。edge-agent 只允许下载网络巡检输出目录下的合法产物，拒绝 _work 目录、临时私钥、路径穿越和输出根目录。

这类安全细节决定了网络巡检能不能用于生产。如果 artifact 里混入私钥或原始敏感输出，自动化越强，风险越大。

因此，AI 生成网络巡检能力前，提示词必须先锁死边界：只读命令、白名单 runtime、私钥脱敏、artifact 下载范围、失败设备隔离、ZIP 结构、AI 输入截断。少一个约束，都可能变成生产隐患。

6. 裸金属与配置中心同步

裸金属管理不是简单维护服务器列表，它还涉及节点状态、BMC、业务 IP、客户归属、批量分配、批量回收、电源操作和外部配置源同步。

平台里裸金属能力采用几个原则：

这些设计都来自生产场景。AI 开发时，如果只按“增删改查”实现，会漏掉大量状态机和运维边界。

7. 公网 IP 与 SNAT 映射

公网 IP 管理被放在边缘运维下，但它不是 edge-agent runtime 能力。公网 IP 是中心平台的权威数据，不需要 Agent 到网络设备上执行变更。

平台支持公网 IPv4 台账、CIDR 拆分、父子段关系、单 IP 分配、回收、删除、批量导入、运营商识别和审计。

SNAT 映射自动生成则是面向网络侧交付的能力：根据容器 IP 清单和公网 SNAT IP/CIDR 清单，轮询生成分组映射，保存不可变历史版本，并支持 Excel、TXT 下载和历史版本对比。

这类功能的重点是“生成可信交付物”，不是自动改防火墙。第一阶段不自动下发网络配置，是一个很重要的边界。

8. 平台操作审计

AIOps 把操作审计从“系统用户审计”升级成“平台操作审计”。审计域不只覆盖系统管理，也覆盖边缘运维等高风险模块。

审计页支持按审计域、模块、动作、状态、关键字和时间范围查询。表格保留操作者、目标用户、资源、状态、开始时间、耗时和详情入口。

生产审计要注意两件事。

第一，审计不是简单保存 HTTP 请求体。请求体里可能有密码、Token、私钥、OIDC 信息或验证码。平台只记录语义化快照和脱敏摘要。

第二，审计写入要覆盖成功和失败。失败记录同样重要，因为它能证明越权、参数错误、状态不允许等情况确实被平台拦截。

9. AI 分析如何接入

巡检的 AI 分析不应该把所有原始输出无脑塞进 prompt。这样既容易超长，也容易泄露敏感信息。

更合理的做法是使用任务摘要、设备状态、错误摘要、结构化 metrics 和经过截断的 resultJson。对网络巡检，默认不读取完整 raw 原始命令输出，也不直接下载 ZIP 给 AI。

这让 AI 分析更像“结构化诊断助手”，而不是“原始日志吞吐机”。它可以给出健康风险、异常项解释和排障建议，但不能替代白名单边界和人工确认。

换句话说，AI 在这里不是被放到生产系统里“自由判断”，而是被放到一个受控输入、受控输出、受控权限的诊断位置。这个边界设计比调用模型本身更重要。

10. 为什么这套方法适合 Claude+Codex

边缘运维闭环涉及很多跨层改动：前端页面、后端编排、权限 SQL、审计模型、Agent runtime、产物下载、AI prompt、发布文档和浏览器验证。

Claude+Codex 适合这种工作，因为它可以在同一个上下文里连续推进多个文件和多个模块。但要让它稳定产出，必须给出强约束：

先读设计文档。先确认目标和非目标。危险操作必须后端校验。凭据不得回显。SQL 必须幂等。edge-agent 变更必须同步版本和 capabilities。每轮变更必须写回开发流和发布说明。

这些约束把 AI 的产出从“能运行”推向“能上线”。

这里的含金量不在于“AI 帮我写了代码”，而在于你能把边缘运维的生产经验拆成清晰任务：哪些由中心平台负责，哪些由 edge-agent 负责，哪些必须进入审计，哪些必须拒绝，哪些必须在发布文档里提醒。

如果没有这些知识储备，即使模型能力很强，也只能生成一个看起来能跑、但很难上线的工具。

11. 小结

AIOps 边缘运维闭环的核心，不是把所有设备都接进来，而是把每一次查询、巡检、操作和分析都放进受控链路。

PVE 负责虚机生命周期，Ceph 负责存储巡检，网络设备负责只读网络巡检，裸金属负责节点和电源状态，公网 IP/SNAT 负责网络资源交付，平台审计负责把所有高风险动作串起来。

中心平台保存权威状态，edge-agent 做无状态受控执行，AI 分析基于脱敏结构化数据工作。这个组合，才是边缘运维从脚本走向平台化的关键。

这也是我认为 AI 开发真正有价值的地方：它让有经验的人把复杂系统更快落地，而不是让没有经验的人绕过系统设计、风险判断和生产验收。

很多人用 AI 写代码时，最容易遇到的问题不是“AI 不会写”，而是“AI 写得太快，边界没有跟上”。一个生产级 AIOps 平台，不能只看功能是否跑通，还要看权限、审计、SQL、版本、构建、部署、回滚和敏感信息是否都被管住。

这个 AIOps 项目已经完成上线，代码实现由 Claude+Codex 完成。这里说的“AI 开发”，不是把一句话丢给模型，也不是小白复制提示词就能交付生产平台。它需要先具备足够的运维、架构、权限、安全、发布和验收经验，再把这些经验转成 AI 能执行的提示词和工程规则。

本文重点讲开发方法，不贴源码，讨论如何用脚手架、提示词和文档约束，让 AI 从需求一路推进到可交付版本。

1. 一行代码不写，不等于没有工程门槛

如果只对 AI 说“帮我做一个公网 IP 管理功能”，它很可能先生成页面，再补接口，最后留下权限、审计、导入模板、SQL 幂等和发布文档的缺口。

所以第一道门槛不是写代码，而是知道一个生产功能应该包含哪些部分。没有这层知识储备，AI 生成得越快，缺口越隐蔽。

更稳的方式，是把 Codex 当成一个工程团队来管理。每个需求进入开发前，都要先回答这些问题：

这些问题回答清楚以后，AI 写代码才不会散。

这也是为什么“一行代码不写”并不等于“任何人都能做”。真正难的是把隐性的生产经验显性化，再让 AI 按这个结构执行。

2. 工程规模越大，越需要提示词纪律

这个项目最终不是一次性生成的小工具，而是一个 30 万行级别的生产工程。按非空行粗略统计，排除常见构建产物、依赖目录和图片资产后，仓库仍约有 2,957 个文件、30.7 万行工程内容。

其中后端 Java 约 10.6 万行，前端 TS/TSX 约 7 万行，edge-agent Python 约 3.5 万行；后端包含 42 个 Maven 模块/聚合、69 个 Controller、112 个 Service 实现、143 个 DAO 接口；前端 src/pages 下约 258 个页面文件；边缘 Agent src 下约 82 个 Python 文件。

前端目录还包含部分静态运行时资产，所以不能把所有行数都简单理解为业务代码。但这个体量足以说明一件事：AI 不是在替人写几个函数，而是在一个跨前端、后端、数据库、边缘执行器、文档和发布流程的大工程里持续协作。

规模一上来，提示词就不能只写“帮我实现某功能”。它必须变成工程约束，明确菜单、权限、SQL、审计、版本、敏感信息、测试、截图和发布文档，否则每一轮自动生成都可能扩大债务。

3. 先搭脚手架，再谈 AI 速度

AI 适合在清晰边界内高速推进，不适合在一片空地上替人决定所有工程秩序。

这个项目能用 Claude+Codex 持续开发，前提是先搭好了基础脚手架：

有了这些地基，AI 才能像工程团队一样扩展功能。没有这些地基，AI 只能不断生成局部补丁。

4. 提示词要先约束边界

这个项目里最重要的提示词约束，不是“代码写得优雅”，而是“哪些事情不能做”。

提示词不是模板魔法。高质量提示词背后，是对业务、架构和生产风险的理解。你必须知道哪些字段敏感、哪些操作危险、哪些状态不能跳过、哪些发布动作会影响线上，才能写出有效约束。

典型约束包括：

不要泄露真实 IP、客户名、主机名、密码、Token、私钥。不要把构建产物、node_modules、target、dist 长期留在项目目录。不要只做前端隐藏，危险操作必须后端强校验。不要使用 latest、local 或长后缀 tag 作为生产版本。不要把 edge-agent 当成有状态数据库或任务中心。不要把任意 shell 执行能力暴露给边缘 Agent。

这些“不要”比“要实现什么”同样重要。它们决定了平台最终是不是生产系统，而不是演示项目。

5. 开发流文档是 AI 项目的记忆

AIOps 项目里，每个重要功能都有设计文档和开发进度文档。它们不是形式主义，而是长周期 AI 开发的记忆系统。

例如边缘运维能力会记录：设计结论、目标、非目标、菜单结构、总体架构、责任边界、数据模型、安全策略、接口草案和验收清单。

开发流则记录每轮变更：

阶段：本轮目标：修改范围：测试命令：测试结果：风险：下一步：

这样做有两个好处。

第一，Codex 在下一轮开发时可以从文档恢复上下文，不需要靠聊天记录猜测历史决策。

第二，人工验收时能快速判断这轮改动是否越界，是否漏掉 SQL、权限、版本或发布说明。

6. 需求拆分必须包含非目标

生产项目里，非目标经常比目标更重要。

以 Ceph 巡检为例，目标是通过 edge-agent 做只读采集，中心平台生成 Excel、统计图和 AI 分析。非目标则包括：不让中心平台直连边缘 SSH、不开放任意 shell、不执行 Ceph 变更命令、不复用 PVE runtime 接口、不把历史脚本目录打进生产镜像。

这些非目标能防止 AI 为了“快速实现”做出危险捷径。

再以公网 IP 管理为例，第一阶段只做 IPv4 公网 IP 台账、CIDR 拆分、客户分配、回收、批量导入和运营商识别，不做 IPv6 地址池展开，不自动下发防火墙，不做带宽计费。

功能越复杂，越要把第一阶段范围压清楚。

7. 前端、后端、SQL、权限要一起验收

AIOps 这类平台常见的问题是“页面看起来完成了，但生产不能用”。原因通常是其中一层没闭环。

一项功能至少要同时检查：

Codex 可以同时改多层，但验收时必须按层拆开看。

这里的验收能力也是门槛。你要能看懂接口返回、构建日志、SQL 升级结果、权限缓存、浏览器截图和容器镜像 tag。否则 AI 说“完成了”，你也无法判断它是不是真的能上线。

8. 浏览器截图是很有效的验收方式

在这个项目里，截图不是为了好看，而是为了发现真实 UI 问题。

比如搜索栏是否拥挤、表格横向滚动条是否可见、按钮是否越权展示、弹窗是否能表达二次确认、页面是否仍显示旧版本文案，这些问题靠读代码不一定能发现。

平台中也保留了前端自动截图工作流：扫描路由、自动登录、截取页面、收集 DOM 摘要和可访问性树。这样 AI 可以用截图和 DOM 反向分析页面结构，再给出修复建议。

9. edge-agent 变更要单独上锁

AIOps 的边缘能力依赖 edge-agent。只要变更涉及 runtime、capabilities、API 入参/出参、内置脚本或运行时资产，就必须把 edge-agent 纳入发布影响面。

典型场景包括：

这条规则能避免一个常见生产事故：backend/frontend 已升级，但边缘 Agent 仍是旧版本，结果页面有按钮，后端有接口，实际边缘执行失败。

10. 版本和发布规则要写死

AI 开发很容易产生很多临时版本名，例如带日期、功能名、环境名或 SNAPSHOT。这对生产交付很危险。

AIOps 的版本规则被固定为：

backend/control：v0.1.xfrontend：v1.0.xedge-agent：v1.1.x

生产镜像 tag 必须是 vX.Y.Z。禁止使用 latest、local、日期后缀、功能名后缀、环境名后缀或覆盖旧 tag。

发布文档也必须记录：组件版本、是否包含 MySQL 变更、SQL 文件清单、升级步骤、验证步骤、回滚方案和用户侧注意事项。

11. AI 开发的真正优势

Claude+Codex 的优势不是少写几行代码，而是能在同一轮工作里完成多层联动。

一个需求从设计到上线，可能同时涉及前端页面、后端接口、DAO、SQL、权限、审计、测试、文档、升级手册和截图验收。传统开发里这些工作容易分散到多人、多天、多次沟通。AI 适合在明确边界内连续推进。

但前提是人要把目标和边界说清楚。AI 越强，越需要明确约束，否则它会用很高的效率扩大错误。

当工程规模达到数千文件、数十万行时，真正节省的不是某一个接口的编码时间，而是跨模块联动的上下文切换成本。Codex 可以把“改页面、补接口、加 SQL、更新权限、写文档、跑验证”放在同一条工作流里完成，人的重点则转向设计、约束和验收。

这类项目的含金量，恰恰在于人能把复杂系统拆成 AI 可执行的任务，并持续判断 AI 的产出是否满足生产标准。

12. 小结

用 Claude+Codex 开发生产级 AIOps，我认为最关键的是 5 件事。

第一，先有知识储备和脚手架，再谈 AI 开发速度。

第二，先写设计和非目标，再让 AI 执行。

第三，把提示词约束写成工程规则，尤其是安全、权限、版本、发布和敏感信息。

第四，开发流文档必须持续更新，让 AI 项目有长期记忆。

第五，前端、后端、SQL、权限、审计和发布要一起验收。

第六，截图和浏览器冒烟要进入流程，因为真实页面能暴露很多代码审查看不到的问题。

AI 可以写完整个平台，但生产边界必须由工程纪律来守住。所谓一行代码不写，不是没有能力门槛，而是把能力从“敲代码”迁移到“定义系统、约束系统、验收系统”。

AIOps 平台最难的地方，不是把页面做出来，也不是把接口跑通，而是把“运维入口、边缘资源、权限审计、巡检产物、发布升级”放进同一个可长期维护的体系里。

这个项目已经完成开发并上线。整个代码实现由 Claude+Codex 驱动完成，人工没有逐行手写业务代码，但这不代表没有门槛。真正的门槛在于：能不能把运维经验、架构判断、基础脚手架、提示词约束、测试验收和生产发布规则讲清楚。

本文不展开源码，而是从产品功能、架构分层和实现方法看这个平台是怎么落地的。它更像一篇“AI 驱动生产开发复盘”，不是一篇“小白复制提示词就能做平台”的教程。

1. 项目规模：不是 Demo 工程

这不是一个只有几个页面、几个接口的演示项目。按非空行粗略统计，在排除 node_modules、target、dist、缓存目录和博客图片资产后，项目仍约有 2,957 个文件、30.7 万行工程内容；如果按仓库文件清单看，全仓约 3,100+ 个文件。

这个数字不等同于“全部都是人工手写业务代码”，前端目录也包含部分静态运行时资产。但从模块数量、联动范围和发布物数量看，它已经是一个完整的生产级平台工程。

这意味着 Claude+Codex 不是在补一个页面，而是在同时维护前端体验、后端编排、权限模型、SQL 升级、边缘执行、审计闭环、发布文档和脱敏资料。

也正因为项目体量足够大，AI 开发的价值才体现出来：它能在清晰约束下快速推进多模块联动。但人的架构判断、领域知识和验收能力也必须同步放大，否则代码生成速度越快，失控范围也越大。

2. 先定义平台边界

这个 AIOps 平台不是单点脚本工具，而是面向多机房、多资源域、多角色的运维控制台。

它覆盖的能力包括告警、CI/CD、数据库、通知、资产、边缘运维、系统管理、用户设置等模块。其中最有生产价值的部分，是把边缘机房里的 PVE、Ceph、网络设备、裸金属、公网 IP 和巡检任务统一纳入中心平台。

平台的核心定位可以概括成一句话：

中心平台负责状态、权限、审计和编排；边缘 Agent 负责受控执行。

这个边界非常重要。只有中心平台掌握权威数据，后续的审计、权限、回滚、升级和多租户治理才不会散掉。

3. 总体架构

平台采用“中心编排 + 无状态边缘执行”的结构。前端控制台访问后端 API；后端保存机房、Agent、凭据、任务、产物和审计；edge-agent 部署在边缘机房内，负责访问本地 PVE、Ceph、网络设备和裸金属资源。

这张图里最关键的是 4 条线。

第一条是用户入口线。运维人员通过控制台发起操作，外部系统可以通过开放 API 对接告警、资产或自动化流程。

第二条是平台运行时线。Backend App 承载业务编排，Control Service 承载租户和权限能力，后端内部模块按 system、tenant、ops、asset、project、notice、plugins 等能力域组织，但它们不是独立部署服务。

第三条是数据与异步线。MySQL 保存业务数据、权限和审计；Redis 保存会话和权限缓存；MinIO 保存巡检产物、导入导出文件；RocketMQ 用于异步消息和任务解耦。

第四条是边缘执行线。中心平台通过受控 API 调用 edge-agent，edge-agent 在机房内网访问 PVE、Ceph、网络设备、裸金属等资源，并把结构化结果回传给中心。

4. 功能域怎么拆

AIOps 的菜单不是简单堆功能，而是按平台职责拆分。

EfficiencyManagement 用于效率看板和指标概览。它适合做管理视角的入口，让用户先看到告警存量、处理状态和团队效率趋势。

Alert 和 Notification Center 承载告警、分派策略、通知渠道和通知记录。它们是运维事件进入平台后的第一层治理。

CI/CD 和 Asset 负责交付和资产底座。代码源、制品、集群、模板、变量等能力都在这里沉淀，避免每个业务模块重复维护基础配置。

Edge Operations 是这个项目的重心，包含机房、Agent、PVE 集群、Ceph 集群、虚机清单、虚机操作台、裸金属节点、裸金属操作台、任务历史、自动化巡检和网络运维。

Settings 负责角色、用户、群组、系统日志、系统属性、SSO 配置和 AI 诊断配置。高风险动作都要进入这里的权限和审计体系。

5. 边缘 Agent 为什么必须无状态

边缘机房常见问题是网络边界复杂、内网地址重复、机房数量多、资源类型混杂。如果中心平台直接保存一堆临时脚本和本地缓存，很快会变成不可控的运维黑盒。

因此 edge-agent 被设计成无状态执行器：

这个设计带来一个直接好处：边缘侧可以横向部署多个 Agent，但权威状态始终在中心平台。Agent 出问题可以重启或替换，不会丢失任务历史和审计链路。

6. 生产功能不是“能点按钮”就结束

平台里很多能力看似只是按钮，但生产实现必须补齐闭环。

例如虚机操作台不是简单调用 PVE API。它需要先选择机房，输入虚机 IP，解析候选虚机，再让用户核对 VMID、节点、虚机名、IP、当前状态，最后执行启动、停止或重置。

公网 IP 管理也不是一张 Excel 表。它要支持 CIDR 规范化、父子段拆分、单 IP 状态、分配历史、回收、删除、批量导入、运营商识别和审计。

自动化巡检也不是跑一段脚本。它要支持 PVE、Ceph、网络设备等不同巡检类型，按机房和 Agent 分组执行，允许部分成功，保存 Excel、ZIP、JSON 等产物，并接入 AI 分析。

这些细节决定了平台能不能真的上线，而不是只停留在演示环境。

7. 一行代码不写，人的角色不是消失

这个项目的代码由 Claude+Codex 完成，但并不意味着“给一句需求，然后等它自己写完”。真正有效的方式，是把 AI 当成一个可以持续执行的工程团队，同时用人的经验给它搭好边界。

“一行代码不写”的含义，是不把人的精力消耗在重复编码上。人的工作前移到更高层：判断系统怎么拆、哪些动作危险、哪些数据不能泄露、哪些组件需要联动升级、哪些测试能证明上线安全。

人工主要做 5 件事：

Codex 负责把这些约束转成代码、文档、测试、构建脚本和升级记录。

这种协作方式的重点不是让 AI “自由发挥”，而是把自由发挥限制在工程边界内。

8. 最关键的工程经验

第一，先有知识储备，再写提示词。提示词不是口号，而是把业务经验、架构经验和生产事故经验结构化表达出来。

第二，先搭基础脚手架，再让 AI 扩展功能。菜单、路由、权限、后端分层、SQL 规则、镜像版本、文档入口，这些地基不稳，AI 写得越快，返工越多。

第三，先写设计文档，再让 AI 开发。没有设计文档，AI 容易只补当前缺口，忽略状态机、权限、审计和发布路径。

第四，每个功能都要有开发流文档。开发流记录目标、修改范围、测试命令、测试结果、风险和下一步，避免长周期项目丢上下文。

第五，前端、后端、SQL、权限必须同步。只做页面按钮没有意义，后端不校验权限就有越权风险；只做后端接口也不够，菜单和角色权限不更新，用户看不到入口。

第六，edge-agent 相关能力必须单独判断发布影响。如果功能依赖 Agent runtime、capabilities、内置脚本或返回字段，就不能只升级 backend/frontend。

第七，发布版本必须有纪律。生产镜像 tag 使用 vX.Y.Z，不能使用 latest、local、日期后缀或功能名后缀。

9. 小结

这个 AIOps 平台的落地经验可以总结为三点。

第一，平台架构要先把中心状态和边缘执行拆开。中心平台保存权威数据，edge-agent 做无状态受控执行。

第二，功能设计要围绕生产闭环。权限、审计、导入导出、失败处理、产物归档和升级回滚，和页面按钮一样重要。

第三， Claude+Codex 可以完成完整工程实现，但前提是知识储备、脚手架、需求约束、测试用例和发布纪律足够清晰。AI 负责产出，人负责判断和边界。

所以，这个项目的含金量不在“少写了多少代码”，而在**“把一个复杂运维平台拆成 AI 能稳定执行、能验收、能上线的工程系统”**。

AI 集群上共享文件系统的规划，不能只问“需要多少 PB”。真正决定落地规模的变量至少有 4 个：GPU 客户端数量、总吞吐目标、总文件数、故障域与容量水位。

本文以千卡级 AI 集群为例，整理 JuiceFS 方案评审时最容易混淆的几个问题：Gateway/Cache 到底跟谁扩展，Meta 是按文件系统数量算还是按总文件数算，社区版和企业版在超大命名空间下该怎么选。

1. 先拆开 4 个维度

容量由对象存储层决定。对象存储节点数量受总容量、EC 策略、目标水位、磁盘规格和故障域影响。

接入层由 GPU 客户端规模和吞吐目标决定。Gateway、Cache 或等价接入组件不应该简单按文件系统个数乘，而应该看并发客户端、热点数据、回源带宽和业务峰值。

Meta 由总文件数、目录层级、元数据访问压力和产品形态决定。文件系统数量只是隔离和治理维度，不会自动把总元数据量变小。

文件系统拆分由命名空间、权限隔离、故障域、团队边界和运维复杂度决定。一个文件系统更简单，多个文件系统更利于隔离，但也会增加配额、凭据、挂载和数据治理成本。

2. 容量规划公式

对象存储容量可以按以下公式估算：

单节点原始容量 = 单盘容量 * 单节点数据盘数量EC 后逻辑容量 = 单节点原始容量 * data_chunks / (data_chunks + parity_chunks)目标可用容量 = 节点数 * EC 后逻辑容量 * 目标水位

例如一台存储节点有 24 块 7.68TB NVMe，采用 EC 8+2，则单节点原始容量约为 184.32TB，EC 后逻辑容量约为 147.456TB。若按 80% 水位规划，每节点可承载的规划容量约为 117.96TB。

如果目标是 16.5PB 级逻辑容量，按 80% 水位反推，存储节点下限约为 140 台。这个数字只是容量口径，还没有包含后续扩容余量、故障恢复、热点倾斜和业务峰值冗余。

3. 故障域要和容量水位一起看

“允许两个 rack 临时故障”与“两个 rack 永久丢失仍可无感恢复”不是一回事。

如果两个 rack 是临时故障，并且故障期间通过 Ceph 运维策略避免立即回填，集群可以在降级状态下维持业务，等待故障 rack 恢复后再回到正常水位。

如果两个 rack 永久丢失，则必须重新计算剩余节点容量、水位和恢复策略。此时要么补节点，要么接受水位上升和恢复窗口变长，不能把临时故障口径直接写成永久容灾能力。

下面这张图把 16.5PB 容量下限、140 台节点、12 台/rack 和 2 个 rack 故障口径放到同一个视图里。这样可以避免把“临时降级运行”误写成“永久容灾能力”。

生产规划里建议明确 3 个值：

4. Gateway 与 Cache 跟随客户端规模

很多方案评审会把 Gateway/Cache 误解成“每个文件系统固定几台”。这在小规模场景里看似成立，但到千卡级 AI 集群就会失真。

Gateway/Cache 更合理的驱动因素是 GPU 客户端数量、并发训练任务、数据集热点、回源带宽和读写峰值。

例如按“每 100 个 GPU 客户端配置 4 台 Gateway、1 台 Cache”的经验口径，千卡级集群的接入层大约需要 40 到 44 台 Gateway、10 到 11 台 Cache。无论最终是 1 个文件系统还是多个文件系统，接入层都要服务同一批 GPU 客户端和吞吐目标。

下面这张图说明 Gateway/Cache 是跟随 GPU 客户端和吞吐目标扩展，而不是跟文件系统数量简单相乘。文件系统数量影响隔离方式，接入层总规模仍要回到客户端规模。

如果只部署 1 个文件系统，Gateway/Cache 可以共同服务同一个命名空间。如果拆成多个文件系统，可以按业务组、训练队列或数据域把 Gateway/Cache 自然切分，但总规模仍要回到客户端和吞吐需求上。

5. Meta 按总文件数估算

Meta 规划最容易混淆的是“文件系统数量”和“总文件数”。

如果总文件数不变，只是从 1 个文件系统拆成 10 个文件系统，Meta 总量不会自动乘以 10。真正让 Meta 明显放大的，是总文件数从 500 亿变成 5000 亿。

在一次保守方案估算里，可以使用以下经验口径：

1 亿文件 >= 30GB Meta 内存

按这个口径，500 亿文件约需要 15TB Meta 内存。如果单台 Meta 节点内存为 1.5TB 左右，理论下限约 10 台，工程上建议按 12 到 16 台规划。

如果是 10 个文件系统，每个都要求 500 亿文件，总文件数会变成 5000 亿。此时 Meta 内存估算约为 150TB，已经是完全不同的工程规模，节点数量可能需要按 100 到 140 台级别重新评估。

这个估算不是通用承诺。真实 Meta 规模还会受到文件名长度、目录深度、扩展属性、ACL、快照、文件变更频率和产品版本影响。正式方案要结合厂商 sizing、压测和容量增长模型复核。

6. 1 个文件系统还是多个文件系统

1 个大文件系统的优势是命名空间统一、业务迁移简单、训练任务不用处理多挂载点。适合数据域清晰、权限模型简单、希望统一治理的数据平台。

多个文件系统的优势是隔离更强。不同业务可以拥有独立 Volume、独立挂载 Token、独立 Bucket、独立对象存储凭据、独立配额和审计策略。适合多租户、多团队、强权限边界或不同生命周期的数据域。

但是多个文件系统不是免费的。它会增加凭据分发、挂载管理、数据复制、跨域访问、监控告警和运维排障复杂度。尤其是“每个文件系统都要承载数百亿文件”时，Meta 规模要按总文件数重新计算。

7. 社区版与企业版选择

社区版适合通用共享文件系统、对象存储接入和常规规模场景。Redis、TiKV、MySQL/PostgreSQL 等元数据后端各有适用边界，部署前要按文件数、并发和可用性目标评估。

当需求明确指向单文件系统数百亿文件、正式 SLA、分布式缓存、超大规模元数据和统一命名空间时，更合理的评审方式是引入企业版能力做 sizing。此时要关注分布式元数据、分布式缓存、主动失效、容量扩展和服务支持边界。

可以把方案分成 4 类：

如果原始需求是“一个统一文件系统承载数百亿文件”，优先评估企业版 1FS。如果需求是“多个租户必须强隔离”，再评估企业版多 FS，并按总文件数重新计算 Meta。

8. 生产落地建议

第一，容量层按水位和故障域规划，不要只按裸容量除一下。至少保留正常水位、临时故障水位和扩容触发水位。

第二，接入层按 GPU 客户端规模和吞吐规划。Gateway/Cache 要随着客户端并发扩展，不要被文件系统数量误导。

第三，Meta 按总文件数规划。拆分文件系统是隔离手段，不是减少总元数据的手段。

第四，读多写少数据集要重视 Cache、warmup 和热点治理。checkpoint、小文件和中间产物要单独建模，不要混在同一个平均吞吐目标里。

第五，所有容量和性能数字都要经过业务压测闭环验证。方案估算只能决定初始规模，不能替代真实 workload 验证。

9. 小结

千卡级 AI 集群的 JuiceFS 规划，核心不是“1FS 还是 10FS”这个表面选择，而是把容量、接入、Meta、缓存和隔离拆开计算。

对象存储节点主要跟容量、水位和故障域走；Gateway/Cache 主要跟 GPU 客户端和吞吐走；Meta 主要跟总文件数走；文件系统数量主要跟权限、命名空间和治理边界走。

只要这 4 条线拆清楚，方案评审就不会被“文件系统数量”和“节点数量”的简单乘法带偏。

参考资料：

• JuiceFS Architecture
• JuiceFS Cache
• JuiceFS Command Reference
• JuiceFS Redis Best Practices
• JuiceFS Enterprise Edition

存储压测最容易踩的坑，是把不同测试口径的数字放在一张表里直接排名。对 JuiceFS 这类“客户端 + 元数据引擎 + 对象存储”的架构来说，顺序读写、随机读写、延迟约束、客户端缓存、对象存储回源、元数据压力都会影响结果。

本文只讨论客户端视角的压测方法和可公开汇总数据。原始终端截图不会直接公开；下文复用的是从项目报告中提取后裁剪脱敏的客户端 fio 结果片段，已去掉主机名、挂载路径、命令 prompt 和工具栏。

1. 为什么要从客户端视角看

业务真正感知到的是客户端返回的吞吐、IOPS 和延迟，而不是存储集群后台某个监控面板上的聚合值。服务端聚合带宽可以证明后端集群有能力承载流量，但不能直接说明单个训练任务、单个数据加工任务或单个挂载点的体验。

客户端视角要回答 4 个问题：

1. 大块顺序写能否支撑 checkpoint、归档和大文件生成。
2. 大块顺序读能否支撑训练样本扫描、模型权重加载和批处理读取。
3. 4K 随机写能否承受小文件、索引、日志和元数据密集写入。
4. 4K 随机读能否承受小样本、索引查询和随机访问。

如果只看顺序读，很容易高估系统能力；如果只看 4K 随机写，又会低估对象存储后端在大文件场景里的价值。

2. 测试矩阵设计

建议至少保留两个测试矩阵。

第一组是吞吐与 IOPS 基线：

第二组是延迟受控测试。它不追求最大吞吐，而是把延迟压在业务可接受范围内，观察在该约束下能给多少吞吐或 IOPS。

压测命令要固定并记录 bs、iodepth、numjobs、runtime、direct、文件大小、文件数量、挂载参数和缓存状态。否则同一套系统不同轮次之间也不能直接比较。

3. JuiceFS 客户端结果摘要

以下数据来自客户端侧汇总表，单位已统一。过程截图中的局部值属于不同轮次或不同参数组合，公开稿以汇总表为准。

延迟受控轮次如下：

这组结果的第一结论不是“某个数字绝对好或坏”，而是读写画像很清楚：顺序读和随机读表现更突出，写入路径更受对象上传、元数据提交、flush、缓存策略和后端写入能力影响。

3.1 JuiceFS 客户端截图

以下截图来自项目报告中的客户端 fio 结果，已做公开版裁剪，只保留测试结果区域。

4. NFS 客户端对照结果

为了避免跨口径误读，这里只放物理客户端汇总表中可以公开表达的 NFS 客户端观测值，不引入服务端聚合截图。

延迟受控轮次如下：

这张表只能作为同类测试项的参考，不能扩展成“所有场景下 NFS 与 JuiceFS 的绝对优劣”。NFS 的实现方式、服务端导出参数、客户端数量、缓存状态、网络路径和后端磁盘都会改变结果。

4.1 为什么加一层 NFS 后会变慢

本次 NFS 口径里，客户端不是直接访问后端分布式存储能力，而是先访问 NFS 导出层，再由 NFS 服务端访问后端存储。链路从“客户端并发访问存储后端”变成了“客户端 -> NFS 服务端 -> 后端存储”，多了一次协议转换、一次网络转发和一层服务端调度。

这层 NFS 服务端会变成明显的收敛点。即使后端存储集群具备更高聚合带宽，客户端看到的吞吐也会受 NFS 服务端 CPU、内存、网卡、内核 NFS 线程、导出参数、页缓存、单连接/多连接行为和后端挂载性能限制。换句话说，后端有多强，不等于经过 NFS 导出后客户端就能吃满。

写入场景尤其容易被放大。NFS 需要处理客户端请求、权限检查、锁、属性更新、写入提交和缓存一致性；如果导出配置偏同步、服务端后端写入延迟偏高，1M 顺序写和 4K 随机写都会被服务端等待链路拖慢。小块随机写还会进一步放大 RPC 次数和元数据更新次数，所以随机写 IOPS 往往比直连或客户端原生并发路径更难看。

读取场景也不是总能靠缓存解决。热数据可能被 NFS 服务端页缓存加速，但冷读、跨客户端读、随机读和缓存失效后仍要回到后端存储。多客户端并发读取时，NFS 服务端既要承担网络出口，又要承担后端读取和缓存管理，很容易从“共享入口”变成“共享瓶颈”。

因此，这里看到的 NFS 性能偏低，并不是简单说明“NFS 协议一定差”，而是说明在本项目这种二次导出链路下，NFS 更适合作为兼容性入口或少量通用共享目录，不适合作为高并发 AI 数据面主路径。AI 训练、样本扫描、checkpoint 和大量小文件读写，应该优先让客户端直接接入 JuiceFS/CephFS/对象存储网关等能横向扩展的数据路径。

4.2 NFS 客户端截图

以下截图同样来自项目报告中的物理客户端 fio 结果，已做公开版裁剪。它们用于证明对照数据的来源，不引入服务端监控聚合图。

5. 如何解释这组数据

JuiceFS 顺序读表现较好，通常来自对象存储并发读取、客户端 buffer、预读和缓存的组合收益。读多写少的数据集、模型权重、训练样本扫描更容易发挥这类优势。

JuiceFS 写入要经历客户端 buffer、对象存储上传、元数据提交和 flush 过程。对于小文件随机写，写入延迟更容易受对象存储回写、元数据压力和文件碎片影响。大量小文件写入时，不要只调大并发，还要观察 Redis 延迟、RGW 上传延迟、客户端 buffer 是否拥塞。

NFS 对照结果则说明，给后端存储再包一层通用文件共享入口，会牺牲一部分横向扩展能力。它能降低客户端接入复杂度，但也把并发、缓存、锁和网络出口集中到 NFS 服务端，适合通用共享和兼容性场景，不适合把高并发训练数据面全部压在这一层。

--prefetch 和 --max-readahead 对顺序读、局部随机读有帮助，但也可能引入读放大。读取稀疏大文件时，预取过大反而会浪费对象存储带宽。

--cache-size 可以提升重复读取和随机读体验，但本地缓存不等于端到端数据保护。对缓存盘可靠性敏感的场景，要评估 --verify-cache-checksum 等完整性策略。

--writeback 能改善某些小文件写入体验，但会把数据可靠性压力转移到本地缓存盘。关键数据、跨节点共享和生产强一致场景不要轻易启用。

6. 面向 AI 业务的映射

训练数据集通常以读为主。如果数据集已经固化，可以使用缓存盘、预热和较大的 readahead 提高吞吐。此时重点观察顺序读、随机读、cache hit、对象存储回源带宽。

checkpoint 是大块写入，对象存储写带宽、flush 延迟和写入并发更关键。此时要重点观察 1M 或更大块顺序写、尾延迟、失败重试和写入完成后的跨客户端可见性。

小文件样本和索引会放大元数据压力。此时 4K 随机读写只是一个近似入口，还要补充真实目录层级、文件数量、文件大小分布和并发客户端数。

日志、临时文件和中间产物不一定适合全部放入共享文件系统。高频短生命周期数据可以考虑本地盘、临时卷或专门的缓存层，最终产物再落 JuiceFS。

7. 小结

JuiceFS 压测要从“客户端实际体验”出发，而不是追求单个最大数字。顺序读、顺序写、随机读、随机写、延迟受控轮次要分别解释。

参考资料：

• JuiceFS Benchmark and Profiling
• JuiceFS Cache
• JuiceFS Command Reference
• JuiceFS Fault Diagnosis and Analysis

在 AI 训练、数据湖、离线分析和多节点共享数据场景里，单机文件系统很快会遇到容量、并发和多客户端一致性问题。JuiceFS 的价值在于把文件系统语义拆成两层：元数据放在独立的 Metadata Engine，文件数据切块后落到对象存储。

本文以 Redis Cluster + Ceph RGW/S3 + JuiceFS Client 的组合为例，整理一套可以落地的生产部署方法。文中的地址、凭据、卷名、Bucket 和路径均使用占位符，实际发布和交付时不要把真实环境信息写入文档、命令历史或截图。

1. 架构拆分

这套架构可以分成 4 个平面。

第一层是业务客户端。训练任务、推理服务、数据加工任务通过 POSIX 接口访问挂载点，不需要感知对象存储的分片、命名和生命周期。

第二层是 JuiceFS Client。客户端负责 FUSE 挂载、元数据访问、读写缓冲、预读、本地缓存、对象上传下载和后台任务。

第三层是 Redis Cluster。Redis 保存文件名、目录树、inode、权限、chunk/slice/block 映射、会话等元数据。Redis 需要按核心生产组件对待，必须做持久化、备份、访问控制和容量监控。

第四层是 Ceph RGW/S3。对象存储保存真实数据块。RGW 可以通过同一个 Ceph 集群、同一个 RGW zone 内的多个入口做负载均衡，但不要跨异步复制 zone 或跨独立集群做同一个 JuiceFS 卷的数据入口。

2. 生产前置条件

Redis Cluster 要开启持久化，并设置 maxmemory-policy noeviction。如果 Redis 因内存策略主动淘汰元数据，文件系统会出现严重风险。Redis 的 RDB/AOF、快照、备份恢复演练都要纳入常规运维。

Ceph RGW 建议启用 HTTPS，对外提供稳定的 S3 endpoint。内网测试环境可以使用 HTTP，但公开最佳实践不要把 HTTP 写成生产推荐。Bucket 建议按文件系统隔离，至少要做到不同业务使用不同访问凭据。

JuiceFS Client 建议统一版本，并在上线前完成 juicefs bench、业务 fio/vdbench、长稳读写、重启自动挂载、元数据恢复、RGW 故障切换等验证。

3. 文件系统创建示例

创建文件系统时，命令里不要直接写真实密钥。更稳妥的做法是通过受控的环境变量、密钥管理系统或 systemd EnvironmentFile 注入。

export META_PASSWORD='<redis-password>'export S3_ACCESS_KEY='<s3-access-key>'export S3_SECRET_KEY='<s3-secret-key>'juicefs format \  --storage s3 \  --bucket https://<bucket>.<rgw-domain> \  --access-key "$S3_ACCESS_KEY" \  --secret-key "$S3_SECRET_KEY" \  --trash-days 1 \  --capacity <capacity-gib> \  --inodes <inode-limit> \  "redis://<redis-user>@<redis-cluster-endpoints>/<fs-prefix>" \  <volume-name>

--capacity 的单位是 GiB，--inodes 用来限制 inode 数量。它们是文件系统配额，不会自动发现 Ceph/RGW 的真实容量。设置这两个值的意义是让容量展示、配额治理和业务预期保持一致。

--trash-days 默认会启用回收站。回收站可以降低误删风险，但会增加对象存储实际占用。高频覆盖写或删除场景要同时监控逻辑用量和对象存储用量。

4. 挂载参数分层

生产环境不要把某一组参数当成所有场景的唯一答案。JuiceFS 的缓存参数本质上是在一致性可见性、元数据压力、对象存储读放大和吞吐之间做取舍。

4.1 一致性优先配置

多客户端同时写同一批目录、对跨客户端可见性敏感、或者排障阶段希望减少缓存变量时，可以使用保守配置。

export META_PASSWORD='<redis-password>'juicefs mount \  --attr-cache=0 \  --entry-cache=0 \  --dir-entry-cache=0 \  --negative-entry-cache=0 \  --open-cache=0 \  --prefetch=0 \  --max-readahead=0 \  --cache-size=0 \  "redis://<redis-user>@<redis-cluster-endpoints>/<fs-prefix>" \  /mnt/<volume-name>

这组参数会减少内核元数据缓存、客户端 open 缓存、本地数据缓存和预取带来的变量，但代价是 Redis 请求、对象存储请求和客户端延迟都会上升。它适合一致性排查和强可见性场景，不适合直接作为所有读密集任务的性能配置。

4.2 读密集配置

AI 数据集、模型权重、离线样本等大量只读或读多写少场景，可以保留 close-to-open 语义，同时开启本地缓存、预读和预取来提升吞吐。

export META_PASSWORD='<redis-password>'juicefs mount \  --attr-cache=1 \  --entry-cache=1 \  --dir-entry-cache=1 \  --open-cache=0 \  --prefetch=1 \  --max-readahead=256 \  --cache-size=<cache-size-mib> \  --cache-dir /var/jfsCache/<volume-name> \  "redis://<redis-user>@<redis-cluster-endpoints>/<fs-prefix>" \  /mnt/<volume-name>

如果业务明确是只读训练数据集，可以进一步评估 --open-cache、juicefs warmup 和更大的本地 SSD 缓存。但一旦存在多客户端频繁修改同一批文件，就要谨慎放大元数据缓存 TTL。

4.3 后台任务配置

--no-bgjob 不是一致性开关，而是运维负载分配开关。它可以让重负载业务客户端不承担后台清理、session 清理、回收站过期处理和元数据备份等任务。

生产环境可以让业务客户端使用 --no-bgjob，但必须至少保留一个维护客户端或独立运维挂载点不加 --no-bgjob，并显式开启元数据备份。

juicefs mount \  --backup-meta 1h \  "redis://<redis-user>@<redis-cluster-endpoints>/<fs-prefix>" \  /mnt/<volume-name-maintenance>

--backup-meta 默认间隔是 3600 秒，0 表示关闭。它能把 JuiceFS 元数据备份到对象存储，但不能替代 Redis 自身的 RDB/AOF、快照和恢复演练。

5. systemd 自动挂载

不建议用 --update-fstab 把包含凭据的 META URL 写入 /etc/fstab。生产环境更建议使用 systemd service，并把敏感变量放到权限受控的 EnvironmentFile。JuiceFS 支持用 META_PASSWORD 或 META_PASSWORD_FILE 提供元数据密码，因此 URL 中可以不直接出现密码。

# /etc/systemd/system/juicefs-<volume-name>.service[Unit]Description=JuiceFS <volume-name> MountAfter=network-online.targetWants=network-online.target[Service]Type=simpleEnvironmentFile=/etc/juicefs/<volume-name>.envExecStartPre=/usr/bin/mkdir -p /mnt/<volume-name>ExecStart=/usr/local/bin/juicefs mount \  --attr-cache=0 \  --entry-cache=0 \  --dir-entry-cache=0 \  --negative-entry-cache=0 \  --open-cache=0 \  --prefetch=0 \  --max-readahead=0 \  --cache-size=0 \  redis://<redis-user>@<redis-cluster-endpoints>/<fs-prefix> \  /mnt/<volume-name>ExecStop=/bin/fusermount -uz /mnt/<volume-name>Restart=on-failureRestartSec=5[Install]WantedBy=multi-user.target

环境文件示例：

# /etc/juicefs/<volume-name>.envMETA_PASSWORD=<redis-password>S3_ACCESS_KEY=<s3-access-key>S3_SECRET_KEY=<s3-secret-key>

如果使用的是 redis://:<password>@... 这类 URL 形式，应改成 redis://<redis-user>@... 或 redis://... 并由 META_PASSWORD 注入密码，避免凭据出现在进程参数、配置文件和审计日志里。

sudo chown root:root /etc/juicefs/<volume-name>.envsudo chmod 600 /etc/juicefs/<volume-name>.envsudo systemctl daemon-reloadsudo systemctl enable --now juicefs-<volume-name>.service

如果系统使用 fusermount3，需要把 ExecStop 改成对应路径。不同发行版的 FUSE 包名和命令路径可能不同，上线前要在目标 OS 上验证。

6. 多业务隔离

持有元数据地址和密码的客户端，基本等同于拥有该 JuiceFS 文件系统的管理能力。多业务共享时，不要只依赖 Linux 用户权限做隔离。

推荐模型是“一个业务域一个文件系统”。每个文件系统使用独立 Volume Name、独立 Redis ACL 用户、独立 key 前缀、独立 S3 凭据，最好使用独立 Bucket。

业务 A -> Redis ACL user-a + key prefix {a}* -> bucket-a -> mount-a业务 B -> Redis ACL user-b + key prefix {b}* -> bucket-b -> mount-b业务 C -> Redis ACL user-c + key prefix {c}* -> bucket-c -> mount-c

在 Redis Cluster 场景里，URL 里的 /<fs-prefix> 更适合理解成 key 前缀或 hash tag 隔离，而不是传统单机 Redis 的多 DB 隔离。ACL 要在 Redis 节点上限制对应 key 前缀，并配合网络 ACL 限制客户端来源。

7. 监控与运维闭环

JuiceFS 客户端侧需要关注吞吐、延迟、buffer、cache 命中、对象存储错误和后台任务状态。常用命令包括 juicefs stats、juicefs profile、juicefs status、juicefs info。

Redis 侧要监控内存、key 数、持久化状态、主从复制、Cluster 状态、慢查询、连接数和过期/淘汰风险。noeviction、持久化成功率和恢复演练比单纯看存活更重要。

RGW/S3 侧要监控 4xx/5xx、请求延迟、带宽、连接重试、bucket 用量、对象数量和多 part 上传异常。负载均衡必须限定在同一个 Ceph 集群和同一个 RGW zone 内。

日志要接入 logrotate 或集中日志系统。root 用户通常写 /var/log/juicefs.log，非 root 用户通常写 $HOME/.juicefs/juicefs.log，具体路径以实际版本为准。

8. 小结

Redis Cluster + Ceph RGW/S3 + JuiceFS Client 是一套工程上清晰的共享文件系统架构。真正决定稳定性的不是单条 mount 命令，而是元数据保护、对象存储可靠性、缓存策略、后台任务、自动挂载和监控告警能否形成闭环。

一致性优先参数适合强可见性和排障场景，读密集任务则应该结合业务访问模式开启缓存和预读。生产部署时要把参数写成“场景化策略”，而不是一组固定模板。

参考资料：

• JuiceFS Architecture
• JuiceFS Cache
• JuiceFS Command Reference
• JuiceFS Redis Best Practices
• JuiceFS Metadata Backup and Recovery
• JuiceFS Object Storage Setup

这篇文章整理的是 Qwen3-235B-A22B-FP4 在 vLLM OpenAI API 上的压测方法与结果解读。项目资料里使用 vllm bench serve 做统一 workload 压测，并对 CX8 与 89144 两套平台做了同口径对比。为了公开发布，文中隐藏真实 endpoint、路径、端口和内部脚本目录，只保留测试方法、参数口径和聚合指标。

一、推理压测不能只看 tok/s

很多大模型推理压测只展示 tokens/s，这很容易误导。推理服务的用户体验至少由四类指标共同决定：

对于长输入场景，TTFT 受 prefill 影响很大；对于长输出场景，TPOT 更能反映 decode 性能；对于高并发，排队和调度会显著影响 P95/P99。只看平均值或峰值都不够。

二、测试对象和服务参数

服务启动参数核心如下：

vllm serve <model-path> \  --served-model-name Qwen3-235B \  --host 0.0.0.0 \  --port <api-port> \  --tensor-parallel-size 8 \  --enable-expert-parallel \  --max-num-seqs 32 \  --max-model-len 8192 \  --max-num-batched-tokens 8192 \  --gpu-memory-utilization 0.9 \  --enable-chunked-prefill \  --no-enable-prefix-caching \  --kv-cache-dtype fp8 \  --trust-remote-code

项目里还记录了一组 forced-RoCE/Spectrum-X 通信参数，其中比较关键的是：

NCCL_P2P_DISABLE=1NCCL_SHM_DISABLE=1NCCL_IB_GID_INDEX=3NCCL_CROSS_NIC=1NCCL_IB_ADAPTIVE_ROUTING=1NCCL_NET_PLUGIN=<spectrum-x-plugin>

这里要特别注意：NCCL_P2P_DISABLE=1 会禁用本机 GPU P2P，使 TP8 decode 中频繁的 GPU 间通信更可能走 NET/IB 路径。它是解释性能差异的重要假设，但最终必须通过单变量 A/B 验证，不能只凭参数推断下结论。

三、vLLM Bench Serve 命令模板

vllm bench serve 的价值是把请求形态、并发、结果保存和百分位指标固定下来：

vllm bench serve \  --backend openai \  --model Qwen3-235B \  --tokenizer <model-path> \  --endpoint /v1/completions \  --host <api-host> \  --port <api-port> \  --dataset-name random \  --random-input-len 4000 \  --random-output-len 1000 \  --ignore-eos \  --max-concurrency 16 \  --num-prompts 64 \  --request-rate 10000 \  --percentile-metrics ttft,tpot,itl,e2el \  --metric-percentiles 50,90,95,99 \  --save-result \  --save-detailed \  --plot-timeline \  --plot-dataset-stats \  --result-dir ./results/public \  --result-filename qwen3_4000_1000_c16.json

几个参数需要解释：

四、当前两组结果

CX8 架构当前完成了两组同口径测试，每组 64 请求，全部成功：

这两组 workload 的含义不同：

1000/300/c6 更接近短输入、短输出、中等并发，用来看 TTFT、排队和 decode 轻负载表现。

4000/1000/c16 更重，输出更长，并发更高，更能放大 decode 阶段每 token 延迟和通信路径差异。

五、CX8 与 89144 对比（这里是服务器机型对比）

89144 的同口径手工重跑结果。两组对比都显示 89144 在吞吐和 TPOT 上明显优于 CX8。

89144是可以混跑IB网络与P2P，CX8是GPU之间通信统一走IB网卡

1000/300/c6

4000/1000/c16

从这两张表可以看出，差距主要不在 TTFT，而在 TPOT/ITL，也就是 decode 阶段。

六、为什么怀疑通信路径

当前 CX8 服务使用 forced-RoCE 参数，其中 NCCL_P2P_DISABLE=1 和 NCCL_SHM_DISABLE=1 会让本机 TP8 中的 GPU 间通信更多走 NET/IB/GDRDMA。项目资料里也记录了一个现象：89144 一旦禁用 P2P，吞吐会接近 CX8；而保留 P2P 时，TPOT 和 completion tok/s 更好。

因此当前最值得优先验证的假设，不是模型、压测工具或 tokenizer，而是通信路径：

P2P/CUMEM 可用路径  -> 本机 GPU 间 decode 通信更短  -> TPOT 下降  -> completion tok/s 上升forced-RoCE/NET 路径  -> decode 阶段频繁通信经过 NET/IB  -> 每 token 延迟升高  -> E2E latency 被拉长

当然，最终结论必须通过单变量 A/B 验证，不能只凭经验判断。

七、推荐 A/B 实验

下一步建议只改一个变量：打开本机 P2P。

NCCL_P2P_DISABLE=0NCCL_DEBUG=INFONCCL_DEBUG_SUBSYS=INIT,NET,GRAPH,ENV

然后重跑：

1000/300/c64000/1000/c16

观察四类证据：

如果打开 P2P 后 CX8 的 TPOT 明显下降，就可以把通信路径作为主要归因，并继续用相同 workload 复测 batch token、并发和插件版本等变量。

八、压测报告应该怎么写

一份可复盘的 vLLM 压测报告建议至少包含：

1. 模型、量化格式、served name。
2. 服务参数：TP、PP、max model len、max num seqs、batch tokens、KV cache dtype。
3. NCCL/RDMA 参数，尤其是 P2P、SHM、IB、GID、插件。
4. workload：input/output/concurrency/requests/request rate。
5. 成功数、失败数、错误类型。
6. TTFT、TPOT、ITL、E2E 的 P50/P90/P95/P99。
7. QPM、TPM、completion tok/s、total tok/s。
8. 是否预热，是否冷启动，是否存在 lazy compile。
9. 原始 JSON 和图表路径。

九、参考资料

• vLLM Bench Serve：https://docs.vllm.ai/en/latest/cli/bench/serve/
• vLLM Benchmark CLI：https://docs.vllm.ai/en/latest/benchmarking/cli/
• vLLM Metrics：https://docs.vllm.ai/en/stable/design/metrics/

十、总结

Qwen3-235B 这组压测最有价值的地方，不是某个 tok/s 数字，而是展示了如何用 vLLM bench serve 固定 workload，用 TTFT/TPOT/E2E/吞吐矩阵拆解瓶颈，并进一步通过 NCCL 单变量 A/B 定位通信路径。

对于 TP8 这类强通信场景，decode 阶段的 TPOT 往往比平均延迟更能说明问题。只要把 workload、服务参数、NCCL 参数和结果指标记录完整，后续换平台、换驱动、换 NCCL 插件或调整 P2P/RoCE 策略，都可以用同一套方法复测。

大模型推理拓扑没有“万能最佳”。同样是双机 16 卡，真正要先分清的是两类扩展：一类是服务级副本扩展，例如 TP8x2、TP4x4；另一类是单模型副本的模型并行扩展，例如 PP2/TP8。

TP8x2 和 PP2/TP8 看起来都用了 16 张卡，但含义完全不同。TP8x2 是两个独立 TP=8 的 vLLM 实例，每个请求只落到其中一台 8 卡机器。PP2/TP8 是一个 vLLM engine，TP=8、PP=2，单个请求会跨两台机器完成。

本文基于项目中的 DeepSeek-V4-Flash 双机压测资料整理公开版经验。文中不暴露真实节点、IP、端口和原始结果路径，只保留拓扑含义、指标矩阵和生产判断方法。

一、三种拓扑分别是什么

所以 TP8x2 和 PP2/TP8 不是同一个东西。前者是“两个服务副本”，优势是隔离简单、入口可横向扩展；后者是“一个跨机模型副本”，优势是单个模型副本可以使用两台机器的显存和算力，但每个请求会经历跨机 pipeline。

从直觉看，TP4x4 副本更多，似乎适合并发；PP2/TP8 用满两台机器，似乎适合超大模型；TP8x2 则是容易生产化的折中。但最终不能靠直觉，必须用业务 workload 和高并发扫描共同判断。

二、为什么要把 workload 分成两类

项目资料里使用了两类压测口径。

第一类是业务三组：

这类 workload 适合看业务体验，重点看 TTFT、TPOT、P95 latency、QPM、TPM。

第二类是高并发短输出扫描，例如：

c1024_r2048_t128c2048_r4096_t128c2560_r5120_t128

这里 c2048_r4096_t128 表示并发 2048、总请求 4096、每个请求最大输出 128 token。它更适合找吞吐峰值、过载拐点和 P95 latency 退化。

生产选型时不能只看其中一类。只看业务三组，可能看不到满载能力；只看高并发短输出，又可能误判长上下文体验。

三、DeepSeek-V4-Flash 历史拓扑结论

TP4x4 在 DeepSeek-V4-Flash 上表现非常强，双机高并发短输出峰值达到：

在这组结果里，TP4x4 明显适合高并发短输出。原因也很清楚：TP=4 已能容纳模型和 65K KV cache，单副本通信域更小，4 个独立副本可以提供更多请求队列。

但后续 H20 + DSFlash 项目中，同口径与 6000D 对齐时，TP8x2 成为了当前服务级推荐基线。这里的 TP8x2 指两个独立 TP8 endpoint，而不是一个 TP=16 或 PP=2 的跨机 engine。原因是新一轮同字段测试显示：

这说明同一个模型，在不同镜像、内核、调度参数、入口策略、压测口径下，最佳拓扑会变化。

四、当前 H20 TP8x2 为什么成为推荐基线

当前 H20 与 6000D 的同拓扑对齐结果显示，H20 TP8x2 在三组 workload 上均优于 6000D 参考口径。它适合作为生产基线的原因，不是“单请求用了 16 卡”，而是“每台机器一个独立 TP8 副本，入口层可以稳定分流”：

这组结果说明，当前服务的瓶颈不一定在 H20、RoCE/NCCL 或显存硬件能力本身。对 TP8x2 来说，每个请求主要在单机 8 卡副本内完成，跨机 RoCE 更偏向服务编排和入口侧，而不是单请求每层必经路径。更值得关注的是 vLLM 调度、HTTP 连接复用和入口分流。

五、短请求为什么要单独优化入口

TP8x2 的优化记录里，一个很重要的发现是：短输入高并发时，HTTP 连接复用和 API worker 分配不均可能导致 TTFT 排队。对 1000/300/c6 做不同策略后结果如下：

但是 force-close 和更大的 batched tokens 并不适合所有请求。中长上下文可能退化。因此更合理的生产策略不是全局改参数，而是分入口：

这也是拓扑选型之外非常重要的一点：很多“模型慢”其实是入口层和客户端连接策略导致的排队。

六、PP2/TP8 什么时候有价值

PP2/TP8 不适合作为当前默认生产吞吐拓扑，但并非没有价值。它和 TP8x2 的核心差别是：PP2/TP8 是一个跨机模型副本，因此适合验证“单请求跨双机”的能力，而不是替代两个独立 endpoint 做高并发吞吐。

它适合三类场景：

1. 复现跨机 pipeline 性能问题。
2. 做超长输入、低并发、单请求专项对照。
3. 验证跨机模型内部执行路径的稳定性。

50000/1000/c1 这类单请求超长输入下，PP2/TP8 的 TPM 曾比 TP4x4 高约 2.99%。但这不能代表整体吞吐最佳。只要进入中短输入或高并发，pipeline bubble、跨机通信和单 endpoint 队列都会放大延迟。

如果模型单机 8 卡能放下，生产上通常优先考虑 TP8x2 这类副本并行；如果模型单机放不下，或需要验证单请求使用双机显存，才更自然地进入 PP2/TP8 或更复杂的 TP/PP 组合。

七、选型方法论

我建议把推理拓扑选择做成四步：

第一步，确定业务流量形态。短问答、代码助手、RAG 长上下文、批量摘要、多轮 Agent，它们需要看的指标不一样。

第二步，定义统一 workload。至少包含短输入并发、中长输入、超长输入、吞吐峰值扫描四类。

第三步，固定变量做 A/B。一次只改一个变量：拓扑、batch token、连接策略、P2P/RoCE、CUDA graph、MTP、max-num-seqs。

第四步，按场景给入口，而不是追求一个全局最优参数。短请求和长上下文混在同一个入口，很容易互相拖累。

八、参考资料

• vLLM Parallelism and Scaling：https://docs.vllm.ai/en/stable/serving/parallelism_scaling/
• vLLM Distributed Inference and Serving：https://docs.vllm.ai/en/v0.6.0/serving/distributed_serving.html

九、总结

DeepSeek-V4-Flash 的双机拓扑选型不能用一句“TP4x4 更快”或“TP8x2 更稳”概括。更准确的说法是：TP8x2、TP4x4 是服务副本扩展，PP2/TP8 是单模型副本跨机扩展，二者解决的问题不同。

历史探索中，TP4x4 在高并发短输出峰值上非常强；但当前 H20 + DSFlash 同口径复测里，TP8x2 是服务级推荐基线，并且通过短/长入口分流进一步改善了业务体验。

真正可落地的结论是：拓扑选择要绑定 workload、指标口径和入口策略。生产默认可以选当前综合最稳的 TP8x2，但保留 TP4x4 和 PP2/TP8 作为专项对照，才能在业务变化时快速复测和切换。

这篇文章整理的是一个 H20 双机 16 卡推理服务的公开版落地经验。目标模型是 DeepSeek-V4-Flash，服务框架使用 vLLM OpenAI-compatible API，分布式执行使用 Ray，运行形态使用 Docker 容器。为了适合公网发布，文中不会出现原始节点名、IP 地址、模型绝对路径、内部镜像仓库、日志路径和内部业务信息，相关位置统一用占位符表示。

一、为什么不是简单 docker run vllm

单机小模型部署时，一个 vLLM 容器、一个模型路径、一个 API 端口通常就能跑起来。但 DeepSeek-V4-Flash 这类 MoE、FP8、长上下文模型部署到双机 16 卡时，真正的难点在于四层协同：

生产部署的目标不是“启动一次成功”，而是要做到环境可检查、参数可复现、日志可定位、服务可压测、失败可回滚。

二、推荐架构

第一条是业务入口链路。业务方访问入口代理或 vLLM API Server，API 使用 OpenAI-compatible 协议，最常用的是 /v1/chat/completions、/v1/completions、/v1/models 和 /health。生产中建议前面接 Nginx、Envoy 或 HAProxy，用于健康检查、TLS、鉴权、限流和多入口分流。

第二条是 Ray 控制面链路。Ray head 运行在 head 节点，worker 节点加入 Ray 集群。控制面建议绑定管理网，例如 <management-bond>，不要和 RoCE 数据面混用。Ray 看到的 GPU 资源应该是双机共 16 张卡。

第三条是 NCCL 数据面链路。跨机 Tensor Parallel 或 Pipeline Parallel 通信依赖 RoCE/RDMA。容器必须能看到 /dev/infiniband，NCCL 需要绑定正确的 HCA 列表、GID index 和 socket interface。日志中应能看到 Using network IB、GDRDMA 等证据，避免静默退回 TCP/socket。

这里要先区分两种生产形态：如果目标是一个跨双机的单模型副本，vLLM 主流写法是每节点内做 TP、节点间做 PP，例如 2 台 8 卡节点使用 TP=8, PP=2。如果模型单机 8 卡就能放下，也可以部署两个独立 TP=8, PP=1 副本，再由入口代理分流；这属于服务级副本扩展，不是一个跨 16 卡的 vLLM engine。

生产上还要把多节点通信放在隔离网络里。Ray、PyTorch Distributed、NCCL、KV cache 传输都不应该直接暴露到公网；对外只暴露经过鉴权、限流和审计的 API 入口。

三、部署前环境检查

容器 GPU 检查可以用类似命令：

docker run --rm \  --gpus all \  --network=host \  --ipc=host \  <cuda-or-vllm-image> nvidia-smi

RDMA 工具建议至少包含：

ibv_devinfoibdev2netdevshow_gids

如果官方 vLLM 镜像没有这些工具，可以做一个很薄的派生镜像，只增加 rdma-core、iproute2、curl、net-tools 等诊断工具。

四、容器运行方式

双机推理服务建议使用 host network，减少容器网络对 Ray、NCCL、RoCE 的干扰。典型容器形态如下：

docker run -d \  --name <vllm-ray-container> \  --gpus all \  --network=host \  --ipc=host \  --shm-size=256g \  --ulimit memlock=-1:-1 \  --ulimit stack=67108864 \  --cap-add IPC_LOCK \  --device=/dev/infiniband \  -v /dev/infiniband:/dev/infiniband \  -v <model-path>:<model-path>:ro \  -v <log-dir>:<log-dir> \  -e NCCL_NET=IB \  -e NCCL_SOCKET_IFNAME=<management-bond> \  -e NCCL_IB_GID_INDEX=<gid-index> \  -e NCCL_IB_HCA=<hca-list> \  -e NCCL_ASYNC_ERROR_HANDLING=1 \  -e NCCL_IB_DISABLE=0 \  -e GLOO_SOCKET_IFNAME=<management-bond> \  -e VLLM_HOST_IP=<node-management-ip> \  <vllm-image> sleep infinity

这里有几个容易踩坑的点。

--network=host 不是为了省事，而是为了让 Ray、vLLM、NCCL 在多网卡环境中更可控。--ipc=host 或足够大的 --shm-size 对 PyTorch/vLLM 也很重要。--device=/dev/infiniband 和卷挂载同时配置，是为了让容器内 RDMA 诊断工具和 NCCL 都能看到设备。

五、Ray 启动顺序

推荐顺序是先容器、再 Ray、再 vLLM。

head 节点：启动容器 -> ray start --headworker 节点：启动容器 -> ray start --address <head-ip>:6379head 节点：检查 ray status -> 启动 vLLM API Server

Ray 检查重点不是“命令返回成功”，而是资源视图是否正确。应该看到两台节点 active，并且总 GPU 数为 16。若 Ray 资源不足，vLLM 后续 placement group 会失败或一直等待。

六、vLLM 参数基线

DeepSeek-V4-Flash 是 MoE + FP8 + 长上下文模型，不建议一开始就把上下文和并发拉满。一个更稳的首轮基线可以这样设计：

vllm serve <model-path> \  --host 0.0.0.0 \  --port <api-port> \  --served-model-name DeepSeek-V4-Flash \  --trust-remote-code \  --distributed-executor-backend ray \  --tensor-parallel-size 8 \  --pipeline-parallel-size 2 \  --dtype auto \  --kv-cache-dtype fp8 \  --max-model-len 65536 \  --gpu-memory-utilization 0.88 \  --max-num-seqs 8 \  --enable-expert-parallel \  --tokenizer-mode deepseek_v4 \  --tool-call-parser deepseek_v4 \  --enable-auto-tool-choice \  --reasoning-parser deepseek_v4

参数解释：

如果使用的是深度定制 DSFlash 镜像，可能还有额外 parser、block size 或 speculative decoding 参数。不建议把这类非通用参数写死；先用 vLLM 主线参数跑通，再按镜像说明做专项 A/B。

TP=16, PP=1 也可以作为实验项，即 Tensor Parallel 横跨两台机器。但这会让大量逐层 all-reduce 穿过跨机 RoCE，对网络、NCCL、GDRDMA 和拓扑一致性要求更高。除非跨机互联已经被验证足够稳定，否则它更适合作为压测对照，而不是首轮生产基线。

如果显存不足，优先按下面顺序收敛：降低 max-num-seqs，再降低 max-model-len，最后再调整 gpu-memory-utilization。不要一开始就把显存利用率拉到极限，否则后续排障很难判断是模型、KV cache、碎片还是通信导致的问题。

七、服务验证

服务启动后，最少做三类验证。

健康检查：

curl -fsS http://<api-host>:<api-port>/healthcurl -fsS http://<api-host>:<api-port>/v1/models

功能冒烟：

curl http://<api-host>:<api-port>/v1/chat/completions \  -H 'Content-Type: application/json' \  -d '{    "model": "DeepSeek-V4-Flash",    "messages": [      {"role": "user", "content": "请用一句话介绍你自己。"}    ],    "max_tokens": 128,    "temperature": 0  }'

通信证据：

grep -E "Using network IB|GDRDMA|NCCL|Ray" <vllm-log>

如果只看 API 能返回，可能会漏掉 NCCL fallback。跨机推理服务必须确认数据面真的走 RoCE/IB/GDRDMA。

八、生产排障经验

第一，镜像能力要先验收。模型 config 支持 DeepSeek V4 不等于当前镜像一定支持对应 architecture、parser、MoE、FP8 和长上下文。

第二，控制面和数据面要分清。Ray、Gloo、API 健康检查可以走管理网；NCCL 数据面要绑定 RoCE HCA。两者混在一起会导致“能启动但性能不稳定”。

第三，日志要从启动阶段开始保留。TileLang lazy compile、Ray worker lost、NCCL fallback、OOM、KV cache 不足都可能只在特定阶段出现。

第四，长上下文不能只靠 max_position_embeddings 判断。模型配置可能支持极长上下文，但实际可服务长度取决于 KV cache、并发、显存碎片和 batch token 策略。

九、参考资料

• vLLM Parallelism and Scaling：https://docs.vllm.ai/en/stable/serving/parallelism_scaling/
• vLLM Docker Deployment：https://docs.vllm.ai/en/stable/deployment/docker/
• vLLM Security：https://docs.vllm.ai/en/latest/usage/security/

十、总结

H20 双机 16 卡部署 DeepSeek-V4-Flash 的关键，是把 Docker、Ray、vLLM、RoCE/NCCL 和模型参数放在同一个工程闭环里。正确的落地方式不是复制一条启动命令，而是先检查环境，再固化容器和网络参数，然后按小并发到大并发、短上下文到长上下文逐步压测。

当服务能稳定通过健康检查、功能冒烟、NCCL 数据面验证和三组 workload 压测后，才适合作为后续拓扑优化和业务接入的基线。

进入生产后，真正考验运维能力的不是“有没有故障”，而是故障出现后能否快速定界。GPU 掉卡、NVSwitch 未识别、Fabric Manager 启动失败、NCCL 慢节点，这些问题在单台机器上看似独立，在训练集群里都会表现为任务失败、通信超时或整体带宽下降。

一、排障原则：先定界，再换件

生产现场最容易犯的错误是看到 nvidia-smi 少卡就直接判断 GPU 坏了。实际上，GPU 不识别可能来自多种原因：

正确方法是先收集证据，再缩小范围，最后决定是否换 GPU、换线缆、处理 NVSwitch、调整配置或升级软件。

二、第一步：带外和 OS 双视角确认

GPU 掉卡排障建议先看带外，再看 OS。

带外视角用于判断硬件管理面是否能识别 GPU。这里可以通过 BMC 页面或 Redfish 接口查看设备状态、传感器、错误告警。

OS 视角用于判断驱动和系统是否识别 GPU：

nvidia-sminvidia-smi -Llspci | grep -i nvidiadmesg | egrep -i 'nvrm|xid|nvidia|pcie'

如果 BMC 能识别但 OS 不能识别，优先看驱动、PCIe、系统日志和 Fabric。若 BMC 和 OS 都不能识别，硬件路径问题概率更高。

三、第二步：检查 ECC 与 Row Remapper

如果 GPU 仍然可见，但训练任务异常、NCCL 报错或性能不稳定，建议检查 ECC 与 Row Remapper：

nvidia-smi -q -d ECC,ROW_REMAPPER

关注项包括：

如果错误已经指向 GPU 硬件健康问题，就不应继续把它放回训练池。生产上可以先隔离节点，再做进一步定界。

四、第三步：NVSwitch 与 Fabric Manager

8 卡服务器如果使用 NVSwitch 或 Fabric Manager，GPU 可见不代表 Fabric 正常。Fabric Manager 异常会导致 GPU 间通信能力受影响，NCCL 可能表现为初始化失败、带宽异常或任务挂住。

常用检查：

dmesg | grep -i nvswitchsystemctl status nvidia-fabricmanagerjournalctl -u nvidia-fabricmanager -n 100 --no-pagerlspci -nn | grep -i nvidia

排障时建议分三层看：

1. lspci 是否能看到对应 NVIDIA 设备。
2. 内核日志是否有 NVSwitch 或 PCIe 错误。
3. Fabric Manager 服务是否启动成功，日志里是否有模块未识别、拓扑不一致或版本不匹配。

如果确认某个 NVSwitch 模块未识别，现场可以按厂商维护规范做断电复位、插拔清洁或部件替换。公开文章建议写方法，不建议公开现场照片和模块编号。

五、第四步：NCCL 慢节点单卡隔离

有些故障不会表现为 GPU 掉卡，而是表现为 NCCL 慢。定位这类问题时，最有效的方法是逐步隔离 GPU 和 HCA。

单机全卡测试：

./all_reduce_perf -g 8 -b 8M -e 12G -f 2

排除某一张 GPU：

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 ./all_reduce_perf \  -g 7 \  -b 8M \  -e 12G \  -f 2

轮流排除 GPU 0 到 GPU 7。如果排除某一张 GPU 后性能恢复，要继续判断问题是 GPU 本身、对应 HCA、PCIe 路径、NVSwitch 路径，还是局部链路。

跨机慢节点也可以用类似方法：

1. 从大规模测试中拿掉可疑节点。
2. 对可疑节点做双机测试。
3. 对可疑节点做单机 8 卡测试。
4. 轮流排除 GPU 或 HCA。
5. 结合 RoCE 队列、端口错误、PFC/ECN 统计判断。

六、第五步：槽位对调判断“跟卡走还是跟槽走”

当 OS 不识别某张 GPU，且重启无法恢复时，可以通过槽位对调进一步定界：

对调前：  Slot-X 中 GPU-A 不识别。操作：  将 GPU-A 与 Slot-Y 中 GPU-B 对调。对调后：  如果故障跟着 GPU-A 走，倾向 GPU 单卡问题。  如果故障仍停留在 Slot-X，倾向槽位、线缆、基板或主板路径问题。

生产现场一定要记录 GPU UUID、SN、槽位、线缆、BDF 和对调前后照片

七、排障证据清单

八、故障闭环模板

建议每一次生产故障都按同一个模板记录：

故障现象：  训练任务失败 / NCCL 带宽下降 / nvidia-smi 少卡 / Fabric Manager 异常。影响范围：  单节点 / 单 Leaf / 多节点 / 整网。初步证据：  告警、日志、NCCL 结果、GPU 健康状态。定界过程：  BMC -> OS -> GPU 健康 -> Fabric -> 单卡隔离 -> 槽位对调。结论：  GPU 单卡 / NVSwitch / HCA / 线缆 / 槽位 / 软件配置。恢复动作：  隔离、替换、复位、升级、回滚。复测结果:  单机 NCCL、双机 NCCL、目标规模 NCCL。

这个模板的价值在于减少误判。没有复测结果的“恢复”，不能算闭环。

九、生产经验

第一，慢节点优先隔离，避免影响正在排队的训练任务。大规模集群里，一个慢节点可能拖垮整个作业。

第二，硬件证据和软件证据要分开看。nvidia-smi 正常不代表 NVSwitch 正常，BMC 正常也不代表 OS 驱动正常。

第三，换件前要尽量完成槽位对调或路径定界。否则可能出现 GPU 换了、问题还在原槽位的情况。

第四，恢复后必须复跑 NCCL。硬件恢复只是第一步，训练通信恢复才是生产可用的证据。

十、总结

智算集群故障定界的关键是流程化：先带外，再 OS；先设备识别，再健康指标；先单机，再跨机；先隔离，再换件；最后用 NCCL 复测闭环。

在 生产环境里，排障方法本身就是平台能力的一部分。只有把 GPU 掉卡、NVSwitch 异常、Fabric Manager 故障和 NCCL 慢节点纳入统一闭环，集群才能长期稳定运行。

上一篇文章解决的是“GPU 节点如何接入 Kubernetes，让 Pod 能调度到 GPU Worker 上”。

这篇文章继续往下走一步：

一台 Worker 有 8 张 GPU，我不想让一个 Pod 使用整台机器，只想让它使用其中 1 张 GPU，应该怎么做隔离？能不能配合 NVIDIA Run:ai 做管控调度？Run:ai 是不是开源免费？

先给结论：

• 生产默认方案：使用 NVIDIA GPU Operator 或 NVIDIA device plugin 暴露 nvidia.com/gpu，Pod 声明 limits.nvidia.com/gpu: 1。这表示 Pod 申请并独占 1 张 full GPU，不是独占整台 8 卡 Worker。
• 传统 device plugin 模式下：不能在普通 Pod spec 里可靠表达“我要这台机器上的物理 GPU 3”。Kubernetes 调度器看到的是节点资源数量，具体哪张卡由 device plugin/kubelet/runtime 分配。
• 需要硬隔离：优先考虑 MIG，但前提是 GPU 型号支持 MIG。
• 需要提升利用率、能接受弱隔离：可以考虑 time-slicing 或 MPS。
• 需要队列、配额、公平性、多租户治理：开源生产优先评估 Kueue、Volcano、KAI Scheduler；商业平台再评估 NVIDIA Run:ai。
• Run:ai 平台本身不要理解成开源免费平台。当前可公开确认的是 KAI Scheduler 是开源调度器；NVIDIA Run:ai 是面向企业 AI 集群的商业平台能力，需要按 NVIDIA/Run:ai 官方授权和产品形态评估。

1. nvidia.com/gpu: 1 到底是什么意思

假设一台 Worker 有 8 张 NVIDIA GPU。

NVIDIA device plugin 正常工作后，节点会向 kubelet 注册扩展资源：

status:  capacity:    nvidia.com/gpu: "8"  allocatable:    nvidia.com/gpu: "8"

业务 Pod 只需要声明：

resources:  limits:    nvidia.com/gpu: 1

这表示：

• 调度器只会把 Pod 放到至少还有 1 张可分配 GPU 的节点。
• kubelet 会向 device plugin 请求 1 个 GPU device。
• NVIDIA runtime 会把分配到的 GPU 注入容器。
• 容器内通常只看得到这一张 GPU。

所以，1 个 Pod 申请 nvidia.com/gpu: 1，不是占用整台 8 卡 Worker，而是占用该节点上的 1 张 GPU 资源。

Kubernetes 官方对 GPU 这类扩展资源还有一个重要规则：

• GPU 资源只能写在 limits。
• 如果同时写 requests 和 limits，两者必须相等。
• 只写 limits 时，Kubernetes 会把它当作 request 使用。

因此，最推荐的写法就是只写：

resources:  limits:    nvidia.com/gpu: 1

2. 最小可落地 Pod 示例

下面是一个 1 Pod / 1 GPU 的最小验证示例。

apiVersion: v1kind: Podmetadata:  name: one-gpuspec:  restartPolicy: Never  runtimeClassName: nvidia  nodeSelector:    nvidia.com/gpu.present: "true"  tolerations:    - key: nvidia.com/gpu      operator: Exists      effect: NoSchedule  containers:    - name: app      image: nvidia/cuda:12.4.1-base-ubuntu22.04      command: ["bash", "-lc", "nvidia-smi -L && echo GPU_OK && sleep infinity"]      resources:        limits:          nvidia.com/gpu: 1

如果你的集群把 NVIDIA runtime 配成了默认 runtime，runtimeClassName: nvidia 可以不写。

但我更建议显式写上。这样排障时不会混淆“资源已经分配”和“容器是否走 NVIDIA runtime”这两件事。

部署：

kubectl apply -f one-gpu.yamlkubectl wait --for=condition=Ready pod/one-gpu --timeout=300skubectl logs one-gpu

验证容器内可见 GPU：

kubectl exec one-gpu -- nvidia-smi -Lkubectl exec one-gpu -- bash -lc 'echo $NVIDIA_VISIBLE_DEVICES'

容器里常见输出是：

GPU 0: NVIDIA ...

这里的 GPU 0 是容器内部可见设备编号，不等于宿主机物理 GPU0。

严谨验证应使用 GPU UUID 对齐。

宿主机侧：

nvidia-smi -L

容器侧：

kubectl exec one-gpu -- nvidia-smi -L

如果容器内只看到 1 个 GPU UUID，就说明“1 Pod / 1 GPU”的设备可见性隔离已经生效。

3. 隔离了什么，没有隔离什么

默认 nvidia.com/gpu: 1 提供的是：

• 调度层面的整数资源独占。
• 容器可见设备隔离。
• runtime 注入层面的 GPU device 控制。

它不提供：

• GPU 显存配额细分。
• 同一张 GPU 上多个租户之间的硬隔离。
• 防止特权容器绕过设备隔离的安全边界。
• 按物理 GPU index 的稳定调度契约。

换句话说，默认 full GPU 模式的语义是：

这张卡分给这个容器，这个容器只看得到这张卡。

不是：

这张卡的 20% 显存和 20% 算力分给这个容器。

如果你需要“显存/算力份额”这种能力，需要看 MIG、time-slicing、MPS 或 DRA，而不是普通 nvidia.com/gpu: 1。

4. 不要手写 NVIDIA_VISIBLE_DEVICES 来抢卡

有些人会尝试在 Pod 里写：

env:  - name: NVIDIA_VISIBLE_DEVICES    value: "3"

这不是生产推荐方式。

原因是：

• 它绕开 Kubernetes device plugin 的分配语义。
• 它可能和 kubelet/device plugin 的分配结果冲突。
• GPU index 并不是可靠的长期契约。
• 驱动、硬件枚举、节点维护后，index 可能造成误解。

更稳的做法是：

• 让 device plugin 分配 GPU。
• 用 GPU UUID 做观测和审计。
• 如果必须按特定 GPU 属性选择，评估 DRA。

5. 能不能指定某一张物理 GPU

传统 device plugin 模式下，普通 Pod spec 不能可靠表达：

我要 <gpu-worker-01> 上的 GPU-UUID-xxx

你可以做到的是：

5.1 固定到某台 GPU 节点

nodeSelector:  kubernetes.io/hostname: <gpu-worker-01>

或用 node affinity：

affinity:  nodeAffinity:    requiredDuringSchedulingIgnoredDuringExecution:      nodeSelectorTerms:        - matchExpressions:            - key: kubernetes.io/hostname              operator: In              values:                - <gpu-worker-01>

这只能固定节点，不能固定该节点里的某张卡。

5.2 用 UUID 做验证，不用 index 做契约

宿主机：

nvidia-smi -L

容器：

kubectl exec one-gpu -- nvidia-smi -L

把容器里看到的 UUID 和宿主机 UUID 对齐。

注意：容器内部看到的 GPU 0 通常只是容器视角的第 0 张可见卡。

5.3 需要按 UUID/PCI/拓扑调度，评估 DRA

DRA 是 Kubernetes 面向动态设备分配的新机制。

它允许通过 ResourceClaim、DeviceClass、ResourceSlice 表达更细的设备选择。

概念上可以写成：

apiVersion: resource.k8s.io/v1kind: ResourceClaimTemplatemetadata:  name: gpu-by-uuidspec:  spec:    devices:      requests:        - name: gpu          exactly:            deviceClassName: gpu.nvidia.com            selectors:              - cel:                  expression: device.attributes["gpu.nvidia.com"].uuid == "GPU-xxxx"

但这不是所有集群都能直接使用。

它依赖：

• Kubernetes 版本。
• NVIDIA DRA driver。
• GPU Operator 版本。
• CDI 支持。
• driver 版本。
• ResourceSlice 实际暴露了哪些字段。

因此，DRA 更适合新集群规划或平台化建设，不建议在已有生产集群里临时硬塞。

6. 三种隔离/共享模式的边界

这张图是简化决策图：先区分“整卡独占、硬隔离、弱共享、平台调度”。完整开源生产选型建议看第 9 节，那里会把 Kueue、Volcano、KAI Scheduler 分开。

6.1 Full GPU 独占

这是最简单、最稳的默认方案。

写法：

resources:  limits:    nvidia.com/gpu: 1

适合：

• 训练任务。
• 性能敏感推理。
• 单租户或强可预测资源场景。
• 不希望互相干扰的业务。

优点：

• 调度语义清楚。
• 风险低。
• 排障简单。
• 和大多数框架兼容。

缺点：

• 小任务可能浪费 GPU。
• 无法表达“半张卡”。

6.2 MIG：硬切分隔离

MIG 可以把一张支持 MIG 的 GPU 切成多个硬件实例。

每个 MIG 实例有相对独立的计算、显存、缓存和带宽边界。

适合：

• 多租户推理。
• 需要更强隔离的小模型任务。
• A100/H100 等支持 MIG 的 GPU。

典型资源名可能类似：

nvidia.com/mig-1g.10gbnvidia.com/mig-2g.20gb

Pod 示例：

resources:  limits:    nvidia.com/mig-1g.10gb: 1

注意：

• MIG 需要 GPU 硬件支持。
• MIG 模式/切分策略变更会影响节点上已有 workload。
• 生产上应通过 GPU Operator 的 MIG Manager 管理，而不是手工在节点上随意切换。

6.3 Time-slicing：弱隔离共享

time-slicing 会把一张 GPU 暴露成多个逻辑 replica。

比如 8 张 GPU，每张切成 10 个 replica，节点可能显示出 80 个逻辑共享资源。

适合：

• 开发调试。
• 轻量推理。
• 低优先级任务。
• 可以接受互相影响的场景。

风险：

• 没有显存硬隔离。
• 没有故障硬隔离。
• 一个进程 OOM 或异常可能影响共享体验。
• 申请多个共享 GPU 不代表获得线性算力。

最佳实践：

• 使用 renameByDefault=true 把共享资源改名为 nvidia.com/gpu.shared。
• 使用 failRequestsGreaterThanOne=true，避免用户误以为申请 2 个 shared GPU 就有 2 倍算力。

示意：

resources:  limits:    nvidia.com/gpu.shared: 1

6.4 MPS：共享但更可控，仍需谨慎

MPS 可以让多个 CUDA 进程共享一张 GPU，并通过 MPS daemon 做一定的计算和显存份额控制。

相比 time-slicing，它更可控一些。

但在 Kubernetes device plugin 语境里，MPS 支持仍应谨慎看待：

• 不是所有 GPU/模式都适合。
• 和 time-slicing 互斥。
• 不适合和 MIG-enabled 设备混用。
• 运维复杂度高于 full GPU 独占。

除非你明确知道 workload 特性，否则生产默认仍建议 full GPU 或 MIG。

7. Run:ai 能解决什么

NVIDIA Run:ai 可以理解为面向 AI 集群的 GPU 资源治理平台。

它关注的问题不是“一个容器怎样看到某张 GPU”，而是更上层的治理：

• 多租户项目。
• 队列。
• 配额。
• 公平调度。
• GPU 利用率提升。
• 训练/推理 workload 编排。
• 组织级资源可视化。
• 管理员策略控制。

也就是说，Run:ai 可以和 NVIDIA GPU Operator、device plugin、MIG、共享 GPU 等能力配合。

它更像是：

平台治理层 + 调度层 + 资源抽象层

而不是单纯替代 nvidia.com/gpu: 1。

8. Run:ai 是不是开源免费

这个问题要拆开说。

8.1 KAI Scheduler 是开源的

KAI Scheduler 是 NVIDIA 开源的 Kubernetes 原生调度器，来自 Run:ai 的调度能力。

它适合关注：

• 队列。
• 公平性。
• GPU sharing。
• AI workload 的调度优化。

如果你的目标是研究或落地开源 GPU 调度器，可以评估 KAI Scheduler。

8.2 NVIDIA Run:ai 平台不应默认理解成开源免费

NVIDIA Run:ai 是完整企业平台能力，包含远不止调度器的部分。

它通常涉及：

• 平台控制面。
• 用户/项目/租户。
• 配额和策略。
• 可视化。
• 企业集成。
• SaaS 或 self-hosted 部署形态。
• 商业支持。

因此，不能把“开源 KAI Scheduler”直接等同于“完整 Run:ai 平台开源免费”。

如果要采购或生产使用完整 Run:ai 平台，应以 NVIDIA/Run:ai 官方授权、报价和部署合同为准。

9. 完整开源生产落地方案

如果目标是“开源、可生产落地”，不要把所有能力都压到一个调度器里。

更稳的做法是分层：

底座层：  NVIDIA Driver  NVIDIA Container Toolkit  NVIDIA device plugin / GPU Operator  DCGM Exporter资源隔离层：  full GPU 独占  MIG  time-slicing / MPS  DRA平台治理层：  Kueue / Volcano / KAI Scheduler  namespace / quota / priority / queue  多团队资源池 / 队列 / 公平共享 / Gang Scheduling

9.1 方案 A：基础生产栈，最推荐先落地

这是最适合先上线的方案。

组件：

• NVIDIA GPU Operator
• NVIDIA device plugin
• GPU Feature Discovery
• DCGM Exporter
• kube-scheduler
• Namespace / RBAC / ResourceQuota
• Taint / Toleration
• Prometheus / Grafana

适合：

• 1 Pod / 1 full GPU。
• 小团队或单团队 GPU 集群。
• 训练任务数量还没有明显排队。
• 优先要求稳定、可观测、容易排障。

这套方案就可以回答本文最核心的问题：

8 卡 Worker 上，1 个 Pod 只使用 1 张 GPU。

Pod 侧只需要：

resources:  limits:    nvidia.com/gpu: 1

Namespace 配额控制团队上限：

apiVersion: v1kind: ResourceQuotametadata:  name: gpu-quota  namespace: team-aspec:  hard:    requests.nvidia.com/gpu: "4"    limits.nvidia.com/gpu: "4"

这套方案的优点是足够朴素。

朴素不是缺点。GPU 生产环境里，第一优先级通常不是“调度器功能最多”，而是：

• 资源语义清楚。
• 任务失败容易定位。
• 不发生隐性超卖。
• 不让用户误以为共享 GPU 是硬隔离。
• 监控和告警能解释 GPU 利用率、显存、温度、XID 错误。

9.2 方案 B：Kueue，多团队排队和配额治理

当 GPU 集群开始被多个团队共享，单纯 ResourceQuota 往往不够。

典型问题是：

• team-a 一次提交很多 Job，占满 GPU。
• team-b 有配额但抢不到队列顺序。
• 不同 GPU 型号需要做资源池区分。
• 希望任务先进入队列，等资源满足后再 admission。

这时可以引入 Kueue。

组件：

• NVIDIA GPU Operator
• Kueue
• Kubernetes Job / JobSet
• Kubeflow Training Operator
• ResourceFlavor
• ClusterQueue / LocalQueue

Kueue 的核心不是替代 kubelet 或 device plugin，而是做批任务 admission 和队列配额。

推荐结构：

ResourceFlavor:  表达资源类型，例如 A800、H800、L40S、RTX 4090ClusterQueue:  表达集群级资源池和配额LocalQueue:  namespace 内团队提交入口Workload:  Kueue 接管的待 admission 任务

适合：

• 多团队训练。
• Job/JobSet 形态任务。
• Kubeflow PyTorchJob、MPIJob、RayJob 等可和 Kueue 集成的任务。
• 希望资源先排队，再被准入。

不适合：

• 只是要跑少量长驻 Deployment。
• 只需要最简单的 1 Pod / 1 GPU。
• 团队还没有明显的排队和公平共享诉求。

Kueue 落地建议：

1. 先把 GPU 型号打成 node label。
2. 用 ResourceFlavor 对应 GPU 型号或节点池。
3. 用 ClusterQueue 给团队分配 nominal quota。
4. 用 LocalQueue 作为 namespace 内提交入口。
5. 训练任务统一通过 Job/JobSet 或 Training Operator 提交。

9.3 方案 C：Volcano，分布式训练和 Gang Scheduling

如果你的训练任务是分布式的，比如：

• 8 个 worker 必须一起启动。
• 部分 Pod 先启动也没意义。
• 训练框架需要 gang scheduling。
• Spark、Ray、Flink、MPI、PyTorch 分布式训练很多。

这时 Volcano 更合适。

组件：

• NVIDIA GPU Operator
• Volcano Scheduler
• Volcano Queue
• VolcanoJob
• PodGroup
• PyTorchJob / MPIJob / Spark/Ray 集成

Volcano 的核心价值是 batch scheduling 和 gang scheduling。

它适合解决：

一组 Pod 要么一起拿到资源并启动，要么都等着。

否则很容易出现：

• rank 0 启动了，rank 1~7 没资源。
• GPU 被部分 Pod 占住，但任务跑不起来。
• 集群资源碎片化。
• 分布式训练长时间卡住。

适合：

• 大规模分布式训练。
• 大数据和 AI 混部。
• 需要队列、优先级、Gang Scheduling 的集群。

不适合：

• 单 Pod / 单卡为主。
• 只需要普通 Deployment 或简单 Job。
• 团队还没有分布式训练队列治理需求。

9.4 方案 D：KAI Scheduler，Run:ai 调度器的开源路线

KAI Scheduler 是 NVIDIA 开源的 Kubernetes 原生 GPU 调度器，源自 Run:ai 的调度能力。

它适合评估这些方向：

• GPU-aware scheduling。
• AI/ML workload 调度优化。
• 队列和公平共享。
• gang scheduling。
• workload priority。
• 更贴近 Run:ai 调度器思路的开源方案。

但要注意两个边界：

第一，KAI Scheduler 是开源调度器，不是完整 Run:ai 平台。

第二，生产引入任何新调度器，都要 PoC：

• 是否和现有 workload API 兼容。
• 是否支持你当前的训练入口。
• 是否和 GPU Operator、MIG、time-slicing、MPS 策略一致。
• 是否能接入现有监控、审计和告警。
• 失败时是否容易回滚到默认 kube-scheduler。

我的建议是：

如果你明确想走 Run:ai 风格的开源调度路线，再评估 KAI Scheduler。如果只是多团队排队，先看 Kueue。如果是强 gang scheduling 和 AI/big data batch，先看 Volcano。

9.5 开源方案选型表

9.6 我推荐的开源生产落地顺序

第一阶段：先稳住 GPU 底座。

GPU Operatordevice pluginGPU Feature DiscoveryDCGM ExporterResourceQuotataint / tolerationPrometheus / Grafana

目标：

• 节点正确上报 nvidia.com/gpu: 8。
• 业务 Pod 使用 nvidia.com/gpu: 1。
• 容器只看到 1 张 GPU。
• 团队 namespace 有 GPU 配额。
• 监控能看到 GPU 使用率和错误。

第二阶段：引入队列。

如果是普通训练 Job 排队，优先 Kueue。

如果是分布式训练和 gang scheduling，优先 Volcano。

第三阶段：评估高级调度。

如果想贴近 Run:ai 的 GPU 调度能力，再 PoC KAI Scheduler。

如果需要完整平台能力，比如 UI、租户、项目、策略、审计、企业支持，再评估商业 Run:ai。

第四阶段：精细化设备模型。

如果有硬隔离诉求，评估 MIG。

如果有低风险共享诉求，评估 time-slicing/MPS。

如果有按设备属性选择诉求，评估 DRA。

这个顺序的好处是每一步都能独立验收，不会一上来把 GPU 驱动、device plugin、队列、共享、平台全部混在一起排障。

10. 生产最佳实践清单

节点侧：

kubectl describe node <gpu-node> | grep -A10 -E 'Capacity|Allocatable'kubectl get node <gpu-node> \  -L nvidia.com/gpu.present,nvidia.com/gpu.count,nvidia.com/gpu.product,nvidia.com/gpu.replicas,nvidia.com/gpu.sharing-strategy

期望：

• full GPU 独占模式下，8 卡节点显示 nvidia.com/gpu: 8。
• 如果显示远大于 8，要检查是否启用了 time-slicing。
• 如果出现 nvidia.com/gpu.shared，说明共享资源命名已经启用。

Pod 侧：

kubectl exec one-gpu -- nvidia-smi -Lkubectl exec one-gpu -- bash -lc 'echo $NVIDIA_VISIBLE_DEVICES'

调度侧：

kubectl describe pod one-gpukubectl get pod one-gpu -o wide

安全侧：

• 不给普通业务容器 privileged: true。
• 不手写 NVIDIA_VISIBLE_DEVICES。
• 不把 GPU 节点开放给任意 namespace。
• 用 ResourceQuota 限制 namespace 可用 GPU 数量。
• 用 taint/toleration 控制 GPU 节点调度入口。
• 用 DCGM Exporter 监控 GPU 利用率、显存、温度和错误。

Namespace 配额示例：

apiVersion: v1kind: ResourceQuotametadata:  name: gpu-quota  namespace: team-aspec:  hard:    requests.nvidia.com/gpu: "4"    limits.nvidia.com/gpu: "4"

GPU 节点 taint 示例：

kubectl taint node <gpu-node> nvidia.com/gpu=true:NoSchedule

业务 Pod 显式容忍：

tolerations:  - key: nvidia.com/gpu    operator: Equal    value: "true"    effect: NoSchedule

11. 我的推荐路径

如果你是从 0 到 1 落地 GPU on Kubernetes，我建议这样走：

1. 先用 GPU Operator 或 device plugin 跑通 full GPU 独占。
2. 业务统一用 limits.nvidia.com/gpu: 1 1 GPU。
3. 用 namespace quota、taint/toleration、priority class 做基础治理。
4. 用 DCGM Exporter 做 GPU 观测。
5. 多团队普通训练 Job 排队，优先评估 Kueue。
6. 分布式训练需要 gang scheduling，优先评估 Volcano。
7. 想走 Run:ai 调度器的开源路线，再 PoC KAI Scheduler。
8. 如果 GPU 支持 MIG，并且有多租户硬隔离诉求，再启用 MIG。
9. 如果只是开发/低风险推理，需要提高利用率，再评估 time-slicing/MPS。
10. 如果必须按 UUID/拓扑选择设备，规划 DRA，不要用环境变量硬指定。
11. 如果需要完整平台 UI、企业支持、跨团队策略和审计，再评估商业 Run:ai。

一句话总结：

“1 Pod 使用 1 张 GPU”用 nvidia.com/gpu: 1 ；多团队排队优先 Kueue；分布式训练优先 Volcano；类 Run:ai 开源调度路线再看 KAI Scheduler；完整企业平台能力再评估商业 Run:ai。

参考资料

• Kubernetes：Schedule GPUs
• Kubernetes：Device Plugins
• Kubernetes：Dynamic Resource Allocation
• NVIDIA k8s-device-plugin
• NVIDIA GPU Operator
• NVIDIA GPU Operator：GPU Sharing
• NVIDIA GPU Operator：MIG
• NVIDIA GPU Operator：DRA
• NVIDIA DRA Driver for GPUs
• Kueue
• Volcano
• KAI Scheduler
• NVIDIA Run:ai Documentation

title: “GPU on Kubernetes 落地：RKE2、NVIDIA Runtime、Multus 与可登录训练 Pod”
tags:

• Kubernetes
• RKE2
• GPU
• NVIDIA
• Multus
• Whereabouts
• MLOps

GPU on Kubernetes 落地：RKE2、NVIDIA Runtime、Multus 与可登录训练 Pod

这篇文章解决一个很常见、也很容易被低估的问题：

机器上 nvidia-smi 明明能看到 GPU，为什么 Kubernetes 还是调度不了 GPU Pod？

答案通常不在“显卡有没有插好”这一层，而在这条链路里：

Host NVIDIA Driver  -> NVIDIA Container Toolkit  -> containerd 的 nvidia runtime handler  -> Kubernetes RuntimeClass  -> NVIDIA device plugin 初始化 NVML  -> kubelet 上报 nvidia.com/gpu  -> 业务 Pod request/limit nvidia.com/gpu

只要其中一环断开，Kubernetes 调度器就可能“看不见” GPU。

本文基于 RKE2 + containerd + NVIDIA Container Toolkit + NVIDIA device plugin + Multus + Whereabouts 的组合，整理一套可复制的 GPU on K8s 落地方案。

1. 方案目标

本次目标不是单纯跑通一个 nvidia-smi 测试 Pod，而是要交付一个可用于训练、调试和后续扩展的基础形态：

• GPU 节点加入 RKE2 集群。
• Kubernetes 能正确识别并调度 nvidia.com/gpu。
• GPU Pod 显式使用 NVIDIA RuntimeClass。
• 提供一个可 SSH 登录的 GPU 训练 Pod，便于交互式调试。
• 保留默认 Pod 网络，同时通过 Multus 添加二层网卡。
• 支持固定 IP 或地址池自动分配。
• 支持后续扩展为管理网、算力网多网卡模型。
• 明确容器模型下“系统盘”和“数据盘”的边界。

公开博客里的示例采用这些占位符：

2. 为什么“节点有 GPU”不等于“K8s 能调度 GPU”

很多 GPU 接入问题都卡在一个认知误区：

nvidia-smi 在宿主机能跑通，Kubernetes 就应该自动知道这台机器有 GPU。

实际上不是。

Kubernetes 不会天然扫描宿主机上的所有 GPU 并把它们变成可调度资源。它依赖 device plugin 框架把厂商设备注册给 kubelet。

NVIDIA GPU 的常见资源名是：

nvidia.com/gpu

只有当 NVIDIA device plugin 在节点上成功启动、成功初始化 NVML、成功向 kubelet 注册后，节点状态里才会出现类似：

status:  capacity:    nvidia.com/gpu: "1"  allocatable:    nvidia.com/gpu: "1"

如果这里没有 nvidia.com/gpu，调度器就不会把这个节点当作 GPU 节点。

3. 本次问题的典型现象

落地过程中看到的典型现象是：

• GPU 节点已经打了标签，例如 nvidia.com/gpu.present=true。
• 宿主机执行 nvidia-smi 正常。
• 业务 Pod 申请了 nvidia.com/gpu: 1 后一直 Pending。
• kubectl describe node 看不到 nvidia.com/gpu capacity。
• NVIDIA device plugin 日志出现类似错误：

Failed to initialize NVML: could not load NVML library.

这类错误的关键不是“device plugin 本身坏了”，而是它的容器没有通过 NVIDIA runtime 启动。

device plugin 容器如果走默认 runc，容器内可能拿不到 NVIDIA 驱动库和 NVML 能力。它就无法发现 GPU，也无法向 kubelet 注册 nvidia.com/gpu。

最终表现就是：节点上有卡，但 Kubernetes 看不到卡。

4. 节点侧基线：驱动、Toolkit、containerd

GPU 节点首先要满足宿主机层面的条件：

1. NVIDIA 驱动安装完成。
2. 宿主机 nvidia-smi 正常。
3. NVIDIA Container Toolkit 安装完成。
4. containerd 已配置 nvidia runtime handler。
5. RKE2 agent 重启后加载 containerd 配置。

Ubuntu/Debian 系节点安装 Toolkit 的官方流程大致是：

sudo apt-get updatesudo apt-get install -y --no-install-recommends ca-certificates curl gnupg2curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpgcurl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.listsudo apt-get updatesudo apt-get install -y nvidia-container-toolkit

然后配置 containerd：

sudo nvidia-ctk runtime configure --runtime=containerd

普通 containerd 环境通常会生成或修改：

/etc/containerd/conf.d/99-nvidia.toml/etc/containerd/config.toml

但 RKE2 使用的是内置 containerd。实际配置路径通常在：

/var/lib/rancher/rke2/agent/etc/containerd/config.toml

所以在 RKE2 场景里要特别确认：RKE2 最终生成的 containerd 配置里确实包含 nvidia runtime handler，并且 handler 指向 nvidia-container-runtime。

可在 GPU 节点上检查：

sudo grep -n "nvidia" /var/lib/rancher/rke2/agent/etc/containerd/config.toml || truewhich nvidia-container-runtimenvidia-smi

如果修改过 runtime 配置，重启 RKE2 agent：

sudo systemctl restart rke2-agent

5. RuntimeClass：把 nvidia runtime 暴露给 Pod

Kubernetes 的 RuntimeClass 用来让 Pod 选择不同的容器运行时配置。

如果你没有把 NVIDIA runtime 设置成节点默认 runtime，就应该显式创建一个 RuntimeClass/nvidia：

apiVersion: node.k8s.io/v1kind: RuntimeClassmetadata:  name: nvidiahandler: nvidia

验证：

kubectl get runtimeclasskubectl get runtimeclass nvidia -o yaml

业务 Pod 使用时写：

spec:  runtimeClassName: nvidia

这一步非常关键。

仅仅申请 nvidia.com/gpu: 1，并不必然代表容器会用 NVIDIA runtime 启动。资源分配和运行时选择是两件事。

在本文方案里，我们让两类 Pod 都显式使用 runtimeClassName: nvidia：

• NVIDIA device plugin DaemonSet。
• 实际使用 GPU 的业务 Pod。

6. 修复关键：device plugin 自己也要走 NVIDIA runtime

很多人只关注业务 Pod 的 runtimeClassName，但这次真正卡住的是 device plugin 自己。

device plugin 的职责是发现 GPU、监控 GPU 健康状态、向 kubelet 注册资源。

如果 device plugin 这个容器没有通过 NVIDIA runtime 启动，它可能连 NVML 都加载不到。于是 kubelet 就收不到 GPU 注册信息。

下面是一个脱敏后的 DaemonSet 示例。

生产环境建议通过 Helm 或 GitOps 固定版本。示例中的镜像请按你的环境替换为官方镜像、企业镜像仓库或可信镜像代理。

apiVersion: apps/v1kind: DaemonSetmetadata:  name: nvidia-device-plugin-daemonset  namespace: kube-systemspec:  selector:    matchLabels:      app: nvidia-device-plugin-ds  template:    metadata:      labels:        app: nvidia-device-plugin-ds    spec:      runtimeClassName: nvidia      priorityClassName: system-node-critical      nodeSelector:        nvidia.com/gpu.present: "true"      tolerations:        - key: CriticalAddonsOnly          operator: Exists        - key: nvidia.com/gpu          operator: Exists          effect: NoSchedule      containers:        - name: nvidia-device-plugin-ctr          image: nvcr.io/nvidia/k8s-device-plugin:<固定版本>          imagePullPolicy: IfNotPresent          securityContext:            allowPrivilegeEscalation: false            capabilities:              drop: ["ALL"]          volumeMounts:            - name: device-plugin              mountPath: /var/lib/kubelet/device-plugins      volumes:        - name: device-plugin          hostPath:            path: /var/lib/kubelet/device-plugins

几个点要讲清楚：

• runtimeClassName: nvidia：让 plugin 容器能访问 NVIDIA runtime 注入的能力。
• nodeSelector：只跑在标记过的 GPU 节点上。
• priorityClassName：把它作为关键节点组件处理。
• /var/lib/kubelet/device-plugins：device plugin 和 kubelet 通过这个目录下的 socket 通信。

给 GPU 节点打标签：

kubectl label node <gpu-worker-01> nvidia.com/gpu.present=true

应用并等待：

kubectl apply -f nvidia-plugin.yamlkubectl -n kube-system rollout status ds/nvidia-device-plugin-daemonset --timeout=600s

7. GPU 注册验证

先看 device plugin Pod：

kubectl -n kube-system get pod -o wide | grep nvidia-device-pluginkubectl -n kube-system logs -l app=nvidia-device-plugin-ds --tail=200

期望看到类似：

Loading NVMLRegistered device plugin with Kubelet

再看节点资源：

kubectl get node <gpu-worker-01> \  -o jsonpath='capacity={.status.capacity.nvidia\.com/gpu} allocatable={.status.allocatable.nvidia\.com/gpu}{"\n"}'

期望：

capacity=1 allocatable=1

如果这里仍为空，排查顺序建议是：

1. 宿主机 nvidia-smi 是否正常。
2. RKE2 containerd 配置里是否有 nvidia runtime。
3. RuntimeClass/nvidia 是否存在，handler 是否为 nvidia。
4. device plugin Pod 是否真的使用了 runtimeClassName: nvidia。
5. device plugin 日志是否还有 NVML 错误。

8. 最小 GPU 测试 Pod

节点上报 GPU 后，用一个最小 Pod 验证调度链路：

apiVersion: v1kind: Podmetadata:  name: gpu-smoke-testspec:  restartPolicy: Never  runtimeClassName: nvidia  nodeSelector:    kubernetes.io/hostname: <gpu-worker-01>  tolerations:    - key: nvidia.com/gpu      operator: Exists      effect: NoSchedule  containers:    - name: cuda      image: nvidia/cuda:12.4.1-base-ubuntu22.04      command: ["bash", "-lc", "nvidia-smi && echo GPU_OK"]      resources:        limits:          nvidia.com/gpu: 1

执行：

kubectl apply -f gpu-smoke-test.yamlkubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/gpu-smoke-test --timeout=300skubectl logs gpu-smoke-testkubectl delete pod gpu-smoke-test

日志里看到 nvidia-smi 输出和 GPU_OK，说明 GPU 从节点注册到业务容器访问这条链路已经跑通。

9. 可 SSH 登录的 GPU 训练 Pod

很多训练场景早期需要交互式调试。最直接的交付形态是一个 StatefulSet：

• runtimeClassName: nvidia。
• 申请 nvidia.com/gpu: 1。
• 用 Headless Service 保留稳定 DNS。
• 用 NodePort 或后续 LoadBalancer 暴露 SSH。
• 用 Secret 注入 SSH 公钥或临时密码。
• 通过 startupProbe 避免首次安装工具时被 kubelet 误杀。

正式生产不建议直接 root + 密码 + NodePort。下面示例使用 SSH key，并禁用密码登录。

先创建 SSH 公钥 Secret：

kubectl create namespace gpu-trainkubectl -n gpu-train create secret generic gpu-ssh-authorized-keys \  --from-file=authorized_keys=./authorized_keys

StatefulSet 示例：

apiVersion: v1kind: Servicemetadata:  name: gpu-train-headless  namespace: gpu-trainspec:  clusterIP: None  selector:    app: gpu-train  ports:    - name: ssh      port: 22      targetPort: 22---apiVersion: v1kind: Servicemetadata:  name: gpu-train-ssh  namespace: gpu-trainspec:  type: NodePort  selector:    app: gpu-train  ports:    - name: ssh      port: 22      targetPort: 22      nodePort: 30022---apiVersion: apps/v1kind: StatefulSetmetadata:  name: gpu-train  namespace: gpu-trainspec:  serviceName: gpu-train-headless  replicas: 1  selector:    matchLabels:      app: gpu-train  template:    metadata:      labels:        app: gpu-train    spec:      runtimeClassName: nvidia      nodeSelector:        kubernetes.io/hostname: <gpu-worker-01>      terminationGracePeriodSeconds: 10      containers:        - name: main          image: nvidia/cuda:12.4.1-base-ubuntu22.04          imagePullPolicy: IfNotPresent          command: ["bash", "-lc"]          args:            - |              set -euo pipefail              export DEBIAN_FRONTEND=noninteractive              apt-get -o Acquire::ForceIPv4=true -o Acquire::Retries=5 update              apt-get -o Acquire::ForceIPv4=true -o Acquire::Retries=5 install -y --no-install-recommends \                ca-certificates \                openssh-server \                iproute2 \                net-tools \                iputils-ping \                curl \                wget \                git \                vim-tiny \                less \                procps              mkdir -p /run/sshd /root/.ssh              cp /ssh/authorized_keys /root/.ssh/authorized_keys              chmod 700 /root/.ssh              chmod 600 /root/.ssh/authorized_keys              sed -ri 's/^#?PermitRootLogin[[:space:]]+.*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config              sed -ri 's/^#?PasswordAuthentication[[:space:]]+.*/PasswordAuthentication no/' /etc/ssh/sshd_config              sed -ri 's/^#?PubkeyAuthentication[[:space:]]+.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config              exec /usr/sbin/sshd -D -e          volumeMounts:            - name: ssh-authorized-keys              mountPath: /ssh              readOnly: true          ports:            - name: ssh              containerPort: 22          startupProbe:            tcpSocket:              port: 22            periodSeconds: 5            failureThreshold: 360          readinessProbe:            tcpSocket:              port: 22            periodSeconds: 5          livenessProbe:            tcpSocket:              port: 22            periodSeconds: 10          resources:            limits:              nvidia.com/gpu: 1      volumes:        - name: ssh-authorized-keys          secret:            secretName: gpu-ssh-authorized-keys

部署并验证：

kubectl apply -f gpu-ssh.yamlkubectl -n gpu-train rollout status statefulset/gpu-train --timeout=1200skubectl -n gpu-train get pod -o widekubectl -n gpu-train logs -f gpu-train-0

登录：

ssh root@<node-ip> -p 30022

进入容器后验证：

nvidia-smi -Lip -br a

这个形态适合早期调试和小规模训练环境。规模化训练平台建议进一步封装为镜像、模板、队列和租户权限模型。

10. 为什么需要 Multus：默认 Pod IP 不适合所有训练流量

Kubernetes 默认只给 Pod 创建一张网卡，通常叫 eth0。

这张网卡由主 CNI 负责，例如 Cilium、Calico、Flannel 等。它适合服务发现、集群内通信和普通业务访问。

但 GPU 训练场景常常还有额外需求：

• Pod 需要一个和物理网络同网段的固定 IP。
• 运维人员希望直接 SSH 到训练环境。
• 分布式训练希望流量走独立算力网卡。
• RoCE、IB 等网络可能需要绕过默认 Overlay。
• 多租户场景希望管理网、数据网、训练网分离。

这时可以用 Multus 给 Pod 追加第二张、第三张网卡。

本文的网络模型是：

eth0: 主 CNI 创建，保留 Kubernetes 默认 Pod 网络net1: Multus 创建，ipvlan L2，接入管理二层网络net2: 可选，Multus 创建，接入算力网络

11. RKE2 安装 Multus + Whereabouts

RKE2 官方支持通过内置 HelmChart 方式安装 Multus，并可启用 rke2-whereabouts。

示例：

apiVersion: helm.cattle.io/v1kind: HelmChartmetadata:  name: rke2-multus  namespace: kube-systemspec:  repo: https://rke2-charts.rancher.io  chart: rke2-multus  targetNamespace: kube-system  valuesContent: |    rke2-whereabouts:      enabled: true

应用：

kubectl apply -f rke2-multus.yamlkubectl -n kube-system rollout status ds/rke2-multus --timeout=600skubectl -n kube-system rollout status ds/rke2-multus-rke2-whereabouts --timeout=600s

验证 NAD CRD：

kubectl get crd network-attachment-definitions.k8s.cni.cncf.io

验证 CNI 二进制：

ls -l /opt/cni/bin | egrep 'multus|whereabouts|ipvlan|macvlan|static|host-local' || true

注意一个容易踩的点：

rke2-whereabouts DaemonSet 起来，不代表 Whereabouts 所需的所有 CRD 一定已存在。使用 ipam.type: whereabouts 前，应确认：

kubectl get crd | grep whereabouts.cni.cncf.io

至少应看到类似：

ippools.whereabouts.cni.cncf.iooverlappingrangeipreservations.whereabouts.cni.cncf.io

如果缺少 CRD，Pod 可能卡在 ContainerCreating，事件里出现找不到 ippools.whereabouts.cni.cncf.io 的错误。

12. 创建 NetworkAttachmentDefinition

NAD 是 Multus 读取的二网卡配置对象。

下面提供两种模式：

• ipvlan-static：固定 IP。
• ipvlan-pool：Whereabouts 从地址池自动分配 IP。

把 <master-nic> 替换成 GPU 节点上真实存在、已经连入对应二层网络的网卡名。

apiVersion: k8s.cni.cncf.io/v1kind: NetworkAttachmentDefinitionmetadata:  name: ipvlan-static  namespace: gpu-trainspec:  config: |    {      "cniVersion": "0.4.0",      "name": "ipvlan-static",      "type": "ipvlan",      "master": "<master-nic>",      "mode": "l2",      "ipam": {        "type": "static",        "addresses": [          { "address": "10.20.30.240/24" }        ]      }    }---apiVersion: k8s.cni.cncf.io/v1kind: NetworkAttachmentDefinitionmetadata:  name: ipvlan-pool  namespace: gpu-trainspec:  config: |    {      "cniVersion": "0.4.0",      "name": "ipvlan-pool",      "type": "ipvlan",      "master": "<master-nic>",      "mode": "l2",      "ipam": {        "type": "whereabouts",        "range": "10.20.30.241-10.20.30.250/24"      }    }

应用：

kubectl apply -f gpu-train-nads.yamlkubectl -n gpu-train get net-attach-def

让 Pod 挂载固定 IP 二网卡，在 Pod 模板 annotation 里加入：

metadata:  annotations:    k8s.v1.cni.cncf.io/networks: |      [        { "name": "ipvlan-static", "namespace": "gpu-train", "interface": "net1" }      ]

如果使用地址池：

metadata:  annotations:    k8s.v1.cni.cncf.io/networks: |      [        { "name": "ipvlan-pool", "namespace": "gpu-train", "interface": "net1" }      ]

重建 Pod：

kubectl apply -f gpu-ssh.yamlkubectl -n gpu-train delete pod gpu-train-0kubectl -n gpu-train wait --for=condition=Ready pod/gpu-train-0 --timeout=1200s

验证事件：

kubectl -n gpu-train describe pod gpu-train-0 | grep -A3 -E 'AddedInterface|multus'

期望看到类似：

Add net1 [10.20.30.240/24] from gpu-train/ipvlan-static

进入容器：

ip -br aip route

同网段机器可以尝试：

ssh root@10.20.30.240

如果你已经通过 net1 固定 IP 登录，NodePort 可以逐步退场，改成更清晰的二层访问模型。

13. net1 state UNKNOWN 不是一定坏了

使用 ipvlan 时，Pod 内可能看到：

net1@if2  UNKNOWN  10.20.30.240/24

这里的 UNKNOWN 是 Linux 接口 operstate，不等价于“网络不可用”。

很多虚拟接口没有物理网卡那样明确的 carrier 状态，所以内核无法准确显示 UP 或 DOWN，会显示 UNKNOWN。

更重要的是看 flags：

ip -d link show net1

如果能看到 UP、LOWER_UP，并且同网段访问正常，就不需要因为 UNKNOWN 误判故障。

ipvlan L2 模式下，Pod 的 net1 复用宿主机 master 网卡收发二层流量。外部机器访问 10.20.30.240 时，流量会经宿主机物理网卡进入，再转到 Pod 网络命名空间。

需要注意：这类二层旁路网卡不一定受主 CNI 的 NetworkPolicy 约束。安全策略应在节点防火墙、上游交换网络、ACL 或独立 VLAN 上补齐。

14. 扩展：管理网与算力网分离

更接近生产的 GPU 训练网络通常不是一张网卡打天下，而是至少分成：

• 管理网：SSH、运维、控制面访问。
• 存储网：数据集、模型权重、检查点读写。
• 算力网：分布式训练通信，例如 NCCL/Gloo。

如果宿主机有第二张物理网卡或 bond，可继续创建一个算力网 NAD：

apiVersion: k8s.cni.cncf.io/v1kind: NetworkAttachmentDefinitionmetadata:  name: ipvlan-compute-pool  namespace: gpu-trainspec:  config: |    {      "cniVersion": "0.4.0",      "name": "ipvlan-compute-pool",      "type": "ipvlan",      "master": "<compute-nic>",      "mode": "l2",      "ipam": {        "type": "whereabouts",        "range": "192.168.100.10-192.168.100.250/24"      }    }

Pod 同时挂两张二层网卡：

metadata:  annotations:    k8s.v1.cni.cncf.io/networks: |      [        { "name": "ipvlan-static", "namespace": "gpu-train", "interface": "net1" },        { "name": "ipvlan-compute-pool", "namespace": "gpu-train", "interface": "net2" }      ]

训练框架里显式绑定算力网卡，比改默认路由更稳妥。

NCCL 示例：

export NCCL_SOCKET_IFNAME=net2

Gloo 示例：

export GLOO_SOCKET_IFNAME=net2

不要随意把 Pod 默认路由改到算力网，否则可能影响访问 Kubernetes Service、DNS、镜像仓库和控制面。

15. IP 冲突：二层网络里最难排的坑

Multus + ipvlan/macvlan 把 Pod 接到真实二层网络后，IP 冲突会比普通 Overlay 网络更麻烦。

如果使用 static IPAM，两个 Pod 写了同一个 IP，常见表现是：

• SSH 一会能连，一会超时。
• 同一个 IP 的 ARP 记录来回变化。
• 分布式训练随机断开、卡住、吞吐抖动。
• 故障看起来像训练框架问题，但根因在二层地址冲突。

排查：

ip neigh show | grep '<pod-l2-ip>' || truearp -an | grep '<pod-l2-ip>' || truekubectl -n gpu-train describe pod <pod-name> | grep -A5 -E 'multus|whereabouts|Failed'

建议：

• 多副本优先使用 Whereabouts 地址池。
• 必须固定 IP 时，用模板生成每个副本独立 NAD。
• 地址池避开网关、交换机、宿主机、BMC、已有服务器地址。
• 更严谨的生产环境应使用独立 VLAN 或独立物理网络承载训练网。

16. 持久化：容器里的“系统盘”和“数据盘”

有些用户会提出一个很像虚拟机的需求：

我希望训练 Pod 有系统盘和数据盘。重装系统时清空系统盘，但保留数据盘。

在容器模型里，要先把语义讲清楚。

容器的 rootfs 来自镜像，默认是临时写层。你在容器里 apt-get install 到 /usr/bin 的内容，不会因为 StatefulSet 重建而长期稳定保留。

更推荐的做法是：

• 把基础工具、CUDA、SSH、Python、conda 等做进自定义镜像。
• 用 PVC 挂载 /data 保存数据集、输出、模型权重。
• 可选再用一个 PVC 挂载 /workspace 或 /system 保存代码、环境产物和用户态工具。

StatefulSet 增加两块盘：

spec:  volumeClaimTemplates:    - metadata:        name: workspace      spec:        accessModes: ["ReadWriteOnce"]        resources:          requests:            storage: 50Gi    - metadata:        name: data      spec:        accessModes: ["ReadWriteOnce"]        resources:          requests:            storage: 500Gi  template:    spec:      containers:        - name: main          volumeMounts:            - name: workspace              mountPath: /workspace            - name: data              mountPath: /data

StatefulSet 会自动创建类似：

workspace-gpu-train-0data-gpu-train-0

“重装系统但保留数据盘”的容器语义可以这样做：

kubectl -n gpu-train delete pod gpu-train-0kubectl -n gpu-train delete pvc workspace-gpu-train-0# 不删除 data-gpu-train-0kubectl -n gpu-train get pvc data-gpu-train-0

但如果你真正需要 VM 级别的系统盘、快照、回滚和重装语义，应考虑 KubeVirt、Harvester 或传统虚拟化，而不是把容器强行当 VM 使用。

17. 安全基线

GPU 训练环境常常被临时开放成“能登录就行”，但公开或半公开网络中这样风险很高。

建议至少做到：

• 不把 SSH 密码写进 YAML 。
• 优先使用 SSH key，禁用密码登录。
• NodePort 只允许内网、堡垒机或 VPN 访问。
• 二层 net1/net2 所在 VLAN 做 ACL。
• 不把 GPU Pod 暴露到办公网或公网。
• 镜像使用固定 tag 或 digest。
• 用独立 namespace、ResourceQuota 和 LimitRange 控制租户资源。
• 训练数据盘和模型盘配置权限、审计和备份。
• 对可登录 Pod 做生命周期管理，避免长期无人维护。

如果只是临时调试，可以接受 NodePort。

如果是生产平台，应优先走：

用户 -> VPN/堡垒机 -> 平台审计 -> Kubernetes API/Job -> 受控训练环境

NCCL 是大规模 GPU 训练集群验收中最核心的指标之一。它不只是跑一个 all_reduce_perf，而是用集合通信的方式把 GPU、NIC、RoCE、路由、交换机、拥塞控制、驱动版本和节点一致性一起压出来。

一、NCCL 验收要回答什么问题

大规模 NCCL 验收至少要回答四个问题。

第一，单机 8 卡是否健康。单机测试用来排除 GPU、驱动、CUDA、NCCL、本机拓扑问题。如果单机都不稳定，跨机测试没有意义。

第二，双机 16 卡是否稳定。双机测试是跨机通信的最小闭环，可以验证 RoCE、GID、HCA、GDR、业务网控制通道、MPI 启动链路是否正常。

第三，百台级性能曲线是否符合预期。64/128/256 机测试用于观察规模放大后的带宽曲线、尾延迟和慢节点。

第四，整网是否可复跑。350 机以上验收不是为了得到一个漂亮数字，而是证明网络、GPU 和软件栈具备生产稳定性。

二、测试指标如何解读

NCCL Tests 常见字段包括：

重点展示 busbw、消息大小、节点规模、测试轮次和错误数量。更好的方式是给出分规模结果矩阵和结论。

三、推荐测试阶梯

生产验收不要一开始就跑 350 机。建议按下面顺序推进：

单机 8 卡  -> 双机 16 卡  -> 8/16 机冒烟  -> 64 机小规模验收  -> 128 机百台级验收  -> 256 机大规模验收  -> 350 机以上整网验收

每个阶段都要记录：

四、参考命令

单机测试模板：

NCCL_ALGO=ring ./all_reduce_perf \  -g 8 \  -b 8M \  -e 12G \  -f 2

双机和多机测试模板：

mpirun -np <total-ranks> \  -H <node-a>:8,<node-b>:8,... \  --allow-run-as-root \  --bind-to none \  --map-by slot \  --mca btl_tcp_if_include <business-bond> \  --mca oob_tcp_if_include <business-bond> \  -x NCCL_SOCKET_IFNAME=<business-bond> \  -x UCX_NET_DEVICES=<business-bond> \  -x NCCL_IB_DISABLE=0 \  -x NCCL_IB_GID_INDEX=<gid-index> \  -x NCCL_IB_HCA=<train-hca-list> \  -x NCCL_IB_TC=<traffic-class> \  -x NCCL_NET_GDR_LEVEL=<gdr-level> \  ./all_reduce_perf \  -g 1 \  -b 120M \  -e 34G \  -f 2 \  -n 100

AllToAll 测试模板：

mpirun -np <total-ranks> \  -H <node-list> \  <mpi-and-nccl-env> \  ./alltoall_perf \  -b 1M \  -e 2048M \  -f 2 \  -g 1

五、慢节点定位方法

慢节点定位要避免“看到带宽低就换卡”。建议按下面顺序收敛。

第一步，确认是否所有节点都慢。如果所有节点一起下降，优先看全局网络、交换机队列、PFC/ECN、DCQCN、NCCL 参数和业务网控制通道。如果只有少数节点慢，优先看节点本地。

第二步，做排除式测试。把可疑节点从集群里拿掉，复跑同规模或小一档规模测试。如果带宽恢复，说明可疑节点或其上联路径需要深入排查。

第三步，做单机 8 卡测试。确认本机 GPU、驱动、NVSwitch 或 PCIe 拓扑是否正常。

第四步，做单卡隔离。轮流排除某一张 GPU 或某一路 HCA，观察结果是否恢复：

# 示例：排除最后一张 GPU，仅使用 GPU 0-6CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 ./all_reduce_perf \  -g 7 \  -b 8M \  -e 12G \  -f 2

第五步，检查网卡与 RoCE 参数。包括 GID、PFC、ECN、DSCP、CNP、DCQCN、MTU、错误包、丢包、交换机端口统计。

第六步，检查 GPU 和 NVSwitch。包括 nvidia-smi、ECC、row remapper、Fabric Manager、dmesg、lspci。

六、慢节点常见原因矩阵

七、验收报告应该怎么写

一份可用的 NCCL 验收报告，建议至少包含：

1. 集群规模和脱敏节点范围。
2. GPU、驱动、CUDA、NCCL、OFED 版本矩阵。
3. RoCE 关键配置摘要。
4. 单机、双机、小规模、百台级和整网测试结果。
5. AllReduce 和 AllToAll 指标说明。
6. 慢节点处理记录和复测结果。

八、总结

智算集群 NCCL 验收的关键，不是一次跑出高带宽，而是形成从单机到整网的可复跑阶梯。AllReduce 能验证梯度同步类场景，AllToAll 能补充验证更复杂的多对多通信压力。慢节点定位要从 GPU、NIC、RoCE、Fabric、路由和参数一致性逐层排除。

NCCL 是验收工具，也是巡检工具。把 NCCL 测试做成标准化、脱敏化、可复跑的流程，后续扩容、替换、升级和故障恢复都会轻松很多。

在 H20 训练集群里，GPU 通信性能的上限很大程度取决于 RoCEv2 网络工程质量。400G 网卡、Leaf-Spine、ECMP 这些硬件条件只是基础，真正决定稳定性的，是端到端参数是否一致、拥塞控制是否生效、GPU Direct RDMA 是否打通，以及所有配置是否能批量验证。

一、RoCEv2 调优目标

RoCEv2 调优不是追求某个单独参数“看起来正确”，而是让训练流量在大规模集合通信中稳定、低抖动、可定位。

生产环境建议同时关注这些目标：

很多集群的问题不是“完全不能跑”，而是“小规模正常，大规模掉速”。这类问题通常与队列、路由、局部拥塞、少数节点配置漂移有关。

二、RDMA 与 GPU Direct 基线

第一步是让 RDMA 与 NVIDIA GPU Direct RDMA 的基础模块稳定加载。

cat >/etc/modules-load.d/rdma.conf <<'EOF'ib_coreib_umadib_uverbsib_cmrdma_cmiw_cmrdma_ucmmlx5_ibib_ipoibnvidia_peermemnvidia_uvmnvidia_modesetEOFfor module in ib_core ib_umad ib_uverbs ib_cm rdma_cm iw_cm rdma_ucm mlx5_ib ib_ipoib nvidia_peermem nvidia_uvm nvidia_modeset; do  modprobe "${module}"done

验证时不要只看命令返回值，至少要检查：

lsmod | egrep 'mlx5_ib|rdma_cm|nvidia_peermem'ibv_devinfoshow_gidsnvidia-smi topo -m

nvidia_peermem 是 GPU 与 NIC 之间走 GDR 的关键模块。如果这个模块未加载或加载异常，NCCL 仍可能跑通，但跨机带宽和延迟会明显不符合预期。

三、网卡命名、MTU 与路由

8 卡 H20 服务器通常会有多张训练网卡。生产环境不建议依赖系统自动生成的 enp* 名称，因为 BIOS、固件、系统版本变化都可能导致接口名漂移。

建议做法是根据 PCI 地址生成稳定命名，并把训练网卡统一映射到约定名称，例如：

<train-iface-1> -> bond2<train-iface-2> -> bond3...<train-iface-8> -> bond9

这里的 bond2-bond9 更像是项目中的训练网卡命名约定，不一定代表传统意义上的双口链路聚合。这是“训练网卡稳定命名”，原始 udev 规则里的真实 PCI、MAC 和业务命名。

MTU 要和交换机端保持一致。但必须满足三个要求：

1. 服务器端、交换机端、对端服务器一致。
2. GID、路由、策略路由与 MTU 配置一并纳入自动化。
3. 每次调整后通过 ping、RDMA 工具、NCCL 三层验证。

四、RoCE 模式与 GID 检查

ConnectX 网卡需要确认链路类型和 RoCE 控制参数。模板如下：

mst startfor dev in <mst-device-list>; do  mlxconfig -y -d "${dev}" set LINK_TYPE_P1=2  mlxconfig -y -d "${dev}" set ROCE_CONTROL=2donereboot

重启后检查：

for dev in <mst-device-list>; do  mlxconfig -d "${dev}" query | egrep 'LINK_TYPE|ROCE_CONTROL'doneshow_gidscma_roce_mode -d <mlx5-device>

如果 NCCL 使用了固定 NCCL_IB_GID_INDEX，就必须确认所有节点同一张训练网卡上的 GID index 语义一致。否则会出现部分节点通信正常、部分节点连接异常或性能异常的情况。

五、PFC、ECN、DSCP 与 CNP

RoCEv2 建立在以太网上，训练网络需要对拥塞和丢包特别敏感。项目资料中采用了 DSCP 信任、PFC 队列、ECN 开关和 CNP DSCP 48 的组合思路。

for iface in <train-iface-list>; do  mlnx_qos -i "${iface}" --trust dscp --pfc 0,0,0,0,0,1,1,0  echo 48 > "/sys/class/net/${iface}/ecn/roce_np/cnp_dscp"  echo 1 > "/sys/class/net/${iface}/ecn/roce_np/enable/5"  echo 1 > "/sys/class/net/${iface}/ecn/roce_rp/enable/5"done

检查：

for iface in <train-iface-list>; do  echo "### ${iface}"  mlnx_qos -i "${iface}"  cat "/sys/class/net/${iface}/ecn/roce_np/cnp_dscp"done

这里最容易出问题的是“只配服务器，不配交换机”或“服务器与交换机 DSCP/队列不一致”。RoCE 的 PFC 和 ECN 是端到端工程，服务器端正确不代表整网正确。

六、DCQCN 拥塞控制

DCQCN 是 RoCEv2 生产网络里常用的拥塞控制机制。项目资料中启用了 DCQCN 兼容模式和 legacy DCQCN 软件模式：

mst startfor dev in <mst-device-list>; do  mlxconfig -d "${dev}" -y set ROCE_CC_DCQCN_COMPATIBILITY_MODE=1  mlxconfig -d "${dev}" -y set ROCE_CC_LEGACY_DCQCN_SW=1donereboot

检查：

for dev in <mst-device-list>; do  mlxconfig -d "${dev}" query | grep ROCE_CCdone

DCQCN 的价值通常在规模放大后才明显。双机测试可能看不出差异，但到 128 机、256 机甚至整网验收时，拥塞控制不一致会造成带宽波动、尾延迟升高和慢节点。

七、PCI ACS 与 GPU Direct RDMA

PCI ACS 可能把 PCIe 点对点访问重定向到 Root Complex，影响 GPU 与 NIC 之间的直接通信。训练集群中如果需要 GPU Direct RDMA，就要确认 ACS 不阻断关键路径。

lspci -d "*:*:*" | awk '{print $1}' | while read bdf; do  if setpci -s "${bdf}" ECAP_ACS+0x06.w >/dev/null 2>&1; then    setpci -s "${bdf}" ECAP_ACS+0x06.w=0000  fidone

生产上要注意两点：

1. ACS 调整要纳入变更审批，并结合服务器型号、BIOS 和安全策略确认。
2. 调整后必须复跑单机和双机 NCCL，不能只看配置值。

八、NCCL 侧配合项

RoCE 网络调好后，NCCL 侧也要显式绑定正确路径：

mpirun -np <total-ranks> \  -H <node-a>:8,<node-b>:8,... \  --allow-run-as-root \  --bind-to none \  --map-by slot \  --mca btl_tcp_if_include <business-bond> \  --mca oob_tcp_if_include <business-bond> \  -x NCCL_SOCKET_IFNAME=<business-bond> \  -x UCX_NET_DEVICES=<business-bond> \  -x NCCL_IB_DISABLE=0 \  -x NCCL_IB_GID_INDEX=<gid-index> \  -x NCCL_IB_HCA=<train-hca-list> \  -x NCCL_IB_TC=<traffic-class> \  -x NCCL_NET_GDR_LEVEL=<gdr-level> \  ./all_reduce_perf -g 1 -b 120M -e 34G -f 2 -n 100

九、生产调优检查表

十、总结

H20 RoCEv2 调优的核心不是把命令背下来，而是形成闭环：先建立硬件和软件基线，再统一网卡命名和路由，然后配置 RoCE、PFC、ECN、DSCP、DCQCN，最后通过 NCCL 分层验收验证效果。

在 3000卡智算集群里，任何“只有一个节点不一致”的问题，都会在大规模通信中变成慢节点、掉速或超时。生产最佳实践是把所有调优项做成幂等自动化，并且每个配置项都要有验证命令和验收结果。

这篇文章整理的是一个 390 台H20 智算集群的公开版落地经验。项目形态是典型的大规模训练集群：单台服务器 8 张 H20 GPU，训练侧使用 8 张 400G ConnectX-7 网卡承载 RoCEv2 算力网络，业务侧使用 200G x2 bonding 形成 400G 聚合业务网络。

一、为什么大规模 GPU 集群不是“装驱动 + 跑测试”

单机 GPU 服务器交付时，大家容易关注 nvidia-smi 是否正常、CUDA 是否能跑、单机 NCCL 是否有带宽。但到 390 台级规模，集群是否可用不再取决于单点成功，而取决于每一层都能被批量复制、批量验证、批量回滚。

在这个规模下，任何一个细节都会被放大。比如某一批网卡 RoCE 模式没有固化，可能导致双机测试偶发失败；某几个节点 PCI ACS 没有关，可能导致 GPU Direct RDMA 带宽异常；某个 Leaf 下 PFC 或 ECN 配置不一致，可能在 128 机以上才暴露成 NCCL 尾延迟。

因此，生产验收要按“分层基线”推进：

真正的交付目标不是“某一次跑通”，而是任何节点出现异常后，都能快速定界、隔离、恢复，并在恢复后复跑同一套验收基线。

二、集群网络平面设计

这个项目的网络可以按职责拆成三类平面。

第一类是业务管理网。它承载 SSH、调度控制、镜像拉取、运维平台、日志回传、少量数据分发等流量。项目口径中业务侧采用 200G x2 bonding，形成 400G 聚合能力。这里要特别注意，bond 的聚合速率不等于单 TCP 流一定能吃满 400G，实际还取决于 bonding 模式、交换机聚合算法、五元组分布和上层业务并发模型。

第二类是 RoCEv2 算力网络。每台 8 卡 H20 服务器配 8 张 400G 训练网卡，常见目标是尽量让 GPU 和 NIC 建立稳定、可预测的亲和关系，使 NCCL 在跨机通信时能充分利用多 HCA、多路径和 ECMP。这里的关键不是“网卡速率足够高”，而是 RoCE 的无损队列、拥塞控制、DSCP、PFC、ECN、GID、MTU 等参数必须端到端一致。

第三类是存储数据路径。训练数据读取和 Checkpoint 写入可以走独立存储网络，也可以复用高速数据网络。无论使用 CephFS、对象存储、并行文件系统，还是缓存层，存储验收都不能只看单次顺序读写带宽，还要同时看延迟分布、客户端 CPU、网卡速率、服务端 OSD 或磁盘利用率。

三、单机 8 卡服务器基线

单机基线要先回答四个问题。

第一，硬件是否完整识别。GPU 数量、NIC 数量、NVSwitch 或 PCIe 设备数量必须和 BOM 一致。对 8 卡服务器来说，不能只看 nvidia-smi 是否显示 8 张卡，还要看 PCIe BDF、GPU UUID、网卡 PCI 地址、NUMA 亲和、NVLink/NVSwitch 状态。

第二，软件栈是否一致。大规模集群最怕“少数节点版本漂移”。驱动、CUDA、NCCL、OFED、固件、BIOS 参数都要形成版本矩阵。本文项目资料中的单机 NCCL 证据图可以看到 H20-3e 设备和 NCCL 测试输出，适合公开证明机器类型和测试方法。

第三，GPU Direct RDMA 是否可用。H20 跨机训练的通信路径不能只停留在 TCP 或普通 RDMA，要确保 nvidia_peermem、mlx5_ib、rdma_cm 等模块加载正常，PCI ACS 不阻断点对点访问，NCCL 能正确选择 IB/RoCE 路径。

第四，单机 NCCL 是否稳定。单机 8 卡测试的价值不是替代整网测试，而是尽早排除 GPU、NVLink/NVSwitch、驱动、CUDA、NCCL 本地问题。单机不稳定时，直接上百台测试只会制造噪声。

四、从单机到整网的验收阶梯

大规模 NCCL 验收建议分阶段推进。

项目资料中的脱敏 NCCL 结果显示，64 机、128 机、256 机和 350 机验收批次均达到预期。这里需要强调一点：NCCL 的 busbw 不是单张网卡线速，也不是所有网卡线速简单相加，它是集合通信算法下的有效总线带宽指标。解读结果时，要结合消息大小、迭代次数、算法、协议、节点规模和网络拓扑。

五、生产交付的关键原则

第一，所有配置必须自动化。包括 RDMA 模块持久化、网卡命名、RoCE 模式、DSCP、PFC、ECN、DCQCN、ACS、NCCL 环境变量模板。手工配置可以用于排障，但不能作为集群的生产交付方式。

第二，所有自动化必须可验证。每个配置项都要有检查命令和期望输出。例如配置了 CNP DSCP，就要能批量读取对应 sysfs 值；配置了 DCQCN，就要能批量查询网卡固件参数；加载了 nvidia_peermem，就要能从模块列表和 NCCL 结果确认生效。

第三，验收结果必须可复跑。生产环境里经常会有节点替换、固件升级、网络维护、驱动升级。没有可复跑的验收模板，后续任何变更都只能靠经验判断，风险会越来越高。

第四，故障定界必须闭环。GPU 掉卡、NVSwitch 异常、Fabric Manager 启动失败、NCCL 慢节点、RoCE 丢包，都不能停留在“重启好了”。每一次恢复都要记录现象、证据、判断、动作和复测结果。

六、总结

智算集群的核心难点不是单个组件，而是硬件、网络、GPU 通信、存储和运维之间的系统协同。一个可靠的交付方案，应该具备清晰的网络分层、统一的软件栈、可自动化的 RoCE 调优、分阶段的 NCCL 验收、可复跑的测试模板，以及面向生产的故障定界闭环。

如果只能给一个建议，那就是：不要把大规模 GPU 集群交付做成一次性工程。它应该是一套可以持续验证、持续修复、持续扩容的生产系统。

一、测试概述

本次压测旨在验证基于Ceph存储集群在GPU服务器高负载场景下的性能表现，涵盖顺序读写、随机读写、高并发IOPS及延迟控制等多个维度。测试采用fio工具，模拟多种I/O模式，评估存储系统的吞吐量、IOPS与延迟表现。

二、硬件配置概述

1. Ceph存储节点（3台）

• CPU：SR660V2 5318Y × 2
• 内存：256GB
• 数据盘组合：
  • 4 × 3.84TB NVMe U.2（PCIe 4.0, QLC NAND）
• 网络：双口100G网卡

2. GPU客户端服务器

• CPU：Intel Xeon Platinum 8558，192核
• 内存：2TB
• 网络：400Gbps网卡
• CephFS挂载点：容量14TB

# CPUCPU(s):                   192  On-line CPU(s) list:    0-191Vendor ID:                GenuineIntel  Model name:             INTEL(R) XEON(R) PLATINUM 8558    CPU family:           6    Model:                207    Thread(s) per core:   2    Core(s) per socket:   48# 内存root@GPU-Server-leaf-1-3:~# free -h               total        used        free      shared  buff/cache   availableMem:           2.0Ti        16Gi       1.9Ti        23Gi        23Gi       1.9Ti# 网卡速率Advertised pause frame use: NoAdvertised auto-negotiation: YesAdvertised FEC modes: RSSpeed: 400000Mb/sDuplex: FullAuto-negotiation: onPort: FIBREPHYAD: 0Transceiver: internalSupports Wake-on: dWake-on: dLink detected: yes

三、吞吐量压测

4M顺序写-吞吐

fio -direct=1 -iodepth=128 -rw=write -ioengine=libaio -bs=4M -numjobs=12 -size=50G -time_based=1 -runtime=600 -group_reporting -filename=/mnt/cephfs/write_test -name=Write_Test

CPU/内存使用率

网卡速率

磁盘使用率

吞吐量 11.3GiB/s 延迟 532ms/s

4M顺序读-吞吐

fio -direct=1 -iodepth=128 -rw=read -ioengine=libaio -bs=4M -numjobs=12 -size=50G -time_based=1 -runtime=600 -group_reporting -filename=/mnt/cephfs/Read_Test -name=Read_Test

吞吐量 15.6GiB/s 延迟383ms/s

4M顺序读写-吞吐

fio -direct=1 -iodepth=128 -rw=rw -ioengine=libaio -bs=4M -numjobs=12 -size=50G -time_based=1 -runtime=600 -group_reporting -filename=/mnt/cephfs/readwrite_test -name=Read_Write_Test

读写吞吐量 10.1GiB/s 延迟290-302ms

四、IOPS压测

<5ms延迟 4K 随机写-IOPS

# numjobs=4fio -direct=1 -iodepth=128 -rw=randwrite -ioengine=libaio -bs=4k -numjobs=4 -size=50G -time_based=1 -runtime=300 -group_reporting -filename=/mnt/cephfs/Rand_Write_Test -name=Rand_Write_Test

IOPS 172K/s 延迟3ms/s

• 平均延迟 (lat avg) 3ms
• 延迟分布 (95.00th) 95%请求<5ms
• 平均IOPS 172K/s

<5ms延迟 4k 随机读-IOPS

# numjobs=6fio -direct=1 -iodepth=128 -rw=randread -ioengine=libaio -bs=4k -numjobs=6 -size=50G -time_based=1 -runtime=300 -group_reporting -filename=/mnt/cephfs/Rand_Read_Test -name=Rand_Read_Test

IOPS 326K/s 延迟2.4ms/s

• 平均延迟 (lat avg) 2.4ms
• 延迟分布 (99.90th) 99.9%请求<5.3ms
• 平均IOPS 326K/s

<5ms延迟 4k 随机读写-IOPS

# numjobs=6fio -direct=1 -iodepth=128 -rw=randrw -ioengine=libaio -bs=4k -numjobs=6 -size=50G -time_based=1 -runtime=300 -group_reporting -filename=/mnt/cephfs/Rand_Read_Write_Test -name=Rand_Read_Write_Test

读写IOPS 122K/s

• 读平均延迟 (lat avg) 2.7ms
• 写平均延迟 (lat avg) 3.5ms
• 读延迟分布 (99.00th) 99%请求<5ms
• 写延迟分布 (95.00th) 95%请求<5.3ms
• 平均IOPS 122K/s

<10ms延迟 4k随机读IOPS

# numjobs需要逐步增加，找到<10ms的极限值。numjobs=12fio -direct=1 -iodepth=128 -rw=randread -ioengine=libaio -bs=4k -numjobs=8 -size=50G -time_based=1 -runtime=300 -group_reporting -filename=/mnt/cephfs/Rand_Read_Test -name=Rand_Read_Test

IOPS 433K/s 延迟3.5ms/s

• 平均延迟 (lat avg) 3.5ms
• 延迟分布 (99.50th) 99.5%请求<10.2ms
• 平均IOPS 433K/s

<10ms延迟 4k随机写IOPS

# numjobs需要逐步增加，找到<10ms的极限值。numjobs=8fio -direct=1 -iodepth=128 -rw=randwrite -ioengine=libaio -bs=4k -numjobs=8 -size=50G -time_based=1 -runtime=300 -group_reporting -filename=/mnt/cephfs/Rand_Write_Test -name=Rand_Write_Test

IOPS 198K/s 延迟5.2ms/s

• 平均延迟 (lat avg) 5.2ms
• 延迟分布 (95.00th) 95%请求<9.4ms
• 平均IOPS 198K/s

<10ms延迟 4k随机读写IOPS

# numjobs需要逐步增加，找到<10ms的极限值。numjobs=8fio -direct=1 -iodepth=128 -rw=randrw -ioengine=libaio -bs=4k -numjobs=8 -size=50G -time_based=1 -runtime=300 -group_reporting -filename=/mnt/cephfs/Rand_Read_Write_Test -name=Rand_Read_Write_Test

读写IOPS 137K/s

• 读平均延迟 (lat avg) 3.2ms
• 写平均延迟 (lat avg) 4.3ms
• 读延迟分布 (99.90th) 99.9%请求<10.3ms
• 写延迟分布 (99.50th) 99.5%请求<10.6ms
• 平均IOPS 137K/s

五、系统稳定性评估

• 测试过程中未出现性能波动或异常中断，Ceph集群与客户端系统运行稳定。
• 各节点硬件资源（CPU、内存、网络、磁盘）利用率均衡，无单点瓶颈。

六、结论

本次压测表明，当前Ceph存储集群在搭配高性能GPU服务器时，能够充分发挥NVMe硬盘的性能潜力，在顺序读写、随机读写及高并发IOPS场景下均表现出色，且系统资源无瓶颈，满足高性能计算与AI训练等场景的存储需求。

1.1 中心机房+边缘机房

1.1 组件高可用

1.2 边缘自治机制

• 中心机房故障后，由边缘机房的n9e-edge发出告警消息

1.3 数据存储计划

2. 功能配置说明

2.1 配置数据源

http://192.168.137.20:8481/select/0/prometheus/http://192.168.137.20:8480/insert/0/prometheus/api/v1/write# 时序库选择victoriametrics

2.2 创建团队/用户，团队可以根据不同部门或业务组区分，方便后续发送告警

2.3 创建用户并填写手机号，后续告警会通过手机号AT对应的人员，将用户分别加入对应的团队组里

2.4 红橙绿字段模板

{{if $event.IsRecovered}}{{else}}{{end}}{{$event.RuleName}}  - - -  {{if $event.IsRecovered}}<font color='#008800'>**告警名称**:</font> {{$event.AnnotationsJSON.summary}}  <font color='#008800'>**告警区域**:</font> {{if $event.TagsMap.business}}{{$event.TagsMap.business}}{{else}}N/A{{end}}  <font color='#008800'>**告警主机**:</font> {{if $event.TagsMap.instance}}{{$event.TagsMap.instance}}{{else}}N/A{{end}}  <font color='#008800'>**告警项目**:</font> {{if $event.TagsMap.project}}{{$event.TagsMap.project}}{{else}}N/A{{end}}  <font color='#008800'>**告警服务**:</font> {{if $event.TagsMap.service}}{{$event.TagsMap.service}}{{else}}N/A{{end}}  <font color='#008800'>**告警级别**:</font> {{if eq $event.Severity 1}}critical{{else if eq $event.Severity 2}}warning{{else}}info{{end}}  <font color='#008800'>**告警信息**:</font> {{if $event.AnnotationsJSON.description}}{{$event.AnnotationsJSON.description}}{{else}}{{$event.AnnotationsJSON.summary}}{{end}}  <font color='#008800'>**告警时间**:</font> {{timeformat $event.TriggerTime "2006.01.02 15:04:05"}}  <font color='#008800'>**恢复时间**:</font> {{timeformat $event.LastEvalTime "2006.01.02 15:04:05"}}  {{else}}{{if eq $event.Severity 1}} <!-- Critical --><font color='#FF0000'>**告警名称**:</font> {{$event.AnnotationsJSON.summary}}  <font color='#FF0000'>**告警区域**:</font> {{if $event.TagsMap.business}}{{$event.TagsMap.business}}{{else}}N/A{{end}}  <font color='#FF0000'>**告警主机**:</font> {{if $event.TagsMap.instance}}{{$event.TagsMap.instance}}{{else}}N/A{{end}}  <font color='#FF0000'>**告警项目**:</font> {{if $event.TagsMap.project}}{{$event.TagsMap.project}}{{else}}N/A{{end}}  <font color='#FF0000'>**告警服务**:</font> {{if $event.TagsMap.service}}{{$event.TagsMap.service}}{{else}}N/A{{end}}  <font color='#FF0000'>**告警级别**:</font> critical  <font color='#FF0000'>**告警信息**:</font> {{if $event.AnnotationsJSON.description}}{{$event.AnnotationsJSON.description}}{{else}}{{$event.AnnotationsJSON.summary}}{{end}}  <font color='#FF0000'>**告警时间**:</font> {{timeformat $event.TriggerTime "2006.01.02 15:04:05"}}  {{else if eq $event.Severity 2}} <!-- Warning --><font color='#FFA500'>**告警名称**:</font> {{$event.AnnotationsJSON.summary}}  <font color='#FFA500'>**告警区域**:</font> {{if $event.TagsMap.business}}{{$event.TagsMap.business}}{{else}}N/A{{end}}  <font color='#FFA500'>**告警主机**:</font> {{if $event.TagsMap.instance}}{{$event.TagsMap.instance}}{{else}}N/A{{end}}  <font color='#FFA500'>**告警项目**:</font> {{if $event.TagsMap.project}}{{$event.TagsMap.project}}{{else}}N/A{{end}}  <font color='#FFA500'>**告警服务**:</font> {{if $event.TagsMap.service}}{{$event.TagsMap.service}}{{else}}N/A{{end}}  <font color='#FFA500'>**告警级别**:</font> warning  <font color='#FFA500'>**告警信息**:</font> {{if $event.AnnotationsJSON.description}}{{$event.AnnotationsJSON.description}}{{else}}{{$event.AnnotationsJSON.summary}}{{end}}  <font color='#FFA500'>**告警时间**:</font> {{timeformat $event.TriggerTime "2006.01.02 15:04:05"}}  {{else}} <!-- Info --><font color='#0000FF'>**告警名称**:</font> {{$event.AnnotationsJSON.summary}}  <font color='#0000FF'>**告警区域**:</font> {{if $event.TagsMap.business}}{{$event.TagsMap.business}}{{else}}N/A{{end}}  <font color='#0000FF'>**告警主机**:</font> {{if $event.TagsMap.instance}}{{$event.TagsMap.instance}}{{else}}N/A{{end}}  <font color='#0000FF'>**告警项目**:</font> {{if $event.TagsMap.project}}{{$event.TagsMap.project}}{{else}}N/A{{end}}  <font color='#0000FF'>**告警服务**:</font> {{if $event.TagsMap.service}}{{$event.TagsMap.service}}{{else}}N/A{{end}}  <font color='#0000FF'>**告警级别**:</font> info  <font color='#0000FF'>**告警信息**:</font> {{if $event.AnnotationsJSON.description}}{{$event.AnnotationsJSON.description}}{{else}}{{$event.AnnotationsJSON.summary}}{{end}}  <font color='#0000FF'>**告警时间**:</font> {{timeformat $event.TriggerTime "2006.01.02 15:04:05"}}  {{end}}{{end}}

2.4.1 告警与恢复效果

2.5 部署categraf采集器，使用自愈功能需部署此采集器

# 下载安装包，里面集成了所有插件https://github.com/flashcatcloud/categraf/releasestar zxf categraf-v0.4.14-linux-amd64.tar.gz -C /data/mv /data/categraf-v0.4.14-linux-amd64 /data/categraf# 创建主配置文件cd /data/categrafvim conf/config.toml[global]# 启动的时候是否在stdout中打印配置内容print_configs = false# 机器名，作为本机的唯一标识，会为时序数据自动附加一个 agent_hostname=$hostname 的标签# hostname 配置如果为空，自动取本机的机器名# hostname 配置如果不为空，就使用用户配置的内容作为hostname# 用户配置的hostname字符串中，可以包含变量，目前支持两个变量，# $hostname 和 $ip，如果字符串中出现这两个变量，就会自动替换# $hostname 自动替换为本机机器名，$ip 自动替换为本机IP# 建议大家使用 --test 做一下测试，看看输出的内容是否符合预期# 这里配置的内容，在--test模式下，会显示为 agent_hostname=xxx 的标签hostname = ""# 是否忽略主机名的标签，如果设置为true，时序数据中就不会自动附加agent_hostname=$hostname 的标签omit_hostname = false# 时序数据的时间戳使用ms还是s，默认是ms，是因为remote write协议使用ms作为时间戳的单位precision = "ms"# 全局采集频率，15秒采集一次interval = 15# 全局附加标签，一行一个，这些写的标签会自动附到时序数据上[global.labels]service="pvenode"business="SZ"project="yw"[log]# 默认的log输出，到标准输出(stdout) # 如果指定为文件, 则写入到指定的文件中file_name = "stdout"# options below will not be work when file_name is stdout or stderr# 如果是写入文件，最大写入大小，单位是MBmax_size = 100# max_age is the maximum number of days to retain old log files based on the timestamp encoded in their filename.# 保留多少天的日志文件max_age = 30# max_backups is the maximum number of old log files to retain.# 保留多少个日志文件max_backups = 7# local_time determines if the time used for formatting the timestamps in backup files is the computer's local time.# 是否使用本地时间local_time = true# Compress determines if the rotated log files should be compressed using gzip.# 是否将老文件压缩（gzip格式)compress = true# 发给后端的时序数据，会先被扔到 categraf 内存队列里，每个采集插件一个队列# chan_size 定义了队列最大长度# batch 是每次从队列中取多少条，发送给后端backend[writer_opt]# default: 2000batch = 2000# channel(as queue) sizechan_size = 10000# 后端backend配置，在toml中 [[]] 表示数组，所以可以配置多个writer# 每个writer可以有不同的url，不同的basic auth信息[[writers]]# 注意端口号# v5版本端口是19000# v6+版本端口是17000# 写入vmagent，由vmagent聚合重写标签再push到vminseturl = "http://127.0.0.1:8429/api/v1/write"# Basic auth usernamebasic_auth_user = ""# Basic auth passwordbasic_auth_pass = ""# timeout settings, unit: mstimeout = 10000dial_timeout = 3000max_idle_conns_per_host = 100# 是否开启push gateway[http]enable = falseaddress = ":9100"print_access = falserun_mode = "release"# 是否启用告警自愈agent[ibex]enable = true## ibex flush intervalinterval = "2000ms"## n9e ibex server rpc addressservers = ["192.168.137.20:20090"]## temp script dirmeta_dir = "./meta"# 心跳上报（附带资源信息,对象列表中使用），适用于夜莺v6+# 如果是v5版本，这里不需要保留[heartbeat]enable = true# 如果心跳携带参数 gid=<group_id> 可以实现自动归属于某个业务组效果# report os version cpu.util mem.util metadataurl = "http://192.168.137.20:17000/v1/n9e/heartbeat"# interval, unit: sinterval = 10# Basic auth usernamebasic_auth_user = ""# Basic auth passwordbasic_auth_pass = ""## Optional headers# headers = ["X-From", "categraf", "X-Xyz", "abc"]# timeout settings, unit: mstimeout = 5000dial_timeout = 3000max_idle_conns_per_host = 100# embeded prometheus agent mode[prometheus]# 是否启用 prometheus agent mode 功能enable = false# 可直接使用 prometheus 的 scrape yaml 文件，来描述抓取任务scrape_config_file = "/path/to/in_cluster_scrape.yaml"## log level, debug warn info errorlog_level = "info"## wal file storage path ,default ./data-agent# wal_storage_path = "/path/to/storage"## wal reserve time duration, default value is 2 hour# wal_min_duration = 2 # 安装，自动添加system_service./categraf  --install# 启动systemctl start categraf.servicesystemctl status categraf.service# 看日志是否有写入数据报错journalctl -f -u categraf.service# 如果需要使用哪个插件，就在插件的配置文件添加target和采集规则

2.6 告警自愈功能配置

2.6.1 已部署categraf的机器才会自动注册到全部机器的列表，然后把机器加入告警规则的业务组

• 注意，一定要把机器加入对应业务组，否则告警自愈模板不会触发

2.6.2 在对应业务组创建告警自愈的模板

• host一定要填机器的名字，IP是不通的

2.6.3 批量设置告警规则或设置单个规则，选择对应的自愈模板

2.6.4 然后触发告警测试，观察告警自愈的历史任务是否有执行结果

2.6.5 选择历史任务的stdouts日志输出，查看流程是否执行成功，并且状态是否success

3. 部署边缘机房edge

• 依赖的组件：victoriametrics集群/Redis集群
• edge的pushgw.Writers的配置是本地边缘机房的victoria，存储的是告警元数据，并不是监控数据，但是与监控数据的victoria共用了同一套集群

# 必须要依赖redis，每个边缘机房都要独立的。这里方便模拟，只部署了单机cat docker-compose.yml version: '3.7'networks:  n9e-edge:    driver: bridgeservices:  redis:    image: "redis:6.2"    container_name: redis    hostname: redis    restart: always    environment:      TZ: Asia/Shanghai    networks:      - n9e-edge    ports:      - "6379:6379"            docker-compose up -d# 部署单机victoriametrics，方便模拟wget https://github.com/VictoriaMetrics/VictoriaMetrics/releases/download/v1.122.0/victoria-metrics-linux-amd64-v1.122.0.tar.gztar zxf victoria-metrics-linux-amd64-v1.122.0.tar.gz -C /usr/bincat > /etc/systemd/system/victoria-metrics.service <<'EOF'[Unit]Description=Linux VictoriaMetrics ServerDocumentation=https://docs.victoriametrics.com/After=network.target[Service]ExecStart=/usr/bin/victoria-metrics-prod -httpListenAddr=0.0.0.0:8428 -storageDataPath=/data/victoria-metrics -retentionPeriod=3[Install]WantedBy=multi-user.targetEOFsystemctl daemon-reloadsystemctl enable --now victoria-metrics.servicesystemctl status victoria-metrics.service# 部署edge组件，在官方n9e压缩包已经包括了wget https://github.com/ccfos/nightingale/releases/download/v8.2.2/n9e-v8.2.2-linux-amd64.tar.gzmkdir /data/n9e-edge/tar zxf n9e-v8.2.2-linux-amd64.tar.gz -C /data/n9e-edge/cd /data/n9e-edge# 修改basicauthpass的token鉴权，与n9e配置文件内一致，开启apiforservice，修改日志级别，开启ibex，修改redis地址# 同一个边缘机房多个edge的enginename一定要一致vim etc/edge/edge.toml[Global]RunMode = "release"[CenterApi]# 改成n9e中心机房的ip地址。还需要修改basicauthpass的token鉴权，与n9e配置文件内一致Addrs = ["http://192.168.137.20:17000"]BasicAuthUser = "user001"BasicAuthPass = "ccc26da7b9aba533cbb263sdklf902384"# unit: msTimeout = 9000[Log]# log write dirDir = "logs"# log level: DEBUG INFO WARNING ERROR# 生产环境改为WARNING模式Level = "DEBUG"# stdout, stderr, fileOutput = "stdout"# # rotate by time# KeepHours = 4# # rotate by size# RotateNum = 3# # unit: MB# RotateSize = 256[HTTP]# http listening addressHost = "0.0.0.0"# http listening portPort = 19000# https cert file pathCertFile = ""# https key file pathKeyFile = ""# whether print access logPrintAccessLog = false# whether enable pprofPProf = false# expose prometheus /metrics?ExposeMetrics = true# http graceful shutdown timeout, unit: sShutdownTimeout = 30# max content length: 64MMaxContentLength = 67108864# http server read timeout, unit: sReadTimeout = 20# http server write timeout, unit: sWriteTimeout = 40# http server idle timeout, unit: sIdleTimeout = 120[HTTP.APIForAgent]Enable = true # [HTTP.APIForAgent.BasicAuth]# user001 = "ccc26da7b9aba533cbb263a36c07dcc5"# 一定要改为true，否则无法启动[HTTP.APIForService]Enable = true[HTTP.APIForService.BasicAuth]# 修改token鉴权，与n9e配置文件内一致user001 = "ccc26da7b9aba533cbb263sdklf902384"[Alert][Alert.Heartbeat]# auto detect if blankIP = ""# unit msInterval = 1000# 同一个机房一定要同一个名字EngineName = "shenzhen-region"# [Alert.Alerting]# NotifyConcurrency = 10[Pushgw]# use target labels in database instead of in seriesLabelRewrite = true# # default busigroup key name# BusiGroupLabelKey = "busigroup"ForceUseServerTS = true# [Pushgw.DebugSample]# ident = "xx"# __name__ = "xx"# [Pushgw.WriterOpt]# QueueMaxSize = 1000000# QueuePopSize = 1000[[Pushgw.Writers]] # 这个是单机版的victoriametricsUrl = "http://192.168.137.23:8428/api/v1/write"# Basic auth usernameBasicAuthUser = ""# Basic auth passwordBasicAuthPass = ""# timeout settings, unit: msHeaders = ["X-From", "n9e"]Timeout = 10000DialTimeout = 3000TLSHandshakeTimeout = 30000ExpectContinueTimeout = 1000IdleConnTimeout = 90000# time duration, unit: msKeepAlive = 30000MaxConnsPerHost = 0MaxIdleConns = 100MaxIdleConnsPerHost = 100## Optional TLS Config# UseTLS = false# TLSCA = "/etc/n9e/ca.pem"# TLSCert = "/etc/n9e/cert.pem"# TLSKey = "/etc/n9e/key.pem"# InsecureSkipVerify = false# [[Writers.WriteRelabels]]# Action = "replace"# SourceLabels = ["__address__"]# Regex = "([^:]+)(?::\\d+)?"# Replacement = "$1:80"# TargetLabel = "__address__"# 开启为true，categraf的配置文件可以改为edge的IP地址[Ibex]Enable = trueRPCListen = "0.0.0.0:20090"[Redis]# address, ip:port or ip1:port,ip2:port for cluster and sentinel(SentinelAddrs)# 修改为边缘机房本地的redis集群地址Address = "127.0.0.1:6379"# Username = ""# Password = ""# DB = 0# UseTLS = false# TLSMinVersion = "1.2"# standalone cluster sentinelRedisType = "standalone"# Mastername for sentinel type# MasterName = "mymaster"# SentinelUsername = ""# SentinelPassword = ""cat > /etc/systemd/system/n9e-edge.service <<'EOF'[Unit]Description="n9e-edge"After=network.target[Service]Type=simpleExecStart=/data/n9e-edge/n9e-edge -configs /data/n9e-edge/etc/edgeWorkingDirectory=/data/n9e-edge/etc/edgeRestart=on-failureSuccessExitStatus=0LimitNOFILE=65536StandardOutput=syslogStandardError=syslogSyslogIdentifier=n9e-edgeOOMScoreAdjust=-1000[Install]WantedBy=multi-user.targetEOFsystemctl daemon-reloadsystemctl enable --now n9e-edge.servicesystemctl status n9e-edge.service

3.1 配置所有边缘机房的数据源，关联对应的告警引擎enginename

3.2 通过业务组来区分不同的采集器，例如exporter和telegraf

3.3 将告警规则关联所有边缘机房的数据源，这里精确匹配边缘的数据源来进行测试

3.4 将告警阈值调低，让夜莺更新告警规则，并下沉到边缘机房edge

3.5 马上将中心机房的3台集群包括夜莺，直接断开电源模拟故障

3.6 然后观察edge的日志，验证边缘机房告警下沉是否能正常发出

• 中心机房故障，只保留边缘机房。告警规则由edge去本地边缘机房victoria查询，告警消息由edge发送
• 中心机房恢复后，edge是不会发送恢复告警的，因为此时中心机房的victoria已经恢复，由n9e夜莺接管了，重新改回正常触发阈值。除非不修改回正常的触发阈值，再等下一次由n9e触发的告警

4. 模拟2个边缘机房故障情况

4.1 先将所有告警规则批量改为匹配所有数据源，确保中心机房+所有边缘机房都关联起来

4.2 将其中1个告警规则的阈值调低，然后马上将2个边缘机房断电模拟故障

• 告警规则阈值调低后，边缘的vmagent会推送数据到中心机房，因此告警会从中心机房的监控数据中获取并触发

5. 配置电话告警

5.1 先去阿里云创建语音通知模板

模板内容

告警机房：${business}，告警消息为：${summary}，当前触发值为：${values}，告警级别：${severity}，请及时处理。

5.2 夜莺创建Aliyun_Voice通知媒介

5.3 请求参数填写阿里云的通知模板TtsCode和Number等信息

AccessKeyId=LTAI5tQhsjxxxxxAccessKeySecret=30cFbeMS4xxxxCalledNumber={{ $sendto }}CalledShowNumber=阿里云的电话TtsCode=模板codeTtsParam={"business":"{{$tpl.business}}","summary":"{{$tpl.summary}}","values":"{{$tpl.values}}","severity":"{{$tpl.severity}}"}

5.4 配置消息模板，选择Aliyun Voice的模板进行修改

# 字段标识必须与上面的{{$tpl.business}}，模板key一致business={{$event.TagsMap.business}}severity={{if eq $event.Severity 1}}critical{{else if eq $event.Severity 2}}warning{{else}}info{{end}}summary={{$event.AnnotationsJSON.summary}}values={{$event.TriggerValue}}

5.5 团队添加对应的人员，通知规则选择接收团队

5.6 测试电话告警，将通知规则添加对应的告警通道

很简单的一个问题，你是想要学习解决问题的思路和方法，还是直接就想要享受成果？

授人以渔是传道解惑，在回答你的问题时可以得到正反馈、满足感，同时也意味着这个领域内增加了一些优质的新鲜血液，因此我们乐于授人以渔。

以问为舟，渡运维之海，一个好的问题，如同在迷雾中点亮灯塔，不仅照亮眼前的困境，更指引思考的方向。一个宽泛的问题如同没有坐标的地图，而一个精准的问题，则是带有经纬度的导航。

一、为什么提问比答案更重要？

1. 从“经验”到“实践”的认知革命

运维这条路它可不像搭积木，按照说明书一步步来就能搞定。运维更像是在一片未知的森林里摸索前行，到处都是隐藏的 “陷阱” 和 “谜题”。当你遇到难题时，如果能把问题问得好，那简直就像拥有了一个超级精准的导航仪，能直接带你找到解决问题的最佳路径。

对一个问题良好的界定，已经将问题解决一半了。你想啊，要是你问的问题含含糊糊，别人连你到底卡在哪儿都不知道，那怎么给你出招呢？就好比你跟朋友说 “我有点不舒服”，朋友肯定得追问你是头疼、肚子疼还是哪里难受，才能帮你决定是去买药还是去医院。提问也一样，得把症状说得明明白白，别人才能对症下药。

例如，当你在调试一段代码时，若仅停留在“为什么报错？”的层面，可能永远无法触及根本问题；但若将其拆解为“变量作用域是否冲突？” “异步回调是否未处理异常？”，问题便迎刃而解。

2. “问题界定”的科学方法论

在运维领域里，那可是啥样的问题都有。有些朋友提问，简直就是让回答者一头雾水。比如说 “我的脚本跑不了，咋回事啊？” 这问题一抛出来，估计大家都得在心里默默翻个白眼。脚本跑不了的原因千千万万，可能是语法错误，可能是逻辑漏洞，还可能是环境配置问题，你这么一问，别人咋猜得到你到底是哪出了问题呢？

还有些朋友，就喜欢问一些特别宽泛的问题。比如 “怎么用 Python 做个网站？” 这问题大得都能把人给吓跑了。做网站涉及到前端、后端、数据库一大堆东西，你这么一问，别人得从何说起呢？这就好比你问 “怎么盖一栋房子？” 是先打地基、还是先砌墙、还是先装水电？

问题的界定需结合**“历史性”与“情景性”**。避免用“固定概念”束缚思维，而需以“新的眼光”重构问题。面对需求文档，若直接照搬需求描述（如“实现一个登录功能”），可能陷入技术细节的泥潭；但若将其重构为 “如何平衡用户认证的安全性与体验流畅性？”，则能快速锁定技术选型（如OAuth2.0 vs JWT）。

二、提问的正确方式

1.精准定位，直击要害

当你遇到问题时，先别急着求救。自己先好好琢磨琢磨，把问题的范围缩小缩小再缩小。比如说，你发现程序运行得很慢，那就先想想是哪一部分可能出了问题。是数据库查询太耗时？还是代码不够高效？你可以通过一些调试工具，看看程序在哪个环节卡住了。就像医生给病人做检查一样，得先找到病因，才能开药方。

在发出求助前，先成为自己问题的第一位诊断师。

• 缩小范围：是性能问题、稳定性问题还是功能异常？
• 收集证据：日志、监控指标、错误码、时间线——数据是提问的最佳佐证。
• 初步假设：基于证据提出一个或多个可能的原因方向。这展示了你的思考深度。

2.提供背景，让信息自己说话

一个问题往往不是孤立存在的，它背后可能有一大堆相关的因素。所以你在提问的时候，一定要把相关的背景信息都说清楚。比如说，你在用 Python 写一个数据分析的脚本，遇到了一个库的兼容性问题。那你得说清楚你用的是哪个 Python 版本，用的是哪个数据分析库，还有你的操作系统是什么。因为不同的 Python 版本、不同的库版本、不同的操作系统，都可能会导致问题不一样。

就像你去餐厅吃饭，跟服务员说 “我要一份不辣的菜”，服务员还得知道你是对辣味完全不能接受，还是只是稍微有点忌口，这样才能给你推荐合适的菜品。信息给得越全，别人回答得就越准。

一个孤立的问题陈述是苍白的。请赋予它生命所需的上下文：

• 环境：操作系统、软件版本、硬件配置、网络拓扑。
• 操作：导致问题发生的具体步骤或变更。
• 预期与实际：你期望发生什么？实际发生了什么？
• 已尝试的努力：你已做过哪些排查？结果如何？这能避免重复劳动，并显示你的主动性。

3.提供代码、日志与截图

在技术领域，一份可复现的代码片段、一段关键的错误日志、一张清晰的监控截图，胜过千言万语的描述。

4.展示思考，赢得尊重

当你提问的时候，把自己思考的过程也展示出来，那绝对能让回答者对你刮目相看。这不仅能让别人更好地理解你的问题，还能让别人知道你不是个只会伸手要答案的 “小白”。比如说，你在解决一个算法问题的时候，你可以这样说 “我先尝试了用暴力枚举的方法，但是发现时间复杂度太高了。然后我又想到了用动态规划，但是不知道怎么定义状态，现在卡在这里了。” 这样一说，别人就知道你已经思考过了，只是在某个环节遇到了困难，他们也更愿意帮你出谋划策。

三、提问的 “锦上添花” 技巧

1.善用搜索引擎与文档，先自助后求助

在提问之前，利用搜索引擎、官方文档、内部Wiki，你很可能发现答案早已存在。这个过程本身，就是极佳的学习与信息过滤训练。

你可以把问题的关键字组合一下，比如 “Python 数据分析 库 兼容性问题”，说不定就能搜到别人遇到过类似的问题，还给出了详细的解决方案。这样不仅能节省别人的时间，还能让你自己先对问题有个初步的了解。

2.多逛逛技术社区，积累经验

像 Stack Overflow、CSDN 这些技术社区，里面可是藏着无数的宝藏。你可以多逛逛，看看别人是怎么提问的，别人是怎么回答的。你还能从中学到很多知识和技巧。说不定你在逛的时候，就能看到别人遇到过和你一样的问题，还给出了超棒的解决方案。

3.学会总结归纳，举一反三

当你解决了一个问题之后，别忘了总结一下。想想这个问题是怎么产生的，你是怎么解决的，还有没有别的解决方法。这样下次再遇到类似的问题，你就能更快地解决了。而且你还能把总结的经验分享给团队，帮助团队成长。

问题解决后，完成最后的闭环：

• 总结归纳：问题根源是什么？解决方案是什么？有无更优解？
• 分享传承：将经验写入文档、分享给团队，或形成知识库条目。
• 举一反三：此类问题是否有通用模式？如何通过监控、告警或流程优化避免复发？

四、案例启示：从混沌到澄明

1. 编译错误

❌ 无效提问：
“我的代码编译不过，怎么办？”
问题分析：无具体错误信息、无代码片段、无环境描述。

✅ 正确提问：
“在Linux环境下使用GCC 13.1编译C项目时，报错undefined reference to 'std::thread::_M_start_thread'，代码中使用了C11的std::thread，已添加-pthread编译选项但未解决，是否遗漏了其他依赖？”
亮点：

• 提供环境（Linux+GCC）、错误类型（链接错误）、已尝试的解决方案。
• 明确技术点（C++11多线程）。

2. API调用失败

❌ 无效提问：
“调用微信支付API没反应，求助！”
问题分析：无请求参数、无响应码、无调试日志。

✅ 正确提问：
“调用微信支付V3接口返回HTTP 401，请求头已包含Authorization: WECHAT-PAY-SHA256-RSA2048签名，时间戳误差在5秒内，证书序列号已验证有效，是否因商户号与证书不匹配导致？”
亮点：

• 提供具体错误码（401）、请求头细节、已排查的环节。
• 锁定可能原因（证书与商户号绑定）。

3. 正则表达式失效

❌ 无效提问：
“我的正则匹配不到内容，哪里错了？”
问题分析：无正则表达式、无测试文本、无编程语言。

✅ 正确提问：
“在Python 3.11中，使用re.findall(r'\b\d{3}-\d{2}-\d{4}\b', text)匹配号码失败，测试文本含123-45-6789但返回空列表，是否因单词边界\b与连字符冲突？如何调整？”
亮点：

• 提供正则表达式、测试用例、语言版本。
• 分析可能冲突点（\b与连字符）。