Skip to main content

邮件相关

然后如果要发送邮件验证code来激活账户。是不是需要手动配置一个 邮件收发服务器？

下面按你两个目标分别给出 Keycloak 26（你现在的版本）里最直接、最稳妥的做法，并补充“是否必须自建邮件服务器”的工程选项。

（1）关闭重复邮箱​

当前一个邮件可以注册多次，改成一个邮件只能注册一次，该怎么修改。

进入：Realm: Ordinis → Realm settings → Login

在这一页通常有几项开关（不同 UI 小版本位置可能略有差异，但都在 Login/Registration 相关区域）：

  1. User registration：开启/关闭注册（你既然允许注册，这个应为 ON）

    image-20260121233107697

  2. Duplicate emails / Duplicate emails allowed：把它设为 OFF

  3. （可选但强烈建议）Email as username / Registration email as username

    • 让用户名直接等于 email，避免用户填一堆随机用户名导致混乱

  4. （可选）Login with email：ON（允许用邮箱登录，体验更符合 SaaS）

    image-20260121233221629

注意：如果你当前已经有“重复邮箱的用户”存在，关闭 duplicate emails 可能会提示冲突或后续创建/更新时报错。需要先把重复邮箱的旧用户清理/合并/改邮箱。

用“配置即代码”的方式确认（你导出的 realm JSON 里）​

你导出的 Ordinis-realm.json 里通常会有类似字段（不同版本字段名可能略有差异）：

  • duplicateEmailsAllowed: false
  • registrationEmailAsUsername: true
  • loginWithEmailAllowed: true

你可以把这些写进你的 realm 配置并通过 import 保持一致性。

2) “发送邮件验证码激活账户”：Keycloak 支持，但默认是“邮件链接”不是“数字验证码”​

2.1 Keycloak 原生能力：Email Verification（发验证邮件）​

路径：Realm settings → Login

把 Verify email（或 Email verification）设为 ON。

效果：

  • 用户注册后，Keycloak 会发一封“验证邮箱”的邮件
  • 用户点击邮件中的链接完成激活（本质是一个 action token 链接）

这是最省事、最稳定、最符合 Keycloak 设计的激活方式。

2.2 你问的“发送邮件验证 code（数字码）”​

Keycloak 默认并不是给一个 6 位数 code，让用户手动输入；默认是点击链接验证。

如果你必须要“数字码 + 输入框”这种体验，一般有两种路：

  1. 自定义认证/Required Action（SPI 扩展）：实现“生成 code、存储、发送、校验”的完整逻辑（工程量明显更大）
  2. 引入第三方/自建服务：让你自己的服务发码并校验，然后再回到 Keycloak（通常会破坏 Keycloak 的统一流程，不是首选）

结论：MVP 阶段我建议先用 Keycloak 原生“邮件链接验证”，后续如果产品强需求再做“数字验证码”定制。

3) 是否需要“手动配置邮件收发服务器”？​

你不需要自己搭建一整套邮件服务器（Postfix/Dovecot）​

但你必须配置一个可用的 SMTP 发信渠道，否则 Keycloak 没法把验证邮件发出去。

Keycloak 的模式是：Keycloak 作为 SMTP 客户端，把邮件交给一个 SMTP 服务去投递。

你有三类选择（按推荐程度）：

  1. 第三方 SMTP 服务（推荐，生产常用）
    • SendGrid / Amazon SES / Mailgun / Postmark 等
    • 优点：投递率高、配置简单、可监控、不会进垃圾箱那么容易
  2. 已有企业邮箱/域名邮箱提供商的 SMTP
    • 例如你域名邮箱供应商提供的 SMTP（有的支持，有的限制严格）
  3. 自建 SMTP（不推荐，除非你很确定）
    • 需要处理：SPF/DKIM/DMARC、IP 信誉、反垃圾策略、退信处理
    • 成本高、坑多、投递率不稳定

Keycloak 里如何配置 SMTP​

路径：Realm settings → Email

填这些关键项：

  • Host / Port（SMTP 服务器与端口，常见 587 STARTTLS 或 465 SSL）
  • From（发件人地址，例如 no-reply@ordinis.dev）
  • Encryption（TLS/SSL）
  • Authentication（用户名密码或 API key）
  • 配完后点 Test connection / Test email（测试发信）

推荐你现在的最小落地组合（MVP 最稳）​

  1. Realm settings → Login：
    • Duplicate emails allowed = OFF
    • Verify email = ON
    • （可选）Registration email as username = ON
  2. Realm settings → Email：
    • 配一个第三方 SMTP（SendGrid/SES 等）
  3. 用无痕窗口走一遍：
    • 注册 → 收到验证邮件 → 点击链接激活 → 登录成功

如果你把你现在 Admin Console 里 Login 页和 Email 页的截图贴一下，或把你准备使用的 SMTP 服务商（SendGrid/SES/企业邮箱等）告诉我，我可以给你一份逐字段填写模板（包括端口、加密方式、From 地址建议、以及避免进垃圾箱的最小 DNS 记录：SPF/DKIM/DMARC）。