geMoldInsight/docs/topics/storage/STORAGE_SETUP.md

# 存储架构说明

> 文档定位：**存储分层与数据流的专题说明文档**。
> 本文主要解释 geMoldInsight 的存储架构，不作为当前部署入口或当前状态的权威说明。当前部署方式见 [../../DEPLOYMENT.md](../../DEPLOYMENT.md)，当前状态见 [../../STATUS.md](../../STATUS.md)，总体架构见 [../../ARCHITECTURE.md](../../ARCHITECTURE.md)。
> 其历史中的“本项目自行拉起 PostgreSQL / MinIO 并通过 `python src/main.py` 启动单体”的部分，**已不再代表当前默认部署方式**。

当前默认部署前提是：

- PostgreSQL 由服务器已有服务提供
- Redis 由服务器已有服务提供
- RustFS / MinIO 兼容对象存储由服务器已有服务提供
- 项目自身只部署：`moldinsight` / `moldinsight-celery` / `inventory`

如需查看当前部署方式，请优先参考：
- [../../../README.md](../../../README.md)
- [../../deployment/LINUX_SETUP.md](../../deployment/LINUX_SETUP.md)
- [../../deployment/DEPLOY_PORT.md](../../deployment/DEPLOY_PORT.md)
- [../../archive/BACKEND_MODULARIZATION_BLUEPRINT.md](../../archive/BACKEND_MODULARIZATION_BLUEPRINT.md)

---

## 架构概述

本项目采用 **RustFS（S3兼容）对象存储** + **PostgreSQL 元数据存储** 的双层存储架构。

```text
┌─────────────────────────────────────────────────────────────┐
│                  应用层 (moldinsight / inventory)            │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                              │
┌───────▼────────┐        ┌─────────▼─────────┐
│   PostgreSQL    │        │     RustFS / S3   │
│   (元数据)      │        │   (对象存储)       │
│                │        │                  │
│ - users        │        │ - stp-files      │
│ - stp_files    │        │ - geometry       │
│ - geometry_data│        │ - mold-cavities │
│ - processing   │        │ - html-files     │
│ - logs         │        │ - user-files     │
└────────────────┘        └──────────────────┘
```

---

## PostgreSQL 数据表（摘要）

### 用户管理
- `users` - 用户信息
- `roles` / `permissions` - 权限体系

### moldinsight 相关
- `stp_files` - STP 文件元数据
- `html_files` - HTML 报告元数据
- `geometry_data` - 几何分析数据
- `mold_cavity_data` - 模具型腔数据
- `feature_detections` - 特征检测结果
- `design_recommendations` - 设计建议
- `processing_tasks` - 处理任务记录
- `analysis_metrics` - 分析指标

### inventory 相关
- `products` - 产品/物料
- `product_materials` - BOM
- `inventory` - 库存
- `stock_movements` - 库存流水
- `purchase_orders` / `sales_orders` - 订单
- `finance_transactions` - 财务流水

---

## RustFS / S3 存储桶

| 存储桶名称 | 用途 | 存储内容 |
|---|---|---|
| `moldinsight-stp-files` | STP/STEP 文件 | 用户上传的原始 3D 模型 |
| `moldinsight-geometry` | 几何结果 | 几何分析 JSON |
| `moldinsight-mold-cavities` | 模具结果 | 模具设计 JSON |
| `moldinsight-html` | HTML 报告 | 生成的 HTML 报告文件 |
| `moldinsight-user-files` | 用户文件 | 其他附件/用户文件 |

---

## 当前推荐初始化方式

### 1. 准备环境变量

```bash
cp .env.example .env
nano .env
```

确保以下变量指向**服务器上已存在的真实服务**：

```env
DB_HOST=your-db-host
DB_PORT=5432
DB_NAME=moldinsight
DB_USER=moldinsight
DB_PASSWORD=change-me

REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=

RUSTFS_ENDPOINT=http://your-storage-host:9000
RUSTFS_ACCESS_KEY=change-me
RUSTFS_SECRET_KEY=change-me
```

### 2. 初始化数据库

当前初始化入口参考：
- [init_db.py](../../../src/shared/database/init_db.py)

### 3. 启动项目服务

当前推荐通过（按模式对应不同 compose 文件）：
- `docker compose up -d`（[docker-compose.yml](../../../docker-compose.yml)，默认 unified）
- `docker compose -f docker-compose.moldinsight.yml up -d`
- `docker compose -f docker-compose.inventory.yml up -d`
- 或直接 [src/entrypoints/](../../../src/entrypoints/) 入口

而不是继续使用历史单体 `python src/main.py` 作为默认方式。

---

## 监控与维护

### 对象存储
- 检查对象存储服务可达性
- 定期清理历史产物
- 配置生命周期策略

### PostgreSQL
- 定期备份
- 监控连接池与慢查询
- 保持 Alembic 迁移链一致

---

## 故障排除

### 对象存储连接失败
- 检查 `RUSTFS_ENDPOINT`
- 检查 access key / secret key
- 检查服务端口与网络策略

### 数据库连接失败
- 检查 `DB_HOST` / `DB_PORT`
- 检查数据库账号密码
- 检查防火墙与白名单

### 文件上传失败
- 检查对象存储可用性
- 检查 Celery worker 是否运行
- 检查 Redis 是否可达