database-mysql/LinuxDiskAutoExpansion

Fork 0

Files

database-mysql 2fa1eb2ba3 update USAGE.md

2026-09-06 18:27:30 +08:00

13 KiB

Raw Blame History

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

1. 概述

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

核心能力：

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

2. 环境准备

2.1 前提条件

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

磁盘已扩容 — 如果是云服务器（如阿里云、腾讯云、AWS 等），需要先在云平台控制台将磁盘容量扩大。例如将 /dev/sda 从 50GB 扩大到 100GB。
存在未分配空间 — 磁盘上必须有尚未分配给分区的可用空间。可以通过以下命令检查：
```
# 查看磁盘分区情况
lsblk
df -hT /
```
如果 lsblk 显示的磁盘总大小大于根分区大小，说明有未分配空间。
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://git.opensource-studio.info/database-mysql/LinuxDiskAutoExpansion/src/commit/8bce42bc846f6404052c64a6511a29e1b1bc7d95/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

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

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

解决：

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

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

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

解决：

检查 PV 是否已占满磁盘：pvs 和 lsblk 对比
如果 PV 未占满磁盘，脚本会自动尝试扩展
如果 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 安全建议

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

12.2 限制说明

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

12.3 云平台扩容前置步骤

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

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

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

13 KiB Raw Blame History Unescape Escape