TgAuth2

TgAuth2

NeoForge 1.21.1 的服务端 Telegram 身份验证。玩家每次登录时通过 Telegram 机器人进行验证,设备会话有效期为 12 小时。

社交

TgAuth — Telegram 认证

仅服务端。 玩家每次登录都通过 Telegram 进行认证。无需客户端模组。


工作原理

新玩家 — 首次设置

  1. 玩家打开 Telegram → 向机器人发送 /start
  2. 机器人检查白名单 → 发放一个 6 位验证码
  3. 玩家加入服务器 → 输入 /tgauth link <code>
  4. 账号永久绑定到其 Telegram

回归玩家 — 每次登录

Join server
    │
    ▼
Same device as last time? (IP-based session, valid 12 hours)
    ├── YES → Auto login, no Telegram needed ✅
    └── NO  → Bot sends confirmation to Telegram:
                  [✅ Yes]   [❌ No]
                  │              │
              Logged in ✅    Kicked ❌

功能特性

  • 🔐 每次登录 Telegram 确认 — 每个新设备都需要批准
  • 💾 12 小时设备会话 — 相同 IP = 在会话窗口内无需提示
  • 📋 按 Telegram ID 白名单 — 仅允许已批准的用户注册
  • 🤖 内联键盘按钮 — 直接在 Telegram 聊天中的 是/否 按钮
  • ⏱ 可配置超时 — 若在 N 秒内无响应则踢出
  • 🔧 管理员命令 — 管理白名单、强制批准、清除会话
  • 💿 持久化数据 — 绑定关系在服务器重启后依然保留(world/data/tgauth_players.json)

设置

1. 创建一个 Telegram 机器人

打开 @BotFather → /newbot → 复制 token。

2. 获取玩家的 Telegram ID

每位玩家向 @userinfobot 发送消息 → 复制其 Id。

3. 配置 config/tgauth-server.toml

[bot]
    botToken    = "1234567890:AAH..."
    botUsername = "MyServerAuthBot"

[whitelist]
    telegramIds = ["123456789", "987654321"]

[session]
    durationHours = 12

4. 重启服务器。 完成。


命令

玩家

命令 描述
/tgauth link <code> 绑定 Telegram 账号(新玩家)
/tgauth status 显示绑定状态和活动会话

管理员(OP 2+)

命令 描述
/tgauth admin whitelist list 列出所有白名单中的 Telegram ID
/tgauth admin whitelist add <id> 添加一个 Telegram ID
/tgauth admin whitelist remove <id> 移除一个 Telegram ID
/tgauth admin unlink <player> 解除玩家的 Telegram 账号绑定
/tgauth admin force <player> 强制批准一个待处理的登录
/tgauth admin sessions <player> 显示活动的设备会话
/tgauth admin clearsessions <player> 使所有设备会话失效
/tgauth admin reload 从配置重新加载白名单

兼容性

Minecraft 1.21.1
加载器 NeoForge
端 仅服务端
Java 21+

常见问题

玩家可以在同一网络下吗? 可以。指纹由 IP + UUID 组合而成,因此同一 NAT 下的两名玩家具有不同的指纹。

如果玩家使用 VPN 会怎样? 其 IP 会变化 → 会话失效 → 下次登录需要 Telegram 确认。

这在离线模式服务器上能工作吗? 可以,匹配通过 UUID 完成,NeoForge 在在线和离线模式下均会提供 UUID。

机器人 token 存储安全吗? 它位于服务器上的 config/tgauth-server.toml 中 — 请妥善保管该文件。