企业微信iPad协议把“一台iPad”抽象为可编程的实例（Guid）。创建、登录、热恢复、销毁四个阶段全部收敛到一条HTTP通道，官方轮询15 s的延迟被压缩到毫秒级。下面给出在生产环境验证过的最小闭环。
一、创建实例
POST /client/createClient
核心字段只有三处：
• deviceName：设备昵称，用于后台拓扑展示
• customerParam：业务侧透传，建议把租户ID+环境标识写进去，方便灰度
• proxyUrl：socks5代理，登录阶段必须，可配置onlyProxyLogin=1，登录后流量直连，降低带宽成本
请求示例
curl -X POST http://8.140.194.207:9901/client/createClient \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${token}" \
-d '{
"deviceName": "srv-42",
"deviceType": 1,
"proxyUrl": "socks5://user:pass@10.0.0.42:1080",
"onlyProxyLogin": 1,
"customerParam": "tenant=acme&env=prod"
}'
成功返回
{
"code": 0,
"data": {
"guid": "0193483a-3f98-7f3e-b4d2-1f9a2b3c4d5e" },
"msg": "ok"
}
guid即实例全局唯一标识，后续所有登录、重连、销毁操作均围绕它展开。
二、首次登录与验证码规避
新guid首次登录会触发6位验证码；若用户已在另一iPad在线，服务端会下发“顶号”事件。为避免打扰，可使用“恢复实例”接口：
POST /client/recoverClient
仅需guid与上次登录成功的wxId，SDK内部携带本地cookie+key，实现零验证码重登。恢复策略：
- 先检测guid是否仍在线，若tcp连接存活，直接复用
- 若已掉线，用上次sessionKey换ticket，再走一次mmtls短握手，耗时<400 ms
代码片段
func Recover(ctx context.Context, guid string) error {
req := map[string]string{
"guid": guid}
return httputil.Post(ctx, "/client/recoverClient", req, nil)
}
三、实例保活与资源回收
sdk内部维护心跳map，若连续3次心跳超时（90 s）即标记为idle，10 min内无恢复则主动释放goroutine与fd。租户维度可设置maxIdle=100，防止机器连接数打满。
四、销毁实例
DELETE /client/{guid}
立即断开长连接并清除本地session，已落盘的消息文件同步上传S3，返回signedURL供审计。
五、异常场景汇总
• 401：token过期，需调用/tenant/token刷新
• 429：同一IP创实例频率>10次/min，触发流控
• 10013：guid不存在或已手动注销，需要重新create
通过把“实例”当做临时容器，企业微信iPad协议实现了设备级隔离与无状态横向扩展，单节点4C8G可稳定保持600个guid并发在线，事件推送P99延迟18 ms，满足高并发群控、会话存档等实时需求。
