diskmanager2/AGENTS.md

Linux 存储管理器 (Linux Storage Manager)

项目概述

这是一个基于 PySide6 开发的 Linux 图形化存储管理工具，提供磁盘管理、逻辑卷管理(LVM)和软 RAID 管理功能。应用程序通过调用系统命令（如 lsblk, parted, mdadm, lvm 等）与 Linux 存储子系统交互。

主要功能模块

1. 块设备管理 - 查看磁盘信息、创建分区、格式化文件系统(ext4/xfs/ntfs/fat32)、挂载/卸载设备
2. LVM 管理 - 物理卷(PV)、卷组(VG)、逻辑卷(LV)的创建、删除和扩容
3. RAID 管理 - 软 RAID 阵列的创建、删除和监控（支持 RAID0/1/5/6/10）

技术栈

• GUI 框架: PySide6 (Qt for Python)
• UI 设计: Qt Designer (form.ui)
• 构建工具: PyInstaller
• 依赖库:
  • PySide6 - GUI 框架
  • pexpect - 交互式命令执行（用于 RAID 创建时的密码输入）

项目结构

.
├── mainwindow.py          # 应用程序入口，主窗口逻辑，连接各模块
├── ui_form.py             # 由 form.ui 自动生成的 UI 类
├── form.ui                # Qt Designer UI 定义文件（主界面布局）
├── dialogs.py             # 自定义对话框（分区创建、挂载、RAID/LVM 创建等）
├── system_info.py         # 系统信息获取模块（lsblk 解析等）
├── disk_operations.py     # 磁盘操作（分区、格式化、挂载管理）
├── lvm_operations.py      # LVM 操作（PV/VG/LV 管理）
├── raid_operations.py     # RAID 操作（mdadm 命令封装）
├── occupation_resolver.py # 设备占用检测与解除（嵌套挂载、进程占用）
├── logger_config.py       # 日志配置（输出到 QTextEdit 控件）
├── pyproject.toml         # PySide6 项目配置文件
├── disk-manager.spec      # PyInstaller 打包配置
└── build-app.sh           # 构建脚本

模块依赖关系

mainwindow.py
    ├── ui_form.py (UI 布局)
    ├── system_info.py (系统信息)
    ├── logger_config.py (日志)
    ├── disk_operations.py (磁盘操作)
    │       └── 依赖 system_info.py, lvm_operations.py
    ├── raid_operations.py (RAID 操作)
    │       └── 依赖 system_info.py
    ├── lvm_operations.py (LVM 操作)
    ├── occupation_resolver.py (占用解决)
    │       └── 依赖 lvm_operations.py, system_info.py
    └── dialogs.py (对话框)
            └── 依赖 logger_config.py

代码组织规范

文件命名

• 模块文件使用下划线命名法：disk_operations.py, lvm_operations.py
• UI 相关文件：form.ui（设计源文件）, ui_form.py（自动生成）

类命名规范

• 主窗口类：MainWindow
• UI 类：Ui_MainWindow（Qt 自动生成）
• 操作类：DiskOperations, LvmOperations, RaidOperations
• 对话框类：CreatePartitionDialog, MountDialog, CreateRaidDialog
• 工具类：SystemInfoManager, OccupationResolver

命令执行模式

所有系统命令执行都通过 _execute_shell_command 或 _run_command 方法封装，统一处理：

• sudo 权限提升
• 错误处理和日志记录
• QMessageBox 错误提示（可抑制）

构建和运行

运行环境要求

• Linux 操作系统（需要 root/sudo 权限执行存储管理命令）
• Python 3.x
• 系统依赖：parted, mdadm, lvm2, dosfstools, e2fsprogs, xfsprogs, ntfs-3g

安装依赖

pip install PySide6 pexpect

运行应用

python mainwindow.py

注意：大部分功能需要 root 权限，建议以 sudo 运行或确保用户有 sudo 权限。

打包可执行文件

# 使用 PyInstaller
sudo pyinstaller -F --name "disk-manager" mainwindow.py

# 或使用提供的脚本
sudo ./build-app.sh

打包后的可执行文件位于 dist/disk-manager。

开发注意事项

UI 修改流程

1. 使用 Qt Designer 编辑 form.ui
2. 使用 pyside6-uic form.ui -o ui_form.py 重新生成 Python UI 文件
3. 或在 Qt Creator 中配置 PySide6 项目自动处理

日志系统

• 使用 logger_config.py 中配置的全局 logger
• 日志同时输出到控制台和 GUI 的 QTextEdit 控件
• 日志级别：logging.DEBUG（开发时可调整）

线程安全

• 格式化操作使用 FormatWorker 在后台线程执行，避免阻塞 UI
• 通过 Qt Signal/Slot 机制与主线程通信

错误处理

• 所有 shell 命令执行都有统一的错误处理
• 关键错误会弹出 QMessageBox 提示用户
• 详细错误信息写入日志

系统命令依赖

应用依赖以下 Linux 命令行工具：

功能	命令
块设备信息	lsblk
分区操作	parted, partprobe
文件系统	mkfs.ext4, mkfs.xfs, mkfs.ntfs, mkfs.vfat
挂载管理	mount, umount, findmnt
RAID 管理	mdadm
LVM 管理	pvcreate, vgcreate, lvcreate, pvs, vgs, lvs 等
进程查询	lsof, fuser

安全考虑

1. 权限要求: 应用需要 root/sudo 权限执行存储管理操作
2. 危险操作确认: 格式化、删除分区/卷等操作都有确认对话框
3. 设备占用检测: OccupationResolver 模块检测并解除设备占用（卸载挂载点、停止进程）后才执行操作
4. fstab 备份: 修改 /etc/fstab 前建议用户手动备份

已知限制

• 仅支持 Linux 系统
• 需要图形桌面环境
• 部分操作（如 RAID 创建）可能需要密码输入
• 不支持 LVM/RAID 的降级恢复等高级场景

调试建议

1. 查看日志输出（GUI 底部 QTextEdit 或控制台）
2. 检查系统命令是否安装：which parted mdadm lvm
3. 手动测试命令：sudo lsblk -J
4. 检查权限：确保用户有 sudo 权限或已切换到 root

---

跨平台兼容性 (新增)

本项目现在支持 Arch Linux 和 CentOS/RHEL 8 两大平台，统一使用 Tkinter 作为 GUI 后端。

平台支持矩阵

平台	Python版本	GUI后端	状态
Arch Linux	3.7+	Tkinter	✓ 完全支持
CentOS 8	3.6	Tkinter	✓ 完全支持
CentOS 8 Stream	3.9+	Tkinter	✓ 完全支持
RHEL 8	3.6	Tkinter	✓ 完全支持
Ubuntu/Debian	3.x	Tkinter	✓ 支持

为什么统一使用 Tkinter?

• Python 内置: 无需额外安装
• 跨版本兼容: 支持 Python 3.6+ (包括 CentOS 8 的 Python 3.6)
• 跨发行版: 所有 Linux 发行版都支持
• 打包简单: PyInstaller 处理更稳定

新文件说明

• main.py - 统一入口点，使用 Tkinter
• platform_compat.py - 平台检测模块
• system_compat.py - 系统命令兼容性模块
• build-compat.sh - 跨平台构建脚本
• disk-manager-compat.spec - PyInstaller 兼容配置
• run.sh - 启动脚本

启动方式

# 统一入口（推荐）
python3 main.py

# 或使用启动脚本
./run.sh

# 或直接运行主模块
python3 mainwindow_tkinter.py

Python 3.6 兼容性修改

为支持 CentOS 8 的 Python 3.6，进行了以下修改：

1. system_info.py - _run_command() 方法避免使用 capture_output 和 text 参数
2. platform_compat.py - _command_exists() 使用 stdout/stderr 代替 capture_output
3. system_compat.py - 版本检测使用 stdout/stderr 管道
4. smart_monitor.py - 为 dataclasses 提供回退实现
5. disk_operations_tkinter.py - 修复 f-string 中文引号问题

系统命令兼容性

命令	Arch Linux	CentOS 8
lsblk	lsblk -J (JSON)	lsblk -J (JSON)
lsblk 列	支持 PATH	不支持 PATH，使用 KNAME
LVM JSON	支持	支持

构建打包

# 使用新的构建脚本（自动检测平台）
./build-compat.sh

# 或手动打包
pyinstaller -F disk-manager-compat.spec

打包后的可执行文件可在两个系统上运行，启动时会自动检测并选择合适的 GUI 后端。