Appearance
邮件防伪三记录（SPF / DKIM / DMARC）与 realm SMTP 配置
读者：品牌产品线运营者（人类；全部动作在 DNS 面板与 Keycloak 管理台，无代码）。 定位：让品牌 realm 用
noreply@<品牌域>发出的注册验证 / 找回密码邮件不进垃圾箱。是品牌自托管接入标准 §3.1「发布 SPF / DKIM / DMARC」一行提示与基座侧 realm 上线指引 §3.5（docs/ops/realm-topology-rollout-guide.md，基座侧文档）的展开 how-to。 状态基准：2026-09-14。契约面：无（纯 DNS + Keycloak 管理台操作）。
0. 三条记录各是什么（大白话）
三条都是域名 DNS 里的 TXT 文本记录，作用是让收件方（Gmail / Outlook / QQ 邮箱……）相信「以 @<品牌域> 名义发来的这封信不是伪造的」：
| 记录 | 大白话含义 |
|---|---|
| SPF | 一份发件服务器白名单：「凡 <品牌域> 名义发出的邮件，只允许从这几台服务器发」。不在名单上的服务器冒充你发信，直接判假 |
| DKIM | 一把防伪签名：发出的每封信带加密签名，DNS 里放对应公钥。收件方验签确认信没被篡改、确实出自你授权的服务 |
| DMARC | 一条处置规矩：「SPF / DKIM 都没过时，扔垃圾箱还是直接拒收」，并让收件方定期给你发报告，你能看到有多少冒充你域名的信 |
不配的后果：注册验证邮件、找回密码邮件进垃圾箱或被直接拒收——用户「收不到验证码」类的工单几乎都源出于此。
1. 时机：为什么不能一次配完
DKIM 的公钥由你将来选定的「发信服务」生成——服务没选，公钥就不存在。所以完整三记录的配置时点 = 给品牌 realm 配 SMTP 的那一天，两边必须配套。分两个阶段：
- 阶段 A（现在，可选）：声明「此域名暂不发信」的兜底记录，防别人冒充你的域名发钓鱼邮件；
- 阶段 B（配 realm SMTP 时，必须）：正式三记录 + Keycloak 回填。
2. 阶段 A：暂不发信兜底（可选）
在域名商的 DNS 解析管理页添加两条 TXT 记录：
| 类型 | 主机记录 | 记录值 | 作用 |
|---|---|---|---|
| TXT | @ | v=spf1 -all | 没有任何服务器被授权用此域名发信 |
| TXT | _dmarc | v=DMARC1; p=reject; | 验证不过的信直接拒收 |
代价：进入阶段 B 时必须替换这两条（见下），忘了替换会让新发信服务的邮件全部被拒。
3. 阶段 B：正式配置五步（配 realm SMTP 当天做）
- 选一个邮件发送服务（Resend / SendGrid / 阿里云邮件推送等；用户在海外为主就选海外服务）。
- 在该服务控制台绑定域名
<品牌域>——服务商会直接给出 2~4 条现成 DNS 记录（SPF、DKIM 公钥、域名归属验证）。这些值由服务商生成，不需要也不应该自己发明。 - 回 DNS 面板照抄加上这些记录；同时删掉/替换阶段 A 的两条兜底。
- 加一条宽松起步的 DMARC：主机记录
_dmarc，值v=DMARC1; p=none; rua=mailto:<你的常用邮箱>——先只观察不拦截；跑一两周确认报告正常后，把p=none收紧为p=quarantine（扔垃圾箱）或p=reject（拒收）。 - 回填 Keycloak（见 §4）。
4. Keycloak 侧回填位置
基座 Keycloak 管理台 https://<基座域名>/auth/admin/（基座 owner 开放的管理入口）→ 对应品牌 realm → Realm Settings → Email：
- host / port / 账号 / 密码：按发信服务提供的 SMTP 参数填；
- from：
noreply@<品牌域>。
每个品牌 realm 独立配置发件人（不同品牌线互不影响）。
两个常见澄清：
noreply@<品牌域>不需要真的创建一个邮箱——它只是「寄件人署名」；- DMARC 报告邮箱（
rua=）要填一个你真实收得到的邮箱（报告量可能不小，可后续换专用信箱或聚合服务）。
5. 验证
- 连通性：Keycloak 管理台该 realm 的 Email 设置页有测试入口（给管理员邮箱发测试信）——先确认 SMTP 参数本身正确。
- 看真实信头：收到测试信后在邮箱里「显示原文 / Show original」，
Authentication-Results一行应同时含spf=pass与dkim=pass，且dmarc=pass。 - 外部复查（可选）：MXToolbox / dmarcian 等在线工具输入域名复查三记录解析正确。
6. 坑速查
| 坑 | 后果 | 处置 |
|---|---|---|
| 只配 SPF 没配 DKIM（或反过来） | 大邮箱仍判可疑 | 两条都是服务商给的就都加上；DMARC 验的是「至少一条过 + 域对齐」 |
DMARC 直接 p=reject 起步 | 配置期误杀正常邮件 | p=none 起步观察，再逐步收紧 |
| 阶段 A 兜底没删 | 新发信服务的邮件全部被拒（v=spf1 -all 意为「谁都不许发」） | 阶段 B 第 3 步是替换不是叠加 |
| 换发信服务没改记录 | 旧 DKIM 公钥验不了新服务的签名，全部失效 | 换服务 = 重跑阶段 B 第 2~4 步 |
给 www 子域也配了一套 | 白费功夫 | SPF / DKIM / DMARC 配在 apex（@）即可，www 只做 301 |
| DNS 生效了但 KC 没回填 / 回填了但 DNS 没生效 | 各自独立失败 | §5 的三步验证分别覆盖两条链路 |