WebConnector
通过受控的 HTTP API、公共 Java API 以及签名 Webhook,将你的 Minecraft 服务器连接到网站、商店、Discord 机器人和其他插件。
精确定义集成可以执行的操作。WebConnector 会验证传入的 JSON,检查客户端权限,跟踪每个操作,并在服务器重启后保留幂等性密钥(idempotency keys)。
你可以构建什么
- 一个使用稳定订单 ID 授予配置好的等级或通行证的商店。
- 一个接收玩家加入和首次加入事件的 Discord 机器人或网站。
- 具有对单个服务器操作范围访问权限的 NodeDashboard 集成。
- 一个注册私有操作或通过 HTTP 显式暴露它们的 Java 插件。
- 使用现有 HTTP 附加组件的 Skript 集成。
功能特性
- 带有过期时间、操作范围和权限命名的 API 密钥。
- IP/CIDR 白名单、请求大小限制、超时和速率限制。
- 针对玩家名称、UUID、字符串、整数、布尔值、枚举和正则表达式的类型化验证。
- 异步操作,支持请求 ID、状态轮询和持久的重试保护。
- 带有过滤器、每路由目标地址和指数退避重试的签名 Webhook 请求。
- 可选的文件删除功能,仅限白名单中的常规文件,并提供明确的高风险操作控制。
- 动作、密钥和事件路由的热重载。
兼容性
服务端 JAR 适用于 Paper 1.20.1–26.2,并包含 实验性的 26.3 支持。Minecraft 1.20.1–1.20.4 请使用 Java 17,1.20.5–1.21.11 请使用 Java 21,26.1+ 请使用 Java 25。无需安装客户端组件。不支持 Folia 和代理服务器。
WebConnector 使用通用的 Bukkit API,不依赖 NMS(Net Minecraft)。请参阅 兼容性矩阵 以了解验证范围。Skript 和 HTTP 附加组件是可选的,并具有各自的版本要求。
入门指南
- 将主要的 WebConnector JAR 安装到
plugins/ 目录中并启动服务器。
- 打开生成的
plugins/WebConnector/config.yml。会自动生成一个私有 API 密钥。
- 定义你的动作,并为每个集成提供作用域受限的密钥。
- 在更改动作、密钥或事件路由后,使用
/webconnector reload 命令进行重载。
默认 API 绑定到 localhost,并且仅暴露一个无害的 ping 操作。对于远程集成,你的托管计划必须提供一个可访问的额外端口或反向代理。当流量跨越网络时,请在代理端使用 HTTPS。
重试奖励或订单时使用相同的 Idempotency-Key。已完成或中断的操作不会为该密钥自动重新执行。外部命令不具备事务性:在超时或失败后,在创建新密钥之前,请检查操作和服务器的状态。
WebConnector 提供集成网关;它不包含仪表盘或支付处理器。文件删除和关闭服务器的功能默认处于禁用状态。
文档 · HTTP API · Java API · Русская документация · 问题反馈
从 1.x 升级? 在替换插件之前,请先阅读 迁移指南。
WebConnector
Connect your Minecraft server to websites, shops, Discord bots and other plugins through a controlled HTTP API, a public Java API and signed webhooks.
Define exactly which actions an integration may run. WebConnector validates incoming JSON, checks the client's permissions, tracks each operation, and remembers idempotency keys across server restarts.
What you can build
- A store that grants a configured rank or pass using a stable order ID.
- A Discord bot or website that receives player join and first-join events.
- A NodeDashboard integration with scoped access to individual server actions.
- A Java plugin that registers private actions or explicitly exposes them over HTTP.
- Skript integrations using an existing HTTP addon.
Features
- Named API keys with expiry, action scopes and permissions.
- IP/CIDR allowlists, request size limits, timeouts and rate limits.
- Typed validation for player names, UUIDs, strings, integers, booleans, enums and regex rules.
- Asynchronous operations with request IDs, status polling and durable retry protection.
- Signed webhook requests with filters, per-route destinations and exponential retries.
- Optional file deletion restricted to allowlisted regular files, and explicit dangerous-action controls.
- Live reload of actions, keys and event routes.
Compatibility
One server-side JAR targets Paper 1.20.1–26.2, with experimental 26.3 support. Use Java 17 for Minecraft 1.20.1–1.20.4, Java 21 for 1.20.5–1.21.11, and Java 25 for 26.1+. No client installation is required. Folia and proxy servers are not supported.
WebConnector uses the common Bukkit API without NMS. See the compatibility matrix for verification scope. Skript and HTTP addons are optional and have their own version requirements.
Getting started
- Install the main WebConnector JAR in
plugins/ and start the server.
- Open the generated
plugins/WebConnector/config.yml. A private API secret is generated automatically.
- Define your actions and give each integration a scoped key.
- Use
/webconnector reload after changing actions, keys or event routes.
The default API binds to localhost and exposes only a harmless ping action. For remote integrations, your hosting plan must provide a reachable additional port or reverse proxy. Use HTTPS at the proxy when traffic crosses a network.
Use the same Idempotency-Key when retrying a reward or order. Completed or interrupted operations are not automatically executed again for that key. External commands are not transactional: after a timeout or failure, inspect the operation and server state before creating a new key.
WebConnector provides the integration gateway; it does not include a dashboard or payment processor. File deletion and shutdown are disabled by default.
Documentation · HTTP API · Java API · Русская документация · Issues
Upgrading from 1.x? Read the migration guide before replacing the plugin.
评论 0
登录后参与评分
还没有评论,来抢沙发吧