252 lines
9.2 KiB
Markdown
252 lines
9.2 KiB
Markdown
# Volcengine Server Manager - 设计文档
|
||
|
||
**日期**: 2026-04-04
|
||
**状态**: 待审核
|
||
|
||
## 概述
|
||
|
||
Windows 桌面应用，用于管理火山引擎云服务器 ECS。首期功能：查看服务器状态、重启服务器。
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 选型 | 说明 |
|
||
|---|------|------|
|
||
| GUI | egui + eframe (glow backend) | 纯 Rust，无外部依赖，单 exe 友好 |
|
||
| 火山引擎 API | volcengine-rust-sdk (1.0.2) | crates.io 官方 SDK |
|
||
| HTTP | reqwest (SDK 自带) | SDK 内部使用 |
|
||
| 异步运行时 | tokio | API 异步调用 |
|
||
| 序列化 | serde + serde_json | 配置读写、API 响应解析 |
|
||
| 编译目标 | x86_64-pc-windows-gnu | MSYS2 MinGW 工具链 |
|
||
|
||
## 配置
|
||
|
||
### 配置项
|
||
|
||
| 配置项 | 类型 | 默认值 | 必填 | 说明 |
|
||
|--------|------|--------|------|------|
|
||
| access_key_id | String | 空 | 是 | 火山引擎 Access Key ID |
|
||
| secret_access_key | String | 空 | 是 | 火山引擎 Secret Access Key |
|
||
| endpoint | String | `ecs.volcengineapi.com` | 否 | ECS API 端点 |
|
||
|
||
### 存储方式
|
||
|
||
- 文件路径: `%APPDATA%\volcengine-server-manager\config.json`
|
||
- 格式: JSON
|
||
- 首次启动时检测配置是否存在，不存在则弹出配置弹窗
|
||
|
||
## 火山引擎 API 调用
|
||
|
||
### DescribeInstances（查询实例列表）
|
||
|
||
- **目的**: 获取用户账号下所有 ECS 实例
|
||
- **请求参数**: `MaxResults=100`，支持分页
|
||
- **响应关键字段**:
|
||
- `InstanceId` - 实例 ID
|
||
- `InstanceName` - 实例名称
|
||
- `Status` - 实例状态（Running, Stopped, etc.）
|
||
- `PrivateIpAddresses` - 私网 IP
|
||
- `PublicIpAddresses` - 公网 IP
|
||
- `ZoneId` - 可用区
|
||
- `RegionId` - 地域
|
||
- `InstanceType` - 实例规格
|
||
- `CreationTime` - 创建时间
|
||
|
||
### RebootInstance（重启单台实例）
|
||
|
||
- **目的**: 重启指定 ECS 实例
|
||
- **请求参数**: `InstanceId` (字符串)
|
||
- **响应**: 操作结果
|
||
- **注意**: 重启前需要用户确认弹窗
|
||
|
||
### 区域处理
|
||
|
||
- 不要求用户手动配置 Region
|
||
- 先调用 `DescribeRegions` 获取所有可用区域列表
|
||
- 对每个区域并发调用 `DescribeInstances` 获取该区域实例
|
||
- 如果 `DescribeRegions` 不可用，则使用常见区域列表硬编码：`cn-beijing`, `cn-shanghai`, `cn-guangzhou`, `cn-chengdu`, `ap-singapore-1`
|
||
|
||
## 架构设计
|
||
|
||
### 模块划分
|
||
|
||
```
|
||
src/
|
||
├── main.rs # 入口：初始化 tokio 运行时，启动 eframe
|
||
├── app.rs # egui UI 主逻辑：渲染、事件处理、状态管理
|
||
├── config.rs # 配置结构体、JSON 读写
|
||
├── api.rs # 火山引擎 API 封装
|
||
└── types.rs # 数据类型定义
|
||
```
|
||
|
||
### 模块职责
|
||
|
||
#### `types.rs`
|
||
- `InstanceStatus` 枚举: Running, Stopped, Starting, Stopping, Rebooting, Error, Unknown
|
||
- `InstanceInfo` 结构体: 实例完整信息
|
||
- `AppState` 枚举: Loading, Ready, Error(String)
|
||
|
||
#### `config.rs`
|
||
- `AppConfig` 结构体: 配置项
|
||
- `load_config()` -> `Result<AppConfig>`
|
||
- `save_config(&AppConfig)` -> `Result<()>`
|
||
- 配置目录: `%APPDATA%\volcengine-server-manager\`
|
||
|
||
#### `api.rs`
|
||
- `VolcClient` 结构体: 封装 SDK Session 或 HTTP 客户端
|
||
- `new(access_key_id, secret_access_key, endpoint)` -> Self
|
||
- `list_instances()` -> `Result<Vec<InstanceInfo>>`
|
||
- `reboot_instance(instance_id)` -> `Result<()>`
|
||
- **签名机制**: 火山引擎使用 HMAC-SHA256 签名，SDK 不支持时直接构造 HTTP 请求
|
||
|
||
#### `app.rs`
|
||
- `VolcManagerApp` 结构体: egui App 实现
|
||
- 状态: instances (Vec), app_state, config, show_config_dialog, selected_instance, loading
|
||
- `update()`: UI 渲染主循环
|
||
- 方法: `refresh_instances()`, `reboot_selected()`, `open_config_dialog()`, `save_config()`
|
||
|
||
#### `main.rs`
|
||
- 初始化配置
|
||
- 创建 tokio 运行时
|
||
- 启动 eframe native window
|
||
- 设置 `windows_subsystem = "windows"` 去掉控制台
|
||
|
||
### 数据流
|
||
|
||
```
|
||
用户操作 → egui 事件 → App 方法 → tokio spawn 后台任务 → API 调用 → 结果通过 channel 返回 → 更新 state → request_repaint() → UI 刷新
|
||
```
|
||
|
||
### UI 布局
|
||
|
||
#### 主窗口
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ 火山引擎服务器管理 [刷新] [⚙ 配置] │
|
||
├──────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │ 实例名称 │ │ 实例名称 │ │ 实例名称 │ │
|
||
│ │ 状态: 运行中 │ │ 状态: 已停止 │ │ 状态: 运行中 │ │
|
||
│ │ IP: x.x.x.x │ │ IP: x.x.x.x │ │ IP: x.x.x.x │ │
|
||
│ │ 区域: cn-beijing │ 区域: cn-shanghai │ 区域: cn-guangzhou│
|
||
│ │ 规格: ecs.g3i.large │ 规格: ... │ 规格: ... │ │
|
||
│ │ │ │ │
|
||
│ │ [🔄 重启] │ [▶ 启动] │ [🔄 重启] │
|
||
│ └────────────┘ └────────────┘ └────────────┘ │
|
||
│ │
|
||
│ ┌────────────┐ ┌────────────┐ │
|
||
│ │ ... │ │ ... │ │
|
||
│ └────────────┘ └────────────┘ │
|
||
│ │
|
||
├──────────────────────────────────────────────────────┤
|
||
│ 实例数: 5 最后刷新: 2026-04-04 19:30 │
|
||
└──────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 配置弹窗（Modal）
|
||
|
||
```
|
||
┌────────────────────────────────────┐
|
||
│ 配置 │
|
||
├────────────────────────────────────┤
|
||
│ Access Key ID: │
|
||
│ [________________________________]│
|
||
│ │
|
||
│ Secret Access Key: │
|
||
│ [________________________________]│
|
||
│ │
|
||
│ Endpoint: │
|
||
│ [ecs.volcengineapi.com___________]│
|
||
│ │
|
||
│ [保存] [取消] │
|
||
└────────────────────────────────────┘
|
||
```
|
||
|
||
#### 重启确认弹窗
|
||
|
||
```
|
||
┌────────────────────────────────────┐
|
||
│ 确认重启 │
|
||
├────────────────────────────────────┤
|
||
│ 确定要重启实例 "xxx" 吗？ │
|
||
│ 实例 ID: i-xxxxxxxxxxxx │
|
||
│ │
|
||
│ [确定] [取消] │
|
||
└────────────────────────────────────┘
|
||
```
|
||
|
||
### 状态颜色映射
|
||
|
||
| 状态 | 颜色 |
|
||
|------|------|
|
||
| Running | 绿色 |
|
||
| Stopped | 灰色 |
|
||
| Starting | 蓝色 |
|
||
| Stopping | 橙色 |
|
||
| Rebooting | 橙色 |
|
||
| Error | 红色 |
|
||
| Unknown | 黄色 |
|
||
|
||
### 错误处理
|
||
|
||
- API 调用失败：底部状态栏显示错误信息，3 秒后自动消失
|
||
- 配置未设置：首次启动弹出配置弹窗，阻止主界面操作
|
||
- 网络异常：显示 "网络连接失败，请检查网络设置"
|
||
- 认证失败：显示 "Access Key 或 Secret Key 无效"
|
||
|
||
### 中文支持
|
||
|
||
- 加载 Windows 系统字体 `C:\Windows\Fonts\msyh.ttc`（微软雅黑）
|
||
- 通过 `egui::FontDefinitions` 注入为默认字体
|
||
- 如果字体加载失败，回退到 egui 内置字体（英文字符）
|
||
|
||
### 编译配置
|
||
|
||
#### Cargo.toml 关键设置
|
||
|
||
```toml
|
||
[package]
|
||
name = "volcengine-server-manager"
|
||
version = "0.1.0"
|
||
edition = "2021"
|
||
|
||
[[bin]]
|
||
name = "volcengine-server-manager"
|
||
path = "src/main.rs"
|
||
|
||
[profile.release]
|
||
opt-level = 2
|
||
strip = true
|
||
lto = true
|
||
|
||
# Windows 子系统设置（去掉控制台窗口）
|
||
[package.metadata.windows]
|
||
subsystem = "windows"
|
||
```
|
||
|
||
实际去掉控制台的方法：在 `main.rs` 中设置 `#![windows_subsystem = "windows"]` 属性。
|
||
|
||
### 依赖列表
|
||
|
||
```toml
|
||
[dependencies]
|
||
eframe = { version = "0.29", default-features = false, features = ["glow"] }
|
||
egui = "0.29"
|
||
volcengine-rust-sdk = "1.0.2"
|
||
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
|
||
serde = { version = "1", features = ["derive"] }
|
||
serde_json = "1"
|
||
dirs = "5"
|
||
```
|
||
|
||
### 编译命令
|
||
|
||
```bash
|
||
# 在 MSYS2 MinGW 环境下
|
||
rustup target add x86_64-pc-windows-gnu
|
||
cargo build --release --target x86_64-pc-windows-gnu
|
||
```
|
||
|
||
输出文件: `target/x86_64-pc-windows-gnu/release/volcengine-server-manager.exe`
|