admin/Pre_Seg_Server
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

2026-04-29-22-29-26 - 完善README.md：系统架构+技术栈+完整部署流程+常见问题

Browse Source
This commit is contained in:
admin
2026-04-29 22:32:06 +08:00
parent fd4b5e5b3d
commit f41d9c20f5
5 changed files with 536 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

388
README.md
View File

@@ -2,19 +2,387 @@
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" /> <img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
</div> </div>
# Run and deploy your AI Studio app # 语义分割系统（SegServer）
This contains everything you need to run your app locally. > 基于 React + FastAPI + SAM 2 的全栈交互式图像/视频语义分割与标注平台。
>
> 支持本地多媒体资产上传、服务器端按帧解析、AI 视觉大模型实时推理（正反向选点、框选生成分割 Mask）、动态图层状态管理及最终标注数据结构化导出。
View your app in AI Studio: https://ai.studio/apps/2707f0e1-d453-4594-a618-fba53cb937c4 ---
## Run Locally ## 核心功能
**Prerequisites:** Node.js - **多媒体资产管理** — 支持视频（MP4/AVI/MOV）和 DICOM 医学影像的上传、存储与解析
- **AI 智能分割引擎** — 集成 SAM 2 模型，支持点分割（point）、框分割（box）、语义分割（semantic）和自动分割（auto）
- **交互式画布标注** — 基于 Konva 的高性能 Canvas，支持缩放/平移/选点/框选，实时渲染 Mask 遮罩
- **本体字典管理** — 可配置的分类体系、颜色映射、图层优先级（z-index）
- **项目工作区** — 项目创建、帧浏览、多图层标注、进度追踪
- **数据导出** — 支持 COCO JSON 格式和 PNG Mask 批量导出
---
1. Install dependencies: ## 系统架构
`npm install`
2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key ```
3. Run the app: ┌─────────────────────────────────────────────────────────────┐
`npm run dev` │ 前端展示层 (React 19 + Vite + TailwindCSS) │
│ localhost:3000 │
│ Zustand(状态) + Axios(API) + WebSocket(实时进度) │
│ Konva(Canvas渲染) + lucide-react(图标) │
└──────────────────────────┬──────────────────────────────────┘
│ HTTP / WebSocket
┌──────────────────────────▼──────────────────────────────────┐
│ 业务逻辑层 (FastAPI + Python 3.11) │
│ localhost:8000 │
│ ├── /api/auth 登录认证 │
│ ├── /api/projects 项目 & 视频帧 CRUD │
│ ├── /api/templates 本体字典（分类/颜色/z-index） │
│ ├── /api/media 文件上传 & FFmpeg/pydicom 帧解析 │
│ ├── /api/ai SAM 2 推理（点/框/语义/自动分割） │
│ └── /api/export COCO JSON / PNG Masks 导出 │
└──────────────────────────┬──────────────────────────────────┘
│ SQLAlchemy 2.0
┌──────────────────────────▼──────────────────────────────────┐
│ 数据持久化层 │
│ PostgreSQL 14 — 项目/帧/标注/Mask 元数据 │
│ Redis 6 — 缓存 & 任务队列状态 │
│ MinIO — 对象存储（原始视频/解析帧/Mask图像） │
└─────────────────────────────────────────────────────────────┘
```
---
## 技术栈
| 层级 | 技术选型 | 版本 |
|------|----------|------|
| 前端框架 | React + TypeScript | React 19, TS 5.8 |
| 构建工具 | Vite | v6 |
| 样式方案 | TailwindCSS + 自定义深色主题 | v4 |
| 状态管理 | Zustand | - |
| Canvas 渲染 | Konva + react-konva | - |
| HTTP 客户端 | Axios | - |
| 后端框架 | FastAPI | v0.136+ |
| 数据库 ORM | SQLAlchemy + Alembic | 2.0+ |
| 数据库 | PostgreSQL | 14 |
| 缓存 | Redis | 6 |
| 对象存储 | MinIO | 2025+ |
| AI 推理 | SAM 2 (Meta) + PyTorch | - |
| 视频处理 | FFmpeg + OpenCV | 4.4+ |
| DICOM 处理 | pydicom | 3.0+ |
---
## 目录结构
```
Seg_Server/
├── backend/ # FastAPI 后端
│ ├── main.py # 应用入口（CORS/生命周期/路由注册）
│ ├── config.py # 环境变量配置（Pydantic Settings）
│ ├── database.py # SQLAlchemy 引擎 + Session
│ ├── models.py # ORM 模型（Project/Frame/Template/Annotation/Mask）
│ ├── schemas.py # Pydantic 请求/响应校验模型
│ ├── minio_client.py # MinIO 上传/下载/预签名URL封装
│ ├── redis_client.py # Redis 连接封装
│ ├── download_sam2.py # SAM 2 模型权重自动下载脚本
│ ├── requirements.txt # Python 依赖
│ ├── routers/ # API 路由
│ │ ├── auth.py # 登录认证
│ │ ├── projects.py # 项目 & 帧 CRUD
│ │ ├── templates.py # 本体字典管理
│ │ ├── media.py # 上传 & 解析
│ │ ├── ai.py # SAM 2 推理接口
│ │ └── export.py # 数据导出
│ └── services/ # 业务服务
│ ├── sam2_engine.py # SAM 2 推理引擎（懒加载 + stub降级）
│ └── frame_parser.py # FFmpeg 拆帧 / pydicom 读片
├── src/ # React 前端
│ ├── main.tsx # 应用挂载点
│ ├── App.tsx # 根组件（模块路由 + 鉴权）
│ ├── store/
│ │ └── useStore.ts # Zustand 全局状态
│ ├── lib/
│ │ ├── api.ts # Axios 实例 + API 方法封装
│ │ ├── websocket.ts # WebSocket 客户端（解析进度）
│ │ └── utils.ts # cn() 工具函数
│ └── components/ # 组件（扁平化目录）
│ ├── Login.tsx # 登录页
│ ├── Sidebar.tsx # 左侧导航栏
│ ├── Dashboard.tsx # 总体概况仪表盘（解析队列）
│ ├── ProjectLibrary.tsx # 项目库列表
│ ├── VideoWorkspace.tsx # 核心分割工作区布局
│ ├── CanvasArea.tsx # Konva 画布（缩放/平移/选点/Mask渲染）
│ ├── ToolsPalette.tsx # 左侧工具栏
│ ├── OntologyInspector.tsx # 右侧本体/属性检查面板
│ ├── FrameTimeline.tsx # 底部时间轴
│ ├── AISegmentation.tsx # AI 智能分割引擎界面
│ └── TemplateRegistry.tsx # 模板库管理
├── models/ # SAM 2 模型权重（.pt 文件）
├── uploads/ # 临时上传目录
├── frames/ # 临时帧目录
├── start_services.sh # 一键启动所有服务脚本
├── server.ts # 旧版 Express 入口（已弃用）
├── index.html # SPA HTML 入口
├── vite.config.ts # Vite 构建配置
├── package.json # npm 依赖与脚本
└── tsconfig.json # TypeScript 配置
```
---
## 环境准备
### 系统要求
- **OS**: Ubuntu 22.04 LTS
- **GPU**: NVIDIA GPU（推荐 RTX 4090 或同等算力），用于 SAM 2 推理
- **CUDA**: 12.x / 13.x
- **Node.js**: 22.x+
- **Python**: 3.11（通过 Miniconda/Anaconda 管理）
### 安装系统级依赖
```bash
# 更新包索引
sudo apt update
# 安装 PostgreSQL、Redis、FFmpeg、构建工具
sudo apt install -y postgresql postgresql-contrib redis-server ffmpeg \
libpq-dev build-essential curl ca-certificates gnupg
# 安装 MinIO（二进制方式）
mkdir -p ~/minio_data
cd /tmp
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/
```
---
## 部署流程
### 步骤 1: 配置 PostgreSQL 数据库
```bash
# 启动服务
sudo systemctl start postgresql redis-server
# 创建数据库和用户
sudo -u postgres psql -c "CREATE DATABASE segserver;"
sudo -u postgres psql -c "CREATE USER seguser WITH PASSWORD 'segpass123';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE segserver TO seguser;"
sudo -u postgres psql -d segserver -c "GRANT ALL ON SCHEMA public TO seguser;"
sudo -u postgres psql -c "ALTER DATABASE segserver OWNER TO seguser;"
```
### 步骤 2: 启动 MinIO
```bash
nohup minio server ~/minio_data --console-address :9001 > /tmp/minio.log 2>&1 &
# 验证
# API: http://localhost:9000
# 控制台: http://localhost:9001 （minioadmin / minioadmin）
```
### 步骤 3: 创建 Conda 环境并安装 Python 依赖
```bash
# 创建环境
conda create -n seg_server python=3.11 -y
conda activate seg_server
# 安装 PyTorch（根据 CUDA 版本选择）
# CUDA 12.x 用户:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
# CPU 用户（无 GPU）:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# 安装后端依赖
cd ~/Desktop/Seg_Server/backend
pip install -r requirements.txt
```
### 步骤 4: 下载 SAM 2 模型权重
```bash
cd ~/Desktop/Seg_Server/backend
python download_sam2.py
# 模型将下载到 ~/Desktop/Seg_Server/models/
# sam2_hiera_tiny.pt (149 MB)
# sam2_hiera_small.pt (176 MB)
# sam2_hiera_base_plus.pt (309 MB)
# sam2_hiera_large.pt (856 MB)
```
> **注意**：当前系统磁盘紧张时，建议仅保留 `sam2_hiera_tiny.pt`，删除其他模型以释放空间。
### 步骤 5: 配置环境变量
项目根目录已提供默认配置，如需修改请编辑以下文件：
**backend/.env**（数据库/Redis/MinIO/SAM 路径）:
```ini
DATABASE_URL=postgresql://seguser:segpass123@localhost:5432/segserver
REDIS_URL=redis://localhost:6379/0
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=seg-media
SAM2_MODEL_PATH=/home/wkmgc/Desktop/Seg_Server/models/sam2_hiera_tiny.pt
```
### 步骤 6: 启动后端服务
```bash
cd ~/Desktop/Seg_Server/backend
source ~/miniconda3/etc/profile.d/conda.sh
conda activate seg_server
uvicorn main:app --host 0.0.0.0 --port 8000
# 或使用后台模式
nohup uvicorn main:app --host 0.0.0.0 --port 8000 > /tmp/fastapi.log 2>&1 &
```
后端启动后将自动：
- 创建数据库表（如果不存在）
- 检查 MinIO bucket 是否存在
- 测试 Redis 连接
- 懒加载 SAM 2 模型（权重存在且 sam2 包已安装时）
### 步骤 7: 安装前端依赖并构建
```bash
cd ~/Desktop/Seg_Server
# 安装依赖
npm install
# 类型检查
npm run lint
# 生产构建
npm run build
# 启动前端服务
npm start
# 或使用后台模式
nohup npm start > /tmp/frontend.log 2>&1 &
```
---
## 一键启动（推荐）
项目根目录提供了 `start_services.sh` 脚本，可一键启动所有服务：
```bash
cd ~/Desktop/Seg_Server
./start_services.sh
```
脚本将依次检查并启动：PostgreSQL → Redis → MinIO → FastAPI 后端 → 前端。
---
## 访问地址与默认凭证
| 服务 | 地址 | 说明 |
|------|------|------|
| 前端界面 | http://localhost:3000 | admin / 123456 |
| 后端 API 文档 | http://localhost:8000/docs | Swagger UI |
| MinIO 控制台 | http://localhost:9001 | minioadmin / minioadmin |
| PostgreSQL | localhost:5432 | seguser / segpass123 |
---
## 可用命令
### 前端
```bash
npm install # 安装依赖
npm run dev # Vite 开发模式（端口 5173）
npm run build # 生产构建（输出到 dist/）
npm run lint # TypeScript 类型检查
npm start # Node.js 运行 server.ts（旧版）
```
### 后端
```bash
# 在 conda seg_server 环境中
cd backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload # 开发模式（热重载）
uvicorn main:app --host 0.0.0.0 --port 8000 # 生产模式
```
---
## 常见问题
### Q1: 磁盘空间不足导致 PyTorch / sam2 安装失败
**现象**: `OSError: [Errno 28] No space left on device`
**解决**:
```bash
# 1. 清理系统包缓存
sudo apt autoremove -y && sudo apt clean
# 2. 清理 conda 缓存
conda clean --all -y
# 3. 仅保留最小模型
rm ~/Desktop/Seg_Server/models/sam2_hiera_large.pt
rm ~/Desktop/Seg_Server/models/sam2_hiera_base_plus.pt
rm ~/Desktop/Seg_Server/models/sam2_hiera_small.pt
# 4. 如需安装 sam2 包，确保有 >5GB 可用空间后再执行
```
### Q2: SAM 2 推理返回 dummy polygons（矩形框）
**原因**: `sam2` Python 包未安装，或模型权重路径不正确。
**解决**:
```bash
# 1. 确认模型文件存在
ls ~/Desktop/Seg_Server/models/sam2_hiera_tiny.pt
# 2. 安装 sam2（需 >5GB 磁盘空间）
cd /tmp
git clone --depth 1 https://github.com/facebookresearch/segment-anything-2.git
cd segment-anything-2
pip install -e . --no-build-isolation
# 3. 重启后端服务
```
### Q3: MinIO 报 `XMinioStorageFull`
**原因**: 系统磁盘可用空间低于 MinIO 默认阈值。
**解决**: 清理解析产生的临时帧文件或扩展磁盘空间。
### Q4: 前端无法连接后端 API
**检查清单**:
1. 后端是否已启动（`curl http://localhost:8000/health`）
2. `backend/.env` 中的 `cors_origins` 是否包含 `http://localhost:3000`
3. 前端 `src/lib/api.ts` 中的 `baseURL` 是否为 `http://localhost:8000`
---
## 开发团队
本项目基于 Google AI Studio 模板构建，经全栈化改造后用于工业级语义分割场景。
---
> 如需添加新功能或修复问题，请遵循项目根目录 `工程分析/代码编纂工作流.md` 中定义的代码编纂流程。

42
工程分析/实现方案-2026-04-29-22-29-26.md Normal file
View File

@@ -0,0 +1,42 @@
# 实现方案 - 2026-04-29-22-29-26
## 对应需求
- 需求分析文档: `需求分析-2026-04-29-22-29-26.md`
## 方案概述
将现有 20 行的旧版 README.md 重写为完整的项目文档，涵盖系统介绍、技术架构、目录结构、环境准备、分步部署流程、配置说明和常见问题。
## 修改文件清单
### 文件 1: README.md（重写）
- **修改类型**: 重写
- **内容结构**:
1. 项目标题与概述
2. 核心功能列表
3. 系统架构图（文本版）
4. 技术栈表格
5. 目录结构说明
6. 环境准备（系统依赖、Conda、Node.js）
7. 部署流程（分步命令）
- 步骤 1: 基础设施（PostgreSQL/Redis/MinIO/FFmpeg）
- 步骤 2: Conda 环境创建与 Python 依赖安装
- 步骤 3: SAM 2 模型权重下载
- 步骤 4: 数据库初始化
- 步骤 5: 后端启动
- 步骤 6: 前端依赖安装与构建
- 步骤 7: 前端启动
8. 一键启动脚本说明
9. 环境变量配置说明
10. 访问地址与默认凭证
11. 常见问题（磁盘空间、SAM2 安装）
## 新增依赖
无
## 兼容性分析
- 无业务代码变更
- 回滚策略: 从 git 历史恢复旧 README
## 预估工作量
- 文档编写: 15 分钟
- 验证: 5 分钟

48
工程分析/测试方案-2026-04-29-22-29-26.md Normal file
View File

@@ -0,0 +1,48 @@
# 测试方案 - 2026-04-29-22-29-26
## 对应实现方案
- 实现方案文档: `实现方案-2026-04-29-22-29-26.md`
## 测试范围
- README.md 内容完整性
- Markdown 语法正确性
- 部署命令准确性
## 测试用例
### 用例 1: 文档结构完整性
- **前置条件**: README.md 已更新
- **操作步骤**: 检查是否包含以下章节
1. 项目概述
2. 核心功能
3. 系统架构
4. 技术栈
5. 目录结构
6. 环境准备
7. 部署流程
8. 一键启动
9. 环境变量
10. 访问地址
11. 常见问题
- **预期结果**: 全部 11 个章节均存在
- **通过标准**: grep 每个章节标题均有匹配
### 用例 2: Markdown 渲染验证
- **前置条件**: README.md 已更新
- **操作步骤**: 在 Gitea 或 Markdown 预览器中打开
- **预期结果**: 无格式错乱，表格/代码块/标题层级正确
- **通过标准**: 视觉检查通过
### 用例 3: 部署命令准确性抽查
- **前置条件**: README.md 已更新
- **操作步骤**: 随机抽取 3 条命令在 Shell 中验证语法
- **预期结果**: 命令格式正确，路径存在
- **通过标准**: 3/3 通过
## 回归测试
- [ ] 不破坏现有文件
- [ ] .gitignore 未受影响
## 测试环境
- Gitea Markdown 渲染器
- Shell bash

18
工程分析/经验记录.md
View File

@@ -99,4 +99,22 @@ AI 助手运行的容器/环境与项目实际开发环境分离，后者才装
--- ---
## 2026-04-29-22-29-26 — README.md 完善
### A. 具体问题
项目全栈改造完成后，README.md 仍为旧版 AI Studio 模板，未反映真实系统架构和部署流程，新用户无法按文档独立完成部署。
### B. 产生原因
前期聚焦功能开发，文档滞后；改造涉及后端/前端/基础设施/AI 模型多个层级，文档编写工作量大。
### C. 解决方案
按代码编纂工作流，编写需求分析→实现方案→测试方案，然后一次性重写 README.md，涵盖系统架构、技术栈、目录结构、分步部署命令、环境变量、访问凭证、常见问题。
### D. 后续如何避免问题
- 任何架构级变更后，同步更新 README.md
- 将 README 纳入代码审查清单
- 新成员入职时按 README 走通部署流程作为验收标准
---
> 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。 > 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。

50
工程分析/需求分析-2026-04-29-22-29-26.md Normal file
View File

@@ -0,0 +1,50 @@
# 需求分析 - 2026-04-29-22-29-26
## 需求来源
- 提出时间: 2026-04-29-22-29-26
- 需求类型: 文档完善
## 原始需求描述
完善 README.md，在其中加入程序部署流程。
## 需求拆解
### 需求 1: 重写 README.md 项目概述
- **详细描述**: 当前 README 仍为 AI Studio 旧模板，需更新为反映全栈语义分割系统的真实定位
- **优先级**: P0-阻塞
- **影响范围**: README.md
- **验收标准**: README 开篇准确描述项目定位、核心功能、技术栈
### 需求 2: 加入系统架构图/说明
- **详细描述**: 用文本或 Markdown 表格描述前后端架构拓扑
- **优先级**: P0-阻塞
- **影响范围**: README.md
- **验收标准**: 读者可从 README 理解系统各层级关系
### 需求 3: 加入完整部署流程
- **详细描述**: 包含基础设施安装（PostgreSQL/Redis/MinIO/FFmpeg）、Conda 环境配置、Python 依赖安装、模型权重下载、前后端启动
- **优先级**: P0-阻塞
- **影响范围**: README.md
- **验收标准**: 新用户按 README 可独立完成从零到运行的全部部署
### 需求 4: 加入目录结构说明
- **详细描述**: 列出 backend/、src/、models/ 等关键目录的用途
- **优先级**: P1-高
- **影响范围**: README.md
- **验收标准**: 目录结构清晰，便于开发者快速定位代码
### 需求 5: 加入环境变量和配置说明
- **详细描述**: 说明 .env、backend/.env 等配置文件的作用和必填项
- **优先级**: P1-高
- **影响范围**: README.md
- **验收标准**: 配置项完整，默认值合理
## 约束条件
- 使用中文撰写 README（界面已中文，文档保持一致）
- 不修改任何业务代码
- 保留现有 banner 图片（如有）
## 风险评估
| 风险点 | 影响 | 缓解措施 |
|--------|------|----------|
| 文档与实际代码不同步 | 中 | 基于实际已部署的代码和配置编写 |