2026-06-23-12-07-35 部署并验证局域网 4000 服务

2026-06-23 12:11:28 +08:00
parent 60ebbf4196
commit 1e044fb349
4 changed files with 207 additions and 0 deletions
--- a/工程分析/实现方案-2026-06-23-12-07-35.md
+++ 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 服务`。
--- a/工程分析/测试方案-2026-06-23-12-07-35.md
+++ 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。
--- 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 校验或源码热更新状态影响访问判断。
--- a/工程分析/需求分析-2026-06-23-12-07-35.md
+++ 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 公网部署。
+- 默认假设本次仅做部署、验证和工程分析文档维护，不做功能代码变更。