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

准备工作：环境检查三步骤

如何确保启动前环境就绪？在开始使用 Garmin Grafana 平台前，需要完成三项关键准备工作，确保系统环境满足运行要求。

1. 环境依赖确认

首先需检查本地是否已安装 Docker 和 Docker Compose。这两个工具是项目运行的基础，Docker 用于容器化部署应用，Docker Compose 则负责协调多容器服务。可通过以下命令验证安装状态：

docker --version  # 检查Docker版本
docker-compose --version  # 检查Docker Compose版本

2. 项目获取与文件准备

从仓库克隆项目代码到本地：

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

3. 核心文件功能速查表

项目包含多个关键文件，了解它们的作用有助于后续配置与使用：

文件路径	功能描述
compose-example.yml	Docker Compose 配置示例，定义服务组件关系
src/garmin_grafana/garmin_fetch.py	核心数据获取脚本，负责从 Garmin 服务器拉取健康数据
Grafana_Dashboard/Garmin-Grafana-Dashboard.json	Grafana 仪表板配置文件，包含健康数据可视化模板
Grafana_Datasource/influxdb.yaml	InfluxDB 数据源配置，定义 Grafana 与数据库的连接方式

核心功能：数据流转全解析

如何实现健康数据从采集到可视化的完整流程？Garmin Grafana 平台通过三大核心组件协同工作，实现数据的获取、存储与展示。

1. 服务启动与容器编排

项目采用 Docker Compose 实现多容器协调。首先需要将示例配置文件复制为实际配置文件：

cp compose-example.yml docker-compose.yml

然后启动所有服务组件：

docker-compose up -d  # -d参数表示后台运行模式

该命令会启动三个核心服务：

• garmin-fetch-data：运行数据获取脚本的容器
• influxdb：InfluxDB（时序数据库）容器，用于存储时间序列健康数据
• grafana：Grafana 容器，提供数据可视化界面

2. 数据采集流程解析

数据从 Garmin 服务器到 Grafana 仪表板的流转过程如下：

1. garmin_fetch.py 脚本通过 Garmin Connect API 认证并获取用户健康数据
2. 数据经过处理后存储到 InfluxDB 数据库
3. Grafana 通过配置好的数据源连接 InfluxDB，读取数据并渲染仪表板

3. 常见启动问题排查

启动过程中可能遇到以下问题，可按对应方法解决：

问题现象	可能原因	解决方法
容器启动后立即退出	环境变量配置错误	检查 docker-compose.yml 中的环境变量是否完整
InfluxDB 连接失败	数据库服务未就绪	确认 influxdb 服务是否正常运行，可通过 docker logs influxdb 查看日志
Garmin 数据获取失败	认证信息错误	检查 Garmin 账户邮箱和密码是否正确配置

个性化配置：参数调优与安全加固

如何根据个人需求调整系统行为并保障数据安全？通过合理配置参数和安全措施，可以让平台更符合使用习惯并保护敏感信息。

1. 关键参数对照表

docker-compose.yml 文件中的核心配置参数及其说明：

参数名称	作用描述	建议值
INFLUXDB_HOST	InfluxDB 服务地址	influxdb（容器名）
INFLUXDB_DATABASE	数据库名称	garmin_health
GARMINCONNECT_EMAIL	Garmin 账户邮箱	个人 Garmin 注册邮箱
GARMINCONNECT_BASE64_PASSWORD	Base64 编码的密码	使用 `echo -n "password"
UPDATE_INTERVAL_SECONDS	数据更新间隔（秒）	3600（每小时更新一次）
LOG_LEVEL	日志详细程度	INFO（普通模式）或 DEBUG（调试模式）

2. 安全配置建议

为保护个人健康数据和账户安全，建议采取以下措施：

• 密码安全：定期更新 Garmin 账户密码，并使用强密码
• 令牌持久化：配置 garmin_tokens_data 卷以保存登录令牌，避免频繁重新认证
• 网络隔离：限制 Grafana 服务的访问端口，仅允许本地或信任网络访问
• 数据备份：定期备份 InfluxDB 数据目录，防止数据丢失

3. 仪表板个性化展示

Grafana 仪表板支持高度自定义，可通过以下方式调整展示效果：

1. 登录 Grafana 界面（默认地址：http://localhost:3000）
2. 导入 Grafana_Dashboard/Garmin-Grafana-Dashboard.json 文件
3. 根据个人需求调整图表布局、时间范围和数据指标

图：Garmin Grafana 仪表板预览，展示多种健康数据指标的可视化效果

通过以上配置，您可以搭建一个功能完善的个人健康数据监控系统，长期跟踪运动、睡眠等健康指标趋势。系统的模块化设计也使得未来扩展新的数据类型或可视化方式变得简单。