PotatoSack

插件

· 作者 somebottle

适用于 Minecraft 服务器的区块级增量数据备份插件,支持流式上传,备份时几乎不占用额外磁盘空间。支持 OneDrive / Dropbox / S3。

0 本站下载 0 关注 更新于 1 个月前

最新 3.0.0 · 26.3 · Bukkit / Paper

一键开服(送7天)

PotatoSack

慢慢来,老朋友,这袋土豆可比苏珊阿姨的大理石雕像好拿多了!

语言:简体中文 | English

  • Github 仓库:

这是什么?

这是一个简单的备份插件,最初是为我的 Minecraft 服务器编写的,用于备份指定目录中的数据。它支持增量/全量备份机制,且增量备份支持区块级粒度。

备份后的归档文件不会存储在本地,而是上传到 OneDrive、Dropbox 和 S3 / S3 兼容对象存储等云存储服务。

  • 支持的 Minecraft 版本:1.19+

  • ✨ 该插件可以压缩并上传文件,同时极少占用本地磁盘空间,因此适用于服务提供商对磁盘空间有限制的场景。详见 概念。

目前,该插件支持 OneDrive(非世纪互联版)、Dropbox,以及 AWS S3 / S3 兼容服务(MinIO、Cloudflare R2、Wasabi、腾讯云 COS 等)。

概念

展开 / 收起:关于“一组备份”、“流式压缩上传”和“区块级增量备份”

一组备份

“一组备份”指的是“一次全量备份 + 随后的增量备份(在下一次全量备份之前)”。

每次创建新的全量备份时,都会创建一个新的“一组备份”。在下一次全量备份之前的后续增量备份都将存储在此组中。

更多详情,请参阅 备份目录结构(仅中文)。

流式压缩上传

本插件的“流式压缩上传”是指一种在压缩文件的同时将其上传至云端的备份方法,采用了以时间换空间的理念,仅占用少量内存空间(用作缓冲区),几乎不占用任何额外的磁盘空间。

之所以需要以时间换空间,是因为 OneDrive API 要求在上传大文件之前必须知道确切的最终文件大小,因此需要一个额外的进程来模拟压缩以计算文件大小。
如果您使用的是 Dropbox,则无需以时间换空间,因为 Dropbox 不需要预先知道文件的总大小(但是,如果您的服务器部署在中国大陆,您可能需要设置代理以确保能够访问 Dropbox API (;´д`)ゞ)。
S3 也不需要预先知道最终的对象大小(分片上传只需要部分大小),因此使用 S3 时,流式模式也无需额外的尺寸计算流程。

传统的备份方法是先将要备份的文件临时压缩为 zip 归档文件,然后再上传到云端,这需要足够的磁盘空间来容纳待备份的文件和生成的 zip 归档文件。

然而,许多 Minecraft 服务器托管提供商限制了可用磁盘空间。如果可用空间仅为 10 GiB,而世界数据占用了 7 GiB,那么磁盘上剩余的空间将无法容纳临时的 zip 归档文件,导致备份失败。

区块级增量备份

从 3.0.0 版本开始,PotatoSack 实现了成本和维护复杂度相对较低的区块级增量备份。PotatoSack 在备份记录文件中存储区域时间戳表,并通过检查区块时间戳是否已更改来确定是否需要增量备份。增量备份归档文件也以专门的 PSMCA(delta mca)格式存储每个 .mca 文件,其中仅包含已更改的区块。

注意:为了保持维护的可控性,我们没有实现更细粒度的变更检测,例如在移除 InhabitedTime 和 LastUpdate 等易变字段后对区块进行哈希处理,甚至细化到区块级别。这些方法需要解压区块数据并解析 NBT,这将增加计算复杂度,同时显著增加维护难度(Mojang 可能会从一个版本到下一个版本更改这些底层数据字段)。更细粒度的哈希字节串也难以压缩,如果记录文件为每个区块存储如此细粒度的状态,随着 .mca 文件的生成,其体积将会显著增长。

在测试中,在有利条件下,3.0.0 的增量备份归档文件已经比 2.x.x 版本小 85%(具体减少量取决于玩家移动的区域)。切换到紧凑的二进制格式并对其进行压缩后,记录文件的体积也显著减小。这对于当前用途来说已经足够。

使用时戳作为主要缺点在于,只要玩家在附近,区块就可能被更改(对于区域文件,这主要通过 InhabitedTime 体现),这会更新区块及其时间戳。与 2.x.x 机制(任何更改都会备份整个 .mca 区域文件)相比,3.0.0 仍然从增量备份归档文件中移除了大量冗余数据。


安装

  1. 从此处下载插件。(PotatoSack*.jar)
  2. 将插件放入服务器目录下的 plugins 文件夹中。
  3. 启动服务器,插件将生成初始配置文件 configs.yml。你需要对其进行配置。
  4. 配置完成后重启服务器。如果你看到如下日志,说明插件已成功初始化。
    [12:52:32 INFO]: [PotatoSack] PotatoSack successfully initialized! Savor using it!
    

配置

配置文件位于 plugins/PotatoSack/configs.yml。

# PotatoSack 配置版本
version: '3.0.0'

client:
    # 选择你想要使用的云存储服务提供商。
    # 支持的值:onedrive / dropbox / s3
    use: onedrive
    # 在云存储中存储备份的基础目录路径(默认为空,表示根目录)
    # 示例:如果设置为 "my/backups",数据将存储在 "my/backups/PotatoSack/..."
    # 注意:前导和尾随斜杠将被自动移除。例如,"/my/backups/" 将被视为 "my/backups"。
    base-dir: ""
    # OneDrive API 配置(支持 OneDrive Business(ODB) / Personal(ODC))
    # 参考:https://learn.microsoft.com/en-us/graph/auth-v2-user?tabs=http#5-use-the-refresh-token-to-get-a-new-access-token
    # 工具:https://potatosack.imbottle.com/onedrive-token-helper.html
    onedrive:
        # use-app-folder 指定是否使用“应用文件夹”来存储备份。
        # 参考:
        #   [1] https://learn.microsoft.com/en-us/onedrive/developer/rest-api/concepts/special-folders-appfolder
        #   [2] https://learn.microsoft.com/en-us/graph/onedrive-sharepoint-appfolder
        # 尽管目前只有 OneDrive Personal(ODC) 完全支持“应用文件夹”(权限为 "Files.ReadWrite.AppFolder"),
        # 但仍建议启用此选项以实现更安全的数据隔离和未来的兼容性。
        # 对于 OneDrive Business(ODB),数据隔离可能无法完全支持,
        # 但应用文件夹仍可正常创建和使用(权限为 Files.ReadWrite.All)。
        use-app-folder: true
        client-id:
        client-secret:
        refresh-token:
    # Dropbox API 配置
    # 创建一个 Dropbox 应用,并使用具有 "files.content.write"、
    # "files.content.read" 和 "files.metadata.read" 权限的刷新令牌。
    # 工具:https://potatosack.imbottle.com/dropbox-token-helper.html
    dropbox:
        app-key:
        app-secret:
        refresh-token:
    # S3 / S3 兼容对象存储配置(AWS S3、QCloud COS、Aliyun OSS、...)
    # 注意:仅支持静态凭证(访问密钥/秘密密钥,可选会话令牌)。
    # 注意:目标桶所需的 IAM 权限:
    #       s3:ListBucket, s3:GetObject, s3:PutObject, s3:AbortMultipartUpload, s3:DeleteObject
    # 注意:S3 上传使用固定的 32 MiB 分片(最多 10,000 个分片),因此一个备份对象限制约为
    #       312.5 GiB。不建议归档接近数百 GiB 的文件。
    s3:
        # 自定义端点。留空以使用 SDK 根据 “region” 选择的 AWS S3 端点。
        # 对于 MinIO 或其他 S3 兼容服务,请填写包含方案的完整端点,例如
        #   endpoint: "http://127.0.0.1:9000"
        #   endpoint: "https://minio.example.com"
        endpoint: ""
        # 用于签名的区域。它必须与服务器的签名配置匹配。
        # AWS S3 用户应将其设置为桶的实际区域;大多数 S3 兼容服务接受默认值 "us-east-1"(MinIO 的默认区域也是 us-east-1)。
        region: "us-east-1"
        # 对象存储桶的名称。
        # 插件在此桶内 "<base-dir>/PotatoSack/..." 下存储数据。
        bucket: ""
        # 访问密钥 (Access Key)
        access-key: ""
        # 秘密密钥 (Secret Key)
        secret-key: ""
        # 会话令牌,仅在临时凭证时需要。留空则仅使用 AK/SK。
        session-token: ""
        # 是否使用路径样式访问 (http://endpoint/bucket/key) 而不是
        # 虚拟主机样式访问 (http://bucket.endpoint/key)。
        # MinIO 和大多数自定义端点需要设置为 true;AWS S3 本身通常保持 false。
        path-style-access: false

# 保留的全量备份数量,实际上指的是要保留的“备份组”数量。
# 注意:“一组备份”由一个全量备份及其后的一组增量备份组成(直到下一个全量备份之前)。
# 注意:如果删除了一个全量备份,其后的所有增量备份(直到下一个全量备份之前)也将被删除。
max-full-backups-retained: 10

cron:
    # 生成全量备份的 Cron 表达式
    # 注意:这使用标准的 UNIX Cron 语法。
    # 示例:"0 2 */1 * *" 表示每天凌晨 2:00 运行全量备份。
    full-backup: "0 2 */1 * *"

    # 生成增量备份的 Cron 表达式
    # 注意:这使用标准的 UNIX Cron 语法。
    # 示例:"*/30 * * * *" 表示每 30 分钟运行一次增量备份。
    incremental-backup: "*/30 * * * *"

# 当没有玩家加入时是否停止增量备份
# - true:如果自上次增量/全量备份以来没有玩家加入,则跳过增量备份
# - false:无论玩家活动如何,都按照 cron 表达式执行增量备份
stop-incremental-backup-when-no-player: true

# 当没有玩家加入时是否停止全量备份
# - true:完成全量备份后,如果没有玩家加入,则跳过后续计划的全量备份,直到有玩家再次加入
# - false:无论玩家活动如何,都按照 cron 表达式执行全量备份
stop-full-backup-when-no-player: false

# 是否在压缩文件的同时上传。(时间与空间的权衡)
# 注意:这将防止在创建备份期间将 zip 文件完全写入本地磁盘,而是将其分块直接上传到云端,因此当创建 zip 文件时,备份过程不受磁盘大小限制。
# 注意:实际上,这会将每个 zip 文件的块临时写入内存中的缓冲区,但这通常只需要**常量**额外空间,成本不高。(OneDrive/Dropbox 每块约 15.625 MiB,S3 为 32 MiB。)
use-streaming-compression-upload: false

# 您希望进行备份的目录路径,可以是绝对路径或相对路径(相对于服务器根目录),示例:
# paths:
#   - world
#   - ./world_nether
#   - world_the_end
#   - plugins/GroupManager
#
# Minecraft JE 26.1 之后,可以是:
# paths:
#   - /workspace/server/world
#
# 注意 1:如果留空,插件将无法工作。
# 注意 2:所有路径必须位于服务器根目录下。
# 注意 3:您可以在服务器根目录中放置一个 .potatosackignore 文件,以排除某些文件或目录不被备份。
#         更多信息,请参阅 README。
# 注意 4:路径不能是服务器根目录本身。
# 注意 5:备份路径之间不能重叠。例如,不要同时包含 'world' 和 'world/playerdata'。
paths: [ ]

存储服务配置指南

有关获取配置文件所需的 key、secret 和 refresh-token 的详细指导,请参阅以下文档:

从备份中忽略特定文件

您可以在 服务器根目录 中放置一个 .potatosackignore 文件,以便在备份过程中忽略特定的文件或目录,其语法类似于 .gitignore。

为了保持实现简单,它与 .gitignore 有两个不同之处:

  1. 它只能放置在 服务器根目录 中。
  2. 不支持否定 ! 语法。

示例:

# 注释:以 # 开头的行是注释;空行也会被忽略

# 末尾带有 / 的规则仅匹配目录;不带末尾斜杠的规则则同时匹配文件和目录。
# 下面两条规则适用于任何嵌套层级:
#   logs/  匹配 world/logs/、a/b/logs/ 等(仅限目录,不包括文件)
#   temp   匹配 temp、plugins/temp、x/y/temp(文件或目录)
logs/
temp

# * 匹配单个路径段内的任意字符(不包括 /)。 
# 在这种情况下,它匹配该路径段内的 .log 文件。
*.log

# ? 匹配单个字符(不包括 /)。
# 在这种情况下,它匹配 cache1.dat、cacheX.dat 等。
cache?.dat

# 前导 / 将规则锚定到服务器根目录。
# 在这种情况下,它仅匹配根目录下的 temp.db
/temp.db

# 包含中间斜杠的规则也会锚定到根目录。
# 在这种情况下,它仅匹配 server-root/world/region/ 下的 .mca 文件
world/region/*.mca

# ** 匹配零个或多个目录层级。  
# 这将匹配 logs/ 下的所有内容
logs/**

# 位于中间的 ** 匹配零个或多个目录。
# 在这种情况下,它匹配 a/c、a/x/c、a/x/y/c 等。
a/**/c

服务器根目录是服务器 jar 文件所在的目录(例如 server.jar)。

命令

该插件只有一个命令:

/potatosack reload

用于热重载插件配置文件。

权限节点

potatosack.reload

? 管理员(Operators) 默认拥有此权限。

小工具

备份合并器

如上所述,“一组备份”由一个完整备份和一些增量备份组成。BackupsMerger 可以在我们恢复服务器数据时 将这些备份合并为一个完整的备份。

参见 BackupsMerger。

常见问题

  1. 问:为什么控制台在启动时会打印出 404?

    答:这通常是因为插件首次初始化时云端的文件或目录缺失,但不用担心,当遇到 404 问题时,程序会自动创建所需的文件和目录。

  2. 问:云端中的备份数据存储在哪里?

    答:取决于您使用的提供商:

    • OneDrive:取决于 configs.yml 中的 client.onedrive.use-app-folder 设置 ——

      • true(默认):OneDrive root/Apps/<application name>/<base-dir>/PotatoSack(应用文件夹)
      • false:OneDrive root/<base-dir>/PotatoSack
    • Dropbox:Dropbox root/<base-dir>/PotatoSack 或 Dropbox root/Apps/<your app name>/<base-dir>/PotatoSack。如果您在创建 Dropbox 应用时选择了“仅限应用文件夹”访问限制,则为后者(推荐)。

    • S3:<bucket>/<base-dir>/PotatoSack/...。S3 没有真正的目录——路径通过对象键前缀表示,且插件不会创建零字节标记对象。删除旧的备份组会批量删除其前缀下的所有对象。

    (<base-dir> 指的是 configs.yml 中的 client.base-dir 设置)

  3. 问:为什么插件名为 'PotatoSack'?

    答:因为我的服务器性能就像土豆一样,备份数据就像扛着一袋土豆。(゜ー゜)

如果您有其他问题,欢迎提交 Issue。

许可证

采用 Apache-2.0 许可证。

感谢您的使用。( ̄▽ ̄)"

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源