POST https://uniteban.mcwaf.cn/api.php
此接口用于检查玩家是否在联合封禁云端黑名单中，可在玩家加入服务器前进行安全检查。
请求参数
| 参数名 |
类型 |
是否必须 |
描述 |
| xuid |
String |
可选 |
玩家的XUID |
| clientid |
String |
可选 |
客户端ID |
| ip |
String |
可选 |
玩家IP地址 |
提示： 至少需要提供一项参数才能进行有效的封禁检查。
响应示例
玩家已被封禁
{
"exists": true,
"message": "Record exists",
"searched_fields": [
"xuid"
],
"search_values": {
"xuid": "2535441386894771"
},
"query_counts": [
{
"record_id": "574",
"query_count": 31
}
],
"reason": "偷窃玩家物品而且拆家",
"statistics": {
"total_visits": "429897",
"total_blocks": "486"
}
}
玩家未被封禁
{
"exists": false,
"message": "Record not found",
"searched_fields": [
"xuid"
],
"search_values": {
"xuid": "2535461883808331"
},
"query_counts": [
],
"reason": null,
"statistics": {
"total_visits": "429836",
"total_blocks": "485"
}
}
POST https://uniteban.mcwaf.cn/innerapi.php
此接口用于注册服务器和将玩家上传到云黑数据库中。
请求参数
| 参数名 |
类型 |
是否必须 |
描述 |
| mac |
String |
必填 |
上传服务器的MAC地址 |
| token |
String |
必填 |
32位随机字符串 |
| name |
String |
必填 |
玩家的Name |
| xuid |
String |
可选 |
玩家的xUID |
| uuid |
String |
可选 |
玩家的uUID |
| clientid |
String |
可选 |
玩家的客户端/设备ID |
| ip |
String |
可选 |
玩家IP地址 |
| reason |
String |
必填 |
封禁原因 |
提示： XUID，UUID，ClientID，IP至少有一项。
响应示例
服务器未获取上传权限
{
"status": "error",
"message": "Permission denied. New record created."
}
缺少参数
{
"status": "error",
"message": "Insufficient parameters"
}
缺少参数
{
"status": "error",
"message": "Insufficient parameters"
}
玩家成功新添加到云黑
{
"status": "success",
"action": "created_new_row"
}
上传的玩家发生数据合并/更新
{
"status": "success",
"action": "merged_rows",
"merged_count": 1,
"earliest_created_at": "2025-07-01 20:37:17",
"total_query_count": 0,
"new_data": {
"name": [
"PHEyeji"
],
"xuid": [
],
"uuid": [
],
"clientid": [
],
"ip": [
"1.1.1.1"
]
}
}
最佳实践与注意事项
重要安全提示
1. 请妥善保管你的token，不要将其公开或包含在客户端代码中
2. 建议在服务器端进行封禁检查，避免客户端被绕过
3. 对玩家IP等敏感信息进行适当脱敏处理
推荐集成方式
在玩家尝试加入服务器时，按照以下流程进行安全检查：
- 服务器每次启动时往innerapi.php发送mac和token用于注册，如果没有token则生成32位随机字符串作为token并长期保存不变
- 在玩家预加入阶段(onPreJoin)收集玩家信息
- 调用api.php接口检查玩家是否在封禁名单中
- 如果exists为true，立即踢出玩家并记录日志
- 对于确认的恶意玩家，调用innerapi.php上传封禁信息
处理私有IP和本地网络
为了避免误封本地网络玩家，建议在处理IP地址时排除以下情况：
- IPv4私有地址范围：10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 127.0.0.0/8
- IPv6本地地址：fc00::/7, fe80::/10, ::1/128