# 使用文档 — Linux 根目录自动扩容脚本

## 目录

- [1. 概述](#1-概述)
- [2. 环境准备](#2-环境准备)
- [3. 安装与部署](#3-安装与部署)
- [4. 基本使用](#4-基本使用)
- [5. 运行模式详解](#5-运行模式详解)
- [6. 执行流程详解](#6-执行流程详解)
- [7. 各发行版使用示例](#7-各发行版使用示例)
- [8. LVM 架构详解](#8-lvm-架构详解)
- [9. 标准分区架构详解](#9-标准分区架构详解)
- [10. 日志说明](#10-日志说明)
- [11. 故障排查](#11-故障排查)
- [12. 注意事项](#12-注意事项)

---

## 1. 概述

本脚本用于自动将 Linux 服务器根目录 (`/`) 扩容至磁盘最大可用空间。脚本会自动识别服务器的磁盘架构（LVM 或标准分区），并根据实际架构选择对应的扩容策略，全程无需人工干预。

**核心能力：**

- 自动识别 LVM / 非 LVM 磁盘架构
- 自动识别文件系统类型（ext4 / XFS / btrfs）
- 自动安装缺失的依赖工具
- 将磁盘上所有未分配空间分配给根目录
- 支持在线扩容，无需重启服务器
- 支持模拟运行，预览扩容计划

---

## 2. 环境准备

### 2.1 前提条件

在运行脚本之前，请确认以下条件：

1. **磁盘已扩容** — 如果是云服务器（如阿里云、腾讯云、AWS 等），需要先在云平台控制台将磁盘容量扩大。例如将 `/dev/sda` 从 50GB 扩大到 100GB。

2. **存在未分配空间** — 磁盘上必须有尚未分配给分区的可用空间。可以通过以下命令检查：

   ```bash
   # 查看磁盘分区情况
   lsblk
   df -hT /
   ```

   如果 `lsblk` 显示的磁盘总大小大于根分区大小，说明有未分配空间。

3. **root 权限** — 脚本需要 root 权限运行。

### 2.2 检查当前磁盘状态

```bash
# 查看根目录使用情况和文件系统类型
df -hT /

# 查看所有磁盘和分区
lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINT

# 查看磁盘详细信息（需 root）
sudo fdisk -l
```

**判断是否有可扩容空间的示例：**

```
# lsblk 输出示例
NAME                      MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda                         8:0    0   50G  0 disk
├─sda1                      8:1    0    1M  0 part
├─sda2                      8:2    0    1G  0 part /boot
└─sda3                      8:3    0   29G  0 part
  └─ubuntu--vg-ubuntu--lv 253:0    0   20G  0 lvm  /
```

上例中，`sda` 总共 50GB，`sda3` 只用了 29GB，VG 中有约 10GB 未分配空间，可以扩容。

---

## 3. 安装与部署

### 3.1 获取脚本

**方式一：Git 克隆（推荐）**

```bash
git clone https://github.com/your-repo/LinuxDiskAutoExpansion.git
cd LinuxDiskAutoExpansion
```

**方式二：直接上传**

将 `src/main.sh` 上传到服务器任意目录。

```bash
# 使用 scp 上传
scp src/main.sh user@server:/tmp/
```

**方式三：直接下载**

```bash
wget -O /tmp/main.sh https://raw.githubusercontent.com/your-repo/LinuxDiskAutoExpansion/main/src/main.sh
```

### 3.2 设置执行权限（可选）

```bash
chmod +x main.sh
```

> 注意：即使不设置执行权限，也可以通过 `bash main.sh` 方式运行。

---

## 4. 基本使用

### 4.1 命令格式

```bash
sudo bash main.sh [选项]
```

### 4.2 可用选项

| 选项 | 缩写 | 说明 |
|------|------|------|
| `--dry-run` | 无 | 模拟运行模式，仅检测环境并输出扩容计划，不实际执行任何修改 |
| `--help` | `-h` | 显示帮助信息并退出 |

### 4.3 推荐操作流程

```bash
# 第一步：模拟运行，查看扩容计划
sudo bash main.sh --dry-run

# 第二步：确认计划无误后，正式执行
sudo bash main.sh

# 第三步：验证扩容结果
df -hT /
```

---

## 5. 运行模式详解

### 5.1 模拟运行模式（--dry-run）

模拟运行模式会执行除实际扩容以外的所有检测步骤，输出将要执行的操作命令，但不会修改任何磁盘数据。

```bash
$ sudo bash main.sh --dry-run

========================================================
       Linux 根目录自动扩容脚本
       适配 Debian / Ubuntu / CentOS 等
========================================================

[2026-09-06 10:00:01] [INFO]  检查并安装必要依赖...
[2026-09-06 10:00:01] [INFO]  检测到包管理器: apt
[2026-09-06 10:00:02] [INFO]  获取根分区信息...
[2026-09-06 10:00:02] [INFO]  根目录所在设备: /dev/mapper/ubuntu--vg-ubuntu--lv
[2026-09-06 10:00:02] [INFO]  根目录文件系统: ext4
[2026-09-06 10:00:02] [INFO]  检测到 LVM 架构
[2026-09-06 10:00:03] [INFO]  根目录所在卷组 (VG): ubuntu-vg
[2026-09-06 10:00:03] [INFO]  可用于扩容的空间: 29G
[2026-09-06 10:00:03] [INFO]  ========== 开始 LVM 模式扩容 ==========
[2026-09-06 10:00:03] [INFO]  [模拟] 将执行: lvextend -l +100%FREE /dev/mapper/ubuntu--vg-ubuntu--lv
[2026-09-06 10:00:03] [INFO]  [模拟] 将执行文件系统扩容: ext4 on /dev/mapper/ubuntu--vg-ubuntu--lv
```

**适用场景：**

- 首次使用脚本，了解扩容逻辑
- 生产环境变更前，确认扩容计划
- 排查问题时，收集磁盘环境信息

### 5.2 正式执行模式

不带任何参数直接运行，脚本将自动完成全部扩容操作。

```bash
sudo bash main.sh
```

---

## 6. 执行流程详解

脚本按以下步骤顺序执行：

### 步骤 1：权限检查

检查是否以 root 用户运行。非 root 用户将报错退出。

```
[ERROR] 此脚本需要 root 权限运行，请使用 sudo bash main.sh
```

### 步骤 2：依赖检查与安装

自动检测以下工具是否已安装，缺失时自动安装：

| 工具 | 用途 | 对应软件包 |
|------|------|-----------|
| `growpart` | 扩展磁盘分区 | `cloud-guest-utils`（Debian/Ubuntu）<br>`cloud-utils-growpart`（CentOS/RHEL） |
| `xfs_growfs` | 扩展 XFS 文件系统 | `xfsprogs` |
| `lsblk` | 查看磁盘信息 | `util-linux` |

### 步骤 3：获取根分区信息

通过 `findmnt` 获取根目录所在设备和文件系统类型。

### 步骤 4：LVM 检测

通过多重检测机制判断是否使用 LVM：
- 检查设备路径是否为 `/dev/mapper/*` 或 `/dev/dm-*`
- 通过 `lvs` 命令验证是否为 LVM 逻辑卷
- 通过 `lsblk` 的 TYPE 字段二次确认

### 步骤 5：打印当前磁盘状态

输出磁盘分区表、文件系统使用情况、LVM 信息（如适用），便于对比扩容前后变化。

### 步骤 6：检查可扩容空间

- **LVM 模式**：检查 VG 剩余空间；若不足，自动尝试扩展 PV
- **标准分区模式**：检查分区后是否有未分配扇区

### 步骤 7：执行扩容

根据检测到的架构自动执行对应的扩容命令。

### 步骤 8：验证结果

扩容完成后自动输出磁盘状态，与步骤 5 的输出对比即可确认扩容是否成功。

---

## 7. 各发行版使用示例

### 7.1 Ubuntu 20.04 / 22.04 / 24.04（LVM + ext4）

```bash
# 查看当前状态
df -hT /
# Filesystem                        Type  Size  Used Avail Use% Mounted on
# /dev/mapper/ubuntu--vg-ubuntu--lv ext4   20G  3.1G   16G  17% /

# 执行扩容
sudo bash main.sh

# 验证结果
df -hT /
# Filesystem                        Type  Size  Used Avail Use% Mounted on
# /dev/mapper/ubuntu--vg-ubuntu--lv ext4   49G  3.1G   44G   7% /
```

### 7.2 Debian 11 / 12（标准分区 + ext4）

```bash
# 查看当前状态
df -hT /
# Filesystem     Type  Size  Used Avail Use% Mounted on
# /dev/vda1      ext4   20G  2.4G   16G  13% /

# 执行扩容
sudo bash main.sh

# 验证结果
df -hT /
# Filesystem     Type  Size  Used Avail Use% Mounted on
# /dev/vda1      ext4   99G  2.4G   92G   3% /
```

### 7.3 CentOS 7 / 8 / Stream（LVM + XFS）

```bash
# 查看当前状态
df -hT /
# Filesystem               Type  Size  Used Avail Use% Mounted on
# /dev/mapper/centos-root  xfs    20G  1.8G   19G   9% /

# 先安装依赖（如果无法联网可跳过，脚本会自动处理）
# sudo yum install -y cloud-utils-growpart

# 执行扩容
sudo bash main.sh

# 验证结果
df -hT /
# Filesystem               Type  Size  Used Avail Use% Mounted on
# /dev/mapper/centos-root  xfs    49G  1.8G   48G   4% /
```

### 7.4 AlmaLinux / Rocky Linux（LVM + XFS）

与 CentOS 使用方式完全一致：

```bash
sudo bash main.sh
```

### 7.5 openSUSE / SLES

```bash
sudo bash main.sh
```

脚本会自动使用 `zypper` 安装依赖。

---

## 8. LVM 架构详解

### 8.1 识别 LVM 架构

以下特征表明服务器使用了 LVM：

- 根设备路径包含 `/dev/mapper/`，如 `/dev/mapper/ubuntu--vg-ubuntu--lv`
- `lsblk` 中 TYPE 列显示 `lvm`
- `df` 输出中的 Filesystem 为 mapper 设备

### 8.2 LVM 扩容流程

```
磁盘空间不足时的完整扩容链路：

1. growpart /dev/sda 3     ← 扩展 sda3 分区占满磁盘
2. pvresize /dev/sda3      ← 扩展物理卷
3. lvextend -l +100%FREE   ← 扩展逻辑卷
4. resize2fs / xfs_growfs  ← 扩展文件系统
```

### 8.3 LVM 术语说明

| 术语 | 缩写 | 说明 |
|------|------|------|
| 物理卷 | PV | 实际的磁盘分区或整块磁盘 |
| 卷组 | VG | 由一个或多个 PV 组成的存储池 |
| 逻辑卷 | LV | 从 VG 中划分出来的"虚拟分区"，格式化后挂载使用 |

---

## 9. 标准分区架构详解

### 9.1 识别标准分区

以下特征表明根目录使用标准分区（非 LVM）：

- 根设备路径为 `/dev/sda1`、`/dev/vda1`、`/dev/nvme0n1p1` 等
- `lsblk` 中 TYPE 列显示 `part`

### 9.2 标准分区扩容流程

```
1. growpart /dev/sda 1     ← 扩展 sda1 分区占满磁盘
2. resize2fs /dev/sda1     ← 扩展 ext4 文件系统
   或 xfs_growfs /         ← 扩展 XFS 文件系统
```

---

## 10. 日志说明

### 10.1 日志位置

```
/var/log/disk_auto_expand.log
```

### 10.2 日志内容

日志包含以下信息：

- 时间戳
- 日志级别（INFO / WARN / ERROR）
- 磁盘环境检测结果
- LVM 信息（PV / VG / LV）
- 扩容前后磁盘状态
- 执行命令的输出

### 10.3 查看日志

```bash
# 查看完整日志
cat /var/log/disk_auto_expand.log

# 查看最近的日志
tail -50 /var/log/disk_auto_expand.log

# 搜索错误信息
grep "ERROR" /var/log/disk_auto_expand.log
```

---

## 11. 故障排查

### 11.1 常见错误与解决方案

**错误：`此脚本需要 root 权限运行`**

原因：未使用 sudo 运行。

解决：
```bash
sudo bash main.sh
```

**错误：`磁盘没有足够的未分配空间进行扩容`**

原因：磁盘分区已占满全部空间，没有剩余空间可供分配。

解决：
1. 如果是云服务器，先在控制台扩大磁盘容量
2. 确认磁盘扩容后，重新运行脚本

**错误：`卷组没有足够的可用空间进行扩容`**

原因：LVM 场景下，VG 中可用空间不足 100MB。

解决：
1. 检查 PV 是否已占满磁盘：`pvs` 和 `lsblk` 对比
2. 如果 PV 未占满磁盘，脚本会自动尝试扩展
3. 如果 PV 已占满但 VG 仍无空间，说明空间已被其他 LV 占用

**错误：`无法识别包管理器，请手动安装`**

原因：使用了非主流发行版，脚本无法自动安装依赖。

解决：手动安装所需工具：
```bash
# Debian/Ubuntu
apt-get install -y cloud-guest-utils xfsprogs

# CentOS/RHEL
yum install -y cloud-utils-growpart xfsprogs
```

**警告：`growpart 执行失败，可能分区已是最大`**

说明：分区已经占满磁盘，这通常是正常情况。脚本会继续尝试后续步骤。

### 11.2 手动检查扩容是否成功

```bash
# 查看根目录大小
df -hT /

# 查看分区表
lsblk

# 查看 LVM 状态（如使用 LVM）
sudo pvs
sudo vgs
sudo lvs
```

---

## 12. 注意事项

### 12.1 安全建议

1. **首次使用请先 `--dry-run`** — 确认扩容计划无误后再正式执行
2. **重要数据请提前备份** — 虽然扩容操作是无损的，但生产环境建议做好备份
3. **检查日志** — 扩容完成后检查日志确认没有错误

### 12.2 限制说明

1. **仅支持扩容，不支持缩容** — 脚本仅将空间分配给根目录，不涉及缩小操作
2. **仅扩容根目录** — 脚本只处理 `/` 根目录的扩容，不涉及其他挂载点
3. **需要网络** — 首次运行可能需要联网安装依赖工具
4. **不支持加密分区** — 如果根分区使用了 LUKS 加密，脚本暂不支持

### 12.3 云平台扩容前置步骤

在运行脚本之前，需要先在云平台控制台扩大磁盘容量：

| 云平台 | 操作路径 |
|--------|---------|
| 阿里云 | ECS 控制台 → 实例 → 云盘 → 扩容 |
| 腾讯云 | CVM 控制台 → 实例 → 云硬盘 → 扩容 |
| 华为云 | ECS 控制台 → 云硬盘 → 扩容 |
| AWS | EC2 → Volumes → Modify Volume |
| Azure | Virtual Machines → Disks → Resize |

磁盘扩容完成后，运行本脚本即可完成操作系统层面的扩容。