Garmin Grafana 健康数据可视化平台使用指南

🔍 功能概览

Garmin Grafana 是一个开源健康数据可视化解决方案，通过 Python 脚本从 Garmin Connect 平台获取健康数据，存储到 InfluxDB（时序数据库）中，并通过 Grafana 仪表板实现长期健康趋势的可视化分析。该项目支持心率、睡眠质量、活动轨迹等多维度健康数据的采集与展示，帮助用户建立个性化健康管理体系。

📌 环境准备

硬件要求

• 最低配置：2核CPU/4GB内存/10GB可用磁盘空间
• 推荐配置：4核CPU/8GB内存/20GB SSD存储

软件依赖

• Docker Engine 20.10+（容器化运行环境）
• Docker Compose 2.0+（多容器编排工具）
• Git（版本控制工具）

环境检查

# 验证Docker是否安装
docker --version
# 验证Docker Compose是否安装
docker compose version

执行效果：成功输出版本号即表示环境就绪，若提示"command not found"需先安装对应组件

📋 核心文件功能速查表

文件路径	类型	核心功能
src/garmin_grafana/garmin_fetch.py	Python脚本	从Garmin Connect API获取健康数据
src/garmin_grafana/influxdb_exporter.py	Python脚本	将数据格式化并写入InfluxDB
Grafana_Dashboard/Garmin-Grafana-Dashboard.json	配置文件	Grafana可视化仪表板定义
compose-example.yml	Docker配置	容器服务组合模板
easy-install.sh	脚本文件	快速部署工具
k8s/	目录	Kubernetes部署配置集

⚙️ 配置指南

基础配置文件准备

1. 复制示例配置文件

cp compose-example.yml docker-compose.yml

2. 核心配置参数说明

参数名称	必填/可选	默认值	推荐值	安全注意事项
INFLUXDB_HOST	必填	influxdb	influxdb	容器内服务名，无需修改
INFLUXDB_PORT	可选	8086	8086	保持默认端口
INFLUXDB_USERNAME	必填	admin	自定义用户名	避免使用默认值
INFLUXDB_PASSWORD	必填	admin123	强密码	至少8位，包含大小写字母和特殊符号
GARMINCONNECT_EMAIL	必填	-	你的Garmin邮箱	确保账户已开启API访问权限
GARMINCONNECT_BASE64_PASSWORD	必填	-	Base64编码的密码	使用`echo -n "密码"
UPDATE_INTERVAL_SECONDS	可选	3600	1800	建议间隔30-60分钟
LOG_LEVEL	可选	INFO	INFO	调试时设为DEBUG

⚠️ 安全提示：所有敏感配置不应提交到版本控制系统，生产环境建议使用环境变量或密钥管理服务

常见配置问题

❓ Q: 如何生成Base64编码的密码？
A: 在终端执行echo -n "your_password" | base64，输出结果即为编码后的密码

❓ Q: 数据存储路径如何自定义？
A: 在docker-compose.yml中修改volumes配置，如./data/influxdb:/var/lib/influxdb

🚀 启动流程

1. 前置检查

• 确保8086（InfluxDB）、3000（Grafana）端口未被占用
• 网络连接正常，能访问Garmin Connect服务器
• 配置文件中必填项已正确设置

2. 启动命令解析

# 构建并启动服务（首次运行）
docker compose up -d --build

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f garmin-fetch-data

执行效果：当看到"Successfully fetched and stored data"日志时，表示数据采集服务正常运行

3. 状态验证

• InfluxDB验证：访问http://localhost:8086，能打开管理界面
• Grafana验证：访问http://localhost:3000，使用默认账号admin/admin登录
• 数据验证：在Grafana中导入Grafana_Dashboard/Garmin-Grafana-Dashboard.json，查看是否有数据展示

📊 仪表板使用指南

导入仪表板后，你将看到一个包含多维度健康数据的综合视图，主要包括：

核心指标区域

• 心率趋势：24小时心率变化曲线与静息心率统计
• 睡眠分析：睡眠阶段分布与睡眠质量评分
• 活动概览：每日步数、卡路里消耗与活动类型占比
• 训练详情：运动轨迹、配速、心率区间分布

数据筛选功能

使用仪表板顶部的时间选择器可查看不同时间段的数据，支持按日、周、月、年等维度筛选。通过变量选择器可切换不同的健康指标视图。

⚠️ 避坑指南

1. Garmin API访问限制

   • 问题：频繁获取数据导致API暂时封禁
   • 解决：将UPDATE_INTERVAL_SECONDS设置为1800秒以上，避免短时间内多次请求

2. InfluxDB数据持久化

   • 问题：容器重启后数据丢失
   • 解决：确保docker-compose.yml中正确配置了InfluxDB数据卷映射

3. Grafana插件依赖

   • 问题：部分图表无法正常显示
   • 解决：在Grafana插件管理中安装"Pie Chart"和"Worldmap Panel"插件

🔧 故障排查流程图

1. 服务未启动 → 检查docker-compose.yml语法 → 查看容器日志 → 检查端口占用
2. 数据不更新 → 验证Garmin账号凭证 → 检查网络连接 → 查看fetch服务日志
3. 仪表板无数据 → 检查InfluxDB连接 → 验证数据写入权限 → 确认时间范围选择

📝 总结

Garmin Grafana项目通过容器化部署简化了健康数据的采集、存储与可视化流程。按照本指南配置后，你将获得一个功能完备的个人健康数据分析平台。建议定期备份InfluxDB数据目录，并根据使用情况调整数据采集频率以平衡数据新鲜度与API调用限制。

如需进一步定制，可以修改Python采集脚本扩展数据类型，或调整Grafana仪表板布局以满足个性化需求。项目的Kubernetes配置文件也为大规模部署提供了支持方案。