跳到主要内容

通过 Telegram 登录

XLADA 允许管理员使用 Telegram 账号登录面板。这样登录时 不需要密码：面板会把你带到 Telegram 页面，确认后 发放普通的 JWT 令牌。这便于日常工作，也 能防止密码被暴力破解。

通过 Telegram 登录仅限面板管理员登录。它与 订阅用户无关，并且与用于通知的机器人分开配置。

需要什么​

配置位于面板的 Settings → Authentication → Telegram OAuth2 区域。需要四个值：

字段是什么
启用提供方开关
Client IDTelegram 应用标识符
Client SecretTelegram 应用密钥
Frontend Domain面板域名，不带 https://，例如 panel.example.com
Allowed IDs管理员数字 Telegram ID 列表

Client ID 和 Client Secret 由 Telegram 为你的机器人签发——这是单独 的数据，不是 TELEGRAM_BOT_TOKEN 令牌。面板域名必须是真实的 FQDN：面板用它构造回调地址，且它必须与为机器人 注册的地址一致。

需要为机器人放行的回调地址：

https://panel.example.com/api/auth/oauth2/callback/telegram
提示

请完整复制回调地址，连同 /api/auth/oauth2/callback/telegram。 如果只填写域名，Telegram 无法把你送回面板。

在 Allowed IDs 中添加管理员的数字 ID。该列表是必填的：只要 它为空，就无法启用提供方，任何人都无法登录。ID 是 数字，而不是用户名。

注意

如果 Client ID、Client Secret 或 Frontend Domain 中哪怕有一项未填写，面板都不会启用 Telegram OAuth2。 请保存设置并立即检查登录，以免失去访问权限。

登录过程​

  1. 你点击通过 Telegram 登录，面板会打开 Telegram 授权 页面。
  2. 面板发送 state 和 PKCE 校验（code_verifier，S256 方法）； 请求使用 openid、profile 和 telegram:bot_access 权限范围。
  3. Telegram 把授权码返回到回调地址——也就是 /api/auth/oauth2/callback/telegram。
  4. 面板校验 state 和提供方，用授权码换取令牌，并从 ID 令牌中读取用户的数字 ID。
  5. 如果该 ID 在 Allowed IDs 中，面板会发放超级管理员令牌， 并把成功登录写入日志。
说明

确认后进入面板的是第一位管理员（超级管理员）。 其他管理员无法通过 Telegram 登录——这是有意为之。

限制​

  • 提供方仅通过 HTTPS 工作：没有带 TLS 的反向代理，面板本来也无法 启动。
  • Frontend Domain 不带协议和路径。本地调试时 可以使用 localhost 和 127.0.0.1。
  • Allowed IDs 是唯一的访问过滤器。如果列表为空或其中 有多余的 ID，不该进来的人也能登录。
  • 提供方可以与密码和其他登录方式一起启用——它们不会 冲突。

安全​

面板通过多种机制保护登录：

  • state 保存在 Valkey 中且有效期有限——没有它无法 伪造 Telegram 的响应；
  • 使用 PKCE，因此被截获的授权码无法变成令牌；
  • 访问权由 ID 列表决定，而不是邮箱地址或姓名；
  • 登录失败会以事件 service.login_attempt_failed 记录， 并发送到 Telegram 和 Webhook；
  • 密码不会包含在这类通知中。
危险

Client Secret 是完整的密钥。它保存在面板设置中，不会 以明文对外提供。不要公开它、不要在即时通讯中转发， 也不要保存在仓库中。一旦泄露，请在 Telegram 和设置中更换密钥。

如果你关闭了密码登录又失去了 Telegram 访问权限，紧急 CLI 可以帮你登录：它能够重新启用密码登录。

接下来​