clover-mail/docs/mail-client-setup.md

邮箱客户端配置指南（IMAP / POP3 / SMTP）

适用于 clover 三叶草邮局实例。示例使用 example.com，请替换成你自己的域名。 面板地址：https://<面板域名>（例如 https://panel.example.com）

---

一、服务器参数（照抄）

用途	服务器	端口	加密方式	用户名	密码
收信 IMAP（推荐）	mail.<你的域名> 或服务器 IP	993	SSL/TLS	完整邮箱地址	建邮箱时设的
收信 IMAP（备选）	同上	143	STARTTLS	同上	同上
收信 POP3	同上	995	SSL/TLS	同上	同上
收信 POP3（备选）	同上	110	STARTTLS	同上	同上
发信 SMTP（推荐）	同上	587	STARTTLS	同上	同上
发信 SMTP（备选）	同上	465	SSL/TLS	同上	同上

三条铁律：

1. 用户名必须写完整邮箱地址（boss@example.com），不是只写 boss
2. 加密必须开，个人邮箱别用明文端口（143/110 不带加密时密码是明文的）
3. 发信必须勾选「需要认证」，否则会被当开放中继

端口 25 不要用做客户端发信端口——那是服务器之间投递用的，客户端用 587。

WebMail（不想装客户端就用这个）：浏览器打开 https://<面板域名>/webmail （面板左侧「WebMail」页选邮箱可免密直达；直接打开这个网址则用邮箱地址+密码登录）

---

二、各客户端具体步骤

Thunderbird（Windows / macOS / Linux）

1. 账户设置 → 新建账户 → 电子邮件
2. 填姓名 / 邮箱地址 / 密码 → 点「手动配置」（别让向导自己猜）
3. 按上表填：
   • 收件：IMAP，mail.<域名>，993，SSL/TLS
   • 发件：mail.<域名>，587，STARTTLS，认证方式「普通密码」
   • 用户名两处都填完整邮箱地址
4. 点「重新测试」→ 两边都显示成功后「完成」
5. 若提示证书不受信任：勾选「永久信任此证书」→ 确认（自签证书，见第四节）

iPhone / iPad（iOS「邮件」App）

设置 → 邮件 → 账户 → 添加账户 → 其他 → 添加邮件账户

• 收件服务器：IMAP，主机名 mail.<域名>，用户名 = 完整邮箱，密码
• 发件服务器：主机名 mail.<域名>，用户名/密码同上
• 保存后进「账户 → 高级」确认：收件用 993 + SSL，发件用 587 + STARTTLS（iOS 有时会自动选错端口，务必核对）
• 弹证书警告 → 「详细信息 → 信任」（自签证书）

Android（系统「电子邮件」/ Gmail App 的「其他」）

手动设置 → IMAP：

• 收件：mail.<域名> / 993 / SSL/TLS
• 发件：mail.<域名> / 587 / STARTTLS / 需要登录
• 用户名 = 完整邮箱地址

Outlook（Windows / Mac / 移动端）

文件 → 添加账户 → 手动设置 → POP 或 IMAP

• 若坚持用 POP3：收件 995 SSL，发件 587 STARTTLS，勾选「在服务器上保留邮件副本」（否则手机拉走就没了）
• 建议改用 IMAP（多设备同步）

Apple Mail（macOS）

系统设置 → 互联网账户 → 添加其他账户 → 邮件 → 填账号密码 → 手动填上面参数

---

三、POP3 还是 IMAP？

	IMAP（推荐）	POP3
多设备同步	✅ 服务器保存，各端看到同一份	❌ 默认下载到本地并删除服务器副本
已读/文件夹/标记	✅ 同步	❌ 只有收件箱概念
服务器占用	配额内一直占	拉走即释放（省空间）

结论：手机+电脑都用 → 用 IMAP。只有一台设备且想省服务器空间 → 用 POP3（务必勾「保留副本」免得误删）。

POP3 和 ManageSieve 监听器由 .env 中的 ENABLE_POP3=1、ENABLE_MANAGESIEVE=1 启动（示例配置默认启用）。IMAP、POP3、ManageSieve 和 SMTP 的账号访问开关集中在「邮箱账户 → 全局邮箱设置」中，默认全部启用；关闭 IMAP 会同时关闭Roundcube。

---

四、证书这件事（首次连接必看）

全新安装默认使用自签证书（安装器自动生成，CN = mail.<主域>）。所以：

• 客户端首次连接会报「证书不受信任 / 无法验证服务器身份」
• Thunderbird：勾「永久信任」；iOS：进「详细信息 → 信任」；Android：选「继续/接受」
• 不影响加密（连接仍是 TLS 加密的），只影响证书链验证

想彻底消除警告：登录面板，打开「面板设置 → TLS 证书」，在「邮件服务证书」卡片点击「签发 / 检查续期」。邮件主机名的 A 记录需指向本机，公网 TCP 80 可达，Cloudflare 代理需暂时关闭。签发成功后证书会安装到 DMS，并由证书助手自动续期；续期时邮件服务会短暂重启。

---

五、限制与已知问题

项	值 / 状态
DMS 单封邮件大小上限	按「全局邮箱设置」中的附件总量自动设置，并预留 MIME 编码空间；默认附件上限 100 MB 时，DMS 总邮件上限约 150 MiB。
邮箱配额	面板建邮箱时填的「配额 MB」；不填 = 不限
附件总量限制	全局设置同时应用于 Webmail；DMS 的 Postfix 上限是完整 MIME 邮件的全局值，客户端（如 Foxmail）也受此值限制。勾选“无限额”可关闭上限；API 中填 0 表示无限额。
远程图片	默认不自动显示，使用 Roundcube 原生图片拦截/按需加载功能；全局邮箱设置可调整自动显示默认值。
外网来信	若 VPS 服务商或防火墙未放行公网 TCP 25，则无法接收外部来信
发信被 Gmail 判垃圾	检查 PTR 反解是否指向 mail.<域名>，并确认 SPF / DKIM / DMARC 已配置
自动配置（autoconfig）	❌ 暂未生效：DNS 里 autoconfig.<域名> 有 CNAME，但服务器未托管自动配置 XML，客户端自动发现会失败 → 按本文手动填参数
CalDAV / CardDAV（日历通讯录）	❌ 未部署（DMS 不含），如需可另装

---

六、连不上时怎么排查

在服务器上（或本机有 openssl 的话）逐条测：

# 1) IMAPS 995 是否通 + 证书信息
openssl s_client -connect mail.<域名>:993 -servername mail.<域名> </dev/null | openssl x509 -noout -subject -dates

# 2) 587 STARTTLS 是否可用（看到 "250-STARTTLS" 即正常）
openssl s_client -starttls smtp -connect mail.<域名>:587 -crlf </dev/null | head -20

# 3) POP3S 995
openssl s_client -connect mail.<域名>:995 </dev/null | head -5

# 4) 端口是否被机房拦（从另一台机器测）
for p in 993 995 587 465 143 110 25; do timeout 5 bash -c "exec 3<>/dev/tcp/<服务器IP>/$p" 2>/dev/null && echo "$p 通" || echo "$p 不通"; done

常见错误对照：

现象	原因	处理
Authentication failed / LOGIN failed	用户名没写完整地址；或密码错	用户名必须是 xxx@域名 完整形式
能收不能发	发信端口/加密错，或没勾「需要认证」	用 587 + STARTTLS + 认证
STARTTLS not supported	服务器没配 TLS 证书	确认 .env 里有 SSL_TYPE=manual 且证书路径存在；docker compose up -d mail
一直卡在「正在连接」	端口被机房封	上面第 4 条命令确认；被拦需工单放行
提示证书错误	自签证书	见第四节；或按第四节换真证书
发出去的信进垃圾箱	PTR 未匹配 / SPF/DKIM 未配	面板 → Cloudflare 页推送 DNS；机房面板改 PTR

服务器侧看日志：

docker exec docker-mailserver sh -c "tail -50 /var/log/mail/mail.log"     # 投递/认证日志
docker exec docker-mailserver doveadm auth test boss@<域名> '密码'         # 直接验证账号密码
docker exec docker-mailserver setup email list                            # 账号清单

用脚本发信务必带上 Date 和 Message-ID 头，否则会被内容过滤器判 BAD-HEADER-0 退信 （真实客户端都会自动带，不受影响）。