smtp notifications - yumi-furry/AstralGame-cli GitHub Wiki

SMTP 邮件通知

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

第 1 步：配置 SMTP 服务器

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

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

字段说明：

字段 类型 默认值 说明
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}} 同步切换为「离线邀请串（短码服务暂不可用）」。

触发时机与行为

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

相关页面