Workout.cool快速上手指南：5分钟搭建你的个人健身平台

2026-02-05 04:49:55作者：戚魁泉Nursing

你还在为找不到开源、可定制的健身追踪平台而烦恼吗？想拥有专属的锻炼计划管理系统却受制于商业软件的功能限制？本文将带你5分钟从零搭建Workout.cool——一个现代化、功能全面的开源健身平台，让你完全掌控自己的健身数据与训练方案。

读完本文你将能够：

快速部署完整的健身管理系统
配置用户认证与数据库
导入专业的健身动作库
个性化定制训练计划
掌握平台核心功能与扩展方法

🚀 环境准备与快速安装

系统要求清单

软件/工具	版本要求	用途
Node.js	18.x 或更高	运行JavaScript环境
pnpm	8.x+ 或 npm	包管理工具
PostgreSQL	14.x+	数据库服务
Docker	可选	容器化部署
Git	最新版	代码版本控制

一键安装流程

# 1. 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/wo/workout-cool.git
cd workout-cool

# 2. 安装依赖包
pnpm install

# 3. 配置环境变量
cp .env.example .env

# 4. 使用Docker快速启动（推荐新手）
make init

# 5. 手动启动开发服务器（适用于已有PostgreSQL）
pnpm dev

执行上述命令后，系统将自动完成：

数据库初始化与迁移
基础数据导入
开发服务器启动（默认端口3000）

⚙️ 核心配置详解

环境变量关键参数

编辑.env文件，配置以下核心参数：

# 数据库连接（必填）
DATABASE_URL="postgresql://username:password@localhost:5432/workout_cool"

# 认证密钥（使用命令生成：openssl rand -base64 32）
BETTER_AUTH_SECRET="your-secure-random-string"

# 应用URL（开发环境默认值）
BETTER_AUTH_URL="http://localhost:3000"

# 可选：Google登录配置
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# 可选：邮件服务（用于用户验证）
RESEND_API_KEY="re_your-api-key"

⚠️ 安全提示：生产环境必须更换默认密钥，使用强随机字符串并定期轮换

数据库结构概览

Workout.cool采用Prisma ORM管理数据库，核心数据模型关系如下：

erDiagram
    User {
        String id PK
        String email
        String name
        UserRole role
        DateTime createdAt
    }
    Exercise {
        String id PK
        String name
        String description
        String fullVideoUrl
    }
    WorkoutSession {
        String id PK
        String userId FK
        DateTime startedAt
        DateTime endedAt
    }
    WorkoutSet {
        Int setIndex
        Int valuesInt
        Boolean completed
    }
    
    User ||--o{ WorkoutSession : "创建"
    Exercise ||--o{ WorkoutSessionExercise : "包含"
    WorkoutSession ||--o{ WorkoutSessionExercise : "包含"
    WorkoutSessionExercise ||--o{ WorkoutSet : "包含"

主要数据实体说明：

User: 用户信息与认证数据
Exercise: 健身动作库，包含详细说明与视频链接
WorkoutSession: 训练记录，关联用户与动作
WorkoutSet: 每组训练数据，如重量、次数、完成状态

💪 动作数据库导入

导入命令与格式

Workout.cool支持CSV格式批量导入动作数据：

# 使用示例数据导入
pnpm run import:exercises-full ./data/sample-exercises.csv

# 自定义CSV导入
pnpm run import:exercises-full /path/to/your/exercises.csv

CSV文件需包含以下列（至少）：

id,name,name_en,description,description_en,attribute_name,attribute_value
1,"深蹲","Squat","基础下肢训练动作","Basic lower body exercise",PRIMARY_MUSCLE,QUADRICEPS
1,"深蹲","Squat","基础下肢训练动作","Basic lower body exercise",EQUIPMENT,BODYWEIGHT
1,"深蹲","Squat","基础下肢训练动作","Basic lower body exercise",MECHANICS_TYPE,COMPOUND

支持的属性类型

系统支持多种动作分类属性，完整列表如下：

pie
    title 动作类型分布
    "力量训练(STRENGTH)" : 45
    "自重训练(BODYWEIGHT)" : 30
    "有氧训练(CARDIO)" : 15
    "拉伸训练(STRETCHING)" : 10

主要属性类别：

TYPE: 训练类型（力量、有氧、拉伸等）
PRIMARY_MUSCLE: 主要肌群（股四头肌、胸肌、背阔肌等）
EQUIPMENT: 所需器械（哑铃、杠铃、弹力带等）
MECHANICS_TYPE: 动作机制（复合动作、孤立动作）

🔑 用户认证与权限

认证流程

sequenceDiagram
    participant 用户
    participant 应用
    participant 数据库
    
    用户->>应用: 访问登录页面
    应用->>用户: 显示登录表单
    用户->>应用: 提交邮箱/密码
    应用->>数据库: 验证凭据
    数据库-->>应用: 返回验证结果
    alt 验证成功
        应用->>用户: 创建会话并重定向
    else 验证失败
        应用->>用户: 显示错误信息
    end

角色与权限管理

系统内置两种用户角色：

角色	权限范围	典型场景
user	个人训练记录管理	普通用户
admin	全平台数据管理	系统管理员

修改用户角色命令：

# 使用Prisma Studio可视化管理
pnpm prisma studio

# 或通过API更新（需管理员权限）
# PUT /api/admin/users/{id}

📊 功能使用指南

训练计划创建流程

创建训练会话：
- 访问 /onboarding 设置训练目标
- 或直接进入 /workout-builder 开始构建
选择训练动作：
- 按肌群筛选（胸部、背部、腿部等）
- 按器械类型筛选（哑铃、杠铃、自重等）
- 查看动作详情与示范视频
设置训练参数：
- 组数与每组次数
- 重量/阻力设置
- 休息时间
- 完成状态跟踪

flowchart TD
    A[开始训练] --> B[选择肌群]
    B --> C{有器械?}
    C -->|是| D[选择器械类型]
    C -->|否| E[显示自重动作]
    D --> F[筛选动作列表]
    E --> F
    F --> G[添加到训练计划]
    G --> H[设置组数/次数]
    H --> I[开始训练]
    I --> J[记录完成情况]
    J --> K[生成训练报告]

数据统计与进度跟踪

系统自动记录训练数据并生成统计报告：

训练频率分析
肌群训练分布
重量/次数进步曲线
完成率与训练时长统计

访问 /profile 查看个人数据仪表盘，或通过API导出数据进行自定义分析：

// 示例：获取用户训练历史
fetch('/api/workout-sessions', {
  headers: {
    'Authorization': `Bearer ${userToken}`
  }
})
.then(res => res.json())
.then(data => console.log(data));

🛠️ 开发与扩展

项目架构概览

采用Feature-Sliced Design架构，代码组织如下：

src/
├── app/               # Next.js路由与页面
├── entities/          # 核心数据模型（用户、训练等）
├── features/          # 业务功能模块
│   ├── auth/          # 认证相关功能
│   ├── workout-builder/ # 训练计划创建
│   └── workout-session/ # 训练记录管理
├── shared/            # 共享组件与工具
└── widgets/           # UI组件

常用开发命令

# 运行开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 运行单元测试
pnpm test

# 数据库迁移
pnpm prisma migrate dev --name add_new_feature

# 生成API文档
pnpm run docs

📝 部署指南

生产环境部署选项

1. 基础VPS部署

# 1. 准备环境
apt update && apt install -y nodejs postgresql pnpm

# 2. 配置数据库
sudo -u postgres psql -c "CREATE DATABASE workout_cool;"

# 3. 部署应用
git clone https://gitcode.com/gh_mirrors/wo/workout-cool.git
cd workout-cool
pnpm install
pnpm build

# 4. 使用PM2启动
pnpm add -g pm2
pm2 start npm --name "workout-cool" -- start

2. Docker Compose部署

# docker-compose.yml
version: '3'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/workout_cool
      - NODE_ENV=production
      - BETTER_AUTH_SECRET=${SECRET}
  
  db:
    image: postgres:14
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=workout_cool
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

启动命令：docker-compose up -d

❓ 常见问题解决

数据库连接失败

检查PostgreSQL服务是否运行：systemctl status postgresql
验证数据库URL格式：postgresql://user:pass@host:port/dbname
确认数据库用户权限：GRANT ALL PRIVILEGES ON DATABASE workout_cool TO username;

动作导入失败

检查CSV文件编码（需UTF-8）
验证属性值是否符合枚举定义（见schema.prisma）
确保没有重复的slug字段值

认证服务无法启动

检查BETTER_AUTH_SECRET是否设置
确认JWT密钥长度至少32字符
验证BETTER_AUTH_URL与实际访问URL一致

📚 学习资源与社区

官方文档与教程

完整文档：访问 /docs 目录或在线文档
视频教程：项目wiki中的"入门视频"系列
API参考：pnpm run docs 生成Swagger文档

贡献代码指南

Fork项目仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'feat: add amazing feature'
创建PR并描述功能改进

贡献者将自动出现在README的贡献者墙中

📈 功能路线图

阶段	主要功能	预计时间
v1.0	基础训练记录与动作库	已完成
v1.1	高级统计与进度图表	进行中
v1.2	移动响应式优化	Q4 2025
v2.0	社区功能与训练分享	2026 Q1
v2.1	智能训练计划推荐	2026 Q2