Data synchronization

插件

· 作者 squarecode

适用于 Paper 和 Folia 26.3+ 的跨服务器玩家数据同步

0 本站下载 0 关注 更新于 3 周前

最新 2026.10.2 · 26.3 · Folia / Paper

一键开服(送7天)

DataSynchronization

适用于 Paper、Purpur 和 Folia 26.3+ 的跨服务器玩家数据同步

无重复物品 · 无数据丢失 · 支持 Folia · Redis / RabbitMQ / SQL / MongoDB · 历史、回滚、审计与 GUI 工具


概述

DataSynchronization 确保玩家数据在整个 Minecraft 网络中完美同步。它在服务器之间传输背包、末影箱、生命值、进度(advancements)、属性、药水效果、位置、配方、统计信息、PersistentDataContainer(NBT)字节以及自定义插件数据。

与传统“最后写入优先”的同步插件不同,DataSynchronization 旨在消除重复物品和数据丢失类 bug。每次保存都通过每个玩家的 FIFO 队列,并由单调会话所有权令牌进行防护,因此来自被取代节点的写入在被触及数据库之前就会被拒绝。


要求

  • 服务器: Paper 26.3++、Purpur 或 Folia
  • Java: 25 或更高版本
  • 存储: H2、MariaDB、MySQL、PostgreSQL 或 MongoDB
  • 网络推荐: Redis
  • 可选: RabbitMQ、Vault、PlaceholderAPI

不支持: Bukkit 和 Spigot。该插件依赖仅 Paper 可用的 API(原生 Adventure、PersistentDataContainer 字节序列化、AsyncChatEvent、现代 Paper 元数据)。


同步内容

每个类别都可以单独启用或禁用。

  • 背包: 主背包、盔甲栏、副手、末影箱
  • 生命体征: 生命值、饥饿值、饱和度、 exhaustion(疲惫度)、空气值、经验值、等级、分数
  • 效果: 药水效果、属性(最大生命值、速度、伤害、挖掘距离等)
  • 世界状态: 位置、床重生点、游戏模式、飞行状态、飞行速度和步行速度
  • 进度: 进度(advancements)、配方、统计信息
  • 插件数据: PersistentDataContainer / NBT 字节数据
  • 自定义模块: 通过 SyncModule API
  • 按世界黑名单: 排除创造模式、建造或小游戏世界

核心功能

存储与集群

  • H2、MariaDB、MySQL、PostgreSQL 和 MongoDB 后端
  • 大型网络的分片存储变体
  • Redis pub/sub、RabbitMQ fanout、插件消息或自动检测
  • 基于 Redis SETNX 的会话所有权、单调围栏令牌和 TTL 心跳
  • 每个 UUID 的 FIFO 写入合并
  • GZIP 压缩使存储行缩小 4-6 倍
  • 分层缓存(L1 内存 + L2 Redis)
  • 带有自动恢复功能的存储层熔断器
  • 瞬态故障下的指数退避重试
  • 带有优先级队列和背压的异步流水线

平台与运行时

  • 对 Paper、Purpur 和 Folia 的一流支持
  • 原生使用 Folia 实体区域调度器
  • 原生 Adventure 使用,无需阴影包裹的 BukkitAudiences 桥接
  • 热路径上的内联分发优化
  • bStats 集成用于设置形状遥测

可靠性与安全

  • 每个玩家的暂停,重启后持久化并广播至整个集群
  • 通过领导者选举扫描自动恢复限时暂停
  • 同步失败时可选踢出玩家并显示自定义消息
  • 创造模式背包同步保护
  • 破坏性操作的确认提示
  • 重型操作命令冷却
  • 防 SQL 注入的标识符验证
  • 原子导出重命名(先写临时文件再重命名)
  • 可配置的 512 MiB 导入大小上限
  • 带信号量背压的并行批量导入

历史与回滚

  • 每个玩家的快照历史,支持可配置的滚动保留
  • 固定快照在滚动清理中幸存
  • 通过 --only / --except 选择性恢复
  • 应用恢复前预览差异
  • 比较同一玩家的两个快照,或两个玩家并排比较

实时 GUI 工具

  • /ds view - 分页玩家浏览器,支持排序、搜索、快照导航和比较模式
  • /ds edit - 游戏内背包、末影箱和统计编辑器
  • Bossbar 进度条用于全部保存、导出、导入和重新分片

更新通知

  • 启动时及每六小时异步检查 SpigotMC API
  • 结果在 /ds version、/ds status 的系统区块中显示,并在玩家加入时向操作员显示一次性点击跳转至 SpigotMC 的通知
  • 五秒超时,绝不阻塞主线程,礼貌的 User-Agent
  • 在具有严格出站策略的网络上,可通过 update-checker.enabled: false 禁用

管理工具

Operations 是一等公民的功能面,而非事后补充。

  • Doctor: 存储、消息、缓存、熔断器和配置气味检查
  • Metrics: 运行时间、保存和加载计数、重试次数、队列深度、缓存命中率
  • Benchmark: 合成保存和加载循环,包含最小值 / p50 / p95 / 最大值
  • Round-trip test: 每个玩家的序列化器自检
  • Stats: 行数、平均和最大尺寸、最重的 Top-N 玩家
  • Errors view: 游戏内 WARNING / SEVERE 日志查看器,集群同步
  • Watch: 选定玩家的实时同步事件追踪
  • Whoami: 自身身份、权限和会话状态
  • Whois: 玩家的综合取证视图
  • Search: 在审计和 SEVERE 错误缓冲区中进行 grep 搜索
  • Audit log: 25 种跟踪的操作类型,可过滤和分页
  • Debug: 流水线、会话和分片内部结构,支持实时刷新
  • Import / export: 流式 JSON,支持试运行和选择性范围

模块与 API

第三方插件可以通过 SyncModule API 同步其自身数据,而无需 fork DataSynchronization。

  • 注册自定义捕获和应用逻辑
  • 每个模块的指标
  • 每个模块的状态部分
  • /ds view 中的每个模块 GUI 图标
  • /ds <module-id> 下的每个模块子命令
  • 每个模块的计划任务
  • 每个模块的 PlaceholderAPI 占位符
  • 带有迁移钩子的数据版本控制
  • UUID 合并的合并策略
  • 无需加载-修改-保存的原子单字段补丁

捆绑模块: Vault 经济系统和 Advancements(带有配方和统计切换开关)。


翻译

开箱即用六种语言:English, Deutsch, Español, Português brasileiro, Français, Polski.

  • 全文支持 MiniMessage 格式(颜色、渐变、悬停和点击事件)
  • 通过 WatchService 实现热重载——编辑 YAML 文件并保存后,即可立即看到更改
  • 四层回退链:本地活动配置、本地默认配置、JAR 内置活动配置、JAR 内置默认配置
  • 带版本控制的捆绑包与安全自动升级:替换前会先备份过期的本地文件
  • 支持任意 ISO-639 语言的即插即用 YAML 配置

对比

与 HuskSync 相比

  • 单调递增的栅栏令牌可防止延迟或过时的写入
  • 模块 API 支持任意插件数据,包括状态和 GUI 界面
  • 提供游戏内 GUI 编辑器,而非仅支持只读查看
  • 存储分片功能,附带离线迁移工具
  • 支持快照固定与选择性恢复
  • 以 Folia 优先的调度器设计
  • 预置六种语言,且支持热重载
  • 诊断命令,包含基础设施与配置检测功能
  • 支持 Redis、RabbitMQ 及插件消息传递(不仅限于 Redis)
  • 分层缓存使 Redis 调用量减少约 20 倍
  • GZIP 压缩负载
  • 集群范围的自动清理,配合领导者选举机制
  • 将 PersistentDataContainer 同步作为一等公民数据类型

与传统同步插件相比

  • 现代数据库支持,涵盖 SQL 与 NoSQL
  • 带有背压机制的异步管道
  • 熔断器与指数退避重试机制
  • 会话栅栏保护
  • 带进度报告的流式导入与导出
  • 历史记录、回滚与审计追踪
  • MiniMessage 翻译支持
  • 防 SQL 注入的安全标识符处理

快速入门

单 Paper 服务器

storage-method: h2

cache:
  type: memory

messaging-service: none

将 jar 文件放入 plugins/ 目录并启动服务器。

多服务器网络

storage-method: mariadb
server-name: "survival-01"

cache:
  type: redis

messaging-service: redis

redis:
  address: redis.internal:6379
  password: "..."

data:
  address: maria.internal:3306
  database: datasync
  username: datasync
  password: "..."

所有服务器共享 Redis 和 MariaDB。会话、缓存和消息传递均由 Redis 提供支持。每台服务器需配置独立的 server-name。


建议

存储后端

  • 单服务器、开发环境、CI: H2
  • 多服务器 SQL 设置: MariaDB 或 PostgreSQL
  • 文档型栈: MongoDB
  • 2,000+ 并发玩家: 上述任一方案启用分片功能

Redis

单服务器设置中非必需。强烈建议多服务器网络使用:Redis 可实现原子会话声明、跨服务器的共享缓存以及亚毫秒级的发布/订阅失效通知。

分片

仅在单个数据库不再满足需求时启用。大多数并发玩家数低于 2,000 的网络在单个 MariaDB 或 PostgreSQL 实例上运行良好。

不应同步的内容

  • 在拥有长期活跃账号的网络上禁用 statistics(这些地图可能会为每个玩家积累数千条记录)
  • 如果没有插件实际需要共享你所需的 PDC 字节,请禁用 persistentDataContainer

常见问题

它在 Folia 上能运行吗? 可以。Capture 通过平台调度器在玩家的实体区域线程上运行;其余部分则在非主线程中执行。

为什么不支持 Spigot 或 Bukkit? 该插件仅使用 Paper 专属 API(原生 Adventure、PersistentDataContainer 字节序列化、AsyncChatEvent、现代 Paper 元数据),而 Spigot 没有对应的等效实现。

如果数据库宕机了会发生什么? 当连续失败次数达到可配置阈值时,熔断器会开启,停止频繁请求数据库,并在数据库恢复后自动重新连接。

如果服务器在会话期间崩溃了会发生什么? 会话所有权声明会通过 TTL(生存时间)过期。此时其他服务器可以获取该声明并加载玩家。来自已崩溃节点的后写入操作会被 fencing token(隔离令牌)拒绝。

我可以同步自定义插件的数据吗? 可以。实现 SyncModule(或继承 AbstractSyncModule)并通过 API 或自动发现机制进行注册。

我可以只恢复快照的一部分吗? 可以。使用 /ds restore <player> <#> --only inventory,enderchest 或 --except statistics。

存储的行有多大? 启用 GZIP(默认情况下),典型后期游戏玩家的数据量在 10-40 KiB 范围内。

我可以添加自己的语言吗? 复制 translations/en.yml 到例如 it.yml,进行翻译并保存。文件监视器会实时重新加载它。

更新插件时翻译会被破坏吗? 不会。每个捆绑的 YAML 都包含一个 meta.version;过期的磁盘文件会自动备份为 <name>.yml<random-suffix> 并用新的捆绑版本替换。


命令

主命令:/datasync(别名 /ds)。

核心
/ds status [--section <name>]
/ds reload
/ds version
/ds metrics [--reset]
/ds doctor [--quiet]
/ds debug <pipeline|session|sharding> [player] [--watch]
玩家数据
/ds saveall [--filter <regex>]
/ds saveandkick <player|*> [--reason ...]
/ds forcesync <player>
/ds lookup <player> [--section <name>] [--json]
/ds view [player]
/ds view-confirm
/ds edit <player> inventory|enderchest|stats
/ds compare <p1> <p2> [--section <a,b>] [page]
/ds pause <player|--list|--all> [--duration <Nm|Nh|Nd>] [reason]
/ds resume <player|--all> [confirm]
历史版本与快照
/ds snapshot <玩家> [--备注 ...]
/ds history <玩家> [--包含 ...] [--自 1小时|7天] [页/置顶 <编号>|取消置顶 <编号>]
/ds diff <玩家> <编号1> <编号2> [--部分 <a,b>] [页]
/ds restore <玩家> <编号> [--仅|--排除 类型] [--预览] [--原因 ...] [确认]
维护
/ds purge <player> [--reason ...] [--dry-run] [confirm]
/ds purge --inactive <days> [--reason ...] [--dry-run] [confirm]
/ds reset <player> --type <types> [--reason ...] [confirm]
/ds move <old-uuid> <new-uuid> [--dry-run] [confirm]
/ds export <file> [--inactive <days>] [--with-history] [--with-audits] [--with-errors] [--all]
/ds import <file> [--dry-run] [--skip-players] [--skip-history] [--skip-audits] [confirm]
/ds reshard <new-shard-count> [--export <dir>]
缓存
/ds cache info
/ds cache clear [player|confirm]
/ds cache refresh [player]
审计与诊断
/ds audit [player] [--action a,b,c] [--by <name>] [--server <name>] [--contains <text>] [--since 1h|7d] [--until 1h|7d] [--export] [page]
/ds errors [--level WARNING|SEVERE] [--contains <text>] [--since 1h|7d] [page]
/ds watch <player|off>
/ds stats
/ds benchmark [N] [--concurrent <K>]
/ds test <player> [--count <N>]
/ds whoami
/ds whois <player>
/ds search <query> [--sources audit,errors] [--limit N] [page]
模块
/ds module list [--enabled|--disabled] [page]
/ds module info <id>
/ds module enable <id>
/ds module disable <id>
/ds module reload [<id>] [--only <ids>]
/ds module export <id> <file>
/ds module import <id> <file>
翻译
/ds translations info
/ds translations reload
/ds translations set <lang>

权限

父级授予(仅限操作员):

datasync.admin

自助服务权限,默认为 true:

datasync.command.whoami
细粒度子命令授予
datasync.command.status
datasync.command.reload
datasync.command.saveall
datasync.command.saveandkick
datasync.command.lookup
datasync.command.purge
datasync.command.forcesync
datasync.command.history
datasync.command.restore
datasync.command.export
datasync.command.import
datasync.command.cache
datasync.command.audit
datasync.command.diff
datasync.command.module
datasync.command.snapshot
datasync.command.doctor
datasync.command.metrics
datasync.command.version
datasync.command.compare
datasync.command.test
datasync.command.errors
datasync.command.watch
datasync.command.reset
datasync.command.benchmark
datasync.command.stats
datasync.command.move
datasync.command.view
datasync.command.view-confirm
datasync.command.edit
datasync.command.debug
datasync.command.reshard
datasync.command.pause
datasync.command.resume
datasync.command.translations
datasync.command.whois
datasync.command.search

高级用户权限,支持复制物品:

datasync.command.view.copy

警告: 请谨慎授予 datasync.command.view.copy。它会在 /ds view 中启用 Shift+点击物品复制功能。


开发者 API

api 模块已发布至 https://repo.tmp0.cc/releases。坐标如下:

de.squarecodefx:datasynchronization-api:<version>

功能:

  • 加载和保存玩家数据
  • 访问和恢复快照
  • 原子化单字段补丁
  • 注册自定义 SyncModules
  • 发布和订阅跨服务器自定义消息
  • 检查指标和运行时配置
  • 使用类型化的 SyncKeys 进行模块数据存储,无需样板代码
公共包
de.squarecodefx.datasynchronization.api
de.squarecodefx.datasynchronization.api.annotation
de.squarecodefx.datasynchronization.api.data
de.squarecodefx.datasynchronization.api.event
de.squarecodefx.datasynchronization.api.exception
de.squarecodefx.datasynchronization.api.module
入口点
DataSynchronizationAPI api = DataSynchronizationProvider.get();
示例操作
api.getPlayerData(uuid);
api.getPlayerSnapshots(uuid, 10);
api.forceSyncPlayer(uuid);
api.patchPlayerField(uuid, "health", 20.0);
api.setSyncPaused(uuid, true);
api.publishCustomMessage("channel", "payload");

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源