SparkyFitness 自托管健身数据平台:Docker Compose 部署、环境变量与全家桶功能解析
SparkyFitness 自托管健身数据平台:Docker Compose 部署、环境变量与全家桶功能解析
SparkyFitness 是一个自托管(self-hosted)、隐私优先的健身与健康数据追踪平台,定位为 MyFitnessPal、Flo、Hevy、Shotsy 等付费订阅产品的替代方案,在一个应用内同时覆盖营养、运动、身体指标与健康数据记录,数据存储在你自有的基础设施上。本文以仓库根目录 README.md 为主线,结合 docker/docker-compose.prod.yml、docker/.env.example、docker/.env.simple.example 等真实配置,完整讲解项目的架构组成、功能范围、健康设备集成,以及从零开始的 Docker Compose 部署流程与关键环境变量,让读者能够独立完成一套自托管实例的搭建与安全配置。
项目构成:一个后端、一个 Web 前端与原生移动端
SparkyFitness 由三大部分组成,全部存在于当前仓库中:
- 后端服务器(SparkyFitnessServer):提供 API 与数据存储,基于 Express 5 + TypeScript,使用 PostgreSQL 存储健康数据,启动时自动执行 SQL 迁移(见 SparkyFitnessServer/index.ts 中"migrations run here, before any application module is imported"的说明);
- Web 前端(SparkyFitnessFrontend):基于 React + Vite 的单页应用;
- 原生移动端(SparkyFitnessMobile):面向 iOS 与 Android 的 Expo/React Native 应用,并附带 watchOS 手表端(
targets/watch)与桌面组件(targets/widget)等原生目标; - 另有独立的 Garmin 微服务(SparkyFitnessGarmin),负责 Garmin Connect 数据抓取,在 docker-compose 中默认注释启用。
README 明确强调:平台在你控制的服务器上存储和管理健康数据,不依赖任何第三方服务,这是它与商业订阅类应用最本质的区别。
核心功能一览
按 README.md 的 "Core Features" 章节,SparkyFitness 覆盖的功能包括:
- 营养、运动、饮水、睡眠、断食(fasting)、情绪与身体测量的记录与追踪;
- 目标设定与每日打卡(daily check-in),仓库中有对应的 goalRepository.ts、checkInPhotoRoutes.ts 等实现佐证;
- 交互式图表与长期报告,支持自定义日期范围(见 dailySummaryRangeService.ts);
- 多用户档案与家庭共享(Family access),支持细粒度权限控制;
- 浅色/深色主题;
- OIDC、TOTP、Passkey、MFA 等认证方式,基于 Better Auth 实现(见 SparkyFitnessServer/auth.ts 中的
betterAuth()装配与@better-auth/passkey、@better-auth/sso依赖)。
此外 README 明确声明:睡眠分期、HRV、血糖等数据由手表、手机或血糖仪导入,SparkyFitness 负责存储、分析与绘图,而不是自行测量。
与同类产品的定位差异
README 中附有一张对比表,将 SparkyFitness 与 wger、MyFitnessPal、Cronometer、Hevy、Zero、Flo、Garmin Connect、Google Health 等进行对比。表格由项目自身编写(README 原话 "This table is written by the project being compared, so read it that way"),并注明检查日期为 2026 年 8 月 14 日、部分信息可能已过时。对比中的关键差异点包括:
- 自托管、数据自持:⭐(相对 wger 的 ✅);
- 无订阅、无广告:✅;
- 营养/力量/睡眠/断食/周期/用药一体管理:⭐;
- 完整历史与自定义日期报告:✅ 免费(多数竞品为付费层 💰);
- 可穿戴与健康平台同步:✅ 8+ 服务;
- 家庭共享与细粒度权限:⭐ 7 类权限;
- CSV 导入与免费数据导出:✅;
- MCP 服务器 + 自带 LLM:⭐。
对比结论的阅读姿势应保持客观:README 自己也在邀请读者纠正对自家不利的条目。
健康与设备集成:22 类数据源
SparkyFitness 支持从多个健康与健身平台同步数据,完整清单见 README.md 的 "Health & Device Integrations" 章节:
- Apple Health(iOS)、Google Health Connect(Android)、Google Health API;
- Fitbit、Garmin Connect、Withings、Polar Flow、Oura、Hevy、Strava(README 标注为 partially tested)、COROS;
- 食物数据库类:OpenFoodFacts、USDA、Fatsecret、Nutritionix、Mealie、Tandoor、Norish、Yazio(使用非官方 API)、Swiss Food Database、Canadian Nutrient File (Health Canada);
- 运动库类:Free Exercise DB(GitHub)、Wger。
这些集成在服务器端一一对应真实实现,例如 SparkyFitnessServer/integrations/ 下的 garminconnect/、fitbit/、oura/、withings/、openfoodfacts/、fatsecret/、nutritionix/、wger/ 等目录。同步内容包括步数、运动、睡眠等活动数据,以及体重、身体测量等健康指标,自动写入 SparkyFitness 服务器。
可选的 AI 功能(Beta)
README 介绍了名为 SparkyAI 的可选对话式 AI 功能,目前处于 Beta 阶段:
- 通过聊天直接记录食物、运动、身体指标与步数;
- 上传食物图片实现自动餐食记录(food photo logging,对应 foodPhotoLogService.ts 等服务);
- 保留对话历史以支持后续追问。
AI 功能在服务端由 SparkyFitnessServer/ai/ 目录承载,包含模型供应商分发(providerDispatch.ts)、MCP 适配(mcp/mcpAdapter.ts)以及数十个领域工具(ai/tools/ 下的 foodTools.ts、exerciseTools.ts、sleepScienceTools.ts 等)。README 明确提示:AI 功能当前为 Beta,可能存在缺陷或功能不完整。
安装方式一:Docker Compose 自托管
README 提供了完整的一键式自托管安装流程,使用 Docker Compose 可在数分钟内启动。以下是继承并展开的完整步骤。
第一步:创建目录并下载 compose 文件
# 1. Create a new folder
mkdir sparkyfitness && cd sparkyfitness
# 2. Download docker-compose.yml
curl -L -o docker-compose.yml https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/docker-compose.prod.yml
# 3. Set up your .env configuration (Choose one option):
# Option A (Recommended): Generate custom .env with 1-click secure keys in browser
# Option B: Minimal template — 5 values, everything else uses the defaults
curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.simple.example
# Option C: Full reference — every supported variable, commented out with its default
# curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.example
# 4. Replace the placeholders (skip if you used Option A)
# SPARKY_FITNESS_DB_PASSWORD any strong password
# SPARKY_FITNESS_API_ENCRYPTION_KEY openssl rand -hex 32 (64 hex chars)
# BETTER_AUTH_SECRET openssl rand -base64 32 (44 chars)
# SPARKY_FITNESS_FRONTEND_URL the URL you will open the app at
# 5. Start the app
docker compose pull && docker compose up -d
# Access application at http://localhost:3004
对应到当前仓库,可以直接使用仓库内已有的 docker/docker-compose.prod.yml(生产环境 compose 定义)与 docker/.env.simple.example(最小环境模板)、docker/.env.example(全量参考模板)。
第二步:理解 compose 的服务拓扑
从 docker/docker-compose.prod.yml 可以看到生产部署包含三个核心服务,外加一个默认注释的 Garmin 微服务:
| 服务 | 镜像 | 作用 |
|---|---|---|
sparkyfitness-db |
postgres:18.3-alpine |
PostgreSQL 数据库,首次初始化时读取 POSTGRES_DB/USER/PASSWORD,并带健康检查 pg_isready |
sparkyfitness-server |
codewithcj/sparkyfitness_server:latest |
后端 API,启动时执行迁移;depends_on 数据库且要求 condition: service_healthy,避免迁移与数据库初始化竞争 |
sparkyfitness-frontend |
codewithcj/sparkyfitness:latest |
Nginx 托管前端,将 /api、/health-data、/uploads 反向代理到后端服务 |
sparkyfitness-garmin(注释) |
codewithcj/sparkyfitness_garmin:latest |
Garmin Connect 微服务,启用 Garmin 功能时取消注释 |
compose 中值得注意的几个要点:
- 端口映射:前端容器将
${SPARKY_FITNESS_FRONTEND_PORT:-3004}映射到NGINX_LISTEN_PORT(默认 80),两者必须保持一致,否则 Nginx 监听在未发布的端口上导致应用不可访问; - 数据库端口默认不暴露到宿主机,需要 pgAdmin/DBeaver 时才取消
ports注释; SPARKY_FITNESS_SERVER_HOST默认sparkyfitness-server:这是 compose 网络内的服务名,前端 Nginx 在容器内解析它。若改成localhost会指向前端容器自身,导致所有 API 调用返回 502;- 数据卷:数据库落在
./postgresql,备份落在./backup,上传(头像、运动图片)落在./uploads,均可通过DB_PATH、SERVER_BACKUP_PATH、SERVER_UPLOADS_PATH重定向; - PG 密码初始化语义:compose 注释明确警告,
POSTGRES_DB/USER/PASSWORD只在数据库首次初始化时生效,已有实例修改无效,且会导致服务器认证失败——必须直接在 PostgreSQL 中ALTER。
第三步:三种 .env 配置方案
README 推荐三种取 .env 的方式:
- Option A(推荐):使用网页端的交互式
.env生成器,一键生成含安全随机密钥的配置; - Option B(最小模板):仅 5 个值,其余全部使用 compose 默认值,适合大多数自托管安装。仓库内对应 docker/.env.simple.example,其五个必填值如下:
# 1. PostgreSQL Superuser
SPARKY_FITNESS_DB_USER=sparky
SPARKY_FITNESS_DB_PASSWORD=changeme_db_password
# 2. Cryptographic Security Keys
SPARKY_FITNESS_API_ENCRYPTION_KEY=replace_with_a_64_character_hex_string # openssl rand -hex 32
BETTER_AUTH_SECRET=replace_with_a_base64_secret # openssl rand -base64 32
# 3. Access URL
# e.g., http://localhost:3004, http://192.168.1.100:3004, or https://fitness.yourdomain.com
SPARKY_FITNESS_FRONTEND_URL=http://localhost:3004
- Option C(全量参考):仓库内对应 docker/.env.example,覆盖每一个受支持的变量并带默认值注释,适合需要 SSO、SMTP、外部数据库或反向代理的场景。
README 特别警告:服务器会在占位符原样保留时拒绝启动(仓库后端入口 SparkyFitnessServer/index.ts 中的 runPreflightChecks() 正是为此存在),且数据库会用已发布的密码初始化,因此第 4 步的占位符替换不可跳过。
环境变量速查:从最小集到完整集
以 docker/.env.example 的章节顺序为准,将核心变量整理如下(未注明的均为可选):
数据库与密钥(必填)
| 变量 | 说明 | 默认值 |
|---|---|---|
SPARKY_FITNESS_DB_USER |
PostgreSQL 超级用户 | sparky |
SPARKY_FITNESS_DB_PASSWORD |
必填,数据库超级用户密码 | 无 |
SPARKY_FITNESS_DB_NAME |
数据库名(仅首次初始化生效) | sparkyfitness_db |
SPARKY_FITNESS_DB_HOST / SPARKY_FITNESS_DB_PORT |
数据库地址/端口 | sparkyfitness-db / 5432 |
SPARKY_FITNESS_APP_DB_USER / SPARKY_FITNESS_APP_DB_PASSWORD |
应用角色;留空则由服务器自建 sparky_app 并每次启动生成新密码;多服务器共享同一库时建议显式设置 |
可选 |
SPARKY_FITNESS_API_ENCRYPTION_KEY |
必填,64 位十六进制,openssl rand -hex 32 |
无 |
BETTER_AUTH_SECRET |
必填,openssl rand -base64 32(44 字符);签名会话 cookie 并加密存储的 2FA/TOTP 密钥,必须永久保持不变——更换会让所有用户登出、启用 2FA 的用户永久锁死;服务器按 base64 解码,字母表外字符会被静默丢弃导致密钥缩短 |
无 |
运行时与访问
| 变量 | 说明 | 默认值 |
|---|---|---|
SPARKY_FITNESS_FRONTEND_URL |
必填,访问应用的 URL(http://localhost:3004 或域名) |
无 |
NODE_ENV |
运行环境 | production |
SPARKY_FITNESS_LOG_LEVEL |
日志级别 | ERROR |
TZ |
时区,决定记录按哪一时区归入自然日 | Etc/UTC |
SPARKY_FITNESS_SERVER_PORT |
后端容器内监听端口 | 3010 |
SPARKY_FITNESS_FRONTEND_PORT |
前端对外映射端口 | 3004 |
SPARKY_FITNESS_DISABLE_SIGNUP |
关闭注册 | false |
SPARKY_FITNESS_ADMIN_EMAIL |
拥有该邮箱的用户可访问管理后台 | 空 |
BETTER_AUTH_URL |
覆盖 Better Auth 构建回调链接的基址(无法从 FRONTEND_URL 推导时使用) | 可选 |
登录与 OIDC/SSO
FORCE_EMAIL_LOGIN 优先于 DISABLE_EMAIL_LOGIN;真正禁用密码登录需 DISABLE_EMAIL_LOGIN=true 且 FORCE_EMAIL_LOGIN 未设置或为 false,且务必先确认 OIDC 或 SMTP 魔法链接可用,否则新实例无人能登录。DISABLE_PASSKEY_LOGIN 强制关闭 Passkey 登录,FORCE_PASSKEY_LOGIN 强制打开且优先级最高。OIDC 相关变量(SPARKY_FITNESS_OIDC_AUTH_ENABLED、ISSUER_URL、CLIENT_ID、CLIENT_SECRET、ADMIN_GROUP、SCOPE、TOKEN_AUTH_METHOD、ID_TOKEN_SIGNED_ALG、TIMEOUT 等)在 docker/.env.example 第 7 节有完整示例(以 Authentik 为例)。
邮件、代理与安全开关
- SMTP:
SPARKY_FITNESS_EMAIL_HOST/PORT/SECURE/USER/PASS/FROM,用于邮件通知与魔法链接登录; - 反向代理与真实 IP:
SPARKY_FITNESS_REAL_IP_HEADER(如 CDN 场景的CF-Connecting-IP)、SPARKY_FITNESS_TRUSTED_PROXY_HOPS(默认 1;置于外部反代后设 2)、SPARKY_FITNESS_TRUSTED_PROXIES(信任 CIDR,务必只填真实代理 IP 或代理专用网段); - 限流:
SPARKY_FITNESS_SIGN_IN_RATELIMIT_MAX/WINDOW(登录)、SPARKY_FITNESS_API_KEY_RATELIMIT_MAX_REQUESTS/WINDOW_MS(API Key); - SSRF 开关:
ALLOW_PRIVATE_NETWORK_AI与ALLOW_PRIVATE_NETWORK_FOOD_PROVIDERS允许任何已注册非管理员用户让服务器向内网发请求(SSRF),.env 注释明确警告仅限可信单租户部署; - 出站代理:
HTTP_PROXY/HTTPS_PROXY/NO_PROXY; - 文件型密钥:任意变量都可用
VAR_FILE指向挂载的密钥文件,compose 底部有整套secrets:配置示例(sparkyfitness_db_password、sparkyfitness_api_key等)。
存储路径与移动端构建
独立部署(非 Compose)时用 SPARKY_FITNESS_CUSTOM_UPLOADS_DIRECTORY、SPARKY_FITNESS_CUSTOM_BACKUP_DIRECTORY、SPARKY_FITNESS_CUSTOM_TEMP_DIRECTORY。移动端构建相关:iOS 的 EXPO_DEV_APPLE_TEAM_ID、EXPO_DEV_BUNDLE_IDENTIFIER、WIDGET_BUNDLE_IDENTIFIER、IOS_APP_GROUP_*;Android 的 GOOGLE_MAPS_ANDROID_API_KEY(用于地图绘制跑步路线,无密钥时 Android 端路线退化为普通线条,iOS 用 Apple Maps 无需密钥)。
安装方式二:云端托管(面向非技术用户)
若不想自备服务器,README 提供通过第三方云托管商一键部署的选项(PikaPods、Zenith),并注明这些是独立第三方服务,建议自行评估各提供商特性后选择。
许可证与升级注意事项
重要:SparkyFitness 是 source-available(源码可得)而非传统意义的 open source。仓库 LICENSE 明确:
- 仅限非商业用途,任何以商业利益或金钱回报为主要目的的产品/服务/项目使用均需作者书面许可;
- 允许非商业目的的修改与衍生作品,但衍生作品同样受此非商业条款约束;
- 分发须保留完整版权声明与许可证;
- 提交的代码、文档等贡献,其权利全部转让给原作者(codewithcj)。
此外,README.md 的 "Known Issues / Beta Features" 章节提醒:项目处于活跃开发中,发布间可能引入破坏性变更(breaking changes);不建议容器自动更新,升级前务必阅读 release notes。当前处于 Beta、可能未充分测试的功能包括:
- AI Chatbot;
- Family & Friends 家庭共享访问;
- API 文档。
在源码中进一步探索
想深入验证本文提到的机制,可优先阅读以下仓库文件:
- docker/docker-compose.prod.yml:生产 compose 全量定义(健康检查、服务依赖、卷、secrets);
- docker/.env.example 与 docker/.env.simple.example:环境变量参考与最小模板;
- SparkyFitnessServer/index.ts:启动顺序(dotenv → 密钥加载 → 预检 → 迁移 → 服务模块),解释了迁移必须在 Better Auth 校验 schema 之前执行的原因;
- SparkyFitnessServer/auth.ts:Better Auth 装配与 OIDC、Passkey 集成点;
- SparkyFitnessServer/integrations/:各健康平台同步实现;
- SparkyFitnessServer/ai/:SparkyAI 的模型分发、MCP 适配与工具集;
- LICENSE:非商业许可证全文。
对于希望了解 Docker 部署辅助脚本的读者,仓库内还有 docker/Dockerfile.backend、docker/Dockerfile.frontend、docker/docker-entrypoint.sh 与 docker/Docker_deploy_manual_command.md 可参考。