fix: 统一存储
This commit is contained in:
root
@@ -1,9 +1,438 @@
|
||||
# 架构设计
|
||||
# Python Core 架构设计
|
||||
|
||||
## 硬性要求
|
||||
- 将所有功能集成到命令行触发
|
||||
- 所有命令行功能 都是基于 JSON RPC Progress 带进度条反馈的命令
|
||||
- 所有命令行依赖的功能 后期要迁移到api 要支持无痛切换
|
||||
## 🎯 硬性要求
|
||||
- ✅ **命令行集成** - 将所有功能集成到命令行触发
|
||||
- ✅ **进度反馈** - 所有命令行功能都基于 JSON RPC Progress 带进度条反馈
|
||||
- ✅ **API迁移** - 所有命令行依赖的功能后期要迁移到API，支持无痛切换
|
||||
|
||||
## 存储设计
|
||||
- 支持多种存储方式切换，当前存储在json文件，后期可以方便的更改为数据库/mongo等
|
||||
## 💾 存储设计
|
||||
- ✅ **多存储支持** - 支持多种存储方式切换
|
||||
- ✅ **当前实现** - 存储在JSON文件
|
||||
- ✅ **未来扩展** - 可方便切换为数据库/MongoDB等
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 整体架构
|
||||
|
||||
### **分层架构设计**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CLI Layer (命令行层) │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ MediaManager │ │ SceneDetection │ │ TemplateManager │ │
|
||||
│ │ Commander │ │ Commander │ │ Commander │ │
|
||||
│ │ (进度条) │ │ (进度条) │ │ (进度条) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Service Layer (服务层) │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ MediaManager │ │ SceneDetection │ │ TemplateManager │ │
|
||||
│ │ Service │ │ Service │ │ Service │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Storage Layer (存储层) │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ JSON Storage │ │ Database │ │ MongoDB │ │
|
||||
│ │ (当前) │ │ Storage │ │ Storage │ │
|
||||
│ │ │ │ (未来) │ │ (未来) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Utils Layer (工具层) │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Progress │ │ Logger │ │ Config │ │
|
||||
│ │ Commander │ │ Utils │ │ Manager │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### **核心设计原则**
|
||||
|
||||
#### **1. 命令行优先 (CLI-First)**
|
||||
- 🎯 所有功能都通过命令行暴露
|
||||
- 📊 统一的进度反馈机制
|
||||
- 🔧 标准化的参数处理
|
||||
|
||||
#### **2. 服务分离 (Service Separation)**
|
||||
- 🧩 业务逻辑与CLI分离
|
||||
- 🔌 服务可独立测试和复用
|
||||
- 📦 清晰的接口定义
|
||||
|
||||
#### **3. 存储抽象 (Storage Abstraction)**
|
||||
- 💾 存储接口标准化
|
||||
- 🔄 多种存储实现
|
||||
- 🚀 无缝切换能力
|
||||
|
||||
#### **4. 进度统一 (Progress Unified)**
|
||||
- 📈 JSON-RPC 2.0 进度协议
|
||||
- ⏱️ 实时进度反馈
|
||||
- 📊 统一的进度管理
|
||||
|
||||
---
|
||||
|
||||
## 📁 目录结构设计
|
||||
|
||||
```
|
||||
python_core/
|
||||
├── services/ # 服务层
|
||||
│ ├── media_manager/ # 媒体管理服务
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── types.py # 数据类型
|
||||
│ │ ├── storage.py # 存储接口
|
||||
│ │ ├── manager.py # 业务逻辑
|
||||
│ │ └── cli.py # 命令行接口
|
||||
│ ├── scene_detection/ # 场景检测服务
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── types.py
|
||||
│ │ ├── detector.py
|
||||
│ │ └── cli.py
|
||||
│ └── template_manager/ # 模板管理服务
|
||||
│ ├── __init__.py
|
||||
│ ├── types.py
|
||||
│ ├── manager.py
|
||||
│ └── cli.py
|
||||
├── storage/ # 存储层
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py # 存储基类
|
||||
│ ├── json_storage.py # JSON存储实现
|
||||
│ ├── database_storage.py # 数据库存储实现
|
||||
│ └── mongo_storage.py # MongoDB存储实现
|
||||
├── utils/ # 工具层
|
||||
│ ├── __init__.py
|
||||
│ ├── commander/ # 命令行工具
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── base.py
|
||||
│ ├── progress/ # 进度管理
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── commander.py
|
||||
│ │ └── reporter.py
|
||||
│ ├── logger.py # 日志工具
|
||||
│ └── config.py # 配置管理
|
||||
├── config.py # 全局配置
|
||||
└── readme.md # 架构文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 核心组件设计
|
||||
|
||||
### **1. 进度命令基类**
|
||||
```python
|
||||
class ProgressJSONRPCCommander(ABC):
|
||||
"""带进度的JSON-RPC命令基类"""
|
||||
|
||||
def _is_progressive_command(self, command: str) -> bool:
|
||||
"""判断是否需要进度报告"""
|
||||
pass
|
||||
|
||||
def _execute_with_progress(self, command: str, args: dict) -> Any:
|
||||
"""执行带进度的命令"""
|
||||
pass
|
||||
|
||||
def _execute_simple_command(self, command: str, args: dict) -> Any:
|
||||
"""执行简单命令"""
|
||||
pass
|
||||
|
||||
def create_task(self, name: str, total: int):
|
||||
"""创建进度任务"""
|
||||
pass
|
||||
```
|
||||
|
||||
### **2. 存储抽象接口**
|
||||
```python
|
||||
class StorageInterface(ABC):
|
||||
"""存储接口基类"""
|
||||
|
||||
@abstractmethod
|
||||
def save(self, key: str, data: Any) -> bool:
|
||||
"""保存数据"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def load(self, key: str) -> Any:
|
||||
"""加载数据"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def delete(self, key: str) -> bool:
|
||||
"""删除数据"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def exists(self, key: str) -> bool:
|
||||
"""检查数据是否存在"""
|
||||
pass
|
||||
```
|
||||
|
||||
### **3. 服务基类**
|
||||
```python
|
||||
class ServiceBase(ABC):
|
||||
"""服务基类"""
|
||||
|
||||
def __init__(self, storage: StorageInterface):
|
||||
self.storage = storage
|
||||
|
||||
@abstractmethod
|
||||
def get_service_name(self) -> str:
|
||||
"""获取服务名称"""
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 实现策略
|
||||
|
||||
### **阶段1: 当前实现 (JSON存储)**
|
||||
- ✅ **JSON文件存储** - 简单、快速、易调试
|
||||
- ✅ **进度命令行** - 统一的进度反馈
|
||||
- ✅ **模块化服务** - 清晰的服务分离
|
||||
|
||||
### **阶段2: 存储扩展**
|
||||
- 🔄 **数据库支持** - SQLite/PostgreSQL/MySQL
|
||||
- 🔄 **NoSQL支持** - MongoDB/Redis
|
||||
- 🔄 **云存储支持** - AWS S3/阿里云OSS
|
||||
|
||||
### **阶段3: API化**
|
||||
- 🌐 **REST API** - 标准HTTP接口
|
||||
- 📡 **WebSocket** - 实时进度推送
|
||||
- 🔌 **GraphQL** - 灵活的数据查询
|
||||
|
||||
### **阶段4: 微服务化**
|
||||
- 🐳 **容器化** - Docker部署
|
||||
- ⚖️ **负载均衡** - 高可用架构
|
||||
- 📊 **监控告警** - 完整的运维体系
|
||||
|
||||
---
|
||||
|
||||
## 📊 进度协议设计
|
||||
|
||||
### **JSON-RPC 2.0 进度协议**
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "progress",
|
||||
"params": {
|
||||
"step": "service_name",
|
||||
"progress": 0.65,
|
||||
"message": "处理中: 文件名 (3/5)",
|
||||
"timestamp": 1752242302.647,
|
||||
"details": {
|
||||
"current": 3,
|
||||
"total": 5,
|
||||
"elapsed_time": 2.5,
|
||||
"estimated_remaining": 1.2,
|
||||
"throughput": "1.2 files/sec"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **进度状态管理**
|
||||
```python
|
||||
class ProgressTask:
|
||||
"""进度任务管理"""
|
||||
|
||||
def __init__(self, name: str, total: int):
|
||||
self.name = name
|
||||
self.total = total
|
||||
self.current = 0
|
||||
self.start_time = time.time()
|
||||
|
||||
def update(self, current: int = None, message: str = None):
|
||||
"""更新进度"""
|
||||
pass
|
||||
|
||||
def finish(self, message: str = "任务完成"):
|
||||
"""完成任务"""
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 API迁移设计
|
||||
|
||||
### **无痛切换策略**
|
||||
|
||||
#### **1. 接口标准化**
|
||||
```python
|
||||
# 命令行接口
|
||||
def execute_command(command: str, args: dict) -> dict:
|
||||
"""执行命令"""
|
||||
pass
|
||||
|
||||
# API接口 (未来)
|
||||
@app.post("/api/v1/{service}/{command}")
|
||||
async def api_execute_command(service: str, command: str, args: dict) -> dict:
|
||||
"""API执行命令"""
|
||||
# 直接调用相同的服务逻辑
|
||||
return service_instance.execute_command(command, args)
|
||||
```
|
||||
|
||||
#### **2. 进度推送**
|
||||
```python
|
||||
# 命令行进度 (当前)
|
||||
def progress_callback(progress_data: dict):
|
||||
print(json.dumps(progress_data))
|
||||
|
||||
# WebSocket进度 (未来)
|
||||
async def websocket_progress(websocket: WebSocket, progress_data: dict):
|
||||
await websocket.send_json(progress_data)
|
||||
```
|
||||
|
||||
#### **3. 配置统一**
|
||||
```python
|
||||
class Config:
|
||||
"""统一配置管理"""
|
||||
|
||||
# 存储配置
|
||||
STORAGE_TYPE = "json" # json/database/mongodb
|
||||
STORAGE_PATH = "data/"
|
||||
|
||||
# API配置
|
||||
API_ENABLED = False
|
||||
API_HOST = "0.0.0.0"
|
||||
API_PORT = 8000
|
||||
|
||||
# 进度配置
|
||||
PROGRESS_ENABLED = True
|
||||
PROGRESS_WEBSOCKET = False
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 扩展性设计
|
||||
|
||||
### **1. 插件化架构**
|
||||
```python
|
||||
class PluginManager:
|
||||
"""插件管理器"""
|
||||
|
||||
def register_service(self, service_class: Type[ServiceBase]):
|
||||
"""注册服务"""
|
||||
pass
|
||||
|
||||
def register_storage(self, storage_class: Type[StorageInterface]):
|
||||
"""注册存储"""
|
||||
pass
|
||||
|
||||
def register_commander(self, commander_class: Type[ProgressJSONRPCCommander]):
|
||||
"""注册命令行"""
|
||||
pass
|
||||
```
|
||||
|
||||
### **2. 配置驱动**
|
||||
```yaml
|
||||
# config.yaml
|
||||
services:
|
||||
media_manager:
|
||||
enabled: true
|
||||
storage: json
|
||||
|
||||
scene_detection:
|
||||
enabled: true
|
||||
storage: json
|
||||
|
||||
storage:
|
||||
json:
|
||||
path: "./data"
|
||||
|
||||
database:
|
||||
url: "postgresql://user:pass@localhost/db"
|
||||
|
||||
mongodb:
|
||||
url: "mongodb://localhost:27017/db"
|
||||
|
||||
api:
|
||||
enabled: false
|
||||
host: "0.0.0.0"
|
||||
port: 8000
|
||||
```
|
||||
|
||||
### **3. 监控和日志**
|
||||
```python
|
||||
class ServiceMonitor:
|
||||
"""服务监控"""
|
||||
|
||||
def track_command_execution(self, service: str, command: str, duration: float):
|
||||
"""跟踪命令执行"""
|
||||
pass
|
||||
|
||||
def track_progress(self, service: str, progress: float):
|
||||
"""跟踪进度"""
|
||||
pass
|
||||
|
||||
def track_error(self, service: str, error: Exception):
|
||||
"""跟踪错误"""
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用示例
|
||||
|
||||
### **当前使用方式 (命令行)**
|
||||
```bash
|
||||
# 媒体管理
|
||||
python -m python_core.services.media_manager upload video.mp4
|
||||
|
||||
# 场景检测
|
||||
python -m python_core.services.scene_detection batch_detect /videos
|
||||
|
||||
# 模板管理
|
||||
python -m python_core.services.template_manager import /templates
|
||||
```
|
||||
|
||||
### **未来使用方式 (API)**
|
||||
```bash
|
||||
# REST API
|
||||
curl -X POST http://localhost:8000/api/v1/media_manager/upload \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"video_path": "video.mp4"}'
|
||||
|
||||
# WebSocket进度
|
||||
ws://localhost:8000/ws/progress
|
||||
```
|
||||
|
||||
### **混合使用**
|
||||
```python
|
||||
# 程序化调用
|
||||
from python_core.services.media_manager import MediaManagerService
|
||||
|
||||
service = MediaManagerService()
|
||||
result = service.upload_video("video.mp4")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎉 架构优势
|
||||
|
||||
### **1. 统一性**
|
||||
- 🎯 **命令行优先** - 所有功能都可通过CLI访问
|
||||
- 📊 **进度统一** - 统一的进度反馈机制
|
||||
- 🔧 **接口标准** - 标准化的服务接口
|
||||
|
||||
### **2. 可扩展性**
|
||||
- 🔌 **插件化** - 易于添加新服务
|
||||
- 💾 **存储灵活** - 支持多种存储后端
|
||||
- 🌐 **API就绪** - 无痛迁移到API
|
||||
|
||||
### **3. 可维护性**
|
||||
- 🧩 **模块化** - 清晰的模块分离
|
||||
- 📝 **文档完整** - 详细的架构文档
|
||||
- 🧪 **测试友好** - 易于单元测试
|
||||
|
||||
### **4. 用户友好**
|
||||
- 📊 **进度可视** - 实时进度反馈
|
||||
- 🔧 **配置灵活** - 丰富的配置选项
|
||||
- 📄 **输出多样** - 多种输出格式
|
||||
|
||||
这个架构设计完全满足您的硬性要求，提供了从当前JSON存储到未来API化的完整迁移路径！
|
||||
- 文件存储 当前是存储到本地 后续会存储到远程 需要无痛切换
|
||||
Reference in New Issue
Block a user