SparkyFitness

一款以隐私为先的自托管 MyFitnessPal 替代品。追踪营养、运动、身体指标和健康数据，同时完全掌控您的数据。

SparkyFitness 是一个自托管的健身追踪平台，由以下部分组成：

• 后端服务器（API + 数据存储）
• 基于 Web 的前端
• iOS 和 Android 原生移动应用

它将健康数据存储并管理在您控制的基础设施上，无需依赖第三方服务。

核心功能

• 营养、运动、水分摄入、睡眠、禁食、情绪和身体测量的追踪
• 目标设定和每日打卡
• 交互式图表和长期报告
• 多用户个人资料和家庭共享访问权限
• 浅色与深色主题
• OIDC、TOTP、Passkey、MFA 等

健康与设备集成

SparkyFitness 可以从多个健康和健身平台同步数据：

• Apple Health（iOS）
• Google Health Connect（Android）
• Fitbit
• Garmin Connect
• Withings
• Polar Flow（部分测试）
• Hevy（未测试）
• OpenFoodFacts
• USDA
• Fatsecret
• Nutritioninx
• Mealie
• Tandoor
• Strava（部分测试）

这些集成会自动同步活动数据，如步数、锻炼和睡眠，以及健康指标，如体重和身体测量，到您的 SparkyFitness 服务器。

可选 AI 功能（测试版）

SparkyAI 提供了一个用于记录数据和回顾进展的对话式界面。

• 通过聊天记录食物、运动、身体数据和步数
• 上传食物图片以自动记录餐食
• 保留对话历史以便后续跟进

注意：AI 功能目前处于测试阶段。

快速入门（服务器）

使用 Docker Compose，您可以在几分钟内启动一个 SparkyFitness 服务器。

# 1. 创建新文件夹
mkdir sparkyfitness && cd sparkyfitness

# 2. 仅下载 Docker 文件
curl -L -o docker-compose.yml https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/docker-compose.prod.yml
curl -L -o .env https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/default.env.example

# 3. （可选）编辑 .env 文件以自定义数据库凭据、端口等。

# 4. 启动应用
docker compose pull && docker compose up -d

# 访问应用：http://localhost:8080

🎥 视频教程

一段 2 分钟的快速教程，展示如何安装 SparkyFitness（自托管健身追踪器）。

文档

有关完整的安装指南、配置选项和开发文档，请访问我们的 文档网站。

快速链接

• 安装指南 - 部署和配置
• 功能概述 - 完整的功能文档
• 开发流程 - 开发者指南和贡献流程
• iOS 应用信息 和 Android 应用信息

需要帮助？

• 在 Github 的问题/讨论区发帖。
• 如需更快响应并获得其他社区成员的帮助，请 加入我们的 Discord。

星标历史

翻译

Weblate 翻译

仓库活动

贡献者

⚠️ 已知问题 / 测试版功能 ⚠️

SparkyFitness 目前正处于积极开发中。 不同版本之间可能会出现破坏性变更。

• 不建议自动更新容器
• 升级前请务必查看发布说明

以下功能目前处于测试阶段，可能尚未经过充分测试。您可能会遇到一些 bug 或功能不完整的情况：

• AI 聊天机器人
• 家人与朋友访问权限
• API 文档

SparkyFitness 快速上手指南

SparkyFitness 是一个自托管、隐私优先的健身追踪平台，可作为 MyFitnessPal 的替代方案。它允许您在完全掌控数据的前提下，追踪营养、运动、身体指标及健康数据。

环境准备

在开始之前，请确保您的服务器满足以下要求：

• 操作系统：支持 Docker 的 Linux 发行版（如 Ubuntu, Debian, CentOS）或 macOS。
• 核心依赖：
  • Docker (推荐最新稳定版)
  • Docker Compose (通常包含在 Docker Desktop 或新版 Docker 引擎中)
• 网络要求：服务器需能访问 GitHub 以拉取镜像和配置文件。
  • 国内用户提示：若拉取 GitHub 资源缓慢，建议配置 Docker 镜像加速器（如阿里云、腾讯云等国内源），或在 hosts 文件中优化 GitHub 域名解析。

安装步骤

使用 Docker Compose 可在几分钟内完成部署。请在终端执行以下命令：

# 1. 创建项目目录并进入
mkdir sparkyfitness && cd sparkyfitness

# 2. 下载 Docker Compose 配置文件和环境变量示例
# 注意：国内网络若无法直接访问 GitHub，请使用代理或手动下载后上传
curl -L -o docker-compose.yml https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/docker-compose.prod.yml
curl -L -o .env https://github.com/CodeWithCJ/SparkyFitness/releases/latest/download/default.env.example

# 3. (可选) 自定义配置
# 编辑 .env 文件以修改数据库凭证、端口号等设置
# nano .env  或  vim .env

# 4. 拉取镜像并启动服务
docker compose pull && docker compose up -d

启动完成后，应用将在 http://localhost:8080 运行。若通过远程服务器访问，请将 localhost 替换为服务器 IP 地址。

基本使用

1. 初始化账户： 在浏览器中访问 http://<您的服务器 IP>:8080，按照页面指引创建管理员账户。

2. 记录数据： 登录后，您即可在 Web 端或通过移动端 App（iOS/Android）开始记录：

   • 营养与饮食：手动输入或通过集成的数据库（如 OpenFoodFacts, USDA）搜索食物。
   • 运动与健康：记录锻炼、睡眠、体重及身体围度。
   • 设备同步：在设置中绑定 Apple Health、Google Health Connect、Fitbit 或 Garmin 等设备，自动同步步数、卡路里及睡眠数据。

3. 体验 AI 功能 (Beta)： 进入聊天界面，尝试使用自然语言记录数据（例如：“我刚才吃了两个苹果”或“上传食物照片”）。系统会自动解析并录入相关信息。

注意：本项目处于活跃开发阶段，部分功能（如 AI 聊天、家庭共享）标记为 Beta 版本。升级前请务必阅读发布说明，且不建议开启容器自动更新，以免发生破坏性变更。