2026-04-29-21-51-19 - 全栈系统改造：FastAPI后端+SAM2+PostgreSQL+Redis+MinIO+前端Zustand重构

2026-04-29 22:17:25 +08:00
parent c8f8686097
commit fd4b5e5b3d
39 changed files with 3816 additions and 211 deletions
--- a/工程分析/实现方案-2026-04-29-21-51-19.md
+++ b/工程分析/实现方案-2026-04-29-21-51-19.md
@@ -0,0 +1,185 @@
+# 实现方案 - 2026-04-29-21-51-19
+
+## 对应需求
+- 需求分析文档: `需求分析-2026-04-29-21-51-19.md`
+
+## 方案概述
+在 RTX 4090 + Ubuntu 22.04 环境下，将纯前端 React 应用改造为全栈语义分割系统。本次为**骨架搭建 + 核心能力落地**，优先保证各模块可独立运行并互联互通。
+
+## 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        前端层 (React 19)                         │
+│  Zustand (状态)  +  Axios (HTTP)  +  WebSocket (实时进度)        │
+│  Konva (Canvas)  +  TailwindCSS (样式)                           │
+└────────────────────────────┬────────────────────────────────────┘
+                             │ HTTP / WebSocket
+┌────────────────────────────▼────────────────────────────────────┐
+│                    后端层 (FastAPI + Python)                     │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐               │
+│  │ 项目/模板 API │ │ 媒体解析 API │ │ AI 推理 API  │               │
+│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘               │
+│         └─────────────────┼─────────────────┘                   │
+│                           │ SQLAlchemy                          │
+│  ┌────────────────────────▼────────────────────────┐           │
+│  │           PostgreSQL (关系数据)                  │           │
+│  └─────────────────────────────────────────────────┘           │
+│                           │                                    │
+│  ┌────────────────────────▼────────────────────────┐           │
+│  │           MinIO (对象存储: 视频/帧/Mask)         │           │
+│  └─────────────────────────────────────────────────┘           │
+│                           │                                    │
+│  ┌────────────────────────▼────────────────────────┐           │
+│  │           Redis (缓存 + 任务队列)                │           │
+│  └─────────────────────────────────────────────────┘           │
+│                           │                                    │
+│  ┌────────────────────────▼────────────────────────┐           │
+│  │           SAM 3 (GPU 推理节点)                   │           │
+│  └─────────────────────────────────────────────────┘           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 修改/新增文件清单
+
+### A. 基础设施层
+
+#### A1. 系统服务安装
+- **操作**: `sudo apt install postgresql postgresql-contrib redis-server ffmpeg`
+- **操作**: 下载并启动 MinIO 二进制
+- **说明**: 配置 PostgreSQL 数据库/用户，Redis 默认端口，MinIO 端口 9000/9001
+
+#### A2. Conda 环境
+- **操作**: `conda create -n seg_server python=3.11`
+- **操作**: 安装 PyTorch 2.5+ CUDA 13.x、FastAPI、SQLAlchemy、psycopg2-binary、redis-py、minio、uvicorn、python-multipart、celery、opencv-python、pillow、scikit-image、pydicom、numpy
+
+### B. 后端层 (新增 backend/ 目录)
+
+#### B1. `backend/main.py`
+- **类型**: 新增
+- **内容**: FastAPI 入口，CORS 配置， lifespan 管理（启动/关闭数据库、Redis、MinIO 连接）
+
+#### B2. `backend/config.py`
+- **类型**: 新增
+- **内容**: 环境变量配置（DB_URL、REDIS_URL、MINIO_ENDPOINT、SAM_MODEL_PATH 等）
+
+#### B3. `backend/database.py`
+- **类型**: 新增
+- **内容**: SQLAlchemy engine + session + Base，PostgreSQL 连接
+
+#### B4. `backend/models.py`
+- **类型**: 新增
+- **内容**: 数据库 ORM 模型：Project、Frame、Annotation、Template、Mask
+
+#### B5. `backend/schemas.py`
+- **类型**: 新增
+- **内容**: Pydantic 数据校验模型
+
+#### B6. `backend/minio_client.py`
+- **类型**: 新增
+- **内容**: MinIO 客户端封装（上传、下载、预签名 URL）
+
+#### B7. `backend/redis_client.py`
+- **类型**: 新增
+- **内容**: Redis 客户端封装
+
+#### B8. `backend/routers/projects.py`
+- **类型**: 新增
+- **内容**: 项目 CRUD API
+
+#### B9. `backend/routers/templates.py`
+- **类型**: 新增
+- **内容**: 本体模板 API
+
+#### B10. `backend/routers/media.py`
+- **类型**: 新增
+- **内容**: 视频/图片/DCM 上传 API，FFmpeg 拆帧任务触发
+
+#### B11. `backend/routers/ai.py`
+- **类型**: 新增
+- **内容**: SAM 3 推理 API（point/box/semantic），Mask 生成与存储
+
+#### B12. `backend/routers/export.py`
+- **类型**: 新增
+- **内容**: 标注数据导出（COCO JSON、PNG Mask）
+
+#### B13. `backend/services/sam3_engine.py`
+- **类型**: 新增
+- **内容**: SAM 3 模型加载、推理封装、GPU 内存管理
+
+#### B14. `backend/services/frame_parser.py`
+- **类型**: 新增
+- **内容**: FFmpeg 视频拆帧、DCM 影像逐帧提取、帧上传 MinIO
+
+#### B15. `backend/services/task_queue.py`
+- **类型**: 新增
+- **内容**: Celery + Redis 异步任务队列封装
+
+#### B16. `backend/requirements.txt`
+- **类型**: 新增
+- **内容**: Python 依赖清单
+
+### C. 前端层 (修改现有 src/)
+
+#### C1. `src/store/index.ts` (新增)
+- **内容**: Zustand 全局 Store（project、workspace、annotations、ui 状态）
+
+#### C2. `src/lib/api.ts` (新增)
+- **内容**: Axios 实例封装，baseURL 指向 FastAPI
+
+#### C3. `src/lib/websocket.ts` (新增)
+- **内容**: WebSocket 客户端，接收解析进度
+
+#### C4. `src/App.tsx` (修改)
+- **内容**: 移除 Login 硬编码，接入真实登录 API；Provider 包裹
+
+#### C5. `src/components/ProjectLibrary.tsx` (修改)
+- **内容**: 从后端 API 加载项目列表，支持创建/删除
+
+#### C6. `src/components/TemplateRegistry.tsx` (修改)
+- **内容**: 从后端 API 加载本体字典，支持动态增删
+
+#### C7. `src/components/CanvasArea.tsx` (修改)
+- **内容**: 点击画布捕获坐标，发送至后端 AI 接口，接收并渲染 Mask Path
+
+#### C8. `src/components/AISegmentation.tsx` (修改)
+- **内容**: 对接后端 SAM 3 推理接口，显示推理状态
+
+#### C9. `src/components/Dashboard.tsx` (修改)
+- **内容**: 显示真实解析队列进度（WebSocket）
+
+### D. 部署与运维
+
+#### D1. `start_services.sh` (新增)
+- **内容**: 一键启动 PostgreSQL、Redis、MinIO、FastAPI 的脚本
+
+#### D2. `backend/download_sam3.py` (新增)
+- **内容**: SAM 3 模型权重自动下载脚本
+
+## 新增依赖
+
+### Python (conda 环境)
+```
+fastapi uvicorn[standard] python-multipart
+sqlalchemy psycopg2-binary alembic
+redis celery
+minio
+opencv-python pillow scikit-image pydicom numpy
+```
+
+### 前端 (npm)
+```
+zustand axios
+```
+
+## 兼容性分析
+- Express `server.ts` 将被保留但不再作为默认启动方式，FastAPI 成为主后端
+- 前端路由逻辑不变，仅数据获取方式从内存/mock 改为 HTTP API
+- 回滚策略: 回退到 `npm start` 仍可运行旧版 Express 前端
+
+## 预估工作量
+- 基础设施: 20 分钟
+- 后端骨架: 40 分钟
+- 前端改造: 30 分钟
+- SAM 3 部署: 20 分钟
+- 联调验证: 20 分钟
--- a/工程分析/测试方案-2026-04-29-21-51-19.md
+++ b/工程分析/测试方案-2026-04-29-21-51-19.md
@@ -0,0 +1,78 @@
+# 测试方案 - 2026-04-29-21-51-19
+
+## 对应实现方案
+- 实现方案文档: `实现方案-2026-04-29-21-51-19.md`
+
+## 测试范围
+- 基础设施服务可达性
+- FastAPI 后端启动与 API 响应
+- 前端构建与后端联调
+- SAM 3 模型加载与 GPU 可用性
+- 文件上传与解析流程
+
+## 测试用例
+
+### 用例 1: 基础设施服务验证
+- **前置条件**: 执行 start_services.sh
+- **操作步骤**:
+  1. `curl http://localhost:9000/minio/health/live` → MinIO
+  2. `redis-cli ping` → Redis
+  3. `sudo -u postgres psql -c "\\l"` → PostgreSQL
+- **预期结果**: 全部返回正常响应
+- **通过标准**: MinIO 200, Redis PONG, PostgreSQL 显示数据库列表
+
+### 用例 2: Conda 环境 + GPU 验证
+- **前置条件**: conda 环境已创建
+- **操作步骤**:
+  1. `conda activate seg_server`
+  2. `python -c "import torch; print(torch.cuda.is_available())"`
+- **预期结果**: 输出 True
+- **通过标准**: PyTorch 识别到 CUDA
+
+### 用例 3: SAM 3 权重下载验证
+- **前置条件**: 运行 download_sam3.py
+- **操作步骤**: 检查权重文件存在且大小合理
+- **预期结果**: .pt/.pth 文件存在于 models/ 目录
+- **通过标准**: 文件大小 > 100MB
+
+### 用例 4: FastAPI 启动验证
+- **前置条件**: 依赖安装完成
+- **操作步骤**:
+  1. `cd backend && uvicorn main:app --host 0.0.0.0 --port 8000`
+  2. 访问 `http://localhost:8000/docs`
+- **预期结果**: Swagger UI 正常显示，包含所有 API 路由
+- **通过标准**: HTTP 200，路由列表完整
+
+### 用例 5: 前端构建验证
+- **前置条件**: 前端代码已改造
+- **操作步骤**: `npm run lint && npm run build`
+- **预期结果**: 无类型错误，构建成功
+- **通过标准**: exit code 0
+
+### 用例 6: 前后端联调验证
+- **前置条件**: 前后端均运行中
+- **操作步骤**:
+  1. 前端访问 `http://localhost:3000`
+  2. 打开浏览器 DevTools Network 面板
+  3. 触发项目列表加载
+- **预期结果**: 可见对 `http://localhost:8000/api/projects` 的请求，且返回 200
+- **通过标准**: API 数据正确渲染到界面
+
+### 用例 7: 文件上传验证
+- **前置条件**: 媒体解析模块就绪
+- **操作步骤**: 上传 @Data_MyVideo_1.mp4
+- **预期结果**: 后端接收文件，存入 MinIO，触发解析任务
+- **通过标准**: MinIO bucket 中出现文件，返回 job_id
+
+## 回归测试
+- [ ] 现有 React 组件无运行时错误
+- [ ] 深色主题样式未被破坏
+- [ ] Konva Canvas 可正常交互
+- [ ] 构建产物体积未异常膨胀
+
+## 测试环境
+- OS: Ubuntu 22.04
+- GPU: NVIDIA RTX 4090 24GB
+- CUDA: 13.2
+- Python: 3.11 (conda)
+- Node.js: 22.x
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -65,4 +65,38 @@ AI 助手运行的容器/环境与项目实际开发环境分离，后者才装

 ---

+## 2026-04-29-21-51-19 — 全栈系统改造（FastAPI + SAM2 + PostgreSQL + Redis + MinIO）
+
+### A. 具体问题
+1. 将纯前端 React 应用改造为全栈系统时，工程涉及后端框架替换、数据库设计、对象存储、AI 推理引擎、前端状态管理重构等多个复杂模块，单次执行工程量大。
+2. 系统磁盘空间（24G）不足，PyTorch CUDA 版本（>2GB）和 sam2 pip 包编译（需下载 CUDA 工具链 + 编译 C++ 扩展）均因 `OSError: No space left on device` 失败。
+3. MinIO 对象存储在磁盘紧张时报 `XMinioStorageFull`，导致文件上传失败。
+4. 前端 Agent 执行时因目录扁平化后子目录不存在，产生多次 `File not found` 错误。
+
+### B. 产生原因
+1. 项目改造范围超出单次会议合理容量，涉及 15+ 后端文件、10+ 前端文件、4 个基础设施服务、1 个 AI 模型栈。
+2. 系统盘仅有 24GB，conda 环境（2GB）、node_modules（222MB）、模型权重（1.5GB）、MinIO 帧文件（1.4GB）叠加后迅速耗尽空间。
+3. sam2 的 pip 包依赖 torch>=2.5.1，pip 会尝试重新下载完整 torch wheel（530MB）作为 build dependency，即使 torch 已安装。
+4. 前端 Agent 的 prompt 中未明确说明组件目录已扁平化，Agent 仍尝试读取旧的子目录路径。
+
+### C. 解决方案
+1. **任务拆分 + 并行 Agent**: 将后端和前端代码编写拆分为两个独立 Agent 并行执行，基础设施安装与代码编写并行推进，显著缩短总耗时。
+2. **磁盘管理策略**:
+   - 安装 PyTorch CPU 版本替代 CUDA 版本（占用更小）
+   - 只保留 sam2_hiera_tiny.pt（149MB），删除其他大模型
+   - 清理 conda pkgs 缓存（释放 600MB+）
+   - 删除 MinIO 中解析生成的临时帧文件（释放 1.4GB）
+3. **sam2 安装降级**: 当前环境以 stub 模式运行，提供 `install_sam2.sh` 脚本供用户在扩展磁盘后执行真实安装。
+4. **API 路径修复**: 后端添加 `/api/auth/login` 路由，修复前端 api.ts 中 `/api/predict` → `/api/ai/predict` 的路径不匹配。
+5. **MinIO API 适配**: minio 7.2.x 中 `presigned_url()` 已改为 `get_presigned_url()`，需从 `datetime.timedelta` 传入 expires。
+
+### D. 后续如何避免问题
+1. **大型改造前先做磁盘评估**: 执行 `df -h` 确认可用空间 > 5GB 再开始安装大型依赖。
+2. **AI 模型依赖延迟加载**: 所有 AI 推理引擎必须实现 graceful fallback，模型缺失时不阻塞系统启动。
+3. **Agent prompt 需同步最新目录结构**: 给 Agent 的上下文必须包含当前真实的文件路径，避免 `File not found`。
+4. **构建依赖隔离**: 使用 `--no-build-isolation` 或 `--no-deps` 安装源码包，避免 pip 重复下载已安装的依赖。
+5. **MinIO 空间监控**: 定期清理解析产生的临时帧文件，或配置 MinIO 使用独立大容量数据盘。
+
+---
+
 > 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。
--- a/工程分析/需求分析-2026-04-29-21-51-19.md
+++ b/工程分析/需求分析-2026-04-29-21-51-19.md
@@ -0,0 +1,75 @@
+# 需求分析 - 2026-04-29-21-51-19
+
+## 需求来源
+- 提出时间: 2026-04-29-21-51-19
+- 需求类型: 全栈系统改造 / 架构重构
+
+## 原始需求描述
+将现有纯前端 React 静态 UI 彻底改造为前后端联动的全栈语义分割系统。打通数据流转，实现：
+1. 本地多媒体资产（视频/图片/DCM影像）上传
+2. 服务器端按帧解析（FFmpeg 拆帧）
+3. AI 视觉大模型 SAM 3 实时交互式推理（点分割、box分割、语义分割）
+4. 动态图层状态管理
+5. 标注数据结构化导出
+
+后端技术栈：Python + FastAPI + PostgreSQL + Redis + MinIO
+AI 基座：SAM 3
+输入数据：@Data_MyVideo_1.mp4、@Data_Dicom帧（DCM格式）
+
+## 需求拆解
+
+### 需求 1: 基础设施部署
+- **详细描述**: 在 Ubuntu 22.04 上部署 PostgreSQL、Redis、MinIO 对象存储
+- **优先级**: P0-阻塞
+- **影响范围**: 系统级服务
+- **验收标准**: 三个服务均可访问，有持久化数据目录
+
+### 需求 2: Conda 环境 + SAM 3 模型部署
+- **详细描述**: 新建 conda 环境 seg_server，安装 PyTorch + CUDA，部署 SAM 3 模型权重
+- **优先级**: P0-阻塞
+- **影响范围**: Python AI 推理层
+- **验收标准**: conda 环境可激活，GPU 可被 PyTorch 识别，SAM 3 权重文件存在
+
+### 需求 3: FastAPI 后端框架搭建
+- **详细描述**: 替换现有 Express 后端，建立 FastAPI 服务，包含上传、项目、模板、AI推理、导出等模块
+- **优先级**: P0-阻塞
+- **影响范围**: 后端全部
+- **验收标准**: FastAPI 服务可启动，Swagger UI 可访问
+
+### 需求 4: 前端状态管理 + 网络层改造
+- **详细描述**: 引入 Zustand 全局状态管理，Axios 替代 fetch，WebSocket 对接解析进度
+- **优先级**: P0-阻塞
+- **影响范围**: src/ 全部
+- **验收标准**: 前端可正常与后端通信，状态跨组件同步
+
+### 需求 5: Canvas Mask 渲染对接
+- **详细描述**: Konva Canvas 接收后端 SAM 3 返回的 Mask 数据（Polygon/RLE），动态渲染遮罩图层
+- **优先级**: P1-高
+- **影响范围**: CanvasArea.tsx, AISegmentation.tsx
+- **验收标准**: 点击画布后，后端返回 Mask，前端可正确绘制
+
+### 需求 6: 视频/DCM 解析流水线
+- **详细描述**: 上传视频后 FFmpeg 拆帧，DCM 影像逐帧提取，进度通过 WebSocket 推送
+- **优先级**: P1-高
+- **影响范围**: 后端任务模块 + 前端 Dashboard
+- **验收标准**: 可上传文件，解析队列可显示进度，帧图片存入 MinIO
+
+### 需求 7: 数据持久化（项目/模板/标注）
+- **详细描述**: PostgreSQL 存储项目元数据、本体字典、标注结果；MinIO 存储原始媒体/帧/Mask
+- **优先级**: P1-高
+- **影响范围**: 后端数据库模型 + API
+- **验收标准**: 数据重启后仍可读取
+
+## 约束条件
+- 使用 Ubuntu 22.04, sudo 密码 Wkmgc
+- GPU: RTX 4090, CUDA 13.2
+- 无 Docker，使用系统包管理 + 二进制部署
+- 保持现有前端界面风格（深色主题、中文）
+
+## 风险评估
+| 风险点 | 影响 | 缓解措施 |
+|--------|------|----------|
+| SAM 3 权重下载慢/失败 | 高 | 使用国内镜像源，分段下载验证 |
+| PostgreSQL/Redis 端口冲突 | 中 | 检查端口占用，使用非默认端口 |
+| MinIO 磁盘空间不足 | 中 | 监控磁盘，配置清理策略 |
+| 单次会议工程过大 | 高 | 分模块迭代，先跑通骨架再丰富 |