From 4fc933bc893f44e157b000ae5096d75f3e77c912 Mon Sep 17 00:00:00 2001
From: LanQin_ <lanqinnet@qq.com>
Date: Tue, 16 Jun 2026 21:21:56 +0800
Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E8=A1=A5=E5=85=85=20SMTP=20?=
 =?UTF-8?q?=E5=8F=91=E4=BF=A1=E6=8E=92=E6=9F=A5=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 说明单容器部署下 Webmail 发信的默认 Postfix 配置。
- 补充 `smtp delivery failed: EOF` 的排查命令与 `SMTP Require TLS` 注意事项。
- 调整 `deploy/postfix/master.cf` 中 `smtp/submission` 的监听标志，避免本机提交会话异常。
---
 deploy/README.md         | 21 +++++++++++++++++++++
 deploy/postfix/master.cf |  4 ++--
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/deploy/README.md b/deploy/README.md
index d578fd9..5cb0178 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -128,6 +128,27 @@ docker compose -f docker-compose.stack.yml -f docker-compose.stack.build.yml up
 - Go API 是 Webmail 和管理后台唯一入口；浏览器不直接连接 SMTP/IMAP。
 - Go API 会读取 `LANQIN_MAILDIR_ROOT=/var/mail/vhosts`，周期扫描 Maildir，把 Postfix/Dovecot 入站邮件同步成 Webmail 索引。
 
+## SMTP 发信排查
+
+单容器部署时，Webmail 发信默认提交给同容器内的 Postfix：
+
+```env
+LANQIN_SMTP_HOST=127.0.0.1
+LANQIN_SMTP_PORT=25
+LANQIN_SMTP_REQUIRE_TLS=false
+```
+
+如果页面提示 `smtp delivery failed: EOF`，通常是 Postfix 会话被中断。优先检查：
+
+```bash
+docker compose exec lanqin-email supervisorctl status
+docker compose exec lanqin-email postconf -M smtp/inet submission/inet
+docker compose exec lanqin-email sqlite3 /data/lanqin.db "select key,value from system_settings where key like 'smtp%' order by key;"
+docker compose logs --tail=200 lanqin-email
+```
+
+确认后台“系统设置”里没有把本机 Postfix 的 `SMTP Require TLS` 打开；本机 `127.0.0.1:25` 必须保持 TLS=false。
+
 ## 生产注意
 
 - 建议在服务器或边缘网关配置 HTTPS。
diff --git a/deploy/postfix/master.cf b/deploy/postfix/master.cf
index c30336d..9ed8fd4 100644
--- a/deploy/postfix/master.cf
+++ b/deploy/postfix/master.cf
@@ -1,5 +1,5 @@
-smtp      inet  n       -       y       -       -       smtpd
-submission inet n       -       y       -       -       smtpd
+smtp      inet  n       -       n       -       -       smtpd
+submission inet n       -       n       -       -       smtpd
   -o syslog_name=postfix/submission
   -o smtpd_tls_security_level=may
   -o smtpd_sasl_auth_enable=yes