小米运动健康数据接入实战:逆向 API 与六个大坑

背景

做 LifeOS 的时候,想把小米手环的健康数据(步数、睡眠、心率)同步进来。小米官方没有开放健康数据的公开 API,只能走运动健康 App 的私有接口。这篇文章记录整个接入过程:认证流程怎么逆向出来的、签名怎么算的、以及一路上踩的六个坑。

一、认证体系:一场加密的接力赛

小米健康数据的接口保护层,比想象中厚。核心是四个东西的组合:

  • passToken:登录后拿到的长期令牌,是后续一切认证的起点
  • ssecurity:一个加密密钥,QR 扫码响应里会返回
  • location:跳转地址,跟随它才能换到 serviceToken
  • clientSign:nonce + ssecurity 的 SHA1 签名,是数据请求的”身份证”

整条链路走下来是这样:

1
2
passToken → 拼接 nonce → RC4 加密 nonce → 追加 clientSign
→ 携带 cookie 请求数据接口 → 返回加密数据 → RC4 解密

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
┌─ 前端设置页 ─────────────────────────────┐
│ QR 扫码按钮 → 弹窗显示二维码 │
│ → 自动保存凭据 → 显示同步状态/错误 │
└──────────────────────────────────────────┘
│ fetch
▼
┌─ API 层 ─────────────────────────────────┐
│ POST /api/health/xiaomi-qr 创建QR会话 │
│ POST /api/health/xiaomi-qr/poll 轮询扫码 │
│ POST /api/health/credentials 保存凭据 │
│ GET /api/health/sync 触发同步 │
│ GET /api/health/summary 读取汇总 │
└──────────────────────────────────────────┘
│
▼
┌─ 服务层 ─────────────────────────────────┐
│ MiHealthClient (mi-health.ts) │
│ - 认证: QR/passToken/password │
│ - 签名: RC4 + SHA1 + nonce │
│ - 数据: fetchDaily() 拉取并解析 │
└──────────────────────────────────────────┘
│
▼
┌─ 数据层 ─────────────────────────────────┐
│ HealthCredential (凭据, 含 ssecurity/ │
│ location/verifyUrl) │
│ HealthRecord (每日数据缓存) │
└──────────────────────────────────────────┘

四层结构:前端只管交互,API 层管协议,服务层管加密签名,数据层管持久化。边界清晰,出问题时定位也快。

五、安全设计

  1. 凭据保护:passToken 用 base64 存储(非明文;生产可升级为 AES 加密)
  2. 最小化:只读健康数据,不请求任何写权限
  3. 用户授权:所有操作需 LifeOS 登录态(requireUser)
  4. 验证 URL:70016 时返回验证 URL,引导用户完成授权,不暴露内部凭据
  5. 凭据不入库 git:.env / 数据库凭据绝不含小米账号密码

六、总结与后续方向

这次接入给我最大的感受:**逆向第三方私有接口,难点从来不在”能不能调通”,而在”怎么优雅地处理各种边界情况”**。70016 告诉你授权过期了、401 告诉你签名错了、静默的全 0 最可怕——因为它什么都没告诉你。

后续优化方向:

  1. 密码 + 短信验证码路径做成完整 UI(当前 QR 为主路径)
  2. serviceToken 定期自动刷新(token 有效期)
  3. 健康数据图表化展示(周/月趋势)
  4. 手环设备绑定引导(小米运动健康 App 内操作)

如果你也在接小米健康数据,希望这份记录能帮你少踩几个坑。尤其是 70016 和双重 base64 这两个,网上能找到的资料极少。