文档目录结构简洁化

2026-09-01 18:05:18 +08:00
parent bee439cf34
commit 5e531ffe1e
47 changed files with 1334 additions and 3380 deletions
@@ -0,0 +1,467 @@
+# RustFS 对象存储集成说明
+
+> 文档定位：**RustFS / 对象存储集成的专题说明文档**。
+> 本文解释对象存储侧的接口与集成思路，不作为当前部署入口文档。当前部署方式见 [../../DEPLOYMENT.md](../../DEPLOYMENT.md) 与 [../../deployment/LINUX_SETUP.md](../../deployment/LINUX_SETUP.md)，当前状态见 [../../STATUS.md](../../STATUS.md)。
+## 架构概述
+
+本项目采用 **RustFS** 作为对象存储和 **PostgreSQL** 作为元数据存储的双层存储架构。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     应用层 (FastAPI)                    │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+        ┌──────────────┴──────────────┐
+        │                              │
+┌───────▼────────┐        ┌─────────▼─────────┐
+│   PostgreSQL    │        │     RustFS        │
+│   (元数据)      │        │   (对象存储)       │
+│                │        │                   │
+│ - users        │        │ - stp-files      │
+│ - stp_files    │        │ - geometry       │
+│ - geometry_data│        │ - mold-cavities │
+│ - mold_cavity  │        │ - html-files     │
+│ - features     │        │ - user-files     │
+│ - logs        │        │                   │
+└────────────────┘        └──────────────────┘
+```
+
+## RustFS API 端点
+
+假设 RustFS 运行在 `http://localhost:8080`，需要实现以下 REST API：
+
+### 1. 健康检查
+```
+GET /health
+返回: 200 OK
+```
+
+### 2. 初始化上传
+```
+POST /api/v1/upload/init
+Content-Type: application/json
+Authorization: Bearer <api_key>
+
+请求体:
+{
+  "namespace": "moldinsight/stp-files",
+  "key": "stp-files/abc123.stp",
+  "file_size": 1234567,
+  "file_hash": "sha256_hash",
+  "metadata": {
+    "original_filename": "model.stp",
+    "user_id": "1"
+  }
+}
+
+响应:
+{
+  "upload_id": "unique-upload-id",
+  "upload_url": "https://rustfs/upload/xyz",
+  "expires_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### 3. 上传文件内容
+```
+PUT <upload_url>
+Content-Type: application/octet-stream
+Content-Length: 1234567
+X-File-Hash: sha256_hash
+
+请求体: <文件二进制数据>
+
+响应: 201 Created
+```
+
+### 4. 完成上传
+```
+POST /api/v1/upload/complete
+Content-Type: application/json
+Authorization: Bearer <api_key>
+
+请求体:
+{
+  "upload_id": "unique-upload-id",
+  "namespace": "moldinsight/stp-files",
+  "key": "stp-files/abc123.stp"
+}
+
+响应:
+{
+  "object_key": "moldinsight/stp-files/abc123.stp",
+  "etag": "d41d8cd98f00b204e9800998ecf8427e",
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### 5. 上传 JSON（小文件，直接上传）
+```
+PUT /api/v1/objects/<namespace>/<key>
+Content-Type: application/json
+Authorization: Bearer <api_key>
+X-File-Hash: sha256_hash
+
+请求体: <JSON字符串>
+
+响应: 201 Created
+{
+  "object_key": "moldinsight/geometry/abc123.json",
+  "etag": "d41d8cd98f00b204e9800998ecf8427e",
+  "created_at": "2024-01-01T00:00:00Z"
+}
+```
+
+### 6. 下载文件
+```
+GET /api/v1/objects/<namespace>/<key>
+Authorization: Bearer <api_key>
+
+响应: <文件二进制数据>
+Content-Type: <原上传时的内容类型>
+Content-Length: <文件大小>
+ETag: <文件etag>
+```
+
+### 7. 获取文件信息
+```
+GET /api/v1/objects/<namespace>/<key>/info
+Authorization: Bearer <api_key>
+
+响应:
+{
+  "object_key": "moldinsight/stp-files/abc123.stp",
+  "namespace": "moldinsight/stp-files",
+  "file_size": 1234567,
+  "file_hash": "sha256_hash",
+  "content_type": "application/octet-stream",
+  "created_at": "2024-01-01T00:00:00Z",
+  "last_modified": "2024-01-01T00:00:00Z",
+  "metadata": {
+    "original_filename": "model.stp",
+    "user_id": "1"
+  }
+}
+```
+
+### 8. 删除文件
+```
+DELETE /api/v1/objects/<namespace>/<key>
+Authorization: Bearer <api_key>
+
+响应: 204 No Content
+```
+
+### 9. 列出文件
+```
+GET /api/v1/buckets/<namespace>/objects?prefix=stp-files
+Authorization: Bearer <api_key>
+
+响应:
+{
+  "namespace": "moldinsight/stp-files",
+  "prefix": "stp-files",
+  "objects": [
+    {
+      "object_key": "moldinsight/stp-files/abc123.stp",
+      "file_size": 1234567,
+      "file_hash": "sha256_hash",
+      "created_at": "2024-01-01T00:00:00Z"
+    },
+    ...
+  ],
+  "is_truncated": false,
+  "next_marker": null
+}
+```
+
+### 10. 生成预签名 URL
+```
+POST /api/v1/presigned-url
+Content-Type: application/json
+Authorization: Bearer <api_key>
+
+请求体:
+{
+  "namespace": "moldinsight/stp-files",
+  "key": "stp-files/abc123.stp",
+  "expires": 3600,
+  "method": "GET"
+}
+
+响应:
+{
+  "url": "https://rustfs/objects/moldinsight/stp-files/abc123.stp?signature=xyz&expires=123",
+  "expires_at": "2024-01-01T01:00:00Z"
+}
+```
+
+### 11. 存储统计
+```
+GET /api/v1/stats
+Authorization: Bearer <api_key>
+
+响应:
+{
+  "total_objects": 1234,
+  "total_size": 1234567890,
+  "namespace_stats": {
+    "moldinsight/stp-files": {
+      "object_count": 100,
+      "total_size": 123456789
+    },
+    "moldinsight/geometry": {
+      "object_count": 200,
+      "total_size": 234567890
+    },
+    ...
+  }
+}
+```
+
+## 存储桶（命名空间）
+
+| 命名空间 | 用途 | 存储内容 |
+|---------|------|---------|
+| `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
+
+# 编辑 .env 文件
+nano .env
+```
+
+设置 RustFS 相关配置：
+```env
+RUSTFS_ENDPOINT=http://localhost:8080
+RUSTFS_API_KEY=your-rustfs-api-key
+RUSTFS_TIMEOUT=30
+RUSTFS_PRESIGNED_URL_EXPIRES=3600
+```
+
+### 2. 启动 RustFS 服务
+
+假设你已经有 RustFS 服务，如果没有，可以按照以下方式启动：
+
+```bash
+# 使用 Docker（如果提供了 Docker 镜像）
+docker run -d \
+  --name rustfs \
+  -p 8080:8080 \
+  -e RUSTFS_API_KEY=your-rustfs-api-key \
+  -e RUSTFS_STORAGE_PATH=/data \
+  -v rustfs_data:/data \
+  your-registry/rustfs:latest
+
+# 或直接运行编译好的二进制文件
+./rustfs-server --port 8080 --api-key your-rustfs-api-key --storage-path ./rustfs-data
+```
+
+### 3. 初始化存储
+
+```bash
+# 初始化 RustFS 连接
+python src/storage/init_storage.py
+```
+
+### 4. 使用存储集成服务
+
+```python
+from services.storage_integration_rustfs import storage_integration
+from database.database import db_manager
+
+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"文件已保存到 RustFS，ID: {stp_file.id}")
+```
+
+## Python 客户端使用
+
+### 上传文件
+
+```python
+from storage.rustfs_storage import rustfs_manager
+from pathlib import Path
+
+# 先连接
+await rustfs_manager.connect(
+    endpoint="http://localhost:8080",
+    api_key="your-api-key"
+)
+
+# 上传 STP 文件
+result = await rustfs_manager.upload_file(
+    bucket_type='stp_files',
+    file_path=Path('model.stp'),
+    original_filename='model.stp'
+)
+print(f"上传成功: {result['object_key']}")
+```
+
+### 上传 JSON 数据
+
+```python
+geometry_data = {
+    "volume": 5061079.99,
+    "surface_area": 640037.28,
+    "bounding_box": {...}
+}
+
+result = await rustfs_manager.upload_json_data(
+    bucket_type='geometry_data',
+    json_data=geometry_data,
+    file_hash='sha256-hash'
+)
+print(f"JSON 上传成功: {result['object_key']}")
+```
+
+### 下载文件
+
+```python
+data = await rustfs_manager.download_file(
+    bucket_type='geometry_data',
+    object_key='geometry_data/abc123.json'
+)
+json_data = json.loads(data.decode('utf-8'))
+print(json_data)
+```
+
+### 生成预签名 URL
+
+```python
+url = await rustfs_manager.generate_presigned_url(
+    bucket_type='stp_files',
+    object_key='stp-files/abc123.stp',
+    expires=3600  # 1小时
+)
+print(f"临时访问链接: {url}")
+```
+
+### 列出文件
+
+```python
+files = await rustfs_manager.list_files(
+    bucket_type='stp_files',
+    prefix='stp-files'
+)
+for f in files:
+    print(f"{f['object_key']}: {f['file_size']} bytes")
+```
+
+## RustFS 服务端实现参考
+
+如果你需要实现 RustFS 服务端，以下是一个简单的 Rust 实现框架：
+
+```rust
+use actix_web::{web, App, HttpServer};
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+#[derive(Deserialize)]
+struct UploadInitRequest {
+    namespace: String,
+    key: String,
+    file_size: u64,
+    file_hash: String,
+    metadata: Option<serde_json::Value>,
+}
+
+#[derive(Serialize)]
+struct UploadInitResponse {
+    upload_id: String,
+    upload_url: String,
+    expires_at: String,
+}
+
+async fn upload_init(
+    req: web::Json<UploadInitRequest>,
+    path: web::Data<PathBuf>
+) -> impl web::Responder {
+    // 验证 API Key
+    // 生成 upload_id
+    // 返回上传 URL
+    web::Json(UploadInitResponse { ... })
+}
+
+#[actix_web::main]
+async fn main() -> std::io::Result<()> {
+    HttpServer::new(|| {
+        App::new()
+            .route("/health", web::get().to(health_check))
+            .route("/api/v1/upload/init", web::post().to(upload_init))
+            // ... 其他路由
+    })
+    .bind("0.0.0.0:8080")?
+    .run()
+    .await
+}
+```
+
+## 故障排除
+
+### 连接 RustFS 失败
+```
+错误: RustFS 连接失败
+解决:
+1. 检查 RUSTFS_ENDPOINT 是否正确
+2. 检查 RustFS 服务是否运行
+3. 检查网络连接
+4. 验证 API Key
+```
+
+### 文件上传失败
+```
+错误: RustFS 上传失败
+解决:
+1. 检查磁盘空间
+2. 检查网络连接
+3. 检查文件大小限制
+4. 查看服务端日志
+```
+
+### 预签名 URL 失败
+```
+错误: RustFS 生成预签名URL失败
+解决:
+1. 检查 expires 参数是否有效
+2. 确认服务端支持预签名 URL
+3. 检查权限配置
+```
+
+## 性能优化建议
+
+### 客户端
+- 使用连接池（aiohttp 默认支持）
+- 实现上传重试机制
+- 对大文件使用分片上传
+- 并行上传多个小文件
+
+### 服务端
+- 实现缓存层
+- 支持范围请求（断点续传）
+- 压缩存储
+- CDN 分发静态文件
+
+## 安全建议
+
+1. **更改默认 API Key**：生产环境必须使用强密钥
+2. **启用 HTTPS**：生产环境使用 TLS
+3. **访问控制**：配置命名空间权限
+4. **数据加密**：敏感数据加密存储
+5. **日志监控**：记录所有访问和操作
@@ -0,0 +1,156 @@
+# 存储架构说明
+
+> 文档定位：**存储分层与数据流的专题说明文档**。
+> 本文主要解释 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
+┌─────────────────────────────────────────────────────────────┐
+│                  应用层 (gemold / inventory)                │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+        ┌──────────────┴──────────────┐
+        │                              │
+┌───────▼────────┐        ┌─────────▼─────────┐
+│   PostgreSQL    │        │     RustFS / S3   │
+│   (元数据)      │        │   (对象存储)       │
+│                │        │                  │
+│ - users        │        │ - stp-files      │
+│ - stp_files    │        │ - geometry       │
+│ - geometry_data│        │ - mold-cavities │
+│ - processing   │        │ - html-files     │
+│ - logs         │        │ - user-files     │
+└────────────────┘        └──────────────────┘
+```
+
+---
+
+## PostgreSQL 数据表（摘要）
+
+### 用户管理
+- `users` - 用户信息
+- `roles` / `permissions` - 权限体系
+
+### gemold 相关
+- `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. 启动项目服务
+
+当前推荐通过：
+- [docker-compose.yml](../../../docker-compose.yml)
+- 或 [src/entrypoints/](../../../src/entrypoints/)
+
+而不是继续使用历史单体 `python src/main.py` 作为默认方式。
+
+---
+
+## 监控与维护
+
+### 对象存储
+- 检查对象存储服务可达性
+- 定期清理历史产物
+- 配置生命周期策略
+
+### PostgreSQL
+- 定期备份
+- 监控连接池与慢查询
+- 保持 Alembic 迁移链一致
+
+---
+
+## 故障排除
+
+### 对象存储连接失败
+- 检查 `RUSTFS_ENDPOINT`
+- 检查 access key / secret key
+- 检查服务端口与网络策略
+
+### 数据库连接失败
+- 检查 `DB_HOST` / `DB_PORT`
+- 检查数据库账号密码
+- 检查防火墙与白名单
+
+### 文件上传失败
+- 检查对象存储可用性
+- 检查 Celery worker 是否运行
+- 检查 Redis 是否可达