原创 插件 PluralBackup 1.0.3

[MD] # PluralBackup Minecraft基岩版服务器自动备份插件，支持无停机热备份、定时自动备份、手动备份触发、备份文件管理、GitHub云端备份、百度网盘/123云盘上传以及邮件/飞书/钉钉告警通知等功能。 ## 功能特性 - **无停机热备份**：异步执行备份任务，不阻塞主线程，玩家无感知 - **自动定时备份**：可配置备份间隔（默认60分钟） - **时刻模式备份**：按指定时区的特定时刻触发备份（支持24/12小时制） - **手动备份触发**：通过命令立即执行备份 - **备份文件管理**：列表查看、恢复、自动清理旧备份（手动GitHub上传后也会清理） - **备份进度通知**：备份开始/完成广播消息，支持自定义颜色代码与变量 - **ZIP压缩**：可选压缩备份文件，节省存储空间 - **GitHub云端备份**：通过 GitHub Release 自动上传/下载备份 - **多云端上传**：本地目录、FTP/FTPS、WebDAV、百度网盘、123云盘 - **告警通知**：备份失败时通过邮件、飞书机器人、钉钉机器人、Discord、Telegram发送告警 - **多语言支持**：自动检测服务器语言，内置中英文，支持自定义语言文件 - **配置热重载**：无需重启服务器即可重载配置 - **安全机制**：备份期间暂停自动保存防止数据不一致、文件复制重试、ZIP滑动攻击防护 ## 安装 1. 下载最新的 `PluralBackup-1.0.3.jar` 2. 将 jar 文件放入服务器的 `plugins/` 目录 3. 启动服务器，插件会自动生成默认配置文件 `plugins/PluralBackup/config.yml` 4. 根据需要编辑配置文件 5. 执行 `/backup reload` 或重启服务器使配置生效 ## 命令 所有命令需要 `pluralbackup.admin` 权限（默认OP拥有）。 | 命令 | 说明 | |------|------| | `/backup now` | 立即执行一次备份 | | `/backup list` (或 `/backup ls`) | 列出所有备份 | | `/backup restore <备份名称>` | 恢复指定备份（会重新加载世界） | | `/backup clean` | 清理旧备份 | | `/backup reload` | 重新加载配置文件 | | `/backup status` | 查看插件运行状态 | | `/backup github-list` | 列出 GitHub 上的备份版本 | | `/backup github-download <版本号>` | 从 GitHub 下载指定版本 | | `/backup github-upload` | 备份服务器并上传到 GitHub | ## 配置文件 配置文件位于 `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 # 是否压缩为zip exclude-dirs: # 排除的目录（相对服务器根目录） - "plugins/PluralBackup/backups" # --- 备份行为 --- save-world-before-backup: true # 备份前保存所有世界 pause-autosave-during-backup: true # 备份期间暂停自动保存 file-copy-retry-count: 3 # 文件复制重试次数 file-copy-retry-delay-ms: 500 # 重试间隔（毫秒） # --- 云端上传 --- cloud: enabled: false type: "local" # local / ftp / webdav / baidu / pan123 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: "" # 接入产品名称，文件存放于 /我的应用数据/{app-folder}/ access-token: "" # 留空则自动获取并缓存 # 123云盘（https://www.123pan.cn/developer） pan123: client-id: "" client-secret: "" access-token: "" # 留空则自动获取并缓存 parent-folder-id: 0 # 上传目标文件夹ID，0表示根目录 # --- 告警通知 --- notification: enabled: false # 是否启用备份失败通知 # 邮件通知 email: enabled: false smtp-host: "" # 例如 smtp.qq.com smtp-port: 465 use-ssl: true username: "" # 发件人登录账号 password: "" # 授权码（QQ邮箱需使用授权码） from: "" # 发件邮箱 to: "" # 收件邮箱 subject: "PluralBackup 备份异常告警" # 飞书机器人 feishu: enabled: false webhook: "" # 自定义机器人 Webhook secret: "" # 加签密钥（未启用加签则留空） # 钉钉机器人 dingtalk: enabled: false webhook: "" # 自定义机器人 Webhook secret: "" # 加签密钥（未启用加签则留空） # --- GitHub 备份 --- github: enabled: false token: "your-github-token" # 需要 repo 权限的 PAT owner: "your-username" repo: "PluralGamneBackup" auto-create-repo: true # 仓库不存在时自动创建私人仓库 ``` ## 备份机制说明 ### 双模式定时备份 插件支持两种独立的定时触发模式，可同时启用： **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 额外备份。 ### 无停机备份流程 1. **广播开始消息**（主线程） 2. **保存所有世界**（主线程） 3. **暂停自动保存**（主线程） 4. **异步复制服务器目录**（工作线程，排除备份目录与配置的排除目录） 5. **恢复自动保存**（主线程） 6. **压缩为ZIP**（工作线程，可选） 7. **云端上传**（工作线程，可选） 8. **清理旧备份**（工作线程，保留最近N个） 9. **广播完成消息**（主线程） 10. **失败告警**（异步线程，失败时通过邮件/飞书/钉钉通知） ### 关键线程安全设计 - 所有文件IO与网络操作在工作线程异步执行，不阻塞主线程 - `broadcastMessage` 和向玩家发送消息必须通过 `getScheduler().scheduleTask()` 调度到主线程执行 - GitHub 上传/下载使用 `CompletableFuture.runAsync()` 异步执行 - 通知发送使用 `CompletableFuture.runAsync()` 异步执行 - 使用 `AtomicBoolean` 防止并发备份 ## GitHub 云端备份 ### 工作机制 GitHub备份已集成到主备份流程中（不再使用独立调度器）： - **间隔模式触发**：`auto-backup: true` 时，每隔 `interval-minutes` 分钟备份，备份完成后如果 `github.enabled: true` 则自动上传 - **时刻模式触发**：`schedule.enabled: true` 时，在指定时刻备份，备份完成后如果 `github.enabled: true` 则自动上传 - **手动触发**：执行 `/backup github-upload` 立即备份并上传 ### 准备工作 1. 创建 GitHub Personal Access Token (PAT)： - 访问 https://github.com/settings/tokens - 创建新 token，勾选 `repo` 权限 - 建议设置**永不过期**（或根据安全需求设置） 2. 在 `config.yml` 中配置 `github` 部分 ### 版本号规则 GitHub 备份使用 Release 的 tag 作为版本号，格式为 `v1`、`v2`、`v3`...，自动递增。 ### 限制 - GitHub Release 单个 Asset 大小限制为 **2GB** - 超过限制的备份会上传失败并提示 - 手动执行 `/backup github-upload` 后会自动清理本地旧备份（受 `max-backups` 限制） ## 百度网盘备份 1. 访问 https://pan.baidu.com/union/console 创建应用，获取 `app-id` 与 `app-secret` 2. 在配置中填写 `baidu.app-folder`（即申请接入时填写的"产品名称"） 3. 设置 `cloud.type: "baidu"` 4. 首次上传时插件自动获取 access_token 并缓存；也可手动填写 `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配置 > 自动检测服务器语言 > 默认英语 - **Nukkit版**：通过 `Server.getLanguage()` 检测 - **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 仓库不存在**：自动创建私人仓库并初始化 README - **GitHub Release 创建失败**：记录错误日志并广播失败消息 - **云端上传失败**：记录错误日志，并通过通知渠道告警 - **百度网盘/123云盘令牌过期**：自动重新获取 - **备份期间服务器异常**：通过 `finally` 块确保自动保存状态恢复 - **ZIP解压安全**：防止 ZIP 滑动攻击（路径遍历） ## 许可证 版权所有 © PluralTeam [/MD]