Minecraft-Discord 账号绑定插件 (v2 — 完整规范)
一个现代、高性能的 Paper Minecraft 插件,用于将玩家的 Minecraft 账号安全地绑定到其 Discord 账号。该插件在同一个进程中运行使用 JDA 构建的嵌入式 Discord 机器人,并通过本地 SQLite 数据库持久化连接,无需任何外部设置!
?️ 系统工作原理
这是一个统一插件,在单个 Java 虚拟机 (JVM) 中运行两项独立的服务:
- Minecraft 端(Paper 命令执行器和异步任务线程)。
- Discord 端(通过你的机器人令牌登录的 JDA 客户端,运行其自身的异步监听线程)。
由于两端位于同一进程中,它们不需要套接字网络、API 或 Webhook——它们直接调用彼此的 Java 方法并共享相同的 SQLite 连接池!
核心信任与验证流程(代码桥接)
链接系统在无需手动输入敏感 ID 的情况下,安全地桥接两个独立的身份:
- 在 Discord 上发起: Discord 用户输入
/link。JDA 会自动从交互事件中提供其永久的数字 Discord snowflake ID(例如 23871987349123847)。
- 生成代码票据: 机器人生成一个随机、简洁、易读的 6 位代码(排除容易混淆的字母如
O, 0, I, 1),并保存一行数据:
discord_id = <snowflake_id>, code = <随机代码>, minecraft_uuid = NULL, verified = 0。此代码充当严格绑定到该 Discord 账户的一次性认领票据。
- 在 Minecraft 中兑换: 玩家加入 Minecraft 服务器并输入
/verify <CODE>。Paper 直接从服务器会话中提供其受信任的真实 Minecraft UUID (player.getUniqueId())。
- 绑定身份对: 插件在 SQLite 中搜索未验证且未过期的匹配项。如果找到,则填充
minecraft_uuid 并将 verified 标记为 1。
- 角色分配与日志记录: 数据库触发器异步提示 JDA 为 Discord 用户分配“已验证”角色,发送私信确认,并将验证记录写入管理员日志频道。
安全特性: 验证码是用户唯一需要输入的数据。 没有人会输入自己的 UUID 或 Discord ID,从而完全防止账号冒充或身份盗窃!
⚡ 在线模式与 Mojang 安全性
此链接系统的加密可信度直接取决于服务器的 online-mode 设置:
online-mode=true(推荐且安全)
服务器在玩家加入时直接与 Mojang 服务器验证每个连接。player.getUniqueId() 返回的 UUID 保证属于该 Minecraft 账号的真实持有者。链接具有加密安全性,无法被伪造。
online-mode=false(破解/离线服务器)
服务器不通过 Mojang 验证身份。UUID 是通过哈希用户名离线生成的:
UUID.nameUUIDFromBytes(("OfflinePlayer:" + username).getBytes())
任何人都可以使用任意用户名加入并劫持链接。此插件在离线服务器上也能完美运行,但你应该:
- 确保
config.yml 中的 assume-online-mode 设置为 false。
- 认识到链接的可信度仅取决于你的用户名(我们建议在破解服务器上添加 AuthMe 等身份验证插件!)。
- 查看 Discord 日志频道中的警告,这些警告会标记在离线模式下创建的链接。
? Geyser 与 Floodgate 基岩版兼容性
此插件原生支持通过 Geyser 和 Floodgate 代理加入你的 Java Edition 服务器的 Bedrock Edition 和 Pocket Edition 玩家。
无缝集成逻辑:
- 名称前缀自动检测: Geyser 通常用特殊符号(例如
*, ., 或 _)作为前缀来避免与 Java 账户冲突。插件在链接期间检测这些前缀约定并相应地进行标记。
- 确定性 UUID 匹配: Floodgate 为 Bedrock 玩家使用确定性的 UUID 格式(其中前 8 位为零,例如
00000000-0000-0000-...)。数据库无缝注册这些 UUID,使 /unlink 和 /linkstatus 能够正常工作。
- 可选的 Floodgate API 反射钩子: 如果你的服务器加载了 Floodgate,验证引擎尝试使用反射来查询活动的
FloodgateApi 实例以动态验证 Bedrock 玩家状态,无需任何硬依赖!
⚙️ 配置 (config.yml)
在插件数据目录中的 config.yml 内设置你的变量:
# Discord 机器人密钥
bot-token: "YOUR_DISCORD_BOT_TOKEN"
guild-id: "YOUR_GUILD_ID"
verified-role-id: "YOUR_VERIFIED_ROLE_ID"
log-channel-id: "YOUR_LOG_CHANNEL_ID"
# 策略设置
code-expiry-minutes: 10
rate-limit-seconds: 60
assume-online-mode: true
overwrite-existing-link: true
? Discord 门户与机器人设置指南
要使用此插件,你必须创建并邀请一个自定义 Discord Bot:
- 创建应用:
- 前往 Discord 开发者门户。
- 点击 New Application(新建应用)并为其命名(例如
MyServerLinker)。
- 获取机器人令牌:
- 在侧边栏中导航至 Bot(机器人)选项卡。
- 点击 Reset Token(重置令牌)并复制生成的长令牌密钥。请妥善保管——必须将其粘贴到
config.yml 的 bot-token 字段下。
- 启用权限意图:
- 在同一个 Bot(机器人)选项卡中,向下滚动至 Privileged Gateway Intents(特权网关意图)。
- 必须启用: Server Members Intent(服务器成员意图)(JDA 需要此权限来查找公会成员以分配角色)。
- 授权 / 邀请机器人:
- 前往 Installation(安装)或 OAuth2 选项卡。
- 选择
bot 和 applications.commands 作用域。
- 在 Bot Permissions(机器人权限)下,选择:
Manage Roles(管理角色)(用于向玩家添加已验证角色)
Send Messages(发送消息)
Read Message History(读取消息历史)
- 复制生成的 URL 并在浏览器中打开,将机器人邀请至你的 Discord 服务器。
- 角色层级警告:
- 在你的 Discord 服务器设置中,进入 Roles(角色)。
- 找到为你的机器人自动创建的角色(其名称应与机器人的应用名称匹配)。
- 将此机器人角色拖拽到你希望分配给玩家的 "Verified"(已验证)角色 上方!
- 原因: 如果机器人的最高角色未位于其试图分配的角色之上,JDA 将抛出
HierarchyException 并静默失败,导致无法分配该角色。
? 分步测试计划
按照以下步骤验证你的链接插件是否正常运行:
- 配置密钥: 将你的机器人令牌、服务器公会 ID 和已验证角色 ID 插入
config.yml。
- 服务器启动: 启动你的 Minecraft 服务器。检查控制台日志,确认 SQLite 创建了
links.db 且 JDA 机器人成功登录。
- 请求链接: 在 Discord 中输入
/link。机器人应立即响应一个临时消息框,显示你唯一的 6 位代码(例如 K3F9XZ)。
- 尝试验证: 加入你的 Minecraft 服务器并输入
/verify K3F9XZ。
- 验证成功:
- 游戏内聊天应显示成功消息:“Successfully linked to Discord user YourName#0000”。
- 你的 Discord 账户应立即获得 "Verified"(已验证)角色。
- 你将收到来自机器人的友好私信,确认链接已成功。
- Discord 日志频道应收到一条丰富的日志嵌入消息。
- 验证过期: 等待 11 分钟(或配置
code-expiry-minutes: 1),然后尝试 /verify <已过期的代码>。服务器应回复清晰的无效/过期代码提示。
- 验证冷却: 在 Discord 中尝试在 60 秒内连续运行两次
/link。第二次尝试应被视觉冷却计时器阻止。
- 检查状态: 在 Minecraft 中输入
/linkstatus。它应获取并显示你链接的 Discord 用户名。
- 移除链接: 在 Minecraft 中输入
/unlink。SQLite 中的对应行将被清除,机器人会立即从你的 Discord 账户中移除 "Verified"(已验证)角色。
Minecraft-Discord Account Linking Plugin (v2 — Full Spec)
A modern, high-performance Paper Minecraft plugin that securely links players' Minecraft accounts to their Discord accounts. This plugin runs an embedded Discord bot using JDA inside the same process and persists connections via a local SQLite database, requiring zero external setup!
?️ HOW THE SYSTEM WORKS
This is a unified plugin running two distinct services in a single Java Virtual Machine (JVM):
- The Minecraft side (Paper command executors and asynchronous task threads).
- The Discord side (JDA client logged in via your bot token, running its own asynchronous listener threads).
Because both sides live in the same process, they don't need socket networks, APIs, or webhooks — they call each other's Java methods directly and share the same SQLite connection pools!
Core Trust & Verification Flow (The Code Bridge)
The linking system bridges two independent identities securely without manual input of sensitive IDs:
- Initiate on Discord: A Discord user types
/link. JDA automatically supplies their permanent numeric Discord snowflake ID (e.g., 23871987349123847) from the interaction event itself.
- Generate Code Ticket: The bot generates a random, clean, easily-readable 6-character code (excluding ambiguous letters like
O, 0, I, 1) and saves a row:
discord_id = <snowflake_id>, code = <random_code>, minecraft_uuid = NULL, verified = 0. This code acts as a single-use claim ticket tied strictly to that Discord account.
- Redeem in Minecraft: The player joins the Minecraft server and types
/verify <CODE>. Paper provides their trusted, authentic Minecraft UUID (player.getUniqueId()) directly from the server session.
- Link Identity Pair: The plugin searches SQLite for an unverified, unexpired match. If found, it populates
minecraft_uuid and flags verified = 1.
- Role Assignment & Logs: The database trigger asynchronously prompts JDA to assign the "Verified" role to the Discord user, send a direct message confirmation, and write a verification record to the admin log channel.
Security Property: The verification code is the ONLY piece of data typed by a user. Nobody ever types their own UUID or Discord ID, entirely preventing account spoofing or identity theft!
⚡ ONLINE-MODE & MOJANG SECURITY
The cryptographic trustworthiness of this linking system depends directly on your server's online-mode setting:
online-mode=true (Recommended & Secure)
The server authenticates every connection directly with Mojang's servers on join. The UUID returned by player.getUniqueId() is guaranteed to belong to the genuine holder of that Minecraft account. Links are cryptographically secure and cannot be spoofed.
online-mode=false (Cracked/Offline Servers)
The server does not verify identity with Mojang. UUIDs are generated offline by hashing the username:
UUID.nameUUIDFromBytes(("OfflinePlayer:" + username).getBytes())
Anyone can join with any username and hijack links. This plugin still runs perfectly on offline servers, but you should:
- Ensure
assume-online-mode is set to false in config.yml.
- Acknowledge that links are only as trustworthy as your usernames (we recommend adding authentication plugins like AuthMe to cracked servers!).
- Review warnings in your Discord logging channel, which flag links created while in offline-mode.
? GEYSER & FLOODGATE BEDROCK COMPATIBILITY
This plugin natively supports Bedrock Edition & Pocket Edition players joining your Java Edition server via Geyser and Floodgate proxies.
Seamless Integration Logic:
- Name Prefix Auto-Detection: Geyser typically prefixes Bedrock usernames with special symbols (e.g.,
*, ., or _) to avoid collisions with Java accounts. The plugin detects these prefix conventions during linking and tags them appropriately.
- Deterministic UUID Matching: Floodgate uses deterministic UUID formats for Bedrock players (where the first 8 digits are zero, e.g.,
00000000-0000-0000-...). The database seamlessly registers these UUIDs, allowing /unlink and /linkstatus to function correctly.
- Optional Floodgate API Reflection Hook: If Floodgate is loaded on your server, the verification engine attempts to use reflection to consult the active
FloodgateApi instance to verify Bedrock player statuses dynamically, requiring zero hard dependencies!
⚙️ CONFIGURATION (config.yml)
Set up your variables inside the config.yml located in your plugin's data directory:
# Discord Bot Secrets
bot-token: "YOUR_DISCORD_BOT_TOKEN"
guild-id: "YOUR_GUILD_ID"
verified-role-id: "YOUR_VERIFIED_ROLE_ID"
log-channel-id: "YOUR_LOG_CHANNEL_ID"
# Policy Settings
code-expiry-minutes: 10
rate-limit-seconds: 60
assume-online-mode: true
overwrite-existing-link: true
? DISCORD PORTAL & BOT SETUP GUIDE
To use this plugin, you must create and invite a custom Discord Bot:
- Create Application:
- Go to the Discord Developer Portal.
- Click New Application and give it a name (e.g.,
MyServerLinker).
- Get Bot Token:
- Navigate to the Bot tab in the sidebar.
- Click Reset Token and copy the long token key. Save it securely — this must be pasted into your
config.yml under bot-token.
- Enable Intents:
- On the same Bot tab, scroll down to Privileged Gateway Intents.
- MUST ENABLE: Server Members Intent (required so JDA can lookup guild members to assign roles).
- Authorize / Invite the Bot:
- Go to the Installation or OAuth2 tab.
- Select the
bot and applications.commands scopes.
- Under Bot Permissions, select:
Manage Roles (required to add the verified role to players)
Send Messages
Read Message History
- Copy the generated URL and open it in a browser to invite the bot to your Discord Server.
- Role Hierarchy Warning:
- In your Discord Server settings, go to Roles.
- Locate the role created automatically for your bot (it will match your Bot's application name).
- Drag this bot role ABOVE the "Verified" role you want to assign to players!
- Reason: JDA will throw an
HierarchyException and fail silently to assign the role if the bot's own highest role is not positioned above the role it is trying to assign.
? STEP-BY-STEP TEST PLAN
Follow these steps to verify your linking plugin operates flawlessly:
- Configuring Secrets: Insert your Bot Token, Server Guild ID, and Verified Role ID into
config.yml.
- Server Boot: Start your Minecraft Server. Check console logs to verify SQLite creates
links.db and the JDA Bot logs in successfully.
- Request Link: In Discord, type
/link. The bot should respond instantly with an ephemeral box showing your unique 6-character code (e.g., K3F9XZ).
- Attempt verification: Join your Minecraft server and type
/verify K3F9XZ.
- Verify Success:
- In-game chat should show a success message: "Successfully linked to Discord user YourName#0000".
- Your Discord account should instantly receive the "Verified" role.
- You should receive a friendly DM from the bot confirming the link.
- The Discord log channel should receive a rich log embedding.
- Verify Expiry: Wait 11 minutes (or configure
code-expiry-minutes: 1) and try /verify <expired_code>. Server should reply with a clean invalid/expired code message.
- Verify Cooldown: Try running
/link twice within 60 seconds on Discord. The second attempt should be blocked by a visual cooldown timer.
- Check Status: Type
/linkstatus in Minecraft. It should fetch and display your linked Discord username.
- Remove Link: Type
/unlink in Minecraft. The row will clear from SQLite, and the bot will instantly strip your "Verified" role in Discord.
评论 0
登录后参与评分
还没有评论,来抢沙发吧