从零接入 webrpc：按这份最小清单跑通双端，再写业务

我是 webrpc 作者。SDK、Token 和开发文档在 https://webrpc.cn。

选型看完了，下一步往往卡在同一处：我该按什么顺序写第一行代码？

Go、Python、Rust、Android 各有示例，但最小路径其实一样。这篇不堆完整工程，只给你一份 跨语言都适用的最小可行清单 ：两枚 Token、两端登录、接好本机回调、OpenSession 成功、对端回调里看到一小包 SendData。这四件事通了，再叠 JSON、文件或网盘；不通就不要先改业务字符串。

webrpc 是面向无公网 IP 的跨平台 P2P 通信 SDK：Token 标识设备，登录后建加密会话，再用 SendData / SendFile 收发。官网：https://webrpc.cn。

不想写代码、只想先体验传文件或个人网盘：用 File2File 一键注册，或再加 mywebdisk。下面清单面向 自己链 SDK 的人。

开始前准备什么

打开 webrpc.cn 控制台，准备 两枚 Token 及各自密码（个人试用常见一次两枚，名额与有效期以控制台为准）。
明确角色：
- 设备 A：被连端（家里电脑 / NAS / Agent）用 Token A
- 设备 B：主动拨号端（笔记本 / 手机 Client）用 Token B
下载 当前系统 + CPU 架构 对应的动态库（macOS / Windows / Linux amd64 / Linux arm64 等不要混）。
约定一条 认证口令（permission） ：A 在 New 时设定；B 在 OpenSession 时原样带上。空口令表示知道 Token 就能尝试连，长期在线设备建议用随机串。口令与 Token 密码不是一回事。

两台设备都要能访问互联网以完成握手；不要求公网 IP。验证阶段两边进程都开着。

最小清单（按顺序做）

第 1 步：两端创建客户端并登录

text 复制代码

handle = WebrpcClient_New(token, passwd, permission)
轮询 WebrpcClient_LoginStatus(handle) 直到成功（务必加超时）

登录成功只表示 本机 SDK 就绪，还没有和对端的会话。
登录成功前不要 OpenSession / SendData。
不要死循环空等；失败就查 Token、密码、库架构、本机外网。

第 2 步：接本机回调端口

text 复制代码

port = WebrpcClient_GetReceivePort(handle)
connect 127.0.0.1:port
循环读二进制帧

对端送来的数据，以本机 TCP 帧进入你的进程，不是 SDK 调你的函数指针。只连回环，不要连局域网 IP。

帧头约定（与开发文档一致）：

text 复制代码

sessionId : uint32 大端
type      : uint8
  2 = 数据流
  1 = 文件流

先把读循环跑稳，能打印 sessionId 和 type 再解析业务。

第 3 步：B 对 A 打开会话

在 B 上（A 已登录且回调在跑）：

text 复制代码

sessionId = WebrpcClient_OpenSession(handleB, TokenA, permissionA)

成功：得到 非 0 的 sessionId。
失败：返回 0。先查 A 是否在线、Token 是否填反、口令是否一致、网络是否允许握手。握手不能保证任意网络一次成功；把返回 0 写成正常分支，间隔重试。

第 4 步：发一小包，确认 A 的回调读到

在 B 上对刚才的 sessionId 调一次 SendData，载荷任意短字符串即可，例如 ping。timeOutMs 验证阶段可用 3000～5000：返回 1 通常表示已到对端业务回调。

在 A 的读循环里应看到对应数据流帧。看到了，最小路径就算通了。

第 5 步：再叠你自己的东西

连通之后才加：

JSON / Protobuf 业务 RPC
SendFile 传文件（大文件走文件接口，不要一次巨包 SendData）
网盘、预览、远控等产品逻辑

语言相关细节（ctypes 声明、CGO 链接、Android jniLibs）看控制台各语言示例；最小清单本身与语言无关。

怎样算最小跑通

四条同时满足：

A、B 的 LoginStatus 均为成功
两端回调读循环都在跑（127.0.0.1）
OpenSession 得到非 0 的 sessionId
B 的一次短 SendData，A 的回调能打印出内容

差一条，先补这一条，不要同时改协议字段和动态库路径。

清单上的常见坑

现象	先查
登录一直失败	Token / 密码、库是否对应当前平台、本机能否访问外网
有登录、无数据	回调是否连 `127.0.0.1`、端口是否来自 `GetReceivePort`
`OpenSession` 为 0	对端是否在线、Token 是否填反、口令是否一致、网络与重试
偶发连上又怪	弱网下把失败当分支；必要时重新 `OpenSession`，勿死抱旧会话
Python 返回值离谱	`argtypes` / `restype` 是否按 `uintptr`、`uint32` 声明

口令、超时乱序、三层通道（局域网 / P2P / 中转）等，连通之后再按需深入；第一天目标只是 双端跑通一小包。

不想写 SDK 时

传文件、聊天、远控：装 File2File，一键注册领 Token。
个人网盘：家里跑 mywebdisk-server，出门用 File2File 连。

通道仍是 webrpc；清单里的「登录 → 会话 → 收发」由客户端替你点完。

对照速查

最少需要几枚 Token？

双端验证要两枚：一枚 A，一枚 B。

必须有公网 IP 吗？

不需要。两端能上网以完成握手即可。

第一天要不要上 SendFile？

不必。先 SendData 一小包证明回调与会话；文件下一步再说。

回调为什么不是函数注入？

本机 TCP 推帧，便于多语言同一套读逻辑。只连 127.0.0.1。

OpenSession 返回 0 是 SDK 坏了吗？

多半是对端、Token、口令或网络。按层排查，保留重试。

控制台下载 SDK、管理 Token、查看套餐：https://webrpc.cn。按清单顺序勾完七步，少走很多冤枉路。