DuarteSantos8/openGym

来源: https://github.com/DuarteSantos8/openGym

一个你真正拥有的自托管健身与体重追踪工具。

规划你的每周训练、运行带引导的训练课程、记录每一组和你的体重——在手机上使用，在设备之间同步，通过你自己的 passkey 登录。

Discord (https://discord.gg/e62jY6fwVb) · 在线 (https://discord.gg/e62jY6fwVb) · GitHub stars (https://github.com/DuarteSantos8/openGym/stargazers) · Release (https://github.com/DuarteSantos8/openGym/releases) · Tests (https://github.com/DuarteSantos8/openGym/actions/workflows/test.yml) · Pipeline (https://gitlab.com/DuarteSantos8/opengym/-/pipelines) · Coverage (https://gitlab.com/DuarteSantos8/opengym/-/pipelines?ref=main)

License: AGPL v3

Website (https://opengym.duarte-santos.ch) · 在线 Demo (https://opengym.duarte-santos.ch/demo/) · Android APK (https://github.com/DuarteSantos8/openGym/releases/latest) · 自托管指南 · 路线图 · 更新日志

首页 · 今天的训练和体重 引导训练 · 动作演示和组数 统计 · 热力图、图表和 PR

为什么是 openGym

大多数健身 App 把你的数据留在它们的服务器上，诱导你购买订阅，或者在公司倒闭时随之消失。openGym 运行在你自己的服务器上，把数据存在你自己掌控的文件夹里，并且可以随意 fork。它依然表现得像一个现代应用：可安装到主屏、支持 passkey 登录、离线可用、手机和笔记本之间同步。不需要在别人的服务器上注册账号、没有订阅、没有广告、没有遥测数据。一条 docker compose up 就能跑起来。

浏览器在线 demo (https://opengym.duarte-santos.ch/demo/) 是带示例数据的真实应用，如果你想在安装任何东西之前先试试看。

功能

计划编排

• 每个工作日对应一个训练计划，建立在包含 1,324 个动作 的动作库之上，带动画演示，可搜索，也可在人体肌群图上按部位浏览。按你拥有的器械进行筛选。
• 四个起步模板（推拉腿、上下肢分化、全身、5×5），加载后即可像普通计划一样自由编辑。
• 可以把某一次训练挪到另一天，而不影响整周计划。每周从周一开始还是周日开始，由你决定。
• 超级组、热身组、递减组、休息暂停法、计时类动作（平板支撑、悬垂、农夫行走）、按时间和速度记录的有氧训练、每个动作的休息时间、计划好的减载周。
• 支持自定义动作，配上你自己的照片、GIF 或短视频。位置信息在设备上传前就会被剥离。

训练执行

• 引导式训练：今天的训练自动开始，重量会根据上次的记录预填，组间有休息计时器，PR 会随训练实时检测。在休息日，它会告诉你下一次训练是什么时候。
• 安静的训练界面：每个动作一个菜单，组数本身就是这一组的菜单，支持卡片视图或列表视图。如果怀念以前的按钮排布，在设置里打开开关即可恢复。
• 可选的努力程度列，以 RIR 或 RPE 形式呈现，带颜色标注，并为每个等级配了一句通俗易懂的说明。
• 杠铃、EZ 杆、六角杠和史密斯机的杠片计算，根据你自己拥有的杠片来算。
• 自重动作知道自身不带负重：记录次数即可，需要时加上负重腰带。
• 箭步蹲和单臂训练支持分侧计次，训练时屏幕保持常亮，休息提醒可以设置在嘈杂的健身房里让屏幕闪烁。

进度追踪

• 每个计划或每个动作都有各自的进阶规则：线性进阶、Greyskull LP、通过可见次数区间的双重进阶，或增加时长。每个目标都会解释为什么是这个数字；次数没做完绝不加重，停滞则触发减载。
• 每个动作的估算 1RM 及其独立曲线、结构平衡比（Poliquin、Thibaudeau、ATG）、为期一年的活动热力图。
• 肌群图的三种模式：训练量流向了哪里、哪些肌群仍在恢复、哪些肌群尚未训练。
• 体重图表带目标参考线。
• 事后可以编辑任何已保存的训练、补录你纸上记的训练、或把训练移到正确的日期。记录会根据修正后的历史重新计算。

账号与数据

• 支持 passkey（Face ID、Touch ID、指纹），每个档案的数据可在多设备间同步。密码登录可在每个实例单独开启；新设备通过一次性配对码或二维码配对。
• 两台设备同时编辑时会合并而非互相覆盖（见同步机制）。
• 支持从 FitNotes、Strong、Hevy（CSV 或 API key）以及 Apple Health 的体重导出文件中导入数据。随时可以将全部数据导出为一个 JSON 文件。
• 可以把计划分享为一个小文件，或者打印成 PDF。
• 可选的管理后台，支持仅限邀请注册和活动日志。
• 支持 17 种语言，包括从右到左书写的阿拉伯语。绝大多数语言的动作名称和说明都有翻译。

可选附加组件，默认关闭

• 一个 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

打开后点击 Create profile，即可进入。首次启动会一次性下载动作媒体资源（约 140 MB）。要通过 passkey 从手机访问，需要在某个域名上启用 HTTPS；在 .env 里改两行即可。自托管指南覆盖了 Cloudflare Tunnel、Caddy、Traefik 和 nginx，另外还有针对局域网 HTTPS 和 Kubernetes 的独立指南。

镜像会从同一个 tag 发布到 registry.gitlab.com/duartesantos8/opengym/{api,web}（即 docker-compose.yml 拉取的地址）和 ghcr.io/duartesantos8/opengym-{api,web}。如果你偏好 GHCR，把 image: 行换掉即可；或者运行 docker compose up -d --build 在本地构建。无论哪种方式，宿主机上都不需要安装 Node。

配置参考（全部通过 .env 设置）

推送通知密钥在首次运行时生成到 ./data/vapid.json。DATA_DIR 在容器内固定为 /data，映射到宿主机的 ./data；要改就改挂载卷，不要改这个变量。自托管指南详细介绍了每一个选项。

手机 App

同一套代码库可以用 Capacitor 构建为独立 App：无需账号、无需服务器，一切数据留在手机上，带有原生提醒和通知栏中的休息倒计时。

• Android： 从最新 Release (https://github.com/DuarteSantos8/openGym/releases/latest) 或网站 (https://opengym.duarte-santos.ch) 下载签名的 APK。每个构建产物旁边都有对应的 .sha256，App 自身支持检查更新。openGym 是有意不发布到 Play Store 的。
• iPhone： Apple 不允许从 App Store 以外安装应用。你可以自托管后从 Safari 把 PWA 添加到主屏，或者用 Xcode 把原生 App 构建到你自己的设备上。详情和构建说明：docs/MOBILE.md。

工作原理

• frontend/ 是 React 19 + Vite（React Router、Zustand），在 Docker 内构建为静态文件。
• api/ 是纯 node:http 实现，只有两个依赖：用于 passkey 的 @simplewebauthn/server，以及用于通知的 web-push。所有数据以 JSON 形式存储在 ./data 下。
• web/ 负责构建前端并用 nginx 托管，代理 /api，让整个应用位于同一个 origin 上——这是 passkey 的要求。

训练逻辑（进阶规则、1RM、已记录训练如何被重新读取）位于 frontend/src/lib/ 下的纯函数中，旁边就有对应测试。HTTP API 以 OpenAPI 规范的形式记录在 api/openapi.yaml，可在 opengym.duarte-santos.ch/api.html (https://opengym.duarte-santos.ch/api.html) 在线浏览。

同步机制

每个档案的数据是一份文档，带服务器版本号。设备会连同修改内容一起发送它上次见到的版本号；如果在这期间有另一台设备写入过，服务器会拒绝该请求并返回当前文档，让设备进行合并后重试。断开连接或退出登录时，未到达服务器的内容不会被丢弃，应用在离线状态下会显示提示横幅。

你的数据

所有数据都存放在你宿主机的 ./data 下：

备份 ./data 就等于备份了一切。passkey 的私钥永远不会到达服务器，它们保存在手机的安全硬件或你的密码管理器中。

文档

文档索引按目标读者分类整理了所有指南。最常用的几篇：

路线图

大约每两周发布一次，每个版本都很小且有明确主题。完整计划在 ROADMAP.md 中，issue 集中在 GitHub milestones (https://github.com/DuarteSantos8/openGym/milestones)。

社区

• Discord (https://discord.gg/e62jY6fwVb)，用于发布版本公告、自托管互助和快速交流。通常这是得到回复最快的方式。
• Discussions (https://github.com/DuarteSantos8/openGym/discussions)，适合提出希望后续的人能通过搜索找到的问题和想法。
• Issues (https://github.com/DuarteSantos8/openGym/issues)，用于可复现的 bug 和已经达成共识的工作项。登录问题几乎总是 RP_ID/ORIGIN 不匹配导致的；自托管指南有专门说明。
• Pull requests (https://github.com/DuarteSantos8/openGym/pulls) 欢迎提交；请先阅读 CONTRIBUTING.md。

代码在哪里

GitHub 是本项目的主场。gitlab.com/DuarteSantos8/opengym (https://gitlab.com/DuarteSantos8/opengym) 是一个镜像，由 GitHub Actions workflow 在每次推送到 main 和每个 release tag 时自动更新。它之所以存在，是因为它的 CI 负责构建发布产物：签名的 APK、多架构镜像和 SBOM。没有任何东西是手工合并到那里的。

在更新日志中，!NN 指的是 2026 年 8 月和 9 月那段项目暂居 GitLab 期间的 GitLab merge request。

openGym 是如何开发的

有人问过这件事，所以直说：openGym 是使用 Claude Code (https://claude.com/claude-code) 开发的，即 Anthropic 的编程智能体。相当大一部分代码、测试和文档是在 Claude Code 会话中起草的，仓库中也带有一份 CLAUDE.md，记录了这些会话所依据的项目上下文。这意味著什么、又不意味著什么：

• 由人来决定和发布。 什么进入代码库、什么被审查合并，以及每一次发布，都是维护者的决定。改动会在预发布实例和真实手机上测试之后才会打 tag。
• 测试锁住逻辑。 训练逻辑有单元测试覆盖，pull request 在 CI 中运行前端、API 和 MCP 三套测试。无论代码出自谁或什么之手，这是防止“看起来合理但其实有错“的代码的关键防线。
• 应用本身不需要大语言模型。 默认安装下，没有任何东西会调用 AI 服务。AI 教练和 MCP 服务器都是可选开启的，教练只与你配置的服务商通信，使用你自己的密钥。社区的 pull request 由作者用他们自己喜欢的任何工具编写，并接受同样的审查流程。

支持

openGym 是免费的，并且会一直免费：AGPL 许可、没有付费版本、没有什么内容是为了留给赞助者。如果它替你省掉了付费的追踪软件，你愿意出一份力，下面有咖啡按钮。一颗星、一份 bug 报告或一个 pull request 同样重要。

Star History Chart (https://star-history.com/#DuarteSantos8/openGym&Date)

许可证

openGym 自身的代码 采用 GNU AGPL v3.0 许可。你可以自托管、使用、修改和分享它；如果你把修改后的版本作为网络服务运行，你必须以相同的许可证提供该版本的源代码。

动作媒体资源不受上述许可证覆盖。 动作元数据和说明文字来自 ExerciseDB v1，通过 hasaneyldrm/exercises-dataset 以 MIT 许可提供。图片和动画属于第三方内容，既不受 MIT 许可保护，也不受 AGPL 许可保护，且其所有权存在争议：数据集将其归属于 Gym visual，而 ExerciseDB/AscendAPI（exercisedb.io/faq）声称拥有它们。openGym 不再分发这些资源（你的实例在首次启动时自行下载），也不对它们重新许可。若要复用这些媒体资源，请先与权利方确认。完整的第三方声明，包括人体示意图的几何数据，都在 NOTICE.md 中。