简介小米手环数据自动化导出工具主要面向希望深入查看Zepp Life数据库、对个人健康数据进行归档或取证分析的折腾型用户。通过对Zepp Life软件进行解包直接获取底层数据库配合多个Python脚本完成备份提取、数据解析与重建省去手动导出的繁琐流程。资源共7个文件包含6个Python脚本和1个带注释的JSON5样例文件压缩包仅8KB结构轻量适合快速上手和二次修改。数据脚本覆盖了日期数据提取、全天压力解析、备份获取与解包还原等典型环节JSON5文件则方便直观查看字段含义。目前已有11109人学习下载说明该方案受到不少手环玩家的关注。对想彻底掌握自己身体数据、用于医疗参考或法治取证的同学来说这份工具包能直接提供可运行的脚本与样例数据减少从零摸索的成本。1. 小米手环数据自动化导出工具把云端的数据定期搬回本地很多把小米手环戴了三四年的人最后都会遇到同一个问题想把自己这一年半载的心率、睡眠和步数导出来做健康分析打开 App 却发现只能手动选月份一次一次等邮件附件导出回来还是零散的 Excel。小米手环数据自动化导出工具做的事就是把这个搬数据的过程变成无人值守的定时任务——它替你登录云端账号按天拉取原始数据增量落进本地数据库第二天早上醒来 csv 已经躺在文件夹里。适合那些常年佩戴、想长期分析健康趋势或者怕哪天账号出问题数据全丢的人。接下来我会从数据链路讲起带你搭出一套能每天自动跑的导出管线。2. 数据从哪来手环同步链路与自动化导出方案选型2.1 手环数据在云端怎么存同步链路决定了导出对象手环不是 U 盘。手环 3、4、5 这些设备上的传感器每分每秒都在产生数据但设备本地只保留最近几天的摘要其余历史数据都在云端由手机 App 负责上传同步。数据大致是这样流动的手环通过蓝牙把心率、步数、睡眠分期推给手机 AppApp 再上传到你的账号下之后你在任意一台设备登录同一个账号都能看到完整历史曲线。这个链路决定了自动化导出的对象只能是云端而不是手腕上那个硬件。想直接读手环本地存储需要定制的固件和读取器对绝大多数人不现实。云端才是完整数据的存放地也是脚本每天要打交道的地方。理解这点有个实际好处当手环一直戴在手上但很久没开 App云端数据会存在缺口导出脚本再勤快也拉不到手环还没上传的内容这个问题后面会专门讲。2.2 官方手动导出为什么只适合救急Zepp Life 和老版本小米运动 App 里都有“数据导出”入口但它设计的目标是给用户做一次性数据留存不是给数据分析用的。常见限制包括可选择的时间范围有限通常一次最多勾选一个月要导两年的数据得反复操作二十多次导出结果通过邮件附件发送附件格式和字段在不同版本之间还不一致有的版本只给每日汇总不包含分钟级心率明细App 一旦退出登录旧的导出记录入口也不太好找。实际用下来你会发现官方导出更适合“哪天真想留个底”的救急场景不适合长期定时把数据收走。要把导出变成自动化流水线就得走另一条路让脚本自己调用 App 背后的云端接口。下面会讲怎么选这条路以及它的代价。2.3 自动化选型Zepp Life 私有接口与抓包路径手机 App 里展示的心率曲线、睡眠分阶段都是 App 向云端接口发请求拿到的。这条请求链路通常是 HTTPS JSON少数版本会启用 protobuf 压缩传输。常见的做法是在手机和电脑之间搭一个本地 HTTP 抓包环境比如 Fiddler、Charles 或 mitmproxy然后正常登录一次 App观察它调用了哪些接口、请求头里带了什么参数。整个过程只涉及你自己的账号和流量抓包的目的只是把 App 的请求结构看清拿到自己账号的凭证。抓到之后会发现结构并不复杂登录接口负责交付 token数据接口带上 token 和日期区间就能返回指定时间段的数据。相比申请厂商开放平台——小米和华米生态虽然有过开放平台但手环健康数据接口并不对个人开发者公开审批周期长、权限也有限——私有接口反而是更常见、更稳定的落地路径。它有几个特点要先接受接口没有 Service Level Agreement版本升级可能改字段请求频控不透明所以你的脚本必须留日志、做重试、保留原始返回不能指望它永远不变。方案对比可以看这张表方便你判断该投入哪种路线路线数据完整度自动化程度维护成本适合场景官方邮件导出部分汇总手动低一次性留底App 私有接口抓取高分钟级明细高中需随版本微调长期定时备份与分析手机本地数据库直读高但依赖本机低高碎片化严重临时取证不适合长期后端脚本选私有接口路线时接口域名和路径在不同 App 版本间会变化抓包看清后在脚本里单独抽出一个配置项维护不要几十处硬编码。下面进入实现我会用一个最小可运行的骨架把整条链路串起来。3. 从登录到落盘搭出第一个能跑的数据导出脚本3.1 环境与配置准备拿到自己的账号凭证开始写代码前先准备环境。Python 3.9 以上安装requests、pyyamlpandas 后面按需再装。抓包得到的凭证不要直接写死在代码里放到config.yaml一是避免改脚本二是分享代码时不会把账号密码带出去。我先给一份初始配置字段含义在下面说明account: username: your_phone_or_email password: country_code: 86 device: device_id: # 留空登录后可自动发现 api: base_url: https://your-captured-api-host access_token: 从抓包里复制的token token_type: Bearer export: data_dir: ./export db_path: ./export/miband_data.db timezone: Asia/Shanghai这里有几个点要解释。password故意留空如果抓到的 token 还有效脚本不必要做登录请求token 失效时再临时填入触发登录续期。token_type决定请求头怎么拼有的接口要求Authorization: Bearer token有的直接要token: token字段这以抓包看到的请求头为准。timezone字段后面有大作用别删很多导出数据的日期错位就是时区没设对。抓包时你要重点记录三样东西登录接口的完整请求体和响应体、数据接口的路径、请求头里的User-Agent和app_version。抓包工具里可以直接复制为 curl 或 Python 请求格式复制出来后先人工核对字段名不要盲信工具转换。3.2 登录接口换取 token 的最小请求老版本小米运动 App 的登录接口通常走账号密码密码有的版本做 MD5有的做 RSA不同时期不一样。下面的函数是一个最小骨架用注释标注容易变化的地方import hashlib import requests def login(username: str, password: str, country_code: str, base_url: str): # 部分版本要求密码先做加密传输MD5/RSA 以抓包为准 pwd_hash hashlib.md5(password.encode(utf-8)).hexdigest() session requests.Session() payload { username: username, password: pwd_hash, country_code: country_code, } headers { User-Agent: MIBand/5.2.3 (Android), app_version: 5.2.3, lang: zh-CN, } resp session.post( f{base_url}/v1/client/login, jsonpayload, headersheaders, timeout10, ) resp.raise_for_status() data resp.json().get(data, {}) token data.get(token) or data.get(access_token) user_id data.get(user_id) return token, user_id逻辑说明登录用的Session要保留因为后续请求可能依赖 cookie 会话响应结构里 token 字段在不同版本叫法不同所以写了or来兜底。参数说明timeout10是连接超时登录接口慢时后端会返回 5xx这时要重试而不是继续app_version要和你抓包时的版本一致有些老接口会校验它随便填可能被拒。登录成功后把新 token 和 user_id 写回config.yaml下次启动先检查 token 是否过期不要每跑一次就登录一次。新版 App 如果改成 OAuth 授权流程账号密码登录可能失效常见做法是抓包拿 refresh_token再用它刷新出短期 access_token。这个流程差别较大遇到再单独处理。3.3 数据接口拉取心率、睡眠、步数的请求参数与解析登录接口拿到凭证后核心就是按日期拉数。下面函数演示拉某一天三类数据接口路径以抓包结果为准这里用可替换的fitness路径做示例import datetime import requests def fetch_daily_data(api_cfg, user_id, target_date): 拉取指定日期的步数、心率和睡眠数据 target_date: datetime.date 对象 headers { Authorization: fBearer {api_cfg[access_token]}, app_version: 5.2.3, lang: zh-CN, } params { user_id: user_id, date_from: target_date.strftime(%Y-%m-%d), date_to: target_date.strftime(%Y-%m-%d), } session requests.Session() steps session.get( f{api_cfg[base_url]}/v1/fitness/steps, paramsparams, headersheaders, timeout10, ).json() heart_rate session.get( f{api_cfg[base_url]}/v1/fitness/heart_rate, paramsparams, headersheaders, timeout10, ).json() sleep session.get( f{api_cfg[base_url]}/v1/fitness/sleep, paramsparams, headersheaders, timeout10, ).json() return { date: target_date.isoformat(), steps: steps, heart_rate: heart_rate, sleep: sleep, }逻辑说明按天查三个接口分别返回每天汇总、分钟级心率和睡眠分期结构。链式请求之间加了自然串行没有并发这是为了不给服务端造成瞬时压力。参数说明date_from和date_to都传同一个日期格式是YYYY-MM-DDuser_id必须和 token 属于同一个账号混用会得到空数据或 401heart_rate接口返回的通常是每分钟一个值一天 1440 个点缺测位置可能是 0解析时要把 0 当成无数据不能当成真实心率。这里有个容易翻车的细节如果响应拿回来是一堆乱码而且响应头Content-Type是application/x-protobuf之类说明这个版本启用了 protobufresponse.json()会直接报错。遇到这种情况先看抓包里响应解码是否正常再找对应的.proto定义反序列化。多数老设备与 Zepp Life 的组合仍然是 JSON但新版本多遇到 protobuf脚本需要为这两种情况各写一个解析分支。请求频率上我是这样控制的批量拉日期时循环里每个请求之间time.sleep(0.3)一天三个接口就是约一秒。三天以上的批量任务避免并发串行跑几分钟完全可以接受没必要拿账号去试探频控阈值。3.4 持久化按日期写 CSV顺手入库 SQLite数据拉下来不落盘等于白跑。落盘方案我一般选 SQLite 为主库、CSV 做交换格式因为增量导出会重复跑同一个日期SQLite 的INSERT OR REPLACE天然适合去重。先建一张汇总表保留一份完整原始 JSON 备查import json import sqlite3 def save_to_db(raw, db_path): conn sqlite3.connect(db_path) conn.execute( CREATE TABLE IF NOT EXISTS daily_summary ( date TEXT PRIMARY KEY, steps INT, total_sleep_minutes INT, deep_sleep_minutes INT, avg_heart_rate INT, raw_json TEXT ) ) summary extract_summary(raw) conn.execute( INSERT OR REPLACE INTO daily_summary (date, steps, total_sleep_minutes, deep_sleep_minutes, avg_heart_rate, raw_json) VALUES (?,?,?,?,?,?), (raw[date], summary[steps], summary[total_sleep], summary[deep_sleep], summary[avg_hr], json.dumps(raw, ensure_asciiFalse)), ) conn.commit() conn.close() def extract_summary(raw): # 汇总逻辑按真实字段名解析这里只做占位 return { steps: 0, total_sleep: 0, deep_sleep: 0, avg_hr: 0, }逻辑说明raw_json保存完整原始返回之后如果发现解析漏了字段不需要重新请求直接从库里捞原始数据重新解析就行这是给自己留的后悔药。参数说明date TEXT PRIMARY KEY意味着同一天只会保留一份记录配合INSERT OR REPLACE重跑不会产生重复行。extract_summary在这里是占位你需要按实际返回字段提取步数、睡眠总时长和深睡时长。CSV 导出可以和 SQLite 并存适合直接丢进 Excel 或后续用 pandas 分析。常见做法是在每次同步完成后把近一周的daily_summary导出成一个daily.csv列名用英文小写下划线避免中文编码问题。到这一步脚本从登录到落盘的最小闭环已经通了。4. 让导出自己跑增量同步、定时调度与失败重试4.1 增量窗口设计从“今天”往回推两天脚本跑通之后下一步是让它自动循环。全量重导历史记录问题很大天数多、请求多、容易被限流重复数据还要清理。增量同步的思路是维护一个last_sync.json记录上次同步到的日期下次从“上次日期往前推两天”开始导到昨天为止。为什么要往前推两天因为手环的数据同步不是实时的。很多人睡前戴上早晨起来直接出门没有打开 App手环那一夜的缓存还没上传还有人加班到凌晨第二天的数据中午才同步到云端。往前推两天是给云端留缓冲窗口配合INSERT OR REPLACE重复拉取不会产生脏数据。首次运行没有历史记录可以按需求回退 90 天或 365 天脚本写法如下import json from datetime import date, timedelta from pathlib import Path def next_sync_window(last_sync_file: Path, today: date): if last_sync_file.exists(): last_date date.fromisoformat( json.loads(last_sync_file.read_text())[last_sync_date] ) else: last_date today - timedelta(days90) # 首次运行回退90天 start last_date - timedelta(days2) # 补前端两天的迟滞数据 end today - timedelta(days1) # 昨天是最近完整的一天 return start, end def mark_synced(last_sync_file: Path, end: date): last_sync_file.write_text( json.dumps({last_sync_date: end.isoformat()}) )逻辑说明窗口是闭区间每次从start循环到end跑完把last_sync_date更新为end。下次窗口自动从end - 2开始意味着最近三天会被重复拉一次。这个重复是故意的不是浪费它补的是“手环还没同步完”的数据。参数说明回退天数 90 和缓冲天数 2 都是经验值。刚上手想看更久历史把 90 改成 365如果你每天两次开 App习惯良好缓冲天数可以缩成 1但没必要多拉三天的成本很低。4.2 定时调度cron 和任务计划怎么定时间点定时任务不是随便设的核心约束是数据完整性。很多人第一次设凌晨 2 点跑结果睡眠数据老是缺因为夜里手环上传依赖手机 App 在后台活跃夜里 App 大概率没在工作。更实用的做法是每天跑两次早上 8 点补昨夜睡眠晚上 9 点补白天心率。窗口本身有两天缓冲两次调度即使重复拉同一批日期数据也会被幂等覆盖不会重复。Linux 或 NAS 上crontab 直接加两行# 每天 08:00 和 21:00 各跑一次增量导出 0 8 * * * cd /opt/miband-exporter /usr/bin/python3 export_daily.py logs/export.log 21 0 21 * * * cd /opt/miband-exporter /usr/bin/python3 export_daily.py logs/export.log 21Windows 上用任务计划程序或 schtasks 注册一个每日任务命令如下schtasks /Create /TN MibandExport /SC DAILY /ST 08:00 /TR cmd /c cd C:\miband-exporter python export_daily.py logs\export.log 21参数说明 logs/export.log 21必须保留自动化脚本挂掉时没有任何界面提示只能靠日志定位问题日志建议按月份拆分比如logs/export-202506.log避免单文件涨到几十 MB。cron 里的 python 路径要确认很多环境默认 python 不在/usr/bin/python3可以先which python3查一下。如果你把脚本跑在路由器或 NAS 上还要注意设备睡眠策略别让任务在休眠期间被跳过。4.3 失败重试与限流参数怎么调才不伤账号自动化跑起来后失败是常态关键是处理方式要对。请求返回常见状态码里401 表示 token 失效重试没用要触发重新登录429 是限流要退避等待5xx 是服务端临时问题可以重试超时是网络波动也可以重试。不同错误要区别对待不能一把梭。指数退避是最常见的重试策略我给一个可直接用的装饰器import time import requests from functools import wraps def retry(max_attempts4, base_delay2): def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_attempts): try: return func(*args, **kwargs) except requests.HTTPError as e: status e.response.status_code if status 401: raise # token失效重试没有意义交给上层续期 if attempt max_attempts - 1: raise # 已经最后一次直接暴露问题 delay base_delay * (2 ** attempt) # 2s, 4s, 8s time.sleep(delay) return None return wrapper return decorator逻辑说明指数退避的核心是让服务端有恢复时间不是快速重试轰炸。base_delay2三次重试分别等 2 秒、4 秒、8 秒总计约 14 秒这个量级对日志任务完全够用。参数说明max_attempts建议不超过 4超过之后问题大概率不是瞬时抖动而是账号或网络层面的故障继续重试只会恶化限流。429 响应如果带Retry-After头优先按它的秒数等待这个字段是服务端明确告诉你的冷却时间比指数退避更精准没有这个头再走退避。日常拉数时并发也要控制住。串行请求加 0.3 秒间隔已经能避开大部分限流如果做并发并发数控制在 2 以内并且单日请求总量别超过几百次。连续三次 429 时停止当天任务并写一条告警日志不要无限重试。IP 被限后通常几小时后自动解开这时候改 User-Agent 重登没有实际帮助老老实实等冷却更靠谱。5. 避坑自动导出跑半年后最容易翻车的五个点这一章是血泪经验汇总。工具跑起来前两周通常风平浪静跑满一两个月各种边界问题才会陆续浮出来。列出的每条都按“现象、原因、解决”讲你在自己的脚本里提前布好防线。5.1 token 失效导致进程直接报 401现象某天开始日志里全是 401 Unauthorized手动打开 App 却发现账号完全正常数据也能看。原因新版本签发的 token 有效期短脚本是硬编码 token过期后没有走登录流程也可能因为你在手机上登录了新设备服务端把旧会话踢掉了。解决给请求层加一个钩子——遇到 401 不直接失败先调用登录接口换新 token写回配置再重发原请求同时把 token 的获取时间记在配置里如果 token 有效期已知提前一周主动刷新。要特别注意被踢下线是常态化事件不是异常续期逻辑必须做成自动的不能靠手工改配置。5.2 时区错位睡眠数据跑到前一天现象导出的睡眠记录里入睡时间总是比 App 上显示早 8 小时或者凌晨 0 点到 6 点的数据挂在了前一天的字段里。原因云端返回的时间戳是 UTC 毫秒值脚本直接用了datetime.utcfromtimestamp解析而 App 展示时按 Asia/Shanghai 换算过两边差一个时区日期自然错位。解决统一在配置里写死timezone: Asia/Shanghai解析时间戳时先转东八区再取日期。这里补一个转换示例from datetime import datetime, timezone, timedelta tz timezone(timedelta(hours8)) local_dt datetime.fromtimestamp(ts / 1000, tztz) # ts 单位是毫秒 local_date local_dt.strftime(%Y-%m-%d)注意时间戳单位的坑。有的接口返回秒10 位有的返回毫秒13 位直接用错会差 1000 倍。我习惯在解析函数入口打印一次首条时间戳人工确认单位后再批量处理。导出文件的命名、数据库里的date字段都要按本地日期生成不能按 UTC 生成。5.3 手环没同步完成导致当天数据缺段现象早上 8 点任务跑完晚上打开 App发现昨晚的睡眠分期齐全但导出的 SQLite 里少了两段深睡。原因手环数据上传依赖手机 App 在后台工作。很多人晚上戴着睡早上出门没开过 App手环缓存还没上传云端自然没有那段数据脚本再准时也拉不到。解决每天跑两次以上第二次放在晚上 9 点前后这时候白天数据早已同步增量窗口往回推两天让漏掉的数据在第二次跑时被覆盖补齐。如果发现某个日期反复缺同一段记一份“缺失数据清单”字段包含日期、缺失类型、首次发现时间连续三天仍缺就手动开一次 App 确认手环有没有正常连接。5.4 请求太频繁被限流429 与 IP 封禁的界线现象脚本第一次跑正常几分钟后第二次跑就开始返回 429继续重试几次直接超时。原因没有限速批量日期循环里请求一股脑全打出去家里宽带出口是共享 IP厂商的防护阈值又比较低瞬时请求量一高就被限。解决批量日期之间串行请求每请求间隔 0.3 秒重试时优先尊重Retry-After响应头连续三次 429 就停止当天任务并告警不要无限重试。判断是否被临时封禁看同一 IP 请求其他接口是否也超时即可超时说明到了 IP 级限制这时候只能等几小时自动恢复改 User-Agent 重登作用不大。5.5 密码明文存储与脚本泄露风险现象config.yaml里直接写着账号密码把代码目录同步到网盘或提交到 git 仓库后账号出现异地登录提醒。原因工具越方便越容易忽视安全。私有接口虽然没有公开文档但它同样吃账号权限一旦凭证泄露等于把健康数据整个交出去。解决密码改用环境变量或系统钥匙串读取配置文件里只放 tokentoken 失效需重新登录时临时手动输入密码结束后清空。git 仓库用.gitignore把config.yaml、logs/、export/全部挡在提交之外建议再定期轮换账号密码尤其是部署在共享服务器上的情况。6. 验证导出的数据对不对再把它接进自己的分析流程6.1 三分钟交叉验证法拿 App 数字对账自动化工具最怕的不是报错而是报“成功”但数据是错的。每次跑完抽一天数据和 App 显示的数字对一遍。对账指标选三个就够总步数、睡眠总时长、平均心率。App 展示的是“本地日期 0 点到 24 点”的统计脚本汇总时也按同一口径两边才对得上。抽检可以写成一个小函数def verify_date(target_date): summary load_summary(target_date) # 从SQLite读 expected {steps: 8246, sleep_minutes: 421} # 手输App里看到的数字 print(steps diff:, summary[steps] - expected[steps]) print(sleep diff:, summary[total_sleep_minutes] - expected[sleep_minutes])对不上时按顺序排查先看时区字段有没有统一再看当天手环是否同步完整最后确认原始 JSON 解析字段是否选错。不要拿手环屏幕显示的数去对手环显示的是设备本地缓存和云端不一定同时更新要以手机 App 里看到的云端数据为准。6.2 进阶把导出数据接进自己的健康看板数据进来之后日常分析就顺理成章。SQLite 里有了按天汇总可以直接查近两周的深睡占比看看规律SELECT date, total_sleep_minutes, deep_sleep_minutes, ROUND(deep_sleep_minutes * 100.0 / total_sleep_minutes, 1) AS deep_rate FROM daily_summary ORDER BY date DESC LIMIT 14;字段名按你自己的表结构调整深睡占比如果长期低于 15%值得留意生活习惯。想做更复杂的分析把daily.csv丢给 pandas 或任何可视化工具都行分钟级心率还能做夜间心率分布曲线观察静息心率随疲劳度的变化。如果你的目标是长期积累SQLite 里再按月份建视图会更方便但不要为了分析方便牺牲增量同步那套逻辑——它是数据质量的底线。我最早跑这个工具时以为数据拉下来就结束了结果第三天对账发现步数少了三千排查到凌晨才发现是时区问题。那之后我在所有日期处理的地方统一用 Asia/Shanghai并把中间结果和原始 JSON 都保留下来半年多再没丢过数。把数据自动化拿回自己手里这件事值得投入一套干净、可验证的管线希望帮到你。本文还有配套的精品资源点击获取
简介小米手环数据自动化导出工具主要面向希望深入查看Zepp Life数据库、对个人健康数据进行归档或取证分析的折腾型用户。通过对Zepp Life软件进行解包直接获取底层数据库配合多个Python脚本完成备份提取、数据解析与重建省去手动导出的繁琐流程。资源共7个文件包含6个Python脚本和1个带注释的JSON5样例文件压缩包仅8KB结构轻量适合快速上手和二次修改。数据脚本覆盖了日期数据提取、全天压力解析、备份获取与解包还原等典型环节JSON5文件则方便直观查看字段含义。目前已有11109人学习下载说明该方案受到不少手环玩家的关注。对想彻底掌握自己身体数据、用于医疗参考或法治取证的同学来说这份工具包能直接提供可运行的脚本与样例数据减少从零摸索的成本。1. 小米手环数据自动化导出工具把云端的数据定期搬回本地很多把小米手环戴了三四年的人最后都会遇到同一个问题想把自己这一年半载的心率、睡眠和步数导出来做健康分析打开 App 却发现只能手动选月份一次一次等邮件附件导出回来还是零散的 Excel。小米手环数据自动化导出工具做的事就是把这个搬数据的过程变成无人值守的定时任务——它替你登录云端账号按天拉取原始数据增量落进本地数据库第二天早上醒来 csv 已经躺在文件夹里。适合那些常年佩戴、想长期分析健康趋势或者怕哪天账号出问题数据全丢的人。接下来我会从数据链路讲起带你搭出一套能每天自动跑的导出管线。2. 数据从哪来手环同步链路与自动化导出方案选型2.1 手环数据在云端怎么存同步链路决定了导出对象手环不是 U 盘。手环 3、4、5 这些设备上的传感器每分每秒都在产生数据但设备本地只保留最近几天的摘要其余历史数据都在云端由手机 App 负责上传同步。数据大致是这样流动的手环通过蓝牙把心率、步数、睡眠分期推给手机 AppApp 再上传到你的账号下之后你在任意一台设备登录同一个账号都能看到完整历史曲线。这个链路决定了自动化导出的对象只能是云端而不是手腕上那个硬件。想直接读手环本地存储需要定制的固件和读取器对绝大多数人不现实。云端才是完整数据的存放地也是脚本每天要打交道的地方。理解这点有个实际好处当手环一直戴在手上但很久没开 App云端数据会存在缺口导出脚本再勤快也拉不到手环还没上传的内容这个问题后面会专门讲。2.2 官方手动导出为什么只适合救急Zepp Life 和老版本小米运动 App 里都有“数据导出”入口但它设计的目标是给用户做一次性数据留存不是给数据分析用的。常见限制包括可选择的时间范围有限通常一次最多勾选一个月要导两年的数据得反复操作二十多次导出结果通过邮件附件发送附件格式和字段在不同版本之间还不一致有的版本只给每日汇总不包含分钟级心率明细App 一旦退出登录旧的导出记录入口也不太好找。实际用下来你会发现官方导出更适合“哪天真想留个底”的救急场景不适合长期定时把数据收走。要把导出变成自动化流水线就得走另一条路让脚本自己调用 App 背后的云端接口。下面会讲怎么选这条路以及它的代价。2.3 自动化选型Zepp Life 私有接口与抓包路径手机 App 里展示的心率曲线、睡眠分阶段都是 App 向云端接口发请求拿到的。这条请求链路通常是 HTTPS JSON少数版本会启用 protobuf 压缩传输。常见的做法是在手机和电脑之间搭一个本地 HTTP 抓包环境比如 Fiddler、Charles 或 mitmproxy然后正常登录一次 App观察它调用了哪些接口、请求头里带了什么参数。整个过程只涉及你自己的账号和流量抓包的目的只是把 App 的请求结构看清拿到自己账号的凭证。抓到之后会发现结构并不复杂登录接口负责交付 token数据接口带上 token 和日期区间就能返回指定时间段的数据。相比申请厂商开放平台——小米和华米生态虽然有过开放平台但手环健康数据接口并不对个人开发者公开审批周期长、权限也有限——私有接口反而是更常见、更稳定的落地路径。它有几个特点要先接受接口没有 Service Level Agreement版本升级可能改字段请求频控不透明所以你的脚本必须留日志、做重试、保留原始返回不能指望它永远不变。方案对比可以看这张表方便你判断该投入哪种路线路线数据完整度自动化程度维护成本适合场景官方邮件导出部分汇总手动低一次性留底App 私有接口抓取高分钟级明细高中需随版本微调长期定时备份与分析手机本地数据库直读高但依赖本机低高碎片化严重临时取证不适合长期后端脚本选私有接口路线时接口域名和路径在不同 App 版本间会变化抓包看清后在脚本里单独抽出一个配置项维护不要几十处硬编码。下面进入实现我会用一个最小可运行的骨架把整条链路串起来。3. 从登录到落盘搭出第一个能跑的数据导出脚本3.1 环境与配置准备拿到自己的账号凭证开始写代码前先准备环境。Python 3.9 以上安装requests、pyyamlpandas 后面按需再装。抓包得到的凭证不要直接写死在代码里放到config.yaml一是避免改脚本二是分享代码时不会把账号密码带出去。我先给一份初始配置字段含义在下面说明account: username: your_phone_or_email password: country_code: 86 device: device_id: # 留空登录后可自动发现 api: base_url: https://your-captured-api-host access_token: 从抓包里复制的token token_type: Bearer export: data_dir: ./export db_path: ./export/miband_data.db timezone: Asia/Shanghai这里有几个点要解释。password故意留空如果抓到的 token 还有效脚本不必要做登录请求token 失效时再临时填入触发登录续期。token_type决定请求头怎么拼有的接口要求Authorization: Bearer token有的直接要token: token字段这以抓包看到的请求头为准。timezone字段后面有大作用别删很多导出数据的日期错位就是时区没设对。抓包时你要重点记录三样东西登录接口的完整请求体和响应体、数据接口的路径、请求头里的User-Agent和app_version。抓包工具里可以直接复制为 curl 或 Python 请求格式复制出来后先人工核对字段名不要盲信工具转换。3.2 登录接口换取 token 的最小请求老版本小米运动 App 的登录接口通常走账号密码密码有的版本做 MD5有的做 RSA不同时期不一样。下面的函数是一个最小骨架用注释标注容易变化的地方import hashlib import requests def login(username: str, password: str, country_code: str, base_url: str): # 部分版本要求密码先做加密传输MD5/RSA 以抓包为准 pwd_hash hashlib.md5(password.encode(utf-8)).hexdigest() session requests.Session() payload { username: username, password: pwd_hash, country_code: country_code, } headers { User-Agent: MIBand/5.2.3 (Android), app_version: 5.2.3, lang: zh-CN, } resp session.post( f{base_url}/v1/client/login, jsonpayload, headersheaders, timeout10, ) resp.raise_for_status() data resp.json().get(data, {}) token data.get(token) or data.get(access_token) user_id data.get(user_id) return token, user_id逻辑说明登录用的Session要保留因为后续请求可能依赖 cookie 会话响应结构里 token 字段在不同版本叫法不同所以写了or来兜底。参数说明timeout10是连接超时登录接口慢时后端会返回 5xx这时要重试而不是继续app_version要和你抓包时的版本一致有些老接口会校验它随便填可能被拒。登录成功后把新 token 和 user_id 写回config.yaml下次启动先检查 token 是否过期不要每跑一次就登录一次。新版 App 如果改成 OAuth 授权流程账号密码登录可能失效常见做法是抓包拿 refresh_token再用它刷新出短期 access_token。这个流程差别较大遇到再单独处理。3.3 数据接口拉取心率、睡眠、步数的请求参数与解析登录接口拿到凭证后核心就是按日期拉数。下面函数演示拉某一天三类数据接口路径以抓包结果为准这里用可替换的fitness路径做示例import datetime import requests def fetch_daily_data(api_cfg, user_id, target_date): 拉取指定日期的步数、心率和睡眠数据 target_date: datetime.date 对象 headers { Authorization: fBearer {api_cfg[access_token]}, app_version: 5.2.3, lang: zh-CN, } params { user_id: user_id, date_from: target_date.strftime(%Y-%m-%d), date_to: target_date.strftime(%Y-%m-%d), } session requests.Session() steps session.get( f{api_cfg[base_url]}/v1/fitness/steps, paramsparams, headersheaders, timeout10, ).json() heart_rate session.get( f{api_cfg[base_url]}/v1/fitness/heart_rate, paramsparams, headersheaders, timeout10, ).json() sleep session.get( f{api_cfg[base_url]}/v1/fitness/sleep, paramsparams, headersheaders, timeout10, ).json() return { date: target_date.isoformat(), steps: steps, heart_rate: heart_rate, sleep: sleep, }逻辑说明按天查三个接口分别返回每天汇总、分钟级心率和睡眠分期结构。链式请求之间加了自然串行没有并发这是为了不给服务端造成瞬时压力。参数说明date_from和date_to都传同一个日期格式是YYYY-MM-DDuser_id必须和 token 属于同一个账号混用会得到空数据或 401heart_rate接口返回的通常是每分钟一个值一天 1440 个点缺测位置可能是 0解析时要把 0 当成无数据不能当成真实心率。这里有个容易翻车的细节如果响应拿回来是一堆乱码而且响应头Content-Type是application/x-protobuf之类说明这个版本启用了 protobufresponse.json()会直接报错。遇到这种情况先看抓包里响应解码是否正常再找对应的.proto定义反序列化。多数老设备与 Zepp Life 的组合仍然是 JSON但新版本多遇到 protobuf脚本需要为这两种情况各写一个解析分支。请求频率上我是这样控制的批量拉日期时循环里每个请求之间time.sleep(0.3)一天三个接口就是约一秒。三天以上的批量任务避免并发串行跑几分钟完全可以接受没必要拿账号去试探频控阈值。3.4 持久化按日期写 CSV顺手入库 SQLite数据拉下来不落盘等于白跑。落盘方案我一般选 SQLite 为主库、CSV 做交换格式因为增量导出会重复跑同一个日期SQLite 的INSERT OR REPLACE天然适合去重。先建一张汇总表保留一份完整原始 JSON 备查import json import sqlite3 def save_to_db(raw, db_path): conn sqlite3.connect(db_path) conn.execute( CREATE TABLE IF NOT EXISTS daily_summary ( date TEXT PRIMARY KEY, steps INT, total_sleep_minutes INT, deep_sleep_minutes INT, avg_heart_rate INT, raw_json TEXT ) ) summary extract_summary(raw) conn.execute( INSERT OR REPLACE INTO daily_summary (date, steps, total_sleep_minutes, deep_sleep_minutes, avg_heart_rate, raw_json) VALUES (?,?,?,?,?,?), (raw[date], summary[steps], summary[total_sleep], summary[deep_sleep], summary[avg_hr], json.dumps(raw, ensure_asciiFalse)), ) conn.commit() conn.close() def extract_summary(raw): # 汇总逻辑按真实字段名解析这里只做占位 return { steps: 0, total_sleep: 0, deep_sleep: 0, avg_hr: 0, }逻辑说明raw_json保存完整原始返回之后如果发现解析漏了字段不需要重新请求直接从库里捞原始数据重新解析就行这是给自己留的后悔药。参数说明date TEXT PRIMARY KEY意味着同一天只会保留一份记录配合INSERT OR REPLACE重跑不会产生重复行。extract_summary在这里是占位你需要按实际返回字段提取步数、睡眠总时长和深睡时长。CSV 导出可以和 SQLite 并存适合直接丢进 Excel 或后续用 pandas 分析。常见做法是在每次同步完成后把近一周的daily_summary导出成一个daily.csv列名用英文小写下划线避免中文编码问题。到这一步脚本从登录到落盘的最小闭环已经通了。4. 让导出自己跑增量同步、定时调度与失败重试4.1 增量窗口设计从“今天”往回推两天脚本跑通之后下一步是让它自动循环。全量重导历史记录问题很大天数多、请求多、容易被限流重复数据还要清理。增量同步的思路是维护一个last_sync.json记录上次同步到的日期下次从“上次日期往前推两天”开始导到昨天为止。为什么要往前推两天因为手环的数据同步不是实时的。很多人睡前戴上早晨起来直接出门没有打开 App手环那一夜的缓存还没上传还有人加班到凌晨第二天的数据中午才同步到云端。往前推两天是给云端留缓冲窗口配合INSERT OR REPLACE重复拉取不会产生脏数据。首次运行没有历史记录可以按需求回退 90 天或 365 天脚本写法如下import json from datetime import date, timedelta from pathlib import Path def next_sync_window(last_sync_file: Path, today: date): if last_sync_file.exists(): last_date date.fromisoformat( json.loads(last_sync_file.read_text())[last_sync_date] ) else: last_date today - timedelta(days90) # 首次运行回退90天 start last_date - timedelta(days2) # 补前端两天的迟滞数据 end today - timedelta(days1) # 昨天是最近完整的一天 return start, end def mark_synced(last_sync_file: Path, end: date): last_sync_file.write_text( json.dumps({last_sync_date: end.isoformat()}) )逻辑说明窗口是闭区间每次从start循环到end跑完把last_sync_date更新为end。下次窗口自动从end - 2开始意味着最近三天会被重复拉一次。这个重复是故意的不是浪费它补的是“手环还没同步完”的数据。参数说明回退天数 90 和缓冲天数 2 都是经验值。刚上手想看更久历史把 90 改成 365如果你每天两次开 App习惯良好缓冲天数可以缩成 1但没必要多拉三天的成本很低。4.2 定时调度cron 和任务计划怎么定时间点定时任务不是随便设的核心约束是数据完整性。很多人第一次设凌晨 2 点跑结果睡眠数据老是缺因为夜里手环上传依赖手机 App 在后台活跃夜里 App 大概率没在工作。更实用的做法是每天跑两次早上 8 点补昨夜睡眠晚上 9 点补白天心率。窗口本身有两天缓冲两次调度即使重复拉同一批日期数据也会被幂等覆盖不会重复。Linux 或 NAS 上crontab 直接加两行# 每天 08:00 和 21:00 各跑一次增量导出 0 8 * * * cd /opt/miband-exporter /usr/bin/python3 export_daily.py logs/export.log 21 0 21 * * * cd /opt/miband-exporter /usr/bin/python3 export_daily.py logs/export.log 21Windows 上用任务计划程序或 schtasks 注册一个每日任务命令如下schtasks /Create /TN MibandExport /SC DAILY /ST 08:00 /TR cmd /c cd C:\miband-exporter python export_daily.py logs\export.log 21参数说明 logs/export.log 21必须保留自动化脚本挂掉时没有任何界面提示只能靠日志定位问题日志建议按月份拆分比如logs/export-202506.log避免单文件涨到几十 MB。cron 里的 python 路径要确认很多环境默认 python 不在/usr/bin/python3可以先which python3查一下。如果你把脚本跑在路由器或 NAS 上还要注意设备睡眠策略别让任务在休眠期间被跳过。4.3 失败重试与限流参数怎么调才不伤账号自动化跑起来后失败是常态关键是处理方式要对。请求返回常见状态码里401 表示 token 失效重试没用要触发重新登录429 是限流要退避等待5xx 是服务端临时问题可以重试超时是网络波动也可以重试。不同错误要区别对待不能一把梭。指数退避是最常见的重试策略我给一个可直接用的装饰器import time import requests from functools import wraps def retry(max_attempts4, base_delay2): def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_attempts): try: return func(*args, **kwargs) except requests.HTTPError as e: status e.response.status_code if status 401: raise # token失效重试没有意义交给上层续期 if attempt max_attempts - 1: raise # 已经最后一次直接暴露问题 delay base_delay * (2 ** attempt) # 2s, 4s, 8s time.sleep(delay) return None return wrapper return decorator逻辑说明指数退避的核心是让服务端有恢复时间不是快速重试轰炸。base_delay2三次重试分别等 2 秒、4 秒、8 秒总计约 14 秒这个量级对日志任务完全够用。参数说明max_attempts建议不超过 4超过之后问题大概率不是瞬时抖动而是账号或网络层面的故障继续重试只会恶化限流。429 响应如果带Retry-After头优先按它的秒数等待这个字段是服务端明确告诉你的冷却时间比指数退避更精准没有这个头再走退避。日常拉数时并发也要控制住。串行请求加 0.3 秒间隔已经能避开大部分限流如果做并发并发数控制在 2 以内并且单日请求总量别超过几百次。连续三次 429 时停止当天任务并写一条告警日志不要无限重试。IP 被限后通常几小时后自动解开这时候改 User-Agent 重登没有实际帮助老老实实等冷却更靠谱。5. 避坑自动导出跑半年后最容易翻车的五个点这一章是血泪经验汇总。工具跑起来前两周通常风平浪静跑满一两个月各种边界问题才会陆续浮出来。列出的每条都按“现象、原因、解决”讲你在自己的脚本里提前布好防线。5.1 token 失效导致进程直接报 401现象某天开始日志里全是 401 Unauthorized手动打开 App 却发现账号完全正常数据也能看。原因新版本签发的 token 有效期短脚本是硬编码 token过期后没有走登录流程也可能因为你在手机上登录了新设备服务端把旧会话踢掉了。解决给请求层加一个钩子——遇到 401 不直接失败先调用登录接口换新 token写回配置再重发原请求同时把 token 的获取时间记在配置里如果 token 有效期已知提前一周主动刷新。要特别注意被踢下线是常态化事件不是异常续期逻辑必须做成自动的不能靠手工改配置。5.2 时区错位睡眠数据跑到前一天现象导出的睡眠记录里入睡时间总是比 App 上显示早 8 小时或者凌晨 0 点到 6 点的数据挂在了前一天的字段里。原因云端返回的时间戳是 UTC 毫秒值脚本直接用了datetime.utcfromtimestamp解析而 App 展示时按 Asia/Shanghai 换算过两边差一个时区日期自然错位。解决统一在配置里写死timezone: Asia/Shanghai解析时间戳时先转东八区再取日期。这里补一个转换示例from datetime import datetime, timezone, timedelta tz timezone(timedelta(hours8)) local_dt datetime.fromtimestamp(ts / 1000, tztz) # ts 单位是毫秒 local_date local_dt.strftime(%Y-%m-%d)注意时间戳单位的坑。有的接口返回秒10 位有的返回毫秒13 位直接用错会差 1000 倍。我习惯在解析函数入口打印一次首条时间戳人工确认单位后再批量处理。导出文件的命名、数据库里的date字段都要按本地日期生成不能按 UTC 生成。5.3 手环没同步完成导致当天数据缺段现象早上 8 点任务跑完晚上打开 App发现昨晚的睡眠分期齐全但导出的 SQLite 里少了两段深睡。原因手环数据上传依赖手机 App 在后台工作。很多人晚上戴着睡早上出门没开过 App手环缓存还没上传云端自然没有那段数据脚本再准时也拉不到。解决每天跑两次以上第二次放在晚上 9 点前后这时候白天数据早已同步增量窗口往回推两天让漏掉的数据在第二次跑时被覆盖补齐。如果发现某个日期反复缺同一段记一份“缺失数据清单”字段包含日期、缺失类型、首次发现时间连续三天仍缺就手动开一次 App 确认手环有没有正常连接。5.4 请求太频繁被限流429 与 IP 封禁的界线现象脚本第一次跑正常几分钟后第二次跑就开始返回 429继续重试几次直接超时。原因没有限速批量日期循环里请求一股脑全打出去家里宽带出口是共享 IP厂商的防护阈值又比较低瞬时请求量一高就被限。解决批量日期之间串行请求每请求间隔 0.3 秒重试时优先尊重Retry-After响应头连续三次 429 就停止当天任务并告警不要无限重试。判断是否被临时封禁看同一 IP 请求其他接口是否也超时即可超时说明到了 IP 级限制这时候只能等几小时自动恢复改 User-Agent 重登作用不大。5.5 密码明文存储与脚本泄露风险现象config.yaml里直接写着账号密码把代码目录同步到网盘或提交到 git 仓库后账号出现异地登录提醒。原因工具越方便越容易忽视安全。私有接口虽然没有公开文档但它同样吃账号权限一旦凭证泄露等于把健康数据整个交出去。解决密码改用环境变量或系统钥匙串读取配置文件里只放 tokentoken 失效需重新登录时临时手动输入密码结束后清空。git 仓库用.gitignore把config.yaml、logs/、export/全部挡在提交之外建议再定期轮换账号密码尤其是部署在共享服务器上的情况。6. 验证导出的数据对不对再把它接进自己的分析流程6.1 三分钟交叉验证法拿 App 数字对账自动化工具最怕的不是报错而是报“成功”但数据是错的。每次跑完抽一天数据和 App 显示的数字对一遍。对账指标选三个就够总步数、睡眠总时长、平均心率。App 展示的是“本地日期 0 点到 24 点”的统计脚本汇总时也按同一口径两边才对得上。抽检可以写成一个小函数def verify_date(target_date): summary load_summary(target_date) # 从SQLite读 expected {steps: 8246, sleep_minutes: 421} # 手输App里看到的数字 print(steps diff:, summary[steps] - expected[steps]) print(sleep diff:, summary[total_sleep_minutes] - expected[sleep_minutes])对不上时按顺序排查先看时区字段有没有统一再看当天手环是否同步完整最后确认原始 JSON 解析字段是否选错。不要拿手环屏幕显示的数去对手环显示的是设备本地缓存和云端不一定同时更新要以手机 App 里看到的云端数据为准。6.2 进阶把导出数据接进自己的健康看板数据进来之后日常分析就顺理成章。SQLite 里有了按天汇总可以直接查近两周的深睡占比看看规律SELECT date, total_sleep_minutes, deep_sleep_minutes, ROUND(deep_sleep_minutes * 100.0 / total_sleep_minutes, 1) AS deep_rate FROM daily_summary ORDER BY date DESC LIMIT 14;字段名按你自己的表结构调整深睡占比如果长期低于 15%值得留意生活习惯。想做更复杂的分析把daily.csv丢给 pandas 或任何可视化工具都行分钟级心率还能做夜间心率分布曲线观察静息心率随疲劳度的变化。如果你的目标是长期积累SQLite 里再按月份建视图会更方便但不要为了分析方便牺牲增量同步那套逻辑——它是数据质量的底线。我最早跑这个工具时以为数据拉下来就结束了结果第三天对账发现步数少了三千排查到凌晨才发现是时区问题。那之后我在所有日期处理的地方统一用 Asia/Shanghai并把中间结果和原始 JSON 都保留下来半年多再没丢过数。把数据自动化拿回自己手里这件事值得投入一套干净、可验证的管线希望帮到你。本文还有配套的精品资源点击获取
