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

核心功能概览

Garmin Grafana 是一个开源健康数据可视化平台，能够从 Garmin Connect 账户获取健康数据，存储到 InfluxDB 时序数据库，并通过 Grafana 仪表板展示长期健康趋势。该项目采用 Python 脚本实现数据采集，结合容器化部署方案，为用户提供完整的健康数据监控解决方案。

项目核心组件解析

项目包含以下关键组件，各自承担不同功能角色：

• 数据采集层：src/garmin_grafana/garmin_fetch.py 负责从 Garmin Connect API 获取健康数据，garmin_bulk_importer.py 提供历史数据批量导入功能
• 数据存储层：InfluxDB（时序数据库，用于存储时间序列数据）负责数据持久化，相关配置位于 Grafana_Datasource/influxdb.yaml
• 可视化层：Grafana_Dashboard/ 目录下的 JSON 和 YAML 文件定义了完整的健康数据仪表板
• 部署配置层：docker-compose.yml（容器编排配置）、easy-install.sh（一键部署脚本）和 k8s/（Kubernetes 部署方案）提供多种部署选项

环境部署指南

基础环境准备

在开始部署前，请确保系统已安装以下软件：

• Docker（容器化平台，用于运行应用组件）
• Docker Compose（容器编排工具，用于管理多容器应用）
• Git（版本控制工具，用于获取项目代码）

一键部署流程

🔧 获取项目代码

git clone https://gitcode.com/gh_mirrors/ga/garmin-grafana
cd garmin-grafana
# 执行说明：克隆项目仓库并进入项目目录，预期输出为仓库文件列表

🔧 使用部署脚本

chmod +x easy-install.sh
./easy-install.sh
# 执行说明：赋予脚本执行权限并运行一键安装脚本，预期输出为部署进度信息和最终成功提示

容器状态验证方法

🔧 检查容器运行状态

docker-compose ps
# 执行说明：查看所有服务容器状态，预期输出包含 garmin-fetch-data、influxdb 和 grafana 三个容器，状态均为 Up

🔧 验证服务可用性

curl http://localhost:3000/api/health
# 执行说明：检查 Grafana 服务健康状态，预期输出 {"database":"ok","version":"x.x.x"}

个性化配置详解

基础配置项设置

通过修改 compose-example.yml 文件并另存为 docker-compose.yml 进行基础配置，关键配置项如下：

配置项	默认值	建议值	说明
INFLUXDB_HOST	influxdb	influxdb	InfluxDB 服务地址
INFLUXDB_PORT	8086	8086	InfluxDB 服务端口
INFLUXDB_DATABASE	garmin	garmin	数据库名称
UPDATE_INTERVAL_SECONDS	3600	1800	数据更新间隔（秒）
LOG_LEVEL	INFO	INFO	日志级别（INFO/DEBUG）

🔧 创建自定义配置

cp compose-example.yml docker-compose.yml
nano docker-compose.yml
# 执行说明：复制示例配置并编辑，设置 Garmin 账户信息和其他必要参数

高级调优选项

对于有特定需求的用户，可以进行以下高级配置：

🔧 持久化存储配置

volumes:
  garmin_tokens_data:
    driver: local
    driver_opts:
      type: none
      device: /path/to/local/directory
      o: bind
# 执行说明：在 docker-compose.yml 中添加此配置，将令牌数据存储到本地目录，避免容器重启后登录状态丢失

🔧 性能优化设置

environment:
  - BATCH_SIZE=500
  - RETRY_LIMIT=3
  - TIMEOUT=30
# 执行说明：调整数据批量处理大小、重试次数和超时时间，优化数据同步性能

常见问题解决

登录与认证问题

⚠️ Garmin 登录失败

• 确保 GARMINCONNECT_EMAIL 和 GARMINCONNECT_BASE64_PASSWORD 配置正确
• Base64 密码生成方法：echo -n "your_password" | base64
• 尝试删除 garmin_tokens_data 卷数据后重新登录

数据同步问题

⚠️ 数据不更新

1. 检查容器日志：docker-compose logs garmin-fetch-data
2. 验证网络连接：docker exec -it garmin-fetch-data ping api.garmin.com
3. 确认更新间隔设置：grep UPDATE_INTERVAL_SECONDS docker-compose.yml

仪表板显示问题

⚠️ Grafana 无数据显示

1. 检查 InfluxDB 连接：docker exec -it influxdb influx -database garmin -execute "SHOW MEASUREMENTS"
2. 验证数据源配置：访问 Grafana → Configuration → Data Sources → InfluxDB
3. 导入仪表板：Grafana → Dashboards → Import → 上传 Grafana_Dashboard/Garmin-Grafana-Dashboard.json

功能扩展建议

1. 健康指标扩展

通过修改 fit_activity_importer.py 添加新的健康指标解析，如：

• 睡眠质量分析
• 心率变异性(HRV)监测
• 训练负荷评估

实现思路：扩展数据解析函数，添加新的 InfluxDB 数据点写入逻辑，更新 Grafana 仪表板添加相应图表。

2. 数据导出功能

开发数据导出模块，支持将健康数据导出为多种格式：

def export_to_csv(measurement, start_date, end_date, filename):
    """导出指定时间范围的测量数据到CSV文件"""
    # 实现InfluxDB查询和CSV写入逻辑
# 执行说明：添加此函数到influxdb_exporter.py，可实现健康数据的离线分析

3. 移动设备访问优化

开发响应式 Grafana 仪表板，优化移动设备访问体验：

1. 创建移动友好的仪表板布局
2. 添加触控优化的交互组件
3. 实现数据缓存机制减少移动端流量消耗

通过这些扩展，可以使 Garmin Grafana 平台更符合个人健康管理需求，提供更丰富的数据洞察和使用体验。