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