🏃 Garmin Connect CN → Strava 运动记录同步

将 Garmin Connect 国内版（connect.garmin.cn）的运动记录自动同步到 Strava。

背景

Garmin Connect 国内版与国际版数据不互通，且 Strava 无法直接关联国内版账号。本工具通过模拟登录 Garmin Connect CN，下载活动文件（GPX/TCX/FIT），再上传到 Strava，实现跨平台数据同步。

功能特性

• ✅ 支持 Garmin Connect 国内版 SSO 登录
• ✅ 自动下载活动原始文件（GPX → TCX → FIT 自动降级）
• ✅ 智能去重：同日期 + 同类型 + 相近时长的活动不会重复上传
• ✅ 支持筛选活动类型（跑步、骑行、游泳等）
• ✅ 支持守护模式（定时自动同步）
• ✅ 丰富的活动描述模板
• ✅ 试运行模式（预览待同步活动）

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置凭证

# 复制配置模板
copy .env.example .env   # Windows
cp .env.example .env     # macOS/Linux

编辑 .env 文件：

# Garmin Connect CN 账号
GARMIN_CN_USERNAME=your_email@example.com
GARMIN_CN_PASSWORD=your_password

# Strava API 凭证
STRAVA_CLIENT_ID=12345
STRAVA_CLIENT_SECRET=abc123def456
STRAVA_REFRESH_TOKEN=your_refresh_token_here

3. 获取 Strava API 凭证

步骤 A：创建 Strava API 应用

1. 访问 https://www.strava.com/settings/api
2. 填写应用信息：
   • Application Name: Garmin CN Sync（任意名称）
   • Website: http://localhost
   • Authorization Callback Domain: localhost
3. 创建后获得 Client ID 和 Client Secret

步骤 B：获取 Refresh Token

在浏览器中访问以下 URL（替换 YOUR_CLIENT_ID）：

https://www.strava.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost&approval_prompt=force&scope=activity:write,activity:read_all

授权后，浏览器会跳转到 http://localhost/?state=&code=XXXXXX&scope=...，复制 URL 中的 code 值。

然后运行以下命令换取 Refresh Token（替换对应值）：

curl -X POST https://www.strava.com/oauth/token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=AUTHORIZATION_CODE \
  -d grant_type=authorization_code

从返回的 JSON 中获取 refresh_token，填入 .env。

💡 Refresh Token 长期有效，只需获取一次。Access Token 由程序自动刷新。

4. 运行

# 单次同步（默认最近 30 天）
python main.py

# 同步最近 7 天
python main.py --days 7

# 试运行：仅查看活动列表，不实际同步
python main.py --dry-run

# 守护模式：每 2 小时自动同步
python main.py --daemon

# 详细日志
python main.py --verbose

项目结构

workout-sync/
├── main.py                  # 主入口
├── config.yaml              # 同步策略配置
├── requirements.txt         # 依赖
├── .env.example             # 环境变量模板
├── downloads/               # 活动文件下载目录（自动创建）
└── src/
    ├── __init__.py
    ├── models.py            # 数据模型
    ├── garmin_cn_client.py  # Garmin CN 客户端
    ├── strava_client.py     # Strava API 客户端
    └── sync_service.py      # 同步核心逻辑

配置说明

config.yaml 中的主要配置项：

配置	说明	默认值
sync.days_back	同步最近多少天	30
sync.activity_types	需要同步的活动类型	cycling,running,swimming,hiking,walking,other
sync.skip_duplicates	是否跳过重复活动	true
strava.private	上传活动是否设为私有	false
strava.description_template	活动描述模板	见配置文件

支持的活动类型映射

Garmin 类型	Strava 类型
running / trail_running / treadmill_running	Run
cycling / road_biking / mountain_biking	Ride
swimming / pool_swimming / open_water	Swim
hiking	Hike
walking	Walk
其他	Workout

常见问题

Q: 提示 "Garmin CN 登录失败"？ A: 检查 .env 中的账号密码是否正确。如果开启了二次验证，可能需要使用应用专用密码。

Q: 上传后 Strava 显示 "文件处理中"？ A: Strava 上传是异步的，程序会自动等待处理完成（最长 120 秒）。如果持续失败，可能是文件格式问题，程序会自动尝试 GPX → TCX → FIT 降级。

Q: 能否只同步特定类型的活动？ A: 修改 config.yaml 中的 sync.activity_types，例如只同步跑步和骑行：[running, cycling]。

免责声明

本工具仅供个人学习使用。使用本工具可能违反 Garmin Connect 的服务条款，请自行承担风险。