diff options
Diffstat (limited to 'packages/docs/content/zh/architecture.mdx')
| -rw-r--r-- | packages/docs/content/zh/architecture.mdx | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/packages/docs/content/zh/architecture.mdx b/packages/docs/content/zh/architecture.mdx new file mode 100644 index 0000000..6a2a2df --- /dev/null +++ b/packages/docs/content/zh/architecture.mdx @@ -0,0 +1,281 @@ +--- +title: 架构设计 +description: DropOut Minecraft 启动器的技术架构和设计 +--- + +# 架构设计 + +DropOut 采用现代技术栈构建，旨在实现高性能、安全性和跨平台兼容性。 + +## 技术栈 + +### 后端（Rust） +- **框架**: Tauri v2 +- **语言**: Rust（Edition 2021） +- **异步运行时**: Tokio +- **HTTP 客户端**: reqwest with native-tls + +### 前端（Svelte） +- **框架**: Svelte 5（with runes） +- **样式**: Tailwind CSS 4 +- **构建工具**: Vite with Rolldown +- **包管理器**: pnpm + +### 文档 +- **框架**: Fumadocs with React Router v7 +- **内容**: MDX 文件 +- **样式**: Tailwind CSS 4 + +## 系统架构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 前端（Svelte 5） │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ +│ │ Stores │ │Components│ │ UI Views │ │Particles│ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │ +│ │ │ │ │ │ +│ └─────────────┴─────────────┴──────────────┘ │ +│ │ │ +│ Tauri 命令 │ +│ 事件/发射器 │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────┴──────────────────────────────┐ +│ 后端（Rust/Tauri） │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ main.rs（命令） │ │ +│ └──────────────┬──────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────┴───────────────────────────────┐ │ +│ │ 核心模块 │ │ +│ │ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │ │ +│ │ │ Auth │ │Download│ │ Java │ │ Instance │ │ │ +│ │ └──────┘ └────────┘ └──────┘ └──────────┘ │ │ +│ │ ┌──────┐ ┌────────┐ ┌──────┐ ┌──────────┐ │ │ +│ │ │Fabric│ │ Forge │ │Config│ │Manifest │ │ │ +│ │ └──────┘ └────────┘ └──────┘ └──────────┘ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ 工具和辅助函数 │ │ +│ │ • ZIP 提取 • 路径工具 │ │ +│ └─────────────────────────────────────────────────┘ │ +└──────────────────────────┬──────────────────────────────┘ + │ + 外部 API + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ┌─────┴────┐ ┌──────┴─────┐ ┌──────┴─────┐ + │ Mojang │ │ Fabric │ │ Forge │ + │ APIs │ │ Meta │ │ Maven │ + └──────────┘ └────────────┘ └────────────┘ +``` + +## 核心组件 + +### 前端状态管理 + +DropOut 使用 **Svelte 5 runes** 进行响应式状态管理： + +```typescript +// stores/auth.svelte.ts +export class AuthState { + currentAccount = $state<Account | null>(null); // 响应式 + isLoginModalOpen = $state(false); + + $effect(() => { // 副作用 + // 依赖变化时自动运行 + }); +} +``` + +**关键 Stores：** +- `auth.svelte.ts`: 认证状态和登录流程 +- `settings.svelte.ts`: 启动器设置和 Java 检测 +- `game.svelte.ts`: 游戏运行状态和日志 +- `instances.svelte.ts`: 实例管理 +- `ui.svelte.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(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 或动态代码执行 |