From 1e044fb349d28cc59927780b79f57119e52b7fbc Mon Sep 17 00:00:00 2001 From: admin <572701190@qq.com> Date: Tue, 23 Jun 2026 12:11:28 +0800 Subject: [PATCH] =?UTF-8?q?2026-06-23-12-07-35=20=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E5=B9=B6=E9=AA=8C=E8=AF=81=E5=B1=80=E5=9F=9F=E7=BD=91=204000?= =?UTF-8?q?=20=E6=9C=8D=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 工程分析/实现方案-2026-06-23-12-07-35.md | 71 ++++++++++++++++++++++++ 工程分析/测试方案-2026-06-23-12-07-35.md | 65 ++++++++++++++++++++++ 工程分析/经验记录.md | 18 ++++++ 工程分析/需求分析-2026-06-23-12-07-35.md | 53 ++++++++++++++++++ 4 files changed, 207 insertions(+) create mode 100644 工程分析/实现方案-2026-06-23-12-07-35.md create mode 100644 工程分析/测试方案-2026-06-23-12-07-35.md create mode 100644 工程分析/需求分析-2026-06-23-12-07-35.md diff --git a/工程分析/实现方案-2026-06-23-12-07-35.md b/工程分析/实现方案-2026-06-23-12-07-35.md new file mode 100644 index 0000000..66ff2a8 --- /dev/null +++ b/工程分析/实现方案-2026-06-23-12-07-35.md @@ -0,0 +1,71 @@ +# 实现方案-2026-06-23-12-07-35 + +## 实现方案文档路径 + +`工程分析/实现方案-2026-06-23-12-07-35.md` + +## 修改目标 + +完成一次无业务源码变更的重新部署，使当前程序可通过 `http://192.168.3.11:4000/` 访问，并保留本次操作的工程分析记录。 + +## 涉及路径 + +- `AGENTS.md` +- `README.md` +- `WebSite/README.md` +- `WebSite/package.json` +- `WebSite/vite.config.ts` +- `WebSite/server.ts` +- `工程分析/代码编纂工作流.md` +- `工程分析/工程整体分析.md` +- `工程分析/经验记录.md` +- `工程分析/需求分析-2026-06-23-12-07-35.md` +- `工程分析/实现方案-2026-06-23-12-07-35.md` +- `工程分析/测试方案-2026-06-23-12-07-35.md` + +## 技术路线 + +- 通过仓库文档、脚本和服务入口确认项目是 Express + Vite 的前后端一体服务。 +- 使用 `npm run build` 生成生产构建产物。 +- 使用 `tmux` 会话 `revoxelseg-dicom` 启动 `npm run serve -- --host 0.0.0.0 --port 4000`。 +- 使用 `curl` 同时验证本机地址和目标局域网地址的 API 与首页。 +- 仅将本次工程分析文档和经验记录纳入 Git 备份提交。 + +## 执行步骤 + +1. 检查工作区状态、Node/npm 版本、依赖目录、目标网卡地址、`4000` 端口和 `tmux` 会话。 +2. 在 `WebSite/` 执行 `npm run build`。 +3. 如存在旧 `revoxelseg-dicom` 会话，先确认并重建该会话；如不存在则创建新会话。 +4. 在会话内执行 `npm run serve -- --host 0.0.0.0 --port 4000`。 +5. 验证： + - `http://127.0.0.1:4000/api/health` + - `http://127.0.0.1:4000/` + - `http://192.168.3.11:4000/api/health` + - `http://192.168.3.11:4000/` +6. 检查 `tmux` 会话日志和 `4000` 端口监听状态。 +7. 追加 `工程分析/经验记录.md` 的 A/B/C/D 四段式记录。 +8. 暂存并提交本次工程分析文档，commit message 使用 `2026-06-23-12-07-35 部署并验证局域网 4000 服务`。 + +## 兼容性与回滚方案 + +- 如果构建失败，不重启旧服务，保留错误并汇报。 +- 如果新服务启动失败，查看 `tmux` 日志和端口占用，停止失败会话后恢复上一条可用部署命令。 +- 如果 `4000` 被非本项目进程占用，先记录占用来源，再决定是否停止或改用既有服务验证。 +- 如果 `192.168.3.11` 不在本机网卡上，应停止局域网地址部署验证并报告网络前置条件不满足。 + +## 预计文件变更 + +- 新增： + - `工程分析/需求分析-2026-06-23-12-07-35.md` + - `工程分析/实现方案-2026-06-23-12-07-35.md` + - `工程分析/测试方案-2026-06-23-12-07-35.md` +- 追加： + - `工程分析/经验记录.md` +- 运行构建可能更新或生成 `WebSite/dist/`，该目录为运行态构建产物，不纳入本次文档备份提交。 + +## 提交与部署策略 + +- 先完成构建、部署和访问验证，再追加经验记录。 +- 使用 Git 仅提交本次工程分析文档和经验记录。 +- 不提交 DICOM/STL 数据、`WebSite/data/`、`WebSite/exports/`、`WebSite/dist/` 或无关工作区变化。 +- 提交信息：`2026-06-23-12-07-35 部署并验证局域网 4000 服务`。 diff --git a/工程分析/测试方案-2026-06-23-12-07-35.md b/工程分析/测试方案-2026-06-23-12-07-35.md new file mode 100644 index 0000000..0fa4990 --- /dev/null +++ b/工程分析/测试方案-2026-06-23-12-07-35.md @@ -0,0 +1,65 @@ +# 测试方案-2026-06-23-12-07-35 + +## 测试方案文档路径 + +`工程分析/测试方案-2026-06-23-12-07-35.md` + +## 静态检查 + +- 检查 `WebSite/package.json` 中存在 `build` 与 `serve` 脚本。 +- 检查 `WebSite/server.ts` 会解析 `--host`、`--port` 参数并提供 `/api/health`。 +- 检查本机是否包含目标网卡地址 `192.168.3.11`。 +- 检查当前 Git 工作区，避免提交无关变更。 + +## 构建检查 + +- 在 `WebSite/` 执行 `npm run build`。 +- 如果构建失败，停止部署并记录错误。 + +## 关键业务场景验证 + +- 验证首页 HTML 可正常返回，确认前端入口可访问。 +- 验证 `/api/health` 返回健康状态，确认 Express API 可用。 +- 可选验证 `/api/projects` 返回项目列表，确认默认项目状态可读。 + +## 医学影像数据相关边界验证 + +- 本次仅重新部署，不修改 DICOM/STL 解析、融合、分割映射或 Mask 导出逻辑。 +- 检查默认演示数据目录存在并记录数量，不生成新的医学导出文件。 +- 避免将 `Head_CT_DICOM/`、`Head_CT_ReConstruct/`、`WebSite/data/`、`WebSite/exports/` 混入 Git 提交。 + +## 部署验证 + +- 服务命令：`npm run serve -- --host 0.0.0.0 --port 4000`。 +- 运行载体：`tmux` 会话 `revoxelseg-dicom`。 +- 端口验证：确认 `4000` 端口由当前 Node 服务监听。 +- 访问验证： + - `http://127.0.0.1:4000/api/health` + - `http://127.0.0.1:4000/` + - `http://192.168.3.11:4000/api/health` + - `http://192.168.3.11:4000/` + +## Git/Gitea 备份验证 + +- 只暂存本次工程分析三件套和 `工程分析/经验记录.md`。 +- 提交后用 `git show --stat --oneline HEAD` 验证 commit message 包含 `2026-06-23-12-07-35` 和部署简述。 + +## 风险与回归关注点 + +- 如果 `tmux` 会话已存在，需确认旧服务关闭后新服务能稳定启动。 +- 如果局域网 IP 不属于当前机器，服务即使监听成功也无法通过目标地址访问。 +- 如果只验证 localhost，不能代表 `192.168.3.11` 可访问。 +- 如果误提交构建产物或医学数据，会污染备份提交，需要在提交前复查 staged 文件。 + +## 执行结果 + +- `npm run lint`：通过，`tsc --noEmit` 无错误。 +- `npm run build`：通过，Vite 成功生成 `dist/`；存在 chunk 大于 500 kB 的体积提示，不影响本次部署。 +- 本机网卡：已确认 `ens34` 包含 `192.168.3.11/24`。 +- 端口与会话：`tmux` 会话 `revoxelseg-dicom` 已创建，`4000` 端口由当前 Node 进程监听在 `0.0.0.0:4000`。 +- 启动命令：`NODE_ENV=production npm run serve -- --host 0.0.0.0 --port 4000`。 +- `http://127.0.0.1:4000/api/health`：HTTP 200，返回 `ok: true`。 +- `http://127.0.0.1:4000/`：HTTP 200，返回 HTML。 +- `http://192.168.3.11:4000/api/health`：HTTP 200，返回 `ok: true`。 +- `http://192.168.3.11:4000/`：HTTP 200，返回 HTML。 +- `http://127.0.0.1:4000/api/projects`：HTTP 200，当前返回 2 个项目，默认项目 `head-ct-demo` 包含 300 张 DICOM 与 9 个 STL。 diff --git a/工程分析/经验记录.md b/工程分析/经验记录.md index afafea5..6b7867d 100644 --- a/工程分析/经验记录.md +++ b/工程分析/经验记录.md @@ -2013,3 +2013,21 @@ C. 解决问题方案 D. 后续如何避免问题 后续做局域网部署时，部署验证必须同时覆盖三点：目标 IP 是否属于当前机器、端口是否监听在 `0.0.0.0`、目标 IP 的 API 和首页是否都能访问。若没有既有 tmux 会话，可直接创建同名会话；若端口被占用，则先记录占用来源再处理。 + +## 2026-06-23-12-07-35 无源码变更部署仍要记录实际运行命令 + +A. 具体问题 + +用户要求阅读整个工作区并部署到 `http://192.168.3.11:4000/`。本次没有业务源码变更，但仍需要完成构建、长期运行托管、局域网访问验证和文档备份提交。 + +B. 产生问题原因 + +部署类需求会改变运行态服务，即使不改源码也可能受端口占用、`tmux` 会话残留、网卡地址、生产/开发服务模式和前端入口访问影响。如果只记录“服务已启动”，后续排查时无法确认实际运行命令和验证覆盖面。 + +C. 解决问题方案 + +按工作流创建本次需求分析、实现方案和测试方案。执行前再次阅读部署相关经验，确认 `192.168.3.11` 属于本机网卡且 `4000` 端口空闲。通过 `npm run lint`、`npm run build` 后，在 `tmux` 会话 `revoxelseg-dicom` 中使用 `NODE_ENV=production npm run serve -- --host 0.0.0.0 --port 4000` 启动服务，并分别验证 `127.0.0.1` 与 `192.168.3.11` 的 `/api/health` 和首页均返回 HTTP 200。 + +D. 后续如何避免问题 + +后续无源码变更的重新部署也要记录实际启动命令、运行载体、端口监听地址、目标 IP 归属以及 API/首页双验证结果。若使用 `npm run build` 后部署，优先记录是否以 `NODE_ENV=production` 服务 `dist/`，避免开发中间件 Host 校验或源码热更新状态影响访问判断。 diff --git a/工程分析/需求分析-2026-06-23-12-07-35.md b/工程分析/需求分析-2026-06-23-12-07-35.md new file mode 100644 index 0000000..40a9094 --- /dev/null +++ b/工程分析/需求分析-2026-06-23-12-07-35.md @@ -0,0 +1,53 @@ +# 需求分析-2026-06-23-12-07-35 + +## 开始时间 + +2026-06-23-12-07-35 + +## 原始需求摘要 + +用户要求阅读整个工作区，并部署当前程序，使其可以通过 `http://192.168.3.11:4000/` 被访问。 + +## 业务目标 + +- 确认当前仓库结构、部署约束、运行脚本和历史经验。 +- 在不修改业务源码的前提下完成一次当前版本构建。 +- 使用长期运行方式启动前后端一体服务。 +- 确认本机与局域网目标地址均可访问。 + +## 输入与输出 + +- 输入：当前工作区 `/home/wkmgc/Desktop/ReVoxelSeg_DICOM`、`WebSite/package.json` 脚本、`WebSite/server.ts` 服务入口、DICOM/STL 默认演示数据、已有 `tmux` 和端口状态。 +- 输出：运行在 `0.0.0.0:4000` 的 ReVoxelSeg DICOM 服务、验证通过的 `http://127.0.0.1:4000/` 与 `http://192.168.3.11:4000/` 访问结果、本次工程分析文档和备份提交。 + +## 影响范围 + +- 运行态：`WebSite/dist/` 构建产物、`tmux` 会话 `revoxelseg-dicom`、`4000` 端口监听进程。 +- 文档：新增本次 `需求分析`、`实现方案`、`测试方案`，并在完成后追加 `工程分析/经验记录.md`。 +- 不修改业务源码、医学影像数据、STL 模型数据、运行态状态和导出结果。 + +## 关键约束 + +- 必须先执行 `工程分析/代码编纂工作流.md`。 +- 必须阅读 `工程分析/工程整体分析.md` 和 `工程分析/经验记录.md`。 +- 最终执行方案前需再次确认已读 `工程分析/经验记录.md`。 +- 部署优先使用： + - `cd WebSite` + - `npm run build` + - `npm run serve -- --host 0.0.0.0 --port 4000` +- 长期运行优先沿用 `tmux` 会话 `revoxelseg-dicom`。 +- Git/Gitea 备份 commit message 必须包含时间戳和简要描述。 + +## 风险点 + +- `4000` 端口可能被旧服务或 Docker 容器占用。 +- `tmux` 会话中可能残留旧命令，需要确认实际启动的是当前构建版本。 +- 目标 IP `192.168.3.11` 必须属于当前机器网卡，否则局域网地址无法访问。 +- 如果只验证 `/api/health`，可能遗漏首页 HTML 或前端资源访问异常。 +- 不能将医学数据、运行态产物或无关工作区变更混入备份提交。 + +## 待确认问题或默认假设 + +- 默认假设当前工作区代码即为用户希望部署的版本。 +- 默认假设用户要求的是本机 `tmux` 方式部署，而不是 Docker/FRPC 公网部署。 +- 默认假设本次仅做部署、验证和工程分析文档维护，不做功能代码变更。