2026-05-21-10-38-49 新增Docker部署与FRPC映射
This commit is contained in:
63
工程分析/实现方案-2026-05-21-10-38-49.md
Normal file
63
工程分析/实现方案-2026-05-21-10-38-49.md
Normal file
@@ -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 作为验证环境。软著材料和无关工作区变化不纳入提交。
|
||||
@@ -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 响应、局域网地址和公网域名验证。
|
||||
|
||||
## 修改风险重点
|
||||
|
||||
|
||||
68
工程分析/测试方案-2026-05-21-10-38-49.md
Normal file
68
工程分析/测试方案-2026-05-21-10-38-49.md
Normal file
@@ -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`。
|
||||
18
工程分析/经验记录.md
18
工程分析/经验记录.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`，再用局域网地址和公网域名分别验证。
|
||||
|
||||
59
工程分析/需求分析-2026-05-21-10-38-49.md
Normal file
59
工程分析/需求分析-2026-05-21-10-38-49.md
Normal file
@@ -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`。
|
||||
Reference in New Issue
Block a user