# MCSManager BungeeCord 插件

这是一个用于BungeeCord代理服务器的插件，可以动态增改MCSManager中的Minecraft服务器实例，无需重启代理服务器即可自动同步服务器列表。

#注意这只是一个小型工具请谨慎使用

## 功能特性
- **自动同步**: 定期从MCSManager获取实例信息并更新代理服务器配置
- **智能过滤**: 自动忽略代理服务器实例（BungeeCord、Velocity、Waterfall等）
- ⚡ **实时更新**: 实时添加新实例和移除已删除的实例
- ️ **管理命令**: 提供完整的管理命令来控制插件功能
- **灵活配置**: 支持自定义API地址、守护进程ID、同步间隔、服务器命名等配置
- **守护进程支持**: 支持多守护进程环境，可配置守护进程ID列表
- **命名选择**: 可选择使用实例名或UUID作为服务器名称
- **详细调试**: 提供详细的调试信息帮助排查问题

## 安装说明

### 1. 编译插件

```bash
# 确保已安装Maven
mvn clean package
```

编译完成后，在 `target/` 目录下会生成 `mcsmanager-bungee-plugin-1.0.0.jar` 文件。

### 2. 安装插件

将生成的JAR文件复制到BungeeCord服务器的 `plugins/` 目录下，然后重启BungeeCord。

### 3. 配置插件

首次启动后，插件会在 `plugins/MCSManagerConnector/` 目录下生成 `config.yml` 配置文件。

## 配置说明

编辑 `plugins/MCSManagerConnector/config.yml` 文件：

```yaml
# MCSManager API配置
mcsmanager:
# MCSManager面板地址
api-url: " http://localhost:23333"
# API密钥（在MCSManager面板设置中获取）
api-key: "your-api-key-here"
# 守护进程ID列表（支持多个，会依次尝试）
daemon-ids:
- "local"
- "default"
- "main"
- ""
# 同步间隔（秒）
sync-interval: 30
# 是否启用自动同步
auto-sync: true
# 代理服务器类型过滤（忽略这些类型的实例）
ignore-types:
- "bungeecord"
- "velocity"
- "waterfall"
# 服务器名称前缀
server-prefix: "mcs_"
# 服务器名称类型：name（实例名）或 uuid（实例UUID）
server-name-type: "name"
# 连接超时时间（毫秒）
connection-timeout: 5000
# 调试模式
debug: false
```

### 配置项详细说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `api-url` | String | ` http://localhost:23333` | MCSManager面板地址 |
| `api-key` | String | `your-api-key-here` | MCSManager API密钥 |
| `daemon-ids` | List | `["local", "default", "main", ""]` | 守护进程ID列表，支持多个ID依次尝试 |
| `sync-interval` | Integer | `30` | 自动同步间隔（秒） |
| `auto-sync` | Boolean | `true` | 是否启用自动同步 |
| `ignore-types` | List | `["bungeecord", "velocity", "waterfall"]` | 要忽略的服务器类型列表 |
| `server-prefix` | String | `"mcs_"` | 服务器名称前缀 |
| `server-name-type` | String | `"name"` | 服务器名称类型：`name`（实例名）或 `uuid`（实例UUID） |
| `connection-timeout` | Integer | `5000` | API连接超时时间（毫秒） |
| `debug` | Boolean | `false` | 是否启用调试模式 |

### 守护进程ID配置

在多守护进程环境中，可以配置多个守护进程ID：

```yaml
daemon-ids:
- "3230109da4aa4955811cb2b1fef41799" # 具体的守护进程ID
- "local" # 本地守护进程
- "default" # 默认守护进程
- "" # 空字符串表示不指定守护进程ID
```

插件会按顺序尝试每个守护进程ID，直到成功获取实例列表。

### 服务器命名配置

可以选择两种命名方式：

**使用实例名（推荐）**：
```yaml
server-name-type: "name"
```
结果：`mcs_Lobby-1`, `mcs_SUR`, `mcs_Creative`

**使用UUID**：
```yaml
server-name-type: "uuid"
```
结果：`mcs_f0ee63afaab34aa3bbdbfbf5c0003023`, `mcs_bc8d86ea54d24c55966451bd4762827d`

### 获取API密钥

1. 登录MCSManager管理面板
2. 进入"系统设置" → "API设置"
3. 生成新的API密钥
4. 将密钥填入配置文件的 `api-key` 字段

## 命令说明

插件提供以下管理命令（需要 `mcsmanager.admin` 权限）：

- `/mcsmanager reload` - 重新加载配置文件
- `/mcsmanager status` - 显示插件状态信息
- `/mcsmanager sync` - 手动同步服务器列表
- `/mcsmanager list` - 显示当前管理的服务器列表

## 工作原理

1. **实例获取**: 插件通过MCSManager API定期获取所有实例信息
2. **智能过滤**:
- 忽略代理服务器类型的实例
- 只处理运行中的服务器
- 跳过配置中指定的忽略类型
3. **动态管理**:
- 为新实例创建服务器配置并添加到BungeeCord
- 移除已删除的实例配置
- 更新地址发生变化的实例
4. **无重启操作**: 所有操作都在运行时进行，无需重启代理服务器

## 服务器命名规则

插件会为每个MCSManager实例创建一个对应的服务器配置，命名规则为：

```
{server-prefix}{instance-identifier}
```

根据 `server-name-type` 配置：

**使用实例名**（默认）：
- `{server-prefix}{instance-name}`
- 例如：`mcs_Lobby-1`, `mcs_SUR`, `mcs_Creative`

**使用UUID**：
- `{server-prefix}{instance-uuid}`
- 例如：`mcs_f0ee63afaab34aa3bbdbfbf5c0003023`

## 实例过滤规则

插件会自动过滤以下类型的实例：

1. **代理服务器类型**：
- BungeeCord
- Velocity
- Waterfall
- Travertine

2. **未运行的服务器**：
- 只同步状态为"运行中"（status: 3）的实例

3. **配置中指定的忽略类型**：
- 根据 `ignore-types` 配置列表过滤

4. **缺少必要信息的实例**：
- 缺少IP地址或端口信息的实例会被跳过

## 日志输出

插件会输出详细的日志信息，包括：
- 添加/移除服务器的操作
- API请求状态
- 错误信息和警告
- 调试信息（启用调试模式时）

## 故障排除

### 常见问题

1. **API连接失败**
- 检查 `api-url` 是否正确
- 确认MCSManager服务正在运行
- 检查防火墙设置
- 验证API密钥是否有效

2. **守护进程ID错误**
- 检查 `daemon-ids` 配置是否正确
- 启用调试模式查看尝试的守护进程ID列表
- 确认守护进程在MCSManager中存在

3. **服务器未显示**
- 确认服务器状态为"运行中"（status: 3）
- 检查服务器类型是否被过滤
- 确认服务器有有效的IP和端口信息
- 启用调试模式查看详细信息

4. **实例名解析为null**
- 检查MCSManager实例是否配置了昵称
- 确认实例的 `config.nickname` 字段有值
- 启用调试模式查看API响应内容

5. **端口信息错误**
- 检查实例的 `pingConfig.port` 或 `basePort` 配置
- 确认端口没有被其他服务占用
- 验证防火墙端口设置

### 启用调试模式

在配置文件中设置 `debug: true` 可以查看详细的调试信息：

```yaml
debug: true
```

调试信息包括：
- API请求URL和响应状态
- 尝试的守护进程ID列表
- 实例数据解析过程
- 过滤和同步操作的详细信息

### 调试步骤

1. **启用调试模式**：
```yaml
debug: true
```

2. **手动同步**：
```
/mcsmanager sync
```

3. **查看日志输出**：
- 检查API请求是否成功
- 确认守护进程ID是否正确
- 验证实例数据是否正确解析

4. **检查配置**：
- 验证API密钥和地址
- 确认守护进程ID列表
- 检查过滤规则配置

## API兼容性

### MCSManager API版本
- **支持版本**: MCSManager 9.x+
- **API端点**: `/api/service/remote_service_instances`
- **认证方式**: API密钥URL参数
- **响应格式**: JSON

### 状态码说明
- `status: 3` - 运行中 ✅
- `status: 0` - 已停止
- `status: 1` - 启动中
- `status: 2` - 停止中

## 技术要求

- **Java**: 8 或更高版本
- **BungeeCord**: 1.8.x-1.21.x (兼容所有版本)
- **MCSManager**: 9.x 或更高版本
- **网络**: 能够访问MCSManager API端点
- **权限**: BungeeCord管理员权限（用于插件管理）

## 版本历史

### v1.1.0 (当前版本)
- ✨ 新增守护进程ID配置支持
- ✨ 新增服务器命名类型选择（实例名/UUID）
- 优化实例数据解析逻辑
- 修复状态判断和端口解析
- 增强调试信息输出

### v1.0.0
- 初始版本发布
- 基本的自动同步功能
- 代理服务器过滤
- ️ 管理命令支持

## 开发信息

- **作者**: TheMuo
- **版本**: 1.1.0
- **源码**: [GitHub Repository]

## 支持

如果遇到问题或需要帮助：

### 自助排查
1. **查看控制台日志** - 检查错误信息和警告
2. **启用调试模式** - 获取详细的调试信息
3. **检查API连接** - 验证MCSManager API可访问性
4. **验证配置** - 确认所有配置项正确

### 常用调试命令
```bash
# 手动同步并查看详细日志
/mcsmanager sync

# 查看插件状态
/mcsmanager status

# 重新加载配置
/mcsmanager reload

# 查看管理的服务器列表
/mcsmanager list
```

### 获取帮助
- 查看MCSManager官方文档
- 提交Issue到GitHub仓库
- QQ 2523203097