企业微信iPad协议：实例生命周期与零验证码恢复的技术细节

企业微信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，实现零验证码重登。恢复策略：

1. 先检测guid是否仍在线，若tcp连接存活，直接复用
2. 若已掉线，用上次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，满足高并发群控、会话存档等实时需求。