认证核心

---

✅ 一套代码库，支持所有 Minecraft 版本与所有加载器，1.16.0 → 26.x 及以上，可运行于服务器、Velocity/BungeeCord 之后或独立运行，支持 Fabric / Forge / NeoForge（参见 🔮 多版本与多加载器）。

🧭 初次使用？ 请从 服务器管理员指南 开始，涵盖 jar 选择、安装、配置详解、认证流程、命令和故障排查，并提供一条学习路径，将每个主题映射到更深层的文档（CONFIG / PROXY / WEBPANEL / SECURITY / DEVELOPMENT），让你一步步从零到精通。所有文档也托管为一个精美站点：authcore.potenfyr.in。

---

🔥 亮点

📖	新手友好的安装，开箱即用（默认 SQLite），所有选项均为可选（指南）
🔑	正版自动登录，从 server.properties 自动检测服务器模式，防中断的异步 Mojang 验证并支持自动恢复，离线版回退；混合模式 — 离线玩家也可加入正版模式服务器（allow-offline-players，默认开启）
🔐	2FA / MFA，TOTP 验证器代码、一次性恢复代码、邮箱 OTP、针对敏感操作的 MFA 提权
🕸️	网络 SSO，基于 Redis 的跨服务器网络单点登录
🚪	锁定的登录大厅，无形的 limbo，验证前无法移动/放置方块/聊天，带防抖动移动校正（半径 + 限流快速拉回），完全惰性的物品栏（每次点击都被阻止；聊天绝不受影响），以及崩溃安全的 limbo 快照（服务器崩溃绝不会让玩家在登录后卡在 limbo 状态）
🔘	可点击的聊天按钮（下划线、阴影样式的标题/动作栏），可适应服务器真实的认证需求：2FA 代码、密码确认会以玩家所需的准确命令形式显示
🗂️	拆分配置，每个配置块一个文件（settings.conf + lobby.conf + session.conf + password-rules.conf + commands.conf + database.conf），从旧版单一文件自动迁移
🛡️	防滥用，暴力破解锁定、风险触发的人机验证（物理任务验证码）、速率限制、IP 规则、蜜罐
🧱	针对所有场景加固，符合 OWASP 的威胁模型（弱哈希、冒充、枚举、OP 滥用、战斗记录、SSRF、竞态条件、数据库迁移失败）— 参见安全模型
🧵	无竞态条件，线程安全的规范缓存（每个账户一个 User），到处使用 ConcurrentHashMap/原子计数器，去重的加入/离开钩子，任何路径上都无锁或死锁
🤖	ClientGuard，幽灵客户端 / 宏 / 数据包洪水检测，配套证明，风险评分决策矩阵
🧠	登录智能，风险评分、设备指纹、新 IP/新国家警报
🔔	Discord / webhooks / 邮件，每个安全事件都会发出警报；SMTP 恢复代码
🗄️	SQLite / MySQL / PostgreSQL + Redis 会话与封禁同步，跨服务器事件总线
🌐	Web 管理面板，带令牌认证的仪表盘（完整 + 只读）、HTTPS、暴力破解锁定
👥	Discord 账户绑定，/discord link 代码流程（Redis + 面板 API；机器人在任何时候都不会触碰数据库）
🤝	第三方模组集成，DiscordSRV 绑定同步（认证时自动导入已绑定的 Discord 账户），兼容 InteractiveChat（大厅范围内的限制绝不影响其他模组），/authcore compat 报告
🔁	代理就绪，BungeeCord/Velocity 转发自动检测，Velocity 现代身份（HMAC），与其他认证模组互操作
🌍	7 种内置语言 + 自定义 messages-<lang>.conf，带完整性检查
⚡	50 万+ 账户规模，每条热路径上 O(1) 用户查找，惰性数据库加载，有界缓存，零每 tick 工作，非阻塞 I/O，加入/登录突发下无资源峰值，≤250 MB RAM 配置
🧩	多加载器，一套代码库，为每个版本范围提供 Fabric / Forge / NeoForge 服务器模组，单一源码树产出 7 个 jar
🎯	一个 jar，两种角色，服务器模组 + BungeeCord/Velocity 插件（自动检测）
🔮	面向未来，反射兼容层，版本稳定的 mixin，诚实的 2 角色 × 3 加载器 CI

---

🛡️ 检测绕过抵抗

AuthCore 实现了 7 层纵深防御体系，使自动化客户端绕过认证几乎不可能：

层级	机制	拦截目标
1. 会话绑定	每服务器随机 32 字节配套证明密钥（重载时轮换）	配套伪造、重放攻击、会话令牌窃取
2. 数据包序列验证	登录期间 HELLO → SETTINGS → READY 状态机	跳过/重排登录数据包的客户端、自定义协议实现
3. 行为画像	ClientGuard 风险评分：品牌异常、幽灵检测、洪水限制、选项卡探测	幽灵客户端、宏用户、数据包洪泛者、侦察机器人
4. 视角模式分析	相机旋转变化量方差（变异系数）	零视角、相机移动完全规律的机器人
5. 登录时间分布	IP 级登录时间戳 CV 分析（60 秒窗口，≥3 个样本）	同步定时的僵尸网络农场、凭证填充突发
6. 并发连接指纹	同一 IP 在 5 秒内 ≥3 个不同用户名	僵尸网络农场多账户协同
7. 登录智能	设备指纹（IP+国家）、新 IP/国家警报、2FA 速率限制（5 次/分钟/IP）	账户共享、凭证填充、2FA 暴力破解

关键架构保证：

• 故障关闭默认值：代理认证需要 Redis；空 trusted-proxies 会禁用代理支持
• 每服务器密钥：任何地方都没有硬编码密钥 — 首次启动时生成证明密钥
• 状态完整性：所有检测映射均有界（基数限制）并在 tick 时修剪
• 无单点故障：每层独立；绕过一层不会禁用其他层

---

📦 我需要哪个 jar？

每个 jar 都同时扮演两种角色：服务器模组（Fabric/Forge/NeoForge）和 BungeeCord/Velocity 代理插件（由你放入的加载器自动检测）。选择与你的 Minecraft 版本范围和加载器匹配的 jar：

Jar	Minecraft	加载器	Java	备注
authcore-1.16-1.18-fabric-<v>.jar	1.16.0 - 1.18.2	Fabric	17	中间映射时代
authcore-1.16-1.18-forge-<v>.jar	1.16.0 - 1.18.2	Forge	17	中间映射时代
authcore-1.19-1.21-fabric-<v>.jar	1.19.0 - 1.21.11	Fabric	21	中间映射时代
authcore-1.19-1.21-neoforge-<v>.jar	1.19.0 - 1.21.11	NeoForge	21	中间映射时代
authcore-26.1-26.2-fabric-<v>.jar	26.1 - 26.2+ 及快照	Fabric	25	未混淆时代（Mojang 名称，向前兼容）
authcore-26.1-26.2-neoforge-<v>.jar	26.1 - 26.2+ 及快照	NeoForge	25	未混淆时代（Mojang 名称，向前兼容）

为什么按范围划分 jar？Minecraft 26.0+ 发布的是未混淆代码，Fabric 的中间映射在那里已不存在，参见 Fabric 的公告。每个 jar 在发布前都会由宿主测试框架在其范围内的每个版本上启动。详情见 26.x 构建。

---

🚀 安装

1. 安装你的加载器：Fabric（Loader + Fabric API）、Forge 或 NeoForge。
2. 从 Modrinth 或 GitHub Releases 获取正确的 jar（版本范围 × 加载器）。
3. 将其放入 mods/，启动服务器，配置会自动生成在 config/authcore/。

首次加入： 正版 → 自动检测（服务器自身的会话验证，即使在离线模式服务器上也是如此，会话 API 宕机时自动重试）→ 使用空密码自动登录（绝不会存储生成的密码）· 离线版 → 移至大厅 → /register <pw> <pw> 或 /login <pw> → 返回原处，会话已保存。玩家可随时通过 /account set-mode online|offline 切换自己的登录方式（管理员：/authcore set-mode online|offline <player>）。

---

🛠️ 命令

玩家

命令	作用
/register <password> [<confirm>] [<2fa>]	创建你的账户
/login <password> [<2fa>]	登录并离开大厅
/account logout · set-password <new> · codes	会话、密码与备用代码
/account email <address> · nickname <name>	登录警报/恢复 · 显示名称
/account set-mode online|offline	在自动登录与密码登录之间切换你自己的账户
/account recover <email> [<code> <new-password>]	邮箱密码恢复
/account unregister	删除你自己的账户
/discord link · /discord unlink	Discord 账户绑定

管理员 （OP 3+、LuckPerms 节点或控制台）

命令	作用
/authcore reload · validate · compat	重载配置/消息 · 试运行配置检查 · 兼容性报告（加载器、配置版本、DiscordSRV/InteractiveChat 集成）
/authcore import authme <file>	从 AuthMe SQLite 数据库导入账户（绝不覆盖；弱哈希在下次登录时自动升级）
/authcore whois <player> · history <player>	账户信息 · 最近 10 次登录及风险
/authcore list players · list online/offline-players	基于数据库的账户列表
/authcore destroy-session <player>	强制登出 + 踢出
/authcore set-password <player> <new>（别名 resetpw）	重置密码
/authcore set-mode online|offline <player>	强制账户的模式（自动登录 / 密码登录）
/authcore delete player <player>	清除账户
/authcore set-spawn limbo <x> <y> <z> · backup · export	大厅出生点 · 数据库备份 · JSON 导出
/authcore maintenance on|off	以自定义消息阻止加入

---

⚙️ 配置

所有文件在首次启动时生成于 config/authcore/。配置被拆分为每个配置块一个文件；每个设置恰好有一个归属文件：

文件	拥有	典型内容
settings.conf	根设置	language、debugMode、logging、cache-max-users、配置 version
session.conf	session { … } 块	认证流程、会话、账户锁定、SSO、Web 面板、邮件、客户端守卫
lobby.conf	lobby { … } 块	limbo 限制、超时、验证码、移动校正调优
password-rules.conf	passwordRules { … } 块	密码策略（长度、字符类别、哈希）
commands.conf	commands { … } 块	每命令的 LuckPerms 节点 / 权限等级
database.conf	database { … } 块	SQLite / MySQL / PostgreSQL / Redis（凭据不放在主文件中）
messages-<lang>.conf	面向玩家的消息	英文为 messages.conf，每个语言环境一个文件

区块文件会覆盖 settings.conf 中的相同块（后者只保留根级键）。升级时，旧的单一文件设置会自动迁移到区块文件中，因此不会丢失任何内容。database.conf 之前作为可选覆盖存在；现在它是一个常规的区块文件。

你实际会更改的设置：

# settings.conf
language = "en"              # en | zh | es | de | fr | pt | ru

# session.conf
session {
    # 服务器的正版/离线模式始终自动取自
    # server.properties (online-mode) - 此处无需设置。
    timeout-ms = 3600000     # 会话有效期（60 分钟）

    account-lock { enabled = true
                   max-failed-logins = 8
                   lock-duration-ms = 600000 }

    security { webhook-url = "" }   # ← 用于安全警报的 Discord webhook

    proxy-support { enabled = false  # BungeeCord / Velocity IP 转发
                    protocol = "auto" }

    web-panel { enabled = true
                host = "127.0.0.1"
                port = 25570
                token = "CHANGE_ME" }   # 生成：openssl rand -hex 16

    email { enabled = true              # 登录警报 + 密码恢复
            host = "smtp.gmail.com"
            port = 587
            username = "you@gmail.com"
            password = "app-password"
            from = "AuthCore <you@gmail.com>" }
}

# lobby.conf：值得了解的 limbo 调优
lobby {
    movement-correction-radius = 1.5      # 客户端在快速拉回前可偏移的距离
    movement-correction-interval-ms = 600 # 两次快速拉回之间的最短时间（无屏幕抖动）
}

📖 每个选项（约 180 项设置）、默认值及用例： 配置参考

---

🚦 功能设置一览

以下每个功能都是可选的 — AuthCore 以零配置、使用 SQLite 运行。只启用你的服务器所需的功能。包含每个功能场景的完整分步指南在此：设置指南（逐功能）。

功能	配置块	启用理由	快速设置
人机验证（动作验证码）	lobby.captcha	阻止登录/注册时的机器人。每次登录都会评分（幽灵模式、秒登录、缺少 2FA、新账户、快速重连）；只有类似机器人的玩家会得到物理任务（潜行/跳跃/抬头看）。信任信号（正版、令牌、受信任）会减分。默认开启。	lobby { captcha { enabled = true } }
2FA / MFA（TOTP、邮箱 OTP）	session.authentication	防止密码泄露/被盗	allow-totp-support = true（邮箱 OTP 另需 SMTP）
账户锁定与暴力破解	session.account-lock	重复失败后锁定账户	account-lock { enabled = true }
会话	session.enable-sessions	重连时无需重新输入密码	enable-sessions = true
ClientGuard	session.client-guard	宏/幽灵客户端/洪水检测，带 0-100 风险评分	client-guard { enabled = true }
AuthIntelligence	session.auth-intelligence	密码喷洒、登录洪水、2FA 暴力破解、僵尸网络农场、会话重放、账户接管警报	auth-intelligence { ... }（所有检测默认开启）
速率限制	session.rate-limit	阻止每 IP 的加入/登录洪水	rate-limit { enabled = true }
IP 规则	ip-rules.conf	允许/拒绝特定 IP 或网络	deny = ["45.155.0.0/16"]
SSO（网络范围）	session.sso + Redis	登录一次 = 在网络中所有服务器上受信任	database { redis { enabled = true } } + sso { enabled = true }
Web 管理面板	session.web-panel	带令牌认证 + 锁定的管理仪表盘	web-panel { enabled = true; token = "..." }
蜜罐	session.honeypot	诱捕并记录端口扫描者	honeypot { enabled = true; port = 25571 }
正版自动登录	session.authentication	付费玩家即时加入 — 默认开启，在正版和离线模式服务器上都有效（服务器验证，防中断）；自动登录玩家绝不会有密码（null），切换到密码登录时保留	premium-auto-login = true
代理支持	session.proxy-support	Velocity/BungeeCord 后的真实客户端 IP	proxy-support { enabled = true; protocol = "auto" }
维护模式	session.maintenance	更新期间阻止加入	/authcore maintenance on
自动白名单	session.auto-whitelist	已注册玩家自动加入白名单	auto-whitelist { enabled = true }
影子封禁	session.shadow-ban	对攻击者隐藏安全拦截	shadow-ban { enabled = true }
备份	session.backup	自动轮换数据库备份	backup { interval-hours = 24; keep = 10 }
Discord 绑定	session.discord-link	绑定 Discord 账户以便恢复	discord-link { enabled = true }
Webhooks / 邮件警报	session.security	每个安全事件都收到警报	security { webhook-url = "https://discord.com/api/webhooks/..." }

🧠 场景 — 公共生存服务器： 默认开启的人机验证 + 暴力破解锁定 + 速率限制可阻止 99% 的机器人。为职员账户添加 2FA。添加 Web 面板 + webhooks，这样你无需触碰控制台就能看到每个警报。这就是全部设置 — 其他一切都是可选调优。

---

🌍 语言

代码	语言	代码	语言
en	English	de	Deutsch
zh	简体中文	fr	Français
es	Español	pt	Português
ru	Русский

自定义语言环境：将 messages-<lang>.conf 放入 config/authcore/，缺失的键会被记录。

---

🔁 代理与网络（Velocity / BungeeCord）

AuthCore 运行在模组服务器上，Fabric、Forge 或 NeoForge，并正确支持每种代理设置：

• IP 转发自动检测（session.proxy-support.protocol = "auto"），从握手中解析 BungeeCord 和 Velocity-legacy（ip\0uuid\0properties）；真实客户端 IP 用于 GeoIP、会话、速率限制和登录智能
• Velocity 现代身份转发，HMAC 验证的 velocity:player_info 登录接收器应用真实 UUID/用户名（来自 velocity.toml 的 velocity-secret）
• 互操作通道 authcore:auth（+ BungeeCord 子通道 AuthCore），AuthCore 广播 AUTH_CHANGED|<uuid>|<username>|<1|0>，使网络可以在后端与不同的认证模组共存
• 混合 / 枢纽网络：会话恢复可在枢纽 → 游戏传送间工作（同 IP 要求仅在 session.session-from-same-ip-only 启用时适用），SSO/Redis 信任在服务器间携带登录，代理后的正版验证被禁用（由代理进行认证）
• 每种角色单独的配置，服务器 settings.conf + 区块文件（lobby.conf、session.conf、password-rules.conf、commands.conf、database.conf）；Redis 配置同步分发网络范围的设置
• 📖 完整指南：代理支持

---

⚡ 性能

设计为可轻松承载 50 万+ 注册账户和数千名并发玩家，资源占用平稳 — 无峰值，即使在加入/登录突发下也是如此：

• 每条热路径上 O(1) 用户查找：移动数据包、点击、聊天和 tick 都通过 UUID 键的 ConcurrentHashMap（User.getUser(player)）解析玩家：无字符串分配、无映射扫描、无数据库触碰。用户名路径也已索引（预计算的小写名称），因此即使 lookUpByUsername 模式也绝不扫描缓存。
• 无竞态条件的并发：规范的、线程安全的内存缓存（每个账户一个 User 实例 — getUserByUsername 在单个锁下序列化缓存未命中的数据库获取），所有共享映射和加入/离开去重集使用 ConcurrentHashMap/ConcurrentHashMap.newKeySet，传送 ID 使用原子计数器，专门的有限守护线程池处理 I/O — 任何路径上都无锁、无交错语句、无死锁。
• 绝无峰值："touch" 映射的写入是每个用户每分钟一次，而不是每个数据包一次；limbo 中每用户限流的传送（半径 + 间隔）意味着没有 20Hz 位置数据包洪水；到处都是有界、自清理的缓存；速率限制吸收加入/登录洪水而不会出现资源悬崖。
• 零每 tick 工作，一切都发生在加入/登录/登出事件上；每条热路径在任何玩家数量下都是每数据包恒定成本。
• Mojang 和 GeoIP 查找已缓存（数小时长的 TTL），5000 名玩家的突发仅花费几个 HTTP 请求；所有外部 I/O 在有界守护线程池上非阻塞。
• 惰性用户加载，50 万+ 注册账户保持轻量（有界 LRU，在线用户绝不被逐出；名称索引和最后访问映射同步修剪）— 仅在缓存未命中时才触碰数据库。
• SQLite 为低端机器调优（WAL + synchronous=NORMAL，约 2 MB 页缓存）；MySQL / PostgreSQL 用于多服务器或更大的网络。
• Web 面板默认关闭，在你选择启用之前，模组作为基本、精简的认证插件运行。
• Mixin 仅涉及登录/玩家，与 C2ME、Lithium、Krypton、ModernFix、FerriteCore 无冲突。
• 无绕过：载具移动数据包、配方书放置、物品丢弃/点击和命令提示在 limbo 中都被锁定；即使客户端认为服务器实体移动了，实体也绝不离开锚点。物品栏完全惰性（每次槽位点击都被阻止，交互时关闭），而聊天输入绝不中断：/register 和 /login 始终有效。

🪶 低资源服务器（≤ 250 MB RAM / 1 核）

AuthCore 本身很小；服务器 JVM 占主导。对于 1 核 / ≤250 MB 的机器，在你的启动脚本中添加：

java -Xmx192M -Xms64M -XX:+UseSerialGC -XX:TieredStopAtLevel=1 \
     -XX:-UsePerfData -XX:MaxMetaspaceSize=96M -jar fabric-server.jar nogui

提示：将 settings.conf 中的 cache-max-users 保持默认（20000）或降低（例如 5000），保持 MySQL/PostgreSQL/Redis 禁用（SQLite 最轻），并保持 Web 面板禁用（session.web-panel.enabled = false，默认值）。

---

🔮 多版本与多加载器兼容性

一套代码库产出六个 jar，3 个版本范围 × Fabric/Forge/NeoForge，由宿主测试框架验证：

Jar	版本	方式
authcore-1.16-1.18-{fabric,forge}	1.16.0 - 1.18.2	组 G1 · 构建于 @1.18.2（Java 17，中间映射）
authcore-1.19-1.21-{fabric,neoforge}	1.19.0 - 1.21.11	组 G2 · 构建于 @1.21.11（Java 21，中间映射）
authcore-26.1-26.2-{fabric,neoforge}	26.1 - 26.2+ 及快照	组 G3 · 构建于 @26.2（Java 25，未混淆的 Mojang 名称）

• 多加载器是项目的核心，Fabric、Forge 和 NeoForge 变体共享同一棵树（加载器常量 fabric/forge/neoforge/forgeLike），带有薄的每加载器入口点（FabricEntry、ForgeEntry、NeoForgeEntry）和每加载器元数据（fabric.mod.json、mods.toml、neoforge.mods.toml）。添加或升级加载器只需在 Stonecutter 矩阵中改一行，而不是移植。
• 多版本工作区（Stonecutter + Stonecraft），一个 Mojang 映射的源码树位于 src/main/java，使用 /*? if ... {*/ 版本/加载器条件；每版本依赖在 versions/dependencies/ 中。
• 一个 jar，两种角色，同时是服务器模组和 BungeeCord/Velocity 代理插件。
• 宿主测试框架（test/docker）：在 Docker 中并行启动每个范围 jar — 在官方 eclipse-temurin JRE 镜像上（17/21/25），按 Java 版本要求分组（G1：17，G2：21，G3：25）— 在范围端点（1.16.5 到 26.2+）上运行，并执行功能检查（模组加载干净，无错误/警告、正确的横幅、管理命令、配置/数据库、游戏端口）。
• CI（一个工作流）：构建所有变体，运行安全测试，按组执行并行 Docker 宿主测试，并在 v* 标签时发布到 GitHub Releases。
• 未测试的版本会收到启动警告横幅（绝不拒绝加载），用 logging.show-untested-version-warning = false 静默。

---

🧑‍💻 从源码构建

Gradle 本身需要 JDK 25（26.1-26.2 变体会强制要求）。如果需要便携式 Java，运行 test/install-java-and-provided-jars.sh（或 .ps1）以自动将 Adoptium JDK 17、21、25 和代理编译时库设置到 java-jars/。

./gradlew buildAll                 # 所有六个变体（3 个范围 x fabric/forge/neoforge），jar 存入 dist/
./gradlew build                    # 仅活动变体（1.21.11-fabric）

# 单个变体：
./gradlew :1.18.2-fabric:build     # -> versions/1.18.2-fabric/build/libs/authcore-1.16-1.18-fabric-1.0.0.jar
./gradlew :1.18.2-forge:build      # -> versions/1.18.2-forge/build/libs/authcore-1.16-1.18-forge-1.0.0.jar
./gradlew :1.21.11-fabric:build    # -> versions/1.21.11-fabric/build/libs/authcore-1.19-1.21-fabric-1.0.0.jar
./gradlew :1.