补充文档转换、上下文检索与应用发信指南

2026-09-16 18:26:04 +00:00
parent a50c66960d
commit 38530404a6
6 changed files with 247 additions and 4 deletions
@@ -0,0 +1,74 @@
+---
+title: SMTP relay 应用发信指南
+lifecycle: unknown
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# SMTP relay
+
+为集群应用提供统一出站邮件入口：应用通过集群内 SMTP 连接 relay，
+relay 再使用 STARTTLS 与 XOAUTH2 向 Microsoft 365 提交邮件。
+本页依据 homelab-infra `apps/smtp-relay/README.md` 与 Service/Deployment 配置整理，
+本轮没有连接 relay、发送邮件或查询邮箱。
+
+## 应用接入参数
+
+| 参数 | 已记录值 |
+|---|---|
+| SMTP host | `smtp-relay.smtp-relay.svc.cluster.local` |
+| SMTP port | `25` |
+| 应用到 relay 的 TLS | 此内部链路按明文 SMTP 配置 |
+| 应用到 relay 的认证 | 不提供用户名或密码 |
+| From / envelope sender | `[email protected]` |
+| relay 的上游 | `smtp.office365.com:587`，STARTTLS + XOAUTH2 |
+
+这里的无认证入口限于既定内部使用路径，不能直接把它暴露为外部发信入口。
+其他发件身份需要对应的 Send As 授权，不能只在应用中随意改 From。
+应用只需要 relay 参数，不需要读取或持有 Microsoft 365 refresh token。
+
+## 发送一封接入测试邮件
+
+下面在已能访问集群 Service 的应用环境中使用 Python 标准库。
+将 `SMTP_TEST_RECIPIENT` 设置为自己控制的收件地址；执行会真实发送邮件，应先得到该次发信授权。
+这份示例本轮未执行。
+
+```python
+import os
+import smtplib
+from email.message import EmailMessage
+
+recipient = os.environ["SMTP_TEST_RECIPIENT"]
+sender = "[email protected]"
+message = EmailMessage()
+message["From"] = sender
+message["To"] = recipient
+message["Subject"] = "Homelab SMTP relay test"
+message.set_content("SMTP relay integration test.")
+with smtplib.SMTP("smtp-relay.smtp-relay.svc.cluster.local", 25, timeout=30) as smtp:
+    refused = smtp.send_message(message, from_addr=sender, to_addrs=[recipient])
+    if refused:
+        raise SystemExit("收件人被拒绝，请检查 relay 状态")
+```
+
+客户端提交成功只表示 relay 接收，不保证最终送达。
+维护者随后结合 relay 投递日志与收件箱确认完整链路；也检查垃圾邮件文件夹。
+日志中的上游接收结果仍不能替代收件人侧确认。
+
+## 失败时如何区分
+
+- 连接超时或域名失败：检查集群 DNS、Service 与应用网络范围。
+- relay 接收但不送达：检查投递队列、上游连接和认证，而不是给应用配置上游密码。
+- `535 5.7.3`：源码提示检查 OAuth 身份是否为实际 sender，以及 token 是否需要重新初始化。
+- `5.7.60`：检查 From、envelope sender 与 Microsoft 365 的发信授权是否匹配。
+
+消费者接入不能通过重跑完整 Terraform、部署或 OAuth 初始化流程来试错。
+refresh token 持久化在 `smtp-relay-tokens` PVC，SASL 层负责更新；
+它是可变运行数据，不是可复制进 wiki 的配置。
+源码的 device-code 流程使用 public client，维护说明明确 `CLIENT_SECRET` 留空；
+不要照抄同一旧 README 中与之不一致的“创建 client secret”注释。
+
+初始化、重新授权、DKIM 与恢复入口为 `apps/smtp-relay/README.md`。
+其中 DKIM 等日期属于历史记录，本文不将其升级为新一次验证。
+依赖为 Kubernetes/DNS、token PVC、Microsoft 365 邮箱与授权、上游网络及域名邮件配置。