diff options
Diffstat (limited to 'packages/docs/content/zh/development/architecture.mdx')
| -rw-r--r-- | packages/docs/content/zh/development/architecture.mdx | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/packages/docs/content/zh/development/architecture.mdx b/packages/docs/content/zh/development/architecture.mdx new file mode 100644 index 0000000..4f47115 --- /dev/null +++ b/packages/docs/content/zh/development/architecture.mdx @@ -0,0 +1,311 @@ +--- +title: 架构设计 +description: DropOut Minecraft 启动器的技术架构和设计 +--- + +# 架构设计 + +DropOut 采用现代技术栈构建，旨在实现高性能、安全性和跨平台兼容性。 + +## 技术栈 + +### 后端（Rust） + +- **框架**: Tauri v2 +- **语言**: Rust（Edition 2021） +- **异步运行时**: Tokio +- **HTTP 客户端**: reqwest with native-tls + +### 前端（React） + +- **框架**: React 19 +- **状态管理**: Zustand +- **路由**: React Router v7 +- **样式**: Tailwind CSS 4 +- **构建工具**: Vite (with Rolldown) +- **包管理器**: pnpm + +### 文档 + +- **框架**: Fumadocs with React Router v7 +- **内容**: MDX 文件 +- **样式**: Tailwind CSS 4 + +## 系统架构 + +```mermaid +graph TB + subgraph Frontend["前端 (React 19)"] + direction LR + Stores[Zustand Stores] ~~~ Components[Components] ~~~ Pages[Pages] ~~~ Router[Router] ~~~ Particles[Particle Background] + end + + subgraph TauriLayer["Tauri 通信层"] + direction LR + Commands[命令] ~~~ Events[事件/发射器] + end + + subgraph Backend["后端 (Rust/Tauri)"] + direction TB + MainRS[main.rs 命令处理] + + subgraph CoreModules["核心模块"] + direction LR + Auth[Auth] ~~~ Download[Download] ~~~ Java[Java] ~~~ Instance[Instance] + Fabric[Fabric] ~~~ Forge[Forge] ~~~ Config[Config] ~~~ Manifest[Manifest] + Auth ~~~ Fabric + end + + subgraph Utils["工具和辅助函数"] + direction LR + ZipExtract[ZIP 提取] ~~~ PathUtils[路径工具] + end + + MainRS --> CoreModules + CoreModules --> Utils + end + + subgraph ExternalAPIs["外部 API"] + direction LR + Mojang[Mojang APIs] ~~~ FabricMeta[Fabric Meta] ~~~ ForgeMaven[Forge Maven] + end + + Frontend <--> TauriLayer + TauriLayer <--> Backend + Backend <--> ExternalAPIs + + style Frontend fill:#e3f2fd + style Backend fill:#fff3e0 + style TauriLayer fill:#f3e5f5 + style ExternalAPIs fill:#e8f5e9 +``` + +## 核心组件 + +### 前端状态管理 + +DropOut 使用 **Zustand** 进行全局状态管理： + +```typescript +// models/auth.ts +import { create } from "zustand"; + +interface AuthState { + account: Account | null; + loginMode: LoginMode | null; + // ... + setAccount: (account: Account | null) => void; +} + +export const useAuthStore = create<AuthState>((set) => ({ + account: null, + loginMode: null, + setAccount: (account) => set({ account }), + // ... +})); +``` + +**关键 Stores：** + +- `models/auth.ts`: 认证状态和登录流程 +- `models/settings.ts`: 启动器设置和 Java 检测 +- `models/instance.ts`: 实例管理 +- `stores/game-store.ts`: 游戏运行状态 +- `stores/logs-store.ts`: 游戏日志流管理 +- `stores/ui-store.ts`: UI 状态（提示、模态框、活动视图） + +### 后端架构 + +#### 命令模式 + +所有 Tauri 命令遵循此结构： + +```rust +#[tauri::command] +async fn command_name( + window: Window, + state: State<'_, SomeState>, + param: Type, +) -> Result<ReturnType, String> { + emit_log!(window, "状态消息"); + // 异步逻辑 + Ok(result) +} +``` + +#### 事件通信 + +**Rust → 前端（进度更新）：** + +```rust +window.emit("launcher-log", "正在下载...")?; +window.emit("download-progress", progress_struct)?; +``` + +**前端 → Rust（命令）：** + +```typescript +import { invoke } from "@tauri-apps/api/core"; +const result = await invoke("start_game", { versionId: "1.20.4" }); +``` + +### 核心模块 + +#### 认证（`core/auth.rs`） + +- **微软 OAuth 2.0**: 设备代码流 +- **离线认证**: 本地 UUID 生成 +- **令牌管理**: 刷新令牌存储和自动刷新 +- **Xbox Live 集成**: 完整认证链 + +**认证流程：** + +1. 设备代码请求 → MS 令牌 +2. Xbox Live 认证 +3. XSTS 授权 +4. Minecraft 令牌交换 +5. 配置文件获取 + +#### 下载器（`core/downloader.rs`） + +- **并发下载**: 可配置线程池 +- **断点续传**: `.part` 和 `.part.meta` 文件 +- **多段下载**: 大文件分割成块 +- **校验和验证**: SHA1/SHA256 验证 +- **进度跟踪**: 实时事件到前端 + +#### Java 管理（`core/java.rs`） + +- **自动检测**: 扫描系统路径 +- **Adoptium 集成**: 按需下载 JDK/JRE +- **目录缓存**: 版本列表 24 小时缓存 +- **安装**: 提取到应用数据目录 +- **取消**: 下载取消的原子标志 + +#### Fabric 支持（`core/fabric.rs`） + +- **Meta API 集成**: 获取加载器版本 +- **配置文件生成**: 创建版本 JSON +- **库解析**: Maven 构件处理 + +#### Forge 支持（`core/forge.rs`） + +- **安装程序执行**: 运行 Forge 安装程序 +- **配置文件解析**: 提取安装配置文件 +- **库管理**: 处理 Forge 特定库 + +#### 实例系统（`core/instance.rs`） + +- **隔离**: 每个实例独立目录 +- **配置**: 每个实例的设置 +- **模组管理**: 实例特定模组 +- **版本锁定**: 可复现环境 + +#### 版本管理 + +- **清单解析**（`manifest.rs`）: Mojang 版本清单 +- **继承系统**（`version_merge.rs`）: 父版本合并 +- **游戏版本**（`game_version.rs`）: JSON 解析和验证 +- **规则引擎**（`rules.rs`）: 操作系统/功能条件逻辑 + +### 文件结构 + +``` +~/.local/share/com.dropout.launcher/ (Linux) +~/Library/Application Support/com.dropout.launcher/ (macOS) +%APPDATA%/com.dropout.launcher/ (Windows) +├── versions/ +│ └── <version_id>/ +│ ├── <version_id>.json +│ ├── <version_id>.jar +│ └── natives/ +├── libraries/ +│ └── <maven-path>/ +├── assets/ +│ ├── indexes/ +│ └── objects/ +├── instances/ +│ └── <instance_name>/ +│ ├── mods/ +│ ├── config/ +│ └── saves/ +├── java/ +│ └── <version>/ +├── config.json +└── accounts.json +``` + +## 数据流 + +### 游戏启动序列 + +1. **前端**: 用户点击"启动游戏" +2. **命令**: 调用 `start_game(instance_id, version_id)` +3. **后端处理**: + - 加载版本 JSON（带继承） + - 解析所有库 + - 下载缺少的资源 + - 提取原生库 + - 构建类路径 + - 构造 JVM 参数 + - 替换占位符 +4. **进程生成**: 使用参数启动 Java +5. **流日志**: 向前端发送 stdout/stderr +6. **监视**: 跟踪游戏进程状态 + +### 下载流程 + +1. **队列创建**: 要下载的文件列表 +2. **并发处理**: 信号量限制线程 +3. **恢复检查**: 验证现有 `.part` 文件 +4. **下载**: 大文件多段 +5. **验证**: 校验和验证 +6. **进度事件**: 实时更新到 UI +7. **完成**: 从 `.part` 移动到最终位置 + +### 认证流程 + +1. **设备代码请求**: 获取用户代码 + 设备代码 +2. **用户授权**: 用户访问 URL 并输入代码 +3. **令牌轮询**: 前端轮询完成 +4. **令牌交换**: MS 令牌 → Xbox → XSTS → Minecraft +5. **配置文件获取**: 获取用户名和 UUID +6. **存储**: 使用刷新令牌保存账户 +7. **自动刷新**: 过期时后台令牌刷新 + +## 平台特定考虑 + +### Linux + +- 使用 GTK WebView（`webkit2gtk`） +- 从 `/usr/lib/jvm` 系统 Java 检测 +- 桌面文件集成 + +### macOS + +- 使用系统 WebKit +- 应用程序包结构 +- 钥匙串集成用于安全存储 + +### Windows + +- 使用 WebView2 运行时 +- 注册表 Java 检测 +- MSI 安装程序支持 +- 发布版本中无控制台窗口 + +## 性能优化 + +- **并发下载**: 并行资源/库下载 +- **延迟加载**: 按需加载版本清单 +- **缓存**: Java 目录、版本清单 +- **原生代码**: 用于 CPU 密集型操作的 Rust +- **异步 I/O**: 用于非阻塞操作的 Tokio + +## 安全功能 + +- **令牌加密**: 安全存储认证令牌 +- **仅 HTTPS**: 所有外部 API 调用 +- **校验和验证**: 文件完整性验证 +- **沙箱执行**: Tauri 安全模型 +- **无任意代码**: 无 eval 或动态代码执行 |