2026-05-21-10-38-49 新增Docker部署与FRPC映射

2026-05-21 10:50:24 +08:00
parent e4a403f015
commit b027f50118
12 changed files with 554 additions and 2 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -0,0 +1,25 @@
+.git
+.gitignore
+.codex
+.agents
+node_modules
+WebSite/node_modules
+WebSite/dist
+WebSite/data
+WebSite/exports
+WebSite/.env
+Docker部署/**/data
+Docker部署/**/exports
+工程分析
+新撰写软著文档
+参考软著构建模板
+*.zip
+*.tar
+*.tar.gz
+*.tgz
+*.7z
+*.rar
+*.log
+*.tmp
+*.bak
+
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,8 @@ WebSite/dist/
 # Runtime backend state and generated exports
 WebSite/data/
 WebSite/exports/
+Docker部署/**/data/
+Docker部署/**/exports/

 # Local env
 .env
--- a/Docker部署/Dockerfile
+++ b/Docker部署/Dockerfile
@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22-bookworm-slim
+
+WORKDIR /app
+
+ENV PORT=4000
+ENV HOST=0.0.0.0
+
+ARG HTTP_PROXY
+ARG HTTPS_PROXY
+ARG NO_PROXY
+
+COPY WebSite/package*.json ./WebSite/
+
+WORKDIR /app/WebSite
+RUN npm ci
+
+WORKDIR /app
+COPY WebSite ./WebSite
+COPY Head_CT_DICOM ./Head_CT_DICOM
+COPY Head_CT_ReConstruct ./Head_CT_ReConstruct
+
+WORKDIR /app/WebSite
+RUN npm run build && mkdir -p data exports
+
+ENV NODE_ENV=production
+
+EXPOSE 4000
+
+HEALTHCHECK --interval=10s --timeout=5s --retries=12 --start-period=20s \
+  CMD node -e "fetch('http://127.0.0.1:4000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["npm", "run", "serve", "--", "--host", "0.0.0.0", "--port", "4000"]
--- a/Docker部署/README.md
+++ b/Docker部署/README.md
@@ -0,0 +1,128 @@
+# ReVoxelSeg DICOM Docker 部署说明
+
+本目录提供两套 Docker Compose 部署方式：
+
+- `本机/docker_compose.yaml`：适合当前开发机或普通 Linux 主机。
+- `威联通NAS/docker_compose.yaml`：适合 QNAP QTS Container Station，使用 `/share/Container/revoxelseg_dicom` 绝对路径。
+
+两套 Compose 都包含：
+
+- `revoxelseg_web`：ReVoxelSeg DICOM 前后端一体服务，容器端口 `4000`。
+- `revoxelseg_frpc`：FRPC 客户端，将 `revoxelseg_web:4000` 映射到 `82.157.255.195` 的远程端口 `10008`。
+
+## 一、本机部署
+
+在项目根目录执行：
+
+```bash
+docker compose -f Docker部署/本机/docker_compose.yaml up -d --build
+```
+
+查看状态：
+
+```bash
+docker compose -f Docker部署/本机/docker_compose.yaml ps
+docker compose -f Docker部署/本机/docker_compose.yaml logs -f revoxelseg_web
+docker compose -f Docker部署/本机/docker_compose.yaml logs -f revoxelseg_frpc
+```
+
+访问地址：
+
+```text
+http://192.168.3.11:4000/
+http://127.0.0.1:4000/
+```
+
+公网访问需等待 FRPC 在线，并确认 NPM 反向代理已将 `revoxel.huijutec.cn` 转发到 FRP 服务端 `10008`：
+
+```text
+https://revoxel.huijutec.cn/
+```
+
+停止：
+
+```bash
+docker compose -f Docker部署/本机/docker_compose.yaml down
+```
+
+## 二、威联通 NAS / QTS Container Station 部署
+
+建议把完整项目放到：
+
+```text
+/share/Container/revoxelseg_dicom
+```
+
+然后在 QTS Container Station 中创建应用，选择或粘贴：
+
+```text
+/share/Container/revoxelseg_dicom/Docker部署/威联通NAS/docker_compose.yaml
+```
+
+也可通过 SSH 执行：
+
+```bash
+cd /share/Container/revoxelseg_dicom
+docker compose -f Docker部署/威联通NAS/docker_compose.yaml up -d --build
+```
+
+如果项目目录不是 `/share/Container/revoxelseg_dicom`，需要同步修改 NAS Compose 中：
+
+- `build.context`
+- `/share/Container/revoxelseg_dicom/data`
+- `/share/Container/revoxelseg_dicom/exports`
+
+## 三、数据持久化
+
+容器内路径：
+
+- `/app/WebSite/data`：项目状态、上传数据和导入缓存。
+- `/app/WebSite/exports`：导出的 NII/NII.GZ/TAR.GZ 文件。
+
+本机部署会挂载到：
+
+- `Docker部署/本机/data`
+- `Docker部署/本机/exports`
+
+NAS 部署会挂载到：
+
+- `/share/Container/revoxelseg_dicom/data`
+- `/share/Container/revoxelseg_dicom/exports`
+
+默认演示数据 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/` 会复制进镜像，用于新环境首次启动后的默认项目。
+
+## 四、FRPC 映射
+
+Compose 中内置的 FRPC 配置为：
+
+```toml
+serverAddr = "82.157.255.195"
+serverPort = 7000
+
+auth.method = "token"
+auth.token = "en.xjtu.edu.cn"
+
+transport.poolCount = 5
+transport.heartbeatTimeout = -1
+
+[[proxies]]
+name = "ReVoxelSeg_DICOM"
+type = "tcp"
+localIP = "revoxelseg_web"
+localPort = 4000
+remotePort = 10008
+```
+
+如果远端端口或代理名称调整，只需修改两份 `docker_compose.yaml` 中 `revoxelseg_frpc` 的内嵌配置。
+
+## 五、旧 tmux 部署回退
+
+若需要临时回退到旧部署方式：
+
+```bash
+docker compose -f Docker部署/本机/docker_compose.yaml down
+cd WebSite
+npm run build
+npm run serve -- --host 0.0.0.0 --port 4000
+```
+
--- a/Docker部署/威联通NAS/docker_compose.yaml
+++ b/Docker部署/威联通NAS/docker_compose.yaml
@@ -0,0 +1,70 @@
+# ReVoxelSeg DICOM / QNAP QTS Container Station 直接部署版。
+# 建议把完整项目放到：/share/Container/revoxelseg_dicom
+# Container Station 不一定从项目根目录执行 Compose，因此 build.context 与 volumes 使用绝对路径。
+# 局域网访问：http://NAS_IP:4000/ 或 http://192.168.3.11:4000/
+# 公网访问：NPM 反向代理将 revoxel.huijutec.cn 转发到 FRP 服务端 10008 后生效。
+
+name: revoxelseg-dicom-qnap
+
+services:
+  revoxelseg_web:
+    image: revoxelseg-dicom:web-qnap-20260521
+    build:
+      context: /share/Container/revoxelseg_dicom
+      dockerfile: Docker部署/Dockerfile
+      args:
+        HTTP_PROXY: http://192.168.31.7:7893
+        HTTPS_PROXY: http://192.168.31.7:7893
+        NO_PROXY: localhost,127.0.0.1,192.168.31.0/24,192.168.3.0/24,revoxelseg_web,revoxelseg_frpc
+    restart: unless-stopped
+    ports:
+      - "4000:4000"
+    environment:
+      NODE_ENV: production
+      PORT: 4000
+      APP_URL: https://revoxel.huijutec.cn
+      TRUST_PROXY: "true"
+      HTTP_PROXY: http://192.168.31.7:7893
+      HTTPS_PROXY: http://192.168.31.7:7893
+      http_proxy: http://192.168.31.7:7893
+      https_proxy: http://192.168.31.7:7893
+      NO_PROXY: localhost,127.0.0.1,192.168.31.0/24,192.168.3.0/24,revoxelseg_web,revoxelseg_frpc
+    volumes:
+      - /share/Container/revoxelseg_dicom/data:/app/WebSite/data
+      - /share/Container/revoxelseg_dicom/exports:/app/WebSite/exports
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:4000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
+  revoxelseg_frpc:
+    image: snowdreamtech/frpc:latest
+    restart: unless-stopped
+    entrypoint: ["/bin/sh"]
+    command:
+      - -c
+      - |
+        cat > /tmp/frpc.toml <<'EOF'
+        serverAddr = "82.157.255.195"
+        serverPort = 7000
+
+        auth.method = "token"
+        auth.token = "en.xjtu.edu.cn"
+
+        transport.poolCount = 5
+        transport.heartbeatTimeout = -1
+
+        [[proxies]]
+        name = "ReVoxelSeg_DICOM"
+        type = "tcp"
+        localIP = "revoxelseg_web"
+        localPort = 4000
+        remotePort = 10008
+        EOF
+        exec frpc -c /tmp/frpc.toml
+    depends_on:
+      revoxelseg_web:
+        condition: service_healthy
+
--- a/Docker部署/本机/docker_compose.yaml
+++ b/Docker部署/本机/docker_compose.yaml
@@ -0,0 +1,60 @@
+# ReVoxelSeg DICOM 本机 Docker 部署版。
+# 运行位置：项目根目录下执行 `docker compose -f Docker部署/本机/docker_compose.yaml up -d --build`
+# 局域网访问：http://192.168.3.11:4000/
+# 公网访问：NPM 反向代理将 revoxel.huijutec.cn 转发到 FRP 服务端 10008 后生效。
+
+name: revoxelseg-dicom-local
+
+services:
+  revoxelseg_web:
+    image: revoxelseg-dicom:web-local-20260521
+    build:
+      context: ../..
+      dockerfile: Docker部署/Dockerfile
+    restart: unless-stopped
+    ports:
+      - "4000:4000"
+    environment:
+      NODE_ENV: production
+      PORT: 4000
+      APP_URL: http://192.168.3.11:4000
+      TRUST_PROXY: "true"
+    volumes:
+      - ./data:/app/WebSite/data
+      - ./exports:/app/WebSite/exports
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:4000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
+  revoxelseg_frpc:
+    image: snowdreamtech/frpc:latest
+    restart: unless-stopped
+    entrypoint: ["/bin/sh"]
+    command:
+      - -c
+      - |
+        cat > /tmp/frpc.toml <<'EOF'
+        serverAddr = "82.157.255.195"
+        serverPort = 7000
+
+        auth.method = "token"
+        auth.token = "en.xjtu.edu.cn"
+
+        transport.poolCount = 5
+        transport.heartbeatTimeout = -1
+
+        [[proxies]]
+        name = "ReVoxelSeg_DICOM"
+        type = "tcp"
+        localIP = "revoxelseg_web"
+        localPort = 4000
+        remotePort = 10008
+        EOF
+        exec frpc -c /tmp/frpc.toml
+    depends_on:
+      revoxelseg_web:
+        condition: service_healthy
+
--- a/README.md
+++ b/README.md
@@ -35,4 +35,26 @@ npm run serve -- --host 0.0.0.0 --port 4000
 http://192.168.3.11:4000/
 ```

+## Docker 部署
+
+项目已提供本机与威联通 NAS 两套 Docker Compose 部署文件，详见：
+
+```text
+Docker部署/README.md
+```
+
+本机启动：
+
+```bash
+docker compose -f Docker部署/本机/docker_compose.yaml up -d --build
+```
+
+威联通 NAS / QTS Container Station 建议将完整项目放到 `/share/Container/revoxelseg_dicom`，再使用：
+
+```text
+Docker部署/威联通NAS/docker_compose.yaml
+```
+
+Compose 内置 frpc 映射，会将容器服务 `revoxelseg_web:4000` 映射到 FRP 服务端远程端口 `10008`，配合 NPM 反向代理后可通过 `https://revoxel.huijutec.cn/` 访问。
+
 当前版本不需要 Python/conda。后续接入真实医学级 STL 体素化算法时，可新建 `revoxelseg` conda 环境并安装 SimpleITK、nibabel、numpy、trimesh、vtk 等算法依赖。
--- a/工程分析/实现方案-2026-05-21-10-38-49.md
+++ b/工程分析/实现方案-2026-05-21-10-38-49.md
@@ -0,0 +1,63 @@
+# 实现方案：Docker 双环境部署与 FRPC 公网映射
+
+实现方案文档路径：`工程分析/实现方案-2026-05-21-10-38-49.md`
+
+## 修改目标
+
+新增完整容器化部署方案，使项目可通过 Docker Compose 在本机和威联通 NAS Container Station 中运行，并通过内置 frpc 服务映射到 `82.157.255.195:10008`，配合 `revoxel.huijutec.cn` 访问。
+
+## 涉及路径
+
+- `.dockerignore`
+- `Docker部署/Dockerfile`
+- `Docker部署/README.md`
+- `Docker部署/本机/docker_compose.yaml`
+- `Docker部署/威联通NAS/docker_compose.yaml`
+- `工程分析/需求分析-2026-05-21-10-38-49.md`
+- `工程分析/实现方案-2026-05-21-10-38-49.md`
+- `工程分析/测试方案-2026-05-21-10-38-49.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 停止现有 `tmux` 会话中的 `npm run serve` 服务。
+2. 新增 Dockerfile：
+   - 使用 Node 官方镜像。
+   - 复制 `WebSite/package*.json` 并执行 `npm ci`。
+   - 复制 WebSite 源码、默认 DICOM 数据和默认 STL 数据。
+   - 执行 `npm run build`。
+   - 使用 `NODE_ENV=production` 通过 `npm run serve -- --host 0.0.0.0 --port 4000` 启动。
+3. 新增本机 Compose：
+   - `revoxelseg_web` 暴露 `4000:4000`。
+   - 挂载本机部署目录下的 `data/`、`exports/`。
+   - `revoxelseg_frpc` 使用 `snowdreamtech/frpc:latest`，启动时写入 `/tmp/frpc.toml`。
+4. 新增 QNAP Compose：
+   - build context 使用 `/share/Container/revoxelseg_dicom` 绝对路径。
+   - 运行态目录挂载到 `/share/Container/revoxelseg_dicom/data` 与 `exports`。
+   - frpc 直接内嵌同样的远端映射配置。
+5. 新增 README 说明部署、访问、停止、日志查看和路径修改方式。
+
+## 执行步骤
+
+1. 创建 `Docker部署/`、`Docker部署/本机/`、`Docker部署/威联通NAS/`。
+2. 写入 Dockerfile、两份 Compose 与 README。
+3. 执行 `npm run lint` 与 `npm run build`。
+4. 执行 `docker compose -f Docker部署/本机/docker_compose.yaml config` 校验语法。
+5. 构建并启动本机 Docker 部署。
+6. 验证 `http://127.0.0.1:4000/api/health` 与 `http://127.0.0.1:4000/`。
+7. 检查 frpc 容器日志是否启动并尝试连接服务端。
+8. 更新经验记录并提交本次相关文件。
+
+## 兼容性与回滚方案
+
+- 回滚到旧部署：执行 `docker compose -f Docker部署/本机/docker_compose.yaml down` 后，按旧方式进入 `WebSite` 执行 `npm run serve -- --host 0.0.0.0 --port 4000`。
+- 如果 QNAP 路径不同，只需修改 NAS Compose 中的 `build.context` 和 volume 宿主机路径。
+- 如果远端端口冲突，修改 frpc `remotePort` 和 NPM 反向代理目标端口即可。
+
+## 预计文件变更
+
+新增 Docker 部署文件，不修改业务源码。
+
+## 提交与部署策略
+
+提交包含 Docker 部署文件与工程分析文档；部署以本机 Docker Compose 作为验证环境。软著材料和无关工作区变化不纳入提交。
--- a/工程分析/工程整体分析.md
+++ b/工程分析/工程整体分析.md
@@ -57,6 +57,7 @@
 - `WebSite/data/state.json`：共享登录、项目、用户和构件样式状态。
 - `WebSite/exports/`：Mask 导出文件。
 - `WebSite/dist/`：生产构建产物。
+- `Docker部署/`：Docker 容器化部署方案，包含本机 Compose、威联通 NAS Compose、Dockerfile 和部署说明。
 - 默认项目 ID 为 `head-ct-demo`，由后端扫描 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/` 生成。
 - DICOM/STL 数据和运行态输出通常不应混入文档备份提交。

@@ -73,8 +74,10 @@
 ## 部署约定

 - 当前 README 指向访问地址 `http://192.168.3.11:4000/`。
- 历史经验记录显示本项目长期使用 `tmux` 会话 `revoxelseg-dicom` 托管服务，避免普通后台进程被回收。
- 重新部署前先检查端口和已有 `tmux` 会话；部署后用 `/api/health` 和页面 HTTP 响应验证。
+- 2026-05-21 起新增 Docker 部署方案，优先使用 `Docker部署/本机/docker_compose.yaml` 在本机部署，并使用 `Docker部署/威联通NAS/docker_compose.yaml` 适配 QNAP QTS Container Station。
+- Docker 部署包含 `revoxelseg_web` 与 `revoxelseg_frpc`，frpc 将 `revoxelseg_web:4000` 映射到 FRP 服务端 `82.157.255.195:10008`，配合 NPM 反向代理后可通过 `https://revoxel.huijutec.cn/` 访问。
+- 历史 `tmux` 会话 `revoxelseg-dicom` 可作为回退方式；重新部署前先检查端口和已有服务，避免 Docker 与 tmux 同时占用 4000。
+- 部署后用 `/api/health`、页面 HTTP 响应、局域网地址和公网域名验证。

 ## 修改风险重点

--- a/工程分析/测试方案-2026-05-21-10-38-49.md
+++ b/工程分析/测试方案-2026-05-21-10-38-49.md
@@ -0,0 +1,68 @@
+# 测试方案：Docker 双环境部署与 FRPC 公网映射
+
+测试方案文档路径：`工程分析/测试方案-2026-05-21-10-38-49.md`
+
+## 静态检查
+
+- 检查 Dockerfile 路径、工作目录、复制路径和启动命令。
+- 使用 `docker compose -f Docker部署/本机/docker_compose.yaml config` 校验本机 Compose。
+- 使用 `docker compose -f Docker部署/威联通NAS/docker_compose.yaml config` 校验 NAS Compose。
+- 确认 frpc 配置包含：
+  - `serverAddr = "82.157.255.195"`
+  - `serverPort = 7000`
+  - `auth.token = "en.xjtu.edu.cn"`
+  - `localIP = "revoxelseg_web"`
+  - `localPort = 4000`
+  - `remotePort = 10008`
+
+## 构建检查
+
+- 在 `WebSite/` 下执行 `npm run lint`。
+- 在 `WebSite/` 下执行 `npm run build`。
+- 使用本机 Compose 执行 Docker 镜像构建。
+
+## 关键业务场景验证
+
+- 容器启动后访问 `/api/health` 返回 `ok: true`。
+- 首页 `/` 返回 `200 OK`。
+- 默认项目数据可由容器读取。
+- 本机端口 `4000` 可访问。
+
+## 医学影像数据相关边界验证
+
+- 确认默认 DICOM 与 STL 目录被复制进镜像，运行态数据目录挂载不覆盖默认演示资产。
+- 确认 `WebSite/data` 和 `WebSite/exports` 被挂载为持久化目录，避免容器重建后用户项目和导出结果完全丢失。
+
+## 部署验证
+
+- 停止旧 tmux 服务后，使用本机 Docker Compose 启动服务。
+- 验证 `http://127.0.0.1:4000/api/health`。
+- 验证 `http://127.0.0.1:4000/`。
+- 查看 `revoxelseg_frpc` 日志，确认 frpc 已执行并尝试连接服务端。
+
+## Git/Gitea 备份验证
+
+- 仅暂存本次 Docker 部署文件与工程分析文档。
+- Commit message 包含 `2026-05-21-10-38-49` 与简要描述。
+- 推送到 `http://192.168.31.5:5002/admin/REVOXELSEG_DICOM.git`。
+
+## 风险与回归关注点
+
+- Docker 镜像构建时间和体积受默认医学数据大小影响。
+- frpc 公网访问依赖远端 FRP 服务和 NPM 反向代理，若服务端不可用，本机健康检查仍应通过。
+- 容器运行后不要再同时启动 tmux 版 4000 服务，以免端口冲突。
+
+## 实际执行结果
+
+- 已先停止旧 `tmux` 运行服务，4000 端口空闲后再启动 Docker Compose。
+- `npm run lint`：通过。
+- `npm run build`：通过，仅保留 Vite chunk size 提示。
+- `docker compose -f Docker部署/本机/docker_compose.yaml config`：通过，frpc 远端端口为 `10008`。
+- `docker compose -f Docker部署/威联通NAS/docker_compose.yaml config`：通过，NAS 版路径展开为 `/share/Container/revoxelseg_dicom`。
+- `docker compose -f Docker部署/本机/docker_compose.yaml up -d --build`：通过。
+- `revoxelseg_web`：状态 healthy，端口映射为 `0.0.0.0:4000->4000/tcp`。
+- `revoxelseg_frpc`：日志显示 `login to server success` 与 `[ReVoxelSeg_DICOM] start proxy success`。
+- `curl http://127.0.0.1:4000/api/health`：返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
+- `curl http://127.0.0.1:4000/`：返回 `200 OK`。
+- `curl http://192.168.3.11:4000/`：返回 `200 OK`。
+- `curl https://revoxel.huijutec.cn/`：返回 `200 OK`，响应头包含 `x-served-by: revoxel.huijutec.cn`。
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -1495,3 +1495,21 @@ C. 解决问题方案
 D. 后续如何避免问题

 后续只要系统功能发生变化并要求更新软著材料，应同时更新 Markdown 正文、截图、Word、代码汇总、视频脚本和素材清单，不能只改其中一项。截图自动化必须固定视口并校验图片尺寸、非空像素和引用数量；代码汇总应从当前源码机械生成或明确摘录范围；软著目录按用户要求不提交 Gitea，只提交工程分析记录。
+
+## 2026-05-21-10-38-49 Docker 部署要同时处理默认资产、运行态挂载与公网隧道
+
+A. 具体问题
+
+用户要求停止旧程序，并新增本机与威联通 NAS 两套 Docker 部署方式，同时把 frpc 配置直接写入 Compose，将容器内服务映射到 FRP 服务端 `82.157.255.195` 的 `10008` 端口，最终支持 `http://192.168.3.11:4000/` 和 `revoxel.huijutec.cn` 双入口访问。
+
+B. 产生问题原因
+
+项目此前主要通过 `tmux + npm run serve` 运行，部署依赖当前工作目录和 Node 环境。Docker 化时如果只打包 `WebSite/`，默认项目会找不到仓库根目录下的 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`；如果直接挂载整个 `WebSite/data` 和 `exports` 到镜像内部但不区分默认资产，又容易把运行态数据、导出文件或旧状态混进镜像和 Git。
+
+C. 解决问题方案
+
+新增 `Docker部署/`，在 Dockerfile 中以项目根目录为构建上下文，复制 `WebSite/`、`Head_CT_DICOM/` 和 `Head_CT_ReConstruct/`，容器启动时使用 `NODE_ENV=production` 与 `npm run serve -- --host 0.0.0.0 --port 4000`。两份 Compose 分别适配本机相对路径与 QNAP `/share/Container/revoxelseg_dicom` 绝对路径，运行态仅挂载 `/app/WebSite/data` 和 `/app/WebSite/exports`。frpc 容器启动时动态写入 `/tmp/frpc.toml`，映射 `revoxelseg_web:4000` 到远端 `10008`。同时在 `.dockerignore` 和 `.gitignore` 中排除构建缓存、运行态目录和导出数据。
+
+D. 后续如何避免问题
+
+后续部署变更应先停止旧 4000 服务，再启动新部署方式，避免端口冲突。Docker 构建要明确区分默认演示资产、业务源码和运行态挂载目录；NAS 版 Compose 应使用绝对路径，方便 Container Station 直接导入。frpc 配置变更后必须查看 frpc 日志，确认 `login to server success` 和 `start proxy success`，再用局域网地址和公网域名分别验证。
--- a/工程分析/需求分析-2026-05-21-10-38-49.md
+++ b/工程分析/需求分析-2026-05-21-10-38-49.md
@@ -0,0 +1,59 @@
+# 需求分析：Docker 双环境部署与 FRPC 公网映射
+
+开始时间：2026-05-21-10-38-49
+
+## 原始需求摘要
+
+用户要求先停掉当前程序运行服务，然后新建一个部署文件夹，为项目补充两种 Docker 部署方式：
+
+- 本机 Docker 部署。
+- 威联通 NAS Container Station / QTS 容器工作站部署。
+
+同时需要在 `docker_compose.yaml` 中直接写入 frpc 配置，将本项目容器内访问端口映射到 FRP 服务端 `82.157.255.195:7000`，并将远端 TCP 端口设置为 `10008`。用户已在 NPM 反向代理中配置 `revoxel.huijutec.cn` 指向远端 `10008`，最终希望既可通过 `http://192.168.3.11:4000/` 局域网访问，也可通过 `revoxel.huijutec.cn` 访问。
+
+## 业务目标
+
+将当前依赖 `tmux + npm run serve` 的部署方式升级为可复制、可迁移的容器化部署方案，降低新环境构建成本，并兼容 NAS 的 Container Station 使用习惯。
+
+## 输入与输出
+
+输入：
+
+- 当前项目源码、默认 DICOM 数据 `Head_CT_DICOM/`、默认 STL 数据 `Head_CT_ReConstruct/`。
+- 用户给出的 frpc 连接配置、token、远程端口和 QNAP 部署样例。
+
+输出：
+
+- Docker 镜像构建文件。
+- 本机 `docker_compose.yaml`。
+- 威联通 NAS / QTS `docker_compose.yaml`。
+- 部署说明文档。
+- 工程分析记录、测试记录与经验记录。
+
+## 影响范围
+
+- 新增 Docker 部署相关目录和文件。
+- 新增 Docker 构建上下文忽略规则。
+- 不改变前后端业务源码，不改变 DICOM/STL 处理逻辑。
+- 当前运行服务从 tmux 模式切换到 Docker Compose 模式。
+
+## 关键约束
+
+- 当前服务必须先停止，避免端口 4000 冲突。
+- frpc 配置直接写在 Compose 文件内，不依赖外部 `frpc.toml`。
+- NAS 版 Compose 需要使用绝对路径，适配 QTS Container Station 不一定从项目根目录执行的情况。
+- 默认演示数据必须在容器中可用；运行态 `WebSite/data`、`WebSite/exports` 需要可持久化。
+- 提交时避免混入既有无关删除、测试压缩包和软著目录。
+
+## 风险点
+
+- Docker 构建上下文包含 DICOM/STL 默认数据，镜像体积会偏大，但这是新环境默认项目可用的代价。
+- frpc 连接依赖公网服务器、token、远端端口占用和 NPM 反向代理配置，本地只能验证容器启动，公网域名需结合服务器侧状态确认。
+- QNAP 版绝对路径需要用户将项目放到约定目录 `/share/Container/revoxelseg_dicom`，否则需要改 Compose 中路径。
+- 当前服务使用 TypeScript `server.ts` + `tsx` 运行，生产镜像需要保留运行时所需依赖。
+
+## 默认假设
+
+- 公网域名由用户的 NPM 反向代理处理 HTTPS 或 HTTP 入口，项目容器只需暴露 HTTP 4000。
+- frpc 远端端口固定使用 `10008`。
+- 本机部署目录可使用相对路径挂载运行态数据；NAS 部署使用 `/share/Container/revoxelseg_dicom`。