企业官网建设流程全解析

Immich 邮件通知配置实战：使用 Microsoft 365 / Outlook 应用密码接入 SMTP

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich

Immich 支持通过 SMTP 发送欢迎邮件、共享相册邀请与更新通知等系统邮件，而使用 Microsoft 365 / Outlook 账号作为发信通道是最常见的自建场景之一。本文基于仓库中的 SMTP Microsoft 365 配置指南 展开，完整覆盖应用密码创建、Immich 管理后台 SMTP 参数填写，并结合后端源码讲清 Immich 是如何解析、校验并最终发出这些邮件的，读完你可以独立完成一套可验证、可排错的 Immich 邮件通知配置。

一、Immich 中 SMTP 的作用与邮件触发链路

在 Immich 中，SMTP 配置位于系统级设置，服务于以下邮件场景（对应后端 EmailRepository 中定义的EmailTemplate枚举）：

• 测试邮件（test）：管理员在设置页一键验证 SMTP 配置是否可用；
• 欢迎邮件（welcome）：管理员为用户创建账号并开启通知时发送；
• 相册邀请（album-invite）：他人把你加入共享相册时发送，可携带相册缩略图附件；
• 相册更新（album-update）：共享相册新增媒体时发送，同样可携带缩略图。

从源码结构看，邮件并不在请求线程中同步发出：各业务事件（UserSignup、AlbumInvite、AlbumUpdate等）先投递到 Notification 队列，最终由SendMail任务统一读取当前 SMTP 配置并调用emailRepository.sendEmail发送，完整实现见 NotificationService。因此只要队列中 SMTP 配置被禁用（notifications.smtp.enabled为 false），发送任务会被直接跳过（返回JobStatus.Skipped）。

二、第一步：创建 Microsoft 应用密码

直接使用 Microsoft 邮箱的主账号密码登录 SMTP 服务器通常会被拒绝，需要为账号生成一个应用密码（App Password），供 Immich 作为 SMTP 认证密码使用。根据账号类型，入口不同：

• 个人账号（Outlook.com / Hotmail 等）：登录 Microsoft 账号的“安全信息”（Security info）页面，在其中创建新的应用密码；
• 工作 / 学校（Microsoft 365）账号：通过 Microsoft 提供的 2SV 应用密码管理入口创建。

应用密码生成后请立即妥善保存，它只会显示一次，之后将填入 Immich 的 SMTP 密码字段。

三、第二步：在 Immich 中填写 SMTP 凭据

进入管理后台路径：Administration -> Settings -> Notification Settings（该页面对应前端文件 NotificationSettings.svelte），按下表填写 Microsoft 通道的参数：

“SMTPS 禁用”在源码中意味着什么

Immich 后端把界面中的 SMTPS 开关映射为 nodemailer 的secure选项。见 SmtpOptions 类型定义 与 createTransport 实现：

private createTransport(options: SmtpOptions) { return createTransport({ host: options.host, port: options.port, tls: { rejectUnauthorized: !options.ignoreCert }, secure: options.secure, auth: options.username || options.password ? { user: options.username, pass: options.password } : undefined, connectionTimeout: 5000, }); }

• secure: false（即界面中 SMTPS 关闭）+ 端口 587：连接建立后通过STARTTLS升级为加密通道，这正是 Outlook SMTP 587 端口的标准用法；若你把端口改到 465，则需要将 SMTPS 打开（secure: true，隐式 TLS）；
• ignoreCert对应tls.rejectUnauthorized，默认关闭证书跳过；只有在企业内网使用自签名证书等特殊场景才需要打开；
• connectionTimeout: 5000：连接超时固定为 5 秒，超时即判定配置不可用。

系统配置的默认值同样印证了上述约定，见 config.dto.ts 中 notifications.smtp 默认项：enabled: false、port: 587、secure: false、ignoreCert: false。

四、配置校验与测试邮件的验证机制

填写完成后不要跳过验证，Immich 提供了两层校验：

1. 配置保存时自动验证：NotificationService注册了ConfigValidate事件钩子，只要 SMTP 处于启用状态且配置发生变化，就会调用emailRepository.verifySmtp（底层为 nodemailer 的transport.verify()，建立一次握手后即关闭连接）；失败会抛出 “Invalid SMTP configuration” 并记录Failed to validate SMTP configuration日志，见 onConfigValidate 实现。
2. 手动发送测试邮件：Send Test Email按钮走 sendTestEmail 流程——先verifySmtp验证连通性与认证，再渲染test.email模板（位于 emails 目录），以from发件人、replyTo回复地址发往当前登录管理员邮箱；验证不通过会返回 “Failed to verify SMTP configuration”。

测试邮件中的链接域名取决于系统设置里的外部域名（server.externalDomain），由getExternalDomain计算注入模板，因此如果你的部署有公网访问地址，建议一并配置以保证邮件内链接可点击。

五、可自定义的邮件模板

Notification Settings 之外的 Template Settings 页面（Administration -> Settings -> Template Settings）允许管理员为welcomeTemplate、albumInviteTemplate、albumUpdateTemplate配置自定义 HTML 模板（默认值定义见 config.dto.ts templates.email）。模板为可选增强项：不配置时使用内置的 React Email 模板（emails 目录 下的.email.tsx组件），它们同时渲染 HTML 与纯文本两种版本，由 renderEmail 统一产出。

六、排错要点

结合源码行为，Microsoft 通道常见的失败点与排查方向如下：

• 认证失败：绝大多数是密码填了主密码而非应用密码，或应用密码已被撤销；确认使用第二步生成的一次性密码；
• 端口 / 加密方式不匹配：587 端口必须保持 SMTPS 关闭（STARTTLS）；如果运维侧只放行了 465 端口，则应改用 465 并打开 SMTPS；
• 证书校验失败：仅当出现自签名证书链问题时才考虑打开ignoreCert，正常 Microsoft 公网证书无需开启；
• 保存配置即报错：由于ConfigValidate钩子会实时verifySmtp，保存失败通常等价于“测试邮件必失败”，优先按上述顺序检查主机、端口、认证三要素；
• 发送状态确认：每次任务发送成功后会记录Sent mail with id: <messageId>日志，可用其确认邮件是否真正投递。

单元测试与中测分别覆盖上述行为，可参考 email.repository.spec.ts 与 notification.service.spec.ts。

小结

使用 Microsoft 365 / Outlook 接入 Immich 邮件通知的核心步骤只有两步：为 Microsoft 账号创建应用密码，然后在Administration -> Settings -> Notification Settings中按smtp-mail.outlook.com:587+ 邮箱地址 + 应用密码 + SMTPS 关闭的参数填写，并用 Send Test Email 验证。理解后端将其映射为 nodemailersecure: false（STARTTLS）的传输参数后，你就能自行推导出 465 端口、自签名证书等变体场景下的正确配置，而不是只依赖固定参数表。如果你使用 Gmail 通道，可参考仓库中同系列的 Gmail SMTP 配置指南。

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich