first commit

2026-02-07 14:58:56 +08:00
commit 8c53b9c0a0
19 changed files with 4540 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,275 @@
+# 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 交互处理可能需要调整