AdventureLogins
AdventureLogins 是 Velocity 与登录服一体化的身份验证项目，将正版会话验证、离线账号注册、个人资料、邀请码和密码恢复放在同一条登录链路中。
正版免密
由 Velocity 完成 Mojang / Microsoft 会话验证，绑定后直接进入。
离线密码
离线玩家通过注册与登录命令验证，未认证期间全面锁定。
身份路由
统一的正版、离线身份资料和保留命名空间，避免身份冲突。
风险控制
区分普通与异地 IP 登录，提供失败次数、超时和冻结策略。
运行要求
| 版本 | 0.5.7 |
|---|---|
| 代理端 | Velocity 3.4 |
| 登录服 | Paper / Folia，Minecraft Java 1.21.1—1.21.11 |
| Java | 21 或更高 |
| 可选依赖 | PlaceholderAPI、PacketEvents 或 ProtocolLib |
正式启用前必须更换代理认证和密码重置密钥，并备份三份 properties 数据文件。
安装部署
- 使用 JDK 21 构建或取得 AdventureLogins 产物。
- 将 Velocity 模块放入代理端
plugins/。 - 将登录服模块放入 Paper / Folia 登录服
plugins/。 - 首次启动生成配置和身份数据文件后关闭服务器。
- 在两端设置一致的代理认证 secret，再完成登录服路由。
数据文件
| 文件 | 内容 |
|---|---|
users.properties | 离线账号密码资料 |
auth_profiles.properties | 正版/离线身份路由资料 |
profiles.properties | 个人资料、平台绑定和邀请码 |
登录服只承载认证流程；认证完成后再由现有传送或路由系统将玩家送往目标子服。
双端架构
模块组成
| 模块 | 职责 |
|---|---|
adventurelogins-core | 身份类型、路由决策、名称策略和资料存储 |
adventurelogins-velocity | 连接入口、正版会话验证、离线名称改写与后端路由 |
adventurelogins-loginserver | 注册登录、玩家锁定、GUI、邮箱、密码与资料管理 |
adventurelogins-universal | 统一发布产物 |
认证边界
- 正版真实性由 Velocity 在线会话校验决定。
- 登录服只接受代理发来的可信认证结果。
proxy-auth.secret必须与代理端auth-gate.properties一致。- 不得让玩家绕过 Velocity 直连登录服。
身份模型
正版身份
Velocity 强制在线验证；成功后保存正版名称与 UUID，后续登录自动免密。
离线身份
离线玩家进入后端前会统一改写为 _{ID}_，例如 Steve 进入后端时显示为 _Steve_。
- 不支持中文 ID。
_ID_命名空间由系统保留。- 展示和资料查询时会还原原始名称。
- 身份一旦确定，应通过管理流程清理后再重新选择。
身份资料同时关联代理路由、登录密码和个人资料；只删除其中一个文件会造成状态不一致。
新玩家流程
- 玩家连接 Velocity，离线身份先以
_{ID}_进入登录服。 - 等待 CraftEngine 材质包和 AdventureRule 同意流程完成。
- 身份选择器以外部 Dialog 或内置箱子 GUI 打开。
- 选择正版：进入倒计时并断开，重新连接时完成正版验证。
- 正版验证成功后保存资料、执行正版权限命令并免密进入。
- 选择离线：进入锁定状态，使用
/reg <密码> <重复密码>注册。
正版授权命令
premium:
pending-seconds: 300
countdown-seconds: 3
permission-command: "lp user {player} permission set adventurelogins.premium true"已注册玩家
| 状态 | 处理 |
|---|---|
| 已绑定正版 | 代理验证通过后直接免密 |
| 已注册离线 | 施加失明和缓慢，使用 /l <密码> |
| 普通登录 | 默认 120 秒，最多失败 5 次 |
| 可疑/异地 IP | 默认 60 秒，失败 3 次后冻结 30 分钟 |
锁定期间
插件可隐藏未认证玩家，锁定移动速度，并只允许注册、登录或密码辅助白名单中的命令。
lock:
hide-unauthenticated-players: true
walk-speed:
locked: 0.0
effects:
blindness-amplifier: 0
slowness-amplifier: 4安全策略
| 设置 | 默认值 |
|---|---|
| 密码长度 | 6—64 |
| 普通失败次数 | 5 |
| 可疑失败次数 | 3 |
| 可疑冻结 | 1800 秒 |
| 近期登录窗口 | 7 天 |
| 每日改密次数 | 2 |
| IPv6 识别前缀 | /64 |
管理员授权
admin.authorized-ids 优先填写 UUID；名称只对已验证的正版玩家生效。代码同时检查 adventurelogins.admin.* 权限。
password-reset.token-secret 和 proxy-auth.secret 均不可保留默认的 CHANGE-ME 值。
config.yml
核心分区
| 分区 | 用途 |
|---|---|
module | 登录服与 PAPI 模块开关 |
security | 失败次数、超时、密码和 IP 策略 |
admin | 额外授权 UUID/正版名称 |
mail | 邮箱域名、验证码和 SMTP |
password-reset | 网页重置地址、令牌期限和密钥 |
proxy-auth | 登录服与 Velocity 信任密钥 |
commands | 各认证阶段命令白名单和补全 |
identity.selector | inventory、dialog 或 auto |
登录出生点
login-spawn:
enabled: false
teleport-on-join: true
world: ""
x: 0.5
y: 64.0
z: 0.5邮箱与密码重置
验证码限制
- 默认只允许
@qq.com。 - 验证码有效期 300 秒，冷却 60 秒。
- 每日最多 3 次，单码最多尝试 5 次。
- SMTP 默认关闭，需要填写主机、授权码和发件人。
网页桥接
可直接连接网站数据库，也可以通过签名 HTTPS 请求发布重置令牌。外网数据库不可用时启用 website-bridge，网站仍在本地写入 MySQL。
SMTP 授权码、数据库密码和 bridge secret 不应提交到公开仓库；修改后限制配置文件访问权限。
兼容与 GUI
身份选择器
| 模式 | 行为 |
|---|---|
inventory | 始终使用内置箱子 GUI |
dialog | 执行 AdventureRule Dialog 命令，失败时按配置回退 |
auto | 优先 Dialog，无法打开则回退箱子 GUI |
等待链
compat.wait-adventurerule 会等待规则流程；GUI 另有初始、资源包、规则重试延迟和最大尝试次数，避免界面在材质包或规则窗口前抢先弹出。
可选插件
- PlaceholderAPI：账户状态变量。
- PacketEvents / ProtocolLib：协议层兼容支持。
- AdventureRule：外部 Dialog 身份选择和入服规则流程。
- CraftEngine：通过延迟机制等待资源包加载。
命令与权限
| 命令 | 说明 |
|---|---|
/reg <密码> <重复密码> | 注册离线账号 |
/l <密码> | 登录离线账号 |
/alogin help | 账号中心帮助 |
/alogin mail ... | 邮箱绑定、验证码、修改与重置 |
/alogin pass ... | 密码辅助、设置和重置流程 |
/alogin setpass / change | 设置或修改离线密码 |
/alogin profile | 打开个人资料 |
/alogin invite create|use | 创建或使用邀请码 |
/alogin admin reload | 重载配置 |
/alogin admin clear <玩家> | 清除指定账号资料 |
管理员权限
代码使用 adventurelogins.admin 以及 adventurelogins.admin.reload、.clear、.mail、.pass、.webreset 等细分权限，并支持配置中的额外授权 ID。
PlaceholderAPI 变量
变量前缀为 adventurelogins。
| 变量 | 返回内容 |
|---|---|
%adventurelogins_bound_status% | 是否绑定正版 |
%adventurelogins_premium_name% | 正版 ID |
%adventurelogins_premium_id% | 正版 UUID |
%adventurelogins_password_mode% | 已免密 / 需要密码 |
%adventurelogins_account_type% | 正版 / 离线 |
%adventurelogins_platform_mail% | 已绑定邮箱 |
%adventurelogins_platforms% | 平台绑定汇总 |
%adventurelogins_invited_by% | 邀请人 |
%adventurelogins_change_remaining% | 今日剩余改密次数 |
故障排查
玩家无法进入登录服
- 检查 Velocity 与后端版本是否均为 0.5.7。
- 确认后端不可被公网直连。
- 检查两端 proxy auth secret 是否完全一致。
身份 GUI 不出现
- 暂时将 selector 改为
inventory排除外部 Dialog 问题。 - 检查 AdventureRule 命令和规则 ID。
- 增大资源包与规则等待时间。
玩家持续被识别为异地 IP
- 确认代理正确转发真实地址。
- IPv6 用户可保留默认 /64，精确匹配才设置为 128。
- 不要通过手工删除单个资料文件解除冻结。