[MD]
# YRDatabase-Waterdog - WaterdogPE 数据库前置插件
> 🌐 WaterdogPE 跨服数据同步解决方案，配合 YRDatabase-Nukkit 实现真正的跨服数据管理
---
## 📖 插件简介
YRDatabase-Waterdog 是专为 WaterdogPE 代理服务器设计的数据库管理插件，通过 Redis Pub/Sub 实现跨服通信，让子服插件能够区分玩家的"真实加入/退出"和"服务器转服"。
**核心功能**：
- 🔔 **实时通知** - 通过 Redis Pub/Sub 向所有子服发送玩家真实上线/下线消息
- 🎯 **智能识别** - 区分玩家转服和真实退出，避免频繁持久化
- ⚡ **高性能** - 基于 Redis 的发布订阅模式，低延迟通信
- 📡 **心跳监测** - 定时发送在线人数和会话数据
- 🔌 **即插即用** - 配合 YRDatabase-Nukkit 无需额外开发
---
## 🎮 使用场景
### 问题：为什么需要这个插件？
在多服环境下，玩家频繁转服会导致以下问题：
1. **数据频繁持久化** - 每次转服都触发保存，浪费性能
2. **转服卡顿** - 数据库写入导致玩家转服延迟
3. **数据不一致** - 多服同时写入可能导致数据冲突
### 解决方案
使用 YRDatabase-Waterdog + YRDatabase-Nukkit：
```
玩家真实登录 → WaterdogPE 发送 REAL_JOIN
↓
所有子服收到通知 → 标记玩家为"真实在线"
↓
玩家在子服间转服 → 不触发持久化，只更新缓存
↓
玩家真实退出 → WaterdogPE 发送 REAL_QUIT
↓
当前子服收到通知 → 执行数据持久化
```
---
## 📥 下载安装
### 下载地址
**GitHub Releases**：[YRDatabase Releases](https://github.com/MufHead/YRDatabase/releases)
**Jenkins CI 构建**：[最新构建](https://motci.cn/job/YRDatabase/)
### 安装步骤
1. 下载 `YRDatabase-Waterdog.jar`
2. 放入 WaterdogPE 服务器 `plugins/` 目录
3. 启动 WaterdogPE，插件会自动生成配置文件
4. 编辑 `plugins/YRDatabase-Waterdog/config.yml` 配置 Redis
5. 重启 WaterdogPE
---
## ⚙️ 配置文件
```yaml
# YRDatabase-Waterdog 配置文件
# Redis 配置
redis:
enabled: true
host: localhost
port: 6379
password: ""
database: 0
timeout: 3000
# Redis Pub/Sub 配置
pubsub:
enabled: true
# Pub/Sub 频道配置
channels:
player-join: "yrdatabase:player:join"
player-quit: "yrdatabase:player:quit"
heartbeat: "yrdatabase:heartbeat"
# 心跳间隔（秒）
heartbeat-interval: 30
# 网易 UID 记录功能
netease-uid:
enabled: true
```
---
## 🔧 工作原理
### 1. 玩家真实加入流程
```
1. 玩家连接到 WaterdogPE
↓
2. WaterdogPE 触发 PlayerJoinEvent
↓
3. YRDatabase-Waterdog 记录玩家会话
↓
4. 发送 REAL_JOIN 消息到 Redis
{
"uid": "123456789",
"username": "Steve",
"timestamp": 1234567890
}
↓
5. 所有 Nukkit 子服收到消息
↓
6. 子服标记玩家为"真实在线"
↓
7. 玩家加入某个子服时触发 PlayerDataInitializeEvent(REAL_JOIN)
```
### 2. 玩家转服流程
```
1. 玩家从子服A转到子服B
↓
2. 子服A触发 PlayerQuitEvent
↓
3. YRDatabase-Nukkit 检查 Redis：玩家仍在 WaterdogPE 会话中
↓
4. 触发 PlayerDataPersistEvent(SERVER_TRANSFER)
↓
5. 插件只保存到 Redis 缓存，不写入数据库
↓
6. 子服B触发 PlayerJoinEvent
↓
7. 触发 PlayerDataInitializeEvent(SERVER_TRANSFER)
↓
8. 插件从 Redis 快速加载数据
```
### 3. 玩家真实退出流程
```
1. 玩家断开 WaterdogPE 连接
↓
2. WaterdogPE 触发 PlayerDisconnectEvent
↓
3. YRDatabase-Waterdog 移除玩家会话
↓
4. 发送 REAL_QUIT 消息到 Redis
{
"uid": "123456789",
"username": "Steve",
"lastServer": "lobby"
}
↓
5. 所有 Nukkit 子服收到消息
↓
6. 玩家所在的子服触发 PlayerDataPersistEvent(REAL_QUIT)
↓
7. 插件执行数据持久化到数据库
```
---
## 📡 Redis Pub/Sub 频道
### 1. yrdatabase:player:join
**玩家真实加入频道**
发送时机：玩家连接到 WaterdogPE
消息格式：
```json
{
"uid": "123456789", // 玩家UID（网易UID或UUID）
"username": "Steve", // 玩家名称
"timestamp": 1234567890 // 加入时间戳（毫秒）
}
```
### 2. yrdatabase:player:quit
**玩家真实退出频道**
发送时机：玩家断开 WaterdogPE 连接
消息格式：
```json
{
"uid": "123456789", // 玩家UID
"username": "Steve", // 玩家名称
"lastServer": "lobby", // 最后所在服务器
"timestamp": 1234567890 // 退出时间戳（毫秒）
}
```
### 3. yrdatabase:heartbeat
**心跳频道**
发送时机：每 30 秒（可配置）
消息格式：
```json
{
"timestamp": 1234567890, // 当前时间戳
"online": 100, // 当前在线人数
"sessions": 100 // 当前会话数
}
```
---
## 🌐 完整多服配置示例
### 网络拓扑
```
┌─────────────────┐
│ WaterdogPE │
│ (代理服务器) │
└────────┬────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Lobby │ │ Survival│ │ Creative│
│ (子服1) │ │ (子服2) │ │ (子服3) │
└─────────┘ └─────────┘ └─────────┘
│ │ │
└────────────────────┼────────────────────┘
│
┌────────▼────────┐
│ Redis Server │
│ MySQL Server │
└─────────────────┘
```
### 1. WaterdogPE 配置
**安装插件**：
- `YRDatabase-Waterdog.jar`
**配置文件** (`plugins/YRDatabase-Waterdog/config.yml`)：
```yaml
redis:
enabled: true
host: 192.168.1.100 # Redis 服务器地址
port: 6379
password: ""
database: 0
pubsub:
enabled: true
heartbeat-interval: 30
netease-uid:
enabled: true
```
### 2. Lobby 子服配置
**安装插件**：
- `YRDatabase.jar`
**配置文件** (`plugins/YRDatabase/config.yml`)：
```yaml
mysql:
enabled: true
host: 192.168.1.100
port: 3306
database: minecraft
username: root
password: your_password
redis:
enabled: true
host: 192.168.1.100
port: 6379
password: ""
database: 0
pubsub:
enabled: true # 启用 Pub/Sub 监听
```
### 3. Survival 和 Creative 子服配置
**配置相同**：与 Lobby 子服配置一致
---
## 📊 性能对比
### 不使用 YRDatabase-Waterdog
```
玩家操作 数据库操作 性能影响
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
登录 WaterdogPE 无 -
进入 Lobby 读取数据库 (100ms) 卡顿
Lobby → Survival 写入数据库 (50ms) 卡顿
读取数据库 (100ms) 卡顿
Survival → Creative 写入数据库 (50ms) 卡顿
读取数据库 (100ms) 卡顿
退出服务器 写入数据库 (50ms) 卡顿
总计：4次写入 + 3次读取 = 550ms 延迟
```
### 使用 YRDatabase-Waterdog
```
玩家操作 数据库操作 性能影响
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
登录 WaterdogPE 读取数据库 (100ms) 首次卡顿
进入 Lobby 读取 Redis (5ms) 流畅
Lobby → Survival 写入 Redis (5ms) 流畅
读取 Redis (5ms) 流畅
Survival → Creative 写入 Redis (5ms) 流畅
读取 Redis (5ms) 流畅
退出服务器 写入数据库 (50ms) 可接受
写入 Redis (5ms) 流畅
总计：1次数据库读 + 1次数据库写 + 6次Redis = 180ms 延迟
```
**性能提升**：`550ms → 180ms`，延迟减少 **67%** ✅
---
## 🔍 监控和调试
### 查看 Redis Pub/Sub 消息
使用 Redis CLI 监控消息：
```bash
# 连接到 Redis
redis-cli
# 订阅所有 YRDatabase 频道
PSUBSCRIBE yrdatabase:*
# 或订阅特定频道
SUBSCRIBE yrdatabase:player:join
SUBSCRIBE yrdatabase:player:quit
SUBSCRIBE yrdatabase:heartbeat
```
### 查看 WaterdogPE 日志
```
[YRDatabase-Waterdog] 玩家 Steve (UID: 123456789) 加入代理
[YRDatabase-Waterdog] 发送 REAL_JOIN: Steve → yrdatabase:player:join
[YRDatabase-Waterdog] 玩家 Steve 切换到服务器: survival
[YRDatabase-Waterdog] 玩家 Steve 断开连接（最后所在: survival）
[YRDatabase-Waterdog] 发送 REAL_QUIT: Steve → yrdatabase:player:quit
```
### 查看子服日志
```
[YRDatabase] Redis Pub/Sub 订阅成功
[YRDatabase] 监听频道: yrdatabase:player:join, yrdatabase:player:quit
[YRDatabase] 收到REAL_JOIN: Steve (UID: 123456789)
[YRDatabase] 当前真实在线玩家数: 10
[YRDatabase] 收到REAL_QUIT: Steve (UID: 123456789, 最后所在: survival)
[YRDatabase] 当前真实在线玩家数: 9
```
---
## 🔧 常见问题
### Q: 必须安装 Redis 吗？
**A:** 是的。YRDatabase-Waterdog 依赖 Redis Pub/Sub 实现跨服通信。
### Q: 可以只在 WaterdogPE 安装这个插件吗？
**A:** 不可以。必须同时在 WaterdogPE 和所有 Nukkit 子服安装对应的插件：
- WaterdogPE: `YRDatabase-Waterdog.jar`
- Nukkit 子服: `YRDatabase.jar`（并启用 `pubsub.enabled: true`）
### Q: 如果某个子服没有安装 YRDatabase 会怎样？
**A:** 该子服无法收到 REAL_JOIN/REAL_QUIT 消息，会按照单服模式运行（使用 LOCAL_JOIN/LOCAL_QUIT）。
### Q: Redis 连接失败怎么办？
**A:** 检查：
1. Redis 服务是否启动：`redis-cli ping`
2. WaterdogPE 能否访问 Redis 服务器（防火墙、网络）
3. 配置文件中的地址、端口、密码是否正确
4. 查看 WaterdogPE 日志中的错误信息
### Q: 如何测试是否工作正常？
**A:**
1. 启动 WaterdogPE 和一个子服
2. 玩家登录后查看日志，应该看到：
- WaterdogPE 发送 `REAL_JOIN` 消息
- 子服收到 `REAL_JOIN` 消息
3. 玩家退出后查看日志，应该看到：
- WaterdogPE 发送 `REAL_QUIT` 消息
- 子服收到 `REAL_QUIT` 消息
---
## 🛠️ 高级配置
### 自定义频道名称
```yaml
pubsub:
enabled: true
channels:
player-join: "my-network:join"
player-quit: "my-network:quit"
heartbeat: "my-network:heartbeat"
```
**注意**：如果修改了频道名称，所有子服的配置也必须同步修改。
### 调整心跳间隔
```yaml
pubsub:
heartbeat-interval: 60 # 改为 60 秒
```
心跳间隔越短，数据越实时，但会增加 Redis 负载。
### 禁用心跳
如果不需要监控在线人数，可以禁用心跳：
```yaml
pubsub:
heartbeat-interval: 0 # 设为 0 禁用
```
---
## 📚 开发者接口
虽然 YRDatabase-Waterdog 主要用于自动通信，但你也可以在 WaterdogPE 插件中访问它：
```java
public class MyPlugin extends Plugin {
private YRDatabaseWaterdog yrDatabase;
@Override
public void onEnable() {
yrDatabase = (YRDatabaseWaterdog) getProxy().getPluginManager().getPlugin("YRDatabase-Waterdog");
if (yrDatabase == null) {
getLogger().error("YRDatabase-Waterdog 未安装！");
return;
}
// 获取当前在线玩家数
int onlineCount = yrDatabase.getOnlinePlayerCount();
// 手动发送自定义消息
yrDatabase.publishMessage("my-custom-channel", "{\"data\":\"hello\"}");
}
}
```
---
## 📊 架构设计
### 数据流向
```
┌─────────────────────────────────────────────────────────────┐
│ WaterdogPE │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ YRDatabase-Waterdog Plugin │ │
│ │ │ │
│ │ PlayerJoinEvent → 发送 REAL_JOIN 到 Redis │ │
│ │ PlayerQuitEvent → 发送 REAL_QUIT 到 Redis │ │
│ └───────────────────┬───────────────────────────────────┘ │
└────────────────────────┼─────────────────────────────────────┘
│
Redis Pub/Sub
│
┌────────────────┼────────────────┐
│ │ │
┌───────▼───────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Nukkit子服1 │ │ Nukkit子服2 │ │ Nukkit子服3 │
│ │ │ │ │ │
│ YRDatabase │ │ YRDatabase │ │ YRDatabase │
│ ↓ │ │ ↓ │ │ ↓ │
│ 订阅消息 │ │ 订阅消息 │ │ 订阅消息 │
│ 触发事件 │ │ 触发事件 │ │ 触发事件 │
└───────────────┘ └─────────────┘ └─────────────┘
```
---
## 📜 开源协议
本插件使用 **MIT License** 开源协议。
---
## 💖 支持作者
如果这个插件对你有帮助，请：
- ⭐ 在 GitHub 上给项目点个 Star
- 📢 分享给其他服主
- 🐛 提交 Bug 和建议
---
**插件版本**：v1.0.3
**支持的 WaterdogPE 版本**：2.0.0+
**最后更新**：2026-01-14
**GitHub**：https://github.com/MufHead/YRDatabase
[/MD]
