独立开发者笔记非官方文档。细节以 https://www.webrpc.cn/ 为准。前面写过选型、FAQ 和几段实战代码之后还是有人会问同一句更底层的话webrpc 到底在底下帮我做了什么我写的那几行 New、Login、OpenSession、SendData各自处在整条链路的哪一环这篇不贴大段可运行工程只把工作方式说清楚。弄明白之后再看 Go、Python、Java 示例会轻松很多。webrpc是面向 NAT 与复杂网络的跨平台 P2P 通信 SDK用 Token 标识设备登录后建立尽量直连的加密会话业务侧用接近 RPC 的方式收发数据或文件。官网https://www.webrpc.cn/先建立一张「分层图」可以粗分成三层身份层Token 密码回答「你是哪台设备」。连接层登录、打洞辅助、握手、会话、弱网重试、传输加密——这些主要在 SDK 里。应用层你自己的协议。JSON 也好PULL|文件名也好图片预览也好都只是回调里读到的字节再决定怎么回。很多人第一次接入会把三层缠在一起既怀疑动态库又改业务字符串。分开看问题会收敛得很快登录不上多半是身份或网络能登录却收不到多半是回调没接好会话有了但业务乱才是自己的协议问题。Token设备在网络里的「门牌」在 webrpc 里Token 更像端点 ID而不是传统 HTTP 里的用户登录票据。官网常见表述是一 Token 对应一台设备具体以控制台为准。所以最小验证几乎总是两个 Token家里的 NAS / 电脑一个手机或笔记本一个个人套餐里常见「一年两个 Token」就是为这种双端场景准备的。Token 本身不负责描述「相册权限」或「能不能删文件」——那是你应用层要做的事。SDK 负责的是持有这个门牌的进程能不能和另一个门牌建立会话。登录之后发生了什么调用New(token, password, permission)之后你通常会轮询LoginStatus。返回值变为非 0表示客户端已经处于可用状态。登录阶段SDK 需要和平台侧完成身份校验并进入后续可建会话的状态。对应用代码来说这里最重要的不是协议细节而是两个习惯不要写死「睡两秒一定成功」给登录加超时。登录成功前不要 OpenSession / SendData否则排错时现象会很飘忽。登录成功并不等于已经和对端连上。它只说明「这台设备作为 webrpc 客户端准备好了」。真正的端到端会话要等到OpenSession或对端连过来。回调端口数据不是「函数回调」而是本机 TCP这是 webrpc 里最容易让人愣一下的设计也是理解全局的关键。客户端就绪后SDK 会在本机监听一个 TCP 端口你通过GetReceivePort拿到端口号然后自己connect 127.0.0.1:port 循环读取二进制帧也就是说对端经 P2P 会话送来的数据最后会以「本机回环上的一串帧」交给你的进程。官网约定的帧头大致是sessionId : uint32 大端 type : uint8 2 数据流 1 文件流数据流后面跟长度 payload文件流后面跟文件名长度 文件名 数据长度 文件内容。为什么要绕一层本机 TCP而不是直接给你一个语言层 callback从接入体验看好处很实际C / Go / Python / Java 都能用同一套读帧逻辑业务线程和收包线程更好拆分和「SDK 是 Native 动态库」的形态更契合代价是你必须自己把读循环写对。端口写死、连错 IP、在读循环里同步塞超重的发送都会表现为「偶发收不到」。会话OpenSession 和 sessionId当 A 想主动找 BA 调用sessionId OpenSession(B的Token, permission)成功则得到一个会话 ID。之后无论SendData还是SendFile都要带上这个sessionId。对端回调读到的帧里也会带同一个会话维度的 ID这样你才知道「这是哪条会话上的数据」。如果OpenSession返回 0优先查B 是否已经登录Token 是否填反当前网络是否允许打洞成功官网也提醒过握手不是任何环境都 100%。应用层把「建连失败」当成正常分支处理比假装永远成功更重要。会话建立后链路在能力宣传上常见几点尽量 P2P 直连、传输加密、底层有弱网重试公开材料里也提到过约 200ms 量级握手、QUIC 传输等。这些是连接层的目标能力落到你的环境仍以实测为准。SendData 与 SendFile应用层真正开始的地方可以这么分工SendData指令、JSON、RPC 请求/响应、小文本SendFile图片、日志包、安装包、录像片段一个很典型的组合是手机SendData(PULL|photo.png)电脑在回调里解析请求电脑对同一sessionId调用SendFile(./photo.png)手机在type1文件帧里拿到字节再显示或落盘到这里你应该能看出来webrpc 并不理解PULL是什么。它只保证「会话上能把字节/文件送过去」。业务语义完全是你的。这也是它闻起来像 RPC 的原因你发出去对端处理再回包只是运输层换成了跨 NAT 的 P2P 会话而不是公网 IP 上的 HTTP/gRPC。把整条链路串成一句话如果只能记一段记这个Token 让设备可被找到登录让本机 SDK 就绪回调端口让你的进程能读到推送OpenSession 建立端到端会话SendData/SendFile 在会话上搬运应用数据。再对应到排错现象多半先看哪一层LoginStatus 一直为 0Token、平台库、网络Connection refused 回调端口是否来自 GetReceivePort、是否连 127.0.0.1OpenSession 为 0对端是否在线、Token、网络策略有会话但业务错乱你自己的帧解析/JSON/权限大图/大文件卡死是否阻塞了回调读循环、端上内存策略它刻意不替你做的事理解「怎么工作」同样包括理解边界它不是网盘不帮你管目录树、版本、秒传它不是会议 SDK不负责摄像头采集与浏览器音视频管线它不是完整 IAM细粒度业务权限要自己做它不是「保证全球任意网络永远连通」的魔法官网定位也很清楚把打洞、会话、加密传输收到 SDK 下面让应用团队把精力放回业务调用。个人 NAS、设备互联、私有传文件是它更对口的方向临时开 SSH 入口、纯会议产品各有更合适的工具。写给准备接入的人如果你明天开始写第一行代码我建议按这个顺序验证而不是反过来单端登录成功回调端口能稳定读到测试数据双端 OpenSession 成功一次 SendData 往返再加 SendFile 或 JSON 业务跳步的人最后往往在第三层业务里排查第一层 Token 写错。完整 API 说明、各语言示例和 SDK 下载都在官网控制台https://www.webrpc.cn/弄清工作方式之后选型文和实战文会更好读反过来也只有在真实网络里跑过一次会话这篇里的「回调」「sessionId」才不会只是名词。