Tabby 邮件投递配置指南：通过 SMTP 服务启用密码重置、邀请与通知邮件

Tabby 是一个可自托管的 AI 编程助手，其企业版（EE）服务内置了一套完整的邮件投递功能，用于发送密码重置、用户邀请、注册欢迎等事务性邮件。本指南以 website/docs/administration/smtp/index.md 为骨架，结合仓库中邮件服务的前后端实现源码，系统讲解如何在 Tabby 管理后台配置 SMTP 服务器（含 Amazon SES 与 SendGrid、Mailgun、Resend 等第三方提供商），以及如何发送测试邮件验证链路是否打通。读完本文，你将掌握 Tabby 邮件功能的完整配置流程、每个配置项的语义与取值范围，以及邮件发送在源码层面的工作原理，便于独立完成部署后的邮件联调与排障。

一、为什么 Tabby 需要 SMTP 邮件投递

Tabby 本身不内置邮件服务器，而是通过你所选择的 SMTP 服务器来发送邮件。以下功能必须依赖 SMTP 配置才能正常工作：

• 密码重置：用户忘记密码时，通过邮件发送重置链接与验证码；
• 邮件通知：例如新用户注册成功后的欢迎邮件；
• 用户邀请：管理员邀请成员加入 Tabby 服务器时发送邀请邮件；
• 测试邮件：管理员在配置完成后验证 SMTP 链路是否可用。

在邮件服务实现中，这四类邮件分别对应四个独立方法（见 ee/tabby-webserver/src/service/email/mod.rs）：

方法	邮件主题	触发场景
send_password_reset	Reset your Tabby account password	忘记密码、请求重置
send_invitation	You've been invited to join a Tabby server!	管理员邀请用户
send_signup	Welcome to Tabby!	用户注册成功
send_test	Your mail server is ready to go!	管理后台发送测试邮件

这些邮件的 HTML 模板位于 ee/tabby-webserver/src/service/email/templates.rs，邮件正文中的链接会使用管理后台配置的 external_url（外部访问地址）拼接生成。

二、Mail Delivery 配置页面与字段详解

在 Tabby 管理后台的 Mail Delivery 页面中，可以完成 SMTP 服务器的全部配置。前端表单实现在 ee/tabby-ui/app/(dashboard)/settings/(integrations)/mail/components/mail-form.tsx/settings/(integrations)/mail/components/mail-form.tsx)，页面字段与后端 EmailSettingInput（见 ee/tabby-schema/src/schema/email.rs）一一对应：

表单字段	必填	说明	示例
SMTP Server Host	是	SMTP 服务器主机名	smtp.gmail.com、email-smtp.us-east-1.amazonaws.com
SMTP Server Port	是	SMTP 端口，后端校验范围为 1~65535	25、587、465、2587
From	是	发件人地址，必须是合法邮箱（后端以 email 格式校验）	[e-mail]
SMTP Username	是	SMTP 认证用户名（通常是邮箱地址或 IAM 用户）	[e-mail]
SMTP Password	是（首次配置）	SMTP 认证密码；更新时留空表示沿用已有密码	由提供商签发
Authentication Method	是	认证方式，可选 NONE / PLAIN / LOGIN	一般选择 PLAIN
Encryption	是	加密方式，可选 NONE / SSL/TLS / STARTTLS	见下文端口搭配建议

其中 Authentication Method 与 Encryption 在后端被定义为两个枚举类型：

• Encryption：StartTls / SslTls / None；
• AuthMethod：None / Plain / Login。

需要留意的是加密方式与端口的搭配：SslTls 对应隐式 TLS（例如 465 端口），StartTls 对应显式升级（例如 587 端口），None 表示明文传输（例如本地中继或 25 端口）。由于明文传输会暴露邮件凭据，生产环境建议优先使用 SslTls 或 StartTls。

表单提交后，前端通过 GraphQL 变更 updateEmailSetting(input: EmailSettingInput!) 将配置写入后端；已保存的配置可以在同一页面修改（Update）或删除（Delete，删除会连同 SMTP 连接一并关闭）。在 GraphQL 层，email_setting 的读取与更新均要求管理员权限（check_admin），见 ee/tabby-schema/src/schema/mod.rs 中 email_setting 与 update_email_setting 两个解析器。

三、通过 Amazon SES 配置 SMTP

Amazon SES（Simple Email Service）是常用的邮件发送服务，其 SMTP 端点与凭据都可以直接填进 Tabby 的 Mail Delivery 表单。配置流程如下：

1. 创建并验证发件身份：按 Amazon SES 官方文档的指引，在 SES 控制台创建发件身份（域名或邮箱）并完成验证。只有验证通过的身份才能作为发件人；
2. 创建 SMTP 凭据：使用 AWS IAM（Identity and Access Management）创建具有 SES 发送权限的 IAM 用户，并生成对应的 SMTP 用户名与密码（SES 的 SMTP 凭据由 IAM 凭据派生而来）；
3. 填写 Tabby 配置：将 IAM 用户对应的 SMTP 用户名、密码，以及所选区域的 SMTP 端点填入 Mail Delivery 页面。以 us-east-1 区域为例，端点形如 email-smtp.us-east-1.amazonaws.com，常用端口为 587（STARTTLS）或 465（SSL/TLS），Encryption 选择 SSL/TLS 或 STARTTLS，Authentication Method 选择 PLAIN。

原文档中此场景配有 Amazon SES 配置界面的截图（见 website/docs/administration/smtp/ses.png），截图展示了在 Mail Delivery 页面中填写 SES 端点、端口、凭据与加密方式的界面形态。

四、配置其他 SMTP 提供商

除 Amazon SES 外，Tabby 兼容任何标准 SMTP 服务商，如 SendGrid、Mailgun、Resend 等。这类提供商通常会在各自控制台生成 SMTP 主机、端口、用户名和密码（或 API Key 形式的密码），只需按提供商文档找到对应 SMTP 端点信息，填入 Mail Delivery 页面的对应字段即可。

常见的端口选择参考：

• 587 + STARTTLS：大多数提供商（如 Gmail、SendGrid、Mailgun、Resend）推荐的主流组合；
• 465 + SSL/TLS：隐式 TLS 组合，部分提供商支持；
• 25：明文或本地中继场景，通常不建议用于公网发送。

配置完成后，同样需要指定 From 发件地址，该地址应与提供商已验证的身份一致，否则可能被服务商拒发或标记为垃圾邮件。

五、发送测试邮件验证链路

配置完成后，应立即验证邮件链路是否真正打通。操作方式为：在 Mail Delivery 页面的 Send Test Email To 字段中填写一个测试收件邮箱，点击 Send 按钮。若配置正确，收件人将收到一封主题为 "Your mail server is ready to go!" 的测试邮件（原文档配图见 website/docs/administration/smtp/test-email.png）。

测试邮件的实现路径非常直观：前端调用 GraphQL 变更发送请求后，后端执行 send_test，渲染测试模板并复用统一的 send_email_in_background 发送通道（见 ee/tabby-webserver/src/service/email/mod.rs）。仓库的单元测试也覆盖了这一链路——test_send_test_email 会启动一个内存测试 SMTP 服务器，调用 send_test 后断言收到的邮件主题包含 "ready to go"（见 ee/tabby-webserver/src/service/email/mod.rs 中的测试模块）。

如果发送失败，可重点排查以下几个方面：

• SMTP 凭据是否正确：用户名/密码错误会直接导致认证失败；
• Encryption 与端口是否匹配：STARTTLS 与 SSL/TLS 的握手方式不同，端口选错会导致 TLS 协商失败；
• From 地址是否已验证：很多提供商要求发件身份先通过验证；
• 网络可达性：自托管环境下需确保服务器能访问目标 SMTP 端点（出方向 25/465/587 端口未被防火墙拦截）。

六、源码视角：SMTP 配置的存储与发送原理

为了让读者对邮件功能有更深理解，这里补充配置存储与邮件发送在源码层面的关键设计。

配置存储：SMTP 配置以单行记录的形式持久化在 email_setting 表中，其数据结构在 ee/tabby-db/src/email_setting.rs 中定义，包含 smtp_username、smtp_password、smtp_server、smtp_port、from_address、encryption、auth_method 七个字段。从数据库迁移历史可以看到字段的演进：最初的 email_setting 表只有用户名、密码、服务器三个字段（见 0007_email-setting.up.sql），随后加入了 from_address、encryption、auth_method（见 0011_new-email-settings.up.sql），再补充 smtp_port（见 0013_add-smtp-port.up.sql）。一个值得注意的细节是：更新配置时如果密码字段为空，数据库层会保留原有密码（update_email_setting 中的分支逻辑），因此前端"留空密码"不会覆盖已保存的密码。

发送链路：邮件发送基于 Rust 生态的 lettre 库实现。服务启动时会根据已保存的配置初始化 SMTP 连接（new_email_service → reset_smtp_connection），之后每封邮件都通过 send_email_in_background 异步发送，避免阻塞主流程；若尚未配置 SMTP，任何发送请求都会返回 EmailNotConfigured 错误。加密方式在 make_smtp_builder 中映射为三类传输模式：StartTls 使用 Tls::Required、SslTls 使用 Tls::Wrapper、None 则不带 TLS；认证方式在 auth_mechanism 中映射为 Plain、Login 或空（不认证），见 ee/tabby-webserver/src/service/email/mod.rs。

自定义 CA 证书：对于使用内网或私有 SMTP 服务器（自签证书）的场景，Tabby 支持通过环境变量 TABBY_WEBSERVER_EMAIL_CERT 指定 PEM 格式的 CA 证书，该证书会被添加到 TLS 参数的可信根证书列表中（见 make_smtp_builder 中读取 TABBY_WEBSERVER_EMAIL_CERT 的代码段）。这是企业内网部署邮件服务时的实用能力。

七、配置后的联动行为

SMTP 配置并不是保存后立即对所有历史场景生效，理解其联动行为有助于排障：

• 更新配置即重连：每次保存配置，后端都会用新凭据重建 SMTP 连接（update_setting 中调用 reset_smtp_connection），因此修改后无需重启服务；
• 删除配置即关闭：删除 SMTP 配置会同时关闭已建立的连接（delete_setting → shutdown_smtp_connection），此后邮件发送将报"未配置"错误；
• 读取异常自动清理：如果数据库中保存的加密/认证方式无法解析（例如手工改库导致脏数据），读取配置时会自动删除该记录并提示重新配置（read_setting 中的容错逻辑），避免服务启动失败。

八、常见问题速查

现象	可能原因	处理建议
测试邮件收不到	SMTP 凭据错误 / 端口与加密不匹配 / From 未验证	核对凭据与端口加密组合，检查 From 身份验证状态
发送时报"未配置"错误	从未保存过 SMTP 配置，或配置已被删除	回到 Mail Delivery 页面完整填写并保存配置
使用内网 SMTP 报证书错误	自签证书不受信任	通过 TABBY_WEBSERVER_EMAIL_CERT 环境变量注入 PEM 格式 CA 证书
更新配置时提示密码必填	首次配置且密码为空	首次配置必须填写 SMTP Password；后续更新可留空以沿用旧密码
邮件被标记为垃圾邮件	From 身份未验证或域名信誉不佳	验证发件身份，配置 SPF/DKIM（以邮件服务商文档为准）

至此，从 Mail Delivery 页面的字段配置、Amazon SES 与第三方提供商的接入，到测试邮件的发送验证，以及底层存储与发送原理，Tabby 的邮件投递功能已完整打通。按上述步骤配置并验证通过后，密码重置、用户邀请等依赖邮件的能力即可在生产环境正常使用。