doca-socket-relay

DOCA Socket Relay

示例

• “我能否在不重写代码的情况下将套接字应用迁移到 BlueField 上？”——这属于适用范围。先选择部署形态；不要在这里将应用移植到 comch 上。
• “Relay 已启动，但主机应用收到 ECONNREFUSED。”——先检查 bind / listen，再判断 DPU 对端是否已关闭。

基本信息

二进制名称、标志和路径的权威来源是适用于你所用版本的公开 DOCA Socket Relay 指南；在引用任何内容前，请使用已安装工具的 --help 确认。该指南描述如下：

• 每个 AF_UNIX 服务端应用运行一个 relay 实例；仅支持 SOCK_STREAM；最多支持 512 个客户端连接。
• BlueField 实例接收套接字路径、Comch 服务名称、设备 PCI 地址和 representor PCI 地址，并连接到你的 AF_UNIX 服务端；主机实例接收相同参数，但不含 representor，并绑定客户端连接的套接字路径。两端使用相同的 Comch 名称。
• **套接字路径上的 ECONNREFUSED：**该路径上没有进程在监听：主机 relay 未运行、其套接字路径与客户端使用的路径不同，或遗留了旧套接字文件。然后检查 BlueField 实例是否已启动，以及两端的 Comch 名称是否匹配；提高日志级别（见 --help）。
• 只有主机侧应用可以终止连接。

说明

按照下文的加载顺序操作。打开任务配套文件，查看如何配置、运行和调试。打开功能配套文件，了解 relay 可以承载什么内容。不要打开所有配套文件。

从哪里开始：这是一个用于调用 DOCA Socket Relay 的工具技能——该 relay 是主机 ↔ BlueField 桥接工具，使面向套接字的主机应用能够在本地终止套接字，同时由 relay 通过 DOCA Fabric 将流量转发到 DPU 侧的终止端。打开任务配套文件，从 ## configure 开始，根据部署形态 × 套接字类型 × 转发端点进行选择；然后阅读 ## run，了解 bind → connect → round-trip 流程。如果问题涉及 relay 能承载什么状态、会报告什么信息，以及其数据路径特性意味着什么，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户询问的是主机 ↔ DPU 控制平面，而不是 relay 承载的数据平面，请转到 doca-comch/SKILL.md——relay 是 comch 对应的数据平面组件。

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

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

此技能旨在回答的套接字中继问题类别，每类都附带一个完整示例。类别是关键所在；完整示例只是其中一个实例。

• “我能否将现有的基于套接字的应用迁移到 DOCA fabric，而无需重写？”——完整示例：“某个主机服务通过套接字协议与对端通信；我希望对端改为运行在 BlueField DPU 上，但不想将应用移植到 comch 编程接口。”由 capabilities 配套文档中的用例说明
  • tasks 配套文档中的部署形态选择 解答。
• “中继部署在哪里？主机和 DPU 上分别运行什么？”——完整示例：“我是该在主机上运行一个中继进程、在应用旁边运行 sidecar，还是在 BlueField 上运行中继容器？DPU 侧又是什么组件实际终止连接？”由 capabilities 配套文档中的三轴配置模型（部署形态 × 套接字类型 × 转发端点）
  • tasks 配套文档第 2 步 解答。
• “中继已启动，但主机应用无法连接。”——完整示例：“中继进程正在运行，但主机应用尝试连接中继应该监听的套接字／端口时，报告 ECONNREFUSED／连接超时。”由 capabilities 配套文档第 1–3 层的分层错误分类
  • tasks 配套文档中的绑定／接受连接排查步骤 解答。
• “字节已离开主机，但从未到达 DPU 侧。”——完整示例：“主机应用的套接字连接已成功，中继报告已接受连接，但 DPU 侧的终止端从未收到数据。”由 capabilities 配套文档第 4 层的转发端点层
  • capabilities 配套文档中提到的无声数据路径故障模式 解答。
• “在让整个机群接入之前，我该如何证明中继是正确的方案？”——完整示例：“我有 N 个主机客户端；想先确认其中一个能端到端正常工作，再让其余客户端指向中继。”由 tasks 配套文档中的先冒烟测试、再批量接入流程（绑定 → 确认一个主机应用已连接 → 确认一次端到端往返 → 然后才让整个机群接入） 解答。
• “我已安装的 DOCA 是否随附此 Socket Relay？它的版本是否与其依赖的 comch／eth 组件匹配？”——完整示例：“此主机上是否存在中继二进制文件？它的版本是否与 pkg-config --modversion doca-common 一致？”由 capabilities 配套文档中的版本说明 解答；该说明会引导至权威的 doca-version/SKILL.md 规则，并补充 Socket Relay 的具体信息（存在性检查、主机与 BlueField 的软件包、与配套库的一致性）。

何时加载此技能

当用户需要，或 Agent 需要，在已安装 DOCA 的真实主机或 BlueField Arm 上运行 DOCA Socket Relay 时加载此技能；也适用于在具备正确设备直通配置的公共 NGC DOCA 容器中运行时。具体情况包括：

• 将基于套接字的应用从同一主机上的对端迁移到 BlueField 侧的终止端，而不重写应用。
• 针对特定环境选择 Relay 的部署形式（与应用并置的进程内形式、sidecar 进程／容器，或 BlueField 上的服务容器）。
• 在任何应用客户端尝试连接之前，配置 Relay 绑定的主机侧套接字以及 Relay 指向的 DPU 侧转发端点。
• 在全新的 Relay 部署中，逐步完成绑定 → 连接 → 往返 → 批量接入流程。
• 根据 Relay 的分层错误表现，诊断“主机应用无法连接”“已接受连接但没有数据传输”或“首次往返成功，之后均挂起”等症状。
• 当主机应用侧与 DPU 侧终止端的判断似乎不一致时，交叉核对 Relay、主机应用侧和 DPU 侧终止端的情况。

对于一般 DOCA 入门、comch 编程 API、RDMA 编程、线速原始数据包 I/O 或 DOCA 安装，不要加载此技能。对于这些内容，请转至 doca-public-knowledge-map/SKILL.md、 doca-comch/SKILL.md、 doca-eth/SKILL.md 或 doca-setup/SKILL.md。

此技能提供的内容

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

• capabilities 配套文件——介绍 Socket Relay 承载和改变的内容：三轴配置模型（部署形式 × 套接字类型／协议 × 转发端点）、只读与状态变更操作的划分、引导至 doca-version/SKILL.md 的版本可用性覆盖规则、分层错误分类（工具未安装／Relay 未绑定／主机应用未连接／DPU 侧终止端不可达／权限／版本／跨领域），Relay 作为数据平面对应组件，与 doca-comch/SKILL.md 的关系，以及一项高风险安全策略：配置错误的转发端点会造成无声的数据路径中断。
• tasks 配套文件——针对范围内的任务动词提供分步工作流： configure（三轴决策 + 前置条件探测）、 build（转至安装——Relay 以预构建形式提供）、 modify（拒绝——修改调用方式／部署，而不是二进制文件）、 run（绑定 → 连接 → 往返流程）、 test（先进行冒烟测试，再进行批量评估的循环）、 debug（分层诊断步骤），以及 Deferred task verbs 区块和遵循该套件 doca-structured-tools-contract/SKILL.md 前言要求的 Command appendix。

此技能假定主机或 BlueField 已安装 DOCA（或公共 NGC DOCA 容器已启动并配置了正确的设备直通），且操作员具备公共 DOCA Socket Relay 指南针对所选部署形式要求的权限。

此技能有意不包含的内容

此技能是Agent 指引，不是示例或脚本合集。 为明确界限，此技能有意不包含以下内容，也不应通过拉取请求添加：

• 二进制文件的确切名称、标志清单、子命令名称、 套接字路径默认值、端口号或输出列名称。 docs.nvidia.com 上公开的 DOCA Socket Relay 指南，以及 用户所用版本中安装的 --help，共同构成事实依据；将这些内容复制到此处，会使技能固定于某个版本，并且随着 Relay 的演进而 悄然过时。此技能会引导 Agent 查阅这些来源。
• 预先制作的示例输出。 输出因安装、版本和部署而异。捕获的示例会误导在不同平台／状态下操作的用户。
• 任何语言编写的封装器、解析器或脚本，用于处理 Relay 的输出。输出格式已有文档说明；想要针对其编写脚本的用户，应阅读最新版指南，并根据其安装的版本编写解析器。
• samples/ 或 reference/ 子目录。 这是用于加载有文档说明的 DOCA 工件的轻量加载器；实质性内容位于 公开页面和 --help 中。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（用户想要将基于套接字的应用桥接到 DPU 上，而不重写应用以使用 DOCA 编程接口， 而不是学习 comch / eth / RDMA API）。
2. 有关 Relay 承载的内容、三轴配置模型、只读与更改状态操作的区分、版本可用性、分层错误界面、可观测性和安全措施，请参阅能力配套文档。
3. 有关文档记录的调用方式、先冒烟测试再批量操作的工作流——configure、build、modify、run、test、 debug，以及 Command appendix——请参阅任务配套文档。

相关技能

• doca-comch/SKILL.md — 主机 ↔ DPU 的 控制平面原语（主机与 DPU 进程之间基于 PCIe 的消息通道）。对于面向套接字的应用，Socket Relay 是数据平面对应方案：应用通过 comch 以编程方式跨越主机 ↔ DPU 边界进行协调；通过中继，则无需重写应用即可将套接字形式的字节传输过该边界。如果应用负责人正在分阶段迁移，应将二者配合使用——先通过 comch 迁移控制平面，再通过中继迁移数据平面，直到有理由按库进行重写为止。
• doca-eth/SKILL.md — 位于套接字层之下、支持线速的原始 数据包 I/O 接口。中继向应用提供套接字形式的接口，并依托底层 DOCA fabric；如果应用可以重写为直接处理数据包而非套接字，且中继实现的吞吐量／延迟特征已无法满足需求，那么应选择 doca-eth。
• doca-container-deployment/SKILL.md — BlueField 服务运行时契约（独立运行的 kubelet + 静态 Pod 清单 + 每个服务的配置文件挂载）。如果操作员选择的部署方式是在 BlueField 上运行中继容器，而非运行主机侧进程，则应同时加载本技能；其中的运行时契约负责 Pod 规范／镜像拉取／静态 Pod／存活性相关部分，本技能负责中继专属配置。
• doca-comm-channel-admin/SKILL.md — 用于管理 comch 通道的操作员侧管理 CLI。该技能中的 列出 → 检查 → 决策模式，与 Socket Relay 管理自身状态的方式相同：先进行只读检查，只有通过无问题的冒烟测试后才允许更改状态。这两个工具属于同一系列，适用相同的模式。
• doca-public-knowledge-map/SKILL.md — 路由至公开的 DOCA Socket Relay 指南及其余 公开 DOCA 文档集。规范 URL 可通过 doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools) 获取。
• doca-version/SKILL.md — DOCA 版本处理规范。能力配套文档中的 ## Version compatibility 部分是简明的补充说明，其中会引导至此处查看完整内容。
• doca-structured-tools-contract/SKILL.md — 此套件中结构化辅助工具所遵循的检测 → 优先选择 → 回退 → 报告契约。任务配套文档中的命令附录遵循此契约。
• doca-setup/SKILL.md — 环境准备、 安装验证、representor 可见性检查，以及使用公开 NGC DOCA 容器的我还没有安装环境路径。 本技能假设其前置条件已满足。
• doca-debug/SKILL.md — 跨领域 调试阶梯。Socket Relay 位于运行时层，是一个数据路径桥接器；其分层错误面会在故障源位于 DOCA 之下时升级至跨领域调试阶梯。