docker-mailserver 16.0.1 配置参数详解

docker-mailserver 16.0.1 配置参数详解：mailserver.env 声明式参数、postfix-main.cf/dovecot.cf/Rspamd override 三层覆盖逐参数改值重启实测对比，变更探测热加载边界实测。

docker-mailserverdocker-mailserver2026/10/18

docker-mailserver 16.0.1 配置参数详解

‍‍​​‌​> 目标：讲清 docker-mailserver（DMS）16.0.1 的配置体系——声明式参数文件 mailserver.env、账号数据文件与三层覆盖配置（Postfix/Dovecot/Rspamd）的参数含义、查看与修改方式，并对关键参数做"改值 → 重启 → 行为对比"实测。全部实测在 Ubuntu 22.04 + DMS 16.0.1 完成，数据目录 /opt/data/docker-mailserver/，邮件主机名 mail.example.com。

一、环境信息

  • 操作系统：Ubuntu 22.04
  • docker-mailserver：16.0.1（内部组件实测版本：Postfix 3.10.13、Dovecot 2.4.1-4、Rspamd 4.1.5、ClamAV 1.4.3）
  • 邮件域：example.com；已建账号：admin@example.com、user@example.com（密码 q1w2e3r4）
  • 数据目录：/opt/data/docker-mailserver/（config/ 为本文核心：账号数据 + 覆盖配置）
  • 管理脚本：/opt/data/docker-mailserver/setup.sh（v16.0.1 官方版）
  • 配置文件位置一览（实测）：
/opt/data/docker-mailserver/
├── mailserver.env                    # 声明式总开关（本文主角）
└── config/
    ├── postfix-accounts.cf           # 账号数据（setup.sh 维护）
    ├── postfix-virtual.cf            # 别名表（setup.sh 维护）
    ├── dovecot-quotas.cf             # 配额表（setup.sh 维护）
    ├── postfix-main.cf               # Postfix 主配置覆盖（手工，本文 5.1 实测）
    ├── dovecot.cf                    # Dovecot 配置覆盖（手工，本文 5.2 实测）
    └── rspamd/
        ├── dkim/                     # DKIM 密钥（setup config dkim 生成）
        └── override.d/milter_headers.conf   # Rspamd 模块覆盖（手工，本文 5.3 实测）

二、前置条件

  1. 已按《docker-mailserver Docker Compose 部署指南》完成部署并可登录管理（本文所有参数修改均在该基础上操作）；
  2. 熟悉两个基础查看工具：postconf（Postfix 生效值）与 doveconf -h（Dovecot 生效值），两者在邮件服务器上开箱可用；
  3. 理解本文"重启"与"重建"两个动作的严格区别（这是 DMS 配置生效的第一关键，实测证据见第三章）：
    • 重启（仅重启服务进程）：docker compose restart mailserver
    • 重建（销毁实例重新创建，重新执行全部配置初始化）：docker compose up -d --force-recreate
  4. 本文为配置专题篇，涉及命令均可独立执行；部署主线不在本文重复。

三、参数查看与修改方式

DMS 的参数分三类，查看与修改方式各不相同：

第一类：声明式开关（mailserver.env）。KEY=VALUE 形式，控制组件启停、TLS、安全策略等。修改后必须重建实例才生效（env 是实例创建时注入的）。查看当前生效组件：docker exec dms-16.0.1-mail ps aux 或直接看启动日志的组件注册段。

第二类：账号数据文件（config/postfix-accounts.cf、postfix-virtual.cf、dovecot-quotas.cf）。不手工编辑，全部经 setup.sh 维护；内部变更探测机制约 2 秒内自动应用（实测 alias add 后立刻可见 email list 显示别名，无需任何重启）。

第三类：细粒度覆盖文件（config/postfix-main.cf、config/dovecot.cf、config/rspamd/override.d/*.conf）。手工创建，分别对 Postfix 主配置、Dovecot 配置、Rspamd 模块做增改。实测生效规则：

覆盖文件生效方式（实测）验证命令
rspamd/override.d/*.conf落盘约 2 秒内自动热加载rspamadm configdump <模块>
postfix-main.cf / dovecot.cf仅在实例重建时应用；restart 被跳过postconf <键> / doveconf -h <键>

⚠️ 实测关键证据（改 postfix-main.cf 不生效的定位过程）：写入覆盖文件后 docker compose restart mailserver，postconf message_size_limit 仍返回默认值；启动日志出现 Container was restarted. Skipping most setup routines.，且 /etc/postfix/main.cf 的修改时间停在首次创建时刻——证明 restart 跳过了配置合并阶段。改用 up -d --force-recreate 后立即生效（见 5.1）。

docker 字样仅出现在上述部署动作与实例操作处——docker-mailserver 的官方管理形态即如此（组件名亦来源于此）；下文参数与行为对比均为邮件服务功能视角。

四、参数总览

mailserver.env 官方模板 700+ 行，绝大多数键保持默认即可。下表为部署决策必须明确的关键键与模板实测默认值：

分类键模板默认建议值（实测采用）
组件开关ENABLE_RSPAMD01
组件开关ENABLE_CLAMAV01
组件开关ENABLE_AMAVIS10
组件开关ENABLE_OPENDKIM10
组件开关ENABLE_OPENDMARC10
组件开关ENABLE_POLICYD_SPF10
组件开关ENABLE_FAIL2BAN01
组件开关ENABLE_POP3空（关）空
组件开关ENABLE_FETCHMAIL00
组件开关ENABLE_POSTGREY00
TLSSSL_TYPE空manual
TLSSSL_CERT_PATH / SSL_KEY_PATH空/etc/dms/tls/fullchain.pem / /etc/dms/tls/privkey.pem
身份SPOOF_PROTECTION空（关）1
身份PERMIT_DOCKERnonenone
身份POSTMASTER_ADDRESS空空（按域名默认）
垃圾处置MOVE_SPAM_TO_JUNK11
垃圾处置MARK_SPAM_AS_READ00
评分ENABLE_SPAMASSASSIN00
时区TZ空Asia/Shanghai

💡 技术拓展：ENABLE_OPENDKIM/OPENDMARC/POLICYD_SPF/AMAVIS 与 ENABLE_RSPAMD 是两代反垃圾栈的开关。OpenDKIM/policyd-spf/Amavis 是经典分立组件链路（各自独立进程、各管一段）；Rspamd 把 DKIM/SPF/DMARC 签验、评分、病毒调度整合为一个高性能引擎。实测 v16 同开两栈会得到启动警告，且 DKIM 签名只能由其中一套产生——生产上二选一，选 Rspamd（理由与警告原文见 5.3）。

五、核心参数分类详解（改值 → 重启 → 行为对比实测）

5.1 组件开关类：双反垃圾栈冲突实测

改值：首次部署保持模板默认（ENABLE_RSPAMD=0 + 旧栈四项=1），启动后叠加开启 ENABLE_RSPAMD=1，日志出现并存警告；将旧栈四项改 0 重建，警告消失。

实测对比：

（两栈并存时的启动日志）
2026-10-18 08:28:33+08:00 INFO  start-mailserver.sh: Enabling Rspamd email worker
2026-10-18 08:28:33+08:00 WARN  start-mailserver.sh: Running Rspamd alongside Amavis/OpenDKIM/OpenDMARC/policyd-spf is not recommended...

（旧栈全部关闭、Rspamd 单栈后的完整启动，无警告）
2026-10-18 08:47:40+08:00 INFO  start-mailserver.sh: Welcome to docker-mailserver v16.0.1
2026-10-18 08:47:42+08:00 INFO  start-mailserver.sh: mail.example.com is up and running

验证：rspamc -h 127.0.0.1:11334 counters 有计数输出（Rspamd 在工作），postconf smtpd_milters 中 inet:127.0.0.1:11332 挂接 Rspamd milter。

5.2 TLS 类：SSL_TYPE=manual 实测

改值：

SSL_TYPE=manual
SSL_CERT_PATH=/etc/dms/tls/fullchain.pem
SSL_KEY_PATH=/etc/dms/tls/privkey.pem

证书放置：fullchain.pem 与 privkey.pem 放入数据目录 ssl/（本实测为自签证书：openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout privkey.pem -out fullchain.pem -subj '/CN=mail.example.com' -addext 'subjectAltName=DNS:mail.example.com'，实测生成 subject=CN = mail.example.com、有效期 2026-10-18 至 2036-10-15）。

行为对比（重建前后）：

验证项SSL_TYPE 为空时SSL_TYPE=manual 重建后（实测）
启动日志有自签临时证书警告警告消失，直接 up and running
IMAPS 993未监听LISTEN 0 100 0.0.0.0:993（ss -ltn 实测）
25 端口 EHLO无 STARTTLS250-STARTTLS
587 握手—openssl s_client -starttls smtp -connect 127.0.0.1:587 实测：subject=CN = mail.example.com、New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384

5.3 身份与反伪造类：SPOOF_PROTECTION 实测

改值：SPOOF_PROTECTION=1（重建生效）。

行为对比：开启后，认证身份与 MAIL FROM 不匹配的提交被当场拒绝。实测（以 admin@example.com 认证、伪造 user@example.com 发件）：

553 5.7.1 <user@example.com>: Sender address rejected: not owned by user admin@example.com

验证：用匹配身份（admin 认证 + admin 发件）重发，正常排队（250 2.0.0 Ok: queued as ...）。注意区分：来自外部、冒充本域发件人的入站伪造由 Rspamd 按 DMARC 策略处置（实测 p=quarantine 时拒信 554 5.7.1 Spam message rejected），两道防线叠加。

5.4 Postfix 覆盖实测：message_size_limit

改值（新建 config/postfix-main.cf）：

# 邮件大小上限：默认 10240000(10MB)，调到 20MB
message_size_limit = 20480000

行为对比（改后 restart 无效 → up -d --force-recreate 后生效）：

# 重建后查看生效值
postconf message_size_limit

20480000

# 协议层同步验证（EHLO 能力）
printf 'EHLO probe\r\nQUIT\r\n' | nc -w 5 127.0.0.1 25 | grep SIZE

250-SIZE 20480000

结论：默认上限 10MB（postconf message_size_limit 重建前实测 10240000），覆盖后 20MB 且 EHLO 能力同步变化——这正是"信大了一点就拒收"类问题的标准调法。

5.5 Dovecot 覆盖实测：mail_max_userip_connections

改值（新建 config/dovecot.cf）：

# 单 IP 单账号并发连接数：默认 10，调到 20
mail_max_userip_connections = 20

行为对比（重建后）：

doveconf -h mail_max_userip_connections

20

结论：默认值 10；多客户端同账号并发（手机+电脑+网页）易触顶报 Too many concurrent IMAP connections，按用户规模放大。

5.6 Rspamd 覆盖实测：milter_headers 启用 Authentication-Results

改值（新建 config/rspamd/override.d/milter_headers.conf）：

# documentation: https://www.rspamd.com/doc/modules/milter_headers.html

use = ["x-spam", "authentication-results"];
extended_spam_headers = true;

行为对比：默认仅注入 X-Spam 扩展头；加覆盖文件后约 2 秒热加载（无需重建），下一封入站信即出现 Authentication-Results 头。实测入站信头（节选）：

Authentication-Results: mail.example.com; dmarc=pass (policy=quarantine) header.from=example.com
X-Spamd-Result: default: False [2.90 / 15.00]; R_DKIM_ALLOW[example.com:s=mail](0.00)[];
    DMARC_POLICY_ALLOW(-0.50)[example.com];R_SPF_ALLOW(-0.20)[+ip4:...]

验证：rspamadm configdump milter_headers 可见 use 含 authentication-results；DKIM/SPF/DMARC 三态（pass/softfail/fail）的完整头字段与处置实测见《docker-mailserver 安全加固指南》。

5.7 账号数据类：配额实测

改值（setup.sh 维护，禁止手编 dovecot-quotas.cf）：

./setup.sh quota set user@example.com 1G

行为对比（实测 ./setup.sh email list）：

改前：* user@example.com ( 5.0K / ~ ) [0%]
改后：* user@example.com ( 5.0K / 1.0G ) [0%]

验证：

doveadm quota get -u user@example.com

Quote name Type    Value    Limit   %
STORAGE     bytes   5120     1073741824 0

结论：配额约 2 秒内热应用，IMAP 层直接生效；删除用 ./setup.sh quota del <地址>。

六、生产配置模板

适用场景：8GB 内存、100GB SSD 磁盘、50 人以内团队、自有域名与证书的生产基线（本批全部键值实测验证）：

# mailserver.env —— 生产基线
TZ=Asia/Shanghai
ENABLE_RSPAMD=1
ENABLE_CLAMAV=1
ENABLE_AMAVIS=0
ENABLE_OPENDKIM=0
ENABLE_OPENDMARC=0
ENABLE_POLICYD_SPF=0
ENABLE_FAIL2BAN=1
SPOOF_PROTECTION=1
PERMIT_DOCKER=none
MOVE_SPAM_TO_JUNK=1
MARK_SPAM_AS_READ=0
SSL_TYPE=manual
SSL_CERT_PATH=/etc/dms/tls/fullchain.pem
SSL_KEY_PATH=/etc/dms/tls/privkey.pem
LOG_LEVEL=info

配套覆盖文件模板（磁盘资源宽裕时的两项常用放大，实测见 5.4/5.5）：

# config/postfix-main.cf
message_size_limit = 20480000

# config/dovecot.cf
mail_max_userip_connections = 20

⚠️ 组合说明：ENABLE_FAIL2BAN=1 要求实例具备 NET_ADMIN 能力（Compose cap_add: [NET_ADMIN]），否则 fail2ban 无法操作防火墙；SSL_TYPE=manual 要求 ssl/ 目录已放置双证书文件。模板未含 dns: 自定义项——仅在内网自建 DNS 发布测试域记录时才需要（本文实验环境即如此），生产使用公网解析。

七、常见问题

Q1：为什么改了 postfix-main.cf / dovecot.cf 重启后不生效？ 这两类文件只在实例创建时合并进主配置；restart 跳过该阶段（实测日志：Container was restarted. Skipping most setup routines.）。必须 docker compose up -d --force-recreate。而 rspamd/override.d/ 与账号类文件是约 2 秒热加载的，两者机制不同。

Q2：email list 对新账号报 doveadm ... User doesn't exist 与 ERROR 行？ 实测为无害告警：账号尚未收到第一封邮件、配额目录未生成所致（回显全文见《docker-mailserver Docker Compose 部署指南》Q3），收到首封邮件后自愈。

Q3：DKIM 密钥的 selector 是什么？能改吗？ 实测 ./setup.sh config dkim 默认 selector 为 mail（生成 mail.example.com.key/pub 与 mail._domainkey.example.com DNS 记录）。可用参数自定义（./setup.sh config dkim help 查看用法）；selector 改动需同步改 DNS 记录。

Q4：Rspamd 的默认拒信阈值是多少？ 实测入站信头 X-Spamd-Result: default: False [2.90 / 15.00] 中可见：当前得分 2.90，15.00 为拒信动作阈值；11.00 起进入垃圾处置（配合 MOVE_SPAM_TO_JUNK=1 改投 Junk，实测一封 10.00 分邮件被投递至 .Junk/）。阈值可通过 config/rspamd/override.d/actions.conf 覆盖。

Q5：日志时区不对？ TZ=Asia/Shanghai 需重建生效；实测设置后日志形如 2026-10-18T08:59:44+08:00。另注意日志文件本身位于 /var/log/mail/mail.log（挂载持久化），与应用控制台输出并存。

Q6：改了 env 后如何确认组件真的启停了？ 重建后看两处：启动日志组件注册行（如 Enabling Rspamd email worker）与进程表（ps aux 应含 rspamd/clamd/redis/f2b 进程）；旧栈关闭后 ps aux 不应再有 amavis/opendkim 进程。

八、参考链接

  • 环境变量官方说明：https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/
  • Postfix/Dovecot/Rspamd 官方参数文档：https://www.postfix.org/postconf.5.html、https://doc.dovecot.org/、https://www.rspamd.com/doc/
  • DMS override 机制说明：https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/override-defaults/dovecot/
  • 账号管理官方文档：https://docker-mailserver.github.io/docker-mailserver/latest/config/accounts/