# 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 交互处理可能需要调整