---
title: 架构概览
description: 应用程序的高层架构设计
---

Server Box 采用分层架构，实现了清晰的关注点分离。

## 架构分层

```
┌─────────────────────────────────────────────────┐
│          表现层 (UI)                            │
│          lib/view/page/, lib/view/widget/       │
│  - 页面、组件、控制器                            │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         业务逻辑层                              │
│         lib/data/provider/                      │
│  - Riverpod Provider, State Notifier            │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│           数据访问层                            │
│         lib/data/store/, lib/data/model/        │
│  - Hive 存储, 数据模型                          │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         外部集成层                              │
│  - SSH (dartssh2), 终端 (xterm), SFTP           │
│  - 平台特定代码 (iOS, Android 等)               │
└─────────────────────────────────────────────────┘
```

## 应用基础

### 入口点

`lib/main.dart` 初始化应用：

```dart
void main() {
  runApp(
    ProviderScope(
      child: MyApp(),
    ),
  );
}
```

### 根组件

`MyApp` 提供以下功能：
- **主题管理**：浅色/深色主题切换
- **路由配置**：导航结构
- **Provider Scope**：依赖注入根节点

### 首页

`HomePage` 作为导航枢纽：
- **标签页界面**：服务器、脚本、容器、SSH
- **状态管理**：各标签页独立状态
- **导航**：功能入口

## 核心系统

### 状态管理：Riverpod

**为何选择 Riverpod？**
- 编译时安全
- 易于测试
- 不依赖 Build context
- 跨平台兼容性好

**使用的 Provider 类型：**
- `StateProvider`：简单的可变状态
- `AsyncNotifierProvider`：处理加载/错误/数据状态
- `StreamProvider`：实时数据流
- Future providers：一次性异步操作

### 数据持久化：Hive CE

**为何选择 Hive CE？**
- 无原生代码依赖
- 快速的键值存储
- 通过代码生成实现类型安全
- 无需手动添加字段注解

**存储类：**
- `SettingStore`：应用偏好设置
- `ServerStore`：服务器配置
- `SnippetStore`：命令脚本
- `KeyStore`：SSH 密钥

### 不可变模型：Freezed

**优势：**
- 编译时不可变性
- 联合类型处理状态
- 内置 JSON 序列化
- CopyWith 扩展

## 跨平台策略

### 插件系统

Flutter 插件提供平台集成：

| 平台 | 集成方式 |
|----------|-------------------|
| iOS | CocoaPods, Swift/Obj-C |
| Android | Gradle, Kotlin/Java |
| macOS | CocoaPods, Swift |
| Linux | CMake, C++ |
| Windows | CMake, C# |

### 平台特定功能

**仅限 iOS：**
- 主屏幕小组件
- 实时活动 (Live Activities)
- Apple Watch 配套应用

**仅限 Android：**
- 后台服务
- 推送通知
- 文件系统访问

**仅限桌面端：**
- 菜单栏集成
- 多窗口支持
- 自定义标题栏

## 自定义依赖

### dartssh2 分支

增强版 SSH 客户端，具有：
- 更好的移动端支持
- 增强的错误处理
- 性能优化

### xterm.dart 分支

终端模拟器，具有：
- 移动端优化的渲染
- 手势支持
- 虚拟键盘集成

### fl_lib

共享工具包，包含：
- 通用组件
- 扩展方法
- 辅助函数

## 构建系统

### fl_build 包

自定义构建系统，用于：
- 多平台构建
- 代码签名
- 资源打包
- 版本管理

### 构建流程

```
make.dart (版本计算) → fl_build (执行构建) → 平台产物
```

1. **预构建**：从 Git 计算版本号
2. **构建**：为目标平台编译
3. **后构建**：打包和签名

## 数据流示例

### 服务器状态更新

```
1. 定时器触发 →
2. Provider 调用 service →
3. Service 执行 SSH 命令 →
4. 响应解析为模型 →
5. 状态更新 →
6. UI 使用新数据重新构建
```

### 用户操作流

```
1. 用户点击按钮 →
2. Widget 调用 provider 方法 →
3. Provider 更新状态 →
4. 状态更改触发重构 →
5. UI 反映新状态
```

## 安全架构

### 数据保护

- **密码**：使用 flutter_secure_storage 加密
- **SSH 密钥**：静态存储时加密
- **主机指纹**：安全存储
- **会话数据**：不进行持久化

### 连接安全

- **主机密钥验证**：检测中间人攻击
- **加密**：标准 SSH 加密
- **不存储明文**：敏感数据绝不以明文存储
