【Mail Server 系列文：第 11 篇】

在前 10 篇文章中，我們已經完成整套企業級 Mail Server 的建置：
Postfix、Dovecot、Amavis、SpamAssassin、ClamAV、Piler、Manticore、Roundcube、Pilermilter、MariaDB、Docker 網路、Let’s Encrypt 等。

本篇將整理：

• 常見錯誤與排查流程
• 完整 troubleshooting checklist
• 各服務常用 debug 指令
• FAQ（最常被問的問題）
• 如何快速判斷是哪個模組出錯

你可以把這篇當成 “Mail Server 醫療手冊”。

---

🔶 1. 如何判斷是哪一個服務出問題？（總覽）

郵件系統有 8 個常見故障來源：

場景	最可能原因
無法寄信（Out → Internet）	Postfix → Amavis → DNS → Firewall
無法收信（Internet → In）	DNS → MX → Postfix → Amavis
Webmail 無法登入	Dovecot、TLS、防火牆
IMAP/SMTP 客戶端無法登入	Dovecot、SASL、TLS
信件無法掃毒或分類	Amavis、SpamAssassin、ClamAV
反垃圾過濾異常	SpamAssassin、Rules、Bayes 資料庫
郵件搜尋結果不完整	Manticore index / Piler config
無法登入 Piler 查詢	IMAP Auth、config-site.php

下面會逐一拆解。

---

🔶 2. 無法寄信 Troubleshooting（Out → Internet）

🔍 2.1 通常的錯誤訊號：

• mailq 堆積
• 郵件退件（5.7.1、5.4.4、4.4.3）
• Gmail / Outlook 直接拒信

🔧 2.2 Debug 流程（由下而上）

Step 1：檢查 Postfix queue

postqueue -p

若大量 deferred：

mailq | less

查看退件原因。

---

Step 2：用 swaks 測試外送

swaks --to your@gmail.com --server postfix --port 25

若卡住 = 100% firewall 問題（常見）。

---

Step 3：檢查 DNS（最常見）

dig A mail.yourdomain.com
dig MX yourdomain.com
dig TXT yourdomain.com (SPF)

---

Step 4：檢查 Amavis 是否正常

nc -z amavis 10024
nc -z amavis 10026

---

Step 5：檢查 DKIM / SPF / DMARC

用 mail-tester.com 或：

dig TXT default._domainkey.yourdomain.com

---

🔶 3. 無法收信 Troubleshooting（Internet → In）

🔍 常見症狀

• 對方郵件伺服器報錯 “Connection timed out”
• Gmail 提示 “Recipient server not responding”
• 本機看不到 inbound log

🔧 Debug 流程

Step 1：MX 設定正確？

dig MX yourdomain.com

應該指到： mail.yourdomain.com，而不是 webserver。

---

Step 2：外部測試 25 port

從外部 Linux：

nc -zv mail.yourdomain.com 25

若 timeout = 防火牆問題。

---

Step 3：Postfix 是否有收到 inbound？

tail -f /var/log/postfix/postfix.log

如果沒有任何 inbound log：

→ packet 被擋在 host firewall。

---

Step 4：Amavis 是否能回投 Postfix？

看 10025 log：

grep 10025 /var/log/postfix/postfix.log

若卡住 = amavis queue 問題。

---

🔶 4. Webmail（Roundcube）無法登入 / 收信

⭐ 常見錯誤訊息：

• “Connection to IMAP server failed”
• “Login failed”
• HTTP 502 / 504

🔧 Debug 流程

Step 1：確認 Roundcube 連到 Dovecot

docker exec -it webmail ping dovecot

---

Step 2：測試從容器內 telnet IMAP

openssl s_client -connect dovecot:993

若出現：

unknown protocol

表示 你把 993 接成非 TLS port（最常見）。

---

Step 3：檢查防火牆（重要）

若 host 阻擋 172.18.0.x → 172.18.0.1 → port 993
你會永遠無法登入 Webmail。

參考你的規則：

iptables -I DOCKER-USER 1 -s 172.18.0.0/16 -d 172.18.0.1 -j ACCEPT

---

🔶 5. Dovecot 常見問題排查

🔍 5.1 用戶無法登入

看日誌：

tail -f /var/log/dovecot/dovecot.log

常見錯誤：

• 密碼錯誤（MySQL mapping 有誤）
• 無法連到 mysql server
• TLS 問題：SNI 憑證錯誤

---

🔍 5.2 LMTP 投遞失敗（Postfix → Dovecot）

Log 顯示：

lmtp: Fatal: ...

檢查：

nc -z dovecot 24

若失敗 → Dovecot LMTP 未啟動 / master.conf 設定錯誤。

---

🔶 6. SpamAssassin / Amavis 常見問題

❗ 6.1 Amavis 卡住，Postfix 信件無法過濾

tail -f /var/log/amavis/amavis.log

常見：

• “timed out waiting for SA”
• “ClamAV not responding”

解法：

docker restart amavis spamd clamav

---

❗ 6.2 SpamAssassin 動作異常（不分類）

檢查 spamd 是否在聽：

nc -z spamassassin 783

如果 sa-learn remote 無作用：

→ 通常是你忘記在 global sieve 中設定：

pipe :copy "sa-remote-learn-ham.sh"

---

🔶 7. Piler 常見問題排查

🔍 7.1 無法登入（IMAP Auth 問題）

看 piler error log：

tail -f /var/log/apache2/archive_error.log

或 piler.log：

tail -f /var/log/piler/*

若出現：

authentication failed

檢查 config-site.php：

$config['ENABLE_IMAP_AUTH'] = 1;
$config['IMAP_HOST']        = 'dovecot';
$config['IMAP_PORT']        = 993;

---

🔍 7.2 搜尋中文無結果

→ 99% 是 Manticore 未使用你自訂的 ICU tokenizer image

檢查：

docker logs manticore | grep chinese

---

🔍 7.3 Piler 無法接收 archive 郵件

確定 Postfix：

always_bcc = piler@archive.local

container must resolve archive.local：

docker exec postfix ping archive.local

若不能 → 你漏加：

--add-host archive.local:172.18.0.1

---

🔶 8. Manticore 常見問題排查

🔍 8.1 無法啟動（9306 不可連）

在 entrypoint.sh 中：

wait_for_9306

手動測試：

mysql -h manticore -P 9306

如果不可連：

→ 你把 data 目錄 chown 錯誤
→ 或 index corrupted，需要：

rm -rf piler_manticore/*

重新建立。

---

🔶 9. Postfix 最常見錯誤大全

以下為你系統最常遇到的錯誤：

---

❗ 9.1 “5.4.4 relay access denied”

原因：

• relay_domains
• recipient restrictions
• transport_maps 找不到

---

❗ 9.2 “Name or service not known”

→ 你有用到 docker name，但容器不在同網路。

---

❗ 9.3 “connection refused 10024”

→ Amavis 掛掉。

---

❗ 9.4 DKIM failed

看 amavis：

grep DKIM /var/log/amavis/amavis.log

原因通常是：

• DNS TXT 列太長（需要換行）
• domain 未加入 amavisd.conf

---

🔶 10. FAQ — 常見問題

---

Q1：為什麼我寄到 Gmail / Outlook 會進垃圾郵件？

A：檢查：

• SPF 錯誤
• DKIM 沒過
• DMARC 不一致
• Reverse DNS 沒設定

---

Q2：客戶抱怨收不到信，但我郵件系統正常？

A：很常見的原因是：

• 對方 DNS 錯誤
• 對方黑名單
• 退信被對方網管擋掉

---

Q3：我可以讓用戶用 EXE 或 zip 嗎？

Amavis 預設會擋。

你可以改：

$banned_filename_re

---

Q4：我可以新增多個 domain 嗎？（Yes）

只要在 postfixadmin 加上 domain 即可。

---

Q5：Webmail 可否使用 OAuth / 2FA？

可以，但 Roundcube 需額外插件或前置反向代理 OAuth。

---

🔶 11. 結語：你的郵件系統已進入企業級維運階段

經過本系列 11 篇文章，你已經擁有：

• 完整可控、全模組化的 Mail Server
• 支援中文搜尋
• 具備備份、監控、記錄
• 有完整安全與性能調校
• 具備抗垃圾郵件與病毒能力
• 全 Docker 架構，可自由調整、升級

這已經不只是「可用」的郵件系統
而是 企業級、長期維運、安全可控 的郵件服務平台。