OnePath™ 统一逻辑网络 · 产品白皮书
面向销售培训与客户技术决策者。本文档定位 OnePath 是什么、为什么独特、与 DDS / 分布式软总线等同类概念的本质区别，以及交付给客户的完整内容。
1. 一句话产品定义
OnePath 是一个 C 语言通信中间件：它把分布在不同总线、链路与网段上的异构节点，统一接入一张逻辑网络，对外只提供一套极简、稳定的 C 接口，让节点之间无需感知彼此的物理位置与连接方式，即可完成信息交换与资源共享。
一句话讲清价值：一处编写，全网可达；一条逻辑总线，打通异构链路与跨网段。
2. 产品特性
2.1 异构组网与统一逻辑网络
OnePath 的核心能力是把分布在不同总线、链路、网段上的节点接入同一个逻辑网络。节点之间无需感知彼此的物理位置、所在子网或底层传输方式——同一份应用代码在数据中心、局域网、跨网段、甚至同一台机器的不同进程之间都正确工作。对应用而言，"网络"被收敛成一张统一、扁平、可寻址的逻辑网络。
2.2 零配置自动发现
同一网络内的节点自动相互发现并建立连接，免去手工维护地址列表与配置文件。同子网内通过组播探测对端，节点上线即自动加入；下线即自动感知。对于不想引入中心配置服务、又需要节点动态进出的部署形态，这是开箱即用的能力。
2.3 跨网段转发网关
通过转发网关，OnePath 能在不同局域网、子网之间中继消息，实现跨网互联互通。跨网段通信对应用完全透明：发布者照常发布，订阅者照常订阅，消息在转发网关处被自动接力到目标网段。这让"一张逻辑网络"的边界从单个局域网扩展到广域的、多子网的真实部署。
2.4 两种通信范式 + 层级化通配符寻址
OnePath 内置两类通信范式，覆盖绝大多数分布式场景：
- 发布 / 订阅：面向数据分发，一对多广播，发布者不关心有多少订阅者。
- 请求 / 响应：面向服务调用，请求者发起、响应者应答，内建请求关联与多应答聚合。
寻址采用类文件路径的层级名称标识资源（如 robot/sensor/temperature），并支持通配符进行批量匹配与订阅（* 匹配单层、** 匹配多层）。这让"订阅某一类资源"成为一行代码的事，天然适合海量、动态的数据与服务空间。
2.5 可靠传输与历史补偿
可按需开启消息缓存、丢包检测与历史数据补发。订阅者后加入网络也能收到历史消息，弱网与短暂中断环境下数据不丢、不乱。这一组能力让 OnePath 在不稳定链路（无线、广域、跨网）上依然保持数据面的可靠性，而无需应用层自行实现重传与对齐逻辑。
2.6 节点存活感知与断线透明重连
OnePath 实时感知对端节点的上线 / 离线状态；连接中断后自动按指数退避重连，重连后订阅关系、查询关系自动恢复，整个过程对应用层完全透明——应用代码不需要处理断线、不需要重建会话、不需要重新注册订阅。
2.7 网络拓扑感知
基于运行时自省，OnePath 能发现网络中的节点、各节点承载的服务、节点之间的连接关系与传输类型（TCP / UDP / 串口等，含是否走共享内存），并可聚合为全局拓扑图供监测、告警与可视化使用。运维不再需要在网络之外另搭一套拓扑发现系统——网络本身就"知道"自己长什么样。
2.8 同机零拷贝传输
同一台机器上的不同进程（或同进程的不同会话）之间，OnePath 可自动经共享内存零拷贝交换数据，获得高吞吐与低延迟；跨机时自动回退到网络传输。这一切对用户完全透明——用户始终用同一套发布 / 订阅 API，是否走零拷贝由 OnePath 根据对端是否在本机自动决定。
2.9 安全通信
支持传输层加密（TLS）、身份认证（用户名密码）与基于资源名称的访问控制，保障跨网通信的数据机密性、完整性与访问权限。从局域网到广域跨网，通信链路可按需加固，而应用 API 保持不变。
2.10 内置可观测性（零代码改动）
OnePath 内置分布式链路追踪（W3C Trace Context）与指标（Counter / Gauge / Histogram）。发布 / 订阅、请求 / 响应等核心通路自动埋点，调用链在多跳转发中自动透传——用户代码无需任何修改，仅通过环境变量开关即可开启，关闭则回归零开销。
2.11 全栈覆盖：完整版 + 精简版，同一套代码切换
OnePath 提供两个产物变体，覆盖从云端到微控制器的全栈：
- 完整版（Full）：面向服务器与桌面，全功能，约 15 MB。
- 精简版（Tiny）：面向嵌入式与边缘、对尺寸敏感的场景，约 330 KB，核心功能齐全。
二者共享同一份头文件与同一套应用代码，用户通过一个编译宏即可在两个变体之间切换。这意味着同一套业务代码，既能在数据中心跑完整版，也能在资源受限的边缘设备上跑精简版，并接入同一张逻辑网络。
2.12 统一、简洁的 C 接口
单个头文件、一致的不透明句柄与回调风格，便于快速集成与长期维护。底层通信引擎已静态内嵌进库本身，运行时无任何外部通信依赖——用户链接一个 OnePath 库即可，无需额外安装任何运行时组件。
3. 与 DDS、分布式软总线的定位区别
OnePath 经常被拿来与两类概念比较：DDS（Data Distribution Service，面向严格实时分布式数据总线的工业标准）和分布式软总线（面向近场设备异构链路互联的通信框架）。三者使命不同、解决的问题不同，并非互相替代。理解这一点，是判断 OnePath 适用场景的关键。
说明：以下只讨论 DDS 与分布式软总线的通用概念，不涉及任何特定厂商的产品。
3.1 与 DDS 的定位区别
DDS 的使命：在封闭的、需要确定性服务质量（QoS）契约的分布式系统里，做强类型、强实时的标准化数据分发。它源自航空航天与国防领域，核心是 DCPS（以数据为中心的发布订阅）模型与一组丰富的 QoS 策略（可靠性、持久性、截止时间、存活检测、所有权等），强调类型安全与严格的实时保证。自动驾驶领域的 ROS 2、部分工业控制系统即建立在 DDS 之上。
OnePath 的使命：把异构总线与跨网段的节点统一接入一张逻辑网络，强调异构统一、跨网互联、全栈覆盖与极简集成。OnePath 不追求 DDS 那种细粒度的 QoS 契约，而是追求"一处编写、全网可达、极简接入"。
| 维度 | DDS（通用概念） | OnePath |
|---|---|---|
| 核心使命 | 强类型、强实时的标准化数据总线 | 异构统一的跨网段逻辑网络 |
| 跨网段互联 | 需额外部署 Router / Discovery Server 等桥接组件，配置复杂 | 原生转发网关，跨网中继对应用透明 |
| 寻址模型 | 强类型 topic + 分区 / 内容过滤 | 层级化名称 + 通配符集合语义订阅 |
| 嵌入式 / MCU 覆盖 | 通常较重，桌面 / 服务器为主 | 精简版可裁到约 330 KB，覆盖到资源受限设备 |
| 接入易用性 | QoS 策略多、类型工具链重、学习曲线陡 | 单头文件 + 零配置发现 + 透明重连，极简上手 |
| 可观测性 | 需额外监控工具 | 内置链路追踪 + 指标，零代码改动开启 |
| 类型模型 | 强类型（接口描述语言 + 序列化） | 灵活负载 + 内置序列化 + 内容编码标签 |
OnePath 的优势在于跨网段异构统一与全栈易用；DDS 的优势在于严格的实时 QoS 保证、强类型安全与成熟的工业标准生态。二者是互补关系：需要严格实时 QoS 契约的封闭分布式系统，DDS 是成熟选择；需要把异构节点跨网段统一接入、快速集成、并能从服务器一路覆盖到边缘设备的开放互联场景，OnePath 更契合。
3.2 与分布式软总线的定位区别
分布式软总线的使命：把同一局域网 / 近场范围内的设备，通过蓝牙、Wi-Fi、USB 等异构物理链路统一抽象成一条"软总线"，面向设备级互联。它强调多物理链路的管理与近场直达（尤其蓝牙的链路层直达、USB 直连），并常与具体操作系统的设备管理、权限体系深度集成。
OnePath 的使命：跨网段的统一逻辑网络 + 数据中心通信，面向跨网段、跨规模节点的数据分发与服务调用。
| 维度 | 分布式软总线（通用概念） | OnePath |
|---|---|---|
| 核心使命 | 近场设备异构链路统一接入 | 跨网段异构统一的逻辑网络 |
| 通信范围 | 限于同一局域网 / 近场 | 原生跨网段，转发网关可跨广域网 |
| 通信范式 | 数据传输以点对点会话为主，无原生发布 / 订阅 | 原生发布 / 订阅 + 请求 / 响应 |
| 寻址模型 | 扁平的会话名 + 设备标识 | 层级化名称 + 通配符集合语义订阅 |
| 嵌入式 / MCU 覆盖 | 依赖完整操作系统与设备框架，占用较大 | 精简版可裁到约 330 KB，覆盖到资源受限设备 |
| 断网恢复 | 通常需应用层重建会话 | 传输层透明重连，订阅 / 查询关系自动恢复 |
| 链路直达能力 | 蓝牙 / Wi-Fi 直连 / USB 等近场多链路强项 | 以 IP 网络与串口为主，面向跨网数据通信 |
OnePath 的优势在于跨网段、数据中心的发布订阅能力与全栈覆盖；分布式软总线的优势在于蓝牙等近场物理链路的原生直达与移动设备生态整合。同样地，二者互补：近场设备、尤其依赖蓝牙直连的消费电子互联，分布式软总线更合适；需要跨网段、跨规模、以数据为中心互联的场景，OnePath 更合适。
3.3 三者定位一览
一句话归纳：分布式软总线解决"近场怎么连"，DDS 解决"封闭系统怎么保证实时与类型契约"，OnePath 解决"异构节点怎么跨网段统一接入一张逻辑网络"。
4. 典型应用场景
- 异构系统集成（工业物联网、智慧城市）：把数据中心的算力节点、边缘网关、现场的传感器与终端统一接入一张逻辑网络，跨网段透明共享数据与服务，无需为每个网段单独搭通信栈。
- 机器人与无人系统：多节点的传感器数据分发、控制指令下发、服务调用，跨网段协同；同机节点自动零拷贝以获得高吞吐低延迟。
- 车路云协同与智能交通：车端（边缘 / 精简版）、路侧设备、云端（完整版）跨网互联，端到端链路追踪让整条数据链路可观测。
- 态势共享与指挥系统：跨子网、跨单位的节点统一组网，订阅式获取态势更新，断网后透明恢复，拓扑实时可视。
- 分布式实时数据共享：金融行情、能源监控、运维指标等场景下，海量动态数据的发布订阅与按需查询，弱网下历史补偿保证不丢数据。
- 嵌入式 + 云端混合部署：资源受限的现场设备运行精简版上报，服务器运行完整版聚合，同一套代码、同一张逻辑网络。
5. 提供给客户的内容
OnePath 以预构建库形式交付，客户无需自行编译底层通信引擎，链接一个 OnePath 库即可使用。交付内容如下。
5.1 版本库
| 变体 | 产物 | 典型体量 | 适用场景 |
|---|---|---|---|
| 完整版（Full） | libonepath-full.so | 约 15 MB | 桌面 / 服务器，全功能（含同机零拷贝、高级发布订阅、认证） |
| 精简版（Tiny） | libonepath-tiny.so | 约 330 KB | 嵌入式 / 边缘网关，尺寸敏感场景，核心功能齐全 |
两个变体的核心能力（会话、发布订阅、查询、请求响应、存活感知、自动发现、JSON5 配置）完全一致。完整版独占的能力（同机零拷贝 / 高级发布订阅 / 认证）在精简版下于头文件中即被声明剔除，误用会在编译期报错，而非运行期才暴露问题。
每个变体提供三种构建类型：debug（可调可单步）、release（生产优化）、minsizerel（尺寸优先）。底层通信引擎已静态内嵌，运行时零外部依赖。详见 变体选择 与 安装与集成。
5.2 库头文件
onepath.h—— 主头文件：版本、句柄类型、全部数据面 API。- 专题头文件：JSON 操作、链路追踪 Span、指标（Counter / Gauge / Histogram）。
单头文件设计、不透明句柄模型、一致的回调风格；客户通过一个编译宏选择完整版或精简版。
5.3 使用手册
- 网络拓扑感知指南 —— 本地自省 + 全局聚合、拓扑图、服务归类、变体可用性。
- 同机零拷贝指南 —— 同机自动零拷贝的开启、阈值调优、跨机自动回退、性能基准解读。
- 链路追踪与指标指南 —— 环境变量开关、自动埋点通路、多跳透传、指标对接。
- JSON 操作指南 —— 独立于会话的 JSON / JSON5 解析、层级查询、修改与序列化。
详见 专有场景。
5.4 API 手册
完整 API 参考手册，覆盖所有函数签名、参数与返回值、内存与所有权规则、创建 / 销毁配对表、常量与结构体定义，含会话、发布订阅、查询、请求响应、存活感知、同机零拷贝、高级发布订阅、拓扑感知、链路追踪、指标等全部模块。详见 API 手册。
5.5 演示用例
配套提供完整的演示用例集，覆盖 OnePath 的全部能力维度。每个用例均为可独立编译、可直接运行的 C 程序，命令行参数清晰、运行结果直接打印到终端，便于销售演示与客户快速上手。可在 Codelab 动手跑通。
标注「完整版」的用例依赖完整版独占能力（同机零拷贝 / TLS / 高级发布订阅 / 认证），精简版下不提供。
| # | 用例 | 演示能力 | 备注 |
|---|---|---|---|
| 1 | 自动发现 | 组播自动发现 + 对等组网下的发布 / 订阅 | |
| 2 | 用户认证 | 用户名密码接入认证 | 完整版 |
| 3 | TLS 加密 | 传输层加密通信 | 完整版 |
| 4 | 断线重连 | 中断自动重连 + 节点存活监控 | |
| 5 | 分布式存储 | 内存存储节点 + 查询响应 | |
| 6 | 查询演示 | 客户端主动查询（同步通道） | |
| 7 | 一次性读写 | 无需声明发布者的一次性写入 / 删除 | |
| 8 | 序列化 | 类型化数据的序列化 / 反序列化 | |
| 9 | 共享内存 | 同机零拷贝传输 | 完整版 |
| 10 | 高级发布订阅 | 消息缓存 + 丢包恢复 + 历史回放 | 完整版 |
| 11 | 会话信息 | 本节点标识、路由器与对等节点列表 | |
| 12 | 往返延迟 | 通信往返延迟测量与统计 | |
| 13 | 数据完整性 | 校验码 + 位翻转检测 | |
| 14 | 三模冗余 | 三模冗余 2-of-3 多数投票纠错 | |
| 15 | 延迟自适应 | 按往返延迟动态调整服务质量 | |
| 16 | 状态同步 | 混合逻辑时钟 + 最后写入胜出冲突解决 | |
| 17 | 自组网 | 自动发现 + 存活感知的服务注册与拓扑维护 | |
| 18 | 拉取式订阅 | 环形缓冲非阻塞拉取订阅 | |
| 19 | 存活快照查询 | 一次性查询当前存活节点 | |
| 20 | 持久请求器 | 持久请求端 + 非阻塞查询 + 匹配监听 | |
| 21 | 共享内存请求应答 | 请求 / 响应中的零拷贝 | 完整版 |
| 22 | 共享内存延迟 | 同机零拷贝往返延迟测量 | 完整版 |
| 23 | 吞吐基准 | 零拷贝 vs 普通传输的吞吐上限对比 | 完整版 |
| 24 | 共享内存传输基准 | 不同负载下零拷贝与网络传输的延迟对比 | 完整版 |
| 25 | 编码类型 | 内容编码类型 + 声明式寻址开销优化 | |
| 26 | 连接监控 | 连接状态轮询 + 节点存活监控 | |
| 27 | 端到端链路追踪 | 三进程调用链追踪 + 跨跳透传演示 | |
| 28 | 网络拓扑地图 | 拓扑自省 + 全局聚合可视化 | |
| 29 | JSON 数据处理 | 独立于会话的 JSON / JSON5 解析、查询、修改、序列化 |
另有配套自动化测试体系（单元测试 + 跨节点功能测试 + 冒烟测试），覆盖发布订阅、查询、零拷贝、拓扑、安全、链路追踪等全部能力，保障交付质量。
6. 结语
OnePath 的定位可以用三个关键词概括：异构统一、跨网互联、极简集成。
它不是要替代 DDS 去争夺严格实时的封闭系统市场，也不是要替代分布式软总线去争夺近场蓝牙互联市场——它填补的是"如何把异构的、跨网段的、从服务器到嵌入式设备的节点，统一接入一张逻辑网络，并用一套极简 C 接口打通数据与服务"这个位置。
对客户而言，这意味着：更少的集成工作、更广的覆盖范围、更低的接入门槛——一处编写，全网可达。