Docker部署FluidCAD完整指南:5分钟自建团队共享的自托管3D建模服务
Docker部署FluidCAD完整指南:5分钟自建团队共享的自托管3D建模服务
🚀 FluidCAD 是一款用 JavaScript 编写的开源参数化 CAD 建模工具,而Docker 部署 FluidCAD 是让它为整个团队服务的最佳方式:把项目集中存放在一台服务器上,团队成员用浏览器打开同一个 3D 建模工作区,修改尺寸、复用零件、协同迭代。本指南带你从零完成这套自托管 3D 建模服务的搭建,覆盖本地体验、团队共享、安全加固与版本更新。
为什么选择 Docker 部署 FluidCAD?
FluidCAD 提供三种使用形态:桌面应用、npm 包(npx fluidcad 在本地浏览器中运行)、以及 Docker 镜像(把服务搬到服务器上)。
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,其他机器无法访问,这是最安全的默认姿势。
方式二:团队共享部署(受信任网络免登录)
家庭局域网或 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 |
容器内项目是如何组织的?
理解了这一点,日常运维会轻松很多:
- 启动屏幕(
0.0.0.0:3100):列出/app/projects下所有项目,支持新建项目、展示预览缩略图 - 项目引擎:每个被打开的项目单独启动一个引擎子进程,只绑定本机回环地址,浏览器请求由启动屏幕代理转发(见 launcher/src/server/launcher-server.ts 的设计说明)
- 引擎缓存:如果某个项目固定使用了别的 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 建模服务就搭建完成了 🎉:
- 本机体验:一条
docker run,从日志取登录链接 - 受信任网络:
FLUIDCAD_NO_AUTH免登录,全员浏览器直达 - 共享网络:
127.0.0.1端口 + HTTPS 反向代理 +FLUIDCAD_PUBLIC_URL - 日常运维:两个数据卷保证数据不丢,
docker compose pull && docker compose up -d无痛升级
更多参数与说明可参考官方文档中的安装章节 installation.mdx 与命令行参考 cli.mdx。现在,打开浏览器,和你的团队一起开始建模吧!


