SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-11-06

如何用 Docker Compose 自行托管 openGym

了解如何在 VPS 上部署 openGym:固定 v1.2.7 标签,首次创建 Passkey 前配置域名和 TLS,确认 ./data 与 ./media 的数据位置,并按需运行 MCP 服务器。

自行托管 openGym 后的情况

您可以通过克隆代码仓库、修改 .env 中的两行配置,并在终止 TLS(传输层安全)的反向代理后运行 docker compose up -d --build,来自行托管 openGym。openGym 是健身和体重训练跟踪器:提供每周计划和指导训练,并记录每组训练以及体重变化。它采用 AGPL-3.0 许可,所有数据都以纯 JSON 文件形式存储在磁盘上,因此无需运行数据库服务器。

该技术栈包含两个长期运行的容器:一个提供 React 构建文件的 nginx 容器,以及一个承载 API 的 Node 容器。此外,首次启动时还会运行一个一次性任务,下载约 140 MB 的训练动作图片和 GIF。

项目的 README 暗示了两点,但没有向在公网服务器上部署的用户明确说明。Passkey 登录与主机名绑定,因此域名及其证书必须在首次登录前就绪,而不是登录后再配置。固定在 v1.2.7 标签的可选 MCP 服务器仅支持只读操作,并且运行在 AI 客户端所在的机器上,而不是该技术栈内部。如果数据位于 VPS 上,这会改变您的操作方式。目前的 MCP 服务器在与您的服务器配对后,也支持记录训练。

openGym 仍处于早期阶段。第一个带标签的版本 v1.0.0 的日期是 20 July 2026,v1.2.7 于 18 August 2026 发布。该项目在第一个月就有 13 个标签,到 9 October 2026 已达到 34 个标签,并在当天标记了 v1.4.0。这说明应用仍在快速变化,因此应检出某个发布标签,而不要直接构建默认分支当前包含的代码。

首次登录前规划域名

Passkey 是登录 openGym 的方式。Passkey 绑定到依赖方 ID(RP ID),也就是创建凭据时使用的域名。浏览器只会通过 HTTPS 创建 passkey。唯一的例外是 localhost。

用户在手机上会遇到这一限制。从其他设备打开 http://203.0.113.10:8080 时,完全不会出现 passkey 提示,因为浏览器拒绝在普通 HTTP 来源或裸 IP 地址上创建凭据。项目自身的故障排查说明也指出了相同问题:没有提示,表示你正在使用 http:// 或 IP 地址。

更严重的是,RP ID 已写入用户注册的每个凭据。之后再修改 RP_ID,用户设备上存储的 passkey 就不再匹配,所有人都无法登录。先确定主机名,将 DNS 指向 VPS,并在任何人点击 Create profile 之前配置好证书。

使用 Docker Compose 部署 openGym

Compose 文件会将相对于自身路径的 ./data 和 ./media 绑定挂载,因此您克隆到的目录就是数据库。请将其放在持久化存储位置。

sudo install -d -o "$USER" -g "$USER" /opt/opengym
git clone https://github.com/DuarteSantos8/openGym /opt/opengym
cd /opt/opengym
git checkout v1.2.7
cp .env.example .env

README 中提供了 github.com/DuarteSantos8/openGym 克隆 URL。截至 2026 年 11 月 4 日,该仓库可以正常访问,并将自身描述为项目主页。首次构建前请切换到指定标签:默认分支已经超出本指南所述的版本。在该分支中,练习动画已包含在镜像内,下面的媒体任务也已不存在。关于固定版本的原因,请参阅版本固定一节。

编辑 .env。在 VPS 上,有三行配置很重要。

RP_ID=gym.example.com
ORIGIN=https://gym.example.com
WEB_PORT=127.0.0.1:8080

RP_ID 是不带协议的主机名,ORIGIN 是包含协议的完整 URL。两者必须与浏览器地址栏中的地址完全一致,否则登录时会失败,并显示 verification failed。WEB_PORT 的含义将在“保持端口 8080 私有”一节中说明。

docker compose up -d --build
docker compose ps --all
docker compose logs media

docker compose ps --all 应显示正在运行的 web 和 api,以及退出码为 0 的 media。请保留 --all 标志:没有该标志时,Compose 只会列出正在运行的容器,因此已完成的 media 任务完全不会显示。该任务退出是正常的:媒体任务执行 restart: "no",因为它只需执行一次下载。其日志末尾会有一行以 ✓ Exercise media ready 开头,ls media/img | wc -l 应输出 1,324,而不是 0;这是截至 2026 年 10 月 9 日,上游练习数据集提供的缩略图数量。如果目录为空,说明下载失败,应用随后会显示空白图片的练习卡片。

请保留 --build 标志。该标签对应的 Compose 文件会从 ghcr.io 使用 latest 标签的预构建镜像。虽然这些镜像截至 2026 年 10 月 18 日已重新发布,但 latest 会跟随最新版本,因此 docker compose pull 运行的代码会比您刚刚检出的源代码更新。两个服务都包含 build 部分,而 --build 会改为使用您检出的代码构建它们。如果您刚开始使用 Compose,请先阅读 VPS 上的 Docker Compose,然后返回此处。

固定版本,因为该项目仍处于早期阶段

镜像仓库再次提供了带版本号的镜像,但 v1.2.7 中的 compose 文件仍请求 latest。截至 4 November 2026,latest 指向 1.4.4,该版本于 3 November 2026 发布。需要固定的是磁盘上的检出版本,因为它决定容器中最终使用哪个应用版本。

cd /opt/opengym
git fetch --tags
git checkout v1.2.7

git status 现在会报告处于该标签对应的 detached HEAD 状态,这正是服务器上需要的状态。在检出其他版本之前,当前版本不会自行变化。

v1.2.7 是编写本指南时所依据的版本,现在已经不是最新版本。后续版本会改变部署本身(默认分支中已移除媒体任务),因此在调整固定版本前,请阅读发布说明并对比 compose 文件。v1.4.2 和 v1.4.3 的发布说明还报告了安全修复,项目也要求自行托管的用户进行更新。

然后让 Compose 完全停止访问镜像仓库。将以下内容放入 docker-compose.override.yml,Compose 会自动加载该文件,并将其合并到受跟踪文件之上。标量键会由覆盖文件替换,因此无需修改 git 中的内容,git pull 也会保持干净。完整的合并规则请参阅Compose 如何合并覆盖文件。

services:
  api:
    pull_policy: build
  web:
    pull_policy: build

完成配置后,之后执行 docker compose up -d 时会基于现有源代码构建,而不是拉取当天 latest 所指向的任意内容。先确认合并已生效,然后在该标签对应的版本上重新构建。

docker compose config | grep pull_policy
docker compose up -d --build

使用反向代理终止 TLS

容器使用普通 HTTP。必须由前端组件保存证书。Caddy 配置最简单,因为它会自行从 Let's Encrypt 申请并续期证书。

gym.example.com {
    reverse_proxy 127.0.0.1:8080
}

nginx、Traefik 和 Nginx Proxy Manager 的工作方式相同。Cloudflare Tunnel 也是如此。项目文档介绍了该方案,而且完全不需要开放入站端口。

curl -sI https://gym.example.com | head -1

该命令应返回 HTTP/2 200,且不显示证书警告。现在在浏览器中打开网站,然后点击创建配置文件。如果出现 passkey 提示,但登录时报告 verification failed,则 RP_ID 或 ORIGIN 与地址栏中的 URL 不匹配。修正 .env,然后再次运行 docker compose up -d。该操作会重新创建容器,使容器读取新值。docker compose restart 不会重新加载 .env。

禁止将端口 8080 暴露到公网

默认情况下,Web 服务会在所有网络接口上发布 8080。因此,应用可通过公网 IP 使用明文 HTTP 访问,而代理在同一台服务器上提供 HTTPS。防火墙规则无法解决此问题。Docker 会在 nat 表中使用 DNAT 规则发布端口,然后在 FORWARD 链中处理该流量。Docker 自身的规则会在此接受流量,而 ufw 的规则位于 INPUT 路径上。因此,sudo ufw deny 8080/tcp 不会阻止任何流量。

解决方法是仅绑定到 loopback 地址。Compose 文件映射 "${WEB_PORT:-8080}:${NGINX_PORT:-80}",因此你在 WEB_PORT 中设置的值会替换该映射左侧的内容。Docker 的简写语法接受其中的 ip:port 对。因此,WEB_PORT=127.0.0.1:8080 可以正常工作。

docker compose config
sudo ss -ltnp | grep 8080

在合并后的配置中,Web 服务的 ports 下应显示 host_ip: 127.0.0.1。ss 应显示 127.0.0.1:8080,而不是 0.0.0.0:8080。从另一台机器访问时,curl http://<your-vps-ip>:8080 现在应被拒绝或超时,而 HTTPS 主机名仍应正常工作。

配置个人资料后关闭注册

默认情况下,注册功能处于开启状态,访客模式也已启用。在公网主机名下,这意味着任何找到该 URL 的人都可以在您的服务器上创建个人资料。请先注册您自己的个人资料,然后查找用户 ID:ls data/ 会为每个用户列出一个名为 state-<uid>.json 的文件,其中的 <uid> 就是您需要的值。

ADMIN_UIDS=<your-uid>
INVITE_ONLY=1
ALLOW_GUEST=0

再次运行 docker compose up -d。此时,Settings 中会显示 Admin dashboard,您可以在其中生成和撤销邀请码。这样,只有与您一起训练的人员才能注册。openGym 不支持外部身份提供商,因此这些邀请码只控制此应用,不影响服务器上的其他服务;如果您希望为每个人在所有运行的服务中统一提供一个账号,可以在前面部署 Authentik 作为 forward auth 代理,在 openGym 自带的 passkey 登录界面加载前先限制该主机名的访问。

数据存放位置及保护数据的备份

所有数据都位于 ./data 目录中,该目录挂载到 API 容器内的 /data。文件分为四类:db.json 保存用户资料和公开的 passkey 凭据,state-<uid>.json 保存单个用户的日常计划、训练记录和体重,secret 是会话 cookie 密钥,vapid.json 保存首次运行时生成的推送通知密钥。

cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api

先停止 API,确保 tar 复制文件时,这些文件之间保持一致。在 v1.2.7 中,API 会将数据库和训练状态 JSON 写入临时文件,然后以原子方式将其重命名并覆盖目标文件,因此不会直接改写正在使用的文件。随后将归档文件复制到服务器之外,因为 VPS 上的归档无法在 VPS 故障后保留。不要将 media/ 纳入备份:其中包含 140 MB 的训练图片,媒体任务会重新下载这些图片,无需额外费用。

恢复数据时,需要将归档解压到同一路径,并由使用相同域名的主机提供服务。手机中存储的 passkey 与创建它时使用的 RP ID 绑定,因此恢复到新主机名后,数据库虽然可以正常使用,但任何人都无法登录。应保留原域名,或计划重新注册每个 passkey。相同的原则也适用于其他服务;备份和升级 Docker Compose 堆栈介绍了通用流程。

固定版本的 MCP 服务器为只读,并在您的机器上运行

MCP(模型上下文协议)用于让 Claude Desktop 或 Cursor 等客户端与本地工具服务器通信。openGym 在 mcp/ 中提供了一个 MCP 服务器。它不属于 compose 文件,不是容器,也不监听任何端口。客户端将其作为子进程启动,并通过 stdio 与其通信。固定版本的服务器只读取本地文件;当前服务器还会将训练记录写入您配对的 openGym API。

请在客户端运行的机器上安装,而不是在服务器上安装:

cd openGym/mcp
npm install

然后将其添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "opengym": {
      "command": "node",
      "args": ["/absolute/path/to/openGym/mcp/src/index.js"],
      "env": {
        "OPENGYM_DATA": "/absolute/path/to/openGym/data",
        "OPENGYM_UID": "<your-uid>"
      }
    }
  }
}

在单用户安装中,OPENGYM_UID 是可选的,因为服务器会自动检测找到的唯一配置文件。在当前默认分支中,它提供 11 个工具:list_routines、get_routine、preview_session、get_week_plan、list_workouts、get_workout、get_bodyweight、estimate_1rm、muscle_balance、get_programme 和 log_workout。preview_session 会显示应用在您启动训练计划时实际显示的内容,此时进阶策略和您的历史记录已经覆盖了原始计划。v1.2.7 标签提供了 8 个只读工具,不包含 preview_session、get_programme 或 log_workout。使用该固定版本服务器的助手可以回答您上周的卧推记录,但无法记录一组训练、编辑训练计划或删除任何内容。在当前分支中,10 个工具用于读取,log_workout 用于在完成配对后通过您的服务器保存训练记录;在完成配对前,该工具处于禁用状态。这份列表简明说明了智能体设计反复面对的一个决策:您公开的工具决定了模型能够执行的全部操作,而通过亲自编写循环来了解智能体的工作方式,是理解为什么只读工具集属于设计选择而非功能限制的最快方法。

VPS 用户需要解决下面这个问题。OPENGYM_DATA 是文件系统路径,而您的数据位于 VPS 上,AI 客户端位于笔记本电脑上。下面有两种如实反映这一情况的方案。

  1. 将数据复制到本地,并让服务器指向副本:rsync -a --delete user@gym.example.com:/opt/opengym/data/ ~/opengym-data/,然后将 OPENGYM_DATA 设置为 ~/opengym-data。固定版本的服务器只执行读取操作,因此复制数据不会丢失任何内容。需要获取最新数据时,重新运行 rsync。
  2. 通过 ssh 运行服务器,将 command 设置为 ssh,并将 args 设置为 ["-T", "user@gym.example.com", "OPENGYM_DATA=/opt/opengym/data node /opt/opengym/mcp/src/index.js"]。这要求 VPS 上已安装 Node,并且登录过程不会向 stdout 输出任何内容,因为 stdout 是协议通道。

这两种方案都假设智能体本身运行在您的笔记本电脑上。如果您希望智能体与数据运行在同一台机器上,OneCLI 会在服务器上为每个人提供隔离的智能体环境,这样返回 data/ 的 stdio 跳转再次成为本地通信。

如果 cat data/db.json 返回 Permission denied,则表示 API 容器以 root 身份写入了这些文件,您的登录用户无权读取。请使用 sudo 复制这些文件,或在主机上修改文件所有权。对于需要通过网络而不是 stdio 监听的服务器,请参阅在 VPS 上运行 MCP 服务器。

openGym 还是 wger:你应该运行哪一个?

wger 是该领域中成熟的选择,且软件规模大得多。它的 compose 栈包含运行 Django 应用的 gunicorn、PostgreSQL、Redis 以及 Celery worker,所有这些组件均位于 Nginx 之后。作为回报,你将获得营养和成分追踪、文档齐全的 REST API、庞大的社区锻炼数据库,以及供教练管理他人计划的功能。

openGym 由两个容器和一个 JSON 文件文件夹组成,除了 passkeys 之外无需管理任何账户。这就是两者全部的区别。如果你曾经 维护过 Chatwoot 的安装,即备份意味着 Postgres 转储文件加上上传目录,且每次版本升级都要运行数据库迁移,那么你已经了解 wger 在维护方面对你的要求。

如果你想在追踪训练的同时追踪饮食,或者需要一个 API 来进行开发,请运行 wger。如果你想要一个可以在一个下午内从头到尾读完代码的轻量级栈,并且希望登录时没有密码泄露的风险,请运行 openGym。这种选择的代价是成熟度:截至 2026 年 8 月 19 日,openGym 的首个版本发布仅一个月,而 wger 已经拥有多年的发布历史。请锁定你的版本,做好备份,并在每次更新前阅读发布说明。

如果你仍在决定什么值得在服务器上占用空间,2026 年什么值得自托管 一文涵盖了其中的权衡,而此应用可以与 用于食谱的 Mealie 或 用于财务的 Actual Budget 舒适地共存于同一台小型 VPS 上。

更新且不丢失任何数据

cd /opt/opengym
docker compose stop api
tar czf ~/opengym-$(date +%F).tar.gz data/
docker compose start api
git fetch --tags

使用 git checkout v<new> 检出所需的版本,然后运行 docker compose up -d --build,以便根据该标签重新构建容器。每次都必须先执行备份,因为从磁盘上的 JSON 文件恢复只需运行一条 tar 命令,几秒钟即可完成。

FAQ

为什么 openGym 从不在我的手机上显示通行密钥提示?

浏览器拒绝创建凭据,因为您正在使用 http:// 或裸 IP 地址,例如 http://192.168.1.20:8080。浏览器只允许在 HTTPS 源上使用通行密钥,唯一的例外是 localhost。请将 openGym 放在反向代理后面,并为真实主机名配置有效证书;在 .env 中设置 RP_ID=gym.example.com 和 ORIGIN=https://gym.example.com,然后运行 docker compose up -d,使容器加载新值。如果提示出现,但登录报告 verification failed,说明这两个值与地址栏中的 URL 不完全匹配。

openGym 将我的数据存储在哪里?如何备份?

数据位于 compose 文件旁边的 ./data 目录中,并作为 /data 挂载到 API 容器。该目录包含用于存储个人资料和公开通行密钥凭据的 db.json、每个用户一个的用于存储训练和体重数据的 state-<uid>.json、用于会话 Cookie 密钥的 secret,以及用于推送通知密钥的 vapid.json。使用 docker compose stop api 进行备份,然后运行 tar czf ~/opengym-$(date +%F).tar.gz data/,再运行 docker compose start api,并将归档文件复制到服务器之外。跳过 media/;该目录包含 140 MB 的训练图像,媒体任务会自行重新下载这些图像。

Claude 能读取我的 openGym 训练历史吗?

可以,通过 mcp/ 目录中的可选 MCP 服务器读取。固定版本 v1.2.7 的服务器提供 8 个只读工具。当前默认分支提供 11 个工具:10 个读取训练记录、训练日程预览、周计划、训练、体重、估算单次最大重量、肌肉平衡和训练计划的工具;log_workout 会在配对后通过您的服务器写入训练数据。它不是容器,也不会打开端口:您的客户端通过标准输入输出启动它,其读取工具直接访问 OPENGYM_DATA 中的 JSON 文件。由于这是文件系统路径,在 VPS 上运行 openGym 时,您需要将 data/ 的副本同步到运行客户端的计算机,或者在客户端配置中通过 ssh 调用服务器。

我应该自行托管 openGym,还是托管 wger?

如果您希望在训练日志旁边记录饮食和营养信息,或希望使用有文档说明的 REST API 进行扩展,请选择 wger。它运行的组件更多:nginx 后面是 gunicorn 运行的 Django、PostgreSQL、Redis 和 Celery worker。如果您希望只运行两个容器、使用 cat 读取 JSON 文件,并使用无需管理密码的通行密钥登录,请选择 openGym。截至 19 August 2026,openGym 的首个带标签版本已有一个月,因此每次更新前都应检出一个 git 标签,并备份 data/。

这篇文章对您有帮助吗?