跳到主要内容

桥接事件

桥接事件用于监听服务器连接状态变化，包括服务器上线、离线、连接异常等情况。这些事件对于服务器管理和状态监控非常重要。

事件列表​

bridge_server_online​

功能描述: 当 Minecraft 服务器成功连接到 EasyBot 时触发。

语法:

bus.on("bridge_server_online", function(server, ip) {
    // 处理服务器上线逻辑
});

参数:

  • server (Bridge): 已上线的桥接服务器实例，可用于与服务器交互
  • ip (string): 服务器的 IP 地址

返回值: 无

使用示例:

bus.on("bridge_server_online", function(server, ip) {
    logger.info("服务器已上线: {0}, IP: {1}", server.Session, ip);
    
    // 向服务器发送欢迎消息
    server.SendMessageToAllPlayer("EasyBot 已连接到服务器！");
    
    // 获取服务器信息
    server.GetServerInfo().then(function(info) {
        logger.info("服务器名称: {0}, 版本: {1}", info.ServerName, info.ServerVersion);
    });
});

相关 API:

bridge_server_offline​

功能描述: 当 Minecraft 服务器与 EasyBot 断开连接时触发。

语法:

bus.on("bridge_server_offline", function(server, closeCode, reason, ip) {
    // 处理服务器离线逻辑
});

参数:

  • server (Bridge): 已离线的桥接服务器实例
  • closeCode (number): WebSocket 关闭状态码
  • reason (string): 连接关闭原因描述
  • ip (string): 服务器的 IP 地址

返回值: 无

使用示例:

bus.on("bridge_server_offline", function(server, closeCode, reason, ip) {
    logger.warning("服务器已离线: {0}, 原因: {1} (代码: {2})", server.Session, reason, closeCode);
    
    // 检查是否是正常关闭
    if (closeCode === 1000) {
        logger.info("服务器正常关闭");
    } else {
        logger.error("服务器异常断开，代码: {0}", closeCode);
    }
});

常见关闭代码:

  • 1000: 正常关闭
  • 1001: 端点离开
  • 1006: 连接异常关闭
  • 1011: 服务器错误

bridge_server_connected​

功能描述: 当有客户端尝试连接到桥接服务器时触发（连接建立但未认证）。

语法:

bus.on("bridge_server_connected", function(ip) {
    // 处理连接建立逻辑
});

参数:

  • ip (string): 客户端的 IP 地址

返回值: 无

使用示例:

bus.on("bridge_server_connected", function(ip) {
    logger.info("新的连接来自 IP: {0}", ip);
    
    // 可以在这里记录连接统计
    // 注意：此时连接还未认证，可能是无效连接
});

bridge_server_disconnected​

功能描述: 当客户端从桥接服务器断开连接时触发。

语法:

bus.on("bridge_server_disconnected", function(server, ip, closeCode, reason) {
    // 处理连接断开逻辑
});

参数:

  • server (Bridge): 关联的桥接服务器实例
  • ip (string): 客户端的 IP 地址
  • closeCode (number): WebSocket 关闭状态码
  • reason (string): 连接断开原因描述

返回值: 无

使用示例:

bus.on("bridge_server_disconnected", function(server, ip, closeCode, reason) {
    logger.info("连接断开 - IP: {0}, 原因: {1}", ip, reason);
    
    // 清理与该连接相关的资源
    if (server) {
        logger.info("服务器 {0} 连接已断开", server.Session);
    }
});

bridge_server_invalid_connection​

功能描述: 当检测到无效连接时触发，用于安全监控和问题诊断。

语法:

bus.on("bridge_server_invalid_connection", function(server, context, type, ip) {
    // 处理无效连接逻辑
});

参数:

  • server (Bridge): 关联的桥接服务器实例
  • context (WebSocketContext): 发生异常的 WebSocket 连接对象
  • type (string): 无效连接类型标识
  • ip (string): 客户端的 IP 地址

无效连接类型:

  • INVALID_TOKEN: 错误的 TOKEN
  • INVALID_PACKET: 数据包格式错误
  • NOAUTH: 未通过认证
  • AUTH_TIMEOUT: 认证超时
  • HEARTBEAT_TIMEOUT: 心跳超时

使用示例:

bus.on("bridge_server_invalid_connection", function(server, context, type, ip) {
    logger.warning("检测到无效连接 - IP: {0}, 类型: {1}", ip, type);
    
    switch (type) {
        case "INVALID_TOKEN":
            logger.error("IP {0} 使用了无效的 TOKEN", ip);
            break;
        case "AUTH_TIMEOUT":
            logger.warning("IP {0} 认证超时", ip);
            break;
        case "HEARTBEAT_TIMEOUT":
            logger.warning("IP {0} 心跳超时", ip);
            break;
        default:
            logger.error("IP {0} 发生未知连接错误: {1}", ip, type);
    }
});

bridge_server_raw_packet​

功能描述: 当收到原始数据包时触发，用于调试和高级数据包处理。

语法:

bus.on("bridge_server_raw_packet", function(server, data, context, ip, authed) {
    // 处理原始数据包逻辑
});

参数:

  • server (Bridge): 关联的桥接服务器实例
  • data (string): 接收到的原始数据字符串
  • context (WebSocketContext): 来源 WebSocket 连接对象
  • ip (string): 客户端的 IP 地址
  • authed (boolean): 标识连接是否已通过认证

返回值: 无

使用示例:

bus.on("bridge_server_raw_packet", function(server, data, context, ip, authed) {
    // 仅在调试模式下记录原始数据包
    if (DEBUG_MODE) {
        logger.info("收到原始数据包 - IP: {0}, 已认证: {1}", ip, authed);
        logger.info("数据内容: {0}", data.substring(0, 100)); // 只显示前100个字符
    }
    
    // 可以在这里进行自定义数据包分析
    if (!authed && data.includes("malicious")) {
        logger.warning("检测到可疑数据包来自 IP: {0}", ip);
    }
});

实用示例​

1. 服务器状态监控​

// 服务器状态监控系统
let serverStatus = {};

bus.on("bridge_server_online", function(server, ip) {
    const serverKey = server.Session;
    serverStatus[serverKey] = {
        online: true,
        ip: ip,
        connectTime: new Date(),
        lastSeen: new Date()
    };
    
    logger.info("服务器 {0} 上线，IP: {1}", serverKey, ip);
    
    // 发送上线通知
    server.SendMessageToAllPlayer("§a[系统] EasyBot 连接成功！");
});

bus.on("bridge_server_offline", function(server, closeCode, reason, ip) {
    const serverKey = server.Session;
    if (serverStatus[serverKey]) {
        serverStatus[serverKey].online = false;
        serverStatus[serverKey].disconnectTime = new Date();
        serverStatus[serverKey].disconnectReason = reason;
    }
    
    logger.warning("服务器 {0} 离线，原因: {1}", serverKey, reason);
});

2. 安全监控系统​

// 安全监控：记录可疑连接
let suspiciousIPs = {};

bus.on("bridge_server_invalid_connection", function(server, context, type, ip) {
    if (!suspiciousIPs[ip]) {
        suspiciousIPs[ip] = {
            count: 0,
            types: [],
            firstSeen: new Date()
        };
    }
    
    suspiciousIPs[ip].count++;
    suspiciousIPs[ip].types.push(type);
    suspiciousIPs[ip].lastSeen = new Date();
    
    logger.warning("可疑连接 #{0} 来自 IP: {1}, 类型: {2}", 
        suspiciousIPs[ip].count, ip, type);
    
    // 如果同一IP多次无效连接，发出警告
    if (suspiciousIPs[ip].count >= 5) {
        logger.error("IP {0} 已发生 {1} 次无效连接，建议封禁", 
            ip, suspiciousIPs[ip].count);
    }
});

3. 自动重连通知​

// 自动重连检测和通知
let reconnectTracking = {};

bus.on("bridge_server_online", function(server, ip) {
    const serverKey = server.Session;
    
    if (reconnectTracking[serverKey]) {
        const downTime = new Date() - reconnectTracking[serverKey].disconnectTime;
        const minutes = Math.floor(downTime / 60000);
        
        logger.info("服务器 {0} 重新连接，离线时长: {1} 分钟", serverKey, minutes);
        
        // 通知管理员
        server.SendMessageToAllPlayer(`§e[系统] 服务器重新连接，离线 ${minutes} 分钟`);
        
        delete reconnectTracking[serverKey];
    }
});

bus.on("bridge_server_offline", function(server, closeCode, reason, ip) {
    const serverKey = server.Session;
    reconnectTracking[serverKey] = {
        disconnectTime: new Date(),
        reason: reason,
        closeCode: closeCode
    };
});

4. 服务器信息收集​

// 自动收集服务器信息
bus.on("bridge_server_online", function(server, ip) {
    // 获取服务器详细信息
    server.GetServerInfo().then(function(info) {
        logger.info("服务器信息收集完成:");
        logger.info("- 名称: {0}", info.ServerName);
        logger.info("- 版本: {0}", info.ServerVersion);
        logger.info("- PAPI支持: {0}", info.IsPapiSupported);
        logger.info("- 正版模式: {0}", info.IsOnlineMode);
        
        // 根据服务器特性调整功能
        if (info.IsPapiSupported) {
            logger.info("检测到 PAPI 支持，启用变量功能");
        }
        
        if (info.HasGeyser) {
            logger.info("检测到 Geyser，支持基岩版玩家");
        }
    }).catch(function(error) {
        logger.error("获取服务器信息失败: {0}", error);
    });
});

相关 API 参考​

注意事项​

  1. 事件顺序: bridge_server_connected 总是在 bridge_server_online 之前触发
  2. 错误处理: 在事件处理函数中使用 try-catch 避免异常影响其他监听器
  3. 性能考虑: bridge_server_raw_packet 是高频事件，避免在其中执行耗时操作
  4. 安全性: 利用 bridge_server_invalid_connection 事件进行安全监控
  5. 资源清理: 在服务器离线事件中及时清理相关资源
Copyright © 2024-2025 易栈