打开 Demo
登录认证决定用户如何进入平台：登录与注册方式、邮箱验证、Turnstile 人机验证、OIDC / OAuth2 身份源和登录安全策略。

使用入口#

打开 管理端 → 登录认证。页面分为五组，每组都有独立的保存按钮：

  • 登录页面
  • 登录与注册
  • 人机验证
  • 绑定与验证
  • 登录安全

OIDC / OAuth2 身份源表格位于“登录与注册”内，只有开启第三方登录后才会显示。

配置在用户下次登录或注册时生效。关闭某种登录方式前，先确认至少有一个管理员还能登录。

DEEIX Chat 管理端登录认证

控制登录与注册方式#

  1. 打开登录与注册。
  2. 切换需要的方式。
  3. 点击保存。
开关作用
邮箱登录允许用户使用邮箱和密码登录。
用户名登录允许用户使用用户名和密码登录。
邮箱注册允许用户通过邮箱创建账号。
重置密码允许用户在登录页重置密码，需先开启邮箱验证。
第三方登录开启并展示已配置的 OIDC / OAuth2 身份源。

这些开关互相约束：

  • 只有邮箱登录开启时才能开启邮箱注册。关闭邮箱登录会同时关闭邮箱注册和注册人机验证。
  • 只有开启邮箱验证时才能开启重置密码。关闭邮箱验证会同时关闭重置密码。
  • 同时关闭用户名登录和邮箱登录时，必须已开启第三方登录且至少一个管理员绑定了身份源，否则操作会被拒绝并提示无法关闭登录方式。

设置默认跳转路径#

  1. 打开登录页面。
  2. 在默认跳转路径中填写路径。
  3. 点击保存。

用户访问 /login 且没有 next 参数时，登录成功后会跳转到该路径。路径必须是站内路径，以单个 / 开头，例如 /chat。填写 https://example.com 或 //example.com 会被拒绝，提示默认跳转路径必须是站内路径，例如 /chat。

配置邮箱验证与 SMTP#

  1. 打开绑定与验证。
  2. 开启开启邮箱验证，SMTP 字段随即展开。
  3. 填写 SMTP 主机、SMTP 端口、SMTP 用户名和 SMTP 密码。
  4. 可选填写发件人。
  5. 点击保存。
字段说明
SMTP 主机发送注册验证码的服务地址。
SMTP 端口服务端口，常见为 465 或 587，必须是 1–65535 之间的整数。
SMTP 用户名登录账号，通常为完整邮箱地址。
SMTP 密码登录密码或应用专用密码，保存后不回显。
发件人验证码邮件的发件人，留空使用 SMTP 用户名。

开启邮箱验证后，只要必填 SMTP 字段为空或端口越界，保存就会失败：

  • 开启邮箱验证后，需要填写 SMTP 主机、SMTP 端口、SMTP 用户名、SMTP 密码。
  • SMTP 端口必须是 1-65535 之间的整数。

注册邮箱策略#

字段行为
注册域名白名单允许注册的邮箱域名，留空表示不限制，每行一个域名。
禁止邮箱别名禁止使用 + 别名邮箱注册。
同邮箱自动绑定第三方身份返回的邮箱与本地账号一致，且该身份源的邮箱验证字段（默认 email_verified）为 true 时，才自动绑定到已有账号。

启用注册人机验证#

注册人机验证基于 Cloudflare Turnstile，只作用于邮箱注册，不影响 OIDC / OAuth2 登录。

  1. 先开启邮箱注册并保存。
  2. 打开人机验证。
  3. 开启注册人机验证。
  4. 填写 Turnstile Site Key 和 Turnstile Secret Key。
  5. 点击保存。

Secret Key 保存后不回显，编辑时留空表示沿用原密钥。前置条件不满足时保存会失败：

  • 请先开启邮箱注册，再启用 Turnstile 人机验证。
  • 开启 Turnstile 人机验证后，需要填写 Turnstile Site Key、Turnstile Secret Key。

账号与密码规则#

用户注册、重置密码或管理员创建账号时，平台会执行以下规则。这些规则不可在登录认证页修改。

项目规则
密码长度8–128 个字符。
密码内容不能是纯数字。
用户名长度3–16 个字符。
用户名内容小写字母、数字、_ 和 -；首尾必须是字母或数字；不能包含 @。
保留用户名admin、root、system、support、settings 等会被拒绝。

新增 OIDC / OAuth2 身份源#

  1. 在登录与注册中开启第三方登录并保存。
  2. 点击新增身份源。
  3. 选择预置项（Apple、GitHub、Google、Discord、Facebook、Hugging Face、Linux Do、Microsoft、Twitter (X)、Vercel），或选择自定义 OIDC / 自定义 OAuth2。
  4. 填写字段；OIDC 类型需要选择 Issuer URL 或 Discovery URL。
  5. 复制回调地址并填入身份源提供方的控制台。
  6. 设置 Scopes，必要时在高级设置中调整字段映射。
  7. 点击保存。

回调地址#

弹窗会显示需要身份源放行的回调地址。平台提供服务器回调桥接时，主字段为服务器回调地址（推荐），格式为 <base>/<身份源标识>/callback，同时显示旧版 Web 回调地址（即将废弃），格式为 <origin>/auth/callback?provider=<身份源标识>。未提供桥接时只显示旧版地址，标签为回调地址。点击复制回调地址即可复制。

身份源字段#

字段说明
类型OIDC 或 OAuth2，必填。
名称展示名称，必填。回调地址中的标识由名称推导，除非已有标识。
登录控制允许登录平台账号，默认开启。
注册控制允许自动创建账号，仅在登录控制开启时可用。
Logo URL可选，显示在身份源旁。
Client ID提供方分配的客户端标识，必填。
Client Secret提供方分配的客户端密钥。新建时必填；保存后不回显，编辑时留空表示沿用原密钥。
OIDC 地址OIDC 类型使用，选择 Issuer URL 或 Discovery URL，必填。
Auth URL / Token URL / UserInfo URLOAuth2 类型使用，三项均必填。
Scopes请求的授权范围。自定义 OIDC 默认 openid profile email，自定义 OAuth2 默认 profile email。
来源字段 → 系统字段将提供方返回字段映射到用户 ID、邮箱、邮箱验证状态、昵称和头像。默认分别为 sub、email、email_verified、name、picture。

管理身份源#

身份源表格显示名称、类型、登录控制、注册控制和 Client ID。

  • 可直接在表格中切换登录控制和注册控制。登录控制未开启时不能开启注册控制，否则提示请先开启登录控制。
  • 拖动排序手柄可调整顺序，顺序会自动保存。
  • 点击名称或铅笔图标进入编辑；点击垃圾桶图标删除。
  • 删除身份源会解绑所有使用它的账号。若存在账号仅依赖该身份源登录，平台会显示强制删除身份源。强制删除后，这些账号将无法继续通过该身份源登录。删除前先确认这些用户已设置密码或绑定其他身份源。

设置登录安全#

  1. 打开登录安全。
  2. 按需填写各项。
  3. 点击保存。
字段默认值说明
访问令牌有效期24Access Token 有效期，单位小时，范围 1–168。
登录保持时间720Refresh Token 与会话保持时间，单位小时，范围 1–8760。
失败锁定阈值5同一账号连续登录失败达到该次数后进入锁定，填 0 表示关闭锁定。
锁定时长15登录失败触发锁定后的持续时间，单位分钟，填 0 表示关闭锁定。
平台限流关闭开启后由平台返回 HTTP 429。交由 Traefik、网关或其他外层组件限流时可关闭。
用户接口限流60登录后用户接口的基础每分钟请求上限；平台限流关闭时不生效。
公开鉴权限流30公开登录、注册、刷新令牌等接口的基础每分钟请求上限；平台限流关闭时不生效。

查看安全事件#

登录、双因素、密码等安全事件记录在管理端日志中。

  1. 打开 管理端 → 日志。
  2. 选择认证安全页签。
  3. 使用搜索框、结果筛选和排序菜单缩小范围。
  4. 点击任意一行查看认证日志详情。
列含义
ID事件记录 ID。
用户操作者的昵称、用户名或用户 ID。
事件事件类型。
结果成功、失败或阻断。
原因产生该结果的原因（如有）。
IP客户端 IP 地址。
时间事件发生时间。
请求 ID请求关联 ID。

搜索匹配用户 ID 或事件类型。排序支持发生时间（从新到旧、从旧到新）和 ID（从新到旧、从旧到新）。清理日志可按截止日期删除认证安全历史，但不会改变当前会话和凭据。

配置项对照#

以下键均属于 auth 命名空间。

分组配置键
登录页面auth.login_default_next_path
登录与注册auth.email_login_enabled、auth.username_login_enabled、auth.email_registration_enabled、auth.password_reset_enabled、auth.third_party_login_enabled
人机验证auth.turnstile_registration_enabled、auth.turnstile_site_key、auth.turnstile_secret_key
绑定与验证auth.email_verification_enabled、auth.smtp_host、auth.smtp_port、auth.smtp_username、auth.smtp_password、auth.smtp_from、auth.email_registration_allowed_domains、auth.email_registration_block_plus_alias、auth.auto_link_verified_email
登录安全auth.token_ttl_hours、auth.refresh_token_ttl_hours、auth.login_max_failures、auth.login_lock_minutes、auth.rate_limit_enabled、auth.rate_limit_rpm、auth.public_auth_rate_limit_rpm

OIDC / OAuth2 身份源以独立记录保存，不是单个 auth.* 键。每条记录各自维护登录控制和注册控制。

常见问题#

  • 保存时提示跳转路径错误。 默认跳转路径必须是站内路径，例如 /chat，去掉协议和域名。
  • 登录方式开关被拒绝。 只保留第三方登录前，需要先让管理员绑定可用身份源，再关闭用户名登录和邮箱登录。
  • 邮箱验证无法保存。 补全 SMTP 主机、端口、用户名和密码，端口需在 1–65535 之间。
  • Turnstile 无法保存。 先开启邮箱注册，再填写 Site Key 和 Secret Key。
  • 第三方登录回调报错。 身份源控制台中登记的回调地址必须与弹窗显示的地址完全一致，包括身份源标识。
  • 保存时提示登录状态已失效。 管理端会话已过期，重新登录后再操作。

相关页面#