Online3DViewer_腾讯云部署记录 - 登山亦有道

1. 部署目的

在自有腾讯云服务器上部署开源项目 Online3DViewer，用于验证机械三维模型的浏览器在线预览能力，包括 STEP、IGES、STL、OBJ、glTF 等格式。本部署当前属于功能验证环境，不应上传核心或高保密图纸。Online3DViewer 在浏览器端解析和渲染模型，即使界面不提供下载按钮，具备技术能力的访问者仍可能从网络请求、浏览器缓存或运行时内存中提取原始文件或模型数据。

2. 当前部署状态

记录日期：2026-08-27

项目	状态
服务器环境检查	已完成
Docker环境检查	已完成
官方源码下载	已完成
Docker镜像构建	已完成
容器启动	已完成
腾讯云安全组放行8080端口	已完成
浏览器访问验证	已完成
在线模型预览测试	已完成
STEP专项加载验证	待确认具体测试格式

已成功生成的Docker镜像：

online3dviewer:local

构建结果：

Successfully built c79a5b0b02de
Successfully tagged online3dviewer:local

最终上线结果：Docker镜像构建成功，容器正常运行，腾讯云安全组端口已经放行，公网浏览器可以打开Online3DViewer并完成在线预览测试。

3. 服务器环境

项目	配置
云服务商	腾讯云
操作系统	OpenCloudOS 9.4
架构	x86_64
CPU	4核
内存	3.6 GiB
当时可用内存	约618 MiB
Swap	6.0 GiB
系统盘	60 GB
已使用空间	35 GB，约58%
Docker	26.1.4
Docker Compose	未安装
firewalld	inactive
已占用端口	80、443，由宝塔Nginx占用
Online3DViewer计划端口	8080

由于服务器80和443端口已经由宝塔Nginx使用，本次验证不修改现有Nginx配置，先通过公网IP加8080端口访问。

4. 环境检查命令

cat /etc/os-release
uname -m
nproc
free -h
df -h /
docker --version
docker compose version
sudo systemctl is-active firewalld
sudo ss -lntp | awk 'NR == 1 || /:8080|:8081|:80|:443/'

检查结果表明Docker已安装，但没有Docker Compose插件。本项目只需要单个容器，因此直接使用 docker build 和 docker run，不依赖Compose。

5. 获取官方源码

5.1 安装或升级Git

sudo dnf install -y git

最初尝试直接从GitHub克隆：

sudo mkdir -p /opt/online3dviewer
sudo git clone --depth 1 https://github.com/kovacsv/Online3DViewer.git /opt/online3dviewer/source

由于腾讯云服务器访问GitHub速度较慢，克隆长时间停留在：

Cloning into '/opt/online3dviewer/source'...

因此终止直接克隆，改用GitHub归档代理下载公开仓库压缩包。

5.2 使用加速代理下载源码归档

curl -fL \
  --connect-timeout 20 \
  --retry 3 \
  --retry-delay 3 \
  "https://gh-proxy.com/https://github.com/kovacsv/Online3DViewer/archive/refs/heads/master.tar.gz" \
  -o /opt/online3dviewer/online3dviewer-master.tar.gz

ls -lh /opt/online3dviewer/online3dviewer-master.tar.gz
tar -tzf /opt/online3dviewer/online3dviewer-master.tar.gz | head

实际下载文件约26 MB，压缩包结构检查正常。

解压并整理目录：

tar -xzf /opt/online3dviewer/online3dviewer-master.tar.gz \
  -C /opt/online3dviewer

mv /opt/online3dviewer/Online3DViewer-master \
  /opt/online3dviewer/source

最终源码目录：

/opt/online3dviewer/source

6. 官方构建流程确认

项目官方CI配置使用Node.js 18和20，并依次执行：

npm install
npm run create_dist

项目完整打包脚本会：

生成项目文档；
构建三维引擎；
构建ES Module版本；
构建网站JavaScript、CSS、字体和SVG资源；
将网站入口、静态资源和构建产物复制到发布目录。

最终可发布的网站目录为：

build/package/website

不能只复制源代码中的 website 目录，否则可能缺少编译后的JavaScript、CSS、字体或模型解析相关资源。

7. 构建Docker镜像

本次采用多阶段Docker构建：

构建阶段使用Node.js 20和Python 3；
通过国内npm镜像安装依赖；
执行官方完整打包脚本；
运行阶段只保留Nginx和构建后的静态文件；
Node.js、Python和源码不会进入最终运行镜像。

实际执行命令：

cd /opt/online3dviewer/source

docker build \
  --tag online3dviewer:local \
  --file - \
  . <<'DOCKERFILE'
FROM node:20-bookworm-slim AS builder

WORKDIR /app

RUN apt-get update \
    && apt-get install -y --no-install-recommends python3 ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY package.json package-lock.json ./

RUN npm config set registry https://registry.npmmirror.com \
    && npm ci

COPY . .

ENV NODE_OPTIONS=--max-old-space-size=2048

RUN npm run create_package

FROM nginx:1.27-alpine

COPY --from=builder /app/build/package/website /usr/share/nginx/html

EXPOSE 80
DOCKERFILE

构建过程中完成了三维引擎、模块版本及网站资源编译，最终镜像构建成功。

检查镜像和内存：

docker image ls online3dviewer:local
free -h

8. 启动容器

容器已经成功启动，并配置为服务器或Docker重启后自动恢复运行。

启动容器：

docker run -d \
  --name online3dviewer \
  --restart unless-stopped \
  --publish 8080:80 \
  online3dviewer:local

参数说明：

参数	作用
`--name online3dviewer`	将容器命名为online3dviewer
`--restart unless-stopped`	Docker或服务器重启后自动恢复，除非人工停止
`--publish 8080:80`	将服务器8080端口映射到容器Nginx的80端口

9. 本机验证

docker ps --filter name=online3dviewer
curl -I http://127.0.0.1:8080
docker logs --tail 30 online3dviewer

本机及浏览器访问已经完成验证。正常HTTP检查应返回：

HTTP/1.1 200 OK

如果容器启动失败，可以执行：

docker ps -a --filter name=online3dviewer
docker logs online3dviewer
sudo ss -lntp | grep ':8080'

10. 腾讯云安全组配置

腾讯云安全组的8080端口已经完成放行，外部浏览器能够访问服务。配置方法如下：

配置项	建议值
协议	TCP
端口	8080
来源	优先填写管理员当前公网IP
策略	允许

临时测试时可以将来源设置为：

0.0.0.0/0

但这表示互联网上任何人都可以尝试访问8080端口。测试结束后应立即收紧来源地址，或者关闭8080端口。

由于当前 firewalld 为inactive状态，本机没有额外开放firewalld端口的步骤，但仍需以实际服务器安全策略为准。

11. 浏览器访问

服务已经上线，并通过个人电脑浏览器打开测试。访问形式为：

http://腾讯云服务器公网IP:8080

已经完成基础在线打开及模型预览测试。后续仍建议补充并记录以下专项验证结果：

首页是否正常显示；
官方示例模型能否加载；
小型STL或OBJ文件能否加载；
非核心STEP文件能否加载；
旋转、缩放、剖切及装配结构树是否正常；
浏览器刷新后是否恢复正常；
服务器重启后容器是否自动启动。

12. 常用运维命令

查看运行状态：

docker ps --filter name=online3dviewer

查看日志：

docker logs --tail 100 online3dviewer

停止容器：

docker stop online3dviewer

启动已存在的容器：

docker start online3dviewer

重启容器：

docker restart online3dviewer

检查8080端口：

sudo ss -lntp | grep ':8080'

13. 更新源码与重建思路

由于本次使用GitHub归档压缩包而不是Git仓库，更新时建议：

下载新的master归档；
解压到新的版本目录；
保留旧镜像作为回退版本；
使用新的镜像标签构建；
启动临时容器验证；
验证成功后再替换正式容器。

不要直接覆盖正在运行版本后立刻删除旧镜像，以免更新失败时无法快速回退。

14. 安全边界

当前部署只解决“在自己的服务器上运行Online3DViewer”，不等于已经实现图纸防外流。

Online3DViewer的主要安全限制：

模型在访问者浏览器中解析和渲染；
原始文件或转换后的几何数据可能进入浏览器；
隐藏下载按钮无法阻止技术人员抓取网络响应；
当前实例没有登录认证；
当前实例没有有效期、访问次数或指定人员权限；
当前实例没有动态水印；
当前实例没有完整的访问审计；
当前使用HTTP和公网端口，不具备HTTPS传输保护。

因此当前环境只能用于：

功能验证；
内部普通模型预览；
非核心、已脱敏模型测试。

暂时不应用于：

核心设备完整装配体；
可直接加工的精确STEP模型；
包含内部结构、BOM或专有尺寸的图纸；
需要对外正式分享的高保密资料。

15. 后续改进计划

建议按以下顺序逐步改进：

完成容器启动和本机HTTP验证；
临时放行8080并完成浏览器测试；
使用宝塔Nginx建立独立域名反向代理；
配置HTTPS证书；
增加账号或Basic Authentication；
禁止匿名公开访问；
增加访问日志和动态水印；
设计图纸上传、审批和脱敏流程；
评估服务器转换为降精度GLB的方案；
与图纸通、SView等商业平台进行安全性和成本对比。

16. 相关项目

Online3DViewer项目：https://github.com/kovacsv/Online3DViewer
Online3DViewer在线示例：https://3dviewer.net
Docker Engine安装文档：https://docs.docker.com/engine/install/centos/

THE END

喜欢就支持一下吧