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");
DataSynchronization
Cross-server player data sync for Paper, Purpur and Folia 26.3+
No dupes · No data loss · Folia-ready · Redis / RabbitMQ / SQL / MongoDB · History, rollback, audit and GUI tools
Overview
DataSynchronization keeps player data perfectly synchronised across an entire Minecraft network. It transfers inventories, ender chests, vitals, advancements, attributes, potion effects, locations, recipes, statistics, PersistentDataContainer (NBT) bytes and custom plugin data between servers.
Unlike legacy "last-write-wins" sync plugins, DataSynchronization is built to eliminate the dupe-and-data-loss class of bugs. Every save passes through a per-player FIFO queue and is fenced by a monotonic session-ownership token, so a write from a superseded peer is rejected before it can touch the database.
Requirements
- Server: Paper 26.3++, Purpur or Folia
- Java: 25 or newer
- Storage: H2, MariaDB, MySQL, PostgreSQL or MongoDB
- Recommended for networks: Redis
- Optional: RabbitMQ, Vault, PlaceholderAPI
Not supported: Bukkit and Spigot. The plugin relies on Paper-only APIs (native Adventure, PersistentDataContainer byte serialization, AsyncChatEvent, modern Paper metadata).
What gets synced
Every category can be enabled or disabled individually.
- Inventory: main inventory, armor, off-hand, ender chest
- Vitals: health, food, saturation, exhaustion, air, XP, level, score
- Effects: potion effects, attributes (max HP, speed, damage, reach, …)
- World state: location, bed spawn, gamemode, flight state, fly and walk speed
- Progression: advancements, recipes, statistics
- Plugin data: PersistentDataContainer / NBT byte data
- Custom modules: via the SyncModule API
- Per-world blacklist: exclude creative, build or minigame worlds
Core features
Storage and cluster
- H2, MariaDB, MySQL, PostgreSQL and MongoDB backends
- Sharded storage variants for large networks
- Redis pub/sub, RabbitMQ fanout, plugin messaging or auto-detect
- Session ownership with Redis SETNX, monotonic fencing tokens and TTL heartbeats
- Per-UUID FIFO write coalescing
- GZIP compression for 4-6x smaller stored rows
- Tiered cache (L1 in-memory + L2 Redis)
- Circuit breaker on the storage layer with automatic recovery
- Exponential-backoff retries on transient failures
- Async pipeline with priority queue and backpressure
Platform and runtime
- First-class Paper, Purpur and Folia support
- Folia entity-region scheduler used natively
- Native Adventure usage, no shaded BukkitAudiences bridge
- Inline-dispatch optimisation on hot paths
- bStats integration for setup-shape telemetry
Reliability and safety
- Per-player pause, persistent across restart and broadcast cluster-wide
- Auto-resume of duration-bound pauses via leader-elected sweep
- Optional kick-on-failed-sync with custom message
- Creative-mode inventory sync protection
- Confirmation prompts on destructive operations
- Command cooldowns for heavy operations
- SQL-injection-safe identifier validation
- Atomic export rename (write-temp-then-rename)
- Configurable 512 MiB import-size cap
- Parallel batch import with semaphore backpressure
History and rollback
- Per-player snapshot history with configurable rolling retention
- Pinned snapshots survive rolling cleanup
- Selective restore via
--only / --except
- Preview diff before applying a restore
- Compare two snapshots of one player, or two players side by side
Live GUI tools
/ds view - paginated player browser with sort, search, snapshot navigation and compare mode
/ds edit - in-game inventory, ender-chest and stats editor
- Bossbar progress for save-all, export, import and reshard
Update notifications
- Asynchronous SpigotMC API check at startup and every six hours
- Result shown in
/ds version, the System block of /ds status, and as a one-shot click-to-SpigotMC notice for operators on join
- Five-second timeout, never blocks the main thread, polite User-Agent
- Disable with
update-checker.enabled: false on networks with strict outbound policies
Admin tooling
Operations is a first-class feature surface, not an afterthought.
- Doctor: storage, messaging, cache, circuit breaker and config-smell checks
- Metrics: uptime, save and load counts, retries, queue depth, cache hit rate
- Benchmark: synthetic save and load cycles with min / p50 / p95 / max
- Round-trip test: per-player serializer self-check
- Stats: row count, average and largest sizes, top-N heaviest players
- Errors view: in-game WARNING / SEVERE log viewer, cluster-synced
- Watch: live-tail sync events for selected players
- Whoami: own identity, permissions and session state
- Whois: forensic combined view of a player
- Search: grep across audit and SEVERE-error buffers
- Audit log: 25 tracked action types, filterable and paginated
- Debug: pipeline, session and sharding internals with live refresh
- Import / export: streaming JSON with dry-run and selective scope
Modules and API
Third-party plugins can synchronise their own data through the SyncModule API without forking DataSynchronization.
- Register custom capture and apply logic
- Per-module metrics
- Per-module status sections
- Per-module GUI icons in
/ds view
- Per-module subcommands under
/ds <module-id>
- Per-module scheduled tasks
- Per-module PlaceholderAPI placeholders
- Data versioning with migration hooks
- Merge strategies for UUID merges
- Atomic single-field patches without load-mutate-save
Bundled modules: Vault economy and Advancements (with recipes and statistics toggles).
Translations
Six languages out of the box: English, Deutsch, Español, Português brasileiro, Français, Polski.
- MiniMessage formatting throughout (colours, gradients, hover and click events)
- Live reload via WatchService - edit a YAML, save, see the change immediately
- Four-layer fallback chain: on-disk active, on-disk default, JAR-bundled active, JAR-bundled default
- Versioned bundles with safe auto-upgrade: outdated on-disk files are backed up before replacement
- Drop-in YAML support for any additional ISO-639 language
Comparison
Compared to HuskSync
- Monotonic fencing tokens prevent late, outdated writes
- Module API for arbitrary plugin data, including status and GUI surfaces
- In-game GUI editor, not just read-only viewing
- Storage sharding with offline migration tooling
- Snapshot pinning and selective restore
- Folia-first scheduler design
- Six bundled languages, live-reloadable
- Doctor command with infrastructure and config diagnostics
- Redis, RabbitMQ and plugin-messaging support (not just Redis)
- Tiered cache reduces Redis call volume by approximately 20x
- GZIP-compressed payloads
- Cluster-wide auto-purge with leader election
- PersistentDataContainer sync as a first-class data type
Compared to legacy sync plugins
- Modern database support across SQL and NoSQL
- Async pipeline with backpressure
- Circuit breaker and exponential-backoff retries
- Session fencing
- Streaming import and export with progress reporting
- History, rollback and audit trail
- MiniMessage translations
- SQL-injection-safe identifier handling
Quickstart
Single Paper server
storage-method: h2
cache:
type: memory
messaging-service: none
Drop the jar into plugins/ and start the server.
Multi-server network
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: "..."
All servers share Redis and MariaDB. Sessions, cache and messaging are Redis-backed. Each server gets its own server-name.
Recommendations
Storage backend
- Single server, dev, CI: H2
- Multi-server SQL setup: MariaDB or PostgreSQL
- Document-based stack: MongoDB
- 2,000+ concurrent players: any of the above with sharding enabled
Redis
Not required for single-server setups. Strongly recommended for multi-server networks: Redis unlocks atomic session claims, a shared cache across servers and sub-millisecond pub/sub invalidation.
Sharding
Enable only when a single database is no longer sufficient. Most networks below 2,000 concurrent players run comfortably on a single MariaDB or PostgreSQL instance.
What not to sync
- Disable
statistics on networks with long-lived accounts (those maps can grow into thousands of entries per player)
- Disable
persistentDataContainer if no plugin actually writes PDC bytes you need to share
FAQ
Does it work on Folia?
Yes. Capture runs on the player's entity-region thread via the platform scheduler; everything else runs off-thread.
Why not Spigot or Bukkit?
The plugin uses Paper-only APIs (native Adventure, PersistentDataContainer byte serialization, AsyncChatEvent, modern Paper metadata) without Spigot equivalents.
What happens if the database goes down?
The circuit breaker opens after a configurable number of consecutive failures, stops hammering the database, and resumes automatically when it recovers.
What happens if a server crashes mid-session?
The session-ownership claim expires via TTL. Another server can then acquire the claim and load the player. Late writes from the crashed peer are rejected by the fencing token.
Can I sync my custom plugin's data?
Yes. Implement SyncModule (or subclass AbstractSyncModule) and register it through the API or auto-discovery.
Can I restore only part of a snapshot?
Yes. Use /ds restore <player> <#> --only inventory,enderchest or --except statistics.
How large are stored rows?
With GZIP enabled (default), typical late-game players sit in the 10-40 KiB range.
Can I add my own language?
Copy translations/en.yml to e.g. it.yml, translate, save. The file watcher reloads it live.
Will translations break when I update the plugin?
No. Each bundled YAML carries a meta.version; outdated on-disk files are backed up to <name>.yml<random-suffix> and replaced with the new bundled version automatically.
Commands
Main command: /datasync (alias /ds).
Core
/ds status [--section <name>]
/ds reload
/ds version
/ds metrics [--reset]
/ds doctor [--quiet]
/ds debug <pipeline|session|sharding> [player] [--watch]
Player data
/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]
History and snapshots
/ds snapshot <player> [--note ...]
/ds history <player> [--contains ...] [--since 1h|7d] [page|pin <#>|unpin <#>]
/ds diff <player> <#1> <#2> [--section <a,b>] [page]
/ds restore <player> <#> [--only|--except types] [--preview] [--reason ...] [confirm]
Maintenance
/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>]
Cache
/ds cache info
/ds cache clear [player|confirm]
/ds cache refresh [player]
Audit and diagnostics
/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]
Modules
/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>
Translations
/ds translations info
/ds translations reload
/ds translations set <lang>
Permissions
Parent grant (operators only):
datasync.admin
Self-service permission, default true:
datasync.command.whoami
Granular per-subcommand grants
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
Power-user permission, dupe-capable:
datasync.command.view.copy
Warning: grant datasync.command.view.copy deliberately. It enables shift-click item copying inside /ds view.
Developer API
The api module is published to https://repo.tmp0.cc/releases. Coordinates:
de.squarecodefx:datasynchronization-api:<version>
Capabilities:
- Load and save player data
- Access and restore snapshots
- Atomic single-field patches
- Register custom SyncModules
- Publish and subscribe to cross-server custom messages
- Inspect metrics and runtime configuration
- Use typed SyncKeys for module data without boilerplate
Public packages
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
Entry point
DataSynchronizationAPI api = DataSynchronizationProvider.get();
Example operations
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
登录后参与评分
还没有评论,来抢沙发吧