doca-flow-grpc-server

DOCA Flow gRPC 服务（doca_flow_grpc）

示例

• “我真的需要 Flow 的远程控制平面吗？” — 这属于本技能范围。如果客户端可以运行在同一台主机上， 优先直接链接 libdoca_flow.so。
• “我安装的版本中，gRPC 契约在哪里？” — .proto 是事实来源；不要凭记忆臆造 RPC。

说明

请遵循下文的加载顺序。打开任务配套文件，了解如何配置 / 运行 / 调试。打开能力配套文件，了解何时使用 gRPC 以及端点的安全态势。不要打开所有配套文件。

传输安全方面的关键更正（Run-12 + R13）。 随附的 doca_flow_grpc / doca_flow_grpc_client 二进制文件将 gRPC 明文凭据机制硬编码为： 服务端使用 grpc::InsecureServerCredentials()（位于 tools/flow_grpc_server/server/ 中的 C++ gRPC 服务端 API）； C++ 客户端使用 grpc::InsecureChannelCredentials()（C++ gRPC 客户端 API；客户端位于 libs/doca_flow/grpc/client/，编译进 doca_flow 库，而不在 tools/flow_grpc_client/ 下）； Python 客户端使用 grpc.aio.insecure_channel(...)。不要将服务端的 API 名称写成 grpc::InsecureChannelCredentials() — 那是客户端 API 名称，通过 Grep 检查源码时 会验证失败。目前随附的控制平面没有 TLS、没有 mTLS，也没有令牌认证 配置项。下文（或能力配套文件 / 任务配套文件）中任何将“mTLS / 令牌认证 / TLS 安全态势” 描述为此服务可配置项的文字，都只是该套件先前不切实际的设想， 与随附源码不符。请仅在受信任网段上以明文运行 此服务：必须将其绑定到仅供控制平面使用的 网络网段，并置于外部代理、sidecar 或 VPN 之后， 由该代理、sidecar 或 VPN 自身强制执行 TLS + 身份验证。下文任何关于 “TLS / mTLS / 令牌认证”的讨论，指的都是操作员的外部加固层， 而不是此二进制文件的配置项。有关 TLS / 身份验证设计的讨论， 必须围绕选定的外部代理、sidecar 或 VPN 展开；绝不能将其引向 当前随附二进制文件中的配置项。

从这里开始： 这是一个用于部署和运行 doca_flow_grpc 的工具技能， 它是 DOCA 随附的 doca-flow gRPC 远程控制界面。打开任务配套文件， 从 ## configure 开始，判断远程控制平面是否真的是合适的方案 （而不是直接调用 libdoca_flow.so），然后阅读 ## run，了解 启动 → 绑定 → 单客户端冒烟测试的流程，接着阅读 ## test，了解在任何会修改 Flow / 数据平面状态的 RPC 之前， 必须通过冒烟测试的循环。如果问题涉及 gRPC 契约界面的具体内容 （用户安装中的工具源码树下随附的 .proto 文件）、负责保护明文服务的 外部代理 / sidecar / VPN、gRPC 生态系统支持哪些语言绑定，或如何结合 实时 Flow 应用程序的日志来解读服务自身的日志，请打开能力配套文件。如果未安装 DOCA， 先转至 doca-setup/SKILL.md；如果用户尚未部署 doca-flow，先转至 doca-flow/SKILL.md — gRPC 服务是在 Flow 库之上的远程控制平面， 而不是它的替代品。

如何使用此技能。 阅读此文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读整个章节。仅依据该章节完整作答， 引用的符号和命令也仅限其中所列。不要浏览文档；请使用 doca-public-knowledge-map 中的入口。将环境检查写成适用于用户 DOCA 主机的命令。 对于超出范围的请求，指出负责该内容的技能，然后停止。

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

此技能旨在回答 doca_flow_grpc 问题的各个类别，每个类别都附有一个经过验证的示例。类别是关键所在；经过验证的示例只是其中一种情况。

• “我的 Flow 流水线真的需要远程控制平面吗？还是客户端直接链接 libdoca_flow.so 就行？”——经过验证的示例：“我的客户端是运行在另一台主机上的 Python 服务；它能远程编程 Flow 规则吗？”答案见能力配套文档中的 何时使用 gRPC 决策，以及当直接链接库是更好的选择时，转至 doca-flow/SKILL.md。
• “我的安装中，gRPC 契约实际定义在哪里？”——经过验证的示例：“我想生成 Python 客户端；.proto 文件在哪里获取？”答案见能力配套文档中的 .proto 文件是唯一可信来源 规则，以及关于标准 gRPC 工具的语言绑定讨论（protoc + 特定语言的 gRPC 插件，参见 grpc.io 上的 官方 gRPC 文档）。
• “如何加固 gRPC 端点，避免它成为通往我的数据平面的敞开大门？”——经过验证的示例：“服务器绑定到 0.0.0.0；在对外开放之前我应该怎么做？”答案见能力配套文档中的 管理攻击面 安全态势，以及任务配套文档中的外部防护 / 网络分段决策。
• “如何在向整个集群开放服务器之前，端到端验证一个客户端？”——经过验证的示例：“我的 Python 客户端可以连接到端点；我应该运行哪个第一个 RPC 来证明它能与正在运行的 Flow 应用通信？”答案见任务配套文档中的先冒烟测试、再批量部署流程，以及能力配套文档中的先冒烟测试、再批量部署规则。
• “我的客户端无法连接到服务器——是服务器宕机、端点错误、外部代理不匹配，还是版本不匹配？”——经过验证的示例：“客户端连接超时。”答案见能力配套文档中的分层错误分类，以及任务配套文档中的分层排查流程。
• “我的非 C++ 客户端（Python / Go / Rust）是否真的符合 gRPC 契约，还是有更简洁的途径？”——经过验证的示例：“我想要一个 Rust 客户端；.proto 生成的 API 是什么样的？”答案见能力配套文档中的语言绑定讨论，以及标准 gRPC 工具的使用指引。

适用对象

此技能面向外部运维人员、控制平面开发者，以及需要通过网络边界，从非 C++ 进程为正在运行的 DOCA Flow 流水线编程的 AI Agent，而不是将 libdoca_flow.so 直接链接到控制进程中。具体包括：

• 编写 Python / Go / Rust 客户端、从 BlueField 地址空间之外为其上的 Flow 规则编程的控制平面工程师。
• 在 BlueField 上运行使用 Flow 的服务，并希望向集中式控制平面开放远程控制接口的平台运维人员。
• 在建议修改周边 doca-flow 应用的代码之前，执行“我能否从此客户端／此网络位置为这些 Flow 规则编程”这一排查步骤的 AI Agent。

此技能不适用于调试 gRPC 服务源代码的用户，不能替代 docs.nvidia.com 上最新的 DOCA Flow 公共 gRPC 服务指南，也不是学习 doca-flow API 的地方——相关内容请参阅 doca-flow/SKILL.md。

doca_flow_grpc 是一个由 DOCA 源码树构建的单个 CLI 二进制文件（位于 tools/flow_grpc_server/meson.build 中的 executable('doca_flow_grpc', ..., install: false)，受 flag_enable_grpc_support 控制），并配有 libs/doca_flow/grpc/ 下的 .proto 合约文件；根据该工具的源码树（server/、dpa_device/、packet_buffering/），在需要的配置中，该工具还可以配合数据包缓冲／DPA 端辅助程序使用。此技能采用与此工具集合中其他工具槽相同的 kind: tool 三文件结构（此技能文件 + 配套的 capabilities 文件 + 配套的 tasks 文件）——此文件顶部的 front matter 已写明 kind: tool。（此处早期版本的集合曾写作“library 三文件结构”；该说法与 front matter 不一致，现已更正。）

语言范围

此技能涵盖标准 gRPC 工具支持的各语言中的部署、配置、加固和客户端启动，包括 Python、Go、C++、Rust、Java、Node.js、C#、Kotlin、Ruby、PHP、Dart；客户端通过根据随附 .proto 文件生成的特定语言 gRPC 插件来实现（参见 grpc.io 上的 gRPC 语言支持 索引）。服务端使用 C++ + DOCA；客户端语言不受限制，仅受标准 protoc 插件集约束。关于服务端编程所用的 doca-flow API，请参阅 doca-flow/SKILL.md——该接口采用 C 语言。

何时加载此技能

当用户需要——或 Agent 需要——针对正在运行的 doca-flow 应用（或其先决条件）启动 doca_flow_grpc，并将非 C++ 客户端连接到该服务时，加载此技能。具体包括：

• 判断远程 gRPC 控制平面是否为合适的接口（而不是在客户端进程中直接链接 libdoca_flow.so）。
• 在用户的安装目录中查找 .proto 文件，以便语言绑定客户端生成相应的存根。
• 确定部署的传输安全策略和网络分段。注意：随附的服务端仅支持明文传输（grpc::InsecureServerCredentials()）；TLS / mTLS / 令牌身份验证不是二进制配置项——它们属于外部基础设施问题，需由功能完备的代理、sidecar 或 VPN 处理；明文端点必须位于可信的隔离网段内。
• 在已知正常的 Flow 设置旁启动服务端，并在向整个集群开放端点之前，端到端冒烟测试一个客户端。
• 通过分层分类法诊断连接／版本／RPC 故障。

一般 DOCA 介绍、doca-flow API 工作、DOCA 安装或通用 gRPC 工具不应加载此技能（相关内容请直接参阅 grpc.io 文档）。

此技能提供的内容

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

• 能力配套文件 — 介绍 doca_flow_grpc 暴露的内容： doca-flow 前端的 gRPC 远程控制界面、 .proto 文件作为权威契约的规则（用户安装的工具源码中随附的 .proto 文件是事实依据）、何时使用 gRPC、何时直接链接库的决策、语言绑定说明（任何语言只要有标准 gRPC 工具即可支持）、外部代理 / sidecar / VPN 和网络网段的选择、依据随附的 packet_buffering/ 和 dpa_device/ 子树提供的数据包缓冲 / DPA 侧选项、版本对应关系（服务端使用其链接的 doca-flow 库版本）、分层错误分类（server-not-started / server-binding-failed / external-layer-rejected / RPC-call-error / Flow-precondition-failed / version / cross-cutting）、可观测性界面（服务端自身日志 + 正在运行的 Flow 应用日志 + RPC 客户端状态码），以及将此端点视为高风险管理攻击面的安全策略。
• 任务配套文件 — 针对范围内任务动词的分步工作流：install（转至 setup；二进制文件需在启用 gRPC 支持的情况下从源码构建）、configure（决定使用远程方式还是直接方式，并选择外部代理 / sidecar / VPN 和网络网段）、build（转至 install）、modify（拒绝——修改部署，而非二进制文件）、run（启动 → 绑定 → 冒烟测试）、test（先冒烟测试再批量测试的循环，其中包含客户端侧存根生成步骤）、debug（分层诊断步骤）、use（Agent 侧使用已捕获 gRPC 服务端会话的工作流），以及一个 Deferred task verbs 区块和一个 Command appendix。

此技能假设主机已安装 DOCA（或正在运行 NGC DOCA 容器），其中有 Flow 库、可供编程使用的正常 doca-flow 应用，并且操作人员了解暴露 gRPC 控制平面会带来极高风险。

此技能有意不包含的内容

此技能是面向 Agent 的指导，而非示例或脚本合集。为明确范围，此技能有意不包含以下内容，拉取请求也不应添加：

• 逐字列出的 RPC 方法名称、消息字段清单或默认端点路径。 用户安装的工具源码树中随附的 .proto 文件才是权威契约；将这些内容复制到此处会使技能绑定到某个版本，并在契约演变时悄然过时。
• 任何语言的预制客户端代码。 特定语言的 gRPC 插件与随附的 .proto 文件构成契约；根据用户安装版本生成的客户端代码才是正确选择，而非固定在某个快照上的存根。
• 预制的外部安全层配置。 CA、令牌和 mTLS 配置应属于选定的代理、sidecar 或 VPN 及其安全审查，而非 doca_flow_grpc。
• 将 gRPC 端点代理为其他协议的包装器、解析器或脚本。 端点就是端点；如果用户需要 HTTP/JSON，那是此技能范围之外的独立事项。
• samples/、bindings/ 或 reference/ 子树。 即使标注为 “参考” 也会造成误导：操作人员会将其视为可构建内容。

加载顺序

1. 首先阅读此技能，确认用户的问题 属于适用范围（用户确实需要在 doca-flow 之上构建远程 gRPC 控制 平面，而不是直接链接库或使用其他 DOCA 库）。
2. 关于服务公开的内容、以 .proto 作为契约的规则、语言绑定方案、外部代理 / sidecar / VPN 和网络分段的决策、版本可用性、分层错误界面、可观测性以及安全态势， 请参阅能力配套文档。
3. 关于文档记录的启动顺序以及先冒烟测试、再批量操作的工作流——install、 configure、build、modify、run、test、debug、use——请参阅 任务配套文档。

相关技能

• doca-flow/SKILL.md — 服务的 gRPC 契约所基于的基础 库，服务的 gRPC 契约是其上薄薄的一层远程 控制封装。管道 / 条目 / 规则语义、提交前验证规则、Flow 计数器 / 检查器 接口都在该文档中。
• doca-flow-tune/SKILL.md — Flow 调优工具。建议修改 Flow 程序时，可通过外围应用应用 更改；如果控制平面是远程的，也可以通过此 gRPC 服务的 RPC 接口应用更改。
• doca-public-knowledge-map/SKILL.md — 指向 docs.nvidia.com 上的公开 DOCA Flow gRPC Server 页面以及其余公开 DOCA 文档集。
• doca-version/SKILL.md — 规范的 版本处理规则。此技能中的 ## Version compatibility 部分是基于该规则的精简补充。
• doca-debug/SKILL.md — 跨领域的 调试阶梯。gRPC 服务故障在运行时层接入该阶梯。
• doca-setup/SKILL.md — 环境准备、 安装验证以及 NGC DOCA 容器路径。
• doca-hardware-safety/SKILL.md — 跨领域的硬件安全元策略；此技能的 ## Safety policy 会对其进行补充。任何会更改状态的 RPC 都可能影响数据平面，因此必须遵循该元策略。