# SMTP 邮件通知

当服务器重启、或房间码发生变动时，系统会自动发送一封与面板同风格的 HTML 邮件（渐变蓝头部、圆角卡片、房间信息表格、大号房间码、邀请链接按钮）给收件人列表。

## 第 1 步：配置 SMTP 服务器

在 `config.toml` 中配置 `[astral_server.smtp]` 表：

```toml
[astral_server.smtp]
enabled = true
host = "smtp.qq.com"          # 见下表
port = 465
username = "your_mail@qq.com"
password = "授权码"            # 注意：是 SMTP 授权码，不是邮箱登录密码
from_name = "Astral Server"
from_email = "your_mail@qq.com"
encryption = "tls"            # 465 端口用 tls；587 用 starttls；内网不加密用 none
recipients = ["friend@example.com"]
```

字段说明：

| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `enabled` | bool | `false` | 总开关（关闭则不发信） |
| `host` | string | 空 | SMTP 服务器主机 |
| `port` | int | `465` | SMTP 端口（TLS 一般 465，STARTTLS 一般 587） |
| `username` | string | 空 | 登录用户名（一般与发件邮箱一致） |
| `password` | string | 空 | 登录密码 / SMTP 授权码 |
| `from_name` | string | `Astral Server` | 发件人显示名称 |
| `from_email` | string | 空 | 发件邮箱地址 |
| `encryption` | string | `tls` | 加密方式：`tls`（隐式 TLS / 465）/ `starttls`（587）/ `none`（不加密） |
| `recipients` | string 数组 | `[]` | 收件人邮箱列表（可在面板编辑） |

## 第 2 步：维护收件人并测试

重启服务后，打开面板「设置 → 邮件通知」：

- 可以看到服务器配置摘要（主机、端口、加密方式、授权码是否已设置）；
- 在「收件人邮箱」中每行填写一个邮箱，点「保存收件人」（会自动去重并校验格式）；
- 点「发送测试邮件」，收件箱收到测试邮件即配置成功；
- 点「一键发信」，立即将**当前房间详情**（游戏、房间码、邀请链接、运行状态、节点数）发送给列表中的所有收件人；当前无房间时会提示先创建或加入房间。

## 常见邮箱参数

| 邮箱 | host | 端口 / 加密 | 授权码获取方式 |
|---|---|---|---|
| QQ 邮箱 | `smtp.qq.com` | 465 / tls（或 587 / starttls） | QQ 邮箱 → 设置 → 账号 → POP3/SMTP 服务 → 开启 → 生成授权码 |
| 163 邮箱 | `smtp.163.com` | 465 / tls | 邮箱设置 → POP3/SMTP/IMAP → 开启 SMTP → 设置客户端授权码 |
| Gmail | `smtp.gmail.com` | 465 / tls（或 587 / starttls） | 需开启两步验证后生成「应用专用密码」；国内服务器通常无法直连 |
| Outlook | `smtp.office365.com` | 587 / starttls | 使用账号密码（部分账号需 OAuth） |

## 注意事项

- `password` 字段填写**授权码/应用专用密码**，几乎所有主流邮箱都不再允许第三方客户端使用登录密码；
- 授权码保存在服务器的 `config.toml` 中，请注意文件权限（`chmod 600 config.toml`）；面板的配置接口不会回传密码；
- 邮件只在**存在房间**时发送（离开房间不会发送空通知）；
- 发送失败只会记录警告日志，不影响房间与其他功能。

## 邮件模板自定义

服务器**首次运行**后，会在可执行文件同目录下自动生成 `Email/` 文件夹，包含两个模板文件：

| 文件 | 说明 |
|---|---|
| `Email/room_notification.html` | HTML 邮件模板（与面板同风格，渐变蓝头部 + 圆角卡片） |
| `Email/room_notification.txt` | 纯文本邮件模板（用于不支持 HTML 的客户端） |

**直接编辑这两个文件即可自定义邮件样式**，无需重启服务（每次发信时实时读取文件）。删除文件后重启服务会重新生成默认模板。

### 模板变量

模板中以下 `{{变量}}` 占位符会在发送时自动替换为实际值：

| 变量 | 释义 | 示例值 |
|---|---|---|
| `{{EVENT_TITLE}}` | 事件标题 | 房间已创建 / 服务器已启动 |
| `{{EVENT_DESC}}` | 事件描述 | 服务器重启后自动恢复了房间 |
| `{{GAME_NAME}}` | 游戏名称 | 我的世界 |
| `{{GAME_ID}}` | 游戏标识 | minecraft |
| `{{SHORT_CODE}}` | 房间码（短码或离线邀请串） | ABC123 |
| `{{CODE_HINT}}` | 房间码提示文字 | 房间码（短码） |
| `{{SHARE_URL}}` | 邀请链接 | https://next.astral.fan/j?c=ABC123 |
| `{{RUNNING}}` | 运行状态 | 运行中 / 未运行 |
| `{{TOTAL_NODES}}` | 在线节点数 | 3 |
| `{{SERVER_VERSION}}` | 服务器版本 | 1.5.1_1 |

> 变量值已做 HTML 转义，可直接在 HTML 模板中使用。
> 房间码优先取短码；短码服务不可用时回退为 `AG1.` 离线串，`{{CODE_HINT}}` 同步切换为「离线邀请串（短码服务暂不可用）」。

## 触发时机与行为

- 服务器重启、或房间码发生变动时自动发送通知邮件；
- 一键发信使用「房间详情速递」标题，立即发送当前房间详情给所有收件人。

## 相关页面

- [配置参考](configuration.md)
- [REST API 参考](rest-api.md)
- [WebSocket 事件推送](websocket-events.md)