8.4 KiB
8.4 KiB
实现方案 - 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 分钟