该模块的功能 #

服务器上的很多事情都会通过邮件通知你：即将到期的证书、快满的磁盘、某个夜间任务的报告。但一台刚安装好的服务器并不知道如何发送这些邮件——要么直接尝试而最终落入垃圾邮件文件夹，甚至被彻底拒收。

smtp 模块通过将主机的出站邮件配置到一个 smarthost（一个确实有权投递的 relay：Amazon SES、企业邮件服务器、你的服务商……）来解决这个问题。它调整 postfix，使其把所有系统邮件转发到该 smarthost，安全地保存密码，重写发件人使其有效，并让你测试发送以确认邮件送达——若出错则向你报告真实的错误。

开始之前

准备好 smarthost 的信息：host、端口（通常为 587），以及需要认证时的凭据。密码不通过命令行传递：它从 stdin 或密钥存储中读取，因此不会留在历史记录里。

快速指南分步任务

常见任务 #

选择你想做的事。每个方案都附有写好的命令——只需把 smarthost 和发件人换成你自己的，然后点击复制。

配置邮件 relay 发送一封测试邮件查看邮件状态查看生效的配置移除 relay

1

配置邮件 relay

让服务器指向你的 smarthost，使邮件真正发出。

用 ubuntu 用户通过 SSH 连接到你的服务器。

用你的 smarthost 信息运行命令。密码通过 stdin 输入，因此不会留在历史记录里：

终端

$ sudo imaxe smtp configure \
    --host email-smtp.eu-west-1.amazonaws.com \
    --user AKIAIOSFODNN7EXAMPLE \
    --from [email protected]

如果你的 smarthost 不需要认证，省略 --user。若端口或 TLS 模式不同，添加 --port 或 --no-tls。

Postfix 已配置为将所有系统邮件转发到你的 smarthost，并将发件人重写为 [email protected]。继续执行方案发送一封测试邮件。

2

发送一封测试邮件

在信赖告警之前，先确认一封邮件能发出并送达。

向一个你能查收的地址发送一封测试邮件：

终端

$ sudo imaxe smtp test --to [email protected]

如果省略 --to，邮件会发送到已配置的发件人。查看你的收件箱（以及垃圾邮件文件夹）以确认送达。

如果邮件送达，你的服务器就已经会通知你了。如果失败，命令会显示 MTA 的真实错误，让你知道要修正什么。

3

查看邮件状态

一眼确认 relay 是否已配置并处于激活状态。

一份关于 relay、smarthost、发件人和 MTA 状态的摘要：

终端

$ sudo imaxe smtp status

要用于脚本或面板？添加 --json 获得机器可读的输出：

终端

$ sudo imaxe smtp status --json

你会立刻知道出站邮件是否已就绪，还是仍需配置。

4

查看生效的配置

查阅当前生效的设置，且不暴露密码。

显示实际在用的 host、端口、用户、发件人和 TLS 模式（密码从不打印）：

终端

$ sudo imaxe smtp show

非常适合在测试发送前核对某项设置，或用于记录主机的配置。

5

移除 relay

禁用转发，并将 postfix 恢复到之前的状态。

禁用出站邮件 relay，并恢复 postfix 的基础配置：

终端

$ sudo imaxe smtp remove

服务器不再通过 smarthost 转发。你可以随时用 configure 重新配置。

测试邮件没有送达？

最常见的原因是发件人未在 smarthost 上通过验证（SES 要求验证域名或 --from 地址），或者凭据不正确。运行 imaxe smtp test：它会返回 MTA 的真实错误，让你精确知道要调整什么。

CLI 参考命令、标志与文件

用法概要 #

用法

imaxe smtp <subcomando> [--host HOST] [--from CORREO] [flags]

所有子命令都需要 root 权限（使用 sudo），因为它们会改动 postfix 的配置、写入 /etc/imaxe/ 并重载系统服务。smarthost 的密码从不作为标志传递：它从 stdin 或密钥存储读取。给 status 或 show 添加 --json 可获得机器可读的输出，适合用于脚本。

子命令 #

子命令	功能	相关标志
configure	将出站邮件 relay 配置到一个 smarthost。密码通过 secrets/stdin 读取。	--host, --port, --user, --from, --tls / --no-tls
test	发送一封测试邮件，若失败则报告 MTA 的真实错误。	--to
status	状态：relay 是否已配置、smarthost、发件人以及 MTA 是否激活。	--json
show	显示生效的配置，且不暴露密码。	--json
remove	禁用 relay 并恢复 postfix。	—

参数与标志 #

标志	类型	默认值	说明
--host 必填	string	—	要转发邮件的目标 SMTP smarthost（例如 `email-smtp.eu-west-1.amazonaws.com`）。在 `configure` 中必填。
--port	int	587	smarthost 的 SMTP 端口。
--user	string	—	用于认证的 SMTP 用户。若省略，则 relay 配置为无认证。
--from	string	—	重写所有邮件的发件人（`sender_canonical`）。用于使用已在 smarthost 上验证的地址。
--tls / --no-tls	bool	--tls	强制与 smarthost 的连接使用 TLS（默认）。`--no-tls` 将其禁用。
--to	string	发件人	在 `test` 中：测试邮件的收件人。默认为已配置的发件人。
--json	bool	false	在 `status`/`show` 中，以 JSON 形式在 `stdout` 输出结果。

密码不是标志

没有 --password 选项。凭据在 configure 期间通过 stdin 读取，或从密钥存储读取（password_secret，默认为 smtp），因此它从不出现在历史记录或进程表中。

文件与路径 #

路径	内容
/etc/imaxe/smtp.yml	模块配置：host、端口、TLS、用户、发件人以及对密码密钥的引用。
/etc/postfix/main.cf	模块为转发而调整的 postfix 配置（relayhost、发件人 canonical……）。
/var/log/mail.log	postfix 的日志，记录每次投递尝试及拒收原因。

smtp.yml 示例：

/etc/imaxe/smtp.yml

enabled: true
host: email-smtp.eu-west-1.amazonaws.com
port: 587
tls: true
username: AKIAIOSFODNN7EXAMPLE
from: [email protected]
password_secret: smtp

退出码与日志 #

每次执行都会返回一个退出码，你可以用 echo $? 查看——便于在脚本中串联：

0OK操作完成；在 test 中，邮件已被接受用于投递。

1ERR未分类的通用错误。请查看日志。

2USAGE参数无效或缺失。

3CONFIGrelay 未配置或配置不完整。

4AUTHsmarthost 拒绝了凭据。

5SEND测试发送在 MTA 处失败（见报告的错误）。

在调试发送时实时跟踪邮件日志：

终端

$ sudo tail -f /var/log/mail.log
$ sudo imaxe smtp test --to [email protected]

故障排查 #

现象	可能原因	解决方法
出现 AUTH（退出码 4）	smarthost 的用户或密码不正确。	检查 `--user`，然后重新运行 `configure` 并再次通过 `stdin` 输入密码。
出现 SEND（退出码 5），发件人被拒绝	`--from` 地址未在 smarthost 上验证（SES 中很常见）。	在服务商处验证域名或地址，然后重试 `test`。
出现 CONFIG（退出码 3）	此主机上尚未配置 relay。	用 smarthost 信息运行 `imaxe smtp configure`。
邮件发出但落入垃圾邮件	发件人域名缺少对齐的 SPF/DKIM。	为 `--from` 的域名配置邮件服务商的记录。

邮件模块遇到问题了？

把「imaxe <module> status --json」的输出发给我们，我们会尽快回复你。

联系支持

让你的告警送达