专业的跑步数据分析工具，助力跑者实现 PB

基于 Garmin 数据，通过专业的跑力（VDOT）分析、心率区间分布、配速趋势等多维度数据，为跑者提供科学的训练建议和数据洞察。

• 专业的跑力分析：基于 Jack Daniels 的 VDOT 理论，精确计算跑力值，追踪训练效果
• 心率区间优化：分析每次训练的心率分布，帮助优化有氧/无氧训练配比
• 配速趋势洞察：可视化配速变化，识别疲劳点和进步曲线
• 个人记录追踪：自动识别和记录不同距离的 PB（个人最佳成绩）

• 完全免费 🎉 - 无需购买云数据库，零运营成本
• 一键部署 🚀 - 部署到 Vercel，享受全球 CDN 加速
• 数据离线化 💾 - SQLite 数据库随代码版本管理，数据永不丢失
• 自动同步 🔄 - GitHub Actions 每日自动同步，无需手动操作
• 隐私安全 🔒 - 数据存储在自己的 GitHub 仓库，完全掌控
• 移动端优化 📱 - 完美适配手机端，随时随地查看数据

步骤 1: 数据同步（每日自动）
┌─────────────────┐
│  Garmin 国际区   │
│   运动数据       │  FIT 文件
│                 │────────┐
└─────────────────┘        │
                           ▼
                    ┌───────────────┐
                    │ GitHub Actions│
                    │ ・下载 FIT     │
                    │ ・解析数据     │
                    │ ・计算 VDOT    │
                    └──────┬────────┘
                           │
步骤 2: 数据存储             │ 写入并提交
┌─────────────────┐        │
│   GitHub 仓库    │        │
│                 │◄───────┘
│ ・代码文件        │
│ ・SQLite 数据库   │
└────────┬────────┘
         │
         │ 自动部署
         ▼
步骤 3: 应用部署
┌─────────────────┐
│     Vercel      │
│  ・Next.js 应用  │
│  ・API Routes   │
│  ・SQLite 读取   │
└────────┬────────┘
         │
         │ HTTPS
         ▼
步骤 4: 用户访问
┌─────────────────┐
│   用户浏览器     │
│  ・查看数据      │
│  ・分析图表      │
└─────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
核心优势

✓ 完全免费    数据库文件随代码提交，无需购买云数据库
✓ 数据安全    SQLite 文件存在自己的 GitHub 仓库
✓ 自动同步    GitHub Actions 每日自动运行
✓ 全球加速    Vercel CDN 全球节点，响应 <100ms
✓ 版本管理    数据库支持 Git 版本控制，永不丢失
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• 数据同步: Node.js + Garmin Connect API
• 数据解析: FIT SDK (心率、配速、GPS 等 28+ 字段)
• 数据存储: SQLite (离线数据库，随代码部署)
• Web 框架: Next.js 16 (App Router + API Routes)
• 数据可视化: ECharts (跑力趋势、心率区间、配速分析)
• 自动化: GitHub Actions (每日同步 + 自动部署)
• 部署平台: Vercel (零配置，全球 CDN)

• Node.js 18+
• Garmin 国际区账号 (国区不支持)
• GitHub 账号
• Vercel 账号 (可选，用于部署)

请先 Fork 本仓库 到你的 GitHub 账号，然后克隆你 Fork 后的仓库（不要直接 clone 上游仓库）：

# 将 YOUR_USERNAME 替换为你的 GitHub 用户名
git clone git@github.com:YOUR_USERNAME/pbRun.git
cd pbRun
npm install

macOS 用户：若 npm install 时 better-sqlite3 编译报错（如 climits file not found），请先设置 SDK 路径再安装：

SDKROOT=$(xcrun --sdk macosx --show-sdk-path) npm install

先创建 .env 并填写 Garmin 账号密码（用于获取 Token，非交互式；也可不填，运行脚本时按提示输入）：

# 在项目根目录创建 .env，至少包含（获取 Token 时使用）：
GARMIN_EMAIL=your_garmin_email@example.com
GARMIN_PASSWORD=your_garmin_password

然后运行脚本获取 Token：

python3 scripts/get_garmin_token.py

脚本会从 .env 读取 GARMIN_EMAIL / GARMIN_PASSWORD，未配置时会提示输入。将输出的 GARMIN_SECRET_STRING 填入下面 .env 中。

在 .env 中补充/保留以下变量：

# Garmin 账号（供 get_garmin_token.py 使用，重新获取 Token 时无需再输入）
GARMIN_EMAIL=your_garmin_email@example.com
GARMIN_PASSWORD=your_garmin_password

# Garmin 认证 Token（由上一步脚本输出，用于同步数据）
GARMIN_SECRET_STRING="your_token_here"

# 个人心率参数 (用于计算心率区间和 VDOT)
MAX_HR=190        # 最大心率
RESTING_HR=55     # 静息心率

# 一键同步所有历史数据
npm run init:data

# 或者手动测试同步最近 5 条记录
node scripts/sync-garmin.js --limit 5

npm run dev
# 访问 http://localhost:3000

详细部署指南请参考 部署文档

1. Fork 本仓库 到你的 GitHub 账号（点击 Fork）。后续操作都在你 Fork 的仓库中进行，不要直接在上游仓库改配置。

2. 配置 GitHub Secrets

   • 进入仓库 Settings > Secrets > Actions
   • 添加以下 Secrets:
     • GARMIN_EMAIL — Garmin 登录邮箱（用于重新获取 Token 等）
     • GARMIN_PASSWORD — Garmin 登录密码（用于重新获取 Token 等）
     • GARMIN_SECRET_STRING — 运行 python3 scripts/get_garmin_token.py 得到的 Token，同步数据时使用
     • MAX_HR — 最大心率（可选）
     • RESTING_HR — 静息心率（可选）

3. 连接 Vercel

   • 登录 Vercel
   • 导入你 Fork 的仓库
   • 自动检测 Next.js 项目，一键部署

4. 启动自动同步

   • GitHub Actions 会每日自动运行
   • 同步数据后自动提交到仓库
   • Vercel 检测到数据库更新后自动重新部署

• ✅ 活动列表 - 查看所有跑步记录，支持按月份筛选
• ✅ 活动详情 - 详细的配速、心率、海拔数据和分段信息
• ✅ 统计分析 - 月度/年度里程、跑量、个人记录
• ✅ 跑力分析 - VDOT 趋势图，追踪训练效果
• ✅ 心率区间 - 分析有氧/无氧训练占比
• ✅ 配速分布 - 识别舒适配速区间
• ✅ 训练建议 - 基于 Daniels 训练法的配速建议

garmin_data/
├── app/                    # Next.js 应用
│   ├── api/               # API 路由 (RESTful)
│   ├── list/              # 活动列表页面
│   ├── analysis/          # 数据分析页面
│   ├── stats/             # 统计页面
│   └── lib/               # 工具库 (数据库、格式化)
├── scripts/               # 数据同步脚本
│   ├── sync-garmin.js     # 主同步脚本
│   ├── fit-parser.js      # FIT 文件解析
│   ├── vdot-calculator.js # VDOT 跑力计算
│   └── db-manager.js      # 数据库操作
├── .github/workflows/     # GitHub Actions
│   └── sync_garmin_data.yml
├── app/data/              # SQLite 数据库
│   └── activities.db
└── docs/                  # 文档
    ├── deployment.md      # 部署指南
    ├── data-sync.md       # 数据同步说明
    └── api-reference.md   # API 接口文档

完整 API 文档: docs/api-reference.md

• 部署指南 - Vercel 部署和 GitHub Actions 配置
• 数据同步说明 - Garmin 数据同步原理和配置
• API 参考 - 完整的 API 接口文档
• VDOT 计算说明 - 跑力计算公式和原理
• 常见问题 - 常见问题解答

欢迎提交 Issue 和 Pull Request！

请先 Fork 本仓库，再克隆你 Fork 的仓库到本地：

# 将 YOUR_USERNAME 替换为你的 GitHub 用户名
git clone git@github.com:YOUR_USERNAME/pbRun.git
cd pbRun

# 安装依赖（macOS 若遇 better-sqlite3 编译错误，改用：SDKROOT=$(xcrun --sdk macosx --show-sdk-path) npm install）
npm install

# 启动开发服务器
npm run dev

# 运行数据验证
node scripts/validate-data.js

MIT License

如果这个项目对你有帮助，请给一个 ⭐️ Star！

• yihong0618/running_page - 本项目实现参考该开源项目（Make your own running home page）
• Jack Daniels' Running Formula - VDOT 理论基础
• Garmin Connect - 数据来源
• Next.js - Web 框架
• Vercel - 部署平台