database-mysql/LinuxDiskAutoExpansion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
database-mysql
2026-09-06 12:58:04 +08:00
commit 2477352d6f
10 changed files with 1393 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

494
USAGE.md Normal file
View File

@@ -0,0 +1,494 @@
# 使用文档 — 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 |
磁盘扩容完成后，运行本脚本即可完成操作系统层面的扩容。