一、模塊定位與作用

• 協議代理
  ngx_mail_pop3_module 讓 NGINX 能夠充當 POP3 代理：客戶端與后端 POP3 服務器之間的所有請求均轉發到 NGINX，由 NGINX 負責與后端會話邏輯。
• 認證方式控制
  通過 pop3_auth 指令指定允許客戶端使用的 POP3 認證方法（如 PLAIN、APOP、CRAM-MD5、EXTERNAL），確保僅符合后端要求的方式生效。
• 功能協商
  pop3_capabilities 指令定義可向客戶端通告的 POP3 擴展列表（CAPA 響應），與后端實現保持一致，讓客戶端知道可用命令。

二、核心指令詳解

1. pop3_auth

pop3_auth method ...;

Default：pop3_auth plain;
Context：mail, server

功能

• 定義允許客戶端使用哪些 POP3 身份驗證方式。
• 如果未顯式列出 plain，則默認仍支持 USER/PASS、AUTH PLAIN 與 AUTH LOGIN，但它們不會自動出現在 CAPA 響應中。

支持的認證方式

方法	說明
plain	常規明文認證，包括：USER <username>/PASS <password>，AUTH PLAIN，和 AUTH LOGIN。 在 TLS 加密下使用較安全，否則存在明文傳輸風險。
apop	APOP （MD5 摘要式）認證。后端必須存儲用戶明文密碼或可計算 MD5，否則無法使用。
cram-md5	AUTH CRAM-MD5 （質詢-響應式）認證。同樣要求后端保存明文密碼或等價 MD5 值。
external	AUTH EXTERNAL，用于客戶端通過 TLS 客戶端證書進行認證。（1.11.6+）

示例

mail {server {listen      110;               # 不加 SSL 的 POP3protocol    pop3;# 僅允許 APOP 與 CRAM-MD5pop3_auth   apop cram-md5;# 將客戶端請求轉發到后端 POP3 服務器proxy_pass  pop3_backend:110;}
}

• 客戶端僅能使用 APOP 或 AUTH CRAM-MD5，若嘗試明文 USER/PASS 或 AUTH PLAIN，將被 NGINX 攔截并拒絕。

2. pop3_capabilities

pop3_capabilities extension ...;

Default：pop3_capabilities TOP USER UIDL;
Context：mail, server

功能

• 定義當客戶端執行 CAPA 命令時，NGINX 向客戶端返回的 POP3 擴展列表。
• NGINX 會自動將 pop3_auth 中指定的 SASL 認證方式，以及 starttls（如果啟用）加入到 CAPA 響應。
• 建議在此列出后端 POP3 服務器實際支持的擴展，以保證客戶端在認證后能夠使用相應命令。

常見擴展

擴展	說明
TOP	支持 TOP <msg> <lines> 命令，用于僅獲取郵件頭部或部分正文行。
USER	傳統用戶名/密碼登錄（USER/PASS）。
UIDL	支持 UIDL 命令，可獲取郵件唯一 ID，常用于客戶端本地同步。
SASL	列出允許的 SASL 認證機制（如 PLAIN、LOGIN、CRAM-MD5）。
PIPELINING	支持復合命令管道，可一次發送多個請求減少網絡往返。
STLS	支持 STLS 命令，可在普通端口上升級到 TLS。

示例

mail {server {listen      995 ssl;            # POP3Sprotocol    pop3;pop3_auth         plain cram-md5;pop3_capabilities TOP USER UIDL SASL PIPELINING;ssl_certificate     /etc/nginx/ssl/mail.crt;ssl_certificate_key /etc/nginx/ssl/mail.key;ssl_protocols       TLSv1.2 TLSv1.3;ssl_session_cache   shared:mail_ssl:10m;ssl_session_timeout 10m;# 反向代理到后端 POP3 服務器proxy_pass         pop3_backend:110;}
}

• 當客戶端執行 CAPA 時，NGINX 將返回：

  +OK Capability list follows
  TOP
  USER
  UIDL
  SASL PLAIN CRAM-MD5
  PIPELINING
  STLS      # 如果 starttls on
  .
  

• 客戶端據此知道可用的認證方式（看到 SASL PLAIN CRAM-MD5）、TOP、UIDL 等功能。

三、綜合示例：POP3 代理配置

結合上述指令，下面給出一個生產環境常用的 POP3S 代理示例。

worker_processes auto;events { worker_connections 1024; }mail {# 全局啟用 STARTTLS（如需在 110 端口上允許加密）starttls   on;server {# 監聽 POP3S（TLS/SSL）listen      995 ssl;protocol    pop3;# 只允許明文（USER/PASS/PLOGIN）和 CRAM-MD5 認證pop3_auth      plain cram-md5;# 明確向客戶端通告支持的擴展：TOP, USER, UIDL, PIPELINING# NGINX 會自動添加 SASL PLAIN CRAM-MD5 和 STLS（若啟用）pop3_capabilities TOP USER UIDL PIPELINING;# TLS 基本配置ssl_certificate     /etc/nginx/ssl/pop3.crt;ssl_certificate_key /etc/nginx/ssl/pop3.key;ssl_protocols       TLSv1.2 TLSv1.3;ssl_ciphers         HIGH:!aNULL:!MD5;ssl_session_cache   shared:mail_ssl:10m;ssl_session_timeout 10m;# 后端真實 POP3 服務器地址proxy_pass          pop3_backend:110;# 可選：讀取后端響應超時proxy_timeout       2m;# 可選：將后端的錯誤消息透傳給客戶端proxy_pass_error_message on;}
}

關鍵解析

1. listen 995 ssl; protocol pop3;

   • 強制 POP3S；客戶端需使用 TLS（如 Outlook、Thunderbird 配置端口 995）。

2. pop3_auth plain cram-md5;

   • 允許 USER/PASS 和 AUTH PLAIN（明文）與 AUTH CRAM-MD5；
   • 若后端僅支持 APOP，可改為 pop3_auth apop。

3. pop3_capabilities TOP USER UIDL PIPELINING;

   • 通告客戶端后端支持的擴展；
   • NGINX 會自動補入 SASL PLAIN CRAM-MD5，以及 STLS（因為 starttls on;）。

4. TLS 配置

   • ssl_certificate/ssl_certificate_key 存放 PEM 格式服務器證書與私鑰；
   • ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; 強制使用安全套件；
   • ssl_session_cache shared:mail_ssl:10m; ssl_session_timeout 10m; 啟用共享會話緩存，加速握手。

5. proxy_pass pop3_backend:110;

   • 將客戶請求轉發到后端 pop3_backend 主機的 110 端口；
   • pop3_backend 可是 DNS 名稱或 Upstream 均可。

四、最佳實踐與注意事項

1. 安全性優先

   • 如果允許 plain 或 login 認證，一定要在 TLS（POP3S 或 STARTTLS）下使用，避免明文泄漏；
   • 若須更高安全，可強制 pop3_auth cram-md5 或使用客戶端證書 pop3_auth external。

2. CAPA 與后端保持一致

   • 確保 pop3_capabilities 中列出的擴展，后端 IMAP/POP3 服務器能夠識別并支持；
   • 若后端不支持 PIPELINING、TOP 等，可去掉對應擴展，避免客戶端發出不受支持的命令。

3. 緩沖與性能優化

   • 默認緩沖（4K 或 8K）適合大多數場景；若后端批量下載、TOP 命令觸發大數據傳輸，可考慮調大 imap_client_buffer（若同時配置 IMAP）或全局 TCP Buffer。

4. 日志排查

   • 可通過 NGINX error_log 和 mail_log 記錄 POP3 命令與錯誤，以便排查認證或轉發失敗原因；
   • proxy_pass_error_message on; 可以讓客戶端直接看到后端返回的錯誤內容（例如：-ERR invalid credentials）。

五、總結

通過 ngx_mail_pop3_module，你能夠在 NGINX 這一高性能代理層靈活管理 POP3 協議與認證方式，同時利用 NGINX 強大的并發、TLS 加速與日志特性，為后端郵件系統提供高可用、安全可靠的代理服務。希望本文的指令詳解與配置示例，能夠幫助你快速上線 POP3 代理并在生產環境中取得穩定運行。祝你部署順利！