|
VLink
2.3.0
A high-performance communication middleware
|
观测一个运行中的分布式系统,需回答两个递进的问题:系统里**存在哪些端点**,以及这些端点上**正在流动什么数据**。VLink 用两层机制分别覆盖:服务发现(Discovery)自动感知全网拓扑,回答"有什么";代理监控(Proxy)旁路聚合话题载荷与统计,回答"在传什么",并能跨越网段边界搬运数据或反向注入。两者共享同一发现数据——Proxy 内部即运行一个发现视图来枚举待订阅话题,CLI 工具 vlink-list / vlink-monitor 亦建立在同一发现层之上。发现是基础,代理是其在跨网段、需要载荷数据时的延伸。

二者的能力边界如下,按需取用:
| 维度 | 🛰️ 服务发现 Discovery | 🔭 代理监控 Proxy |
|---|---|---|
| 回答的问题 | 系统中存在哪些端点(拓扑) | 端点上流动的数据与统计 |
| 数据内容 | URL、传输类型、角色、进程 | 话题统计 + 原始消息载荷 |
| 网段范围 | 同一发现网络(组播可达) | 可跨网段(单播 / 路由可达) |
| 方向 | 只读感知 | 观测 + 录制 + 注入 |
| 部署 | 内嵌库调用,零额外进程 | 需服务端(独立进程或嵌入业务进程) |
| 开销 | 周期组播,极低 | 订阅全部话题并转发,较高 |
服务发现使任一进程自动感知系统中全部活跃的 VLink 端点:URL(话题地址)、传输类型、所属进程,以及实时的上线与下线。机制基于 UDP 组播——节点运行时自动注册,断线由超时自动剔除,全程无需中心注册表或人工配置。发现层是 vlink-list、vlink-monitor 与代理监控的统一数据来源。
进程内若存在 VLink 节点,运行时即周期性地以 UDP 组播将本进程的端点拓扑广播至发现网络。监听者解码这些报文并按 URL 聚合,便得到一张全局拓扑视图,回答四个问题:
dds://、shm://、intra:// 等)。
两个边界条件需明确:
dds:// 的 raw 与 CDR 节点都会携带序列化类型和 schema family 出现在发现视图中。整条发现链路(节点上报 → 组播 → 监听者聚合 → 回调通知)的时序如下:

DiscoveryViewer 是发现机制的用户入口,继承自 MessageLoop。使用分为四步:构造时选定过滤模式、注册回调、async_run() 启动后台接收、按需读取快照。async_run() 是接收数据的前提,未启动则回调不会触发、快照为空。
回调在 viewer 的 MessageLoop 线程上执行,入参列表仅在回调内有效;需在回调外使用时先复制一份。多处需要同一张拓扑视图时,在应用层共享同一个 DiscoveryViewer 实例(或经 std::shared_ptr 持有)即可,无需逐处构造。
下表列出 DiscoveryViewer 的高频接口。除回调外,亦可在任意时刻经 get_info_list() 主动拉取一份当前快照,二者基于同一份内部状态。
| 方法 | 语义 |
|---|---|
DiscoveryViewer(FilterType type = kFilterNone) | 构造,指定过滤模式(见 12.4) |
void register_callback(Callback&&) | 注册 void(const std::vector<Info>&) 回调,拓扑变化时触发;重复注册仅最后一次生效 |
bool async_run() | 启动后台接收(继承自 MessageLoop),接收数据的前提 |
std::vector<Info> get_info_list() | 拉取当前拓扑快照 |
std::string get_ser_type(const std::string& url) const | 查询某 URL 当前的序列化类型名 |
SchemaType get_schema_type(const std::string& url) const | 查询某 URL 的 schema 家族 |
静态工具方法用于将角色位掩码格式化为可读标签,以及查询发现网络地址:
| 静态方法 | 语义 |
|---|---|
convert_type_to_view(uint32_t type) | 将角色位掩码格式化为可读标签 |
convert_type_to_view(uint32_t type, const std::vector<Process>&) | 同上,并附带进程列表的完整标签 |
convert_type(std::string_view str) | 将角色字符串("Pub"、"Sub" 等)转回 ImplType 位 |
get_listen_address() | 返回发现子系统使用的 UDP 组播/广播地址(默认 239.255.0.100) |
get_listen_domain() | 返回 VLINK_DISCOVER_DOMAIN 选定的发现域(默认 0) |
get_listen_port() | 返回发现子系统使用的 UDP 端口(51600 + domain) |
构造时唯一需要决策的参数是过滤模式,它决定哪些广播被纳入快照。默认 kFilterNone。
| FilterType | 行为 | 适用场景 |
|---|---|---|
kFilterNone | 保留全部发现到的端点 | 查看全网拓扑 |
kFilterAvailable | 屏蔽来自其它主机的本地传输(intra://、shm://、shm2://)端点,本机端点全部保留 | 监控工具的常用选择 |
kFilterNative | 仅保留与 viewer 同一主机名的端点 | 仅关心本机 |
判据:本地传输(intra://、shm://、shm2://)的端点仅在本机内可达,远端主机上报的此类端点对本机无实际意义。kFilterAvailable 据此剔除跨主机的本地传输噪声、同时保留本机全部端点,最适合通用监控;kFilterNative 则进一步排除一切非本机端点。
回调入参与 get_info_list() 返回的均为 Info 列表。每个 Info 描述一个 URL 的聚合信息,并内含承载它的进程列表 Process。
Info 字段 | 含义 |
|---|---|
url | 完整 VLink URL,如 "dds://camera_image" |
type | 该 URL 上全部角色的位掩码,经 convert_type_to_view 转为可读标签 |
ser_type | 序列化类型名,如 "demo.proto.PointCloud"、"standard" |
schema_type | 粗粒度 schema 家族:kProtobuf / kFlatbuffers / kRaw / kZeroCopy / kCdr / kUnknown |
process_list | 承载此 URL 的进程列表 |
Process 字段 | 含义 |
|---|---|
type | 该进程在此 URL 上承担角色的位掩码(Publisher / Subscriber / Server 等) |
host | 主机名 |
pid | 进程 ID |
name | 进程名 |
ip_list | std::vector<std::string>,当前仍有效的发现源 IPv4 地址,按 IPv4 数值升序排序并去重 |
profiler | 一个有效地址上报的 CPU 利用率百分比,不叠加多地址副本;-1 表示未启用(需 VLINK_PROFILER_ENABLE=1) |
bridge | 是否为 proxy 转发创建的 Publisher;旧报文缺省为 false,Python 同步提供此字段 |
type 是位掩码而非单一角色:同一 URL 可在同进程或跨进程上被多种角色同时使用(例如既有发布者又有订阅者),展示时统一经 convert_type_to_view 转换。
同一 URL、同一角色下,按主机名、PID、进程名和 bridge 来源合并地址,保留角色与来源间的独立记录。每个地址独立超时,全部地址过期后该记录消失;ip_list 只包含观测到的发现源地址,不代表主机全部网卡或业务后端地址。Python 的 DiscoveryViewer.Process.ip_list 对应字符串列表。
下例实时打印每个 URL 的角色与序列化类型,并逐进程输出 PID / 主机 / IP,在 Profiler 启用时附带 CPU 占用:
发现层回答的是"系统中存在哪些端点"。若需进一步掌握单个端点底层传输的运行状态——匹配对端的出现与消失、截止时间错过、liveliness 变化——则使用节点的 register_status_handler()。
该机制仅 DDS 系列后端生效(dds://、ddsc://、ddsr://);其它后端调用将打印警告并被忽略。回调接收 Status::BasePtr,在回调内经 status->get_type() 分发、经 status->as<...>() 安全下转以读取详情字段。
写方(Publisher / Server / Setter)与读方(Subscriber / Client / Getter)的状态类型如下:
| 状态类型 | 侧 | 触发条件 | 关键字段 |
|---|---|---|---|
kPublicationMatched | 写方 | 匹配的订阅者出现或消失 | current_count、total_count |
kSubscriptionMatched | 读方 | 匹配的发布者出现或消失 | current_count、total_count |
kOfferedDeadlineMissed / kRequestedDeadlineMissed | 写 / 读 | 未在截止时间内发出 / 收到数据 | total_count、last_instance_handle |
kLivelinessLost | 写方 | liveliness 时限内未声明 | total_count |
kLivelinessChanged | 读方 | 对端存活状态变化 | alive_count、not_alive_count |
kOfferedIncompatibleQos / kRequestedIncompatibleQos | 写 / 读 | 发现 QoS 不兼容的对端 | last_policy_id |
kSampleRejected / kSampleLost | 读方 | 样本因资源限制被拒 / 送达前丢失 | total_count(kSampleRejected 另有 last_reason) |
Deadline、Liveliness 等语义由 QoS 策略定义,配置方式见 QoS 配置。代表性回调如下:
发现机制是若干现成工具的底层数据源,多数场景无需自行编写监控程序。
| 入口 | 形态 | 用途 |
|---|---|---|
vlink-list | 一次性查询 | 打印当前全网拓扑表格后退出 |
vlink-monitor | 持续监控(类 top) | 实时刷新,支持按 URL 子串(-i)或进程 hostname(--hostname)过滤 |
| 应用内嵌 | 库调用 | 在应用内构造 DiscoveryViewer,无需单独进程 |
| 代理聚合 | 代理层 | 代理内部运行 viewer 聚合多进程拓扑,供远程监控 |
参数与输出示例见 CLI 工具;代理聚合见 12.8 起。
发现行为经环境变量调节(完整说明见 集成与扩展):
| 环境变量 | 作用 |
|---|---|
VLINK_DISCOVER_DISABLE=1 | 禁用本进程的发现上报 |
VLINK_DISCOVER_NATIVE=1 | 仅限本机发现(组播绑定 loopback) |
VLINK_DISCOVER_IP=<ip,...> | 指定发现组播逐地址发送与加组的本机 IPv4 地址;未设置时收发按系统路由走;同时是 VLINK_DDS_IP 的缺省值 |
VLINK_DISCOVER_DOMAIN=<0-255> | 发现域,默认 0:UDP 端口取 51600 + domain,组播地址与路由不变;须在所有进程上设为同一值;非十进制数字或超出 [0,255] 的值会告警并回落到 0,该值在进程内读取一次,此后修改无效 |
VLINK_PROFILER_ENABLE=1 | 启用 CPU Profiler,使 Process::profiler 有效 |
若需让单个节点不出现在发现视图,可在 init() 之前关闭其上报。这要求节点以延迟初始化方式构造:
Proxy 是 VLink 的旁路监控、录制与注入中间层。业务节点照常使用 dds://、shm:// 等原生传输通信,Proxy 在不改动业务代码的前提下聚合全部话题的载荷与统计,并转发给监控、可视化、录制与回放工具。

VLink 原生传输要求通信双方在同一网段或 DDS 域内能直接发现彼此。当存在路由、防火墙或 VLAN 隔离,或需要在远端集中观测时,原生发现无法跨越边界。Proxy 在业务侧引入一个服务端,由它在本地订阅全部话题(待订阅话题来自 12.1 的发现视图),再通过一条受控链路把数据与统计转发到远端客户端。
体系由三个组件构成,按部署形态选用:
| 组件 | 形态 | 职责 |
|---|---|---|
vlink-proxy | 独立守护进程 | 同机每个 DDS 域一个实例,可连接另一域的代理转发话题 |
ProxyServer | C++ 服务端库 | 将服务端嵌入业务进程,省去独立进程 |
ProxyAPI | C++ 客户端库 | 监控、可视化、录制、注入工具连接服务端的入口 |
链路划分为两个平面,职责与安全级别不同:
| 平面 | 承载内容 | 特性 |
|---|---|---|
| 控制面 | 握手、心跳、控制指令、话题统计 | 经 DDS 安全扩展加密;自动握手、协商会话凭据、断线自愈 |
| 数据面 | 转发与注入的原始消息载荷 | 可选 reliable / TCP / SHM 直连,客户端与服务端配置须一致 |
数据面搬运的是原始序列化字节(Bytes,回调内以浅拷贝视图交付);当载荷本身为零拷贝容器序列化结果时,其布局细节见 零拷贝,普通使用无需关心。
监控端的最小流程为四步:填写 Config、注册回调、async_run() 启动事件循环、send_control() 选择工作模式。
服务端在目标机上启动一行命令:
连接建立后,客户端每秒收到一次话题统计(InfoCallback);选择观察模式后还会收到原始数据(DataCallback)。链路中断约 5 秒触发 ConnectCallback(false),框架在后台自动重连并重发上一次控制指令,无需用户干预。
完整的连接、心跳、控制与数据流转时序如下:

ProxyAPI 为客户端类。构造后调用 async_run()(后台线程)或 run()(当前线程)启动,quit() / wait_for_quit() 退出。Config 一经构造不可更改。
角色在构造时由 Config::role 固定,决定客户端能否驱动服务端:
| 角色 | 权限 |
|---|---|
kController | 可调用 send_control() / send_data(),驱动服务端 |
kListener | 只读观察;send_control() / send_data() 立即返回 false |
direct 模式的 Listener 通过每秒心跳同步当前订阅选择,支持晚加入,并跟随控制端切换选择或停止。
工作模式由控制端通过 Control::mode 切换,决定服务端订阅哪些话题、是否转发数据、是否接受注入:
| 模式 | 用途 |
|---|---|
kObserveAll | 观察域内全部话题:监控面板、Foxglove/Rerun 全量桥接 |
kObserveOne | 仅观察 url_meta_list 指定的单个话题 |
kRecord | 录制指定话题,配合落盘工具 |
kPlay | 回放注入:经 send_data() 灌入数据,服务端转发到真实话题 |
kEdit | 编辑注入:服务端转发控制端注入的数据 |
kAuto / kAutoAndObserveAll | 观察 url_meta_list 指定话题并接受控制端注入;后者改为观察全部话题 |
kOffline | 离线:服务端释放全部订阅 |
五个回调各注册一次,框架在对应事件触发时调用。回调入参(尤其 Data::raw)仅在回调内有效,需外带时先复制。
| 方法 | 触发时机 |
|---|---|
register_connect_callback(void(bool connected)) | 连接状态变化(首个心跳建立 / 断线约 5 秒) |
register_error_callback(void(Error error)) | 错误状态翻转时(见 12.10.5) |
register_time_callback(void(uint64_t sys_time, uint64_t boot_time)) | 每秒心跳,携带服务端系统时间与启动时长(微秒) |
register_info_callback(void(const std::vector<Info>&)) | 每秒一次的话题统计列表 |
register_data_callback(void(const Data&)) | 转发模式下每条数据 |
| 方法 | 语义 |
|---|---|
bool send_control(const Control& ctrl, bool async = true) | 设置模式与关注话题,控制端专用。async=true(默认)投递到事件循环后即返回;false 同步发布并返回真实结果 |
bool send_data(const Data& data) | 向数据通道注入一条消息(kPlay / kEdit 用),控制端专用 |
send_control() 被内部缓存,断线重连后自动重发。send_data() 返回 false 不一定是链路故障,也可能是对端暂无订阅者,或注入数据未填全 ser 与 schema 路由元数据。
连接与统计可随时主动查询:
| 方法 | 返回 |
|---|---|
bool is_connected() | 是否已连接服务端 |
Error get_current_error() | 当前错误码(kNoError 为正常) |
Mode get_current_mode() | 最近一次请求的工作模式 |
int64_t get_latency() | 数据通道延迟(纳秒;direct/SHM 模式返回 0) |
SampleLostInfo get_lost() | 数据通道丢包统计 |
std::string get_proxy_version() | 服务端上报的 VLink 版本字符串 |
std::string get_current_hostname() | 已连服务端的主机名 |
double get_current_cpu_usage() / get_current_memory_usage() | 服务端 CPU / 内存占用(0~100) |
static bool is_support_shm() | 当前构建是否支持 SHM(用于决定 direct) |
两个静态辅助函数把心跳时间戳格式化为可读串:
错误仅在状态翻转时通过 ErrorCallback 上报。除配置类错误外,多数可自愈:
| 错误码 | 触发条件 | 自动恢复 |
|---|---|---|
kNoError | 连接正常 | — |
kControlError | 控制标识与服务端不匹配 | — |
kReliableCompError / kTcpCompError / kDirectCompError | 客户端与服务端的 reliable / enable_tcp / direct 设置不一致 | 否,需统一配置后重连 |
kMultiProxyError | 同一域内检测到多个 ProxyServer,或服务端身份突变 | 部分,真实多服务端需移除多余实例 |
kVersionCompError | 客户端与服务端 VLink 版本不一致 | 是,版本恢复后自动清错 |
kTokenError | 控制面握手未通过 | 是,后台自动重握手直至成功 |
Info(每条话题统计)常用字段:
| 字段 | 类型 | 说明 |
|---|---|---|
url | std::string | 话题 URL,如 "dds://sensor/lidar" |
ser | std::string | 序列化类型名,如 "demo.proto.PointCloud" |
schema | SchemaType | 粗粒度 schema 家族(kProtobuf / kFlatbuffers / kCdr 等) |
status | Status | kActive / kInActive / kPending / kInvalid |
freq / rate | float / uint64_t | 频率(条/秒)/ 吞吐(字节/秒),滑动平均 |
loss / latency | float / float | 丢包率 [0,1] / 延迟(毫秒;-1 无样本,-2 无效) |
process_list | std::vector<Process> | 收发该话题的进程列表(type 角色位掩码 / host / pid / name / ip_list),地址语义同发现快照 |
Data(每条转发或注入数据)字段:url、ser、schema、raw(Bytes 原始载荷)、timestamp(微秒)、seq(序号)。注入时 ser 与 schema 必须显式填全。
构造 ProxyAPI 时传入。控制面行为由前几项确定,数据面三项必须与服务端逐一对齐:
| 字段 | 默认 | 说明 |
|---|---|---|
role | kController | 客户端角色(见 12.10.1) |
domain_id | 0 | DDS 域 ID,须与服务端一致 |
security_key | "" | 控制面对称密钥;空串使用内置默认槽位,显式设置时须与服务端一致 |
native | false | 将 DDS 节点绑定到 VLINK_DDS_NATIVE_IP(未设置时为 127.0.0.1) |
reliable / enable_tcp / direct | false | 数据通道选项,三者均须与服务端完全一致 |
match_version | true | 是否校验 VLink 版本字符串一致 |
跨网段单播发现使用 allow_ip(本地绑定 IP)与 peer_ip(对端 IP),留空时走组播(部署示例见 12.16)。其余高级字段(dds_impl 等)保持默认即可。
vlink-proxy 是 ProxyServer 的独立可执行版本,同机每个 domain_id 仅允许一个实例。命令行参数映射到 ProxyServer::Config:
| 选项 | 说明 |
|---|---|
-d, --domain_id INT | DDS 域 ID(0~255,默认 0),须与客户端一致 |
-k, --key STRING | 安全密钥(默认空),须与客户端一致 |
-r, --reliable | 可靠 QoS(须与客户端一致) |
-t, --tcp | TCP 传输(须与客户端一致) |
-g, --direct | SHM 直连数据通道(须与客户端一致) |
-a, --async | 在 MessageLoop 线程异步转发数据(默认内联转发) |
-x, --max_packet_size FLOAT | 单条消息最大转发大小(MiB,默认 4.0) |
-b, --allow_ip / -p, --peer_ip | 本地绑定 IP / 单播对端 IP(跨子网用) |
-s, --buf_size INT / -e, --mtu_size INT | DDS 收发缓冲区 / MTU 字节数(默认 0 = 内置默认) |
-n, --native | 仅发现本机节点,并将 DDS 节点绑定到 VLINK_DDS_NATIVE_IP(未设置时为 127.0.0.1) |
-c, --iox_config PATH | 指定 Iceoryx TOML 配置;提供此项即拉起内嵌 RouDi(direct/SHM 所需) |
-l, --iox_strategy INT | Iceoryx 内存策略(1 mini / 2 低 / 3 中 / 4 高,默认 3);提供此项即按内置策略拉起 RouDi |
-m, --iox_monitoring on\|off | Iceoryx 监控开关(默认 on) |
--dds_impl STRING | DDS 实现选择(dds / ddsc) |
--runnable [NAME...] | 加载 RunablePluginInterface 插件 |
--config PATH | 所有业务启动参数的 JSON 配置文件;显式命令行参数优先 |
--bridge_domain_id INT | 启用桥接,连接指定远端 proxy 域(0~255),须与本代理域不同;默认不启用 |
--bridge_security_key STRING | 远端 proxy 密钥,默认空串 |
--bridge_allow_ip / --bridge_peer_ip | 内部 ProxyAPI 的本地绑定 IP / 远端发现 IP,默认空串 |
--bridge_dds_impl STRING | 远端 DDS 实现,未指定时使用本代理的 dds_impl |
--bridge_reliable / --bridge_enable_tcp | 远端数据通道选项,默认 false,须与远端 proxy 一致 |
--bridge_filter STRING | 源 URL 子串过滤,空格或逗号分隔、忽略大小写、任一匹配即转发;默认 shm://,shm2://,intra://,空串不限制 URL |
--bridge_subscribe | 主动采集本地业务 Publisher,经 ProxyAPI 下发给远端已发现的 Subscriber;默认 false |
SHM 直连(
-g)需 Iceoryx RouDi 在运行:可由-c/-l让代理内嵌拉起,或外部预先启动iox-roudi。
本地 DDS 绑定参数统一为 --allow_ip(短参数仍为 -b),JSON 与 C++/Python 配置字段同步为 allow_ip。
JSON 键与长参数名一致(去掉 --),例如 domain_id、key、tcp、iox_config、runnable、bridge_domain_id。每项按**显式命令行值 → JSON 值 → 内置默认值**取值,domain_id 默认仍为 0。布尔参数使用 JSON 布尔值,runnable 使用字符串数组,iox_monitoring 使用 "on" / "off"。显式空字符串、空插件列表和数值 0 也会覆盖 JSON;现有布尔开关出现时设为 true。--config 只指定当前文件,不递归加载其他配置。
完整配置示例为 proxy/etc/proxy_config.json,其中启用了连接域 10 的桥接和内嵌 RouDi。JSON 中提供 iox_config 或 iox_strategy 与命令行 -c / -l 一样启用 RouDi;使用外部 RouDi 时应省略这两项。JSON 内的相对 iox_config 路径以 JSON 文件目录为基准,命令行路径仍以工作目录为基准。同机多个代理应共享一个 RouDi,不能各自重复启动。
桥接内嵌 ProxyAPI::kController,使用 kAuto 模式按远端服务发现及 bridge_filter 配置采集和发布通道。远端 proxy 的控制权由 bridge 持有。两端 proxy 均需使用非 direct 数据通道,密钥、DDS 实现、可靠性和 TCP 设置须与桥接参数匹配。
远端 Subscriber 会合并到本端发给 viewer 的服务发现列表。viewer 向匹配 URL 下发消息时,bridge 校验远端订阅及序列化元数据,由远端 proxy 使用原 URL 发布,同时保留本地投递;共享通道及返回镜像不重复发布。未发现 Subscriber 的 URL 不建立下行路由。订阅消失后,下一次 Info 更新会撤销对应路由和远端 Publisher。
bridge_subscribe 默认关闭;开启后,上位机等本地业务 Publisher 的消息也可经内嵌 ProxyAPI 下发到远端 ProxyServer。按远端 Subscriber 预建本地订阅,已发现的本地 Publisher 序列化信息必须匹配,URL 须匹配 bridge_filter,且远端没有业务 Publisher;同一 URL 不同时建立镜像与反向采集。Viewer 注入也经该订阅下发,避免重复转发。远端订阅撤销、连接断开或元数据冲突后停止对应转发。
镜像及桥接下发 Publisher 均保持服务发现,monitor 可自动订阅。发现报文仅对转发 Pub 追加可选尾字段 bridge=1:旧接收端忽略该字段,新接收端接受无标记旧报文,原有字段及 profiler 位置不变。proxy 排除带标记的发布源,再按当前桥接表合并镜像;同进程、同 URL 的真实 Pub 与转发 Pub 分开聚合、独立过期。防回流要求两端 proxy 及其运行库同步更新,旧版 monitor 可继续使用。
目标 Publisher 保留完整源 URL(包括协议、查询参数和 fragment)、序列化类型及原始载荷:shm:// 仍为 SHM,shm2:// 仍为 SHM2,intra:// 仍为 intra。过滤发生在源 URL 上,多个过滤词是“或”的关系。目标需具备对应后端;intra:// 仅供接收代理进程内的业务或 runnable 插件订阅,源端也需能采集该进程的可序列化 intra 消息。进程内裸对象共享、RPC 与 Field 不在此桥接范围内。
桥接发布表独立于本地监控控制,按源端 Info 快照增删,断连或协议错误时清除。镜像与主动采集在接收回调内同步转发,Viewer 本地投递沿用 async,载荷受本代理 max_packet_size 限制;不缓存断线期间的数据,不保证跨网络零拷贝。同机判断要求 hostname 与本机 IPv4 地址集合匹配;两端 machine-id 均非空时还须一致,允许 machine-id 为空。相同机器上的 SHM/SHM2 源通道已可直接访问,桥接按实际后端跳过这些通道,包括 VLINK_INTRA_BIND 映射的 intra,以避免回灌;部署须无环,不要将镜像发布通道再桥接回源端。
未映射到其他传输的 intra 只报告源代理进程内的端点,避免同机其他代理的镜像反馈;桥接合并的远端订阅仍用于下行路由。开启桥接时,本地 DDS 业务端点及镜像使用本代理指定的绑定 IP、peer、buffer 和 MTU;启用 tcp 时设置 TCP,未启用时保留后端环境配置;native 优先使用 VLINK_DDS_NATIVE_IP。
停止服务并等待退出会排空桥接接收回调、撤销镜像及路由。
无需独立进程时,用 ProxyServer 库将服务端嵌入业务进程。每个进程仅一个实例,构造后调用 async_run() / run() 启动。Config 字段与 vlink-proxy 参数对应:domain_id、security_key、reliable、enable_tcp、direct、native_mode、max_packet_size、allow_ip / peer_ip。
ProxyServer 析构同步阻塞,会等待全部 DDS 句柄清理后返回,须确保进程退出前调用。
嵌入式桥接使用 cfg.bridge.emplace() 填写远端 ProxyAPI::Config,例如 cfg.bridge->domain_id = 10;cfg.bridge_filter 默认同命令行。内部强制使用 Controller,两端 direct 必须为 false。新增配置字段改变了 Config 布局,使用该 C++ 接口的程序需重新编译。
控制面经 DDS 安全扩展加密,由 security_key 对称密钥保护,两端必须一致:
security_key 留空时两端使用同一内置默认槽位,可正常通信;生产环境应显式设置自定义密钥。控制面自动完成安全握手与会话凭据协商,对业务代码透明,无需介入。
match_version(默认 true)在首次心跳时校验服务端与本端的 VLink 版本一致,不符触发 kVersionCompError。需跨版本连接(不推荐)时设 match_version = false。
Control 支持在服务端按 URL 关键词或进程名过滤,减少订阅与转发量:
filter_type 取值:0 全部;1/2/3 分别仅显示成对的 Pub+Sub / Server+Client / Setter+Getter 话题;4/5/6 分别显示 Event / Method / Field 类话题;7~12 分别仅显示单一角色。可用 ProxyAPI::is_enable_filter() 查询当前构建是否支持过滤。
典型场景:车载计算单元(EdgePC)运行业务节点与代理服务端,开发机(DevPC)远程监控与注入。两端以 allow_ip / peer_ip 做 DDS 单播发现,双方 IP 须可路由可达。跨 NAT 时可改用 zenoh:// 并部署双方可达的 router/显式 endpoint,或另配网络穿透;VLink 不自动穿透 NAT。
EdgePC 在 12.13 的嵌入式服务端基础上补充绑定 IP:
DevPC 复用 12.9 的最小客户端,补上 IP:
**录制**:选 kRecord 模式,在 DataCallback 中立即将数据写入 bag(落盘容器用法见 录制与回放)。Data::raw 仅在回调内有效,因此下例的 shallow view 只覆盖紧随其后的 BagWriter::push() 调用;push() 的异步分支会在返回前建立 owning Bytes 副本,同步分支则在调用内完成写入。若应用先把 Frame 排入自己的异步队列、稍后才调用 push(),必须在回调内改用 deep_copy。
**回放**:选 kPlay 模式,url_meta_list 中 Event 的 type 设为 vlink::kPublisher,Field 设为 vlink::kSetter,再以 send_data() 逐条注入。Field 路由要求客户端与服务端均支持 kSetter;旧服务端不能处理该路由。
vlink-proxy 可执行文件通常直接使用系统安装版本,无需手动链接。
错误码语义见 12.10.5;下表给出常见现象与处置:
| 现象 | 原因与处置 |
|---|---|
连接被拒,报 kReliableCompError 等 | reliable / enable_tcp / direct 客户端与服务端不一致,须逐项对齐后重连 |
报 kMultiProxyError | 同一 DDS 域内运行了多个 ProxyServer,须每域一个实例或为各实例分配独立 domain_id |
Data::raw 外带后失效 | 不要单独保存 shallow view;可在回调内立即 BagWriter::push() 由 writer 同步消费或建立 owning 副本,其他外带路径须先 Bytes::deep_copy |
direct 模式无数据 | SHM 直连需 Iceoryx RouDi 在运行,须先启动 iox-roudi 或由代理内嵌拉起 |
| 进程退出残留句柄 | ProxyServer 析构同步阻塞清理 DDS 句柄,须在进程退出前显式调用 |