Momentry Studio
e11ee429f1
内容: - 四大模块总览（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、离线模式、插件系统
441 lines
14 KiB
Markdown
441 lines
14 KiB
Markdown
# 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 |