admin/momentry_studio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 添加 Tauri GUI 架构分析文档

Browse Source 
内容:
- 四大模块总览（Search, File Prep, Admin, File Mgmt）
- 每个模块的详细分析（组件、API、数据流、数据库）
- 模块间交互关系和依赖关系
- 已知问题和改进建议
- API 调用链示例
- 技术栈总结

四大模块:
1. Search - 多模式搜索 + 历史管理
2. File Prep/Processing - Pipeline 处理 + 状态追踪
3. Admin - 系统监控 + 配置管理
4. File Management - 文件上传/下载/移动

关键问题:
- 双 API 架构复杂度
- 状态同步不一致
- 缩略图缓存无淘汰策略
- Pipeline 进度轮询效率低
- Admin 配置无验证

改进建议:
- 短期: WebSocket 状态推送、LRU Cache、批量查询
- 中期: 统一 API Gateway、Resumable Upload
- 长期: IndexedDB、离线模式、插件系统
This commit is contained in:
Momentry Studio
2026-10-11 16:41:27 +08:00
parent 9f6939ecc7
commit e11ee429f1
1 changed files with 441 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

441
docs/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,441 @@
# Momentry Studio Tauri GUI 架构文档
**生成时间:** 2026-10-10
**版本:** v1.0.0
---
## 1. 四大模块总览
```
┌─────────────────────────────────────────────────────────────────────┐
│ Momentry Studio GUI │
│ (Vue 3 + TypeScript + Vite) │
└────────────────────────────┬────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐
│ Search Module │ │ File Prep/ │ │ Admin Module │ │ File Mgmt │
│ │ │ Processing │ │ │ │ Module │
│ SearchView │ │ LibraryView │ │ AdminView │ │ ClientView │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘ └──────┬───────┘
│ │ │ │
└──────────────────┼──────────────────┼──────────────────┘
│ │
┌──────────┴──────────┐ │
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│ Core API │ │ MarkBase API │ │ Local SQLite │
│ (localhost: │ │ (localhost: │ │ (demo.sqlite)│
│ 3002) │ │ 11438) │ │ │
└───────┬───────┘ └───────┬──────┘ └──────────────┘
│ │
│ /api/v1/* │ /api/v2/*
│ (Momentry Core) │ (MarkBase Core)
│ │
└────────────────────┼────────────────────┐
│ │
┌──────────┴──────────┐ │
│ Studio Proxy │ │
│ (localhost:8888) │ │
│ - v1/v2 gateway │ │
│ - API key inject │ │
│ - Face thumbnail │ │
│ - Search history │ │
│ - Bookmarks │ │
└─────────────────────┘ │
│
┌──────────────────────────────┘
│
┌───────────┴────────────┐
│ Tauri IPC Commands │
│ (19 Rust commands) │
│ - search_llm_smart │
│ - get_files │
│ - get_people │
│ - register_file │
│ - process_file │
│ - update_identity │
│ - get_thumbnail │
│ - etc. │
└────────────────────────┘
```
---
## 2. 模块详解
### 2.1 Search 模块
**职责:** 提供多模式搜索功能（Keyword, Semantic, Visual, Agent, People）
**前端组件:**
- `SearchView.vue` - 主搜索界面
- `VideoPlayer.vue` - 搜索结果播放
- `useSearchHistory.ts` - 搜索历史管理
- `useBookmarks.ts` - 书签管理
**API 端点:**
```typescript
// v1 端点 (Momentry Core API)
/api/v1/search/keyword // 关键字搜索
/api/v1/search/semantic // 语义搜索
/api/v1/search/llm-smart // LLM 智能搜索
/api/v1/search/people // 人物搜索
/api/v1/agents/search // Agent 搜索
/api/v1/search/vlm/scenes // Scene VLM 搜索
/api/v1/search/vlm/traces // Trace VLM 搜索
// v1 端点 (本地处理)
/api/v1/search-history // 搜索历史
/api/v1/bookmarks // 书签
```
**数据流:**
```
用户输入 → SearchView → apiCall() → Core API
↓
返回结果 → mergeResults() → 结果卡片
↓
History/Bookmarks → SQLite (demo.sqlite)
```
**数据库:**
- `search_history` (SQLite) - 搜索历史
- `bookmarks` (SQLite) - 书签
**关键特性:**
1. **多模式搜索:** Keyword, Semantic, Visual, Agent, People 五种模式
2. **OCR 合并:** 相似文本自动合并，减少重复
3. **搜索历史:** SQLite 持久化，支持 Pin/Rename/Delete
4. **书签系统:** 快速访问常用搜索
---
### 2.2 文件准备/处理模块
**职责:** 管理原始档案的处理流程，从注册到完成
**前端组件:**
- `LibraryView.vue` - 文件列表和处理控制
- `PeopleView.vue` - 人物管理
- `PersonDetailView.vue` - 人物详情
**API 端点:**
```typescript
// v1 端点
/api/v1/files/register // 注册文件
/api/v1/file/{uuid}/process // 处理文件
/api/v1/unregister // 注销文件
/api/v1/file/{uuid}/sync-status // 同步状态
/api/v1/progress/{uuid} // 处理进度
/api/v1/stats/pipeline/{uuid} // Pipeline 统计
/api/v1/stats/file/{uuid} // 文件统计
/api/v1/file/{uuid}/processor-counts // 处理器统计
/api/v1/re-scan // 重新扫描
```
**处理 Pipeline:**
```
Rule 1 Ingestion → Face Tracing → Face Dedup →
TKG Nodes → TKG Edges → Rule 2 Ingestion →
VLM Summary → Scene VLM
```
**状态机:**
```
registered → scanning → keyword_ready →
semantic_ready → face_mgmt_ready → agent_ready
```
**数据库:**
- `videos` (PostgreSQL) - 文件注册表
- `monitor_jobs` (PostgreSQL) - 处理任务
- `processor_status` (PostgreSQL) - 处理器状态
**关键特性:**
1. **状态追踪:** 6 个状态，实时更新
2. **进度监控:** Pipeline 进度 + 系统资源
3. **批量操作:** 批量注册、扫描、注销
4. **处理器控制:** 单独重跑 ASR/OCR/Face 等
---
### 2.3 Admin 监控及参数模块
**职责:** 系统监控、配置管理、服务控制
**前端组件:**
- `AdminView.vue` - 管理界面
**API 端点:**
```typescript
// v1 端点
/api/v1/health // 健康检查
/api/v1/system-stats/validate // 系统验证
/api/v1/admin/config // 系统配置
// v2 端点
/api/v2/admin/system-stats // 系统统计
/api/v2/admin/users // 用户列表
/api/v2/admin/shares // 共享列表
/api/v2/service/start // 启动服务
/api/v2/service/stop // 停止服务
```
**配置文件:**
```json
// admin_config.json
{
"vlm_prompts": {...},
"llm_config": {...},
"processor_config": {...},
"filter_config": {...},
"search": {...}
}
```
**关键特性:**
1. **系统监控:** CPU、内存、GPU、ANE 实时监控
2. **服务管理:** Core API、MarkBase、MBE、Proxy 启停
3. **配置编辑:** VLM Prompts、LLM、Processor、Filter 配置
4. **语言包管理:** 多语言支持
---
### 2.4 File Management 模块
**职责:** 原始档案的上传、下载、移动、删除
**前端组件:**
- `ClientView.vue` - 文件浏览器
**API 端点:**
```typescript
// v2 端点
/api/v2/myfiles/{user}/folders // 文件夹列表
/api/v2/myfiles/{user}/files // 文件列表
/api/v2/upload-unlimited/{user} // 上传文件
/api/v2/myfiles/{user}/preview/{filename} // 文件预览
/api/v2/myfiles/{user}/move // 移动文件
/api/v2/myfiles/{user}/tags // 标签管理
```
**数据库:**
- `files` (MarkBase PostgreSQL) - 文件元数据
- `folders` (MarkBase PostgreSQL) - 文件夹结构
**关键特性:**
1. **文件浏览器:** 文件夹导航、搜索、排序
2. **上传管理:** 多文件上传、进度显示
3. **文件操作:** 重命名、移动、删除
4. **预览功能:** 多格式预览
5. **拖拽支持:** 文件拖拽移动
---
## 3. 数据流图
### 3.1 搜索数据流
```
User Query → SearchView → apiCall()
↓
Core API (PostgreSQL + Qdrant + MongoDB)
↓
Results → VideoPlayer
↓
History/Bookmarks → SQLite
```
### 3.2 文件处理数据流
```
File Selection → register_file()
↓
videos (PostgreSQL) → Pipeline
↓
Processor Output (*.json) → Ingestion
↓
Status Update → LibraryView
```
### 3.3 Admin 配置数据流
```
Admin Edit → admin_config.json
↓
Service Control (MarkBase API)
Config Reload (Core API)
```
---
## 4. 模块间交互
### 4.1 依赖关系
```
Search Module
├──> File Management (缩略图、视频流)
├──> Admin Module (VLM 配置)
└──> Core API (搜索数据)
File Prep/Processing
├──> File Management (原始文件)
├──> Admin Module (处理器配置)
└──> Core API (Pipeline)
Admin Module
├──> Core API (配置)
├──> MarkBase API (服务控制)
└──> File Management (上传路径)
File Management
├──> Admin Module (用户权限)
└──> MarkBase API (文件存储)
```
### 4.2 数据共享
- **全局 Store:** `store.ts`
- `filesCache` - 文件列表
- `thumbnailsCache` - 缩略图
- `profilesCache` - 人物头像
- `pipelineStatsCache` - 处理进度
- **SQLite 共享:**
- `search_history` - Search 模块
- `bookmarks` - Search 模块
- `app_users` - Admin + File Management
---
## 5. 技术栈
| 层次 | 技术 | 用途 |
|-----|------|------|
| **前端框架** | Vue 3 + TypeScript + Vite | 响应式 UI |
| **桌面框架** | Tauri 2 | 原生桌面应用 |
| **路由** | Vue Router | SPA 路由 |
| **状态管理** | Pinia-like (store.ts) | 全局状态 |
| **API 层** | Dual-mode (IPC + HTTP) | 桌面/浏览器双模式 |
| **代理层** | Axum (Rust) | API Gateway |
| **数据库** | PostgreSQL + Qdrant + MongoDB | Core 数据存储 |
| **缓存** | Redis | 任务队列 |
| **本地存储** | SQLite (rusqlite) | 历史和书签 |
---
## 6. 已知问题
### 6.1 双 API 架构复杂度
- **问题:** `/api/v1/*` → Core API, `/api/v2/*` → MarkBase API，易混淆
- **影响:** 文档维护成本高，开发者需要记住命名空间
- **优先级:** 中
### 6.2 状态同步不一致
- **问题:** `fileStatusCache` 前端和 Core API 状态不同步
- **影响:** 用户看到的处理状态滞后
- **优先级:** 高
### 6.3 缩略图缓存无淘汰策略
- **问题:** 缩略图缓存无 LRU 淘汰，内存占用持续增长
- **影响:** 长时间使用后内存占用过高
- **优先级:** 中
### 6.4 Pipeline 进度轮询效率低
- **问题:** 每个文件独立轮询，并发处理时 API 压力大
- **影响:** 系统负载高
- **优先级:** 高
### 6.5 搜索历史功能受限
- **问题:** 限制 30 条，无全文搜索
- **影响:** 用户无法按时间/模式过滤历史
- **优先级:** 低
### 6.6 VideoPlayer 性能问题
- **问题:** 大视频加载慢，Seek 卡顿
- **影响:** 用户体验差
- **优先级:** 中
### 6.7 Admin 配置无验证
- **问题:** `admin_config.json` 编辑无前端验证
- **影响:** 可能保存错误配置导致服务崩溃
- **优先级:** 高
### 6.8 文件上传无断点续传
- **问题:** 大文件上传失败需重头开始
- **影响:** 网络不稳定时体验极差
- **优先级:** 中
---
## 7. 改进建议
### 7.1 短期（1-2 周）
1. ✅ 实现 WebSocket 状态推送，替代轮询
2. ✅ 增加 LRU Cache 用于缩略图
3. ✅ 增加批量状态查询 API
4. ✅ 实现 Admin 配置前端验证
### 7.2 中期（1-2 月）
1. 统一 API Gateway，简化双 API
2. 实现 Resumable Upload
3. 增强搜索历史功能
4. VideoPlayer 性能优化
### 7.3 长期（3-6 月）
1. 迁移到 IndexedDB 持久化
2. 实现离线模式
3. 增加插件系统
4. 实现多租户架构
---
## 8. API 调用链示例
### 8.1 搜索场景
```typescript
用户输入 "find red car"
↓
apiCall('search_llm_smart', {query: 'find red car'})
↓
[Tauri] invoke('search_llm_smart')
[Browser] httpCall → Proxy :8888 → Core API :3002
↓
Core API 查询 PostgreSQL + Qdrant
↓
返回 20 条结果
↓
前端加载缩略图 → 显示卡片
```
### 8.2 文件处理场景
```typescript
用户选择文件 → register_file()
↓
Core API 创建 videos 记录 + monitor_job
↓
process_file() → 触发 Pipeline
↓
pollPipelineProgress() → 显示进度条
↓
Pipeline 完成 → 状态更新为 'agent_ready'
```
---
## 9. 总结
Momentry Studio 是一个复杂的 Tauri GUI 应用，集成了四大核心模块：
1. **Search** - 多模式搜索 + 历史管理
2. **File Prep/Processing** - Pipeline 处理 + 状态追踪
3. **Admin** - 系统监控 + 配置管理
4. **File Management** - 文件上传/下载/移动
通过双 API 架构（Core API + MarkBase API）实现了功能解耦，但也增加了维护成本。当前主要问题集中在状态同步、性能优化和用户体验改进。
---
**最后更新:** 2026-10-10
**维护者:** Momentry Studio Team