3.1 KiB
经验记录
本文件用于记录项目修改过程中的关键问题与解决方案。每条经验使用四段式结构。
2026-05-04-02-38-48 建立代码编纂工作流
A. 具体问题
当前项目尚无统一的需求分析、实现方案、测试方案、经验沉淀和备份提交流程，后续修改容易缺少可追溯记录。
B. 产生问题原因
项目仍处于早期建设阶段，已有前端工程和医学影像数据资产，但尚未建立工程治理文档与固定执行规范。
C. 解决问题方案
创建 工程分析/ 目录，新增工程整体分析、代码编纂工作流、本次需求分析、实现方案、测试方案和经验记录文档。后续项目修改必须先写文档，并在实现方案和测试方案阶段等待用户二次人工审核确认。
D. 后续如何避免问题
每次项目修改前先记录时间戳并阅读 工程分析/工程整体分析.md 与 工程分析/经验记录.md。修改前写入需求、实现和测试文档，确认后再执行，完成后追加经验记录并提交 Gitea 备份。
2026-05-04-02-38-48 Gitea 推送后的本地凭据清理
A. 具体问题
使用带账号信息的一次性推送地址完成 Gitea push 后，本地 branch.main.remote 曾记录为带账号信息的 URL。
B. 产生问题原因
git push -u <url> main 会把该 <url> 记录为当前分支上游，而不是只使用已配置的 origin 名称。
C. 解决问题方案
将 origin 保持为不含账号信息的仓库地址，并把 branch.main.remote 改回 origin、branch.main.merge 改为 refs/heads/main。
D. 后续如何避免问题
后续推送时优先使用已配置好的 origin。如果必须临时带认证信息推送，推送后立即检查 git config --get-regexp 'branch\\.main|remote\\.origin'，确保本地配置中没有保存账号密码。
2026-05-04-02-38-48 开发服务端口占用
A. 具体问题
本项目默认 Vite 端口 3000 已被 /home/wkmgc/Desktop/Seg_Server 的 node 服务占用，无法直接作为本项目部署端口。
B. 产生问题原因
同一机器上已有其他项目服务监听 0.0.0.0:3000。
C. 解决问题方案
不停止既有服务，改用 3001 端口启动当前项目的 Vite 服务，并通过 curl -I http://127.0.0.1:3001/ 验证返回 HTTP/1.1 200 OK。
D. 后续如何避免问题
部署前先使用 ss -ltnp 检查目标端口。如果默认端口被占用，优先选择相邻可用端口并在测试方案执行结果中记录实际访问地址。
2026-05-04-02-38-48 后台部署进程托管
A. 具体问题
使用普通 nohup 后台启动 Vite 时进程会静默退出，无法稳定保留服务。
B. 产生问题原因
当前命令执行环境会回收普通后台子进程，导致 nohup 方式没有形成稳定部署。
C. 解决问题方案
使用 tmux new-session -d -s revoxelseg-dicom 托管 Vite 服务，使开发服务脱离当前命令执行会话独立运行。
D. 后续如何避免问题
需要保留长时间运行的开发服务时，优先使用 tmux 会话托管，并用 tmux capture-pane -pt <session> 查看启动日志，用 curl 验证 HTTP 响应。