2026-04-29-21-51-19 - 全栈系统改造：FastAPI后端+SAM2+PostgreSQL+Redis+MinIO+前端Zustand重构
This commit is contained in:
185
工程分析/实现方案-2026-04-29-21-51-19.md
Normal file
185
工程分析/实现方案-2026-04-29-21-51-19.md
Normal file
@@ -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 分钟
|
||||
Reference in New Issue
Block a user