azad_white_api

一个轻量级 Paper（Minecraft）核心插件，提供一个带鉴权的 HTTP API，用于管理服务器白名单。

• 适用于 Paper 1.21.11+（Java 21）
• 零外部依赖，HTTP 服务基于 JDK 内置 com.sun.net.httpserver.HttpServer
• 白名单操作通过服务器原生 /whitelist 命令完成，自动处理 UUID 解析与持久化

功能

接口	方法	说明
/api/whitelist/add	POST	添加用户名到白名单
/api/whitelist/remove	POST	从白名单移除用户名
/api/whitelist/check	GET	查询用户名是否在白名单

返回结果包含 success / already_in_whitelist / not_in_whitelist / failed 等状态。

构建

环境要求：JDK 21+、Maven 3.9+

mvn package

产物：target/azad_white_api.jar

安装

将 azad_white_api.jar 放入 Paper 服务器的 plugins/ 目录，重启服务器。首次启动会在 plugins/azad_white_api/config.yml 自动生成配置与 API Key。

配置

plugins/azad_white_api/config.yml

server:
  port: 8790
  host: 0.0.0.0
auth:
  api-key: ""   # 留空则首次启动自动生成

游戏内命令

命令	说明	权限
/azadwhiteapi reload	重载配置并重启 API 服务	azad_white_api.admin（默认 OP）
/azadwhiteapi newkey	重新生成 API Key	azad_white_api.admin
/azadwhiteapi	查看当前 API Key	azad_white_api.admin

别名：/awa

API 接口说明

基础信息

• Base URL：http://<服务器IP>:8790（端口可在 config.yml 的 server.port 修改）
• 鉴权方式：请求头携带 API Key，二选一
  • Authorization: Bearer <api-key>
  • X-API-Key: <api-key>
• Content-Type：响应统一为 application/json; charset=utf-8

1. 添加用户到白名单

POST /api/whitelist/add?name=<用户名>

result	说明	HTTP 状态码
success	添加成功	200
already_in_whitelist	该用户已在白名单	200
failed	添加失败（如玩家名无效或 UUID 解析失败）	500

响应示例：

{"result":"success","name":"Steve"}

2. 从白名单移除用户

POST /api/whitelist/remove?name=<用户名>

result	说明	HTTP 状态码
success	移除成功	200
not_in_whitelist	该用户不在白名单	200
failed	移除失败	500

响应示例：

{"result":"not_in_whitelist","name":"Steve"}

3. 查询用户是否在白名单

GET /api/whitelist/check?name=<用户名>

result	说明	HTTP 状态码
in_whitelist	在白名单中	200
not_in_whitelist	不在白名单	200

响应示例：

{"result":"in_whitelist","name":"Steve"}

错误响应

场景	HTTP 状态码	响应
未携带或 API Key 错误	401	{"result":"unauthorized","message":"invalid or missing api key"}
缺少 name 参数	400	{"result":"bad_request","message":"missing 'name' parameter"}
请求方法错误	405	{"result":"method_not_allowed","message":"use POST"}
未知路径	404	{"result":"not_found","message":"unknown endpoint"}

curl 测试示例

# 添加
curl -X POST "http://127.0.0.1:8790/api/whitelist/add?name=Steve" -H "Authorization: Bearer <api-key>"

# 移除
curl -X POST "http://127.0.0.1:8790/api/whitelist/remove?name=Steve" -H "Authorization: Bearer <api-key>"

# 查询
curl "http://127.0.0.1:8790/api/whitelist/check?name=Steve" -H "Authorization: Bearer <api-key>"

注意事项

• name 参数通过 URL query 传递，需 URL 编码
• 添加/移除操作在服务器主线程执行，依赖原生 /whitelist 命令完成 UUID 解析与持久化
• 在线模式服务器添加未注册玩家时可能因 Mojang API 查询而短暂阻塞
• 服务器需在 server.properties 中启用 white-list=true 才能让白名单实际生效（API 操作本身不依赖此开关）

项目结构

azad_white_api
├── pom.xml
├── src/main/java/azad_white_api
│   ├── AzadWhiteApi.java      # 插件主类，配置加载与命令
│   ├── ApiServer.java         # HTTP API 服务器与路由
│   └── WhitelistManager.java  # 白名单操作封装（主线程同步）
└── src/main/resources
    ├── plugin.yml
    └── config.yml