从小米运动健康到运动主页：骑行数据自动同步全攻略

本文将介绍如何将小米运动健康的骑行数据，通过 Keep 中转，最终自动同步到你的个人运动主页（sports-page）。

背景

作为小米手环/手表的用户，我一直在用小米运动健康 App 记录骑行数据。但小米运动健康本身没有提供很好的数据展示和分享功能。于是我想到了一个方案：

小米运动健康 → Keep → sports-page

这个方案的核心思路是：

1. 小米运动健康可以将数据同步到 Keep
2. running_page 项目提供了 Keep 数据同步脚本
3. 通过 GitHub Actions 实现自动化

前置准备

• 小米设备：小米手环 8 Pro / 小米手环 9 Pro / 小米手表 S3 / 小米手表 S4 等支持 GPS 的设备
• 小米运动健康 App：已绑定设备并能正常记录运动数据
• Keep 账号：用于存储和中转运动数据
• GitHub 账号：用于部署 sports-page 项目
• 本地环境：Python 3.8+ / Node.js 20+

第一步：小米运动健康接入 Keep

1.1 在小米运动健康中绑定 Keep

详细步骤：

1. 打开小米运动健康 App（确保已更新到最新版本）
2. 点击右下角 我的
3. 向下滑动，找到 第三方数据接入 选项
4. 点击进入后，找到 Keep
5. 点击 Keep，会跳转到 Keep 的授权页面
6. 使用你的 Keep 账号登录并授权
7. 授权成功后，会自动返回小米运动健康 App

验证绑定状态：

• 在 第三方数据接入 页面，Keep 应该显示为 已绑定
• 绑定后，小米运动健康的运动数据会自动同步到 Keep

注意： 小米运动健康支持同步的运动类型包括：跑步、骑行、徒步、登山等。骑行数据会以 outdoorCycling 类型同步到 Keep。首次同步可能需要等待几分钟到几小时不等。

1.2 验证数据同步

打开 Keep App，进入 运动 → 运动记录，检查是否能看到从小米运动健康同步过来的骑行记录。

第二步：部署 sports-page 项目

2.1 克隆项目

git clone https://github.com/lczhuigz/running_page.git --depth=1
cd running_page

2.2 安装依赖

# Python 依赖
uv add requests

# Node.js 依赖
npm install -g corepack && corepack enable && pnpm install

2.3 同步 Keep 骑行数据

uv run python run_page/keep_sync.py ${手机号} ${密码} --sport-type cycling

参数说明：

• ${手机号}：你的 Keep 账号手机号
• ${密码}：你的 Keep 账号密码
• --sport-type cycling：指定同步骑行数据（可选值：running、cycling、hiking）
• --with-gpx：同时导出 GPX 轨迹文件（用于备份或其他用途）

完整示例：

# 同步骑行数据
python run_page/keep_sync.py 13800138000 yourpassword --sport-type cycling

# 同时导出 GPX 轨迹文件
python run_page/keep_sync.py 13800138000 yourpassword --sport-type cycling --with-gpx

# 同步所有运动类型（不指定 --sport-type）
python run_page/keep_sync.py 13800138000 yourpassword

# 查看帮助
python run_page/keep_sync.py --help

同步成功输出示例：

INFO:root:Login successful
INFO:root:Fetching cycling data...
INFO:root:Found 42 cycling records
INFO:root:Processing record 1/42: 2024-01-15 10:30:00 - 15.2km
INFO:root:Processing record 2/42: 2024-01-14 08:15:00 - 22.8km
...
INFO:root:Sync completed. 42 records saved to data.db

2.4 本地预览

pnpm develop

访问 http://localhost:5173/ 查看效果。

第三步：配置自动化同步

3.1 修改 GitHub Actions 配置

项目已经自带了 .github/workflows/run_data_sync.yml，你只需要修改顶部的环境变量即可：

env:
  RUN_TYPE: keep  # 改为 keep
  ATHLETE: lczhuigz  # 改成你的名字
  TITLE: lczhuigz Sports  # 页面标题
  MIN_GRID_DISTANCE: 10
  TITLE_GRID: Over 10km Activities

关键配置说明：

配置项	说明	示例值
RUN_TYPE	数据源类型	keep
ATHLETE	运动员名称	lczhuigz
TITLE	页面标题	My Sports Page
MIN_GRID_DISTANCE	网格图最小距离(km)	10
BIRTHDAY_MONTH	生日月份(用于生命月图)	2005-03

注意： Keep 同步默认会拉取所有运动类型（跑步、骑行、徒步等），不需要额外指定 --sport-type 参数。同步命令是：

python run_page/keep_sync.py ${{ secrets.KEEP_MOBILE }} ${{ secrets.KEEP_PASSWORD }} --with-gpx

3.2.1 配置 GitHub Secrets

在你的 GitHub 仓库中，进入 Settings → Secrets and variables → Actions，添加以下 Secrets：

Secret 名称	值	说明
KEEP_MOBILE	你的 Keep 手机号	注意是 KEEP_MOBILE，不是 KEEP_PHONE_NUMBER
KEEP_PASSWORD	你的 Keep 密码	Keep 账号密码

⚠️ 重要： Secret 名称必须是 KEEP_MOBILE 和 KEEP_PASSWORD，与 workflow 文件中的变量名保持一致。

3.3 推送代码

git add .
git commit -m "feat: configure Keep sync"
git push origin master  # 注意：项目默认分支是 master

推送后，GitHub Actions 会自动（在仓库设置中授予 Actions 写权限进入 Settings → Actions → General → Workflow permissions → Read and write permissions → Save；第一次需要手动运行一下Run Data Sync的action）：

1. 同步 Keep 数据
2. 生成 SVG 统计图
3. 构建前端页面
4. 部署到 GitHub Pages

第四步：个性化配置

4.1 修改网站信息

编辑 src/static/site-metadata.ts：

const data: ISiteMetadataResult = {
  siteTitle: '我的骑行主页',  // 修改标题
  siteUrl: 'https://your-domain.com',  // 修改域名
  logo: '/images/your-logo.png',  // 修改 Logo
  description: '记录每一次骑行',
  navLinks: [
    {
      name: '首页',
      url: '/',
    },
    {
      name: '关于',
      url: 'https://your-blog.com/about',
    },
  ],
};

4.2 修改地图配置

编辑 src/utils/const.ts：

// 地图供应商（推荐使用免费的 mapcn）
export const MAP_TILE_VENDOR = 'mapcn';

// 地图样式
export const MAP_TILE_STYLE_LIGHT = 'osm-bright';
export const MAP_TILE_STYLE_DARK = 'dark-matter';

// 是否使用虚线显示路线
const USE_DASH_LINE = true;

// 路线透明度
const LINE_OPACITY = 0.4;

4.3 部署到 Vercel（推荐）

1. 在 Vercel 注册账号
2. 导入你的 GitHub 仓库
3. Vercel 会自动检测到 Vite 项目并部署
4. 配置自定义域名（可选）

常见问题

Q1: 为什么 Keep 中没有看到小米运动健康的数据？

A: 请检查：

1. 小米运动健康中的 Keep 授权是否成功（我的 → 第三方数据接入 → Keep 应显示为已绑定）
2. 运动数据是否已上传到小米运动健康云端（在小米运动健康 App 中能看到完整记录）
3. Keep App 是否为最新版本（建议更新到最新版）
4. 首次同步可能需要等待几分钟到几小时，请耐心等待

Q2: keep_sync.py 报错 “login failed”

A: 请检查：

1. 手机号和密码是否正确
2. Keep 账号是否已激活（需要在手机上登录过 Keep）
3. 是否开启了 Keep 的登录验证（如短信验证码），如果开启了需要在手机上手动登录一次
4. 是否使用了正确的手机号格式（如 +86 13800138000）

Q3: 骑行数据没有 GPS 轨迹

A: 可能的原因：

1. 小米手环/手表不支持 GPS（如小米手环 8 标准版）
2. 骑行时没有开启 GPS 记录
3. GPS 信号弱导致轨迹不完整
4. 设备与手机断开连接，导致 GPS 数据丢失

支持 GPS 的小米设备：

• 小米手环 8 Pro / 9 Pro
• 小米手表 S3 / S4
• 小米手表 Ultra
• Redmi Watch 4 / 5

解决方案： 使用支持 GPS 的小米设备，并在骑行时确保：

1. 设备已开启 GPS（设置 → 运动 → GPS）
2. 在户外空旷处等待 GPS 信号锁定后再开始骑行
3. 骑行过程中保持设备与手机的蓝牙连接

Q4: 如何同步多种运动类型？

A: 不需要额外配置。keep_sync.py 默认会同步所有运动类型（跑步、骑行、徒步等）。如果你想查看支持的运动类型，可以运行：

python run_page/keep_sync.py --help

Q5: 如何手动触发同步？

A: 在 GitHub 仓库页面，进入 Actions 选项卡，选择 Run Data Sync 工作流，点击 Run workflow 按钮即可手动触发同步。

Q6: 同步速度很慢怎么办？

A: 同步速度取决于：

1. 运动记录的数量（历史数据越多越慢）
2. 网络状况
3. Keep API 的响应速度

首次同步可能需要较长时间，后续增量同步会快很多。可以在 workflow 中添加超时设置：

- name: Run sync Keep script
  if: env.RUN_TYPE == 'keep'
  timeout-minutes: 30  # 设置 30 分钟超时
  run: |
    python run_page/keep_sync.py ${{ secrets.KEEP_MOBILE }} ${{ secrets.KEEP_PASSWORD }} --with-gpx

数据流图

┌─────────────────┐
│  小米运动健康    │
│  (小米手环/手表) │
└────────┬────────┘
         │ 第三方接入授权（自动同步）
         ▼
┌─────────────────┐
│      Keep       │
│  (运动数据存储)  │
└────────┬────────┘
         │ keep_sync.py（手动/自动同步）
         ▼
┌─────────────────┐
│   SQLite 数据库  │
│   (data.db)     │
└────────┬────────┘
         │ pnpm build
         ▼
┌─────────────────┐
│   静态页面生成   │
│  (HTML/CSS/JS)  │
└────────┬────────┘
         │ GitHub Actions
         ▼
┌─────────────────┐
│   Vercel 部署   │
│  (自动更新)     │
└─────────────────┘

技术细节

keep_sync.py 工作原理

1. 登录 Keep：使用手机号和密码登录 Keep API
2. 获取运动列表：调用 Keep API 获取所有运动记录（默认同步所有类型）
3. 解析数据：解析每条运动记录的距离、时间、配速、GPS 轨迹等
4. 存储数据：将数据存储到 SQLite 数据库（data.db）
5. 导出 GPX：使用 --with-gpx 参数可同时导出 GPX 轨迹文件
6. 生成页面：读取数据库数据，生成静态页面

工作流完整流程

GitHub Actions 触发（每天 / 手动）
    ↓
checkout 代码 + 安装 Python 依赖
    ↓
keep_sync.py 同步 Keep 数据 → data.db + activities/*.gpx
    ↓
gen_svg.py 生成统计图表 → assets/*.svg
    ↓
gh-pages.yml 构建前端 → pnpm build
    ↓
部署到 GitHub Pages

数据格式

Keep API 返回的骑行数据包含：

• sport_type：运动类型（outdoorCycling）
• distance：距离（米）
• duration：时长（秒）
• start_time：开始时间
• end_time：结束时间
• gps_data：GPS 轨迹数据（经纬度坐标序列）

坐标转换

由于小米运动健康使用的是 GCJ-02 坐标系（国测局坐标），而 Mapbox 使用 WGS-84 坐标系，keep_sync.py 会自动进行坐标转换：

# 配置项：是否进行坐标转换
TRANS_GCJ02_TO_WGS84 = True

支持的运动类型

keep_sync.py 支持以下运动类型：

Keep 运动类型	说明	是否有 GPS 轨迹
outdoorRunning	户外跑步	✅
outdoorCycling	户外骑行	✅
outdoorWalking	户外步行	✅
mountaineering	登山	✅
trailRunning	越野跑	✅
indoorRunning	室内跑步	❌
indoorCycling	室内骑行	❌
treadmill	跑步机	❌
swimming	游泳	❌

总结

通过这个方案，你可以：

1. 自动同步：小米运动健康的骑行数据自动同步到运动主页
2. 数据展示：美观的运动主页，支持地图轨迹、统计数据等
3. 多端支持：支持跑步、骑行、徒步等多种运动类型
4. 免费部署：使用 Vercel 免费部署，无需服务器
5. 数据安全：所有数据存储在你自己的 GitHub 仓库中
6. 历史追溯：支持同步历史骑行记录，不丢失任何数据

整个流程配置完成后，你只需要专注于运动，数据会自动同步并展示在你的个人运动主页上。

进阶玩法

自定义同步频率

默认每天同步一次（UTC 时间 0 点，北京时间早上 8 点），你可以根据需要修改 .github/workflows/run_data_sync.yml 中的 cron 表达式：

on:
  schedule:
    # 每 6 小时同步一次
    - cron: '0 */6 * * *'
    # 每天早晚各同步一次
    # - cron: '0 0,12 * * *'
    # 每周一早上同步一次
    # - cron: '0 0 * * 1'
  workflow_dispatch:  # 保留手动触发

多运动类型同步

keep_sync.py 默认同步所有运动类型，不需要额外配置。如果你想只同步特定类型，可以在 workflow 中修改同步命令：

- name: Run sync Keep script
  if: env.RUN_TYPE == 'keep'
  run: |
    # 同步所有类型（默认）
    python run_page/keep_sync.py ${{ secrets.KEEP_MOBILE }} ${{ secrets.KEEP_PASSWORD }} --with-gpx
    # 如果只想同步骑行，可以改成：
    # python run_page/keep_sync.py ${{ secrets.KEEP_MOBILE }} ${{ secrets.KEEP_PASSWORD }} --sport-type cycling --with-gpx

数据备份

running_page 会自动备份 GPX 轨迹文件到 activities/ 目录，你可以定期备份这些文件，防止数据丢失。

手动备份命令：

# 备份 GPX 文件
cp -r activities/ backup/activities_$(date +%Y%m%d)

# 备份数据库
cp data.db backup/data_$(date +%Y%m%d).db

自定义地图样式

编辑 src/utils/const.ts，可以切换不同的地图样式：

// 可选样式：'osm-bright' | 'osm-liberty' | 'dark-matter'
export const MAP_TILE_STYLE_LIGHT = 'osm-bright';
export const MAP_TILE_STYLE_DARK = 'dark-matter';

参考链接

• running_page 项目
• Keep 官网
• 小米运动健康
• Vercel 部署文档
• GitHub Actions 文档
• SQLite 数据库工具

为什么选择 Keep 作为数据源？

1. 数据兼容性好：running_page 原生支持 Keep 数据同步
2. 运动类型丰富：支持跑步、骑行、徒步等多种运动类型
3. GPS 轨迹完整：Keep 会完整保存 GPS 轨迹数据
4. 自动同步：小米运动健康可以自动同步数据到 Keep
5. 免费使用：Keep 基础功能完全免费
6. API 稳定：Keep 的 API 相对稳定，不容易出现同步失败的情况
7. 历史数据完整：可以同步所有历史运动记录，不丢失数据

其他数据源选择

除了 Keep，running_page 还支持以下数据源：

数据源	支持设备	备注
Strava	佳明、高驰、颂拓等	需要 Strava API
Garmin	佳明设备	需要佳明账号
Nike	Nike Run Club	需要 Nike 账号
Keep	Keep App	本文使用
GPX/TCX	通用格式	手动导入

如果你使用的是小米设备，Keep 是最方便的选择，因为小米运动健康可以直接同步数据到 Keep。

实际效果展示

部署完成后，你的运动主页将展示：

1. 运动总览：总骑行距离、总骑行次数、总骑行时长
2. 年度统计：每年的骑行数据汇总
3. 地图轨迹：所有骑行路线的地图展示
4. 单次详情：每次骑行的详细数据（距离、时长、配速、海拔等）
5. 数据可视化：图表展示骑行趋势和分布

版本更新

running_page 项目会不断更新，建议定期同步最新代码：

# 添加上游仓库
git remote add upstream https://github.com/yihong0618/running_page.git

# 拉取最新代码
git fetch upstream

# 合并更新
git merge upstream/main

# 解决冲突（如有）
# ...

# 推送到你的仓库
git push origin main

安全提示

1. 密码安全：GitHub Secrets 中的密码是加密存储的，不会泄露
2. API 限制：Keep API 有请求频率限制，建议每天同步不超过 2 次
3. 数据隐私：运动主页默认公开，如果不想公开可以选择私有仓库或启用隐私模式
4. 隐私模式：编辑 src/utils/const.ts，设置 PRIVACY_MODE = true 可以隐藏地图详情

// 隐私模式：只显示路线，不显示地图底图
const PRIVACY_MODE = false;

// 灯光模式：控制地图亮度
const LIGHTS_ON = false;

结语

通过这个方案，你可以将小米运动健康的骑行数据自动同步到个人运动主页，实现：

• 数据可视化：直观展示骑行轨迹和统计数据
• 自动化管理：无需手动操作，数据自动同步
• 个人品牌：打造专属的骑行主页，分享你的骑行故事
• 数据备份：所有数据存储在你的 GitHub 仓库中，安全可靠

希望这篇文章对你有帮助！如果有任何问题，欢迎在评论区留言讨论。

---

作者: lczhuigz
项目: sports-page

---

本文基于 running_page 项目编写，项目地址：https://github.com/lczhuigz/running_page