![PotatoSack —— 支持区块级粒度、可几乎不占用额外硬盘空间来利用 OneDrive / Dropbox / S3 增量备份世界数据 [1.19+]](/data/resource_icons/8/8648.jpg?1719626935){kind=icon}
- 版权类型
- 原创
- 插件中文名称
- 土豆麻袋
- 插件英文名称
- PotatoSack
- 支持的核心（服务端）
- Spigot
- Paper
- Purpur
- 语言支持
- 中文（简体）
- 适配版本（Java）
- 最新版本
- 26.x
- 1.21
- 1.20
- 1.19
- 开源地址，欢迎 Star：https://github.com/Bottle-M/PotatoSack
本插件在压缩上传文件时可以几乎不占用多余的本地硬盘空间，适用于服务提供商对硬盘空间进行了限制的场景。- 本插件目前支持 OneDrive (非世纪互联版) 、Dropbox 以及兼容 S3 的对象存储（腾讯云 COS, 阿里云 OSS 等）
[MD]
```yaml
# PotatoSack 配置版本 (用于判断插件配置是否过于陈旧，需要更新)
version: '3.0.0'
client:
# 选择你想要采用的存储服务提供方 (onedrive / dropbox / s3)
use: onedrive
# 在存储服务中保存备份文件的基础目录路径（默认为空，表示云端根目录下）
# 比如你把 base-dir 设为 "my/backups"，备份数据就会被存到 "云存储/my/backups/PotatoSack/..." 目录下
# 注：就算你在最前面或者最后面输入了 "/"，程序也会自动将其移除，比如 "/my/backups/" -> "my/backups"
base-dir: ""
# OneDrive API 配置 (支持 OneDrive 企业版 (ODB) / 个人版 (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 指明是否使用 AppFolder 作为存储根目录
# 关于 AppFolder:
# [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 个人版 (ODC) 完全支持了 App Folder 特性，而 OneDrive 企业版 (ODB) 支持可能还不完善，
# 但仍然还是推荐启用这个选项，以支持更安全的数据隔离
# 如果启用这个选项，个人版需要 Files.ReadWrite.AppFolder 权限，而企业版可能需要 Files.ReadWrite.All 权限
use-app-folder: true
client-id:
client-secret:
refresh-token:
# Dropbox API 配置
# 需要有 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、MinIO、Cloudflare R2、腾讯云 COS 等)
# 注: 本版本只支持静态凭证（access key / secret key，可选 session token）
# 注: 目标 bucket 上需要的权限:
# s3:ListBucket, s3:GetObject, s3:PutObject, s3:AbortMultipartUpload, s3:DeleteObject
# 注: S3 上传固定使用 32 MiB 分片（最多 10000 片），单个备份对象上限约为 312.5 GiB。
# 不建议使用本插件备份上百 GiB 的超大存档。
s3:
# 自定义 endpoint。留空表示使用 AWS S3，由 SDK 根据 region 选择官方 endpoint。
# 使用 MinIO 等自建或兼容 S3 的对象存储服务时需要填写完整地址（必须带协议头），
# 例如:
# endpoint: "http://127.0.0.1:9000"
# endpoint: "https://minio.example.com"
endpoint: ""
# 签名所用区域，需要与服务端签名配置匹配。
# AWS S3 用户应填写 bucket 的真实区域；多数兼容 S3 的服务可以使用默认值 "us-east-1"
# （MinIO 的默认 region 就是 us-east-1）。
region: "us-east-1"
# 对象存储桶名称，
# 插件会把数据存放在该桶内的 "<base-dir>/PotatoSack/..." 之下。
bucket: ""
# 访问 Access Key
access-key: ""
# 访问 Secret Key
secret-key: ""
# 临时凭证的 session token，只用 AK / SK 的时候这里可以留空
session-token: ""
# 是否使用 path-style 访问（http://endpoint/bucket/key），而不是
# virtual-hosted-style（http://bucket.endpoint/key）。
# MinIO 及多数自定义 endpoint 需要设为 true，AWS S3 则通常保持 false。
path-style-access: false
# 你想要保留的历史备份组数.
# 注："一组备份 "包括一个全量备份和其后的增量备份（在下一个全量备份之前的）。
max-full-backups-retained: 10
cron:
# 用于安排全量备份时间的 UNIX Cron 表达式
# 例: "0 2 */1 * *" 表示每天凌晨两点检查是否需要全量备份
full-backup: "0 2 */1 * *"
# 用于安排增量备份时间的 UNIX Cron 表达式
# 例: "*/30 * * * *" 表示每 30 分钟检查一次是否需要增量备份.
incremental-backup: "*/30 * * * *"
# 是否在没有玩家加入游戏的情况下暂停增量备份
# true: 如果自从上一次全量 / 增量备份起没有玩家加入过游戏，则跳过增量备份
# false: 老老实实按照 cron.incremental-backup 的安排进行增量备份
stop-incremental-backup-when-no-player: true
# 是否在没有玩家加入游戏的情况下暂停全量备份
# true: 如果自从上一次全量备份起没有玩家加入过游戏，则跳过增量备份
# false: 老老实实按照 cron.full-backup 的安排进行增量备份
stop-full-backup-when-no-player: false
# 是否采用流式压缩上传
# 注: 当服务器硬盘空间不够大时可以启用此选项。
# 注: 这种方式下程序只会将每块压缩文件数据暂时写入内存中的缓冲区，代价并不高。
# 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: 如果 paths 留空，插件就不会工作辣！(∪.∪ )...zzz
# 注 2: 所有的路径都应该指向服务端根目录下级的目录
# 注 3: 你可以在服务端根目录下放一个 .potatosackignore 文件来让插件在备份时忽略掉某些文件或者目录（详情可以看 README）
# 注 4: 配置的路径不可以是服务端根目录
# 注 5: paths 中的路径不能有互相交叠的情况（比如你不能同时配置 'world' 和 'world/playerdata'）
paths: [ ]
```
[/MD]
[MD] ### 存储服务配置指导 关于如何获取配置文件中所需的 key, secret, refresh-token 之类的，咱也写了几个较为详细的指导文档: * [OneDrive](https://github.com/Bottle-M/PotatoSack/blob/main/memos/onedrive-guide.md) * [Dropbox](https://github.com/Bottle-M/PotatoSack/blob/main/memos/dropbox-guide.md) ## 忽略特定文件的备份 你可以在**服务端根目录下**放一个 `.potatosackignore` 文件，以类似 `.gitignore` 的语法来忽略特定文件或者目录的备份。 为了降低实现复杂度，和 `.gitignore` 不一样的两点如下： 1. 只能放在服务端根目录下 2. 不支持取反 `!` 语法 示例如下： ```gitignore # 注释：以 # 开头的行为注释，空行也会被忽略 # 末尾 / 表示仅匹配目录；不含末尾斜杠时文件和目录都匹配。 # 以下两条都会在任意层级生效： # 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 # 含中间斜杠也锚定到根，仅匹配 服务端根目录/world/region/ 下的 .mca world/region/*.mca # ** 跨段匹配零或多层目录，此处匹配 logs/ 下所有内容 logs/** # 中间写 ** 同样匹配零或多个目录：命中 a/c、a/x/c、a/x/y/c 等 a/**/c ``` > 以防你不知道，服务端根目录就是**服务端 jar 包所在的目录**（如 `server.jar`）。 ## 命令 这个插件目前只有一个命令: ```text /potatosack reload ``` 用于热重载插件配置文件。 ### 命令权限节点 ```text potatosack.reload ``` > 💡 服务器管理员（OP）默认有这个权限。 ## 小工具 ### Backup Merger 概念介绍中提到过，“一组备份”包括一个全量备份和一些增量备份。在恢复服务器数据的时候，BackupMerger 可以将这些备份合并成一个完整的备份。 详见 [BackupMerger](https://github.com/Bottle-M/PotatoSack/blob/main/backups-merger/README.zh_CN.md)。 ## FAQ 1. *首次启动时控制台怎么打印出了 404* ？ * 这往往出现在插件首次初始化，是因为云端的文件缺失或相应目录未建立，不过不用担心，程序在遇到 404 响应后会自动建立相应文件和目录。 2. *备份数据会被上传到云端哪个位置*？ * 如果是 OneDrive：取决于 `configs.yml` 中 `client.onedrive.use-app-folder` 的设置—— * `true`（默认）：`OneDrive 根目录/应用/<应用程序名>/<base-dir>/PotatoSack`（App Folder） * `false`：`OneDrive 根目录/<base-dir>/PotatoSack` * 如果是 Dropbox: `Dropbox 根目录/<base-dir>/PotatoSack` 或者 `Dropbox 根目录/应用/<你创建的应用名>/<base-dir>/PotatoSack`。Dropbox 上创建应用时如果勾选采用 App Folder 访问限制，则就是后者（也建议这样）。 * 如果是 S3: `<bucket>/<base-dir>/PotatoSack/...`。S3 本身没有真正的目录，而是由 object key 前缀表达，插件也不会为目录创建零字节 marker object。删除一组旧备份时会按前缀批量、递归删除该组下的所有对象。 > (`<base-dir>` 即你在 `configs.yml` 中配置的 `client.base-dir`) 3. *为什么叫 PotatoSack*？ * 因为咱服务器的性能和土豆差不多，备份数据就像扛土豆麻袋一样 （゜ー゜） 如果还有其他问题，欢迎提出 issue。 ## 开源协议 本插件采用 Apache-2.0 开源协议。 感谢你的使用 (￣▽￣)" [/MD]
