Garmin数据可视化从零开始：健康数据监控平台搭建指南

1. 项目快速上手：核心功能与目录解析

Garmin-Grafana是一个开源健康数据监控解决方案，通过Python脚本从Garmin Connect获取健康数据，存储到InfluxDB时序数据库，并通过Grafana实现长期健康趋势可视化。项目采用容器化架构，支持多环境部署，核心功能包括：健康数据自动抓取、时间序列数据存储、自定义仪表板展示。

项目主要目录结构：

• src/：核心Python代码，包含Garmin数据抓取（garmin_fetch.py）、InfluxDB数据导出（influxdb_exporter.py）等模块
• Grafana_Dashboard/：仪表板配置文件，包含JSON和YAML两种格式的配置
• k8s/：Kubernetes部署模板，支持生产环境容器编排
• Grafana_Datasource/：InfluxDB数据源配置文件

2. 3步完成容器部署：从环境准备到服务启动

步骤1：环境准备与代码获取

确保本地已安装Docker和Docker Compose。通过以下命令克隆项目代码：

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

步骤2：配置文件准备

复制示例配置文件并修改必要参数：

cp compose-example.yml docker-compose.yml

该文件定义了三个核心服务：

• garmin-fetch-data：负责从Garmin服务器获取健康数据
• influxdb：时序数据库服务，存储健康指标
• grafana：可视化仪表板服务，展示健康趋势

步骤3：启动服务集群

使用Docker Compose启动所有服务：

docker-compose up -d

首次启动会自动拉取所需镜像并初始化数据库，服务启动后可通过docker-compose ps检查服务状态。

3. 参数配置详解：环境变量与最佳实践

核心配置参数说明

在docker-compose.yml中需要配置以下关键环境变量：

environment:
  # InfluxDB数据库配置
  - INFLUXDB_HOST=influxdb
  - INFLUXDB_PORT=8086
  - INFLUXDB_USERNAME=admin
  - INFLUXDB_PASSWORD=securepassword
  - INFLUXDB_DATABASE=garmin_health
  
  # Garmin账户配置
  - GARMINCONNECT_EMAIL=[e-mail]
  - GARMINCONNECT_BASE64_PASSWORD=base64_encoded_password
  
  # 系统配置
  - UPDATE_INTERVAL_SECONDS=3600  # 每小时更新一次数据
  - LOG_LEVEL=INFO  # 生产环境建议使用INFO级别

配置项最佳实践

1. 密码安全：Base64编码密码可通过echo -n "your_password" | base64生成，避免明文存储
2. 更新间隔：根据数据需求调整，运动爱好者建议设为1800秒（30分钟），普通用户可设为3600秒（1小时）
3. 存储优化：InfluxDB建议配置数据保留策略，避免磁盘空间溢出
4. 日志管理：调试时设为DEBUG级别，生产环境切换为INFO以减少日志量

4. 数据可视化实践：仪表板导入与自定义

仪表板导入步骤

1. 访问Grafana界面（默认地址：http://localhost:3000）
2. 使用默认账号admin/admin登录，首次登录需修改密码
3. 进入"Dashboard" → "Import"，上传Grafana_Dashboard/Garmin-Grafana-Dashboard.json文件
4. 选择InfluxDB数据源，完成导入

仪表板功能介绍

导入后的仪表板包含多维度健康数据展示：

主要可视化组件包括：

• 心率趋势图：展示静息心率和运动心率变化
• 睡眠分析：深度睡眠/浅度睡眠周期分布
• 活动地图：GPS轨迹可视化与运动路径分析
• 生理指标：步数、卡路里消耗、爬楼层数等日常活动数据
• 训练效果：运动强度分布与恢复建议

5. 常见问题排查：从数据获取到可视化全流程

数据获取类问题

问题1：Garmin数据无法获取

• 检查网络连接：确认容器可访问Garmin Connect服务器
• 验证凭据：通过docker-compose logs garmin-fetch-data查看登录错误
• 令牌持久化：确保garmin_tokens_data卷正确挂载，避免重复登录

问题2：数据更新不及时

• 检查UPDATE_INTERVAL_SECONDS配置值
• 查看日志确认数据抓取任务是否正常执行
• 验证InfluxDB写入权限和磁盘空间

可视化类问题

问题1：Grafana无数据显示

• 检查数据源配置：确认InfluxDB连接参数正确
• 验证数据库存在性：通过docker exec -it influxdb influx进入数据库检查
• 时间范围设置：确认Grafana查询时间范围包含有效数据

问题2：仪表板加载缓慢

• 优化查询：减少时间范围或降低数据采样频率
• 调整面板数量：拆分复杂仪表板为多个专项视图
• 升级硬件：对于大量历史数据，建议增加InfluxDB内存分配

6. 高级部署选项：Kubernetes集群配置

对于企业级部署，可使用项目提供的Kubernetes配置文件：

cd k8s
make deploy  # 基于values.yaml配置部署整个应用栈

Kubernetes部署优势：

• 自动扩缩容：根据数据量动态调整资源
• 高可用性：多副本部署确保服务不中断
• 滚动更新：支持无停机升级应用版本

配置文件位于k8s/templates/目录，包含部署清单、服务定义和持久卷配置，可根据实际环境调整资源需求和网络策略。