小米运动健康数据接入实战:逆向 API 与六个大坑
小米运动健康数据接入实战:逆向 API 与六个大坑
背景
做 LifeOS 的时候,想把小米手环的健康数据(步数、睡眠、心率)同步进来。小米官方没有开放健康数据的公开 API,只能走运动健康 App 的私有接口。这篇文章记录整个接入过程:认证流程怎么逆向出来的、签名怎么算的、以及一路上踩的六个坑。
一、认证体系:一场加密的接力赛
小米健康数据的接口保护层,比想象中厚。核心是四个东西的组合:
- passToken:登录后拿到的长期令牌,是后续一切认证的起点
- ssecurity:一个加密密钥,QR 扫码响应里会返回
- location:跳转地址,跟随它才能换到 serviceToken
- clientSign:
nonce + ssecurity的 SHA1 签名,是数据请求的”身份证”
整条链路走下来是这样:
1 | passToken → 拼接 nonce → RC4 加密 nonce → 追加 clientSign |
RC4 是对称加密,nonce 是随机数,clientSign 保证请求不被篡改。这套组合拳说明小米在接口保护上是下了功夫的——不是简单加个 token 就完事。
二、三种登录方式对比
| 方式 | 流程 | 体验 |
|---|---|---|
| QR 扫码(推荐) | 服务器生成二维码 → 用户手机扫 → 扫码响应含 ssecurity+location → 服务器跟随拿 serviceToken | 需要扫码一次 |
| 密码 + 短信 | 密码登录 → 设备未信任 → 图形验证码 → 短信码 → 完成 | 需要图形码+短信码 |
| passToken 直接 | 浏览器拿 passToken → 服务器交换 | 需要先手动获取 |
项目最终采用 QR 扫码为主路径——用户只需要扫码一次,体验最好,而且扫码本身自带”设备授权”语义,能绕开异地登录验证。
三、六个大坑(每一个都是真金白银换来的)
坑 1:70016 异地登录安全验证(最坑)
- 现象:
serviceLogin返回code: 70016, desc: "登录验证失败",数据同步全 0。 - 根因:小米对新设备/新 IP 的首次登录强制安全验证。服务器 IP 从没登录过这个账号。
- 破解:无法纯技术绕过。需要用户浏览器打开验证 URL 完成授权(约 1 小时生效),或者走 QR 扫码——扫码即授权。
这是整个项目里最没有技术含量、却最折磨人的坑。它明确告诉了你:有些安全机制不是为技术设计的,是为信任设计的。
坑 2:错误被静默吞掉(假数据假象)
- 现象:同步返回
{"ok":true,"synced":30}但数据全 0。 - 根因:
Promise.allSettled+safe()把认证失败(rejected)静默转成空数组 → 全 0。 - 修复:核心请求(steps/calories/sleep)全失败时抛出真实错误,并保留 verifyUrl 等属性。
这个坑的教训是:**”假装成功”比”明确失败”危险一百倍**。全 0 的数据会让用户以为手环没戴,而不是认证出了问题。
坑 3:跟随 location 缺 clientSign → 401
- 现象:认证通过(无 70016)但数据 API 返回 401。
- 根因:跟随 location 拿 serviceToken 时缺少 clientSign 签名参数(
nonce + ssecurity的 SHA1)。 - 修复:完整实现 clientSign 计算并追加到 location URL。
坑 4:ssecurity 双重 base64 编码
- 现象:存储的 ssecurity 解码后是垃圾数据(24 字节异常短)。
- 根因:QR 响应的 ssecurity 已是 base64 字符串,存储时又做了一次
Buffer.from(s).toString("base64")→ 双重编码。 - 修复:ssecurity 与 location 直接存原始字符串,不做二次编码。
坑 5:Next.js 16 路由预渲染 + 保留路径
/api/health/qr路径 404(Next.js 保留路径)→ 改名xiaomi-qr。- GET 路由被静态预渲染(
x-nextjs-prerender:1)→ 轮询改用 POST 端点。
坑 6:Prisma client 滞后
- 新增字段后服务器报 “unknown argument” →
prisma generate必须在 schema 更新后执行。 - 部署脚本顺序:
db push→generate→restart。
四、系统架构
1 | ┌─ 前端设置页 ─────────────────────────────┐ |
四层结构:前端只管交互,API 层管协议,服务层管加密签名,数据层管持久化。边界清晰,出问题时定位也快。
五、安全设计
- 凭据保护:passToken 用 base64 存储(非明文;生产可升级为 AES 加密)
- 最小化:只读健康数据,不请求任何写权限
- 用户授权:所有操作需 LifeOS 登录态(requireUser)
- 验证 URL:70016 时返回验证 URL,引导用户完成授权,不暴露内部凭据
- 凭据不入库 git:.env / 数据库凭据绝不含小米账号密码
六、总结与后续方向
这次接入给我最大的感受:**逆向第三方私有接口,难点从来不在”能不能调通”,而在”怎么优雅地处理各种边界情况”**。70016 告诉你授权过期了、401 告诉你签名错了、静默的全 0 最可怕——因为它什么都没告诉你。
后续优化方向:
- 密码 + 短信验证码路径做成完整 UI(当前 QR 为主路径)
- serviceToken 定期自动刷新(token 有效期)
- 健康数据图表化展示(周/月趋势)
- 手环设备绑定引导(小米运动健康 App 内操作)
如果你也在接小米健康数据,希望这份记录能帮你少踩几个坑。尤其是 70016 和双重 base64 这两个,网上能找到的资料极少。
本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 咻咻咻小陈的空间!