276 lines
8.6 KiB
Markdown
276 lines
8.6 KiB
Markdown
# Linux 存储管理器 (Linux Storage Manager) - AI Agent Guide
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 PySide6 开发的 Linux 存储管理图形界面工具，提供磁盘管理、逻辑卷管理(LVM)和软阵列管理(RAID)三大核心功能。
|
||
|
||
**主要功能模块：**
|
||
1. **磁盘管理** - 分区创建/删除、格式化(ext4/xfs/ntfs/fat32)、挂载/卸载、分区表擦除
|
||
2. **LVM 管理** - 物理卷(PV)、卷组(VG)、逻辑卷(LV)的创建和管理
|
||
3. **RAID 管理** - 软阵列创建、管理、停止/启动阵列 (支持 RAID0/1/5/6/10)
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 说明 |
|
||
|------|------|
|
||
| Python 3.14+ | 主要编程语言 |
|
||
| PySide6 | Qt6 的 Python 绑定，用于 GUI |
|
||
| Qt Designer (.ui 文件) | UI 设计文件 |
|
||
| PyInstaller | 打包工具，生成独立可执行文件 |
|
||
| 系统工具 | parted, mkfs.*, mount, umount, lvm2, mdadm, lsblk, findmnt |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── mainwindow.py # 主窗口，UI 与业务逻辑控制器
|
||
├── ui_form.py # 自动生成的 UI 代码 (从 form.ui 生成)
|
||
├── form.ui # Qt Designer UI 定义文件
|
||
├── system_info.py # 系统信息获取模块 (块设备、RAID、挂载点)
|
||
├── disk_operations.py # 磁盘操作 (分区、格式化、挂载)
|
||
├── lvm_operations.py # LVM 操作 (PV/VG/LV 管理)
|
||
├── raid_operations.py # RAID 操作 (mdadm 管理)
|
||
├── dialogs.py # 自定义对话框 (创建分区、RAID、PV/VG/LV 等)
|
||
├── occupation_resolver.py # 设备占用解除模块 (处理挂载、进程占用)
|
||
├── logger_config.py # 日志配置 (输出到 QTextEdit 和控制台)
|
||
├── pyproject.toml # PySide6 项目配置
|
||
├── disk-manager.spec # PyInstaller 打包配置 (英文版)
|
||
├── Linux存儲管理器.spec # PyInstaller 打包配置 (中文版)
|
||
└── build-app.sh # 打包脚本
|
||
```
|
||
|
||
## 代码组织
|
||
|
||
### 模块依赖关系
|
||
|
||
```
|
||
mainwindow.py (入口)
|
||
├── ui_form.py (自动生成的 UI)
|
||
├── system_info.py (系统信息)
|
||
├── disk_operations.py (磁盘操作)
|
||
│ └── 依赖: system_info.py, lvm_operations.py
|
||
├── lvm_operations.py (LVM 操作，提供 _execute_shell_command)
|
||
├── raid_operations.py (RAID 操作)
|
||
│ └── 依赖: system_info.py
|
||
├── occupation_resolver.py (占用解除)
|
||
│ └── 依赖: lvm_operations.py, system_info.py
|
||
├── dialogs.py (对话框)
|
||
└── logger_config.py (日志)
|
||
```
|
||
|
||
### 核心类说明
|
||
|
||
| 类名 | 文件 | 职责 |
|
||
|------|------|------|
|
||
| `MainWindow` | mainwindow.py | 主窗口，整合所有功能，处理用户交互 |
|
||
| `SystemInfoManager` | system_info.py | 获取系统块设备信息、RAID 信息、挂载点 |
|
||
| `DiskOperations` | disk_operations.py | 磁盘分区、格式化、挂载操作 |
|
||
| `LvmOperations` | lvm_operations.py | LVM 相关操作，提供统一的 shell 命令执行接口 |
|
||
| `RaidOperations` | raid_operations.py | RAID 阵列管理 |
|
||
| `OccupationResolver` | occupation_resolver.py | 解除设备占用 (嵌套挂载、进程占用) |
|
||
| `FormatWorker` | disk_operations.py | 后台格式化工作线程 |
|
||
| `QTextEditLogger` | logger_config.py | 自定义日志处理器，输出到 UI |
|
||
|
||
### 对话框类 (dialogs.py)
|
||
|
||
- `CreatePartitionDialog` - 创建分区对话框
|
||
- `MountDialog` - 挂载分区对话框
|
||
- `CreateRaidDialog` - 创建 RAID 阵列对话框
|
||
- `CreatePvDialog` - 创建物理卷对话框
|
||
- `CreateVgDialog` - 创建卷组对话框
|
||
- `CreateLvDialog` - 创建逻辑卷对话框
|
||
|
||
## 构建和打包
|
||
|
||
### 依赖安装
|
||
|
||
```bash
|
||
pip install PySide6 pyinstaller pexpect
|
||
```
|
||
|
||
### 开发运行
|
||
|
||
```bash
|
||
# 直接运行
|
||
python mainwindow.py
|
||
|
||
# 注意: 部分功能需要 root 权限
|
||
sudo python mainwindow.py
|
||
```
|
||
|
||
### 生成可执行文件
|
||
|
||
```bash
|
||
# 使用 PyInstaller (需要配置虚拟环境路径)
|
||
sudo /path/to/venv/bin/pyinstaller -F --name "disk-manager" mainwindow.py
|
||
|
||
# 或使用提供的打包脚本 (需修改路径)
|
||
bash build-app.sh
|
||
```
|
||
|
||
打包配置文件:
|
||
- `disk-manager.spec` - 英文名称配置
|
||
- `Linux存儲管理器.spec` - 中文名称配置
|
||
|
||
## UI 设计规范
|
||
|
||
### 界面布局 (form.ui)
|
||
|
||
主窗口包含:
|
||
1. **刷新按钮** - 刷新所有设备信息
|
||
2. **标签页控件** - 三个标签页:
|
||
- 块设备概览 (treeWidget_block_devices)
|
||
- RAID 管理 (treeWidget_raid)
|
||
- LVM 管理 (treeWidget_lvm)
|
||
3. **日志输出区** (logOutputTextEdit) - 显示操作日志
|
||
|
||
### 修改 UI 的流程
|
||
|
||
1. 使用 Qt Designer 编辑 `form.ui`
|
||
2. 使用 `pyside6-uic` 重新生成 `ui_form.py`:
|
||
```bash
|
||
pyside6-uic form.ui -o ui_form.py
|
||
```
|
||
3. 注意：`ui_form.py` 是自动生成的，不要手动修改
|
||
|
||
## 编码规范
|
||
|
||
### 代码风格
|
||
|
||
- 使用 4 空格缩进
|
||
- 函数和变量使用小写加下划线命名 (snake_case)
|
||
- 类名使用大驼峰命名 (PascalCase)
|
||
- 注释和日志使用中文
|
||
|
||
### 错误处理
|
||
|
||
所有 shell 命令执行通过 `_execute_shell_command` 方法统一处理:
|
||
- 自动处理 sudo 权限
|
||
- 统一的错误对话框显示
|
||
- 详细的日志记录
|
||
|
||
示例:
|
||
```python
|
||
success, stdout, stderr = self.lvm_ops._execute_shell_command(
|
||
["parted", "-s", device_path, "mklabel", "gpt"],
|
||
f"擦除 {device_path} 上的分区表失败"
|
||
)
|
||
```
|
||
|
||
### 日志记录
|
||
|
||
使用标准 logging 模块，配置在 `logger_config.py`:
|
||
- DEBUG: 详细的调试信息
|
||
- INFO: 常规操作信息
|
||
- WARNING: 警告信息
|
||
- ERROR: 错误信息
|
||
|
||
日志同时输出到:
|
||
1. 控制台 (标准输出)
|
||
2. UI 的 QTextEdit 控件 (通过 QTextEditLogger)
|
||
|
||
## 关键实现细节
|
||
|
||
### 1. 权限处理
|
||
|
||
所有需要 root 权限的操作都通过 `sudo` 执行。项目中没有直接处理密码输入，依赖系统的 sudo 配置。
|
||
|
||
### 2. 异步操作
|
||
|
||
格式化操作使用 `QThread` + `FormatWorker` 在后台执行，避免阻塞 UI:
|
||
```python
|
||
# 信号定义
|
||
formatting_finished = Signal(bool, str, str, str) # success, device, stdout, stderr
|
||
formatting_started = Signal(str)
|
||
```
|
||
|
||
### 3. 设备识别
|
||
|
||
- 使用 `lsblk -J` 获取块设备信息 (JSON 格式)
|
||
- 支持通过设备路径或 maj:min 号识别设备
|
||
- 正确处理符号链接 (如 LVM 设备、RAID 别名)
|
||
|
||
### 4. 占用解除
|
||
|
||
`OccupationResolver` 类处理复杂的设备占用情况:
|
||
- 嵌套挂载点卸载
|
||
- 用户进程占用检测和终止
|
||
- 交换分区关闭
|
||
|
||
## 测试策略
|
||
|
||
当前项目没有自动化测试套件。测试主要依赖:
|
||
|
||
1. **手动测试** - 在真实 Linux 环境中测试各项功能
|
||
2. **日志验证** - 通过日志输出验证操作执行
|
||
|
||
**测试环境要求:**
|
||
- Linux 系统 (建议 Ubuntu/Debian 或 Arch Linux)
|
||
- 安装必要工具: `parted`, `lvm2`, `mdadm`, `dosfstools`, `ntfs-3g`
|
||
- 测试磁盘建议使用虚拟机或空闲磁盘，避免数据丢失
|
||
|
||
## 安全注意事项
|
||
|
||
⚠️ **危险操作警告:**
|
||
|
||
1. **格式化操作** - 会永久删除数据
|
||
2. **分区删除** - 会丢失分区数据
|
||
3. **分区表擦除** - 会清除整个磁盘分区信息
|
||
4. **RAID 操作** - 错误的操作可能导致阵列损坏
|
||
|
||
**安全准则:**
|
||
- 所有危险操作都有确认对话框
|
||
- 操作前会记录警告日志
|
||
- 建议只在测试环境或已备份的系统上使用
|
||
- 部分操作不可逆，请谨慎操作
|
||
|
||
## 外部依赖工具
|
||
|
||
应用程序依赖以下系统工具:
|
||
|
||
| 工具 | 用途 |
|
||
|------|------|
|
||
| lsblk | 获取块设备信息 |
|
||
| parted | 分区管理 |
|
||
| mkfs.ext4/mkfs.xfs/mkfs.vfat/mkfs.ntfs | 文件系统格式化 |
|
||
| mount/umount | 挂载/卸载 |
|
||
| lvm (pvcreate/vgcreate/lvcreate 等) | LVM 管理 |
|
||
| mdadm | RAID 管理 |
|
||
| findmnt | 挂载点查询 |
|
||
| fuser | 进程占用查询 |
|
||
| stat | 设备信息获取 |
|
||
| pexpect | 交互式命令执行 (RAID 创建) |
|
||
|
||
## 配置说明
|
||
|
||
### pyproject.toml
|
||
|
||
PySide6 项目配置文件，定义项目文件列表:
|
||
```toml
|
||
[tool.pyside6-project]
|
||
files = ["dialogs.py", "disk_operations.py", ...]
|
||
```
|
||
|
||
### .gitignore
|
||
|
||
排除目录:
|
||
- /dist/ - PyInstaller 输出
|
||
- /build/ - 构建缓存
|
||
- /.qtcreator/ - Qt Creator 配置
|
||
- /__pycache__/ - Python 缓存
|
||
|
||
## 开发工作流
|
||
|
||
1. **修改 UI**: 编辑 `form.ui` → 运行 `pyside6-uic` 生成 `ui_form.py`
|
||
2. **添加功能**: 在相应模块添加逻辑，在 `MainWindow` 添加槽函数
|
||
3. **测试**: 在 Linux 环境中运行 `python mainwindow.py`
|
||
4. **打包**: 运行 `build-app.sh` 或直接使用 PyInstaller
|
||
5. **提交**: 使用 `up+.sh` 脚本辅助 git 提交 (需配置)
|
||
|
||
## 常见问题
|
||
|
||
1. **UI 更新不生效** - 检查是否重新生成了 `ui_form.py`
|
||
2. **权限错误** - 确保以 sudo 运行或配置 sudo 免密
|
||
3. **命令未找到** - 安装对应的系统工具包
|
||
4. **RAID 创建卡住** - pexpect 交互处理可能需要调整
|