模块拆分 init

2026-08-27 14:53:22 +08:00
parent e6ddea33a2
commit 3ea59551db
15 changed files with 2191 additions and 1399 deletions
@@ -1,255 +1,154 @@
 # 存储架构说明

+> 本文档主要解释 geMoldInsight 的存储分层与数据流。其历史中的“本项目自行拉起 PostgreSQL / MinIO 并通过 `python src/main.py` 启动单体”的部分，**已不再代表当前默认部署方式**。
+
+当前默认部署前提是：
+
+- PostgreSQL 由服务器已有服务提供
+- Redis 由服务器已有服务提供
+- RustFS / MinIO 兼容对象存储由服务器已有服务提供
+- 项目自身只部署：`moldinsight` / `moldinsight-celery` / `inventory`
+
+如需查看当前部署方式，请优先参考：
+- [README.md](../README.md)
+- [LINUX_SETUP.md](./deployment/LINUX_SETUP.md)
+- [DEPLOY_PORT.md](./deployment/DEPLOY_PORT.md)
+- [BACKEND_MODULARIZATION_BLUEPRINT.md](./BACKEND_MODULARIZATION_BLUEPRINT.md)
+
+---
+
 ## 架构概述

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

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

-## PostgreSQL 数据表
+---
+
+## PostgreSQL 数据表（摘要）

 ### 用户管理
- `users` - 用户信息（用户名、邮箱、密码等）
+- `users` - 用户信息
+- `roles` / `permissions` - 权限体系

-### 文件管理
- `stp_files` - STP文件元数据（文件名、哈希、大小、状态等）
- `html_files` - HTML报告文件元数据
-
-### 几何数据
- `geometry_data` - 几何分析数据（体积、表面积、边界框等）
- `mold_cavity_data` - 模具型腔数据（工艺参数、质量评估等）
- `feature_detections` - 特征检测结果（壁厚、拔模角等）
- `design_recommendations` - 设计建议（优先级、参数等）
-
-### 任务和日志
+### gemold 相关
+- `stp_files` - STP 文件元数据
+- `html_files` - HTML 报告元数据
+- `geometry_data` - 几何分析数据
+- `mold_cavity_data` - 模具型腔数据
+- `feature_detections` - 特征检测结果
+- `design_recommendations` - 设计建议
 - `processing_tasks` - 处理任务记录
- `user_activities` - 用户活动日志
- `system_logs` - 系统日志
+- `analysis_metrics` - 分析指标

-## RustFS 存储桶
+### 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` | 用户文件 | 其他用户上传的文件 |
+|---|---|---|
+| `moldinsight-stp-files` | STP/STEP 文件 | 用户上传的原始 3D 模型 |
+| `moldinsight-geometry` | 几何结果 | 几何分析 JSON |
+| `moldinsight-mold-cavities` | 模具结果 | 模具设计 JSON |
+| `moldinsight-html` | HTML 报告 | 生成的 HTML 报告文件 |
+| `moldinsight-user-files` | 用户文件 | 其他附件/用户文件 |

-## 快速开始
+---

-### 1. 安装依赖
+## 当前推荐初始化方式
+
+### 1. 准备环境变量

 ```bash
-pip install -r requirements.txt
-```
-
-### 2. 启动 PostgreSQL
-
-使用 Docker Compose（推荐）：
-```bash
-docker-compose up -d postgres
-```
-
-或手动启动：
-```bash
-# 创建数据库
-createdb moldinsight
-
-# 运行数据库容器
-docker run -d \
-  --name postgres \
-  -e POSTGRES_DB=moldinsight \
-  -e POSTGRES_USER=moldinsight_user \
-  -e POSTGRES_PASSWORD=your_password \
-  -p 5432:5432 \
-  postgres:15
-```
-
-### 3. 启动 MinIO
-
-使用 Docker Compose（推荐）：
-```bash
-docker-compose up -d minio
-```
-
-或手动启动：
-```bash
-docker run -d \
-  --name minio \
-  -p 9000:9000 \
-  -p 9001:9001 \
-  -e MINIO_ROOT_USER=minioadmin \
-  -e MINIO_ROOT_PASSWORD=minioadmin \
-  minio/minio server /data --console-address ":9001"
-```
-
-### 4. 配置环境变量
-
-```bash
-# 复制示例配置
 cp .env.example .env
-
-# 编辑 .env 文件，修改数据库和MinIO配置
 nano .env
 ```

-### 5. 初始化数据库和存储
+确保以下变量指向**服务器上已存在的真实服务**：

-```bash
-# 初始化数据库
-python src/database/init_db.py
+```env
+DB_HOST=your-db-host
+DB_PORT=5432
+DB_NAME=moldinsight
+DB_USER=moldinsight
+DB_PASSWORD=change-me

-# 初始化MinIO存储
-python src/storage/init_storage.py
+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
 ```

-### 6. 启动服务
+### 2. 初始化数据库

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

-## 使用示例
+### 3. 启动项目服务

-### 保存STP文件
+当前推荐通过：
+- [docker-compose.yml](../docker-compose.yml)
+- 或 [src/entrypoints/](../src/entrypoints/)

-```python
-from services.storage_integration import storage_integration
-from database.database import db_manager
+而不是继续使用历史单体 `python src/main.py` 作为默认方式。

-async def upload_file(file_path: str):
-    async with db_manager.get_session() as session:
-        stp_file = await storage_integration.save_stp_file(
-            session=session,
-            file_path=Path(file_path),
-            original_filename="model.stp",
-            user_id=1
-        )
-        print(f"文件已保存，ID: {stp_file.id}")
-```
+---

-### 保存几何数据
+## 监控与维护

-```python
-async def save_geometry(stp_file_id: int, geometry_data: dict):
-    async with db_manager.get_session() as session:
-        geo_data = await storage_integration.save_geometry_data(
-            session=session,
-            stp_file_id=stp_file_id,
-            geometry_json=geometry_data,
-            analysis_method="pythonocc"
-        )
-        print(f"几何数据已保存，ID: {geo_data.id}")
-```
-
-### 获取文件数据
-
-```python
-async def get_file_data(stp_file_id: int):
-    async with db_manager.get_session() as session:
-        data = await storage_integration.get_stp_file_with_data(
-            session=session,
-            stp_file_id=stp_file_id
-        )
-        
-        # 访问几何数据
-        geometry = data['geometry_data']
-        print(f"体积: {geometry['volume']}")
-        print(f"表面积: {geometry['surface_area']}")
-        
-        # 访问模具型腔数据
-        cavity = data['mold_cavity_data']
-        print(f"模具材料: {cavity['mold_material']}")
-        
-        # 访问特征和建议
-        for feature in data['features']:
-            print(f"特征: {feature['feature_type']}")
-```
-
-## 数据清理策略
-
-### MinIO 对象存储
- 设置生命周期策略自动删除旧文件
- 示例：删除30天前的临时文件
+### 对象存储
+- 检查对象存储服务可达性
+- 定期清理历史产物
+- 配置生命周期策略

 ### PostgreSQL
- 定期清理已删除用户的记录
- 归档超过6个月的日志数据
+- 定期备份
+- 监控连接池与慢查询
+- 保持 Alembic 迁移链一致

-## 监控和维护
-
-### 检查存储使用情况
-```bash
-# MinIO控制台
-# http://localhost:9001
-# 用户名: minioadmin
-# 密码: minioadmin
-```
-
-### 数据库备份
-```bash
-# 备份数据库
-pg_dump -h localhost -U moldinsight_user moldinsight > backup.sql
-
-# 恢复数据库
-psql -h localhost -U moldinsight_user moldinsight < backup.sql
-```
-
-## 性能优化
-
-### PostgreSQL
- 创建适当的索引（已在模型中定义）
- 定期运行 VACUUM 和 ANALYZE
- 考虑使用连接池（已配置）
-
-### MinIO
- 启用缓存层
- 配置CDN分发静态文件
- 使用多区域复制
-
-## 安全建议
-
-1. **更改默认密码**：生产环境必须更改所有默认密码
-2. **启用TLS**：生产环境启用 HTTPS
-3. **访问控制**：配置适当的用户权限
-4. **数据加密**：敏感数据加密存储
-5. **定期备份**：设置自动备份策略
+---

 ## 故障排除

-### 连接MinIO失败
-```
-错误: 对象存储连接失败
-解决: 检查 MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY 配置
-```
+### 对象存储连接失败
+- 检查 `RUSTFS_ENDPOINT`
+- 检查 access key / secret key
+- 检查服务端口与网络策略

 ### 数据库连接失败
-```
-错误: 数据库连接失败
-解决: 检查 DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD 配置
-```
+- 检查 `DB_HOST` / `DB_PORT`
+- 检查数据库账号密码
+- 检查防火墙与白名单

 ### 文件上传失败
-```
-错误: STP文件上传失败
-解决: 检查磁盘空间、网络连接、MinIO权限
-```
+- 检查对象存储可用性
+- 检查 Celery worker 是否运行
+- 检查 Redis 是否可达