2. 封禁管理模块

2.1 申请添加封禁

添加新的封禁记录（支持在线/离线两种模式）。

接口: POST /bans/add

请求参数:

JSON
{
    "token": "aBcD1234EfGh5678IjKlMnOpQrSt",
    "player_id": "player123",
    "ip": "192.168.1.1",
    "ipv6": "2001:db8::1",
    "online": true,
    "mcuuid": "550e8400-e29b-41d4-a716-446655440000"
}

Parameter	Type	Required	Description
token	string	Yes	认证 Token（需具备上传权限）
player_id	string	Conditional	玩家标识符（与 ip 至少提供一个）
ip	string	Conditional	IPv4 地址（与 player_id 至少提供一个）
ipv6	string	No	IPv6 地址
online	boolean	No	数据存储模式（true=online，默认false=offline）
mcuuid	string	No	Minecraft UUID（online 模式下可选）

请求示例:

cURL - Offline 模式:

Bash
curl -X POST https://api.ndpreforged.com/bans/add \
  -H "Content-Type: application/json" \
  -d '{
    "token": "aBcD1234EfGh5678IjKlMnOpQrSt",
    "player_id": "player123",
    "ip": "192.168.1.1",
    "online": false
  }'

cURL - Online 模式:

Bash
curl -X POST https://api.ndpreforged.com/bans/add \
  -H "Content-Type: application/json" \
  -d '{
    "token": "aBcD1234EfGh5678IjKlMnOpQrSt",
    "player_id": "player123",
    "ip": "192.168.1.1",
    "ipv6": "2001:db8::1",
    "online": true,
    "mcuuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Python:

Python
import requests

response = requests.post(
    "https://api.ndpreforged.com/bans/add",
    json={
        "token": "aBcD1234EfGh5678IjKlMnOpQrSt",
        "player_id": "player123",
        "ip": "192.168.1.1",
        "online": False
    }
)

响应示例:

Success (200 OK):

JSON
{
    "message": "Added"
}

Error Responses:

Status Code	Error Message	Description
400	`Missing token`	缺少认证 Token
400	`Invalid token format`	Token 格式无效
400	`Token not found`	Token 不存在
403	`No permission`	缺乏上传权限
400	`Missing player_id or ip`	缺少必要的标识参数
400	`Invalid IP format`	IPv4 格式无效
400	`Invalid IPv6 format`	IPv6 格式无效
400	`Invalid MCUUID format`	MCUUID 格式无效
400	`Already banned`	离线模式：记录已存在
400	`Already exists`	在线模式：记录已存在
500	`Server error`	服务器内部错误

2. 封禁管理模块

2.1 申请添加封禁

导航