ASPbackup 使用说明书
Minecraft Spigot 服务器高级备份插件 | Java 21 | Spigot 1.20.6+
目录
- 安装与需求
- 快速开始
- 配置文件详解
- 命令参考
- 备份流程说明
- 分布式传输设置
- 接收端应用
- 常见问题
- 权限节点
1. 安装与需求
系统需求
| 项目 |
需求 |
| Java |
21 或更高版本 (Temurin/OpenJDK) |
| 服务器 |
Spigot / Paper / Leaf 1.20.6+ |
| 存储空间 |
备份目标至少需要与来源目录相同的可用空间 |
安装步骤
- 从 Releases 下载
ASPbackup-1.0.0.jar
- 将 jar 文件放入服务器的
plugins/ 目录
- 启动(或重启)服务器
- 插件会自动生成
plugins/ASPbackup/config.yml 配置文件
- 编辑配置文件以符合您的需求
- 执行
/aspbackup reload 重新加载配置
目录结构
plugins/ASPbackup/
├── config.yml # 主配置文件
├── temp/ # 暂存目录(压缩中的备份档)
├── checkpoints/ # 中断备份的检查点文件
├── logs/ # 备份日志文件
│ ├── backup-2026-08-08.log
│ └── backup-2026-08-09.log
└── backups/ # 本地备份目标(默认,若使用 REMOTE 目标则不会有)
├── ASPbackup-20260808-143022.tar.gz
└── ASPbackup-20260809-080015.tar.gz
2. 快速开始
基本操作
# 手动触发备份
/aspbackup start
# 查看备份状态
/aspbackup status
# 查看备份历史
/aspbackup list
# 重新加载配置
/aspbackup reload
# 查看插件信息
/aspbackup info
# 查看所有命令
/aspbackup help
自动备份
插件默认启用启动备份和关闭备份,无需任何额外设定:
- 服务器启动时:延迟数秒后在后台执行备份,不阻塞服务器
- 服务器关闭时:收到
/stop 命令后拦截关闭,先执行备份,完成后才关闭
定时备份
在 config.yml 中启用定时备份:
schedule:
enabled: true
interval-minutes: 360 # 每 6 小时备份一次
backup-type: "full"
target-id: "remote-cluster"
quiet-hours:
- "06:00-22:00" # 此时间段内不执行备份
3. 配置文件详解
3.1 备份设置 (backup)
backup:
# 服务器启动时是否自动备份
auto-on-start: true
# 服务器关闭时是否自动备份
auto-on-shutdown: true
# 启动备份的延迟秒数(让服务器稳定后再备份)
start-delay-seconds: 10
# 备份主文件名称(用于暂存档命名)
backup-name: "ASPbackup"
# 阻塞式备份超时秒数(防止远程传输失败时阻塞服务器)
blocking-timeout-seconds: 120
# 暂存目录
temp-directory: "plugins/ASPbackup/temp"
# 单次备份最大大小(MB),0 = 无限制
max-backup-size-mb: 0
# 备份完成后是否验证完整性
verify-after-backup: true
# 压缩设置
compression:
format: "targz" # "zip" 或 "targz"
level: 9 # 1 (最快) 到 9 (最小)
3.2 备份来源 (sources)
每个来源可设定 category 分类标签,备份完成后会按分类显示统计信息。
backup:
sources:
# 玩家背包数据
- path: "world/playerdata"
name: "玩家背包数据"
category: "player-data"
exclude:
- "**/*.dat"
- "**/*.dat_old"
max-depth: 10
# 玩家统计数据
- path: "world/stats"
name: "玩家统计数据"
category: "player-data"
exclude:
- "**/*.lock"
max-depth: 10
# 玩家进度数据
- path: "world/advancements"
name: "玩家进度数据"
category: "player-data"
exclude:
- "**/*.lock"
max-depth: 10
# 所有插件文件
- path: "plugins"
name: "所有插件文件"
category: "plugins"
exclude:
- "**/ASPbackup/**" # 排除备份插件自身
- "**/dynmap/web/**"
- "**/*.log"
max-depth: 50
# 插件配置文件(仅备份设定档)
- path: "plugins"
name: "插件配置文件"
category: "plugin-configs"
include:
- "**/config.yml"
- "**/config.yaml"
- "**/settings.yml"
- "**/*.properties"
- "**/*.json"
- "**/*.toml"
- "**/*.conf"
exclude:
- "**/ASPbackup/**"
- "**/dynmap/web/**"
- "**/*.db"
max-depth: 30
来源字段说明:
| 字段 |
类型 |
说明 |
path |
字符串 |
相对于服务器根目录的路径 |
name |
字符串 |
显示名称 |
category |
字符串 |
分类标签,用于备份统计和 tar.gz 内部分类 |
include |
列表 |
仅包含符合这些 glob 模式的文件(空 = 全部) |
exclude |
列表 |
排除符合这些 glob 模式的文件 |
max-depth |
整数 |
最大目录深度 |
3.3 文件过滤规则 (file-filter)
backup:
file-filter:
# 包含的文件(glob 模式)
include:
- "**/*"
# 排除的文件(全局,对所有来源生效)
exclude:
- "**/*.tmp"
- "**/*.lock"
- "**/*.pid"
- "**/ASPbackup/**" # 避免备份的备份
# 最小文件大小(字节),0 = 不限制
min-size-bytes: 0
# 最大文件大小(字节),0 = 不限制
max-size-bytes: 0
Glob 模式说明:
| 模式 |
说明 |
示例 |
* |
匹配任意字符(不含 /) |
*.log 匹配所有 .log 文件 |
** |
匹配任意目录层级 |
**/ASPbackup/** 匹配所有 ASPbackup 目录下的文件 |
? |
匹配单个字符 |
region/r.?.?.mca |
3.4 备份目标 (targets)
backup:
targets:
# 远程分布式目标(传输到接收端)
- id: "remote-cluster"
type: "REMOTE"
retention-count: 3
min-free-space-mb: 10240
# 本地目标
# - id: "local"
# type: "LOCAL"
# path: "backups/"
# retention-count: 10
# min-free-space-mb: 1024
# NAS 目标(挂载的网络磁盘)
# - id: "nas"
# type: "NAS"
# path: "/mnt/nas/minecraft-backups/"
# retention-count: 5
# min-free-space-mb: 5120
目标类型:
| 类型 |
说明 |
LOCAL |
本地目录,path 为相对于服务器根目录的路径 |
NAS |
网络磁盘,path 为绝对路径(如 /mnt/nas/...) |
REMOTE |
远程接收端,通过 TCP 传输 |
3.5 分布式传输设置 (transfer)
transfer:
# 分块大小(KB)— 用于进度显示
chunk-size-kb: 1024
# 并行传输线程数
parallel-threads: 4
# 连接超时(毫秒)
connect-timeout-ms: 10000
# 读取超时(毫秒)
read-timeout-ms: 30000
# 失败重试次数
retry-count: 3
# 重试间隔(毫秒)
retry-delay-ms: 5000
# 负载均衡策略:"round_robin" 或 "least_loaded"
load-balance-strategy: "least_loaded"
# 传输节点列表
nodes:
- id: "node-1"
host: "127.0.0.1"
port: 9876
auth-token: "remote-cluster"
enabled: true
weight: 1
3.6 检查点设置 (checkpoint)
checkpoint:
# 启用中断续传
enabled: true
# 检查点存储目录
directory: "plugins/ASPbackup/checkpoints"
# 自动清理超过 N 天的检查点
max-age-days: 7
3.7 日志设置 (logging)
logging:
# 日志级别:"DEBUG"、"INFO"、"WARN"、"ERROR"
level: "INFO"
# 日志目录
directory: "plugins/ASPbackup/logs"
# 保留天数
retention-days: 30
# 详细传输日志
verbose-transfer: false
# 同时输出到控制台
console-output: true
3.8 磁盘空间监控 (disk-space)
disk-space:
# 可用空间低于此百分比时警告
warn-threshold-percent: 15
# 检查间隔(秒)
check-interval-seconds: 300
4. 命令参考
命令总览
| 命令 |
权限 |
说明 |
/aspbackup start |
aspbackup.start |
手动开始备份 |
/aspbackup stop <id> |
aspbackup.stop |
停止备份(保存检查点) |
/aspbackup status [id] |
aspbackup.status |
查看备份状态 |
/aspbackup resume <id> |
aspbackup.resume |
从检查点续传 |
/aspbackup list |
aspbackup.list |
列出备份历史 |
/aspbackup nodes |
aspbackup.nodes |
管理传输节点 |
/aspbackup verify <id> |
aspbackup.verify |
验证备份完整性 |
/aspbackup reload |
aspbackup.reload |
重新加载配置 |
/aspbackup about |
aspbackup.command |
显示插件信息 |
/aspbackup info |
aspbackup.command |
显示运行状态 |
/aspbackup help |
aspbackup.command |
显示命令帮助 |
详细命令说明
/aspbackup start
/aspbackup start [--full|--incremental] [--target <目标ID>]
启动一个新的备份任务。
参数:
--full:完整备份(默认)
--incremental:增量备份(仅备份变更的文件)
--target <id>:指定目标(默认使用第一个配置的目标)
示例:
/aspbackup start
/aspbackup start --target remote-cluster
/aspbackup start --full --target local
输出:
[ASPbackup] 备份任务已启动:a1b2c3d4
/aspbackup stop
/aspbackup stop <任务ID>
安全停止正在运行的备份任务,并保存检查点以便后续续传。
示例:
/aspbackup stop a1b2c3d4
/aspbackup status
/aspbackup status [任务ID]
查看备份任务的状态。
不带参数:显示所有任务摘要
带任务ID:显示该任务的详细进度
示例输出(摘要):
===== 备份任务 =====
[COMPLETED] a1b2c3d4 - 100.0% - FULL
[PAUSED] e5f6g7h8 - 47.3% - FULL
[RUNNING] i9j0k1l2 - 12.8% - FULL
/aspbackup resume
/aspbackup resume <任务ID>
从中断的检查点恢复备份任务。
注意:仅能恢复状态为 PAUSED 的任务。
/aspbackup list
/aspbackup list [--active|--completed|--failed|--all] [--page <页码>]
列出备份任务历史。
示例:
/aspbackup list --completed
/aspbackup list --all --page 2
/aspbackup nodes
/aspbackup nodes list
/aspbackup nodes status [节点ID]
管理分布式传输节点。
/aspbackup verify
/aspbackup verify <任务ID>
验证已完成备份的 SHA-256 完整性。
/aspbackup reload
/aspbackup reload
重新加载 config.yml,无需重启服务器。
注意:正在执行的备份任务不受影响,新配置将在下一次备份时生效。
/aspbackup about
/aspbackup about
显示插件名称、版本、作者和网站信息。
/aspbackup info
/aspbackup info
显示当前运行状态,包括:
- 启动/关闭备份是否启用
- 定时备份状态
- 备份来源数量
- 备份目标数量
- 传输节点数量
- 活动备份任务数
5. 备份流程说明
5.1 完整备份流程
1. 触发备份(手动/自动/定时)
│
2. 保存世界数据(主线程)
├── /save-off → 关闭自动存档
├── /save-all → 强制保存所有世界
└── /save-on → 重新开启自动存档
│
3. 检查磁盘空间
├── 不足 → 终止备份,记录错误
└── 充足 → 继续
│
4. 收集文件(按 category 分类,套用过滤规则)
│
5. 显示分类统计
──────────────────────────────────
备份内容汇总:
player-data:45 个文件,12.3 MB
plugins:120 个文件,48.7 MB
plugin-configs:15 个文件,0.3 MB
总计:180 个文件,61.3 MB
──────────────────────────────────
│
6. 压缩文件(Tar.gz,SHA-256 校验)
│
7. 传输到目标
├── LOCAL → 复制到本地目录
├── NAS → 复制到网络磁盘
└── REMOTE → TCP 整档传输到接收端(含 ACK 确认)
│
8. 验证完整性
│
9. 清理旧备份(保留策略)
│
10. 完成 → 记录日志
5.2 备份分类系统
备份文件在 tar.gz 内按 category 分类组织,结构如下:
player-data/
world/playerdata/xxx.dat
world/stats/xxx.json
world/advancements/xxx.json
plugins/
plugins/LuckPerms/...
plugins/Essentials/...
plugin-configs/
plugins/Essentials/config.yml
plugins/LuckPerms/config.yml
- player-data:玩家背包、统计、进度数据
- plugins:所有插件文件(排除 ASPbackup 自身、大型网页资源、日志)
- plugin-configs:仅插件设置文件(.yml, .json, .properties, .toml, .conf)
5.3 启动/关闭备份机制
- 启动备份:
save-off/save-all/save-on 在主线程,备份在后台线程异步执行,不阻塞主线程
- 关闭备份:拦截
/stop 命令,先执行备份(阻塞),备份完成后再关闭服务器
- 手动备份:非阻塞,玩家可以继续游戏
5.4 中断与续传流程
备份进行中
│
管理员执行 /aspbackup stop
│
├── 设置中断标记
├── 在安全的边界点暂停
├── 保存检查点 → plugins/ASPbackup/checkpoints/<id>.properties
└── 任务状态变为 PAUSED
管理员稍后执行 /aspbackup resume
│
├── 加载检查点
├── 从中断位置继续收集文件
└── 完成后删除检查点
5.5 备份任务状态
| 状态 |
说明 |
INITIALIZING |
任务已创建,正在初始化 |
COLLECTING |
正在收集要备份的文件 |
COMPRESSING |
正在压缩文件 |
TRANSFERRING |
正在传输到目标 |
VERIFYING |
正在验证完整性 |
PAUSED |
已暂停,检查点已保存 |
COMPLETED |
备份成功完成 |
CANCELLED |
备份已被取消 |
FAILED |
备份失败 |
6. 分布式传输设定
6.1 架构说明
┌─────────────────┐
│ Minecraft 服务器 │ (ASPbackup 插件)
│ 192.168.1.100 │
└────────┬────────┘
│ TCP 9876
├──────────────┬──────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 接收端 #1 │ │ 接收端 #2 │ │ 接收端 #3 │
│ 10.0.0.101 │ │ 10.0.0.102 │ │ 10.0.0.103 │
└─────────────┘ └─────────────┘ └─────────────┘
6.2 负载均衡策略
轮询(Round Robin):
最少负载(Least Loaded):
- 将备份分配给目前传输量最少的节点
- 考虑节点权重(weight)
- 节点失败时增加虚拟负载作为惩罚
6.3 传输协议
目前使用整档传输模式,一次传送完整备份文件。
握手阶段:
插件 → 接收端:4字节长度 + 协议版本(2B) + token长度(1B) + token + node_id长度(1B) + node_id + capabilities(1B)
接收端 → 插件:4字节长度 + ACK(4B, 0=成功)
文件传输:
插件 → 接收端:4字节(任务ID长度) + 任务ID(UTF-8) + 8字节(文件大小) + 文件数据(含进度显示)
接收端 → 插件:4字节长度 + 2字节(任务ID长度) + 任务ID + 1字节(成功标志) + 2字节(消息长度) + 消息
接收端输出:
received-backups/{任务ID}/backup.tar.gz
7. 接收端应用程序
7.1 快速启动
Windows:
java -jar ASPbackup-receiver-1.0.0.jar --port 9876 --dir D:\receiver\received-backups
Linux/macOS:
java -jar ASPbackup-receiver-1.0.0.jar \
--port 9876 \
--dir /mnt/backups/minecraft \
--token your-secure-token
7.2 接收端目录结构
receiver/
├── ASPbackup-receiver-1.0.0.jar # 接收端主程序
└── received-backups/ # 接收的备份输出目录
└── <任务ID>/
└── backup.tar.gz
7.3 参数说明
| 参数 |
默认值 |
说明 |
--port |
9876 |
监听端口号 |
--dir |
received-backups |
备份输出目录 |
--token |
change-me |
认证令牌(必须与插件 auth-token 一致) |
--help |
- |
显示帮助 |
7.4 安全建议
- 使用防火墙:限制只有 Minecraft 服务器 IP 可以连接接收端端口
- 使用强密码令牌:避免使用默认的
change-me
- 使用 VPN:如果接收端在远程网络,建议通过 VPN 连接
- 定期更换令牌:定期更新
auth-token 并重启两端服务
8. 常见问题
Q: 备份失败,提示 "Insufficient disk space"
原因:目标磁盘空间不足。
解決方案:
- 清理目标目录的旧备份
- 调整
retention-count 减少保留数量
- 降低
min-free-space-mb 阈值
- 扩充目标磁盘容量
Q: 备份过程中服务器 lag
原因:压缩大型文件消耗 CPU 和 I/O。
解决方案:
- 降低
compression.level(如从 9 降到 3)
- 排除不必要的目录(如
dynmap/web/)
- 使用
quiet-hours 在玩家较少的时段执行定时备份
- 增加
start-delay-seconds 避免启动时服务器尚未稳定
Q: 备份越来越大?
原因:ASPbackup 上一次备份的文件被包含在本次备份中。
解决方案:
已在配置中默认排除 **/ASPbackup/**,确保备份插件自身的日志、检查点、暂存档不会被重复备份。如果仍有问题,检查 file-filter.exclude 和各来源的 exclude 是否正确设定。
Q: 如何恢复备份?
备份文件为标准的 .tar.gz 格式,已按分类组织:
# 解压缩
tar -xzf backup.tar.gz
# 解压后结构:
# player-data/world/playerdata/...
# plugins/plugins/...
# plugin-configs/plugins/.../config.yml
将对应目录内容复制回服务器即可。
Q: 中断的备份如何续传?
# 1. 查看暂停的任务
/aspbackup status
# 2. 续传
/aspbackup resume <任务ID>
# 3. 如果检查点损坏,可以删除检查点文件重新开始
rm plugins/ASPbackup/checkpoints/<任务ID>.properties
Q: 如何变更备份目标?
编辑 config.yml 中的 backup.targets 后:
/aspbackup reload
/aspbackup start --target <新目标ID>
Q: 接收端连接失败?
原因:接收端未启动、端口号错误、防火墙阻挡、或 JAR 版本过旧。
解决方案:
- 确认接收端已启动并监听正确端口号
- 检查
config.yml 中 nodes.host 和 nodes.port 是否正确
- 确认插件和接收端都是最新版本
- 检查防火墙是否允许该端口号
9. 权限节点
| 权限节点 |
说明 |
默认 |
aspbackup.command |
使用 /aspbackup 命令 |
OP |
aspbackup.start |
手动开始备份 |
OP |
aspbackup.stop |
停止备份任务 |
OP |
aspbackup.status |
查看备份状态 |
OP |
aspbackup.resume |
续传中断的备份 |
OP |
aspbackup.list |
列出备份历史 |
OP |
aspbackup.nodes |
管理传输节点 |
OP |
aspbackup.verify |
验证备份完整性 |
OP |
aspbackup.reload |
重新加载配置 |
OP |
aspbackup.* |
所有权限(通配符) |
OP |
权限设置示例(LuckPerms)
# 给予管理员所有权限
/lp user Admin permission set aspbackup.*
# 给予协管员基本权限
/lp group moderator permission set aspbackup.command
/lp group moderator permission set aspbackup.status
/lp group moderator permission set aspbackup.list
技术支持
- GitHub Issues:
- 授权: Apache License 2.0
ASPbackup v1.0.0 — 文档最后更新:2026-08-13
评论 0
登录后参与评分
还没有评论,来抢沙发吧