Immich 邮件通知配置指南：使用 Gmail 应用密码接入 SMTP 的完整流程

本文基于 Immich 官方指南（docs/docs/guides/smtp-gmail.md）展开，讲解如何为自托管的 Immich 实例接入 Gmail 的 SMTP 服务：从 Google 账号的应用密码创建，到 Immich 管理面板中各项 SMTP 参数的填写，再到参数在源码层的实际作用。读完后你将能够独立完成 Immich 邮件通知（欢迎邮件、共享相册邀请、相册更新通知等）的收发配置，并理解每个 SMTP 字段在代码中的含义，便于排查发送失败问题。

Immich 在哪些场景下发送邮件

在配置 SMTP 之前，先明确这套邮件通道在 Immich 中承担的职责。根据官方文档 Email Notifications，Immich 支持通过邮件发送以下事件的通知：

• 创建新用户（欢迎邮件）；
• 用户被邀请加入共享相册时通知该用户；
• 共享相册中新增素材时通知其他成员。

从源码 EmailTemplate 枚举 可以看到，服务端内置了五类邮件模板：

export enum EmailTemplate {
  TEST_EMAIL = 'test',        // SMTP 连通性测试邮件
  WELCOME = 'welcome',         // 欢迎邮件
  RESET_PASSWORD = 'reset-password', // 重置密码邮件
  ALBUM_INVITE = 'album-invite',  // 相册邀请
  ALBUM_UPDATE = 'album-update',  // 相册更新
}

其中 test 模板专门用于配置完成后的连通性验证。此外，管理员还可在 Administration -> Settings -> Notification settings 中用自定义 HTML 模板覆盖默认通知文案（见 email-notification.mdx 的 "Notification templates" 一节），普通用户则可在个人设置中按事件开关邮件通知。

第一步：为 Gmail 账号创建应用密码

Immich 不能直接使用 Gmail 的登录密码进行 SMTP 认证，需要走 Google 的“应用密码（App Password）”机制。官方指南给出的前置条件有两项：

1. 为你的 Google 账号开启两步验证（2-Step Verification）——这是创建应用密码的硬性前提，未开启 2SV 的账号在 Google 账号设置中看不到应用密码入口；
2. 在 Google 账号设置中创建一个应用密码。应用密码以 16 位随机字符形式展示，创建完成后只显示这一次，务必当场复制保存。

这个应用密码稍后将填入 Immich SMTP 配置表单的“密码（Password）”字段，用户名则填你的完整 Gmail 邮箱地址（如 [e-mail]）。

从实现角度看，Immich 只是把这个用户名/密码原样交给邮件传输库做 SMTP 认证：在 email.repository.ts 中，只要提供了 username 或 password，就会构造 auth: { user, pass } 交给 nodemailer。因此认证失败通常意味着应用密码抄写错误，或 2SV 状态变更导致密码失效。

第二步：在 Immich 管理面板填写 SMTP 凭据

打开 Web 端管理界面，进入 Administration -> Settings -> Notification Settings（管理 → 设置 → 通知设置），在 Email 区域填入连接 Gmail SMTP 服务器所需的信息。Gmail 官方公布的 SMTP 服务参数为 smtp.gmail.com，支持 587 端口（STARTTLS 升级加密）和 465 端口（直接 TLS 加密）。结合 Immich 源码中 SMTP 选项的定义，各字段含义如下：

表单字段	推荐取值（Gmail）	源码字段	说明
Host（主机）	smtp.gmail.com	host	SMTP 服务器地址，必填
Port（端口）	587（或 465）	port	与 SMTPS 开关需配套使用
Username（用户名）	完整 Gmail 地址	username	与 Password 任一提供即启用认证
Password（密码）	上一步创建的应用密码	password	不是 Gmail 登录密码
SMTPS	端口 587 时关闭；465 时开启	secure	控制是否直接建立 TLS 连接
Ignore Certificate（忽略证书）	保持关闭	ignoreCert	自托管环境一般不需要跳过证书校验

对应源码中的选项类型为（email.repository.ts）：

export type SmtpOptions = {
  host: string;
  port?: number;
  secure?: boolean;      // 对应表单的 SMTPS 开关
  username?: string;
  password?: string;
  ignoreCert?: boolean;   // 对应“忽略证书错误”
};

关于 secure 与 ignoreCert 的底层行为，可以从 createTransport 的构造逻辑 中直接确认：

• secure: options.secure 直接透传给 nodemailer，决定连接时是“先明文连接再 STARTTLS 升级”（587 端口）还是“建立连接即 TLS”（465 端口）。端口和该开关必须匹配，这是 587/465 混用时最典型的排障点；
• tls: { rejectUnauthorized: !options.ignoreCert } 表明“忽略证书”开关实际控制的是 TLS 证书是否严格校验。Gmail 使用 Google 签发的公网证书，无需开启；仅当使用自建邮件中继且证书不受信时才有意义；
• connectionTimeout: 5000 表明 SMTP 连接超时固定为 5 秒，如果容器网络无法出站到 587/465 端口，表单会表现为超时错误而非长时间挂起。

验证配置：测试邮件与 SMTP 校验

填写完成后，Immich 通知设置页提供发送测试邮件的能力。从源码看，该流程并非简单地“发一封普通邮件”，而是先对 SMTP 服务器做了一次身份校验：verifySmtp 会创建一个 transport、调用 transport.verify() 验证主机与凭据是否可用，随后无论成功与否都会 close() 释放连接；测试邮件本身则由 EmailRepository.sendEmail 通过 TEST_EMAIL 模板渲染并发送。管理端该能力的入口在 notification-admin.service.ts 中，它把表单提交的 transport 参数作为 smtp 选项传入发送流程。

如果测试邮件发送失败，可以按以下顺序排查：

1. 认证类错误（535 等）：确认账号已开启 2SV、用户名是完整邮箱地址、密码是应用密码且没有多余空格——应用密码只会展示一次，记错了只能重新生成；
2. 超时/连接失败：确认 Docker 容器所在网络能访问 smtp.gmail.com:587/465，注意 5 秒连接超时的硬性限制；
3. TLS 错误：检查 Port 与 SMTPS 开关是否匹配（587 关闭、465 开启）；Gmail 场景下无需开启“忽略证书”。

与其他 SMTP 方案的衔接与源码入口

Gmail 只是 Immich 支持的众多邮件中继之一，官方文档同时提供了 Microsoft 365 SMTP 配置指南（使用 smtp-mail.outlook.com:587、SMTPS 关闭），而参数面板与自定义通知模板的完整说明见 Email Notifications 文档。如需深入邮件发送链路，可从以下文件继续阅读：

• server/src/repositories/email.repository.ts：SMTP 选项定义、nodemailer 传输构造、测试邮件模板；
• server/src/services/notification-admin.service.ts：管理端通知与测试邮件服务；
• server/src/emails/：欢迎邮件、相册邀请、相册更新等 React Email 模板的渲染实现。

总结：接入 Gmail 的核心路径是“开启 2SV → 生成并保存应用密码 → 在 Administration -> Settings -> Notification Settings 填入主机/端口/用户名/应用密码并按端口匹配 SMTPS 开关 → 发送测试邮件验证”。整个配置在源码层收敛为一个轻量的 SmtpOptions 结构，参数含义清晰，排障时基本只需对照认证、端口/TLS 匹配和出站网络三个方向。