path: root/packages/docs/content/zh/architecture.mdx

---
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 或动态代码执行