Dovecot 2.3 升 2.4：缺失 dovecot_config_version 的旧配置会被直接拒读
官方配置转换器： 2.4 示例配置（已按新语法改写）：
现象
把 Dovecot 从 2.3 升到 2.4 之后，沿用原 dovecot.conf 的表现是：服务起不来，或起来了但配置不生效。2.3 的配置不按新语法改写，完全不工作。这里说两条最容易忽略的前置设置，以及后续的逐项改法。
必改的前置两项
dovecot.conf 的第一个设置必须是 dovecot_config_version，例如：
dovecot_config_version = 2.4.0
另一个新必需设置是 dovecot_storage_version：
dovecot_storage_version = 2.4.0
结构与过滤器语义
配置不再是层级结构。所有设置都是全局设置，可以写在任意位置，作用域靠 named filter / named list filter 限定。
父过滤器名称前缀会自动补全，所以
passdb sql {
query = ...
}
等价于 passdb_sql_query。但 passdb sql2 { query = ... } 会展开成并不存在的 passdb_sql2_query，不生效。
插件同理：plugin { ... } 段取消，插件设置与其它设置一样全局。mail_plugins 改为 boollist：
mail_plugins {
quota = yes
}
不再需要 mail_plugins = $mail_plugins quota 这种自引用。
具体逐条改法
变量引用
配置里的 $setting 引用必须写成 $SET:name。旧的单字母变量全部移除，改为新语法并用 | 串联过滤器：
| 旧 | 新 |
|---|---|
%d | %{user | domain} |
%n | %{user | username} |
%u | %{user} |
%h | %{home} |
%r | %{remote_ip} |
%s 分场景：在 login/auth 设置里是 %{protocol}，在 storage 设置里是 %{service}。
旧 %2.256Nu 这类写法改为：
%{user | md5 | substr(0, 8) % 256 | hex(2)}
%Hu 没有对应写法。未知或非法的 %{var} 直接报错，可能表现为认证失败。共享 namespace 里的 %%u %%n %%d 变为 $user $username $domain，其它设置里用 %{owner_user} 等。
passdb / userdb
段必须带名字。passdb { } 报错，要写成：
passdb passwd-file {
passwd_file_path = ...
}
旧的 args = 一串参数 改为独立设置，例如：
userdb static {
fields {
uid = ...
gid = ...
}
}
userdb 字段可以设空值；在 2.3 里空值会变成 yes。
mail_location 拆分
# before
mail_location = maildir:~/Maildir:LAYOUT=fs
# after
mail_driver = maildir
mail_path = ~/Maildir
mailbox_list_layout = fs
旧串里的 INDEX= / CONTROL= 变成 mail_index_path / mail_control_path。mail_home 里的 %d / %n 改成 %{user | domain} / %{user | username}。
SSL
证书路径去掉行首的 <，设置名一并更换：
# before
ssl_cert = </etc/ssl/fullchain.pem
ssl_key = </etc/ssl/private.key
ssl_dh = </etc/ssl/dh.pem
ssl_prefer_server_ciphers = yes
disable_plaintext_auth = yes
# after
ssl_server_cert_file = /etc/ssl/fullchain.pem
ssl_server_key_file = /etc/ssl/private.key
ssl_server_dh_file = /etc/ssl/dh.pem
ssl_server_prefer_ciphers = server
auth_allow_cleartext = no
ssl_server_prefer_ciphers 取值是 client / server，不再是 yes/no，默认 client。ssl_min_protocol 默认已是 TLSv1.2；auth_allow_cleartext = no 也是默认值。保留 < 写旧语法会报 "SSL certificates too long"。
.conf.ext 外部文件
dovecot-sql.conf.ext、LDAP 那套外部文件取消，SQL/LDAP 配置改为普通设置，dovecot-sql.conf.ext 可以删掉。MySQL 连接写成：
mysql 127.0.0.1 {
user = ...
password = ...
}
sql_driver = mysql
口令进了主配置，建议 chmod 600 dovecot.conf。
默认值变化
| 设置 | 2.3 | 2.4 |
|---|---|---|
protocols | imap pop3 lmtp | 不启用任何协议，须显式 protocols { imap = yes } |
mail_cache_max_headers_count | unlimited | 100（要旧行为设 0） |
mail_cache_max_header_name_length | unlimited | 100（要旧行为设 0） |
mailbox_list_drop_noselect | no | yes，\NoSelect 文件夹被丢弃 |
| anvil | chroot | 不再 chroot，以 root 运行 |
service/auth-worker/process_limit | 1 | 30 |
mail_log_prefix | 旧变量 | 改用新变量语法 |
被移除的功能
- director：改用 Lua Director，小规模部署没有对应替代。
- replicator：改用 NFS 等共享文件系统。
- Global ACL 目录：改
acl设置。 - IMAP SETQUOTA：
set_quota设置删除。 - IPC 进程：并入 anvil。
- fts-lucene / fts-squat：改用 fts-flatcurve / fts-solr。
dsync命令：改用doveadm sync。- TCP wrapper。
- 弱口令方案默认禁用，需
auth_allow_weak_schemes。 ssl-parameters.dat不再自动转换。
验证与回退
doveconf -n 输出规范化后的配置，会剥掉被父过滤器匹配的前缀；dovecot -n 同理。!include 失败即报错，通配符无匹配不算错，可用 !include_try。
Sieve 相关要单独处理：全局 Sieve 脚本需要重新 sievec 编译；sieve_script 段要手写，段名只是标识符，global 类型必须显式写 sieve_script_type = global。
实战上，改完先跑一遍 doveconf -n 再重启；升级路径是先升到 2.3 最新版再升 2.4，不要从更早版本一步跳过去；发行版层面，Arch 同时提供 dovecot 与 dovecot23（2.3 只收安全更新），Debian Trixie 直接跳到 2.4、旧配置不再兼容，急用时可先用 dovecot23 包兜底。