database-mysql/LinuxDiskAutoExpansion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2957ef1f1e17ab286488cc6b2b1c58a8c39a9b9d
LinuxDiskAutoExpansion/USAGE.md
database-mysql 487959f30f debug
2026-09-06 13:17:57 +08:00

13 KiB
Raw Blame History

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

目录

1. 概述

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

核心能力：

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

2. 环境准备

2.1 前提条件

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

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

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

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

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

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

2.2 检查当前磁盘状态

# 查看根目录使用情况和文件系统类型
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 克隆（推荐）

git clone https://git.opensource-studio.info/database-mysql/LinuxDiskAutoExpansion.git
cd LinuxDiskAutoExpansion

方式二：直接上传

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

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

方式三：直接下载

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

3.2 设置执行权限（可选）

chmod +x main.sh

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

4. 基本使用

4.1 命令格式

sudo bash main.sh [选项]

4.2 可用选项

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

4.3 推荐操作流程

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

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

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

5. 运行模式详解

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

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

$ 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 正式执行模式

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

sudo bash main.sh

6. 执行流程详解

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

步骤 1：权限检查

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

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

步骤 2：依赖检查与安装

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

工具 用途 对应软件包
growpart 扩展磁盘分区 cloud-guest-utils（Debian/Ubuntu）
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）

# 查看当前状态
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）

# 查看当前状态
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）

# 查看当前状态
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 使用方式完全一致：

sudo bash main.sh

7.5 openSUSE / SLES

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 查看日志

# 查看完整日志
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 运行。

解决：

sudo bash main.sh

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

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

解决：

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

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

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

解决：

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

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

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

解决：手动安装所需工具：

# Debian/Ubuntu
apt-get install -y cloud-guest-utils xfsprogs

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

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

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

11.2 手动检查扩容是否成功

# 查看根目录大小
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

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