SparkyFitness：自托管家庭健康追踪平台

项目简介

SparkyFitness 是一个自托管、注重隐私的健康与健身追踪平台，定位为 MyFitnessPal、Flo、Hevy 等服务的替代方案。它由后端服务（API + 数据存储）、Web 前端、iOS / Android 原生应用，以及 Apple Watch 和 Wear OS 配套应用组成，所有健康数据都存放在你自己控制的服务器上，不依赖第三方服务。

项目使用 TypeScript 编写，面向希望把全家人的饮食、运动、睡眠、用药等记录集中管理，同时又不愿把数据交给商业 App 的用户。

主要功能

• 多维度记录：营养、运动、饮水、睡眠、断食、情绪和身体围度测量
• 目标与打卡：设定健康目标并进行每日打卡
• 手表应用：Apple Watch 与 Wear OS 应用支持目标、饮水、体重、断食、用药、训练及表盘复杂功能
• 报表图表：交互式图表与长期趋势报告
• 家庭共享：多用户档案与家庭访问权限
• 界面外观：浅色与深色主题
• 安全认证：支持 OIDC、TOTP、Passkey、MFA 等登录方式
• 数据导入导出：CSV 导入与免费数据导出
• 健康平台同步：可对接 Apple Health、Google Health Connect、Fitbit、Garmin Connect、Withings、Polar Flow、Oura、Hevy、Strava、COROS、Intervals.ICU 等平台，自动同步步数、训练、睡眠、体重等数据
• 食物数据库：接入 OpenFoodFacts、USDA、Fatsecret、Nutritionix、Mealie、Tandoor、Swiss Food Database 等来源
• SparkyAI（Beta）：对话式记录饮食、运动、身体数据和步数，可上传食物图片自动记录，并保留对话历史以便追问

安装与使用

推荐使用 Docker Compose 自托管部署：

mkdir sparkyfitness && cd sparkyfitness
curl -L -o docker-compose.yml https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/docker-compose.prod.yml
curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.simple.example
docker compose pull && docker compose up -d

启动后访问 http://localhost:3004 即可使用。

配置文件中的占位符必须替换，否则服务会拒绝启动，包括 SPARKY_FITNESS_DB_PASSWORD、SPARKY_FITNESS_API_ENCRYPTION_KEY、BETTER_AUTH_SECRET 和 SPARKY_FITNESS_FRONTEND_URL。密钥可用 openssl rand -hex 32、openssl rand -base64 32 生成；也可以在浏览器中使用官方提供的 .env 生成器 一键生成。

如果需要反向代理、SSO、SMTP 或外部数据库等完整配置，可参考 .env.example 与 文档站。

非技术用户也可以选择第三方托管服务（如 PikaPods、Zenith），这些属于独立第三方平台。

注意事项

• SparkyFitness 属于 source-available 而非开源项目，许可证为非商业用途，商业使用需获得授权。
• SparkyAI 等 AI 功能目前处于 Beta 阶段。
• 升级前请务必备份数据库与环境配置。
• 睡眠分期、HRV、血糖等指标由手表、手机或测量设备导入，SparkyFitness 负责存储、分析和绘图，本身不做测量。
• 部分集成（如 Yazio）使用非官方 API，稳定性由第三方决定。

本作品整理自 GitHub 开源项目 CodeWithCJ/SparkyFitness，原作者 @CodeWithCJ。中文介绍由 AI 根据项目 README 整理，以原仓库为准。