1. 痛点突围：它究竟击穿了什么工程死穴？
当前市面上的绝大多数健身追踪软件，底层商业逻辑均建立在数据托管与功能订阅之上。开发者在日常力量训练中产生的结构化体量数据，被迫存储于第三方商业云端。一旦目标服务商调整商业策略、遭遇数据库宕机或直接关停，用户的历史训练曲线、1RM 演进模型以及长达数年的动作组数记录便会瞬间清空。更严重的是，这类软件往往内置复杂的遥测代码，在无感知的情况下将用户的身体数据与训练偏好上传至远程服务器。
openGym 通过彻底剥离云端依赖进行正面反击。整个架构围绕本地容器构建，数据持久化在宿主机的指定目录中。用户不再需要向任何商业应用支付月度订阅费，也不用担心核心训练隐私遭到广告算法分析。它将现代 Web 应用的用户体验（如渐进式网页应用、Passkey 硬件级生物识别登录、离线状态读写）与传统本地软件的绝对控制权完美融合。
💡 架构核心洞见：通过将现代前端状态管理直接挂载至本地持久化卷，openGym 在抹平本地部署门槛的同时，彻底消除了第三方服务器作为单点故障的隐患。
2. 核心架构与底层数据流向解析
openGym 的后端采用精简的 API 服务与静态 Web 前端分离设计，两者通过 Docker 容器化封装。当客户端发起动作查询、组数记录或训练计划同步时，请求直接流经内部反向代理并命中本地持久化存储层。系统内置的同步逻辑支持多设备并发修改，当两台设备同时离线并产生数据变更时，底层合并算法自动解析冲突而不是粗暴地覆盖最新写入。
[ Mobile / Web Client ] ---> [ Nginx Proxy / Gateway ] ---> [ API Service Container ]
│
▼
[ Local Persistent Volume ] <--- [ Sync & Merge Engine ] <--- [ SQLite / File Store ]
在底层数据流转中，动作媒体资源在首次启动时完成拉取（约 140MB 的动图与多媒体库），后续交互完全在本地局域网或受控服务器内完成。定位数据或设备标识在上传前经过客户端清洗，保障隐私不外泄。可选的 AI 教练模块并不硬编码在核心镜像内，而是作为独立的可选扩展，由用户自行配置 Anthropic、OpenAI、Gemini 或 Ollama 等任意 OpenAI 兼容端点的 API Key，将控制权完全下放。
3. 技术选型与性能横向硬核对比
| 选型维度 | 本方案 (openGym) | 传统实现范式 (如 Strong / Hevy) | 典型开源练功房软件 | 生产环境收益 |
|---|---|---|---|---|
| 数据存储位置 | 本地 Docker 卷 / 自控路径 | 商业云端数据库 (AWS/GCP) | 杂乱的本地 JSON 文件 | 100% 数据主权，免受云端宕机影响 |
| 认证与安全 | 硬件级 Passkey (Face ID/Touch ID) | 邮箱密码 + 第三方 OAuth | 明文密码或基础 Basic Auth | 彻底规避凭证撞库与中心化数据泄露 |
| 运行开销 | 单个 docker compose up，内存 < 150MB |
持续月度订阅费 ($5-$10/月) | 需要复杂的 Node/Python 源码构建 | 零订阅成本，硬件资源消耗极低 |
| 多端同步机制 | 实时冲突合并同步引擎 | 强依赖云端中心化锁机制 | 不支持或仅支持单机导出导入 | 多端并行修改不丢数据，支持离线运作 |
| 离线能力 | 完整 PWA 离线读写缓存 | 弱网或无网时核心功能受限 | 仅支持基础离线查看 | 健身房地下室等极端网络环境正常记录 |
这套技术选型直接瞄准了工程师群体的核心诉求：不要多余的云端中间商，不要突如其来的订阅涨价，只要开箱即用的稳定容器与完全可控的数据物理路径。
4. 手把手极客实操：从零构建最小闭环
在具备 Docker 与 Docker Compose 运行环境的服务器或本地 Linux/macOS 工作站上，执行以下初始化脚本拉取并拉起完整容器集群。
# 克隆官方代码仓库到本地工作目录
git clone https://github.com/DuarteSantos8/openGym
cd openGym
# 复制环境变量模板文件
cp .env.example .env
# 预先拉取预构建的 amd64 与 arm64 架构镜像
docker compose pull
# 在后台启动整个容器化服务集群
docker compose up -d
服务成功启动后，在浏览器访问 http://localhost:8080。点击页面上的 Create profile 按钮即可完成本地初始化。首次运行系统会自动触发静态多媒体资源（约 140MB 动作演示库）的本地解压与挂载。
5. 生产落地踩坑指南与避坑建议 (Gotchas)
在将 openGym 部署至公网服务器或长期用于生产环境时，必须注意网络拓扑与硬件绑定的固有约束。
⚠️ 避坑预警 Passkey 绑定失效：若在
.env中未正确配置RP_ID与ORIGIN为真实的 HTTPS 域名，移动端浏览器将拒绝注册或调用硬件 Passkey。生产部署时务必搭配 Caddy、Traefik 或 Cloudflare Tunnel 启用完整 TLS。⚠️ 避坑预警 首次启动网络超时：首次执行
docker compose up -d时，API 容器需要初始化 140MB 的动作资源媒体。若服务器网络直连 GitHub/GitLab 镜像源存在延迟，可能导致健康检查超时，建议在海外节点或配置合适的代理加速拉取。⚠️ 避坑预警 定期状态备份：由于数据完全掌握在用户手中，宿主机挂载目录即为唯一真理源。建议配合自动化脚本将持久化卷定时打包并异地加密归档，防止物理磁盘故障导致历史训练数据丢失。