如何为自托管 sim 配置事务邮件提供商让工作区邀请与验证邮件真正发出
【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000+ builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim
自托管 Sim 会发送工作区邀请、邮箱验证、密码重置和各类通知，这些邮件全部依赖你在部署环境中配置的事务邮件提供商。问题在于：一个提供商都没配的时候，不会有任何报错——mailer 只会打印一行包含收件人、主题和发件人的日志然后报告发送成功，实际什么都没发，而且消息正文不落日志，这封漏掉的邮件无法从日志里找回。在生产部署上，这意味着工作区邀请会悄无声息地永远到不了。
本文的目标就是让邀请和验证邮件真正发出去：选择一个邮件提供商、写入正确的环境变量、把凭据放进 Secret，最后通过一次真实邀请验证日志。适用于 Docker Compose 或 Kubernetes（Helm）部署的自托管 Sim，配置内容参考 邮件配置文档。
在邮件配通之前，不要设置EMAIL_VERIFICATION_ENABLED=true。按 认证文档的说明，该开关要求邮箱验证通过才能登录，没有邮件提供商时 mailer 只是空转，结果就是所有用户永远无法验证、永远无法登录。
提供商如何选择：固定顺序的 failover
Sim 没有"启用哪个提供商"的开关变量。所有设置了变量的提供商都会激活，mailer 按固定顺序尝试，只有上一个失败才落到下一个：
Resend → AWS SES → SMTP → Azure Communication Services → Gmail所以排在前面的提供商承接正常流量，其余配置都自动充当兜底。只配一个是最简单的情况；配两个会多一份 fallback 路径，代价是偶发情况下邮件可能从另一个发件地址发出。下面按常见程度给出各提供商的配置，选一条主路径即可，其余可留作可选分支。
公共配置：发件人地址
无论选哪个提供商，都需要先定发件人。这几个变量各提供商共用：
| 变量 | 说明 |
|---|---|
FROM_EMAIL_ADDRESS | 发件地址，例如Sim <noreply@example.com> |
EMAIL_DOMAIN | 未设置FROM_EMAIL_ADDRESS时的兜底域——以noreply@EMAIL_DOMAIN发送 |
EMAIL_VERIFICATION_ENABLED | 设为true后注册必须完成邮箱验证 |
文档把发件地址不匹配列为邮件被丢弃的头号原因：发件地址必须是你的提供商已授权可发送的地址，否则邮件可能被提供商接收后，在下游被静默丢弃或判为垃圾邮件。
主路径一：Resend（没有现成邮件基础设施时最简单）
RESEND_API_KEY=re_... FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"其中re_...换成你在 Resend 平台拿到的 API key，yourdomain.com换成你自己的域名。上线前要在 Resend 控制台完成发送域名验证，并添加它给出的 DNS 记录。
主路径二：SMTP（已有任意中继可用）
SMTP 路径兼容任意中继——Postfix、SendGrid、Mailgun、Google Workspace SMTP relay，本地测试可以用 MailHog：
SMTP_HOST=smtp.example.com SMTP_PORT=587 # 465 implicit TLS, 587 STARTTLS, 25 plain SMTP_USER=apikey # omit for unauthenticated relays SMTP_PASS=... # omit for unauthenticated relays # SMTP_SECURE=true # only for implicit TLS. Leave unset on 587 — it is # automatic on 465, and forcing it on a STARTTLS port fails to connect # SMTP_EHLO_NAME=mail.yourdomain.com # only if the relay expects an identity other # than the domain Sim is served from FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"几个适用条件：
SMTP_PORT按你的中继协议选：465 是 implicit TLS，587 是 STARTTLS，25 是明文。SMTP_SECURE只在 implicit TLS 时设置。587 端口上留空——465 会自动启用，而在 STARTTLS 端口强行开启会导致连接失败。SMTP_EHLO_NAME几乎用不上：Sim 会用自身服务域名（由NEXT_PUBLIC_APP_URL推导）向中继打招呼。Kubernetes 上 pod 主机名不含点号，若不这样推导，底层邮件库会退化成[127.0.0.1]，严格中继会直接拒绝这个问候。- 走 Google Workspace 但没有服务账号时，用中继而不是 Gmail API：
SMTP_HOST=smtp-relay.gmail.com、SMTP_PORT=587。需要在中继侧把你的部署出口 IP 加入 Workspace 管理控制台的允许列表，不需要服务账号和域名级委托；除非无法固定出口 IP，文档建议优先这条路径而非 Gmail API。
可选分支：AWS SES、Azure ACS、Gmail API
AWS SES：
AWS_SES_REGION=us-east-1 FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"凭据走标准 AWS provider chain（环境变量、shared config、ECS/EKS task role（IRSA）、EC2 实例 profile 或 SSO）；EKS 上给 IRSA 角色加ses:SendEmail和ses:SendRawEmail即可，一个 key 都不用配。注意：新 SES 账号处于sandbox状态，只能发给已验证的地址，团队邀请会失败，需要先申请 production access，同时完成发送域名验证和 DKIM 配置。
Azure Communication Services：
AZURE_ACS_CONNECTION_STRING=endpoint=https://...;accesskey=... FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"先开通 Email Communication Service、连接已验证的域名，再把它关联到 Communication Service 资源；发件地址必须属于已关联的域名。
Gmail API（GCP 没有第一方事务邮件服务，Google 原生路径就是 Gmail API + Workspace 发件人）：
GMAIL_CREDENTIALS_JSON='{"type":"service_account",...}' GMAIL_SENDER=noreply@yourdomain.com FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"步骤：创建服务账号并下载 JSON key；在 Workspace 管理控制台Security → Access and data control → API controls → Domain-wide delegation → Add new中登记服务账号的client_id，scope 为https://www.googleapis.com/auth/gmail.send；GMAIL_SENDER设为服务账号所冒充的 Workspace 用户。两个限制：FROM_EMAIL_ADDRESS必须与GMAIL_SENDER或其已注册别名一致，Gmail 会改写无法识别的 From 地址，不匹配时邮件"发送成功"但显示为错误发件人；Gmail 每用户每天约 2,000 封的上限对邀请和验证场景足够，超出则换成 Workspace SMTP 中继或 Resend，都是纯配置改动。粘贴 JSON 到 values 文件时保持单行：
jq -c . service-account-key.jsonKubernetes 上把凭据放进 Secret
邮件凭据是 secret，应经 Secret 存储提供而不是明文 values。values.yaml里这样写：
app: env: FROM_EMAIL_ADDRESS: "Sim <noreply@yourdomain.com>" RESEND_API_KEY: "re_..." # via External Secrets or an existing Secret在 default 和 External Secrets 两种模式下，app.env的 key 会写入 chart 管理的 Secret 并经envFrom挂载，不会出现在 pod spec 里。但提交进values.yaml的 secret 依然是你 git 历史里的 secret——更稳妥的做法是走 External Secrets 或预先创建的 Secret（app.secrets.existingSecret，见 Kubernetes 文档）。另外，app.env下的 key 同时会落到 realtime pod 上——chart 把它们写入一个两个 Deployment 共享的 Secret。
验证：发一次真实邀请并看 mailer 日志
文档给出的验证方式是端到端的：从 workspace 设置里邀请一个用户，然后看应用日志。
先确保日志级别能看到 mailer 的那行输出。生产构建下 logger 默认ERROR，此时什么都不会记——Verify 文档的说明是把LOG_LEVEL提到INFO（变量名只接受大写）才能看到 no-op 那一行。
Kubernetes 上：
kubectl logs -n simstudio -l app.kubernetes.io/component=app --tail=100 | grep -i mailDocker Compose 部署等价地查看应用容器日志（服务名simstudio，与docker compose -f docker-compose.prod.yml ps中列出的一致）：
docker compose -f docker-compose.prod.yml logs --tail=100 simstudio | grep -i mail按 Email 文档的对照表判断结果：
| 看到的日志 | 含义 |
|---|---|
| 只有一行含收件人、主题、发件人的日志，没有投递 | 没有配置提供商——mailer 空转了 |
| 提供商 API 报错 | 凭据或发件地址问题，错误信息会指出是哪一个 |
| 显示成功但收件人没收到 | 邮件已交给提供商——去提供商控制台查投递，再依次排查垃圾邮件过滤、SPF、DKIM |
"一行日志 + 报告成功 + 实际未投递"是最容易误判的情况：它不代表配置成功，恰恰说明没有任何提供商被激活。
常见故障对照
- "Delegation denied" /
unauthorized_client（Gmail）：域名级委托条目缺失、client ID 或 scope 错误。对照服务账号 JSON 里的client_id重查管理控制台条目，确认 scope 恰好是https://www.googleapis.com/auth/gmail.send。 - From 地址报错被拒收：发件人未在提供商已验证域名上授权。把
FROM_EMAIL_ADDRESS与已验证域名对齐（Gmail 路径还要与GMAIL_SENDER对齐）。 - SES 拒绝收件人：账号仍在 sandbox，申请 production access。
- 邮件进了垃圾箱：为你的发送域名配置 SPF、DKIM、DMARC——这是你 DNS 上的事，不在 Sim 侧。
- SMTP 在问候阶段报
421-4.7.0 Try again later, closing connection. (EHLO)：中继拒绝的是客户端的自我标识方式，不是凭据或 IP 白名单。严格中继（Google Workspace 是其中之一）不接受非完全限定域名的问候。Sim 已改为用服务域名问候，理论上不应出现；若仍出现，把SMTP_EHLO_NAME设为中继接受的一个带点主机名。旧版本在 Kubernetes 上总是以[127.0.0.1]问候——文档的建议是升级而不是绕过。
配通之后
验证表格确认邀请真正投递后，再做两件事：一是可以安全地设置EMAIL_VERIFICATION_ENABLED=true要求注册时完成邮箱验证（认证文档明确要求先确保邮件可用）；二是如需要兜底路径，再配置第二个提供商——顺序表中靠前的承接流量，后一个自动 failover。整套安装的其他子系统检查可继续走 Verify Your Install清单，其中第 9 步"从 workspace 设置邀请一位队友"正是对邮件链路的复验。
【免费下载链接】simSim is the collaborative workspace to build, deploy, and monitor AI agents and workflows. Used by 100,000+ builders.项目地址: https://gitcode.com/GitHub_Trending/sim16/sim
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
