thisisarpanghosh/garmin-fetch-data

Garmin Grafana

镜像概述和主要用途

Garmin Grafana是一个Docker容器套件，用于从Garmin服务器自动获取健康数据并存储到本地InfluxDB数据库，最终通过Grafana实现直观的数据可视化。该项目专为Garmin设备用户设计，帮助用户全面跟踪和分析个人健康指标。

Fitbit用户请注意：请查看适用于Fitbit的https://github.com/arpanghosh8453/fitbit-grafana%E3%80%82

仪表板示例

!https://github.com/arpanghosh8453/garmin-grafana/blob/main/Grafana_Dashboard/Garmin-Grafana-Dashboard-Preview.png?raw=true

核心功能和特性

• 自动从Garmin收集数据：定期自动获取，无需手动操作
• 全面的健康指标采集，包括：
  • 心率数据
  • 每小时步数热力图
  • 每日步数统计
  • 睡眠数据及模式（血氧饱和度、呼吸频率、睡眠动作、心率变异性）
  • 睡眠规律性热力图（可视化睡眠习惯）
  • 压力数据
  • 身体电量（Body Battery）数据
  • 卡路里消耗
  • 睡眠分数
  • 活动分钟数及心率区间
  • 活动时间线（ workouts）
  • 运动GPS数据（轨迹、配速、海拔、心率）
  • 以及更多...
• 定期自动数据获取：设置后无需干预
• 历史数据回填：支持获取过去的历史数据

使用场景和适用范围

适用于所有Garmin设备用户，尤其是希望：

• 全面跟踪个人健康数据（心率、睡眠、活动等）
• 通过可视化仪表板直观分析健康趋势
• 实现数据本地化存储和管理
• 自动化数据采集，无需手动导出/导入

详细使用方法和配置说明

前置要求

需先安装Docker。Docker支持所有主流平台/操作系统，请参考Docker安装指南。

Docker安装步骤（推荐）

详细且更新的安装说明可参考https://github.com/arpanghosh8453/garmin-grafana%E3%80%82

1. 准备目录

创建主目录并进入：

bash
mkdir garmin-fetch-data && cd garmin-fetch-data

创建令牌存储目录并设置权限：

bash
mkdir garminconnect-tokens
chown -R 1000:1000 garminconnect-tokens

2. 创建compose.yml文件

在garmin-fetch-data目录下创建compose.yml文件，内容如下（根据需要修改环境变量）：

yaml
services:
  garmin-fetch-data:
    restart: unless-stopped
    image: thisisarpanghosh/garmin-fetch-data:latest
    container_name: garmin-fetch-data
    depends_on:
      - influxdb
    volumes:
      - ./garminconnect-tokens:/home/appuser/.garminconnect  # 持久化存储令牌（需确保目录属主为1000:1000）
    environment:
      - INFLUXDB_HOST=influxdb
      - INFLUXDB_PORT=8086
      - INFLUXDB_USERNAME=influxdb_user  # 需对INFLUXDB_DATABASE有读写权限
      - INFLUXDB_PASSWORD=influxdb_secret_password
      - INFLUXDB_DATABASE=GarminStats
      - GARMINCONNECT_EMAIL=your_garminconnect_email  # 可选，详见设置文档
      - GARMINCONNECT_BASE64_PASSWORD=your_base64_encoded_garminconnect_password  # 可选，密码需Base64编码
      - GARMINCONNECT_IS_CN=False  # 中国大陆Garmin-cn用户需设为True（默认False）
      # 以下为可选环境变量，修改前请阅读文档
      # - LOG_LEVEL=INFO  # 设为DEBUG可获取调试日志
      # - UPDATE_INTERVAL_SECONDS=300  # 默认更新间隔5分钟
      # - FETCH_ADVANCED_TRAINING_DATA=False  # 设为True获取高级训练数据（实验性功能）
      # - KEEP_FIT_FILES=False  # 设为True保存FIT文件
      # - ALWAYS_PROCESS_FIT_FILES=False  # 设为True处理无GPS数据的FIT文件
      # - USER_TIMEZONE=""  # 手动设置时区（默认自动获取）
      # - INFLUXDB_ENDPOINT_IS_HTTP=True  # 设为False使用HTTPS连接InfluxDB
      # - FORCE_REPROCESS_ACTIVITIES=False  # 设为True重新处理已处理的FIT文件

  influxdb:
    restart: unless-stopped
    container_name: influxdb
    hostname: influxdb
    environment:
      - INFLUXDB_DB=GarminStats
      - INFLUXDB_USER=influxdb_user
      - INFLUXDB_USER_PASSWORD=influxdb_secret_password
      - INFLUXDB_DATA_INDEX_VERSION=tsi1
    ports:
      - '8086:8086'
    volumes:
      - influxdb_data:/var/lib/influxdb
    image: 'influxdb:1.11'

  grafana:
    restart: unless-stopped
    container_name: grafana
    hostname: grafana
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_PLUGINS_PREINSTALL=marcusolsson-hourly-heatmap-panel
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - '3000:3000'
    image: 'grafana/grafana:latest'

volumes:
  influxdb_data:
  grafana_data:

3. 初始登录（针对启用2FA或未设置环境变量的情况）

若未设置GARMINCONNECT_EMAIL和GARMINCONNECT_BASE64_PASSWORD，或启用了2FA，需先执行以下命令进行交互式登录：

bash
docker pull thisisarpanghosh/garmin-fetch-data:latest && docker compose run --rm garmin-fetch-data

按提示输入Garmin***、密码（输入时可见，确保隐私环境）和2FA验证码。登录成功后，认证令牌将存储在garminconnect-tokens目录，有效期约1年，无需重复登录。

4. 启动服务

bash
docker compose up -d  # 后台启动服务
docker compose logs --follow  # 查看日志，排查潜在错误

5. Grafana配置

1. 访问http://localhost:3000，使用默认账号admin/admin登录
2. 添加InfluxDB数据源：
   • 地址：http://influxdb:8086（注意：使用容器名influxdb而非localhost）
   • 数据库名：GarminStats
   • 用户名/密码：与compose.yml中influxdb的INFLUXDB_USER和INFLUXDB_USER_PASSWORD一致
3. 导入仪表板：
   • 方法1：下载https://github.com/arpanghosh8453/garmin-grafana/blob/main/Grafana_Dashboard/Garmin-Grafana-Dashboard.json%E5%AF%BC%E5%85%A5
   • 方法2：使用导入代码23245直接从Grafana云获取

6. 安装Heatmap插件

Grafana仪表板中的热力图面板需安装插件：

bash
docker exec -it grafana grafana cli plugins install marcusolsson-hourly-heatmap-panel
docker restart grafana

7. 中国大陆用户配置

Garmin-cn用户需在garmin-fetch-data的环境变量中设置：

yaml
- GARMINCONNECT_IS_CN=True

历史数据回填

如需获取过去数据，执行以下命令（替换YYYY-MM-DD为实际日期）：

bash
docker compose run --rm -e MANUAL_START_DATE=YYYY-MM-DD -e MANUAL_END_DATE=YYYY-MM-DD garmin-fetch-data

• MANUAL_END_DATE可选，默认当前日期
• 数据按逆时间顺序获取（从结束日期到开始日期）
• 完成后自动退出，再执行docker compose up -d恢复定期更新

版本更新

bash
cd garmin-fetch-data  # 进入compose.yml所在目录
docker compose pull  # 拉取最新镜像
docker compose down && docker compose up -d  # 重启服务
docker compose logs --follow  # 验证更新是否成功

数据库备份

建议定期备份InfluxDB数据，以下脚本可创建备份：

bash
#!/bin/bash
TIMESTAMP=$(date +%F_%H-%M)
BACKUP_DIR="./influxdb_backups/$TIMESTAMP"
mkdir -p "$BACKUP_DIR"
docker exec influxdb influxd backup -portable -db GarminStats /tmp/influxdb_backup
docker cp influxdb:/tmp/influxdb_backup "$BACKUP_DIR"
docker exec influxdb rm -r /tmp/influxdb_backup

恢复备份时，将备份文件复制到容器内，执行：

bash
docker exec influxdb influxd restore -portable -db GarminStats /path/to/backup/directory

详细备份恢复指南参考influxDB官方文档。

故障排除

• 429 Client Error：IP被Garmin临时限制，可等待几小时、切换网络或使用手机热点重试
• 401 Client Error：检查账号密码是否正确，环境变量密码需Base64编码；关闭***后重试
• 权限问题：确保garminconnect-tokens目录属主为1000:1000，或使用chmod -R 777 garminconnect-tokens临时解决
• 活动详情不显示：在Grafana变量设置中，确保数据源正确，查询为SHOW TAG VALUES FROM "ActivityGPS" WITH KEY = "ActivitySelector" WHERE $timeFilter
• 令牌过期：约1年后需重新登录，执行docker compose run --rm garmin-fetch-data重新认证

环境变量说明

依赖项目

• https://github.com/cyberjunky/python-garminconnect%EF%BC%9AGarmin Web API封装
• https://github.com/matin/garth%EF%BC%9AGarmin SSO认证库

致谢

本项目由r/garmin社区众筹支持开发，感谢社区用户的慷慨***和信任！