一、模块定位与作用

• 协议代理
  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 的 POP3
        protocol    pop3;

        # 仅允许 APOP 与 CRAM-MD5
        pop3_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;            # POP3S
        protocol    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 代理并在生产环境中取得稳定运行。祝你部署顺利！