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

工程分析/经验记录.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 四段。