495 lines
13 KiB
Markdown
495 lines
13 KiB
Markdown
# 使用文档 — 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://git.opensource-studio.info/database-mysql/LinuxDiskAutoExpansion.git
|
||
cd LinuxDiskAutoExpansion
|
||
```
|
||
|
||
**方式二：直接上传**
|
||
|
||
将 `src/main.sh` 上传到服务器任意目录。
|
||
|
||
```bash
|
||
# 使用 scp 上传
|
||
scp src/main.sh user@server:/tmp/
|
||
```
|
||
|
||
**方式三：直接下载**
|
||
|
||
```bash
|
||
wget -O /tmp/main.sh https://git.opensource-studio.info/database-mysql/LinuxDiskAutoExpansion/src/commit/8bce42bc846f6404052c64a6511a29e1b1bc7d95/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 |
|
||
|
||
磁盘扩容完成后，运行本脚本即可完成操作系统层面的扩容。
|