openGym 健身房管理系统

项目概述

openGym 是一款可自托管的健身与体重追踪应用。用户完全拥有自己的数据，无需依赖第三方服务器，无需订阅，无广告，也无遥测。运行一条 docker compose up 即可启动。它具备现代应用的全部特性：可添加到主屏幕、支持通行密钥（Passkey）登录、离线工作，并在手机与电脑之间同步。

核心功能

训练规划

内置超过 5600 个练习的图库，包含动画演示，可按身体部位、肌肉群浏览并按自有器械筛选。提供四种入门计划：推/拉/腿、上/下身、全身、5×5，均可作为普通例程编辑。支持单独移动某次训练到其他日期而不打乱整周安排，星期从周一或周日开始可选。

支持轮换式安排（A、B、C、A……），下一场训练自动选取未完成的那一场。功能涵盖超级组、热身组、递减组与暂停-休息组、计时练习（平板、悬挂、负重行走）、按时间和速度设置的有氧运动、每次练习的休息时间，以及预设的减载周。

用户可创建自定义练习，自带照片、GIF 或短视频，上传前会在设备上自动剥离定位信息。

训练执行

引导式训练自动启动当日内容，重量从上次自动预填，组间计时器自动运行，并在过程中检测个人最佳纪录（PR）。休息日会提示下一次训练的安排。

界面风格简洁：每个练习对应一个菜单，组号即该组的菜单，支持卡片或列表列表模式，可在设置中恢复传统按钮行。可选的"用力程度"列支持 RIR 或 RPE，配色编码并附带通俗说明。杠铃配重计算支持杠铃、EZ 杠、Trap 杠与史密斯架，依据用户自有杠铃片计算。自重训练默认无负重，可记录次数并按需添加负重带。

单侧次数适用于弓步和单臂动作；训练时屏幕保持常亮；休息计时器可在嘈杂环境中闪烁屏幕提醒。组数据支持左滑删除（带撤销）、右滑复制；金字塔组可设置每组的次数和休息；任意休息时间最长支持 15 分钟的滚轮选择。

进度追踪

每个例程或每个练习可设置渐进规则：线性、Greyskull LP、双重渐进（在可见次数区间内）、三重渐进（次数→组数→重量）、或以时间形式递增。每个目标都会说明其设定原因；未完成的次数不会增加负荷，停滞会触发减载。

每个练习可估算 1RM 并绘制独立曲线；结构平衡比率（Poliquin、Thibaudeau、ATG）以及全年活动热力图。肌肉图提供三种模式：训练量分布、仍在恢复的部位、未被训练的部位。体重图表可对照目标线查看，进度照片按时间线排列并支持前后对比滑块。

任何已保存的训练都可以事后编辑、补录纸上记录的训练，或迁移到正确日期，记录会从修正后的历史中重新读取。

账户与数据

支持通行密钥（Face ID、Touch ID、指纹），每个档案的数据可在多设备间同步。可按实例启用密码登录；新设备通过一次性代码或二维码配对。两台设备同时编辑时按字段合并而非相互覆盖（详见同步机制）。

支持从 FitNotes、Strong、Hevy（CSV 或 API 密钥）以及 Apple Health 体重导出导入数据，可随时将全部数据导出为单个 JSON 文件。计划可作为小文件分享或打印为 PDF。可选的管理员仪表板支持仅邀请注册并附带活动日志。共支持 19 种语言，包括从右到左的阿拉伯语和繁体中文，大部分语言的练习名称与说明已翻译完成。

可选扩展（默认关闭）

AI 教练可根据情况起草一周的例程，并基于训练日志后续提出修改建议。所有更改需用户批准。它运行在自有服务器上，使用用户自己的提供方密钥（Anthropic、OpenAI、Gemini 或任何 OpenAI 兼容端点，含 Ollama）。

MCP 服务器允许 Claude Desktop 等助手回答关于训练历史的问题，仅本地只读访问，不包含在 Docker 构建中。

快速开始

需要已安装 Docker 与 Compose：

git clone https://github.com/DuarteSantos8/openGym
cd openGym
cp .env.example .env
docker compose pull      # 拉取预构建的多架构镜像（amd64 + arm64），跳过则从源码构建
docker compose up -d

访问 http://localhost:8080，点击"创建档案"即可使用。练习动画已打包在镜像内，无需额外下载。如需在手机上通过通行密钥访问，须在域名上启用 HTTPS，相关配置在 .env 中调整即可。

架构说明

前端使用 React 19 与 Vite（搭配 React Router、Zustand），在 Docker 中构建为静态文件。后端为纯 node:http，仅依赖 @simplewebauthn/server（处理通行密钥）与 web-push（处理通知），所有数据以 JSON 格式存储于 ./data 目录。Web 容器使用 nginx 提供前端服务并代理 /api，使整个应用位于同一源（通行密钥要求）。

训练逻辑（渐进规则、1RM 计算、训练日志回读）以纯函数形式位于 frontend/src/lib/，并附带单元测试。HTTP API 以 OpenAPI 规范文档化。

同步机制

每个档案的数据是一份带服务器版本号的文档。设备提交修改时附带最后所见的版本号；若其间已有其他设备写入，服务器拒绝并返回当前文档，设备合并后重试。每次修改都带有独立的时间戳，粒度细到单个设置或例程字段，合并时保留每个字段的最新编辑，删除状态保持不变。断网或注销时未上传至服务器的内容不会丢失，应用会在离线时显示横幅提示。

数据存储

所有数据保存在主机的 ./data 目录：

• db.json：档案与公开的通行密钥数据
• db.json.bak：上一次可读副本，主文件读取失败时使用
• state-<user>.json：每位用户的计划、训练、体重与设置
• audit.log：管理员活动日志（默认不记录 IP）
• secret：会话 cookie 签名密钥

备份 ./data 即完成全部备份。通行密钥的私钥从不进入服务器，始终保存在手机的硬件安全模块或密码管理器中。

移动应用

同一套代码库通过 Capacitor 构建独立应用，无需账户、无需服务器，所有数据保留在手机本地，并支持原生提醒与通知栏休息倒计时。

• Android：从最新发布下载已签名 APK，或从官网下载。每个构建附带 .sha256 校验文件，应用会自检更新。
• iPhone：苹果不允许 App Store 外的安装。可自托管后通过 Safari 将 PWA 添加到主屏幕，或使用 Xcode 在自有设备上构建原生应用。

路线图

约每两周发布一次，每个版本小型且主题明确。下一阶段将完成社区心愿单，随后引入全新的练习数据库，之后保持每两周一次的主题发布节奏。

许可证

openGym 自身代码遵循 GNU AGPL v3.0，可自托管、使用、修改与共享；若以修改版本作为网络服务运行，须以相同许可证提供该版本的源代码。练习媒体（静图与动画）由 Aliaksandr Makatserchyk（Gym visual）版权所有，仅授权于 openGym 使用；非商用分支可在保留声明的前提下原样使用，其他用途需自行获取授权。练习文本为 openGym 自有内容，欢迎贡献。贡献者需签署贡献者许可协议（CLA）：贡献者保留作品版权，openGym 可使用并再授权，AGPL 版本始终保持 AGPL。