mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-20 23:54:26 +08:00
364 lines
11 KiB
Markdown
364 lines
11 KiB
Markdown
# 整体架构
|
||
|
||
本文档描述阑山桌面的整体技术架构、各模块职责和交互方式。
|
||
|
||
## 架构概览
|
||
|
||
### 核心模块
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户交互层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │桌面组件 │ │主窗口 │ │托盘图标 │ │设置窗口 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ LanMountainDesktop（桌面宿主） │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ 组件系统 │ │
|
||
│ │ 组件注册 | 组件渲染 | 布局管理 | 编辑模式 │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ 插件运行时 │ │
|
||
│ │ 插件加载 | 生命周期 | SDK 接入 | 契约装配 │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ 核心服务层 │ │
|
||
│ │ 设置 | 主题 | 本地化 | 日志 | 遥测 | IPC │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓ ↓
|
||
┌──────────────────────┐ ┌──────────────────────────────┐
|
||
│ LanMountainDesktop │ │ LanMountainDesktop │
|
||
│ .AirAppRuntime │←IPC→│ .AirAppHost (多实例) │
|
||
│ Air APP 运行时容器 │ │ Air APP 渲染进程 │
|
||
└──────────────────────┘ └──────────────────────────────┘
|
||
↑
|
||
┌──────────────────────┐
|
||
│ LanMountainDesktop │
|
||
│ .Launcher │
|
||
│ 启动器 (唯一入口) │
|
||
└──────────────────────┘
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
### 核心项目
|
||
|
||
| 项目 | 职责 | 类型 |
|
||
|------|------|------|
|
||
| **LanMountainDesktop** | 桌面宿主主程序 | WPF 应用 |
|
||
| **LanMountainDesktop.Launcher** | 启动器（OOBE、Splash、版本管理） | 独立可执行 |
|
||
| **LanMountainDesktop.AirAppRuntime** | Air APP 运行时容器 | 独立服务 |
|
||
| **LanMountainDesktop.AirAppHost** | Air APP 渲染进程 | 框架依赖应用 |
|
||
|
||
### SDK 和基础设施
|
||
|
||
| 项目 | 职责 | 类型 |
|
||
|------|------|------|
|
||
| **LanMountainDesktop.PluginSdk** | 插件 SDK | NuGet 包 |
|
||
| **LanMountainDesktop.AirAppSdk** | Air APP SDK | NuGet 包 |
|
||
| **LanMountainDesktop.Shared.Contracts** | 共享契约类型 | 类库 |
|
||
| **LanMountainDesktop.Shared.IPC** | IPC 基础设施 | 类库 |
|
||
|
||
### 功能模块
|
||
|
||
| 项目 | 职责 | 类型 |
|
||
|------|------|------|
|
||
| **LanMountainDesktop.Settings.Core** | 设置系统 | 类库 |
|
||
| **LanMountainDesktop.Appearance** | 主题和外观 | 类库 |
|
||
| **LanMountainDesktop.DesktopComponents.Runtime** | 组件运行时 | 类库 |
|
||
| **LanMountainDesktop.DesktopHost** | 桌面宿主生命周期 | 类库 |
|
||
|
||
### 未来扩展（计划中）
|
||
|
||
| 项目 | 职责 | 状态 |
|
||
|------|------|------|
|
||
| **LanMountainDesktop.PluginIsolation.Contracts** | 插件隔离契约 | 已创建 |
|
||
| **LanMountainDesktop.PluginIsolation.Ipc** | 插件隔离 IPC | 已创建 |
|
||
|
||
## 启动流程
|
||
|
||
### 生产环境启动
|
||
|
||
```
|
||
1. 用户启动 Launcher.exe
|
||
↓
|
||
2. 首次启动？ → 是 → 显示 OOBE 欢迎页
|
||
↓ 否
|
||
3. 显示 Splash 启动动画
|
||
↓
|
||
4. 扫描 app-* 目录，选择最佳版本
|
||
- 优先选择有 .current 标记的
|
||
- 其次选择版本号最高的
|
||
- 跳过有 .partial 或 .destroy 标记的
|
||
↓
|
||
5. 预启动 AirAppRuntime.exe
|
||
- JIT 框架依赖进程
|
||
- 等待 IPC 管道就绪
|
||
↓
|
||
6. 启动 app-{version}/LanMountainDesktop.exe
|
||
↓
|
||
7. Host 初始化
|
||
- 日志系统
|
||
- 遥测系统
|
||
- 设置加载
|
||
- 主题应用
|
||
↓
|
||
8. 初始化桌面环境
|
||
- 创建桌面窗口
|
||
- 加载插件
|
||
- 注册组件
|
||
- 显示托盘图标
|
||
↓
|
||
9. 将 Host PID 附加给 AirAppRuntime
|
||
↓
|
||
10. 清理标记为 .destroy 的旧版本
|
||
↓
|
||
11. 桌面就绪
|
||
```
|
||
|
||
### 开发环境启动
|
||
|
||
```
|
||
开发者直接启动 LanMountainDesktop.exe
|
||
↓
|
||
检测到没有通过 Launcher 启动
|
||
↓
|
||
跳过 OOBE 和版本管理
|
||
↓
|
||
如果 AirAppRuntime 未运行，自动启动
|
||
↓
|
||
正常初始化桌面环境
|
||
```
|
||
|
||
## 核心系统
|
||
|
||
### 1. 组件系统
|
||
|
||
**职责**: 管理桌面组件的注册、创建、渲染和布局
|
||
|
||
**架构**:
|
||
|
||
```
|
||
ComponentRegistry (组件注册表)
|
||
↓ 注册
|
||
ComponentDefinition (组件定义)
|
||
↓ 创建实例
|
||
ComponentInstance (组件实例)
|
||
↓ 渲染
|
||
ComponentView (Avalonia UI)
|
||
↓ 显示
|
||
DesktopWidgetWindow (桌面窗口)
|
||
```
|
||
|
||
**关键类**:
|
||
- `ComponentRegistry` - 组件注册和查找
|
||
- `ComponentBase` - 组件基类
|
||
- `ComponentInstanceManager` - 组件实例管理
|
||
- `DesktopLayoutService` - 布局管理
|
||
|
||
### 2. 插件系统
|
||
|
||
**职责**: 加载、初始化和管理插件生命周期
|
||
|
||
**运行时模式**:
|
||
|
||
| 模式 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| **in-proc** | ✅ 当前默认 | 插件运行在宿主进程内 |
|
||
| **isolated-background** | 🚧 规划中 | 后台逻辑隔离进程 |
|
||
| **isolated-window** | 🚧 规划中 | UI 渲染隔离进程 |
|
||
|
||
**加载流程**:
|
||
|
||
```
|
||
1. 扫描插件目录
|
||
%LOCALAPPDATA%\LanMountainDesktop\plugins\
|
||
↓
|
||
2. 读取 plugin.json 清单
|
||
↓
|
||
3. 验证依赖关系
|
||
↓
|
||
4. 创建 PluginLoadContext
|
||
↓
|
||
5. 加载插件程序集
|
||
↓
|
||
6. 创建 IPlugin 实例
|
||
↓
|
||
7. 调用 InitializeAsync()
|
||
↓
|
||
8. 注册组件和服务
|
||
```
|
||
|
||
### 3. 设置系统
|
||
|
||
**职责**: 管理应用和插件的配置数据
|
||
|
||
**设置域**:
|
||
|
||
```
|
||
Settings Root
|
||
├── General (通用设置)
|
||
├── Appearance (外观设置)
|
||
├── Components (组件设置)
|
||
├── Plugins (插件设置)
|
||
│ ├── Plugin A
|
||
│ └── Plugin B
|
||
└── Advanced (高级设置)
|
||
```
|
||
|
||
**持久化**:
|
||
- 位置: `%LOCALAPPDATA%\LanMountainDesktop\settings\`
|
||
- 格式: JSON
|
||
- 实时保存，延迟写入
|
||
|
||
### 4. 主题系统
|
||
|
||
**职责**: 管理亮色/暗色主题、圆角系统
|
||
|
||
**圆角规范**:
|
||
|
||
| 级别 | Token | 值 | 用途 |
|
||
|------|-------|----|------|
|
||
| 基础 | `DesignCornerRadiusBasic` | 4 | 按钮、输入框 |
|
||
| 组件 | `DesignCornerRadiusComponent` | 8 | 卡片、面板 |
|
||
| 窗口 | `DesignCornerRadiusWindow` | 12 | 窗口、对话框 |
|
||
|
||
**主题切换**:
|
||
1. 用户选择主题
|
||
2. `AppearanceService` 切换资源字典
|
||
3. 广播主题变更事件
|
||
4. 各组件响应并更新 UI
|
||
5. 通过 IPC 通知 Air APP
|
||
|
||
### 5. IPC 系统
|
||
|
||
**职责**: 进程间通信
|
||
|
||
**通信拓扑**:
|
||
|
||
```
|
||
┌────────────────┐
|
||
│ Host │ ← 外部 IPC 入口点
|
||
│ (主程序) │
|
||
└────────┬───────┘
|
||
│ IPC
|
||
┌────┴────┐
|
||
↓ ↓
|
||
┌────────┐ ┌────────────┐
|
||
│Launcher│ │AirAppRuntime│
|
||
└────────┘ └──────┬──────┘
|
||
│ IPC
|
||
┌─────┴─────┐
|
||
↓ ↓
|
||
┌─────────┐ ┌─────────┐
|
||
│AirAppHost│ │AirAppHost│
|
||
└─────────┘ └─────────┘
|
||
```
|
||
|
||
**IPC 管道**:
|
||
- `LanMountainDesktop.Host.v1` - 宿主公共服务
|
||
- `LanMountainDesktop.AirAppRuntime.v1` - Air APP 生命周期
|
||
- `LanMountainDesktop.AirAppRuntimeControl.v1` - Runtime 控制
|
||
|
||
## 数据流
|
||
|
||
### 设置变更流程
|
||
|
||
```
|
||
用户修改设置
|
||
↓
|
||
SettingsService.SetValue()
|
||
↓
|
||
触发 SettingChanged 事件
|
||
↓
|
||
相关组件监听并响应
|
||
↓
|
||
延迟写入磁盘（防抖 500ms）
|
||
```
|
||
|
||
### 组件更新流程
|
||
|
||
```
|
||
定时器触发 (默认 1 秒)
|
||
↓
|
||
ComponentUpdateService.UpdateAsync()
|
||
↓
|
||
遍历所有组件实例
|
||
↓
|
||
调用 Component.UpdateAsync()
|
||
↓
|
||
组件更新数据
|
||
↓
|
||
UI 自动刷新（数据绑定）
|
||
```
|
||
|
||
### 插件通信流程
|
||
|
||
```
|
||
Plugin A 发送消息
|
||
↓
|
||
PluginMessenger.Send()
|
||
↓
|
||
消息总线分发
|
||
↓
|
||
Plugin B 接收消息
|
||
↓
|
||
处理并可选回复
|
||
```
|
||
|
||
## 安全性
|
||
|
||
### 权限系统
|
||
|
||
插件需要声明所需权限：
|
||
|
||
```json
|
||
{
|
||
"Permissions": [
|
||
"FileSystem.Read", // 读取文件
|
||
"FileSystem.Write", // 写入文件
|
||
"Network.Access", // 网络访问
|
||
"System.Info" // 系统信息
|
||
]
|
||
}
|
||
```
|
||
|
||
### 沙箱隔离（未来）
|
||
|
||
进程隔离模式下：
|
||
- 插件运行在独立进程
|
||
- 通过 IPC 访问宿主服务
|
||
- 限制文件系统访问
|
||
- 限制网络访问
|
||
|
||
## 性能优化
|
||
|
||
### 启动优化
|
||
- ✅ 延迟加载插件
|
||
- ✅ 异步初始化
|
||
- ✅ 组件按需创建
|
||
- ✅ 资源延迟加载
|
||
|
||
### 运行时优化
|
||
- ✅ 虚拟化列表
|
||
- ✅ 图片缓存
|
||
- ✅ 布局缓存
|
||
- ✅ 事件防抖/节流
|
||
|
||
### 内存优化
|
||
- ✅ 弱事件模式
|
||
- ✅ 及时释放资源
|
||
- ✅ 图片降采样
|
||
- ✅ 组件卸载清理
|
||
|
||
## 相关文档
|
||
|
||
- [启动器系统](02-启动器系统.md) - 启动器详细设计
|
||
- [插件运行时](04-插件运行时.md) - 插件加载和管理
|
||
- [组件系统](05-组件系统.md) - 组件架构和渲染
|
||
- [IPC 通信](07-IPC通信.md) - 进程间通信设计
|