zj/diskmanager2

Fork 0

Files

zj 8c53b9c0a0 first commit

2026-02-07 14:58:56 +08:00

8.6 KiB

Raw Blame History

Linux 存储管理器 (Linux Storage Manager) - AI Agent Guide

项目概述

这是一个基于 PySide6 开发的 Linux 存储管理图形界面工具，提供磁盘管理、逻辑卷管理(LVM)和软阵列管理(RAID)三大核心功能。

主要功能模块：

磁盘管理 - 分区创建/删除、格式化(ext4/xfs/ntfs/fat32)、挂载/卸载、分区表擦除
LVM 管理 - 物理卷(PV)、卷组(VG)、逻辑卷(LV)的创建和管理
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 - 创建逻辑卷对话框

构建和打包

依赖安装

pip install PySide6 pyinstaller pexpect

开发运行

# 直接运行
python mainwindow.py

# 注意: 部分功能需要 root 权限
sudo python mainwindow.py

生成可执行文件

# 使用 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)

主窗口包含:

刷新按钮 - 刷新所有设备信息
标签页控件 - 三个标签页:
- 块设备概览 (treeWidget_block_devices)
- RAID 管理 (treeWidget_raid)
- LVM 管理 (treeWidget_lvm)
日志输出区 (logOutputTextEdit) - 显示操作日志

修改 UI 的流程

使用 Qt Designer 编辑 form.ui
使用 pyside6-uic 重新生成 ui_form.py:
```
pyside6-uic form.ui -o ui_form.py
```
注意：ui_form.py 是自动生成的，不要手动修改

编码规范

代码风格

使用 4 空格缩进
函数和变量使用小写加下划线命名 (snake_case)
类名使用大驼峰命名 (PascalCase)
注释和日志使用中文

错误处理

所有 shell 命令执行通过 _execute_shell_command 方法统一处理:

自动处理 sudo 权限
统一的错误对话框显示
详细的日志记录

示例:

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: 错误信息

日志同时输出到:

控制台 (标准输出)
UI 的 QTextEdit 控件 (通过 QTextEditLogger)

关键实现细节

1. 权限处理

所有需要 root 权限的操作都通过 sudo 执行。项目中没有直接处理密码输入，依赖系统的 sudo 配置。

2. 异步操作

格式化操作使用 QThread + FormatWorker 在后台执行，避免阻塞 UI:

# 信号定义
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 类处理复杂的设备占用情况:

嵌套挂载点卸载
用户进程占用检测和终止
交换分区关闭

测试策略

当前项目没有自动化测试套件。测试主要依赖:

手动测试 - 在真实 Linux 环境中测试各项功能
日志验证 - 通过日志输出验证操作执行

测试环境要求:

Linux 系统 (建议 Ubuntu/Debian 或 Arch Linux)
安装必要工具: parted, lvm2, mdadm, dosfstools, ntfs-3g
测试磁盘建议使用虚拟机或空闲磁盘，避免数据丢失

安全注意事项

⚠️ 危险操作警告:

格式化操作 - 会永久删除数据
分区删除 - 会丢失分区数据
分区表擦除 - 会清除整个磁盘分区信息
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 项目配置文件，定义项目文件列表:

[tool.pyside6-project]
files = ["dialogs.py", "disk_operations.py", ...]

.gitignore

排除目录:

/dist/ - PyInstaller 输出
/build/ - 构建缓存
/.qtcreator/ - Qt Creator 配置
/pycache/ - Python 缓存

开发工作流

修改 UI: 编辑 form.ui → 运行 pyside6-uic 生成 ui_form.py
添加功能: 在相应模块添加逻辑，在 MainWindow 添加槽函数
测试: 在 Linux 环境中运行 python mainwindow.py
打包: 运行 build-app.sh 或直接使用 PyInstaller
提交: 使用 up+.sh 脚本辅助 git 提交 (需配置)

常见问题

UI 更新不生效 - 检查是否重新生成了 ui_form.py
权限错误 - 确保以 sudo 运行或配置 sudo 免密
命令未找到 - 安装对应的系统工具包
RAID 创建卡住 - pexpect 交互处理可能需要调整

8.6 KiB Raw Blame History Unescape Escape