后端前端移动开发【免费下载链接】SparkyFitnessSparkyFitness: Built for Families. Powered by AI. Track food, fitness, water, and health — together.项目地址https://gitcode.com/gh_mirrors/sp/SparkyFitness点击查看免费下载本指南面向希望在本机快速运行 SparkyFitness 的开发者与自托管用户。SparkyFitness 是一个面向家庭场景的综合健康追踪应用技术栈为 React 18 TypeScript Vite 前端、Node.js/Express 后端数据库使用带行级安全Row Level Security, RLS的 PostgreSQL。读完本文你将掌握两种部署路径推荐优先的 Docker 辅助脚本一键启动开发与生产双环境以及不依赖 Docker 的裸机本地开发流程同时理解.env中每个关键变量的作用、后端在启动时自动执行数据库迁移的机制以及常见启动故障的排查手段。前置条件根据部署方式的不同需要准备不同的运行环境。Docker 部署推荐Docker 与 Docker Compose容器化运行 SparkyFitness 的必需组件。仓库内的辅助脚本 docker/docker-helper.sh 全部操作都基于docker compose命令完成。Git用于克隆 SparkyFitness 仓库。本地开发不使用 DockerNode.js 18 与 npmJavaScript 运行时与包管理器。需要说明的是仓库根目录与各子包的package.json均声明了packageManager: pnpm10.33.4见 package.json后端依赖构建脚本Dockerfile.backend.dev也使用corepack enablepnpm install因此本地开发建议使用 pnpm 以获得与仓库一致的依赖解析。PostgreSQL 15数据库服务器。Docker 镜像使用的是postgres:18.3-alpine见 docker-compose.dev.yml裸机安装时要求 PostgreSQL 15 及以上。Git版本控制工具。快速开始推荐 Docker 路径最快的方式是使用仓库自带的 Docker 辅助脚本它封装了环境校验、compose 文件选择与常用操作# 克隆仓库 git clone https://github.com/CodeWithCJ/SparkyFitness.git cd SparkyFitness # 复制环境模板 cp docker/.env.example .env # SPARKY_FITNESS_API_ENCRYPTION_KEY 必须设置为合法值 # 可以用以下任一命令生成安全密钥 # openssl rand -hex 32 # 或 # node -e console.log(require(crypto).randomBytes(32).toString(hex)) # 也可以不手动编辑 .env直接通过 sed 原地替换生成 sed s/SPARKY_FITNESS_API_ENCRYPTION_KEYchangeme_replace_with_a_64_character_hex_string/SPARKY_FITNESS_API_ENCRYPTION_KEY$(openssl rand -hex 32)/ .env .env.tmp mv .env.tmp .env # BETTER_AUTH_SECRET 也必须替换服务端遇到占位符会拒绝启动 sed s|BETTER_AUTH_SECRETchangeme_replace_with_a_strong_better_auth_secret|BETTER_AUTH_SECRET$(openssl rand -base64 32)| .env .env.tmp mv .env.tmp .env # 按需编辑其他环境变量 # 若 Docker 运行在另一台机器上需要更新 SPARKY_FITNESS_FRONTEND_URL # 启动开发环境带热重载 ./docker/docker-helper.sh dev up # 访问应用http://localhost:8080或你配置的 URLdocker/docker-helper.sh脚本会切换到仓库根目录、定位 compose 文件并在每次调用时打印当前环境、动作与使用的 compose 文件路径源码见 docker/docker-helper.sh。其中dev up走docker compose up --build -d强制重建镜像prod up则直接拉取预构建镜像并后台启动。为什么必须替换这两个密钥从 docker/.env.example 的注释可以确认两个密钥的用途SPARKY_FITNESS_API_ENCRYPTION_KEY要求 64 位十六进制字符串即openssl rand -hex 32的输出用于 API 数据加密。BETTER_AUTH_SECRET用于签名会话 Cookie 并加密存储的 2FA/TOTP 密钥。该值必须永久保持不变——更换会导致所有用户被登出且开启过 2FA 的用户会被永久锁定。要求 base64 编码openssl rand -base64 32服务端按 base64 解码若混入非 base64 字符会被静默丢弃、缩短密钥而不报错。Docker 辅助脚本使用手册辅助脚本提供了管理开发与生产环境的统一入口# 查看所有可用命令与帮助 ./docker/docker-helper.sh help # 启动开发环境 ./docker/docker-helper.sh dev up # 启动生产环境 ./docker/docker-helper.sh prod up # 查看日志 ./docker/docker-helper.sh logs # 停止服务 ./docker/docker-helper.sh down # 彻底清理 ./docker/docker-helper.sh clean可用命令一览命令作用底层行为对应源码dev up启动开发环境带热重载docker compose up --build -dprod up启动生产环境优化构建/预构建镜像docker compose up -ddown停止并移除所有容器docker compose downlogs [service]查看全部或指定服务日志docker compose logs -fclean移除所有容器、网络与卷down --volumes --remove-orphansdocker system prune -fbuild重建所有镜像docker compose buildrestart [service]重启全部或指定服务脚本帮助文本中列出实际由down/up组合完成注意脚本对参数有严格校验环境参数只能是dev或prod动作只能是up/down/build/logs/ps/clean否则会打印帮助并退出见 docker/docker-helper.sh。同时所有 compose 调用都会显式传入--env-file $ENV_FILE即仓库根目录的.env因此环境变量必须写在根目录.env中而不是.env.example。环境搭建开发环境开发环境适合日常迭代核心特性是热重载与本地代码直挂容器# 启动开发栈 ./docker/docker-helper.sh dev up # 可用服务 # - 前端http://localhost:8080 热重载 # - 后端http://localhost:3010 直接访问 # - 数据库localhost:5432 直接访问开发环境特性Live Reloading前后端文件变更后自动重载。前端容器通过卷挂载将 SparkyFitnessFrontend 挂入容器并以pnpm run dev --host 0.0.0.0启动 Vite见 Dockerfile.frontend.dev后端则通过挂载 SparkyFitnessServer 目录并由 compose 指定command: pnpm startnodemon 托管实现热更新。Volume Mounts本地源码挂载进容器修改立即生效。compose 中同时使用匿名卷覆盖容器内node_modules防止宿主机依赖覆盖镜像内已安装依赖见 docker-compose.dev.yml。Direct Database Access5432:5432端口映射可直接连接 PostgreSQL 调试。Development Dependencies开发工具与调试能力全部启用。开发栈背后的服务编排从 docker-compose.dev.yml 可以看到三个服务sparkyfitness-dbpostgres:18.3-alpine使用POSTGRES_DB/USER/PASSWORD三个变量完成首次初始化数据持久化在./docker_volume/postgresql。sparkyfitness-server构建docker/Dockerfile.backend.dev通过环境变量传入数据库连接、安全密钥、日志级别等配置并依赖sparkyfitness-db启动。sparkyfitness-frontend构建docker/Dockerfile.frontend.dev通过VITE_BACKEND_HOST等变量指向后端服务名sparkyfitness-server完成跨容器通信。环境搭建生产环境生产环境使用优化构建适合部署测试与正式发布# 启动生产栈 ./docker/docker-helper.sh prod up # 可用服务 # - 应用入口http://localhost:3004 nginx 代理生产环境特性Optimized Builds前端产物压缩、后端生产就绪。Nginx Proxy单一入口同时承担静态文件服务与/api、/health-data、/uploads的反向代理。前端容器镜像为codewithcj/sparkyfitness:latest后端为codewithcj/sparkyfitness_server:latest见 docker-compose.prod.yml端口映射为${SPARKY_FITNESS_FRONTEND_PORT:-3004}:${NGINX_LISTEN_PORT:-80}。Environment Isolation独立的网络与安全配置后端与数据库只暴露在内部sparkyfitness-network桥接网络外部不可直达。DockerHub Images使用预构建镜像无需本地编译部署更快。生产编排的关键细节后端通过depends_on的condition: service_healthy等待数据库健康检查通过后再启动——因为迁移会在服务监听前于启动阶段执行不能与仍在初始化的 PostgreSQL 竞争见 docker-compose.prod.yml。前端容器内 nginx 通过SPARKY_FITNESS_SERVER_HOST解析后端服务名注释明确指出此处若写成localhost会指向前端自身导致所有 API 请求返回 502见 docker-compose.prod.yml。Garmin 微服务sparkyfitness-garmin在 compose 文件中以注释形式保留启用 Garmin Connect 集成时需取消注释并配置GARMIN_SERVICE_PORT、GARMIN_SERVICE_IS_CN中国区设为true。本地开发不使用 Docker不依赖 Docker 的裸机开发流程按数据库 → 后端 → 前端顺序进行。数据库设置安装 PostgreSQL 15创建数据库与用户CREATE DATABASE sparkyfitness; CREATE USER sparky WITH PASSWORD your_password; GRANT ALL PRIVILEGES ON DATABASE sparkyfitness TO sparky;后端设置# 进入服务端目录 cd SparkyFitnessServer # 安装依赖 npm install # 复制并配置环境 cp .env.example .env # 编辑 .env 填入数据库凭据 # 运行数据库迁移 npm run migrate # 启动开发服务器 npm run dev关于迁移命令的事实说明从当前仓库 SparkyFitnessServer/package.json 的 scripts 可以看到仓库实际提供的是startnodemon、test:migrations、typecheck、validate、lint、format等脚本并没有名为migrate的脚本。在 Docker 部署中数据库迁移由服务器进程在启动阶段自动应用生产 compose 的注释明确写到 The server applies migrations at startup见 docker-compose.prod.yml迁移 SQL 文件位于 SparkyFitnessServer/db/migrations仓库内共 251 个 SQL 迁移文件。裸机部署时同样依赖启动时的自动迁移而非独立的 migrate 命令若你的裸机流程遇到迁移相关问题应以服务启动日志为准。前端设置# 回到项目根目录 cd .. # 安装依赖 npm install # 启动开发服务器 npm run dev前端开发服务器脚本定义在 SparkyFitnessFrontend/package.json 中dev: vite依赖安装同样推荐使用与仓库一致的 pnpmpnpm install因为前端构建链涉及workspace/shared工作区依赖与patches/下的补丁文件见 Dockerfile.frontend.dev。环境变量详解环境模板统一从仓库根目录复制cp docker/.env.example .env以下为原文档列出的核心变量结合 docker/.env.example 补充了默认值与作用说明数据库配置变量作用DATABASE_URLPostgreSQL 连接字符串裸机部署形式DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASSWORD独立数据库设置在 Docker 编排中实际生效的变量名是SPARKY_FITNESS_DB_*系列SPARKY_FITNESS_DB_NAME默认sparkyfitness_db、SPARKY_FITNESS_DB_USER默认sparky、SPARKY_FITNESS_DB_PASSWORD必填、SPARKY_FITNESS_DB_HOST默认sparkyfitness-db服务名、SPARKY_FITNESS_DB_PORT默认5432。此外还有应用角色SPARKY_FITNESS_APP_DB_USER默认sparky_app与SPARKY_FITNESS_APP_DB_PASSWORD——服务器会创建并同步该角色若多个服务器共享同一数据库或已手动预建角色则应显式设置见 docker/.env.example。重要警告数据库名、超级用户名与超级用户密码仅在数据库首次初始化时读取。在已运行的实例上修改这些值对 PostgreSQL 不生效服务端随后会用不匹配的凭据认证失败如需修改必须直接在 PostgreSQL 中执行ALTER。应用设置变量默认值作用PORT3010后端服务端口compose 中的对应变量为SPARKY_FITNESS_SERVER_PORTNODE_ENVproduction运行模式development/productionJWT_SECRET—JWT 令牌签名密钥补充几个原文档未列但.env.example中重要的运行时变量SPARKY_FITNESS_LOG_LEVEL默认ERROR服务端日志级别。TZ默认Etc/UTC驱动记录按自然日分桶的时区应按自身时区设置。SPARKY_FITNESS_ADMIN_EMAIL拥有该邮箱的用户可访问管理面板。SPARKY_FITNESS_DISABLE_SIGNUP默认false是否关闭注册。SPARKY_FITNESS_FRONTEND_URL前端地址用于构建认证回调链接默认http://localhost:3004Docker 在其他机器时需修改。前端配置变量作用SPARKY_FITNESS_SERVER_HOST后端服务连接地址compose 内默认为服务名sparkyfitness-serverSPARKY_FITNESS_SERVER_PORT后端服务端口AI 集成变量作用OPENAI_API_KEYOpenAI API 密钥AI 功能GOOGLE_AI_API_KEYGoogle Gemini API 密钥ANTHROPIC_API_KEYAnthropic Claude API 密钥后端依赖ai-sdk/openai、ai-sdk/google、ai-sdk/anthropic与ai运行时见 SparkyFitnessServer/package.jsonAI 能力的统一分发逻辑可参考 ai/providerDispatch.ts 与 ai/config.ts。可选增强配置来自.env.exampleSMTP 邮件SPARKY_FITNESS_EMAIL_HOST/PORT/SECURE/USER/PASS/FROM用于邮件通知与邮件登录。OIDC/SSOSPARKY_FITNESS_OIDC_AUTH_ENABLED及配套的ISSUER_URL、CLIENT_ID、CLIENT_SECRET、ADMIN_GROUP、SCOPE等启用第三方单点登录。限流SPARKY_FITNESS_SIGN_IN_RATELIMIT_MAX/WINDOW与SPARKY_FITNESS_API_KEY_RATELIMIT_*控制登录与 API Key 请求速率。反向代理SPARKY_FITNESS_REAL_IP_HEADER、SPARKY_FITNESS_TRUSTED_PROXY_HOPS默认1指内置前端 nginx外部再加一层反代时设为2、SPARKY_FITNESS_TRUSTED_PROXIES按可信 CIDR 指定避免宽泛私网段。Docker Secrets任意变量均可用VAR_FILE形式改为文件注入例如SPARKY_FITNESS_DB_PASSWORD_FILE、BETTER_AUTH_SECRET_FILE、SPARKY_FITNESS_OIDC_CLIENT_SECRET_FILE。SSRF 安全警告ALLOW_PRIVATE_NETWORK_AI与ALLOW_PRIVATE_NETWORK_FOOD_PROVIDERS会让任意已注册的非管理员用户触发服务器向内部网络发请求仅应在可信的单租户部署中开启。手动使用 Docker Compose不借助辅助脚本直接使用 Docker Compose 同样可行# 生产部署后台运行 docker-compose -f docker/docker-compose.prod.yml up -d # 开发环境带热重载前台运行 docker-compose -f docker/docker-compose.dev.yml up # 停止服务 docker-compose down # 查看日志 docker-compose logs -f [service_name]手动模式下仍需要根目录.env存在因为两个 compose 文件都通过env_file: ../.env或${VAR}插值读取环境变量见 docker-compose.dev.yml。配置文件总览Docker 部署涉及以下配置文件Dockerfiles文件作用Dockerfile.frontend前端多阶段构建镜像Dockerfile.backend后端 Node.js 应用镜像Dockerfile.frontend.dev前端开发镜像Vite 热重载Dockerfile.backend.dev后端开发镜像nodemon 托管nginx.confNginx 配置模板由入口脚本完成变量替换Compose 文件文件作用docker-compose.dev.yml开发环境源码挂载、热重载、数据库 5432 端口暴露docker-compose.prod.yml生产环境预构建镜像、内部网络隔离、健康检查门控另有数据库专用编排 docker-compose.db_dev.yml。配置与脚本文件作用docker/.env.example环境变量模板18 个分区、含全部注释与默认值docker/docker-entrypoint.sh环境变量替换脚本渲染 nginx 配置等docker/docker-helper.sh管理脚本环境校验、compose 调用、日志、清理代码质量规范为保证代码一致性与减少错误提交变更前必须通过前端代码质量检查Linting在SparkyFitnessFrontend目录运行npm run lint检查潜在错误并强制编码风格。该脚本定义为eslint . --max-warnings 0见 SparkyFitnessFrontend/package.json即不允许任何 warning。Formatting在SparkyFitnessFrontend目录运行npx prettier . --check验证格式一致性需要修复时使用npm run format。仓库层面还配置了 husky lint-staged在提交时对前端 TS/TSX、服务端 JS/TS 与移动端文件自动执行 Prettier 格式化见根目录 package.json 的lint-staged配置。下一步应用成功运行后探索应用访问 http://localhost:8080开发或 http://localhost:3004生产创建账号注册新用户查看 API后端 API 位于 http://localhost:3010/api仅开发环境阅读架构参见架构指南开始贡献参见贡献指南常见问题排查端口冲突检查所需端口是否被占用lsof -i :8080 # 前端 lsof -i :3010 # 后端 lsof -i :5432 # 数据库Windows 下可用netstat -ano | findstr :port配合taskkill /PID PID /F解决冲突或直接在.env中修改端口。数据库连接问题确认 PostgreSQL 已运行、.env中SPARKY_FITNESS_DB_NAME、SPARKY_FITNESS_DB_USER、SPARKY_FITNESS_DB_PASSWORD正确。查看数据库容器日志./docker/docker-helper.sh dev logs sparkyfitness-db若数据可丢弃仅限开发环境可做破坏性重置./docker/docker-helper.sh dev down ./docker/docker-helper.sh dev clean ./docker/docker-helper.sh dev up权限问题确保 Docker 有足够权限、当前用户已加入docker组sudo usermod -aG docker $USER # 注销后重新登录Linux/WSL 下若遇到卷权限问题尤其 PostgreSQL 数据目录可修正所有权sudo chown -R $USER:$USER ./postgresql。更详细的排查方案参见故障排查指南该文档还覆盖了 Invalid key length 错误、构建失败清理重建、备份恢复等场景。赞分享后端前端移动开发【免费下载链接】SparkyFitnessSparkyFitness: Built for Families. Powered by AI. Track food, fitness, water, and health — together.项目地址https://gitcode.com/gh_mirrors/sp/SparkyFitness点击查看免费下载相关推荐Laradock 快速上手用 Docker 一键搭建完整 PHP 开发环境Laradock 快速上手用 Docker 一键搭建完整 PHP 开发环境 Laradock 是一个基于 Docker 的完整 PHP 开发环境把仓库克隆进后端开发工具DevOpsLangWatch Docker部署本地开发环境快速搭建指南LangWatch Docker部署本地开发环境快速搭建指南 概述 LangWatch是一个领先的LLM Ops大语言模型运维平台专注于评估能力和用户友OpenUI开发环境搭建Docker一键部署与本地开发配置OpenUI开发环境搭建Docker一键部署与本地开发配置 你还在为UI开发环境配置繁琐而头疼本文将带你快速掌握OpenUI的两种部署方式——Docker一人工智能AI 应用代码生成前端后端上一篇easy-vibe跨平台开发教程微信小程序、Android、iOS、PWA与桌面应用5条路径下一篇March7thAssistant时间调度定时执行与任务优先级全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考