- 版权类型
- 转载
- 插件中文名
- mc-data-bridge
- 插件英文名
- mc-data-bridge
- 支持的核心 [服务端]
- Folia
- 语言支持
- 中文(简体)
- 适配Minecraft版本 [Java]
- 1.21
[MD]
# MC Data Bridge
*高性能、安全、通用的玩家数据同步方案*
MC Data Bridge 是一套面向 **Paper/Spigot**、**Folia**、**BungeeCord** 与 **Velocity** 的高性能混合同步插件。它专为高并发生产环境的服务器网络设计，可在多个服务器之间无缝同步玩家数据，包括生命值、饥饿值、经验、背包、末影箱、进度、配方、原版统计、伙伴与宠物，以及 PDC 元数据，并兼顾低延迟与企业级安全性。
## 快速开始
1. **部署插件**
将单个 JAR 文件放入每台 Minecraft 后端服务器（Paper、Folia 或 Spigot）以及代理端（Velocity 或 BungeeCord）的 `plugins/` 文件夹：
```text
mc-data-bridge-*.jar
```
2. **配置后端服务器**
在每台后端服务器上编辑以下配置文件：
```text
plugins/mc-data-bridge/config.yml
```
为每台服务器设置唯一的 `server-id`，例如 `"survival-1"`；随后填写 MySQL 或 MariaDB 数据库连接信息，并将 `security.seed` 设置为足够随机且保密的字符串。
3. **重启并同步**
重启所有后端服务器与代理组件。完成后，玩家数据同步将自动启用。
## 核心功能
- **通用单 JAR 混合架构**
同一个 JAR 文件可运行于 Spigot、Paper、Folia、BungeeCord 和 Velocity，并会自动启用对应平台的处理逻辑。
- **全面的跨服数据同步**
可同步生命值、饥饿值、饱和度、饥饿消耗值、经验、背包、盔甲栏、药水效果、末影箱、进度、配方、原版统计、PDC 元数据、飞行与游戏模式状态、伙伴与宠物、地图，以及按游戏模式分离的档案数据。
- **事件驱动的锁释放通知**
源服务器保存玩家状态后会立即发送 `LockReleased` 信号，立刻唤醒目标服务器的预登录线程，将切服时等待数据锁释放的延迟降至约 50ms。
- **分布式锁栅栏令牌**
通过单调递增的 `lock_version` 代数计数器隔离过期写入，防止发生 GC 暂停等延迟的服务器覆盖当前活跃玩家会话的数据。
- **单事务原子持久化**
将规范化组件表的更新，包括 `databridge_inventories`、`statistics`、`metadata`、`companions` 和 `maps`，连同锁释放操作一并纳入同一数据库事务：
```java
setAutoCommit(false)
...
commit()
```
- **带密钥的 HMAC-SHA256 与数据完整性校验**
使用标准 `HmacSHA256` 密钥派生与服务器盐值保护玩家身份信息，并可检测规范化组件数据表遭到篡改的情况。
- **身份模式与自动迁移**
支持 `PREMIUM` 与 `HYBRID` 身份模式；可对接 FastLogin 的 PreLogin 流程，以及 AuthMe 的登录和 2FA/TOTP 流程，自动将离线 UUID 数据迁移至在线 UUID。
- **交互式背包与末影箱查看器**
使用 `invsee` 和 `endersee` 可实时查看或编辑离线玩家、跨服玩家的背包与末影箱。通过 `--edit` 参数或右键操作进入编辑模式，关闭 GUI 后修改将自动写入数据库。
- **Folia 区域化线程支持**
完全兼容 Folia 的区域化线程模型，可在现代多线程服务器集群中安全处理玩家数据。
- **内置 Prometheus 导出器**
提供 HTTP `/metrics` 端点，用于监控 HikariCP 连接池、事务耗时、活跃查询及缓存效率。
- **细粒度同步与黑名单控制**
可在 `config.yml` 中分别控制各数据组件的同步开关，并配置服务器与世界黑名单。
## 命令与权限
### 数据查看与编辑
#### `/databridge inspect <player> [inventory|enderchest] [--edit]`
打开 GUI，查看或编辑已保存的玩家数据与背包。
- 权限：`databridge.inspect`/*databridge.inspect.edit*(for*--edit*)
#### `/databridge invsee <player> [--edit]`
打开指定玩家已保存的背包查看界面，或进入编辑界面。
- 权限：`databridge.inspect`/*databridge.inspect.edit*(for*--edit*)
#### `/databridge endersee <player> [--edit]`
打开指定玩家已保存的末影箱查看界面，或进入编辑界面。
- 权限：`databridge.inspect`/*databridge.inspect.edit*(for*--edit*)
### 管理命令
#### `/databridge migrate <src> <dest>`
在两个身份之间安全迁移数据。
- 权限：`databridge.admin`
#### `/databridge unlock <player>`
手动释放卡住的玩家数据锁。此命令适用于 Spigot、Folia、BungeeCord 与 Velocity。
- 权限：`databridge.admin`
#### `/databridge reload`
重新加载配置文件与数据库连接池。
- 权限：`databridge.admin`
### 代理端命令
- `/databridge unlock <player>`
适用于 BungeeCord 与 Velocity，在整个服务器网络中释放指定玩家的数据锁。
- `/databridge forceunlock <player>`
适用于 BungeeCord 与 Velocity，向后端服务器转发信号，要求其立即释放数据锁。
### 权限节点
| 权限节点 | 说明 |
|---|---|
| `databridge.inspect` | 允许以安全的只读模式查看玩家数据、背包和末影箱。 |
| `databridge.inspect.edit` | 允许通过 `--edit` 参数或右键交互编辑背包与末影箱。 |
| `databridge.admin` | 拥有全部命令与功能的管理权限。 |
## 下载与文档
- [**GitHub Repository**](https://github.com/westkevin12/mc-data-bridge) - 源代码、问题追踪与 Wiki。
- [**Database Setup Guide**](https://github.com/westkevin12/mc-data-bridge/blob/main/DATABASE_SETUP.md) - MySQL 与 MariaDB 配置、Docker 部署及异地备份说明。
- [**Architecture Guide**](https://github.com/westkevin12/mc-data-bridge/blob/main/ARCHITECTURE.md) - 时序图、锁栅栏机制与关系型 SQL 数据库架构。
[/MD]
# MC Data Bridge
*高性能、安全、通用的玩家数据同步方案*
MC Data Bridge 是一套面向 **Paper/Spigot**、**Folia**、**BungeeCord** 与 **Velocity** 的高性能混合同步插件。它专为高并发生产环境的服务器网络设计，可在多个服务器之间无缝同步玩家数据，包括生命值、饥饿值、经验、背包、末影箱、进度、配方、原版统计、伙伴与宠物，以及 PDC 元数据，并兼顾低延迟与企业级安全性。
## 快速开始
1. **部署插件**
将单个 JAR 文件放入每台 Minecraft 后端服务器（Paper、Folia 或 Spigot）以及代理端（Velocity 或 BungeeCord）的 `plugins/` 文件夹：
```text
mc-data-bridge-*.jar
```
2. **配置后端服务器**
在每台后端服务器上编辑以下配置文件：
```text
plugins/mc-data-bridge/config.yml
```
为每台服务器设置唯一的 `server-id`，例如 `"survival-1"`；随后填写 MySQL 或 MariaDB 数据库连接信息，并将 `security.seed` 设置为足够随机且保密的字符串。
3. **重启并同步**
重启所有后端服务器与代理组件。完成后，玩家数据同步将自动启用。
## 核心功能
- **通用单 JAR 混合架构**
同一个 JAR 文件可运行于 Spigot、Paper、Folia、BungeeCord 和 Velocity，并会自动启用对应平台的处理逻辑。
- **全面的跨服数据同步**
可同步生命值、饥饿值、饱和度、饥饿消耗值、经验、背包、盔甲栏、药水效果、末影箱、进度、配方、原版统计、PDC 元数据、飞行与游戏模式状态、伙伴与宠物、地图，以及按游戏模式分离的档案数据。
- **事件驱动的锁释放通知**
源服务器保存玩家状态后会立即发送 `LockReleased` 信号，立刻唤醒目标服务器的预登录线程，将切服时等待数据锁释放的延迟降至约 50ms。
- **分布式锁栅栏令牌**
通过单调递增的 `lock_version` 代数计数器隔离过期写入，防止发生 GC 暂停等延迟的服务器覆盖当前活跃玩家会话的数据。
- **单事务原子持久化**
将规范化组件表的更新，包括 `databridge_inventories`、`statistics`、`metadata`、`companions` 和 `maps`，连同锁释放操作一并纳入同一数据库事务：
```java
setAutoCommit(false)
...
commit()
```
- **带密钥的 HMAC-SHA256 与数据完整性校验**
使用标准 `HmacSHA256` 密钥派生与服务器盐值保护玩家身份信息，并可检测规范化组件数据表遭到篡改的情况。
- **身份模式与自动迁移**
支持 `PREMIUM` 与 `HYBRID` 身份模式；可对接 FastLogin 的 PreLogin 流程，以及 AuthMe 的登录和 2FA/TOTP 流程，自动将离线 UUID 数据迁移至在线 UUID。
- **交互式背包与末影箱查看器**
使用 `invsee` 和 `endersee` 可实时查看或编辑离线玩家、跨服玩家的背包与末影箱。通过 `--edit` 参数或右键操作进入编辑模式，关闭 GUI 后修改将自动写入数据库。
- **Folia 区域化线程支持**
完全兼容 Folia 的区域化线程模型，可在现代多线程服务器集群中安全处理玩家数据。
- **内置 Prometheus 导出器**
提供 HTTP `/metrics` 端点，用于监控 HikariCP 连接池、事务耗时、活跃查询及缓存效率。
- **细粒度同步与黑名单控制**
可在 `config.yml` 中分别控制各数据组件的同步开关，并配置服务器与世界黑名单。
## 命令与权限
### 数据查看与编辑
#### `/databridge inspect <player> [inventory|enderchest] [--edit]`
打开 GUI，查看或编辑已保存的玩家数据与背包。
- 权限：`databridge.inspect`/*databridge.inspect.edit*(for*--edit*)
#### `/databridge invsee <player> [--edit]`
打开指定玩家已保存的背包查看界面，或进入编辑界面。
- 权限：`databridge.inspect`/*databridge.inspect.edit*(for*--edit*)
#### `/databridge endersee <player> [--edit]`
打开指定玩家已保存的末影箱查看界面，或进入编辑界面。
- 权限：`databridge.inspect`/*databridge.inspect.edit*(for*--edit*)
### 管理命令
#### `/databridge migrate <src> <dest>`
在两个身份之间安全迁移数据。
- 权限：`databridge.admin`
#### `/databridge unlock <player>`
手动释放卡住的玩家数据锁。此命令适用于 Spigot、Folia、BungeeCord 与 Velocity。
- 权限：`databridge.admin`
#### `/databridge reload`
重新加载配置文件与数据库连接池。
- 权限：`databridge.admin`
### 代理端命令
- `/databridge unlock <player>`
适用于 BungeeCord 与 Velocity，在整个服务器网络中释放指定玩家的数据锁。
- `/databridge forceunlock <player>`
适用于 BungeeCord 与 Velocity，向后端服务器转发信号，要求其立即释放数据锁。
### 权限节点
| 权限节点 | 说明 |
|---|---|
| `databridge.inspect` | 允许以安全的只读模式查看玩家数据、背包和末影箱。 |
| `databridge.inspect.edit` | 允许通过 `--edit` 参数或右键交互编辑背包与末影箱。 |
| `databridge.admin` | 拥有全部命令与功能的管理权限。 |
## 下载与文档
- [**GitHub Repository**](https://github.com/westkevin12/mc-data-bridge) - 源代码、问题追踪与 Wiki。
- [**Database Setup Guide**](https://github.com/westkevin12/mc-data-bridge/blob/main/DATABASE_SETUP.md) - MySQL 与 MariaDB 配置、Docker 部署及异地备份说明。
- [**Architecture Guide**](https://github.com/westkevin12/mc-data-bridge/blob/main/ARCHITECTURE.md) - 时序图、锁栅栏机制与关系型 SQL 数据库架构。
[/MD]