联合封禁API文档 - uniteban.xyz:19132

封禁状态检查接口

POST

POST http://uniteban.xyz:19132/api.php

此接口用于检查玩家是否在联合封禁云端黑名单中，可在玩家加入服务器前进行安全检查。

请求参数

参数名	类型	是否必须	描述
xuid	String	可选	玩家的XUID
uuid	String	可选	玩家的UUID
clientid	String	可选	客户端ID
ip	String	可选	玩家IP地址

提示： 至少需要提供一项参数才能进行有效的封禁检查。

请求示例

以下示例展示了如何在不同编程语言中调用此接口：

                    JavaScript (Node.js)
/**
 * 检查玩家是否被联合封禁（通过 API 请求）
 *
 * @param {string|null} realname   - 玩家名称
 * @param {string|null} xuid       - XUID
 * @param {string|null} uuid       - UUID
 * @param {string|null} clientid   - 客户端ID
 * @param {string|null} ip         - IP地址
 */
function checkcloudban(realname, xuid, uuid, clientid, ip) {
    // 构建请求数据对象，仅包含非空字段
    const postData = {
        ...(realname != null && { name: realname }),
        ...(xuid != null && { xuid }),
        ...(uuid != null && { uuid }),
        ...(clientid != null && { clientid }),
        ...(ip != null && { ip })
    };

    // 转换为 JSON 字符串用于网络请求
    const jsonData = JSON.stringify(postData);

    // 设置请求目标 URL
    const url = "http://uniteban.xyz:19132/api.php";

    // 发起 HTTP POST 请求
    network.httpPost(
        url,
        jsonData,
        "application/json", // 内容类型
        (status, result) => {
            try {
                // 判断 HTTP 状态码是否为 200（成功）
                if (status === 200) {
                    const response = JSON.parse(result);

                    // 如果存在封禁记录
                    if (response.exists === true) {
                        logger.log(`玩家 ${realname} 联合封禁 - 检查不通过`);
                        
                        // 将玩家踢出服务器并提示原因
                        mc.runcmd(`kick "${realname}" 联合封禁 - 检查不通过`);
                    } else {
                        logger.log(`玩家 ${realname} 联合封禁检查通过`);
                    }
                } else {
                    // 可选：记录请求失败的状态码
                    // logger.error(`请求失败，状态码: ${status}`);
                }
            } catch (e) {
                // 可选：记录解析失败的错误信息
                // logger.error(`响应解析失败: ${e.message}`);
            }
        }
    );
}
                

                    Python
import json
import logging
import requests

# 设置日志记录器
logger = logging.getLogger(__name__)

def check_cloudban(realname=None, xuid=None, uuid=None, clientid=None, ip=None):
    """
    检查玩家是否被联合封禁（通过 API 请求）

    参数:
        realname (str | None): 玩家名称
        xuid (str | None): XUID
        uuid (str | None): UUID
        clientid (str | None): 客户端ID
        ip (str | None): IP地址

    返回:
        None
    """

    # 构建请求数据，只包含非空字段
    post_data = {
        key: value for key, value in {
            "name": realname,
            "xuid": xuid,
            "uuid": uuid,
            "clientid": clientid,
            "ip": ip
        }.items() if value is not None
    }

    # API 地址
    url = "http://uniteban.xyz:19132/api.php"

    try:
        # 发起 HTTP POST 请求
        response = requests.post(
            url,
            data=json.dumps(post_data),
            headers={"Content-Type": "application/json"}
        )

        # 检查响应状态码是否为 200 OK
        if response.status_code == 200:
            try:
                # 解析返回 JSON 数据
                result = response.json()

                # 判断是否存在封禁记录
                if result.get("exists") is True:
                    logger.info(f"玩家 {realname} 联合封禁 - 检查不通过")

                    # 这里可以执行踢出玩家的操作（取决于你的服务器控制方式）
                    print(f'kick "{realname}" 联合封禁 - 检查不通过')


                else:
                    logger.info(f"玩家 {realname} 联合封禁检查通过")
                    pass

            except json.JSONDecodeError as e:
                logger.error(f"响应解析失败: {e}")
        else:
            logger.error(f"请求失败，状态码: {response.status_code}")

    except requests.RequestException as e:
        logger.error(f"网络请求异常: {e}")
                

                    PHP
 'PlayerToCheck',
    'xuid' => '1234567890',
    'ip' => '192.168.1.100'
);

$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data),
    ),
);

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

if ($response['exists']) {
    echo "玩家已被封禁";
} else {
    echo "玩家未被封禁";
}
?>
                

                    Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class BanCheck {
    public static void main(String[] args) throws Exception {
        String url = "http://uniteban.xyz:19132/api.php";
        String json = String.format(
            "{\"name\":\"PlayerToCheck\"," +
            "\"xuid\":\"1234567890\"," +
            "\"ip\":\"192.168.1.100\"}"
        );
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        
        HttpResponse response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        // 解析JSON响应
        String responseBody = response.body();
        // 使用JSON库解析responseBody
        if (responseBody.contains("\"exists\":true")) {
            System.out.println("玩家已被封禁");
        } else {
            System.out.println("玩家未被封禁");
        }
    }
}
                

                    C#
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var url = "http://uniteban.xyz:19132/api.php";
        var data = new {
            name = "PlayerToCheck",
            xuid = "1234567890",
            ip = "192.168.1.100"
        };
        
        var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        using (var client = new HttpClient()) {
            var response = await client.PostAsync(url, content);
            var result = await response.Content.ReadAsStringAsync();
            var responseObj = Newtonsoft.Json.JsonConvert.DeserializeObject(result);
            
            if (responseObj.exists) {
                Console.WriteLine("玩家已被封禁");
            } else {
                Console.WriteLine("玩家未被封禁");
            }
        }
    }
}
                

响应示例

        玩家已被封禁
        {
            "exists": true,
            "message": "Record exists",
            "searched_fields": [
                "uuid"
            ],
            "search_values": {
                "uuid": "43d2b0b4-9474-3d29-ad91-b3dec8f4cfed"
            },
            "statistics": {
                "total_visits": "9516",
                "total_blocks": "47"
            }
        }
    

                    玩家未被封禁
{
    "exists": false,
    "message": "Record not found",
    "searched_fields": [
        "xuid"
    ],
    "search_values": {
        "xuid": "test"
    },
    "statistics": {
        "total_visits": "9504",
        "total_blocks": "46"
    }
}
                

最佳实践与注意事项

重要安全提示

1. 请妥善保管你的token，不要将其公开或包含在客户端代码中

2. 建议在服务器端进行封禁检查，避免客户端被绕过

3. 对玩家IP等敏感信息进行适当脱敏处理

处理私有IP和本地网络

为了避免误封本地网络玩家，建议在处理IP地址时排除以下情况：