1. bridge是干什么的UDP桥接在Apollo里的真实定位先从一个高频场景说起。很多团队在做自动驾驶系统集成的时候会遇到一个很尴尬的问题Apollo平台内部的模块之间用CyberRT通信话题Topic的定义、序列化方式、收发机制都是平台内部的规矩但外部设备——比如不带CyberRT的MCU板卡、工控机上的V2X盒子、自己写的仿真上位机——根本不认这套协议。它们唯一能统一理解的东西就是最基础的TCP/UDP网络包。于是我们就需要一座桥把CyberRT世界里的消息翻译成外部系统能收发的UDP数据反过来也一样。Apollo的bridge模块就是干这件事的。这里说的bridge是Apollo平台框架里独立的一个通信桥接模块专门负责把CyberRT话题和外部UDP报文相互转换。它在整个体系里的定位很像一个翻译官加邮差内部接CyberRT总线的发布订阅外部接一个UDP网络端点IP和端口中间只做最小限度的格式转换不负责业务逻辑也不做复杂的路由决策。因为模块本身很薄所以延迟小、资源占用低适合放在车载工控机上常驻运行。哪些人需要关注这个模块做车辆底盘接入的工程师车辆底盘控制器通常只提供CAN或者串口转以太网的接口你想把底盘状态车速、转向角、挡位送进Apollo的/chassis话题bridge一边帮你接收UDP数据包另一边帮你以CyberRT消息的形式发布出来。做V2X路侧通信或者车路协同的团队路侧设备发来的SPaT、RSM等信息很多就是自定义UDP协议需要桥接进平台内部话题。做仿真和测试平台开发的同学上位机要实时读取Apollo内部定位、规划结果又不想在外部系统里重新实现一整套CyberRT客户端直接开一个UDP端口让bridge把内部消息推出来。一句话概括bridge的价值它把Apollo内部的事和外部世界的事用UDP这条物理通道解耦了。没有它外部系统要接入Apollo就必须在目标机上装CyberRT环境、写同样的proto定义、处理发现机制这复杂度不是一般的高。有bridge外部只要懂socket编程就万事大吉。这一篇我重点讲清楚三件事模块配置怎么填、收发链路怎么走、实测会踩哪些坑。理解了这些你至少能搭出一个可以跑的UDP桥接通路后面再谈大规模多通道管理和可靠性优化。2. 模块怎么配置拆解一个Bridge节点的关键参数先说结论Bridge模块的配置并不神秘本质上就是声明一个内部话题、一组网络端点、一个消息协议。你搞清楚这几个参数的组合关系就能读懂绝大多数版本的配置。2.1 从一个典型配置说起Apollo里bridge模块的配置通常以bridge_conf.pb.txt的形式存在里面包含一到多个bridge节点定义。我基于平时见到的版本整理一个典型片段字段名在不同的Apollo版本里可能略有差异但逻辑是一样的bridge_senders { id: 1 proto_desc_file: /apollo/modules/localization/proto/localization.proto proto_msg_type: apollo.localization.LocalizationEstimate channel_name: /apollo/localization/pose output_ip: 192.168.1.100 output_port: 8001 bind_port: 0 } bridge_receivers { id: 2 proto_desc_file: /apollo/modules/canbus/proto/chassis.proto proto_msg_type: apollo.canbus.Chassis channel_name: /apollo/canbus/chassis input_ip: 192.168.1.101 input_port: 9000 bind_port: 9000 }左侧bridge_senders负责把Apollo内部消息往外发比如我要把定位结果LocalizationEstimate发给某个外部上位机目标地址是192.168.1.100:8001那么bridge会订阅/apollo/localization/pose话题收到消息后序列化成字节流用UDP发给目标IP和端口。右侧bridge_receivers负责从外部收UDP数据进来比如底盘控制板在192.168.1.101:9000持续发送UDP包bridge在这个端口上监听收到数据后按Chassis的定义反序列化然后以CyberRT消息形式发布到/apollo/canbus/chassis话题上。对了conf里还有接收方配置的channel_name不同版本的字段措辞不一样有的叫channel_name有的在receiver里直接写proto_msg_type对应的消息推送到统一话题总之你要记住的映射关系是网络包里的字节流 ↔ 某种proto消息类型 ↔ 一个CyberRT话题。2.2 proto描述文件最容易配错的地方我用了一个词proto_desc_file。这个配置指向一个.proto文件bridge靠它来解析消息的二进制布局。很多同学第一次配置时会想外部系统发来的数据格式不就是我自己定的吗为什么还要麻烦proto原因在于CyberRT的总线传输要求消息必须按照protobuf序列化后的二进制格式携带。也就是说外部设备发送UDP包的时候payload本身必须是一个已经用protobuf序列化好的二进制块。bridge收到之后借助proto描述文件把字节流解析成具体的消息类型再塞进CyberRT的Writer发布出去。这种做法有个很直接的好处数据体积小序列化/反序列化速度快。自动驾驶场景里一帧Chassis通常不超过一二百字节如果用JSON文本格式光键名就占了半天实时性会差很多。UDP本身是非可靠传输丢了还得重发包里放越多冗余数据丢包概率越高。不过要注意外部设备需要持有与Apollo侧完全一致的proto定义尤其注意字段编号而不是字段名。有人用Python的protobuf库在MCU侧生成消息时顺手改了字段顺序或者漏了几个可选字段结果bridge这边解析出来的数据和实际发送的对不上这种问题很难查因为不报错只是值错乱了。我一般会在配置好proto之后先打印一帧原始hex数据对比一下再上真链路。2.3 多个bridge节点怎么组织通道与端口规划实际工程项目往往不止一个话题要桥接。定位、底盘、规划轨迹、障碍物列表全都要和外设通信。你可以为每个话题单独开一个bridge节点端口依次排开也可以用同一个节点承载多个消息类型。我的经验是按“方向消息优先级”组织更合理而不是按“消息类型”硬切。比如接收方向只开一个端口9000外部设备所有数据都发到这个端口bridge根据消息头里的类型标识分发给不同的CyberRT话题发送方向同样用单一端口把多路消息轮流发出去。这样做的好处是外部设备只需要维护一条网络链路不需要针对每个话题记一串端口。代价是需要在业务代码里做一个轻量级的封装在每个UDP包头部加个自定义头比如4字节消息IDbridge收到后先读ID再决定用哪个proto解析。这个自定义分包逻辑CybeRT不关心纯粹是外部协议部分。如果不想自己写那开多个端口就是更省事的办法缺点是外部设备要维护多套socket连接、留意端口冲突。3. 数据通路的细节CyberRT和UDP互相转换时发生了什么配置看懂了下一步就得弄明白里面的数据究竟是怎么流动的。我在调bridge时发现很多人对这个过程的理解是“大概就是把消息打包成UDP发出去”这个理解没错但差了很多关键细节——现实场景中正是这些细节决定了整个链路的延迟和稳定程度。3.1 发送方向的三段式流水线发送方向一个消息从Apollo内部到达外部设备在bridge里走这样的流程订阅CyberRT话题bridge注册了一个Reader绑定比如/apollo/localization/pose话题平台内部的writer每发一帧数据这里就收到一个消息对象。序列化调用message.SerializeToString()方法把消息对象变成std::string或者字节缓冲区。protobuf序列化输出的是一段紧凑的二进制数据字段值按编号连续排布顺序跟字段定义的顺序无关虽然实践上差不多。UDP打包发送在序列化结果前面加一个4字节的报文长度头很多实现会用固定长度头加payload的方式方便接收端自适应解析然后用socket的sendto发给配置的目标IP和端口。如果你伸手介入过这个过程应该已经注意到一个点UDP的sendto是非阻塞的吗不是系统默认的socket在发送缓冲区满时会把进程卡住。在自动驾驶系统中如果外部设备的网络接收速度跟不上发送缓冲区一旦积压bridge线程会卡在sendto上进而拖累CyberRT的Reader回调——因为Reader的回调线程如果被阻塞后续消息就会排队整个Apollo内部的话题消费延迟都会拉高。遇到这种状况我常用的手段是给发送socket设置非阻塞模式或者干脆在bridge回调里把发送工作丢到一个独立线程池。不太建议简单地在线程里加锁然后死命发丢失和延迟一旦出现很难和问题根源对上号。3.2 接收方向的两个重要细节接收链路反过来的逻辑是外部设备发udp包到某个端口bridge的socket在循环中recvfrom解析出二进制再调用ParseFromString()拿到消息对象后用Writer发布到CyberRT话题。这里面我认为有两个容易忽略的细节第一收到的是一个包还是多个包UDP接收端的经典问题——如果外部设备在一瞬间连续发了好几个小报文你的应用层缓冲区一次recvfrom可能只取走一个数据报。剩余的数据报留在内核缓冲区里不会被自动拼接。所以接收循环里必须反复调用recvfrom直到缓冲区为空否则在高速数据流下会积压。第二帧边界要靠报文长度头去切。UDP虽然有报文边界但一次收到的包内容是否正好是一条完整消息呢不一定。尤其当你自己定义过自定义头、或者外部设备是分两次发送的消息时很容易收到半条内容。所以接收解析时必须维护一个上次没处理完的残留缓冲区比如我习惯的做法是先把收到的数据追加到残留缓冲区末尾然后不断尝试从缓冲区开头按固定头格式提取一条完整的消息提取成功就交给ParseFromString直到缓冲区长度不足一条完整消息为止。这样实现的接收逻辑对零星碎包、粘包都有很好的容忍度。3.3 为什么这个方案“够用”但别指望“完美”需要明确一点UDP桥接不等于可靠通信。你用bridge搭起来的是一个尽力而为的实时通道不是文件传输通道。自动驾驶中很多传感器数据比如定位、车速是以几十赫兹频率持续刷新的偶尔丢一帧对系统影响不大因为下一帧马上就到。此时用UDP换来的是微秒级的收发延迟和极简的网络握手这对控制系统是值得的。但如果你的场景要传的是规划轨迹的完整列表、地图片段、或者其他需要零丢失的数据那么UDP加bridge的方案就不合适了你应该考虑在应用层自己做确认重传或者干脆换到另一个通信机制。拿bridge去硬扛可靠传输只会把模块改得面目全非还未必性能达标。选型一开始就要心里有数。4. 实操跑通搭建一个最小可用的UDP桥接实验前面说得再多不如亲手把链路跑通一次。下面这组实验方法是我常用的不需要特别复杂的设备——一台装了Apollo的开发机、一台可以在同一网络里发包的电脑也可以是开发机自身回环就够了。4.1 实验目标我们要验证两件事外部UDP数据能进到Apollo内部的CyberRT话题里Apollo内部某个话题的数据能通过UDP发到外部监听程序里。为了让场景更直观我用一个简单的外部Python脚本模拟底盘控制板发送一条Chassis类型的消息到bridge同时在另一边监听bridge转发出来的定位话题。4.2 准备输入数据模型先确保你的编译环境里存在proto描述文件。以Chassis为例你可以直接复用Apollo里现有的chassis.proto。但为了让实验最小化我倾向于自己定义一个极简的proto文件减少依赖syntax proto2; package bridge_test; message VehicleState { optional double speed_mps 1; optional double steering_angle_rad 2; optional int32 gear 3; optional uint64 timestamp_ns 4; }注意字段编号后面Python端生成数据时要完全一致。把proto文件放到一个外部Python脚本可访问的路径用protoc命令生成vehicle_state_pb2.pyApollo侧的proto_desc_file就填同一个路径下的.proto文件位置。4.3 配置一个最小Receiver节点假设外部Python脚本往本机回环地址127.0.0.1:9400持续发送VehicleState的二进制数据。我只需要一个bridge_receiver配置bridge_receivers { id: 10 proto_desc_file: /tmp/bridge_test/vehicle_state.proto proto_msg_type: bridge_test.VehicleState channel_name: /bridge_test/vehicle_state input_ip: 127.0.0.1 input_port: 9400 bind_port: 9400 }这里用回环地址好处是调试方便不需要两台机器也不会受网卡配置干扰。把配置放到Apollo运行时加载bridge模块的正确路径下不同Apollo版本的加载方式不同常见的是通过modules/bridge/conf/下的配置然后以Cyber模块方式启动。4.4 外部发送端Python代码外部Python脚本只需要一个UDP socket。以下是核心片段用完全虚构的演示实现import socket import time import vehicle_state_pb2 sock socket.socket(socket.AF_INET, socket.SOCK_DGRAM) addr (127.0.0.1, 9400) msg vehicle_state_pb2.VehicleState() msg.speed_mps 3.5 msg.steering_angle_rad 0.1 msg.gear 1 msg.timestamp_ns int(time.time() * 1_000_000_000) payload msg.SerializeToString() # 可选如果你的bridge实现需要长度头这里再加一个 struct.pack(!I, len(payload)) sock.sendto(len(payload).to_bytes(4, byteorderbig) payload, addr)值得一提外部设备端如果用的是C、C或者Go核心操作也一样生成同样的proto对象、用同样的protobuf序列化即可只要保证编码后的字节流完全一致跨语言毫无障碍。4.5 验证CyberRT里能订阅到数据吗bridge模块启动之后我可以打开另一个终端用CyberRT自带的调试工具订阅一下这个话题cyber_channel echo /bridge_test/vehicle_state如果在终端上看到类似这样的输出说明整条接收链路已经打通VehicleState { speed_mps: 3.5 steering_angle_rad: 0.1 gear: 1 timestamp_ns: 1700000000000000000 }我习惯用发一帧看一轮的方式验证配合修改Python脚本里的数值每次打印的数字都跟着变化就能确认数据不是缓存或巧合。发送方向的验证也类似只是把监听方向调转你用cyber_channel往/apollo/localization/pose发模拟消息外部脚本用socket.bind((0.0.0.0, 8001))监听就能收到bridge转发出来的UDP内容。这组实验的要点是先用最小闭环把链路跑通再去接真设备。真设备往往有各种各样的问题如果把调试协议、验证链路、排查硬件三者叠在一起问题定位会非常痛苦。5. 实测中的坑MTU、序列化对齐与端口问题的排查链路理论挺好文档也不复杂但真正跑起来总有几个坑会反复击倒不熟悉网络细节的开发者。我把实测中遇到过的高频问题整理成排查思路希望你们遇到时可以按图索骥。5.1 大包被分片后接收端怎么处理外界最容易踩到的第一坑UDP数据报超过MTU导致IP层分片。常见的工控机网卡MTU是1500字节减去UDP首部的8字节和IP首部的20字节实际payload大约1472字节。如果你的proto消息体比较大例如一帧障碍物列表轻松超过这个值数据报就会被分片发送。分片带来的问题是只要其中一个分片丢了整个数据报在接收端会被丢弃哪怕其他分片都到齐了。这会让你的接收窗口看起来一跳一跳地丢数据而且丢的还是完整的大消息。排查时可以先看CPU网卡的中断统计确认有没有大量重组失败的包。解决方案按优先级排从源头控制消息体大小尽量让单帧payload小于1472字节。如果消息里有列表字段考虑拆成多条子消息发送在接收端合并。调大MTU。如果整个链路都是千兆网/万兆网内部环境没有经过公网设备可以在网卡上把MTU调到9000字节巨型帧这样单包payload上限大幅提升。但要注意交换机必须同样开启巨型帧支持否则能通速度反而更慢。在应用层做分包和重组。这是绕开MTU问题最彻底的办法把大消息切成长度不超过1400字节的小块每个块带消息ID和序号接收端收集完成再拼接。虽然实现稍微复杂但胜在可控。5.2 外部系统消息解析结果错但没报错第二种问题比较隐蔽bridge能收到外部UDP数据也不报错但解析出来的字段值完全对不上比如车速显示成好几亿、转向角是负数。究其原因绝大多数是外部系统用的proto定义和Apollo侧的proto定义不一致而且这种不一致不是字段名不一致而是字段编号对应关系不一致或者新增了字段导致消息体布局变化。这里需要重点强调protobuf的一个特性序列化后的二进制布局只跟内部字段编号有关跟你起的字段名毫无关系。假设外部设备认为speed_mps的字段编号是1内部Apollo却认为编号2才是speed_mps。那么外部在字段1里写入的3.5Apollo解析时只会看到一个莫名其妙的字段值而字段2在外部数据里根本不存在解析出来就是默认值0。这种问题用文本比较很难看出来。我排这种问题的标准动作外部系统发送一段完全已知内容的固定报文我在bridge端把这帧数据的原始hex打印出来然后用同样的proto在本地Python脚本里手动解析一遍逐步核对每个字段对应的字节位置。只要hex对得上、解析结果与发送值一致就说明两端编码兼容对不上就逐字节找差异。另外还有一个常见隐含点proto版本升级时新增字段老版本接收端本来应该忽略未知字段但如果跨版本时默认值语义变化也可能导致业务代码误判。强烈建议把proto文件纳入版本管理一旦改动立刻同步给所有对接方。5.3 端口绑定失败与防火墙拦截还有一类问题发生在Linux主机上bridge配置好之后日志里一堆bind: Address already in use或者Permission denied。前者通常是之前有另一个进程占用了同一个端口后者常见于绑定端口小于1024的情况——这类端口默认只有root才能bind。排查命令我一贯用sudo netstat -tunlp | grep 9400看是哪号进程占了端口进程是不是之前没杀干净的bridge残留。容器环境里尤其容易遇到你在容器外启动了一个占用端口的进程容器内又去bind同一个端口虽然是不同的网络命名空间可能不冲突但如果用了host网络模式就必然打架。防火墙问题我单独拎出来说是因为我曾经在某个测试环境里被“能发不能收”折磨了一个下午。外部设备能看到Apollo发来的UDP包但Apollo收不到外部设备发送的UDP包。后来发现是目标机防火墙的INPUT链拦住了目标端口的UDP流量。这里不是让你们跑去关防火墙而是提醒遇到单方向的UDP不通时先检查对端的监听状态和防火墙规则不要一开始就怀疑代码逻辑。# 检查端口是否在监听 sudo netstat -ulnp | grep 9400 # 查看防火墙是否有端口放行规则 sudo iptables -L -n | grep 9400UDP没有TCP那种SYN握手防火墙不拦的时候你不会看到任何“连接失败”的报错只是静静地丢包。所以这种问题不靠代码debug靠排查环境。5.4 时间戳和坐标系的隐形差异最后这个小点算是跨系统集成时的经验提醒。外部系统发来的数据里通常会带自己的时间戳有些设备用的是秒为单位有些用毫秒有些直接用系统启动后的毫秒数千奇百怪。如果你直接把外部时间戳无脑填进Apollo的消息头里可能导致平台内部的时间同步逻辑错乱。Apollo的消息头一般有timestamp_sec和lidar_timestamp等字段平台内部很多模块依赖时钟同步的一致性。我遇到过的案例外部设备发来的时间戳用的是设备自身启动后经过的秒数约只有几百到几千秒。bridge转发后规划模块判断这条消息的时延为负几百小时直接进入异常保护。解法很简单但必须做在bridge做时间戳转换统一改为当前系统时间或按平台约定的时钟源必要时做偏移校正。坐标系的问题同理GPS坐标、车身坐标系、相对坐标系外部设备往往各自为政。Bridge模块本身不管坐标系转换但你要在设计阶段就明确进来的是什么坐标系Apollo内部要求什么坐标系转换逻辑放在哪里做——是外部设备做还是bridge上做还是下游业务模块做。提前定好省得链路通了数据也对了业务上层却跑出一堆离谱的行驶轨迹。6. 写在最后的几点体会Bridge这类模块本身不难难的是它站在两个世界的交界处一边是Apollo内部严格的消息模型和CyberRT框架一边是外部世界五花八门的网络协议和数据习惯。实测中你会发现真正让链路稳定运行的往往不是那一两行收发代码而是你对外部设备数据习惯的理解深度包括包大小、发送频率、时间戳语义、是否有突发发送模式。我个人的建议是在正式接设备前先用Python写一个模拟端把外部设备可能发送的各种数据形态都演练一遍正常频率帧、突发密集帧、超大消息、甚至故意发的半截包看bridge的接收解析逻辑会不会崩会不会在残留缓冲区里越积越多。这类防御性的验证比在真车真设备上出了问题再返工成本低一个数量级。这篇先把单条UDP桥接通路讲透了。下一篇我会继续聊多通道的并发管理、自定义报文头设计以及丢失率统计和延迟测量这几种工程上更进阶的问题等我攒够新的实测素材再来填。 
长河君 · 2026/10/20 18:49:05 · 阅读 1.2k Apollo bridge UDP桥接：CyberRT与外部设备通信实战解析
1. bridge是干什么的UDP桥接在Apollo里的真实定位先从一个高频场景说起。很多团队在做自动驾驶系统集成的时候会遇到一个很尴尬的问题Apollo平台内部的模块之间用CyberRT通信话题Topic的定义、序列化方式、收发机制都是平台内部的规矩但外部设备——比如不带CyberRT的MCU板卡、工控机上的V2X盒子、自己写的仿真上位机——根本不认这套协议。它们唯一能统一理解的东西就是最基础的TCP/UDP网络包。于是我们就需要一座桥把CyberRT世界里的消息翻译成外部系统能收发的UDP数据反过来也一样。Apollo的bridge模块就是干这件事的。这里说的bridge是Apollo平台框架里独立的一个通信桥接模块专门负责把CyberRT话题和外部UDP报文相互转换。它在整个体系里的定位很像一个翻译官加邮差内部接CyberRT总线的发布订阅外部接一个UDP网络端点IP和端口中间只做最小限度的格式转换不负责业务逻辑也不做复杂的路由决策。因为模块本身很薄所以延迟小、资源占用低适合放在车载工控机上常驻运行。哪些人需要关注这个模块做车辆底盘接入的工程师车辆底盘控制器通常只提供CAN或者串口转以太网的接口你想把底盘状态车速、转向角、挡位送进Apollo的/chassis话题bridge一边帮你接收UDP数据包另一边帮你以CyberRT消息的形式发布出来。做V2X路侧通信或者车路协同的团队路侧设备发来的SPaT、RSM等信息很多就是自定义UDP协议需要桥接进平台内部话题。做仿真和测试平台开发的同学上位机要实时读取Apollo内部定位、规划结果又不想在外部系统里重新实现一整套CyberRT客户端直接开一个UDP端口让bridge把内部消息推出来。一句话概括bridge的价值它把Apollo内部的事和外部世界的事用UDP这条物理通道解耦了。没有它外部系统要接入Apollo就必须在目标机上装CyberRT环境、写同样的proto定义、处理发现机制这复杂度不是一般的高。有bridge外部只要懂socket编程就万事大吉。这一篇我重点讲清楚三件事模块配置怎么填、收发链路怎么走、实测会踩哪些坑。理解了这些你至少能搭出一个可以跑的UDP桥接通路后面再谈大规模多通道管理和可靠性优化。2. 模块怎么配置拆解一个Bridge节点的关键参数先说结论Bridge模块的配置并不神秘本质上就是声明一个内部话题、一组网络端点、一个消息协议。你搞清楚这几个参数的组合关系就能读懂绝大多数版本的配置。2.1 从一个典型配置说起Apollo里bridge模块的配置通常以bridge_conf.pb.txt的形式存在里面包含一到多个bridge节点定义。我基于平时见到的版本整理一个典型片段字段名在不同的Apollo版本里可能略有差异但逻辑是一样的bridge_senders { id: 1 proto_desc_file: /apollo/modules/localization/proto/localization.proto proto_msg_type: apollo.localization.LocalizationEstimate channel_name: /apollo/localization/pose output_ip: 192.168.1.100 output_port: 8001 bind_port: 0 } bridge_receivers { id: 2 proto_desc_file: /apollo/modules/canbus/proto/chassis.proto proto_msg_type: apollo.canbus.Chassis channel_name: /apollo/canbus/chassis input_ip: 192.168.1.101 input_port: 9000 bind_port: 9000 }左侧bridge_senders负责把Apollo内部消息往外发比如我要把定位结果LocalizationEstimate发给某个外部上位机目标地址是192.168.1.100:8001那么bridge会订阅/apollo/localization/pose话题收到消息后序列化成字节流用UDP发给目标IP和端口。右侧bridge_receivers负责从外部收UDP数据进来比如底盘控制板在192.168.1.101:9000持续发送UDP包bridge在这个端口上监听收到数据后按Chassis的定义反序列化然后以CyberRT消息形式发布到/apollo/canbus/chassis话题上。对了conf里还有接收方配置的channel_name不同版本的字段措辞不一样有的叫channel_name有的在receiver里直接写proto_msg_type对应的消息推送到统一话题总之你要记住的映射关系是网络包里的字节流 ↔ 某种proto消息类型 ↔ 一个CyberRT话题。2.2 proto描述文件最容易配错的地方我用了一个词proto_desc_file。这个配置指向一个.proto文件bridge靠它来解析消息的二进制布局。很多同学第一次配置时会想外部系统发来的数据格式不就是我自己定的吗为什么还要麻烦proto原因在于CyberRT的总线传输要求消息必须按照protobuf序列化后的二进制格式携带。也就是说外部设备发送UDP包的时候payload本身必须是一个已经用protobuf序列化好的二进制块。bridge收到之后借助proto描述文件把字节流解析成具体的消息类型再塞进CyberRT的Writer发布出去。这种做法有个很直接的好处数据体积小序列化/反序列化速度快。自动驾驶场景里一帧Chassis通常不超过一二百字节如果用JSON文本格式光键名就占了半天实时性会差很多。UDP本身是非可靠传输丢了还得重发包里放越多冗余数据丢包概率越高。不过要注意外部设备需要持有与Apollo侧完全一致的proto定义尤其注意字段编号而不是字段名。有人用Python的protobuf库在MCU侧生成消息时顺手改了字段顺序或者漏了几个可选字段结果bridge这边解析出来的数据和实际发送的对不上这种问题很难查因为不报错只是值错乱了。我一般会在配置好proto之后先打印一帧原始hex数据对比一下再上真链路。2.3 多个bridge节点怎么组织通道与端口规划实际工程项目往往不止一个话题要桥接。定位、底盘、规划轨迹、障碍物列表全都要和外设通信。你可以为每个话题单独开一个bridge节点端口依次排开也可以用同一个节点承载多个消息类型。我的经验是按“方向消息优先级”组织更合理而不是按“消息类型”硬切。比如接收方向只开一个端口9000外部设备所有数据都发到这个端口bridge根据消息头里的类型标识分发给不同的CyberRT话题发送方向同样用单一端口把多路消息轮流发出去。这样做的好处是外部设备只需要维护一条网络链路不需要针对每个话题记一串端口。代价是需要在业务代码里做一个轻量级的封装在每个UDP包头部加个自定义头比如4字节消息IDbridge收到后先读ID再决定用哪个proto解析。这个自定义分包逻辑CybeRT不关心纯粹是外部协议部分。如果不想自己写那开多个端口就是更省事的办法缺点是外部设备要维护多套socket连接、留意端口冲突。3. 数据通路的细节CyberRT和UDP互相转换时发生了什么配置看懂了下一步就得弄明白里面的数据究竟是怎么流动的。我在调bridge时发现很多人对这个过程的理解是“大概就是把消息打包成UDP发出去”这个理解没错但差了很多关键细节——现实场景中正是这些细节决定了整个链路的延迟和稳定程度。3.1 发送方向的三段式流水线发送方向一个消息从Apollo内部到达外部设备在bridge里走这样的流程订阅CyberRT话题bridge注册了一个Reader绑定比如/apollo/localization/pose话题平台内部的writer每发一帧数据这里就收到一个消息对象。序列化调用message.SerializeToString()方法把消息对象变成std::string或者字节缓冲区。protobuf序列化输出的是一段紧凑的二进制数据字段值按编号连续排布顺序跟字段定义的顺序无关虽然实践上差不多。UDP打包发送在序列化结果前面加一个4字节的报文长度头很多实现会用固定长度头加payload的方式方便接收端自适应解析然后用socket的sendto发给配置的目标IP和端口。如果你伸手介入过这个过程应该已经注意到一个点UDP的sendto是非阻塞的吗不是系统默认的socket在发送缓冲区满时会把进程卡住。在自动驾驶系统中如果外部设备的网络接收速度跟不上发送缓冲区一旦积压bridge线程会卡在sendto上进而拖累CyberRT的Reader回调——因为Reader的回调线程如果被阻塞后续消息就会排队整个Apollo内部的话题消费延迟都会拉高。遇到这种状况我常用的手段是给发送socket设置非阻塞模式或者干脆在bridge回调里把发送工作丢到一个独立线程池。不太建议简单地在线程里加锁然后死命发丢失和延迟一旦出现很难和问题根源对上号。3.2 接收方向的两个重要细节接收链路反过来的逻辑是外部设备发udp包到某个端口bridge的socket在循环中recvfrom解析出二进制再调用ParseFromString()拿到消息对象后用Writer发布到CyberRT话题。这里面我认为有两个容易忽略的细节第一收到的是一个包还是多个包UDP接收端的经典问题——如果外部设备在一瞬间连续发了好几个小报文你的应用层缓冲区一次recvfrom可能只取走一个数据报。剩余的数据报留在内核缓冲区里不会被自动拼接。所以接收循环里必须反复调用recvfrom直到缓冲区为空否则在高速数据流下会积压。第二帧边界要靠报文长度头去切。UDP虽然有报文边界但一次收到的包内容是否正好是一条完整消息呢不一定。尤其当你自己定义过自定义头、或者外部设备是分两次发送的消息时很容易收到半条内容。所以接收解析时必须维护一个上次没处理完的残留缓冲区比如我习惯的做法是先把收到的数据追加到残留缓冲区末尾然后不断尝试从缓冲区开头按固定头格式提取一条完整的消息提取成功就交给ParseFromString直到缓冲区长度不足一条完整消息为止。这样实现的接收逻辑对零星碎包、粘包都有很好的容忍度。3.3 为什么这个方案“够用”但别指望“完美”需要明确一点UDP桥接不等于可靠通信。你用bridge搭起来的是一个尽力而为的实时通道不是文件传输通道。自动驾驶中很多传感器数据比如定位、车速是以几十赫兹频率持续刷新的偶尔丢一帧对系统影响不大因为下一帧马上就到。此时用UDP换来的是微秒级的收发延迟和极简的网络握手这对控制系统是值得的。但如果你的场景要传的是规划轨迹的完整列表、地图片段、或者其他需要零丢失的数据那么UDP加bridge的方案就不合适了你应该考虑在应用层自己做确认重传或者干脆换到另一个通信机制。拿bridge去硬扛可靠传输只会把模块改得面目全非还未必性能达标。选型一开始就要心里有数。4. 实操跑通搭建一个最小可用的UDP桥接实验前面说得再多不如亲手把链路跑通一次。下面这组实验方法是我常用的不需要特别复杂的设备——一台装了Apollo的开发机、一台可以在同一网络里发包的电脑也可以是开发机自身回环就够了。4.1 实验目标我们要验证两件事外部UDP数据能进到Apollo内部的CyberRT话题里Apollo内部某个话题的数据能通过UDP发到外部监听程序里。为了让场景更直观我用一个简单的外部Python脚本模拟底盘控制板发送一条Chassis类型的消息到bridge同时在另一边监听bridge转发出来的定位话题。4.2 准备输入数据模型先确保你的编译环境里存在proto描述文件。以Chassis为例你可以直接复用Apollo里现有的chassis.proto。但为了让实验最小化我倾向于自己定义一个极简的proto文件减少依赖syntax proto2; package bridge_test; message VehicleState { optional double speed_mps 1; optional double steering_angle_rad 2; optional int32 gear 3; optional uint64 timestamp_ns 4; }注意字段编号后面Python端生成数据时要完全一致。把proto文件放到一个外部Python脚本可访问的路径用protoc命令生成vehicle_state_pb2.pyApollo侧的proto_desc_file就填同一个路径下的.proto文件位置。4.3 配置一个最小Receiver节点假设外部Python脚本往本机回环地址127.0.0.1:9400持续发送VehicleState的二进制数据。我只需要一个bridge_receiver配置bridge_receivers { id: 10 proto_desc_file: /tmp/bridge_test/vehicle_state.proto proto_msg_type: bridge_test.VehicleState channel_name: /bridge_test/vehicle_state input_ip: 127.0.0.1 input_port: 9400 bind_port: 9400 }这里用回环地址好处是调试方便不需要两台机器也不会受网卡配置干扰。把配置放到Apollo运行时加载bridge模块的正确路径下不同Apollo版本的加载方式不同常见的是通过modules/bridge/conf/下的配置然后以Cyber模块方式启动。4.4 外部发送端Python代码外部Python脚本只需要一个UDP socket。以下是核心片段用完全虚构的演示实现import socket import time import vehicle_state_pb2 sock socket.socket(socket.AF_INET, socket.SOCK_DGRAM) addr (127.0.0.1, 9400) msg vehicle_state_pb2.VehicleState() msg.speed_mps 3.5 msg.steering_angle_rad 0.1 msg.gear 1 msg.timestamp_ns int(time.time() * 1_000_000_000) payload msg.SerializeToString() # 可选如果你的bridge实现需要长度头这里再加一个 struct.pack(!I, len(payload)) sock.sendto(len(payload).to_bytes(4, byteorderbig) payload, addr)值得一提外部设备端如果用的是C、C或者Go核心操作也一样生成同样的proto对象、用同样的protobuf序列化即可只要保证编码后的字节流完全一致跨语言毫无障碍。4.5 验证CyberRT里能订阅到数据吗bridge模块启动之后我可以打开另一个终端用CyberRT自带的调试工具订阅一下这个话题cyber_channel echo /bridge_test/vehicle_state如果在终端上看到类似这样的输出说明整条接收链路已经打通VehicleState { speed_mps: 3.5 steering_angle_rad: 0.1 gear: 1 timestamp_ns: 1700000000000000000 }我习惯用发一帧看一轮的方式验证配合修改Python脚本里的数值每次打印的数字都跟着变化就能确认数据不是缓存或巧合。发送方向的验证也类似只是把监听方向调转你用cyber_channel往/apollo/localization/pose发模拟消息外部脚本用socket.bind((0.0.0.0, 8001))监听就能收到bridge转发出来的UDP内容。这组实验的要点是先用最小闭环把链路跑通再去接真设备。真设备往往有各种各样的问题如果把调试协议、验证链路、排查硬件三者叠在一起问题定位会非常痛苦。5. 实测中的坑MTU、序列化对齐与端口问题的排查链路理论挺好文档也不复杂但真正跑起来总有几个坑会反复击倒不熟悉网络细节的开发者。我把实测中遇到过的高频问题整理成排查思路希望你们遇到时可以按图索骥。5.1 大包被分片后接收端怎么处理外界最容易踩到的第一坑UDP数据报超过MTU导致IP层分片。常见的工控机网卡MTU是1500字节减去UDP首部的8字节和IP首部的20字节实际payload大约1472字节。如果你的proto消息体比较大例如一帧障碍物列表轻松超过这个值数据报就会被分片发送。分片带来的问题是只要其中一个分片丢了整个数据报在接收端会被丢弃哪怕其他分片都到齐了。这会让你的接收窗口看起来一跳一跳地丢数据而且丢的还是完整的大消息。排查时可以先看CPU网卡的中断统计确认有没有大量重组失败的包。解决方案按优先级排从源头控制消息体大小尽量让单帧payload小于1472字节。如果消息里有列表字段考虑拆成多条子消息发送在接收端合并。调大MTU。如果整个链路都是千兆网/万兆网内部环境没有经过公网设备可以在网卡上把MTU调到9000字节巨型帧这样单包payload上限大幅提升。但要注意交换机必须同样开启巨型帧支持否则能通速度反而更慢。在应用层做分包和重组。这是绕开MTU问题最彻底的办法把大消息切成长度不超过1400字节的小块每个块带消息ID和序号接收端收集完成再拼接。虽然实现稍微复杂但胜在可控。5.2 外部系统消息解析结果错但没报错第二种问题比较隐蔽bridge能收到外部UDP数据也不报错但解析出来的字段值完全对不上比如车速显示成好几亿、转向角是负数。究其原因绝大多数是外部系统用的proto定义和Apollo侧的proto定义不一致而且这种不一致不是字段名不一致而是字段编号对应关系不一致或者新增了字段导致消息体布局变化。这里需要重点强调protobuf的一个特性序列化后的二进制布局只跟内部字段编号有关跟你起的字段名毫无关系。假设外部设备认为speed_mps的字段编号是1内部Apollo却认为编号2才是speed_mps。那么外部在字段1里写入的3.5Apollo解析时只会看到一个莫名其妙的字段值而字段2在外部数据里根本不存在解析出来就是默认值0。这种问题用文本比较很难看出来。我排这种问题的标准动作外部系统发送一段完全已知内容的固定报文我在bridge端把这帧数据的原始hex打印出来然后用同样的proto在本地Python脚本里手动解析一遍逐步核对每个字段对应的字节位置。只要hex对得上、解析结果与发送值一致就说明两端编码兼容对不上就逐字节找差异。另外还有一个常见隐含点proto版本升级时新增字段老版本接收端本来应该忽略未知字段但如果跨版本时默认值语义变化也可能导致业务代码误判。强烈建议把proto文件纳入版本管理一旦改动立刻同步给所有对接方。5.3 端口绑定失败与防火墙拦截还有一类问题发生在Linux主机上bridge配置好之后日志里一堆bind: Address already in use或者Permission denied。前者通常是之前有另一个进程占用了同一个端口后者常见于绑定端口小于1024的情况——这类端口默认只有root才能bind。排查命令我一贯用sudo netstat -tunlp | grep 9400看是哪号进程占了端口进程是不是之前没杀干净的bridge残留。容器环境里尤其容易遇到你在容器外启动了一个占用端口的进程容器内又去bind同一个端口虽然是不同的网络命名空间可能不冲突但如果用了host网络模式就必然打架。防火墙问题我单独拎出来说是因为我曾经在某个测试环境里被“能发不能收”折磨了一个下午。外部设备能看到Apollo发来的UDP包但Apollo收不到外部设备发送的UDP包。后来发现是目标机防火墙的INPUT链拦住了目标端口的UDP流量。这里不是让你们跑去关防火墙而是提醒遇到单方向的UDP不通时先检查对端的监听状态和防火墙规则不要一开始就怀疑代码逻辑。# 检查端口是否在监听 sudo netstat -ulnp | grep 9400 # 查看防火墙是否有端口放行规则 sudo iptables -L -n | grep 9400UDP没有TCP那种SYN握手防火墙不拦的时候你不会看到任何“连接失败”的报错只是静静地丢包。所以这种问题不靠代码debug靠排查环境。5.4 时间戳和坐标系的隐形差异最后这个小点算是跨系统集成时的经验提醒。外部系统发来的数据里通常会带自己的时间戳有些设备用的是秒为单位有些用毫秒有些直接用系统启动后的毫秒数千奇百怪。如果你直接把外部时间戳无脑填进Apollo的消息头里可能导致平台内部的时间同步逻辑错乱。Apollo的消息头一般有timestamp_sec和lidar_timestamp等字段平台内部很多模块依赖时钟同步的一致性。我遇到过的案例外部设备发来的时间戳用的是设备自身启动后经过的秒数约只有几百到几千秒。bridge转发后规划模块判断这条消息的时延为负几百小时直接进入异常保护。解法很简单但必须做在bridge做时间戳转换统一改为当前系统时间或按平台约定的时钟源必要时做偏移校正。坐标系的问题同理GPS坐标、车身坐标系、相对坐标系外部设备往往各自为政。Bridge模块本身不管坐标系转换但你要在设计阶段就明确进来的是什么坐标系Apollo内部要求什么坐标系转换逻辑放在哪里做——是外部设备做还是bridge上做还是下游业务模块做。提前定好省得链路通了数据也对了业务上层却跑出一堆离谱的行驶轨迹。6. 写在最后的几点体会Bridge这类模块本身不难难的是它站在两个世界的交界处一边是Apollo内部严格的消息模型和CyberRT框架一边是外部世界五花八门的网络协议和数据习惯。实测中你会发现真正让链路稳定运行的往往不是那一两行收发代码而是你对外部设备数据习惯的理解深度包括包大小、发送频率、时间戳语义、是否有突发发送模式。我个人的建议是在正式接设备前先用Python写一个模拟端把外部设备可能发送的各种数据形态都演练一遍正常频率帧、突发密集帧、超大消息、甚至故意发的半截包看bridge的接收解析逻辑会不会崩会不会在残留缓冲区里越积越多。这类防御性的验证比在真车真设备上出了问题再返工成本低一个数量级。这篇先把单条UDP桥接通路讲透了。下一篇我会继续聊多通道的并发管理、自定义报文头设计以及丢失率统计和延迟测量这几种工程上更进阶的问题等我攒够新的实测素材再来填。