PkLogin
一款专为 Spigot、Paper、Folia 和 Velocity 打造的安全、现代且功能丰富的身份验证插件。
? AI 使用披露
AI 工具被用于辅助 代码开发、翻译以及本 README/文档的编写。
✨ 功能
? 身份验证
- 支持 Paper、Folia & Velocity。
- 已验证账号自动登录 — 在成功验证所有权后,经过身份验证的 Minecraft 账号可以在不创建本地密码的情况下加入服务器。
- 登录会话 — 在可配置的时间段内,对于受信任的重连跳过密码输入。
- 暴力破解保护 — 限制失败的登录尝试次数。
- IP 账号数量限制 — 控制单个 IP 地址可以注册的账号数量。
- 登录超时 — 自动断开未通过身份验证的玩家连接。
- Limbo 系统 — 在通过身份验证之前,禁止玩家移动、使用命令和聊天。
- 安全传送 — 在登录前将玩家传送到安全位置,并在之后恢复其之前的位置。
- 用户名冲突处理 — 防止不同账号模式和 UUID 模式之间的冲突。
?️ Velocity 集成
- 零手动代理配置 — PkLogin 会自动检测网络的转发配置。
- 已验证代理消息 — 使用源自 Velocity 现代转发密钥的 HMAC 签名。
- 后端验证 — 代理可以验证身份验证服务器是否正在运行 PkLogin 并使用相同的签名密钥。
- 需要 Velocity 现代转发 才能实现安全的已验证账号自动登录。
? 密码安全
支持多种哈希算法:
| 算法 |
用途 |
| BCrypt |
推荐的默认值 |
| Argon2id |
强密码哈希 |
| PBKDF2 |
600,000 次迭代 |
| SHA-512 / SHA-256 |
加盐兼容模式 |
| AuthMe SHA256 |
只读迁移支持 |
自动哈希迁移: 随时更改配置的算法。现有的受支持密码哈希会被自动检测,并在玩家下次成功登录后重新哈希。
? 双因素身份验证 (2FA)
- Discord 2FA,基于 DM 的验证码。
- 一次性使用的 6 位验证码。
- 验证码在 5 分钟 后过期,且尝试次数有限。
- 计划在未来的版本中添加其他 2FA 方法。
?️ 数据库支持
- SQLite — 默认,零配置
- H2
- MySQL
- MariaDB
- PostgreSQL
? 迁移
AuthMe → PkLogin
/pklogin authme-import
导入现有账号,同时保留受支持的密码、IP 信息和注册日期。
数据库迁移
/pklogin migrate <engine>
在不删除原始数据的情况下,在支持的数据库引擎之间移动账号。
现有账号会被跳过,这使得迁移操作可以安全地重复执行。
? 国际化
内置 20+ 种语言,包括:
英语、西班牙语、葡萄牙语、法语、德语、俄语、中文、波兰语、意大利语、土耳其语、越南语等。
? UUID 模式
选择如何处理账号 UUID:
REAL — 使用经过身份验证的 Minecraft 账号 UUID。
RANDOM — 生成随机 UUID。
OFFLINE — 使用 Minecraft 标准的离线 UUID 生成方式。
?️ 安全性
PkLogin 的设计围绕 默认的安全身份验证 展开。
已验证账号自动登录
PkLogin 可以验证符合条件的 Minecraft 账号,并允许它们在不创建单独 PkLogin 密码的情况下加入服务器。
对于未知用户名,PkLogin 可以查询 Mojang 的账号服务,并在适用时执行标准的 Minecraft 在线身份验证握手。
成功的身份验证提供了对连接账号的加密验证。
如果外部账号服务暂时不可用,PkLogin 可以使用服务器配置的本地身份验证行为,而不是依赖未经在线验证的身份验证结果。
在独立的 Paper 服务器上,已验证账号自动登录需要 PacketEvents 或 ProtocolLib。Velocity 会自动处理所需的代理端身份验证流程。
登录会话
会话允许已通过身份验证的玩家无需再次输入密码即可重新连接。
Security:
session:
enable: true
timeout: 5
会话具有以下特性:
- 有时限
- 绑定到玩家的 IP 地址
- 一次性使用
- 仅存储在内存中
当密码或 2FA 设置更改、账号被删除或 PkLogin 重载时,它们会自动失效。
安全提示: IP 地址并非唯一的身份标识。请保持会话超时时间较短,尤其是在共享网络上。
?️ 命令
玩家命令
| 命令 |
描述 |
/login <password> |
登录 |
/register <pass> <confirm> |
注册本地账号 |
/changepassword <old> <new> |
修改密码 |
/unregister <password> |
删除本地凭证 |
/premium confirm |
启用已验证的 Minecraft 账号模式 |
/offline |
切换到本地账号模式 |
/2fa discord |
链接 Discord 2FA |
/2fa verify2fa <code> |
验证 2FA 验证码 |
管理员命令
每个命令都有各自的权限。
| 命令 |
描述 |
/pklogin help |
显示管理员命令 |
/pklogin reload |
重载配置 |
/pklogin authme-import |
导入 AuthMe 账户 |
/pklogin migrate <engine> |
迁移数据库引擎 |
/pklogin forcelogin <user> |
强制玩家登录 |
/pklogin unregister <user> |
移除玩家的本地密码 |
/pklogin delete <user> |
永久删除一个账户 |
/pklogin changepass <user> <pass> |
更改玩家的密码 |
/pklogin verify <user> |
查看账户信息 |
/pklogin dupeip <ip/user> |
查找共享同一 IP 的账户 |
/pklogin setspawn |
设置预登录出生点 |
/pklogin update |
下载最新版本 |
⚙️ 配置
PkLogin 高度可配置,同时保持设置简单。
Security:
time-to-login: 45
hash-algorithm: BCRYPT
password:
small: 5
large: 15
session:
enable: true
timeout: 5
autologin:
premium:
enable: true
cache-minutes: 60
bedrock:
enable: true
skip-register: true
passwords:
bruteforce:
max-login-tries: 3
security:
ip-limit:
enable: true
limit: 3
teleport:
safe-location: true
last-location: true
limbo:
blindness-effect: false
username-appender:
enabled: false
? 代理设置
PkLogin 不需要额外的代理密钥或 proxy-mode 选项。
当运行在 Velocity 后端时,PkLogin 会自动读取网络已使用的转发配置,并从 Velocity 的现代转发密钥中派生出单独的签名密钥。
这提供了:
- 安全的代理 → 后端认证
- 防止伪造的认证消息
- 自动后端兼容性检查
- 无需在多个配置文件中重复密钥
对于生产网络,强烈推荐使用 Velocity 现代转发 + 防火墙保护后端端口。
? Discord 双重验证 (2FA)
配置:
# plugins/PkLogin/2fa/discord.yml
enable: false
authentication:
token: "YOUR_BOT_TOKEN_HERE"
使用以下命令绑定账户:
/2fa discord
然后将生成的验证码发送给配置的 Discord 机器人。
? 从 AuthMe 迁移
- 将您的
authme.db 放置于:
plugins/AuthMe/authme.db
- 运行:
/pklogin authme-import
PkLogin 会异步导入兼容的账户,并保留其支持的现有密码哈希。
在可能的情况下,成功登录后会自动将哈希迁移到配置的哈希算法。
? 许可证
MIT License — © 2020–2026 PkLogin Contributors
PkLogin
A secure, modern and feature-rich authentication plugin for Spigot, Paper, Folia and Velocity.
? AI Usage Disclosure
AI tools were used to assist with code development, translations, and this README/documentation.
✨ Features
? Authentication
- Paper, Folia & Velocity support.
- Verified account auto-login — Authenticated Minecraft accounts can join without creating a local password when ownership is successfully verified.
- Login sessions — Skip passwords on trusted reconnects for a configurable period.
- Brute-force protection — Limit failed login attempts.
- IP account limits — Control how many accounts can be registered from one IP.
- Login timeout — Automatically disconnect unauthenticated players.
- Limbo system — Block movement, commands and chat until authentication.
- Safe teleportation — Send players to a safe location before login and restore their previous location afterward.
- Username conflict handling — Prevent conflicts between different account and UUID modes.
?️ Velocity Integration
- Zero manual proxy configuration — PkLogin automatically detects the network's forwarding configuration.
- Authenticated proxy messages — Uses HMAC signing derived from Velocity's modern forwarding secret.
- Backend verification — The proxy can verify that authentication servers are running PkLogin and using the same signing key.
- Requires Velocity modern forwarding for secure verified-account auto-login.
? Password Security
Supports multiple hashing algorithms:
| Algorithm |
Use |
| BCrypt |
Recommended default |
| Argon2id |
Strong password hashing |
| PBKDF2 |
600,000 iterations |
| SHA-512 / SHA-256 |
Salted compatibility modes |
| AuthMe SHA256 |
Read-only migration support |
Automatic hash migration: Change the configured algorithm at any time. Existing supported password hashes are detected automatically and re-hashed after the player's next successful login.
? Two-Factor Authentication
- Discord 2FA with DM-based verification codes.
- Single-use 6-digit codes.
- Codes expire after 5 minutes and have limited attempts.
- Additional 2FA methods are planned for future releases.
?️ Database Support
- SQLite — Default, zero configuration
- H2
- MySQL
- MariaDB
- PostgreSQL
? Migration
AuthMe → PkLogin
/pklogin authme-import
Imports existing accounts while preserving supported passwords, IP information and registration dates.
Database Migration
/pklogin migrate <engine>
Move accounts between supported database engines without deleting the original data.
Existing accounts are skipped, making migrations safe to re-run.
? Internationalization
20+ built-in languages, including:
English, Spanish, Portuguese, French, German, Russian, Chinese, Polish, Italian, Turkish, Vietnamese and more.
? UUID Modes
Choose how account UUIDs are handled:
REAL — Uses the authenticated Minecraft account UUID.
RANDOM — Generates a random UUID.
OFFLINE — Uses Minecraft's standard offline UUID generation.
?️ Security
PkLogin is designed around secure authentication by default.
Verified Account Auto-Login
PkLogin can verify eligible Minecraft accounts and allow them to join without creating a separate PkLogin password.
For unknown usernames, PkLogin can query Mojang's account services and, when applicable, perform the standard Minecraft online authentication handshake.
Successful authentication provides cryptographic verification of the connecting account.
If external account services are temporarily unavailable, PkLogin can use the server's configured local authentication behavior instead of relying on an unverified online authentication result.
On standalone Paper servers, verified-account auto-login requires PacketEvents or ProtocolLib. Velocity handles the required proxy-side authentication flow automatically.
Login Sessions
Sessions allow authenticated players to reconnect without entering their password again.
Security:
session:
enable: true
timeout: 5
Sessions are:
- Time-limited
- Bound to the player's IP address
- Single-use
- Stored only in memory
They are automatically invalidated when passwords or 2FA settings change, accounts are deleted, or PkLogin is reloaded.
Security note: IP addresses are not unique identities. Keep session timeouts short, especially on shared networks.
?️ Commands
Player Commands
| Command |
Description |
/login <password> |
Log in |
/register <pass> <confirm> |
Register a local account |
/changepassword <old> <new> |
Change password |
/unregister <password> |
Delete local credentials |
/premium confirm |
Enable verified Minecraft account mode |
/offline |
Switch to local account mode |
/2fa discord |
Link Discord 2FA |
/2fa verify2fa <code> |
Verify a 2FA code |
Admin Commands
Every command has its own permission.
| Command |
Description |
/pklogin help |
Show admin commands |
/pklogin reload |
Reload configuration |
/pklogin authme-import |
Import AuthMe accounts |
/pklogin migrate <engine> |
Migrate database engines |
/pklogin forcelogin <user> |
Force-login a player |
/pklogin unregister <user> |
Remove a player's local password |
/pklogin delete <user> |
Permanently delete an account |
/pklogin changepass <user> <pass> |
Change a player's password |
/pklogin verify <user> |
View account information |
/pklogin dupeip <ip/user> |
Find accounts sharing an IP |
/pklogin setspawn |
Set the pre-login spawn |
/pklogin update |
Download the latest version |
⚙️ Configuration
PkLogin is highly configurable while remaining simple to set up.
Security:
time-to-login: 45
hash-algorithm: BCRYPT
password:
small: 5
large: 15
session:
enable: true
timeout: 5
autologin:
premium:
enable: true
cache-minutes: 60
bedrock:
enable: true
skip-register: true
passwords:
bruteforce:
max-login-tries: 3
security:
ip-limit:
enable: true
limit: 3
teleport:
safe-location: true
last-location: true
limbo:
blindness-effect: false
username-appender:
enabled: false
? Proxy Setup
PkLogin requires no additional proxy secret or proxy-mode option.
When running behind Velocity, PkLogin automatically reads the forwarding configuration already used by the network and derives a separate signing key from Velocity's modern forwarding secret.
This provides:
- Secure proxy → backend authentication
- Protection against forged authentication messages
- Automatic backend compatibility checks
- No duplicated secrets across multiple configuration files
For production networks, Velocity modern forwarding + firewalling backend ports is strongly recommended.
? Discord 2FA
Configuration:
# plugins/PkLogin/2fa/discord.yml
enable: false
authentication:
token: "YOUR_BOT_TOKEN_HERE"
Link an account with:
/2fa discord
Then send the generated verification code to the configured Discord bot.
? Migrating from AuthMe
- Place your
authme.db in:
plugins/AuthMe/authme.db
- Run:
/pklogin authme-import
PkLogin imports compatible accounts asynchronously and preserves their supported existing password hashes.
When possible, hashes are automatically migrated to the configured hashing algorithm after a successful login.
? License
MIT License — © 2020–2026 PkLogin Contributors
评论 0
登录后参与评分
还没有评论,来抢沙发吧