2026-05-21-11-13-49 记录独立Docker程序包分支

2026-05-21 11:23:27 +08:00
parent b027f50118
commit 536370ab9a
4 changed files with 214 additions and 0 deletions
--- a/工程分析/实现方案-2026-05-21-11-13-49.md
+++ b/工程分析/实现方案-2026-05-21-11-13-49.md
@@ -0,0 +1,70 @@
+# 实现方案：独立 Docker 程序目录与 Gitea 分支存储
+
+实现方案文档路径：`工程分析/实现方案-2026-05-21-11-13-49.md`
+
+## 修改目标
+
+在 `~/Desktop/ReVoxelSeg_DICOM_Docker` 生成可独立运行的 Docker 程序包，并将其作为 Gitea 新分支 `docker-standalone-20260521` 推送。
+
+## 涉及路径
+
+主项目：
+
+- `工程分析/需求分析-2026-05-21-11-13-49.md`
+- `工程分析/实现方案-2026-05-21-11-13-49.md`
+- `工程分析/测试方案-2026-05-21-11-13-49.md`
+- `工程分析/经验记录.md`
+
+独立 Docker 程序目录：
+
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/WebSite/`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/Head_CT_DICOM/`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/Head_CT_ReConstruct/`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/Dockerfile`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/.dockerignore`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/.gitignore`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.yaml`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.nas.yaml`
+- `~/Desktop/ReVoxelSeg_DICOM_Docker/README.md`
+
+## 技术路线
+
+1. 从主项目复制必要运行内容到独立目录：
+   - 复制 `WebSite/`，排除 `node_modules`、`dist`、`data`、`exports` 和本地环境文件。
+   - 复制默认演示数据 `Head_CT_DICOM/`、`Head_CT_ReConstruct/`。
+2. 将 Dockerfile 调整为独立目录根构建：
+   - `COPY WebSite/package*.json ./WebSite/`
+   - `COPY WebSite ./WebSite`
+   - `COPY Head_CT_DICOM ./Head_CT_DICOM`
+   - `COPY Head_CT_ReConstruct ./Head_CT_ReConstruct`
+3. 根目录放置两份 Compose：
+   - `docker_compose.yaml`：本机部署，挂载 `./data` 与 `./exports`。
+   - `docker_compose.nas.yaml`：NAS 部署，默认绝对路径 `/share/Container/revoxelseg_dicom`。
+4. 在独立目录初始化 Git 仓库并推送到 Gitea 新分支。
+5. 对独立目录执行 Compose 配置校验和构建验证。
+
+## 执行步骤
+
+1. 清理并重建 `~/Desktop/ReVoxelSeg_DICOM_Docker`。
+2. 使用 `rsync` 复制必要目录并排除运行态产物。
+3. 写入根目录 Docker 部署文件。
+4. 执行 `docker compose -f docker_compose.yaml config` 与 `docker compose -f docker_compose.nas.yaml config`。
+5. 执行 `docker compose -f docker_compose.yaml build` 或 `up -d --build` 验证独立目录可用。
+6. 验证本机端口与健康接口。
+7. 初始化独立目录 Git 仓库，创建 `docker-standalone-20260521` 分支并推送。
+8. 主项目提交工程分析记录。
+
+## 兼容性与回滚方案
+
+- 若独立 Docker 目录构建失败，不影响当前主项目目录和已运行的 Docker 服务。
+- 若 Gitea 分支推送失败，可保留本地独立目录，并重新执行 `git push origin docker-standalone-20260521`。
+- 若 NAS 路径不同，修改 `docker_compose.nas.yaml` 中的 `build.context` 和 volume 宿主机路径。
+
+## 预计文件变更
+
+主项目仅新增/更新工程分析文档；独立目录为新建自包含 Docker 程序包。
+
+## 提交与部署策略
+
+- 独立 Docker 程序包在新分支 `docker-standalone-20260521` 中存储。
+- 主项目 `main` 分支仅提交工程分析记录，避免把独立运行包重复放进主项目。
--- a/工程分析/测试方案-2026-05-21-11-13-49.md
+++ b/工程分析/测试方案-2026-05-21-11-13-49.md
@@ -0,0 +1,75 @@
+# 测试方案：独立 Docker 程序目录与 Gitea 分支存储
+
+测试方案文档路径：`工程分析/测试方案-2026-05-21-11-13-49.md`
+
+## 静态检查
+
+- 检查 `~/Desktop/ReVoxelSeg_DICOM_Docker` 中不包含：
+  - `工程分析/`
+  - `新撰写软著文档/`
+  - `参考软著构建模板/`
+  - `WebSite/node_modules/`
+  - `WebSite/dist/`
+  - `WebSite/data/`
+  - `WebSite/exports/`
+- 检查根目录存在：
+  - `Dockerfile`
+  - `docker_compose.yaml`
+  - `docker_compose.nas.yaml`
+  - `README.md`
+  - `WebSite/package-lock.json`
+  - `Head_CT_DICOM/`
+  - `Head_CT_ReConstruct/`
+
+## 构建检查
+
+- `docker compose -f docker_compose.yaml config`
+- `docker compose -f docker_compose.nas.yaml config`
+- `docker compose -f docker_compose.yaml build`
+
+## 关键业务场景验证
+
+- 从独立目录启动后，`http://127.0.0.1:4000/api/health` 返回 `ok: true`。
+- 首页 `/` 返回 `200 OK`。
+- frpc 容器可以启动并读取内嵌配置。
+
+## 医学影像数据相关边界验证
+
+- 独立目录包含默认 DICOM/STL 数据，脱离主项目目录后仍可构建镜像。
+- 运行态 `data/` 与 `exports/` 挂载在独立目录根部，不覆盖默认演示数据。
+
+## 部署验证
+
+- 如当前已有主项目 Docker 服务占用 4000，验证前先停止旧 Compose 或避免重复启动。
+- 验证后可按需要恢复或保留独立目录 Docker 服务。
+
+## Git/Gitea 备份验证
+
+- 独立目录 Git 分支：`docker-standalone-20260521`。
+- 推送到 `http://192.168.31.5:5002/admin/REVOXELSEG_DICOM.git`。
+- 主项目工程分析记录另行提交，commit message 包含 `2026-05-21-11-13-49`。
+
+## 风险与回归关注点
+
+- 独立分支内容与 `main` 分支目录结构不同，使用者需要明确选择分支。
+- Docker 镜像体积受默认医学数据影响。
+- NAS Compose 绝对路径需要部署时与实际 QTS 路径一致。
+
+## 实际执行结果
+
+- 已创建独立目录：`/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker`。
+- 独立目录根文件包含：`.dockerignore`、`.gitignore`、`Dockerfile`、`README.md`、`docker_compose.yaml`、`docker_compose.nas.yaml`。
+- 独立目录包含必要运行内容：`WebSite/`、`Head_CT_DICOM/`、`Head_CT_ReConstruct/`。
+- 独立目录不包含：`工程分析/`、`新撰写软著文档/`、`参考软著构建模板/`、`WebSite/node_modules/`、`WebSite/dist/`、`WebSite/data/`、`WebSite/exports/`。
+- `docker compose -f docker_compose.yaml config`：通过。
+- `docker compose -f docker_compose.nas.yaml config`：通过。
+- 已停止原主项目 Docker Compose 服务，避免 4000 端口与 FRPC 远端端口冲突。
+- 在独立目录执行 `docker compose -f 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`。
+- 独立目录已初始化 Git 仓库，提交 `57415a1 2026-05-21-11-13-49 独立Docker程序包`。
+- Gitea 新分支已创建并推送：`docker-standalone-20260521`。
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -1513,3 +1513,21 @@ C. 解决问题方案
 D. 后续如何避免问题

 后续部署变更应先停止旧 4000 服务，再启动新部署方式，避免端口冲突。Docker 构建要明确区分默认演示资产、业务源码和运行态挂载目录；NAS 版 Compose 应使用绝对路径，方便 Container Station 直接导入。frpc 配置变更后必须查看 frpc 日志，确认 `login to server success` 和 `start proxy success`，再用局域网地址和公网域名分别验证。
+
+## 2026-05-21-11-13-49 独立 Docker 程序包要脱离主工程验证
+
+A. 具体问题
+
+用户要求将完整 Docker 程序放到 `~/Desktop/ReVoxelSeg_DICOM_Docker`，后续即使没有原始 `ReVoxelSeg_DICOM` 文件夹也能直接运行；独立目录不应包含工程分析、软著材料和其他杂项，并要求 Docker Compose 文件放在程序根目录，同时在 Gitea 新开分支存储。
+
+B. 产生问题原因
+
+之前 Docker 部署文件位于主项目 `Docker部署/` 子目录，构建上下文依赖原始工程根目录。如果直接复制该子目录，缺少 `WebSite/`、默认 DICOM 和 STL 数据，无法脱离主工程运行；如果直接复制整个主工程，又会把工程分析、软著、参考模板、运行态数据和未跟踪测试文件一起带入独立部署包。
+
+C. 解决问题方案
+
+新建 `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker`，只同步 `WebSite/`、`Head_CT_DICOM/`、`Head_CT_ReConstruct/`，并排除 `node_modules`、`dist`、`data`、`exports` 和本地环境文件。将 `Dockerfile`、本机 `docker_compose.yaml`、NAS `docker_compose.nas.yaml` 和 README 放在独立目录根部。停止旧 Compose 后从独立目录执行构建和启动，验证局域网地址、公网域名、健康接口和 frpc 日志。最后在独立目录初始化 Git 仓库，推送到 Gitea 新分支 `docker-standalone-20260521`。
+
+D. 后续如何避免问题
+
+后续若维护 Docker 独立包，应优先在 `ReVoxelSeg_DICOM_Docker` 目录内修改和验证，不要依赖主工程相对路径。根目录 Compose 文件中，本机版保留为 `docker_compose.yaml`，NAS 版使用 `docker_compose.nas.yaml`，避免同名文件冲突。独立分支内容结构与 main 不同，推送前必须检查目录纯净度，确认不含工程分析、软著材料、node_modules、dist、data、exports 等无关内容。
--- a/工程分析/需求分析-2026-05-21-11-13-49.md
+++ b/工程分析/需求分析-2026-05-21-11-13-49.md
@@ -0,0 +1,51 @@
+# 需求分析：独立 Docker 程序目录与 Gitea 分支存储
+
+开始时间：2026-05-21-11-13-49
+
+## 原始需求摘要
+
+用户要求将完整 Docker 程序放到 `~/Desktop/ReVoxelSeg_DICOM_Docker`，后续即使没有原始 `ReVoxelSeg_DICOM` 文件夹，也能直接在 `ReVoxelSeg_DICOM_Docker` 中运行。该独立目录不需要包含 `工程分析/`、软著撰写材料以及其他无关内容。用户还要求将 Docker Compose 文件放在程序根目录，并在 Gitea 新开一个分支进行存储。
+
+## 业务目标
+
+形成一个可单独复制、可单独部署、可单独在 Gitea 分支维护的 Docker 运行包，降低迁移到新机器或 NAS 的操作复杂度。
+
+## 输入与输出
+
+输入：
+
+- 当前主项目中的 `WebSite/` 程序源码。
+- 默认演示数据 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
+- 现有 Docker 部署配置。
+
+输出：
+
+- 独立目录：`~/Desktop/ReVoxelSeg_DICOM_Docker`。
+- 根目录 Dockerfile、`.dockerignore`、`docker_compose.yaml`、`docker_compose.nas.yaml`、`README.md`。
+- 独立目录可通过 Docker Compose 构建和启动。
+- Gitea 新分支保存该独立 Docker 程序包。
+
+## 影响范围
+
+- 新增桌面独立目录，不改变原主项目业务代码。
+- 主项目仅新增本次工程分析记录。
+- Gitea 新分支采用独立程序包内容，不携带 `工程分析/`、软著材料、参考模板、测试压缩包等内容。
+
+## 关键约束
+
+- 独立目录必须自包含默认演示 DICOM/STL 数据。
+- 独立目录不应包含 `WebSite/node_modules`、`WebSite/dist`、`WebSite/data`、`WebSite/exports` 等运行态或构建产物。
+- 根目录无法同时存在两个完全同名的 `docker_compose.yaml`，因此默认使用 `docker_compose.yaml` 表示本机版，`docker_compose.nas.yaml` 表示威联通 NAS 版。
+- Gitea 分支不能混入当前主仓库中既有的历史删除和未跟踪杂项。
+
+## 风险点
+
+- 独立分支若使用同一个 Gitea 仓库，会与 `main` 分支内容结构不同；使用者需要明确切换到 Docker 独立分支。
+- Docker 镜像仍包含默认医学演示数据，构建上下文和镜像体积较大。
+- frpc 公网访问依赖远端服务端与 NPM 反向代理配置，本地只能验证分支、构建和本地服务。
+
+## 默认假设
+
+- 新分支命名为 `docker-standalone-20260521`。
+- 本机 Compose 文件名为 `docker_compose.yaml`。
+- NAS Compose 文件名为 `docker_compose.nas.yaml`。