doca-bare-metal-deployment

DOCA 裸机部署

示例

• “二进制文件启动后立即以状态码 1 退出。” — 这属于此技能的范围。 应将其视为启动／设备绑定／隔离故障，在重写应用代码之前先排查。
• “systemd 不断重启我的 DOCA 应用。” — 硬件上的重启循环风险很高。启用 Restart=always 之前，先排查首次退出的原因。

说明

请遵循下文的加载顺序。打开任务配套文件，了解启动／监控／恢复；打开能力配套文件，了解运行时契约。不要打开所有配套文件。

从这里开始： 此技能是本套件中用于直接在硬件上运行 DOCA 链接应用二进制文件的入口——不使用容器、kubelet 或静态 Pod 清单。对于非容器路径，它对应的是 doca-container-deployment/SKILL.md。如果用户有自己构建的 DOCA 链接二进制文件（遵循 doca-programming-guide/SKILL.md 中的规范工作流），并想了解如何在主机上或 BlueField Arm 核心上正确运行它，请打开任务配套文件，从 ## configure 开始。如果问题是裸机运行时的形态究竟是什么，以及部署契约是什么，请从能力配套文件开始。如果用户尚不确定目标系统应采用容器路径还是裸机路径，请先将路径识别步骤指向 doca-setup/SKILL.md；确认是裸机后再返回此处。

适用对象

此技能面向外部 DOCA 开发者和运维人员，他们拥有自己构建的 DOCA 链接应用二进制文件，并希望直接在硬件上运行它——也就是说，他们已经拥有：

• 按照 doca-programming-guide ## build 构建的 DOCA 链接应用二进制文件，
• 真正的 BlueField NIC，以及与之通信的主机（主机 x86 路径——主机上的 DOCA 安装通过 PCIe 与 BlueField NIC 通信），或者可以通过控制台或 SSH 访问 Arm 端的 BlueField（BlueField Arm 裸机路径——DOCA 安装在 DPU Arm 核心上；二进制文件直接在其上运行），以及
• 希望直接在硬件上运行该二进制文件，而不是在由 kubelet-standalone 管理的容器中运行。

此技能不适用于：

• 为 mlx5_* 或 BlueField OS 做贡献的内核驱动开发者，
• DOCA 库贡献者（这些更改应提交到内部 DOCA 代码库，而非用于裸机部署），
• 管理多台 BlueField 的完整 Kubernetes 集群运维人员（本套件涵盖 doca-container-deployment/SKILL.md 中的单主机 kubelet-standalone 形态；机群／生产规模部署属于机群编排范围——请转到 doca-public-knowledge-map ## Deploying DOCA services at scale 中的编排入口（DPF / Network Operator / Launch Kit），不要手动编写静态 Pod 循环），
• 尚未安装 DOCA、手头也没有硬件的新笔记本用户——他们应参阅 doca-setup ## no-install。

此技能会通过 doca-public-knowledge-map/SKILL.md，指导 Agent 执行裸机部署流程，并说明如何引用公开 DOCA Programming Guide 和公开 BlueField / DPU User Manual 中记录的命令；它不会凭记忆编造标志名称、PCI BDF、NUMA 编号、devlink 路径、representor 字符串或 systemd Restart= 模式名称。

何时加载此技能

当用户正在任一受支持的主机模式（主机 x86 或 BlueField Arm）下，亲自将 DOCA 关联的应用程序二进制文件部署到裸机，或者提出不特定于某个库 API 的跨领域裸机问题时，加载此技能。具体包括：

• 首次在装有 BlueField 网卡的 PCIe 插槽且已在主机上安装 DOCA 的主机上，启动 DOCA 关联的二进制文件。
• 直接在 BlueField Arm 核心上启动 DOCA 关联的二进制文件（BlueField Arm 裸机模式），并按照 BlueField OS 映像的要求在 Arm 侧安装 DOCA。
• 决定使用哪种启动模式（交互式调试用前台直接运行；长期运行且需要手动重新连接时用 tmux/screen；需要重启后自动启动、集成 journald 日志和 Restart= 策略时用 systemd 监管）。
• 将 DOCA 进程绑定到正确的 PCIe 功能、正确的 representor、正确的 NUMA 节点和正确的 CPU 集，并相应地固定 IRQ，而不虚构地址或标志名称。
• 设置每个租户的隔离（cgroup-v2 cpu / memory / io 控制器、多租户部署的网络命名空间、使用 numactl / taskset 进行 CPU + NUMA 绑定），以便多个 DOCA 进程在同一 BlueField 上共用资源而不互相拖垮。
• 诊断运行异常的裸机启动：无法启动、启动后立即退出、运行但找不到设备、已连接设备但工作负载报错、发生 OOM 或被信号终止、在监管程序下陷入重启循环，或受到同机租户干扰。
• 跨领域问题：“我应该在 tmux 中运行，还是将其作为 systemd 单元运行”、“裸机二进制文件从冒烟测试到批量运行的流程是什么”、“我的二进制文件在 BlueField 容器中可以运行，但直接在 Arm 上运行时不行——发生了什么变化”。

不要在以下情况下加载此技能：与容器部署路径对应的问题（此类问题请使用 doca-container-deployment/SKILL.md）； 完整 Kubernetes 集群运维问题（不在此套件的目标范围内）； 库 API 问题（转至对应的 libs/<library> 技能）； 环境准备问题，包括 hugepages、IOMMU、pkg-config 和 devlink 模式切换（使用 doca-setup/SKILL.md）； 任何会改变硬件状态的操作，包括 mlxconfig 写入和 BFB 重刷（跨领域元策略请转至 doca-hardware-safety/SKILL.md）； 或跨库编程问题（使用 doca-programming-guide/SKILL.md）。

此技能提供的内容

这是一份轻量加载器。实质性内容位于两个配套文件中：

• capabilities 配套文件——针对与 DOCA 链接的二进制文件的裸机部署运行时契约：两种主机模式（主机 x86 与 BlueField Arm 裸机）、三种启动模式（直接启动、tmux/screen、systemd 监督）、硬件资源绑定界面（PF / VF / representor 枚举；NUMA 拓扑发现；CPU 绑定原因；IRQ 亲和性规则）、每租户隔离界面（cgroup-v2 cpu / memory / io、网络命名空间、numactl / taskset）、重启与恢复语义（文档化的 systemd Restart= 模式与崩溃后调查、由监督程序驱动的重启）、在 doca-version/SKILL.md 所定义的四项版本匹配基础上叠加的裸机专用版本要求、跨领域错误分类（七层，按顺序逐层检查）、可观测性界面（不同启动模式下的 stdout/stderr 使用规范；通过 devlink / sysfs / mlxconfig query 查询设备状态；每租户资源可见性），以及安全策略（叠加于 doca-hardware-safety/SKILL.md：二进制文件先冒烟测试再批量运行；裸机进程失败属于高风险事件；不得臆造 PCI 地址、NUMA 编号、representor 名称、devlink 路径或 systemd Restart= 模式名称；必须在工作负载启动前确认租户隔离原语）。
• tasks 配套文件——针对范围内裸机操作动词的分步工作流：configure、build、modify、run（包含明确的 ### isolation 子锚点，介绍 cgroup-v2 / 命名空间 / numactl 租户隔离原语）、test、debug、bluefield-lifecycle（BFB 安装 → RShim/TMFIFO → BFB 后恢复的运维顺序阶梯，包含六状态 bluefield-state-classifier 子锚点）、Command appendix（Agent 可引用的文档化命令，每条命令均链接到其公开文档来源；不得臆造命令），以及将容器路径 / 集群 / 库 API / 环境准备 / 硬件状态更改 / 跨库问题转交给所属技能的 Deferred task verbs 区块。（从 ## bluefield-lifecycle 调用任何会产生变更的烧录操作时，其变更应用规范仍属于由 doca-hardware-safety/SKILL.md 定义的元策略，需同时加载该文件。）

此技能假定目标主机或 BlueField 满足以下条件：

• DOCA 已安装且运行正常（参见 doca-setup ## test），
• 用户拥有其构建的、与 DOCA 链接的应用程序二进制文件（参见 doca-programming-guide ## build），
• 用户拥有主机操作系统权限，可枚举设备、预留大页、编写 systemd 单元文件（若选择该启动模式），并将进程绑定到 NUMA 节点。

此技能不涵盖安装 DOCA——该流程请参见 doca-setup/SKILL.md；也不涵盖构建二进制文件——该流程请参见 doca-programming-guide/SKILL.md。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围（在主机 x86 或 BlueField Arm 上裸机启动与 DOCA 链接的二进制文件；不包括容器路径、完整集群或库 API 问题）。
2. 有关运行时契约（两种主机模式、三种启动模式、硬件绑定界面、每租户隔离、版本叠加、七层错误分类、可观测性界面、裸机安全叠加），请参见 capabilities 配套文件。
3. 有关分步工作流——configure、build（转交说明）、modify（转交说明）、run（含 ### isolation 子锚点）、test、debug、bluefield-lifecycle（BFB 安装 + RShim/TMFIFO + BFB 后恢复 + 六状态 bluefield-state-classifier），以及 Command appendix 和 Deferred task verbs 区块——请参见 tasks 配套文件。

此技能擅长回答的示例问题

此技能明确不提供的内容

相关技能