SparkyFitness 自托管健身数据平台:Docker Compose 部署、环境变量与全家桶功能解析

原创2026-10-09 11:22:551,973 阅读
文章标签:后端前端移动开发

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/Dockerfile.backend、docker/Dockerfile.frontend、docker/docker-entrypoint.sh 与 docker/Docker_deploy_manual_command.md 可参考。

登录后查看全文
SparkyFitness