Docker部署FluidCAD完整指南:5分钟自建团队共享的自托管3D建模服务

原创2026-11-02 13:02:031,811 阅读

Docker部署FluidCAD完整指南:5分钟自建团队共享的自托管3D建模服务

🚀 FluidCAD 是一款用 JavaScript 编写的开源参数化 CAD 建模工具,而Docker 部署 FluidCAD 是让它为整个团队服务的最佳方式:把项目集中存放在一台服务器上,团队成员用浏览器打开同一个 3D 建模工作区,修改尺寸、复用零件、协同迭代。本指南带你从零完成这套自托管 3D 建模服务的搭建,覆盖本地体验、团队共享、安全加固与版本更新。

FluidCAD 3D建模工作区:四缸发动机装配体、零件树与关节列表

为什么选择 Docker 部署 FluidCAD?

FluidCAD 提供三种使用形态:桌面应用、npm 包(npx fluidcad 在本地浏览器中运行)、以及 Docker 镜像(把服务搬到服务器上)。

FluidCAD 草图求解器:两个带直径标注的圆与切线,完全约束状态

Docker 方案的核心优势:

  • 📦 集中管理:所有项目存放在服务器的一个目录里,统一备份、统一版本
  • 🌐 浏览器即用:无需安装客户端,团队成员用 URL 即可打开 3D 建模界面
  • 🔒 权限可控:支持登录链接认证、主机名白名单、HTTPS 反向代理
  • 🔄 更新无痛:拉取新镜像重启容器,项目数据原样保留
  • ⚙️ 架构齐全:官方镜像同时支持 x64 与 ARM64,适配常见服务器与家用 ARM 设备

它的原理也很直白:容器内运行 FluidCAD 的"启动屏幕"服务(默认端口 3100),启动屏幕为每个项目单独启动一个引擎进程并代理访问,因此一台服务器即可承载多个项目、多名用户。

部署前准备:环境要求与目录规划

开始之前,只需准备以下两样东西:

准备项 说明
Docker 环境 已安装 Docker 或 Docker Compose 的 Linux / macOS / Windows 服务器
一个可写目录 用于存放项目,例如 ./projects

⚠️ 两个容易被忽略的细节(官方文档 installation.mdx 也有说明):

  • 容器以 uid 1000 的 node 用户运行,在 Linux 上挂载的项目目录必须对它可写:sudo chown 1000:1000 projects
  • 容器需要挂载两个目录:/app/projects(项目本体)和 /home/node/.fluidcad(引擎缓存、最近项目、预览图等运行记忆)

这两个挂载点在仓库根目录的 Dockerfile 中定义:/app/projects 存放项目,/home/node/.fluidcad 保存跨次运行需要记住的内容,服务默认监听 3100 端口。

方式一:在本机快速体验 FluidCAD 容器

如果你只是想在个人电脑上先跑起来看看,一条 docker run 就够了:

mkdir projects
sudo chown 1000:1000 projects
docker run -d --name fluidcad \
  -p 127.0.0.1:3100:3100 \
  -e FLUIDCAD_ALLOWED_HOSTS=localhost \
  -v "$PWD/projects:/app/projects" \
  -v fluidcad-home:/home/node/.fluidcad \
  ghcr.io/fluid-cad/fluidcad:latest

启动后查看日志,FluidCAD 会打印一条带 token 的登录链接:

docker logs fluidcad
# http://localhost:3100/?token=…

在浏览器中打开这条链接完成首次登录,之后容器重启前同一浏览器都会保持登录状态。注意端口只发布到 127.0.0.1,其他机器无法访问,这是最安全的默认姿势。

FluidCAD 中的拉伸特征:草图拉伸出的实体零件

方式二:团队共享部署(受信任网络免登录)

家庭局域网或 Tailscale 虚拟网络内,可以使用免登录模式,团队任何设备打开网址即用。在同级目录下创建 projects 文件夹和 compose.yaml:

services:
  fluidcad:
    image: ghcr.io/fluid-cad/fluidcad:latest
    ports:
      - "3100:3100"
    environment:
      FLUIDCAD_NO_AUTH: "1"
      # 团队访问 FluidCAD 时会用到的所有主机名,其他名称一律拒绝
      FLUIDCAD_ALLOWED_HOSTS: "fluidcad.example.com,192.0.2.20"
    volumes:
      - ./projects:/app/projects
      - fluidcad-home:/home/node/.fluidcad
    restart: unless-stopped

volumes:
  fluidcad-home:

然后启动:

docker compose up -d

团队成员从任意设备打开 http://fluidcad.example.com:3100 即可进入。

⚠️ 安全提示:免登录模式下,任何能访问该端口的人都可读写所有项目、并通过项目执行代码,因此请务必只在受信任网络内使用,不要直接把端口暴露到公网。

方式三:共享网络下的安全部署(HTTPS 反向代理)

办公室、学校这类共享网络推荐使用 HTTPS 反向代理(Caddy、nginx、Tailscale Serve 均可,需支持 WebSocket 升级转发),让端口只对本机代理可见:

services:
  fluidcad:
    image: ghcr.io/fluid-cad/fluidcad:latest
    ports:
      - "127.0.0.1:3100:3100"
    environment:
      FLUIDCAD_PUBLIC_URL: "https://fluidcad.example.com"
    volumes:
      - ./projects:/app/projects
      - fluidcad-home:/home/node/.fluidcad
    restart: unless-stopped

volumes:
  fluidcad-home:

此时服务恢复了登录认证:每个浏览器第一次使用时,从 docker compose logs fluidcad 拿到带 token 的登录链接,打开一次即可。登录机制的实现细节(token 换 HttpOnly 会话 Cookie、Host 校验防 DNS 重绑定等)可以参阅 launcher/src/server/auth.ts,容器启动服务的入口逻辑在 launcher/src/server/launcher-server.ts。

🔐 官方建议:FluidCAD 并非为直面公网而设计。需要远程访问时,请通过 Tailscale 等 VPN 进入自己可控的网络,而不是开放端口。

关键环境变量速查表

容器的全部配置都通过环境变量完成,每个变量都对应启动参数(参见 Dockerfile 中的入口命令注释):

环境变量 对应参数 作用
FLUIDCAD_ALLOWED_HOSTS --allowed-host 逗号分隔的允许主机名白名单,其他 Host 一律拒绝
FLUIDCAD_NO_AUTH --no-auth 置为 1 时免登录,需配合 FLUIDCAD_ALLOWED_HOSTS
FLUIDCAD_PUBLIC_URL --public-url 反向代理对外提供的源地址,如 https://cad.example.com

容器内项目是如何组织的?

理解了这一点,日常运维会轻松很多:

  1. 启动屏幕(0.0.0.0:3100):列出 /app/projects 下所有项目,支持新建项目、展示预览缩略图
  2. 项目引擎:每个被打开的项目单独启动一个引擎子进程,只绑定本机回环地址,浏览器请求由启动屏幕代理转发(见 launcher/src/server/launcher-server.ts 的设计说明)
  3. 引擎缓存:如果某个项目固定使用了别的 FluidCAD 版本,对应引擎会被自动下载并缓存在 /home/node/.fluidcad,这就是第二个数据卷存在的意义

由于 FluidCAD 的模型本质是可版本化的 JavaScript 文件(*.part.js / *.assembly.js),你可以直接把 ./projects 目录交给 Git 管理,获得完整的模型变更历史——这是自托管方案相对桌面应用的隐藏福利。

版本更新与数据持久化

升级到新版只需两步:

docker compose pull
docker compose up -d

如果用 docker run 部署,则拉取新镜像后删除容器(docker rm -f fluidcad)再重新运行相同命令即可。项目与 fluidcad-home 卷都不会丢失。

💡 如果希望团队固定在某个版本上、不跟随 latest,把镜像标签换成具体版本号即可,例如 ghcr.io/fluid-cad/fluidcad:0.0.47。

也支持从源码自行构建镜像:克隆仓库后将 compose 文件中的 image: 改为 build: .。构建流程(多阶段构建、仅保留发布产物、裁剪依赖)完整定义在 Dockerfile 中。

常见问题排查(FAQ)

Q1:浏览器打开报 403 或被拒绝访问? 检查请求所用的主机名是否在 FLUIDCAD_ALLOWED_HOSTS 白名单中——这是防 DNS 重绑定的设计,所有访问名称都需提前声明。

Q2:容器内写不进项目目录(Linux)? 确认宿主目录权限:sudo chown 1000:1000 projects。

Q3:重启后登录链接变了? 正常现象。每次容器启动都会生成新的 token 链接,重新打开一次即可;免登录模式(FLUIDCAD_NO_AUTH=1)则无此问题。

Q4:端口 3100 被占用? 容器会自动向上寻找可用端口,实际端口以日志中打印的链接为准;也可以换用其他宿主端口映射。

Q5:能直接暴露到公网吗? 不建议。请部署在自可控网络(局域网 / Tailscale)内,外部访问走 VPN。

小结

到这里,一套自托管的 FluidCAD 团队 3D 建模服务就搭建完成了 🎉:

  1. 本机体验:一条 docker run,从日志取登录链接
  2. 受信任网络:FLUIDCAD_NO_AUTH 免登录,全员浏览器直达
  3. 共享网络:127.0.0.1 端口 + HTTPS 反向代理 + FLUIDCAD_PUBLIC_URL
  4. 日常运维:两个数据卷保证数据不丢,docker compose pull && docker compose up -d 无痛升级

更多参数与说明可参考官方文档中的安装章节 installation.mdx 与命令行参考 cli.mdx。现在,打开浏览器,和你的团队一起开始建模吧!

登录后查看全文
FluidCAD