Garmin-Grafana实战指南：从部署到定制的全流程解析

核心功能概览

Garmin-Grafana项目是一套健康数据可视化解决方案，通过Python脚本从Garmin服务器获取健康数据，存储到InfluxDB数据库，并利用Grafana构建直观的数据仪表板。该方案实现了健康数据的长期追踪与多维度分析，支持运动轨迹、心率变化、睡眠质量等18类健康指标的可视化呈现。

快速启动流程

准备运行环境

🔧 克隆项目代码库

git clone https://gitcode.com/gh_mirrors/ga/garmin-grafana
cd garmin-grafana

执行效果：在本地创建项目目录并下载全部源代码文件。

🔧 配置基础环境

cp compose-example.yml docker-compose.yml

执行效果：复制示例配置文件作为实际运行配置。

启动服务集群

🔧 启动容器服务

docker-compose up -d

执行效果：后台启动三个服务容器（数据采集器、InfluxDB数据库、Grafana仪表板），首次运行将自动拉取所需镜像。

⚠️ 注意事项：首次启动需等待3-5分钟，期间系统将完成数据库初始化和仪表板配置。可通过docker-compose logs -f命令查看实时启动进度。

个性化配置指南

定制化环境变量配置

核心配置文件为docker-compose.yml，主要环境变量配置建议：

配置项	场景化建议	安全处理
GARMINCONNECT_EMAIL	使用Garmin官网注册邮箱	避免明文存储，建议使用环境变量注入
GARMINCONNECT_BASE64_PASSWORD	使用`echo -n "密码"	base64`生成加密串
UPDATE_INTERVAL_SECONDS	日常使用建议设为3600（每小时更新）	-
LOG_LEVEL	调试时设为DEBUG，稳定运行时设为INFO	-

🔧 修改配置示例

environment:
  - GARMINCONNECT_EMAIL=[e-mail]
  - GARMINCONNECT_BASE64_PASSWORD=dXNlcjEycMzQ=  # 替换为实际Base64加密密码
  - UPDATE_INTERVAL_SECONDS=3600
  - LOG_LEVEL=INFO

数据持久化配置

🔧 配置令牌持久化

volumes:
  - garmin_tokens_data:/app/tokens

作用说明：保存Garmin登录令牌，避免频繁重新验证。

⚠️ 安全提示：令牌文件包含敏感认证信息，需确保garmin_tokens_data卷权限设置为700，仅允许所有者访问。

目录解析

核心功能目录

• src/garmin_grafana/：数据处理核心模块

  • garmin_fetch.py：实现Garmin API数据拉取
  • influxdb_exporter.py：处理数据存储逻辑
  • fit_activity_importer.py：解析运动活动文件

• Grafana_Dashboard/：可视化配置中心

  • Garmin-Grafana-Dashboard.json：完整仪表板配置
  • Garmin-Grafana-Dashboard.yaml：YAML格式配置文件

• k8s/：容器编排支持

  • 包含部署模板、服务配置和持久卷定义，支持Kubernetes环境部署

辅助工具目录

• docs/：项目文档集合，包含手动导入指南
• Extra/：辅助工具集，提供Jupyter Notebook格式的数据处理脚本
• Grafana_Datasource/：数据源配置模板，简化InfluxDB连接设置

常见问题解决

数据同步失败

症状：Grafana面板无数据显示 排查步骤：

1. 检查容器运行状态：docker-compose ps
2. 查看数据采集日志：docker-compose logs garmin-fetch-data
3. 验证Garmin账户状态：登录Garmin官网确认账号正常

仪表板导入失败

解决方法： 🔧 手动导入仪表板

1. 登录Grafana（默认地址：http://localhost:3000）
2. 导航至"Dashboard > Import"
3. 上传Grafana_Dashboard/Garmin-Grafana-Dashboard.json文件
4. 选择InfluxDB数据源完成配置

⚠️ 注意：确保InfluxDB服务已正常运行且数据源配置正确。

通过以上步骤，您可以快速部署并定制Garmin-Grafana健康数据可视化系统，实现个人健康数据的长期追踪与科学分析。系统支持按需扩展，可根据个人需求添加更多健康指标的采集与展示。