From b027f50118c0e788706f5ea0a47db97857bba2b2 Mon Sep 17 00:00:00 2001 From: admin <572701190@qq.com> Date: Thu, 21 May 2026 10:50:24 +0800 Subject: [PATCH] =?UTF-8?q?2026-05-21-10-38-49=20=E6=96=B0=E5=A2=9EDocker?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E4=B8=8EFRPC=E6=98=A0=E5=B0=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .dockerignore | 25 +++++ .gitignore | 2 + Docker部署/Dockerfile | 34 ++++++ Docker部署/README.md | 128 +++++++++++++++++++++++ Docker部署/威联通NAS/docker_compose.yaml | 70 +++++++++++++ Docker部署/本机/docker_compose.yaml | 60 +++++++++++ README.md | 22 ++++ 工程分析/实现方案-2026-05-21-10-38-49.md | 63 +++++++++++ 工程分析/工程整体分析.md | 7 +- 工程分析/测试方案-2026-05-21-10-38-49.md | 68 ++++++++++++ 工程分析/经验记录.md | 18 ++++ 工程分析/需求分析-2026-05-21-10-38-49.md | 59 +++++++++++ 12 files changed, 554 insertions(+), 2 deletions(-) create mode 100644 .dockerignore create mode 100644 Docker部署/Dockerfile create mode 100644 Docker部署/README.md create mode 100644 Docker部署/威联通NAS/docker_compose.yaml create mode 100644 Docker部署/本机/docker_compose.yaml create mode 100644 工程分析/实现方案-2026-05-21-10-38-49.md create mode 100644 工程分析/测试方案-2026-05-21-10-38-49.md create mode 100644 工程分析/需求分析-2026-05-21-10-38-49.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..2926611 --- /dev/null +++ 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 + diff --git a/.gitignore b/.gitignore index 3eab919..9fe8d75 100644 --- 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 diff --git a/Docker部署/Dockerfile b/Docker部署/Dockerfile new file mode 100644 index 0000000..d0c4074 --- /dev/null +++ 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"] diff --git a/Docker部署/README.md b/Docker部署/README.md new file mode 100644 index 0000000..8fe21be --- /dev/null +++ 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 +``` + diff --git a/Docker部署/威联通NAS/docker_compose.yaml b/Docker部署/威联通NAS/docker_compose.yaml new file mode 100644 index 0000000..14d7a90 --- /dev/null +++ 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 + diff --git a/Docker部署/本机/docker_compose.yaml b/Docker部署/本机/docker_compose.yaml new file mode 100644 index 0000000..3adc0e6 --- /dev/null +++ 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 + diff --git a/README.md b/README.md index f9cadee..727aacc 100644 --- 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 等算法依赖。 diff --git a/工程分析/实现方案-2026-05-21-10-38-49.md b/工程分析/实现方案-2026-05-21-10-38-49.md new file mode 100644 index 0000000..2c93237 --- /dev/null +++ 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 作为验证环境。软著材料和无关工作区变化不纳入提交。 diff --git a/工程分析/工程整体分析.md b/工程分析/工程整体分析.md index c4a0455..9e64367 100644 --- 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 响应、局域网地址和公网域名验证。 ## 修改风险重点 diff --git a/工程分析/测试方案-2026-05-21-10-38-49.md b/工程分析/测试方案-2026-05-21-10-38-49.md new file mode 100644 index 0000000..d9bd530 --- /dev/null +++ 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`。 diff --git a/工程分析/经验记录.md b/工程分析/经验记录.md index a12db3b..ec51f78 100644 --- 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`，再用局域网地址和公网域名分别验证。 diff --git a/工程分析/需求分析-2026-05-21-10-38-49.md b/工程分析/需求分析-2026-05-21-10-38-49.md new file mode 100644 index 0000000..e1c0937 --- /dev/null +++ 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`。