原创 工具 PluralBackupJava 1.0.9

[MD] # PluralBackup (Java版) > Minecraft Java版服务器自动备份插件，支持 Spigot / Paper / Purpur / Leaves / Bukkit，兼容 1.18+ 版本。 > > Copyright © PluralTeam. All rights reserved. ## 简介 PluralBackup 是一款面向 Minecraft Java 版服务器的自动热备份插件，提供完整的本地备份、压缩、在线还原、多云端上传以及备份失败告警能力。插件采用异步备份机制，最大程度降低备份过程对服务器主线程的影响，避免 Watchdog 超时崩溃。 ## 功能特性 - **定时自动备份**：可配置备份间隔，默认 60 分钟一次 - **时刻模式备份**：按指定时区的特定时刻触发备份（支持24/12小时制） - **手动备份触发**：通过命令立即执行备份 - **启动备份**：服务器启动后自动执行一次备份（可选） - **无停机备份**：异步执行，不阻塞主线程 - **世界保存控制**：备份前保存世界，备份期间暂停自动保存防止数据不一致 - **ZIP 压缩**：基于 JDK 原生 `java.util.zip` 实现，兼容性最好（zst / 7z / tar.gz 因兼容性问题已暂时下线） - **在线还原**：异步还原备份，自动解压，自动卸载/重载世界 - **备份文件管理**：列表、还原、删除、自动清理旧备份，保留指定数量的最近备份（手动GitHub上传后也会清理） - **多云端上传**：本地目录、FTP/FTPS、WebDAV、百度网盘、123云盘 - **GitHub 备份**：通过 GitHub Release API 上传/下载备份，支持自动创建私人仓库 - **告警通知**：备份失败时通过邮件、飞书机器人、钉钉机器人、Discord、Telegram发送告警 - **多语言支持**：自动检测服务器语言，内置中英文，支持自定义语言文件 - **进度通知**：备份开始/完成/失败时广播消息给全服玩家 - **Tab 自动补全**：命令支持 Tab 补全 ## 环境要求 - Minecraft Java 版 1.18 或更高版本 - Java 17 或更高版本 - 服务端软件：Spigot / Paper / Purpur / Leaves / Bukkit（推荐 Paper） ## 安装 1. 将 `PluralBackupJava-1.0.9.jar` 放入服务器的 `plugins` 目录 2. 启动服务器，插件会自动生成默认配置文件 `plugins/PluralBackup/config.yml` 3. 根据需要修改配置文件 4. 执行 `/backup reload` 重载配置，或重启服务器使配置生效 ## 命令 所有命令需要 `pluralbackup.admin` 权限（默认 OP 拥有）。 | 命令 | 说明 | | --- | --- | | `/backup now` | 立即执行一次备份 | | `/backup list` | 列出所有本地备份 | | `/backup restore <名称>` | 恢复指定备份（会重新加载世界） | | `/backup delete <名称>` | 删除指定备份 | | `/backup clean` | 清理旧备份，保留最近 N 个 | | `/backup reload` | 重新加载配置文件 | | `/backup status` | 查看插件运行状态 | | `/backup github-list` | 查看 GitHub 上的备份版本 | | `/backup github-download <版本号>` | 从 GitHub 下载指定版本 | | `/backup github-upload` | 备份服务器并上传到 GitHub | 命令别名：`/pbackup`、`/pluralbackup` ## 配置文件 配置文件位于 `plugins/PluralBackup/config.yml`，主要配置项说明： ```yaml # 基本备份设置 backup: auto-backup: true # 是否启用自动备份（间隔模式） interval-minutes: 60 # 自动备份间隔（分钟），仅间隔模式生效 backup-on-start: false # 服务器启动时是否执行一次备份 broadcast-message: true # 是否广播备份消息 # 定时备份（按时刻触发，与间隔模式独立，可同时启用） schedule: enabled: false # 是否启用时刻模式 timezone: "Asia/Shanghai" # 触发时区，例如 Asia/Shanghai、America/New_York、Europe/London use-24-hour-format: true # 是否使用 24 小时制（false 则使用 12 小时制，需带 AM/PM） times: # 触发时刻列表 - "00:00" # 24小时制示例：["00:00", "06:00", "12:00", "18:00"] - "12:00" # 12小时制示例：["12:00 AM", "06:00 AM", "12:00 PM", "06:00 PM"] backup-dir: "backups" # 备份存放目录（相对插件数据目录） max-backups: 10 # 最大备份数量（0=不限制） compress: true # 是否压缩（兼容字段，被下方 compression.type 覆盖） # 压缩配置（覆盖上方 compress 字段） compression: type: "zip" # zip / none（zst/7z/tar.gz 已下线，非 none 值均按 zip 处理） level: 6 # 压缩级别（1-9） threads: 0 # 压缩线程数（保留字段，ZIP 始终单线程） exclude-dirs: # 排除不需要备份的目录（相对服务器根目录） - "plugins/PluralBackup/backups" - "logs" - "cache" exclude-files: # 排除不需要备份的单个文件（按文件名匹配，所有目录下同名文件都会被排除） - "session.lock" # Minecraft 服务器运行时的世界锁文件，无法复制且无需备份 # 云端上传 cloud: enabled: false type: "local" # local / ftp / webdav / baidu / pan123 upload-threads: 4 # 上传并发数（百度网盘上限8，123云盘上限4） download-threads: 4 # 下载并发数（GitHub Range，上限8） local: path: "cloud-backups" ftp: host: "127.0.0.1" port: 21 username: "ftpuser" password: "ftppass" remote-dir: "/backups" use-ssl: false webdav: url: "https://dav.example.com/backups" username: "user" password: "pass" # 百度网盘（https://pan.baidu.com/union/console） baidu: app-id: "" app-secret: "" app-folder: "" access-token: "" # 留空则自动获取并缓存 # 123云盘（https://www.123pan.cn/developer） pan123: client-id: "" client-secret: "" access-token: "" # 留空则自动获取并缓存 parent-folder-id: 0 # 告警通知 notification: enabled: false email: enabled: false smtp-host: "" # 例如 smtp.qq.com smtp-port: 465 use-ssl: true username: "" password: "" # 授权码 from: "" to: "" subject: "PluralBackup 备份异常告警" feishu: enabled: false webhook: "" secret: "" dingtalk: enabled: false webhook: "" secret: "" # GitHub 备份 github: enabled: false token: "your-github-token" # 需要 repo 权限 owner: "your-username" repo: "PluralGamneBackup" # 仓库名称 auto-create-repo: true # 仓库不存在时自动创建私人仓库 # 备份行为 save-world-before-backup: true # 备份前保存世界 pause-autosave-during-backup: true # 备份期间暂停自动保存 file-copy-retry-count: 3 # 文件复制失败重试次数 file-copy-retry-delay-ms: 500 # 文件复制重试间隔（毫秒） ``` ## 压缩格式 插件当前仅支持 ZIP 压缩，通过 `compression.type` 配置： | 类型 | 扩展名 | 算法 | 级别范围 | 特点 | |------|--------|------|----------|------| | `zip` | .zip | DEFLATE | 1-9 | JDK 原生实现，兼容性最好 | | `none` | （目录） | 无 | - | 不压缩，直接保存目录 | > **说明**：zst / 7z / tar.gz 格式因在实际服务端（Purpur 26.2 等）存在兼容性问题，已暂时下线。传入任何非 `none` 的 `compression.type` 值均按 ZIP 处理。Nukkit 版不受影响，仍保留全部 4 种压缩格式。 级别通过 `compression.level` 配置（范围 1-9）。 ## 云端备份 ### 百度网盘 1. 访问 https://pan.baidu.com/union/console 创建应用，获取 `app-id` 与 `app-secret` 2. 填写 `baidu.app-folder`（即申请接入时填写的"产品名称"） 3. 设置 `cloud.type: "baidu"` 4. 首次上传时自动获取 access_token 并缓存 5. 备份文件存放于 `/我的应用数据/{app-folder}/backup_xxx.zip` ### 123 云盘 1. 访问 https://www.123pan.cn/developer 创建应用，获取 `client-id` 与 `client-secret` 2. 设置 `cloud.type: "pan123"` 3. 首次上传时自动获取 access_token 并缓存 4. 通过 `parent-folder-id` 指定目标文件夹，0 表示根目录 ## 告警通知 备份任务出现异常时，会自动通过已启用的渠道发送告警： - **邮件**：通过 SMTP 发送（支持 SSL/TLS），使用 jakarta.mail 实现 - **飞书**：通过自定义机器人 Webhook 发送，支持加签校验 - **钉钉**：通过自定义机器人 Webhook 发送，支持加签校验 - **Discord**：通过频道 Webhook 发送，使用 Embed 格式（海外推荐） - **Telegram**：通过 Bot API 发送，支持 Markdown 格式（海外推荐） 通知内容包含失败类型与异常信息，便于运维人员快速定位。 ## 多语言支持 插件支持多语言，可通过config.yml的 `language` 配置项指定： ```yaml # 留空则自动检测服务器语言；手动指定如 "zh_CN"、"en_US"、"ja_JP" 等 language: "" ``` **语言优先级**：config.yml配置 > 自动检测服务器语言 > 默认英语 - **Java版**：通过读取 `server.properties` 的 `settings.language` 字段检测 内置语言： - `en_US` - 英语（默认） - `zh_CN` - 简体中文 语言文件位于 `plugins/PluralBackup/lang/` 目录，首次启动自动生成。用户可自行编辑或添加新语言文件（如 `ja_JP.yml`、`fr_FR.yml`）。 语言代码标准化：`zh_cn` → `zh_CN`，`en-us` → `en_US` ## GitHub 备份说明 ### 工作机制 GitHub备份已集成到主备份流程中（不再使用独立调度器）： - **间隔模式触发**：`auto-backup: true` 时，每隔 `interval-minutes` 分钟备份，备份完成后如果 `github.enabled: true` 则自动上传 - **时刻模式触发**：`schedule.enabled: true` 时，在指定时刻备份，备份完成后如果 `github.enabled: true` 则自动上传 - **手动触发**：执行 `/backup github-upload` 立即备份并上传 1. 在 GitHub 创建 Personal Access Token，需要 `repo` 权限，建议不设置过期时间 2. 在配置文件中填入 `token`、`owner`、`repo` 3. 启用 `github.enabled: true` 4. 仓库不存在时会自动创建私人仓库（需 `auto-create-repo: true`） 5. 空仓库会自动初始化（写入 README.md），否则无法创建 Release 6. 备份文件通过 Release Asset 上传，单文件上限 2GB 7. GitHub 定时备份与本地备份共用 `interval-minutes` 间隔 8. 网络操作（上传/下载）全部异步执行，不阻塞主线程 9. 手动执行 `/backup github-upload` 后会自动清理本地旧备份（受 `max-backups` 限制） ## 双模式定时备份 插件支持两种独立的定时触发模式，可同时启用： **1. 间隔模式**（`backup.auto-backup: true` + `backup.interval-minutes: 60`） - 每隔 N 分钟执行一次备份 - 适合需要高频备份的场景 **2. 时刻模式**（`backup.schedule.enabled: true`） - 在指定时区的特定时刻执行备份 - 支持自定义时区（如 `Asia/Shanghai`、`America/New_York`、`Europe/London`） - 支持 24 小时制（`HH:mm`，如 `00:00`、`12:00`、`18:30`） - 支持 12 小时制（`hh:mm a`，如 `12:00 AM`、`06:00 PM`） - 可配置多个触发时刻 两种模式可同时启用，互不冲突。例如：间隔模式每小时备份一次，时刻模式每天 00:00 和 12:00 额外备份。 ## 权限 | 权限节点 | 默认 | 说明 | | --- | --- | --- | | `pluralbackup.admin` | OP | 允许使用所有备份管理命令 | ## 技术实现要点 - **异步备份**：使用 `ExecutorService` 单线程执行备份任务，避免并发冲突 - **主线程消息调度**：所有 `Bukkit.broadcastMessage` 和向玩家发送消息的操作通过 `Bukkit.getScheduler().runTask()` 调度回主线程执行 - **GitHub 网络操作**：使用 Java 11+ 的 `HttpClient`，通过 `CompletableFuture.runAsync()` 异步执行 - **依赖重定位**：使用 Maven Shade 插件将 `commons-net`、`org.json`、`jakarta.mail`、`jakarta.activation` 重定位到 `cn.plural.backup.lib`，避免与其他插件冲突 - **世界保存控制**：备份前调用 `World.save()`，备份期间通过 `World.setAutoSave(false)` 暂停自动保存 - **备份恢复**：异步卸载所有世界 → 解压并覆盖服务器目录 → 通过 `WorldCreator.createWorld()` 重新加载 - **通知发送**：通过 `CompletableFuture.runAsync()` 异步执行，不阻塞备份流程 ## 许可证 版权所有 © PluralTeam [/MD]