openGym部署前置准备：Docker Compose环境搭建完整教程

openGym部署前置准备：Docker Compose环境搭建完整教程

【免费下载链接】openGymSelf-hosted gym & body-weight tracker — plan routines, log workouts (supersets, warm-ups, cardio), see which muscles are trained, fatigued or detrained, import from FitNotes/Strong/Hevy, passkey login. Your data, your server.项目地址: https://gitcode.com/GitHub_Trending/op/openGym

openGym 是一款自托管的健身房与体重记录应用：规划训练计划、记录超组/热身/有氧训练、查看肌肉负荷与疲劳状态，还支持从 FitNotes、Strong、Hevy 导入历史数据。它的官方部署方式只依赖Docker Compose——不需要在服务器上安装 Node、Postgres 或任何数据库。本文带你完成 openGym Docker Compose 部署前的全部准备：环境检查、仓库克隆、.env配置，直到一键启动并通过健康检查。

部署前必知：openGym 的容器架构

在动手之前，先花 1 分钟看懂 openGym 由哪几部分组成。整个部署就是3 个容器 + 1 个数据目录：

• media：一次性容器，首次启动时下载约 140 MB 的动作演示图片和 GIF 到media/img与media/gif，完成即退出；
• api：Node 服务，负责登录（passkey）与数据存储，所有用户数据以 JSON 形式写入宿主机的./data目录；
• web：nginx 容器，对外暴露 8080 端口，负责提供前端页面并把/api请求代理给 api 容器。

完整的编排逻辑都在根目录的 docker-compose.yml 中：media 服务定义、api 服务定义、web 服务定义。理解了这一点，后面排查问题会轻松很多。

Docker Compose 部署前置条件清单

在开始之前，请逐项确认你的服务器满足以下条件：

💡为什么 passkey 这么重要？openGym 默认用 passkey（Face ID / 指纹）登录，浏览器强制要求 HTTPS（仅http://localhost例外）。所以"电脑上用没问题、手机上用不了"几乎是 100% 的 HTTPS 问题，不是环境没搭好。

克隆仓库并配置 .env 环境变量

在服务器上执行以下命令获取代码（仓库地址：https://gitcode.com/GitHub_Trending/op/openGym）：

git clone https://gitcode.com/GitHub_Trending/op/openGym cd openGym cp .env.example .env

openGym 的全部配置都通过.env文件完成，官方模板.env.example顶部就给了可直接运行的本地默认值：

RP_ID=localhost ORIGIN=http://localhost:8080 WEB_PORT=8080 RP_NAME=openGym

只在你自己的电脑上体验的话，保持默认即可。如果你打算用手机访问（正式部署），需要提前决定一个域名，并改为：

RP_ID=gym.example.com ORIGIN=https://gym.example.com

⚠️两个高频错误：RP_ID只能写裸主机名（无协议、无端口、无斜杠），ORIGIN必须带协议且不带结尾斜杠。另外，后期修改RP_ID会使所有已注册的 passkey 失效，所以域名要在别人注册账号之前定好。

一条命令启动：Docker Compose 部署步骤

配置完成后，部署只有三步：

docker compose pull # 拉取预构建镜像（amd64 + arm64） docker compose up -d # 后台启动三个容器 docker compose ps # 确认 web 与 api 状态为 running

首次启动时，media 容器会打印类似↓ Downloading exercise media (~140 MB, one time)…的日志，下载完成后 web 容器才会就绪。如果你所在网络拉取镜像困难，也可以跳过pull，改用docker compose up -d --build从源码构建（api/Dockerfile 与 web/Dockerfile 已内置构建流程），主机上依然不需要 Node 环境。

部署验证：健康检查与首次登录

用下面的命令确认服务真正可用：

docker compose ps curl http://localhost:8080/api/health # 返回 {"ok":true,...} 即成功

然后打开http://localhost:8080，点击Create profile创建你的第一个 passkey 档案，就能进入应用首页。查看容器日志可以随时执行docker compose logs -f，停止栈用docker compose down。

部署避坑：三个高频问题与修复

还有一个新手容易踩的坑：修改.env后执行docker compose restart不会重新读取环境变量，必须用docker compose up -d重建容器。

部署之后：备份与进阶路线

openGym 的所有用户数据（档案、passkey 公钥、训练记录、自定义动作媒体）都集中在宿主机的./data目录，备份只需一行：

tar czf opengym-backup-$(date +%F).tar.gz data/

后续可深入阅读的资料（仓库内均为相对路径文档）：

• 官方自托管完整指南（域名、反代、多用户管理）：docs/SELF_HOSTING.md
• Kubernetes 部署清单：kubernetes/ 目录，说明见 docs/SELF_HOSTING_KUBERNETES.md
• 常见问题速查：docs/FAQ.md
• 全部环境变量参考表：README.md

到这里，你的 openGym 自托管实例已经跑起来了。记住核心原则：一个.env管所有配置，一个data/目录管所有数据，这就是 openGym Docker Compose 部署的全部复杂度。🏋️

【免费下载链接】openGymSelf-hosted gym & body-weight tracker — plan routines, log workouts (supersets, warm-ups, cardio), see which muscles are trained, fatigued or detrained, import from FitNotes/Strong/Hevy, passkey login. Your data, your server.项目地址: https://gitcode.com/GitHub_Trending/op/openGym