# 备份邮件发送 —— SMTP 配置教程

> 本文档讲清楚如何在 nowen-note 里启用「备份发送到邮箱」能力，并以**真实截屏可复现**的步骤，给出 QQ 邮箱、163 / 126 邮箱、Gmail、Outlook 四家主流邮箱的 SMTP 授权码获取 + 本站填写方法。
>
> 面向对象：系统管理员（`role = admin`）。普通用户看不到 SMTP 配置入口。

---

## 为什么要用这个功能

定时备份如果只存在一块磁盘/一个 Docker 卷里，遇到以下任一情况都会一起损失：

- 磁盘硬件故障
- 容器数据卷被误删（`docker volume rm`）
- 勒索软件或误操作 `rm -rf`
- 主机整机被偷 / 被收

**最廉价、最多端、最不可抵赖的异地备份就是邮箱**：它天然多副本（本地客户端 + Web + 运营商服务器），自带时间线归档，几乎所有人都有至少一个邮箱账号。

本站内建"备份发送到邮箱"能力之后，可以做到：

- 点一下就把任意一条备份作为附件发到指定邮箱
- 可以选择「发送当前备份 / 新建并发送 `.zip` 全量 / 新建并发送 `.bak` 数据库快照」三种附件格式
- 所有 SMTP 凭证经 AES-256-GCM 加密后落库，**永不明文返回前端**
- 发送前、保存配置前都要求 sudo 二次密码验证，防止会话劫持后一键脱库

---

## 总流程（1 分钟读完）

1. 在目标邮箱（如 QQ / 163 / Gmail）后台**开启 SMTP 服务**并**生成授权码**（不是登录密码！）
2. 进入 nowen-note 网页 → 设置 → 数据管理 → 备份 Tab
3. 展开「邮件通道（SMTP）」，填入主机 / 端口 / 账号 / **授权码**，勾选"启用"，保存
4. 在同一面板下面用"发送测试邮件"验证收件
5. 回到备份列表，点任意一条备份右侧的信封图标 → 选择附件格式 → 发送

> ⚠ 重要：主流邮箱**都不支持直接用登录密码**做 SMTP 认证，必须先在官网开启"客户端授权码 / 应用专用密码"，下面逐家讲。

---

## 主流邮箱 SMTP 参数速查表

| 邮箱 | SMTP 主机 | 推荐端口 | 加密方式（nowen-note 里的「使用 TLS」复选框） | 登录账号 | 登录密码 |
| --- | --- | --- | --- | --- | --- |
| **QQ 邮箱** | `smtp.qq.com` | `465` | **勾选**（SSL） | 完整邮箱地址，如 `12345678@qq.com` | **授权码**（16 位，非 QQ 密码） |
| **163 邮箱** | `smtp.163.com` | `465` | **勾选**（SSL） | 完整邮箱地址，如 `me@163.com` | **授权码**（非登录密码） |
| **126 邮箱** | `smtp.126.com` | `465` | **勾选**（SSL） | 完整邮箱，如 `me@126.com` | **授权码** |
| **Gmail** | `smtp.gmail.com` | `465`（SSL）或 `587`（STARTTLS） | 465 **勾选** / 587 **取消勾选** | 完整邮箱 | **应用专用密码**（App Password，16 位） |
| **Outlook / Hotmail / Live** | `smtp.office365.com` | `587` | **取消勾选**（走 STARTTLS） | 完整邮箱 | **应用密码**（需先开启两步验证） |
| **企业微信邮箱（exmail）** | `smtp.exmail.qq.com` | `465` | **勾选** | 完整邮箱 | **客户端专用密码** |
| **Yahoo** | `smtp.mail.yahoo.com` | `465` | **勾选** | 完整邮箱 | **App Password** |

> 📌 关于"使用 TLS"的勾选规则：
>
> - 端口 `465`：一上来就握手 SSL/TLS，勾选；
> - 端口 `587`：明文连接 → 发 `STARTTLS` 升级到加密，**不要勾选**（本站会自动走 STARTTLS）；
> - 端口 `25`：生产环境基本用不到，多数家庭宽带和云服务商也会封掉。

---

## 一、QQ 邮箱

### 1. 开启 SMTP 并生成授权码

1. 浏览器访问 <https://mail.qq.com> 登录。
2. 顶部菜单条 → **设置** → **账户**。
3. 下滑到 **POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务** 区块。
4. 点击 **"IMAP/SMTP 服务"** 后面的 **开启**。
5. 页面要求**用绑定手机发送一条短信**（内容和号码页面会给出，是运营商短信费，一般几毛钱）。
6. 发送成功后回到页面点"我已发送"，系统会弹出一串 **16 位授权码**（形如 `abcdefghijklmnop`）。
7. **立即复制保存** —— 该串只显示一次，丢失需要重新发短信生成。

### 2. 在 nowen-note 里填写

进入 **设置 → 数据管理 → 备份 Tab → 邮件通道（SMTP）**，按下表填：

| 字段 | 值 |
| --- | --- |
| 启用 SMTP 邮件发送 | ✅ 勾上 |
| SMTP 服务器 | `smtp.qq.com` |
| 端口 | `465` |
| 使用 TLS | ✅ 勾上 |
| 登录账号 | 你的完整 QQ 邮箱，如 `12345678@qq.com` |
| 登录密码 / 授权码 | 粘贴刚才的 16 位授权码 |
| 发件人显示名 | 任意，如 `nowen-note` |
| 发件人邮箱 | 必须等于登录账号 |

点 **保存配置** → 再用"发送测试邮件"输入你自己的另一个邮箱，**应在 10 秒内收到**。

### 常见报错

- `535 Login Fail`：99% 的情况是把 QQ 登录密码当授权码填了，或授权码前后带了空格。
- `550 Content denied`：QQ 对"超大附件 / 敏感关键字"偶尔误判，换 163 / Gmail 重试即可。
- 长时间没收到：检查 QQ 邮箱自己的"垃圾箱"，SMTP 自发给自己的信容易被过滤。

---

## 二、163 / 126 邮箱（网易）

163 和 126 是同一套邮件系统，操作完全一致，下文以 163 为例。

### 1. 开启 SMTP 并生成授权码

1. 访问 <https://mail.163.com> 登录。
2. 顶部 **设置** → 左侧 **POP3/SMTP/IMAP**。
3. 右侧找到 **"IMAP/SMTP 服务"**，点击 **开启**。
4. 按页面提示用手机发送**指定内容**到**指定号码**（同样是短信费）。
5. 短信通过后系统生成**授权码**，**仅显示一次**，立即复制。

> 网易近年已完全不支持"用登录密码做 SMTP"，没有授权码一定会 535 认证失败。

### 2. 在 nowen-note 里填写

| 字段 | 值 |
| --- | --- |
| SMTP 服务器 | `smtp.163.com`（126 邮箱填 `smtp.126.com`） |
| 端口 | `465` |
| 使用 TLS | ✅ |
| 登录账号 | `你@163.com`（填完整地址） |
| 登录密码 | 上一步的授权码 |
| 发件人邮箱 | 同登录账号 |

---

## 三、Gmail（含 Google Workspace）

### 1. 开启两步验证并生成 App Password

> Google 从 2022 年起彻底关闭"不安全应用"选项，必须走 App Password。

1. 打开 <https://myaccount.google.com/security>。
2. 先确认 **"两步验证"已开启**（没开的话先开，需要绑定手机/Authenticator）。
3. 两步验证开启后，进入 **应用专用密码**（<https://myaccount.google.com/apppasswords>）。
4. 应用选"邮件"，设备选"其他（自定义名称）" → 填 `nowen-note` → 生成。
5. 系统给出一串 **16 位的 App Password**（形如 `abcd efgh ijkl mnop`），**立即复制，关闭后不再显示**。

### 2. 在 nowen-note 里填写

| 字段 | 值 |
| --- | --- |
| SMTP 服务器 | `smtp.gmail.com` |
| 端口 | `465`（推荐）或 `587` |
| 使用 TLS | 端口 465 → ✅；端口 587 → ❌ |
| 登录账号 | 完整 Gmail，如 `me@gmail.com` |
| 登录密码 | 16 位 App Password（**去掉空格也可**） |
| 发件人邮箱 | 同登录账号 |

### 4. 家宽 / 云主机网络注意

- 国内直连 `smtp.gmail.com:465` 可能超时；如果 nowen-note 部署在国内服务器上，建议走境外中转或改用国内邮箱。
- 若服务器有 HTTPS 代理但没有 SOCKS，可用 `privoxy` / `proxychains` 拦 465/587 端口。

---

## 四、Outlook / Hotmail / Live / Office 365

微软系邮箱都走同一个 SMTP 网关。

### 1. 开启两步验证并生成应用密码

1. 登录 <https://account.microsoft.com/security>。
2. 开启 **两步验证**（Two-step verification）。
3. 进入 **高级安全性选项 → 应用密码 → 创建新的应用密码**。
4. 系统给出一串密码，**立即复制保存**。

> 个人 Outlook.com 账号必须两步验证开启后才会有"应用密码"入口；企业版 Office 365 管理员可能额外关闭了该功能，需要让 IT 放行。

### 2. 在 nowen-note 里填写

| 字段 | 值 |
| --- | --- |
| SMTP 服务器 | `smtp.office365.com` |
| 端口 | `587` |
| 使用 TLS | ❌（**不勾**，使用 STARTTLS 自动升级） |
| 登录账号 | 完整邮箱，如 `me@outlook.com` / `name@yourcompany.com` |
| 登录密码 | 上一步的应用密码 |
| 发件人邮箱 | **必须等于登录账号**（Office 365 强制） |

---

## 五、企业微信邮箱 / 腾讯企业邮箱

参数：

| 字段 | 值 |
| --- | --- |
| SMTP 服务器 | `smtp.exmail.qq.com` |
| 端口 | `465` |
| 使用 TLS | ✅ |
| 登录账号 | 完整企业邮箱 |
| 登录密码 | 在企业邮箱设置里生成的**客户端专用密码** |

---

## 附件格式怎么选？

在"发送备份到邮箱"对话框顶部有三个单选：

| 选项 | 产出文件 | 包含内容 | 体积 | 恢复效果 | 适用场景 |
| --- | --- | --- | --- | --- | --- |
| **发送当前备份** | 当前这条 `.zip` 或 `.bak` | 取决于它本身是 full 还是 db-only | 已知（= 备份大小） | 按其本身决定 | 最常规：想把已有的某条备份投递出去 |
| **新建并发送 `.zip` 全量** | 新生成 `.zip` | 数据库 + 附件 + 字体 + 插件 + JWT 密钥 | 最大 | 几乎 1:1 还原（含图片） | "这一刻的完整快照甩到邮箱" |
| **新建并发送 `.bak` 数据库快照** | 新生成 `.bak` | 仅 SQLite 数据库 | 最小 | 笔记/账户/标签/设置完整，**但图片等附件丢失** | 数据库 < 25MB，想确保能通过邮箱 25MB 限制 |

> **两种"新建"选项**都会在服务端像点击"创建备份"一样落一份新备份到备份列表，形成**一次操作 = 一条本地归档 + 一封邮件**。这样历史追溯清晰，也避免"为了发邮件而创建的备份被立刻删掉"的意外。

### 25MB 附件上限

大多数邮箱服务商的单封邮件附件不得超过 25MB，nowen-note 在前后端都做了 **25MB 硬拦截**：

- 选"发送当前备份"且此备份 > 25MB：前端直接禁用发送按钮并提示；
- 选"新建并发送"：前端无法预知生成后体积，后端在打包后若 > 25MB 会返回 **HTTP 413 + ATTACHMENT_TOO_LARGE**。

超过 25MB 的备份请改走「下载 → 本地邮箱客户端手动发送」或「使用云盘分享链接」，这是邮件协议本身的限制，任何邮箱都绕不开。

---

## 安全与运维建议

1. **SMTP 授权码 ≠ 可以随便泄露**。虽然本站把它 AES-GCM 加密落库，但它等价于"该邮箱可以代你发信"的凭证。泄露后立即在邮箱官网吊销并重新生成。
2. **启用两步验证**：授权码丢了要重生成；但登录密码泄露在有 2FA 的前提下攻击者拿不到。
3. **给本站一个专用邮箱**：不要使用你日常用的个人邮箱做 SMTP 发信账号——一旦授权码泄露，影响面仅限 "这个专用账号"。
4. **定时改授权码**：大多数邮箱支持同时挂多个授权码，换新的不会影响旧客户端。建议每 90 天轮换。
5. **监控发送频率**：如果突然看到"发给自己"的备份邮件频率异常，意味着可能有人拿到了 sudo + 管理员会话，立即修改密码 + 吊销授权码。
6. **防止本服务被当钓鱼跳板**：本站**不允许**自定义邮件正文 HTML、收件人也只能输入管理员一次性指定的地址、备注限制 500 字——这些都是刻意的安全约束，请不要在前端尝试绕过。

---

## 故障排查

| 症状 | 可能原因 | 解决 |
| --- | --- | --- |
| `SMTP_NOT_READY` | 没启用 / 密码未填 | 进入「邮件通道」勾选"启用"，确认密码行有"（已设置）"徽标 |
| `535 Authentication failed` | 填的是登录密码不是授权码 / 授权码过期 | 回邮箱官网重新生成授权码 |
| `550 relaying denied` / `553 From address rejected` | 发件人邮箱与登录账号不一致 | 两者填成同一个完整邮箱地址 |
| 连接超时（`ETIMEDOUT`） | 服务器到邮件网关端口被封（尤其国内云到 Gmail） | 换端口 465 / 587，或换国内邮箱，或配置代理 |
| `ATTACHMENT_TOO_LARGE` | 备份 > 25MB | 选"新建并发送 `.bak`"，或改用下载后手动发 |
| 收到一半乱码附件 | 极少见，多为中继服务器改写 | 换加密端口（465 SSL 通常更稳） |

---

## 附：字段与接口对照

给运维 / 开发者留的内部参考：

- 配置落在 `system_settings` 表，key = `smtp:config`，value 为 JSON：
  - `{ host, port, secure, username, passwordEnc, fromName, fromEmail, enabled }`
  - `passwordEnc` 是 AES-256-GCM 密文（key 从 `JWT_SECRET` + 固定盐 scrypt 派生），读取 API 只回 `hasPassword: true`
- REST 接口：
  - `GET /api/email/smtp` — 读配置（admin）
  - `PUT /api/email/smtp` — 写配置（admin + sudo）
  - `POST /api/email/smtp/test` — 发测试邮件（admin + sudo）
  - `POST /api/backups/:filename/send-email` — 发备份（admin + sudo；body `{ to, note?, createNew? }`）
- 附件上限常量：`EMAIL_ATTACHMENT_LIMIT = 25 * 1024 * 1024`