Mailu 2024.06.65 配置参数详解
Mailu 2024.06 集中式配置文件 mailu.env 逐组详解：通用/邮件/Web/管理员自动创建/高级/反病毒/数据库与 Webmail 八组参数的默认值与生效机制，配套参数级实测验证（TLS 证书、250-SIZE、PORTS 587、自动建号、API_TOKEN、RECIPIENT_DELIMITER 扩展地址投递）。
Mailu 2024.06.65 配置参数详解
目标：逐一解析 Mailu 2024.06 集中式配置文件
mailu.env的关键参数——按官方配置参考（mailu.io/2024.06/configuration.html）的分组展开，标注默认值、生效机制与踩坑点，并对 2024.06.65 实际部署做参数级实测验证（证书回显、端口行为、自动建号、扩展地址投递等）。与《Mailu Docker Compose 部署指南》配套阅读；组件背景与同类对比见《Mailu 2024.06.65 介绍与选型指南》。
一、环境信息
- Mailu：2024.06.65（2024.06 稳定分支锁定版）
- 操作系统：Ubuntu 22.04（x86_64）；部署形态与目录、端口规划见本专栏部署指南篇
- 参数依据：官方配置参考
https://mailu.io/2024.06/configuration.html（查询日期 2026-10-21），逐组与本地部署文件交叉核对 - 实测环境：本专栏部署指南篇搭建的
mail.example.com（主域example.com）服务栈，网络段 10.89.56.0/24
二、配置体系总览
Mailu 的全部服务配置收敛在一份 mailu.env：服务栈内每个服务启动时读取同一份文件（部署指南篇 4.3 节的 env_file 挂载方式），因此"改一处、管全栈"。要点：
- 修改生效方式：
mailu.env在服务启动时读取，改完必须重建服务（docker compose up -d会自动重建受影响服务）；仅restart不会重新读取。部署指南篇第十章 Q4 有实测记录。 - 参数优先级：
mailu.env为全局值；部分能力支持用户/域级覆盖（如垃圾分阈值spam_threshold存在用户属性，DEFAULT_SPAM_THRESHOLD只管新用户初始值）。 - 本地覆盖通道：各服务的
/overrides目录可覆盖服务内配置文件（Postfixmain.cf、Dovecotconf.d等），见部署指南篇第七章；mailu.env管不到的细节走这条通道。 - 官方参数清单：官方配置参考明确说明 "This page explains the variables found in mailu.env"——本文按其原始分组（Common / Mail settings / Web settings / Admin account - automatic creation / Advanced settings / Antivirus settings / Database settings / Webmail settings / Header authentication）整理。
三、通用组（Common configuration）
| 参数 | 默认值 | 说明 |
|---|---|---|
SECRET_KEY | 无（必填） | 16 字节随机串，用于登录态 Cookie 签名等关键加密用途，官方要求每套部署必须更换（pwgen 16 1 或 openssl rand -base64 12 生成）；更换后所有已登录会话失效 |
DOMAIN | 无（必填） | 主邮件域：退信发件人、postmaster 等技术地址都用它生成 |
HOSTNAMES | 无（必填） | 对外主机名列表（逗号分隔），第一个为主主机名，SMTP/IMAP 对外报文中的名字与它对应；自签/申请证书的 CN/SAN 应覆盖它 |
SUBNET | 无（必填） | 服务栈网络地址段（官方原文 "defines the address range of the docker network used by Mailu"），必须与编排文件里的网桥子网一致，否则服务互访异常；与宿主已用网段冲突时才需修改 |
POSTMASTER | 无（必填） | postmaster 技术地址的本地部分，官方建议配一个通用值并用别名转发 |
TLS_FLAVOR | 无（必填） | 证书获取策略五选一：letsencrypt（自动签发+续期）、mail-letsencrypt（仅邮件端口用 LE）、cert（自带证书，读 /certs/cert.pem+key.pem）、mail（仅邮件端口用自带证书）、notls（不加密，不建议） |
AUTH_RATELIMIT_IP | 5/hour | 按 IP 网段的认证限速（防密码喷洒），网段粒度由 AUTH_RATELIMIT_IP_V4_MASK（默认 /24）与 AUTH_RATELIMIT_IP_V6_MASK（默认 /48）控制 |
AUTH_RATELIMIT_USER | 50/day | 按账号的认证尝试限速（防爆破）；同账号同口令的重复尝试只计一次 |
AUTH_RATELIMIT_EXEMPTION_LENGTH | 86400 | 成功登录后该 IP 免限速的秒数（照顾 NAT 后多用户） |
AUTH_RATELIMIT_EXEMPTION | 空 | 完全免限速的网段 CIDR 列表（配 0.0.0.0/0 等于关闭限速，慎用） |
DEFAULT_SPAM_THRESHOLD | 80 | 新用户默认垃圾分容忍度（Rspamd 分值），用户属性可单独调整 |
DISABLE_STATISTICS | False | 是否关闭匿名统计上报，在意隐私可设 True |
WILDCARD_SENDERS | 空 | 允许"冒充任意发件人"的用户地址列表（spoofing 白名单），仅在确有系统发信需求时配置 |
TZ | Etc/UTC | 时区（Region/City 格式）。官方警告：如发现日志时间与远端 MTA 对不上，官方建议改宿主为 UTC 而不是改 TZ——UTC 最利于跨服务器日志比对 |
⚠️
TZ实测：本部署设Asia/Shanghai后，服务内时间显示Wed Oct 21 09:33:32 CST 2026（与宿主一致）。若追求日志关联性，公网部署建议保持默认 UTC。
四、邮件设置组（Mail settings）
| 参数 | 默认值 | 说明 |
|---|---|---|
MESSAGE_SIZE_LIMIT | 50000000 | 单封邮件大小上限（字节）；过大易被塞垃圾撑爆磁盘，过小丢合法邮件。实测生效证据：25 端口 EHLO 回显 250-SIZE 50000000 |
MESSAGE_RATELIMIT | 200/day | 单用户日发信上限（防账号被盗后批量外发）；豁免账号列表 MESSAGE_RATELIMIT_EXEMPTION |
RELAYNETS | 空 | 免认证中继网段（逗号分隔），配错就是开放中继，官方原文警告 "This should be used with great care… may turn your Mailu instance into an open-relay!" |
RELAYHOST | 空 | 全部出站邮件走指定 smarthost，格式 [HOST]:PORT；需要认证时配 RELAYUSER/RELAYPASSWORD |
OUTBOUND_TLS_LEVEL | 空（opportunistic TLS） | 出站 TLS 策略，可设 encrypt/secure；用支持 TLS 的中继时官方建议显式加密 |
DEFER_ON_TLS_ERROR | True | DANE/MTA-STS 附加校验失败时是否缓发邮件 |
INBOUND_TLS_ENFORCE | False | 入站强制 STARTTLS。官方明确警告不要开启（违反 RFC 3207，会导致不支持 STARTTLS 的老服务器无法投递进来） |
SCAN_MACROS | True | 宏邮件拦截（基于 oletools/mraptor 识别恶意宏文档）；部署指南篇因未启用该可选能力设为 false |
FETCHMAIL_ENABLED | True | 启用外域邮箱拉取功能（管理界面显示该项）；注意官方原文指出该服务需在编排中额外部署才真正生效 |
FETCHMAIL_DELAY | 600 | fetchmail 拉取间隔秒数：太短容易被外部服务拉黑，太长收信不及时 |
RECIPIENT_DELIMITER | + | 本地部分与扩展部分的分隔字符（可设多个如 +-），用于无限子地址 |
DMARC_RUA / DMARC_RUF | 空 | DMARC 聚合报告/失败报告邮箱的本地部分（如 admin → admin@DOMAIN） |
FULL_TEXT_SEARCH | en | IMAP 全文检索语言列表（逗号分隔语言代码），设 off 关闭（性能敏感场景） |
DEFAULT_QUOTA | 空 | 域未单独配置配额时，新邮箱的默认配额 |
COMPRESSION | 空 | 邮件落盘压缩算法：gz/bz2/zstd；官方建议：文件系统原生压缩（如 ZFS/btrfs）更高效，就别用它 |
COMPRESSION_LEVEL | 6 | 压缩级别 |
PORTS | 25,80,443,465,993,995,4190 | front 启用的协议端口清单。IMAP(143)/POP3(110)/Submission(587) 默认关闭，需要时追加 110,143,587；官方明确 25/465/993 不可禁用。实测踩坑详见部署指南篇第十章 Q1 |
💡
RECIPIENT_DELIMITER实测：默认+生效时向user1+news@example.com投递，服务器回250 2.0.0 Ok: queued as CE9B78C2280，随后 IMAPS 登录user1查询SEARCH ALL返回* SEARCH 1 2 3（含原两封共三封）——扩展地址正确落进user1主信箱。
五、Web 设置组（Web settings）
| 参数 | 默认值 | 说明 |
|---|---|---|
WEB_ADMIN | /admin | 管理界面路径 |
WEB_WEBMAIL | /webmail | Webmail 路径 |
WEB_API | /api | RESTful API 路径（Swagger UI 挂在其下，如 /api/v1/swagger.json） |
WEBROOT_REDIRECT | /webmail | 根路径跳转目标；设空则未匹配路径返回 404；设 none 表示用 Nginx override 自管 location / |
SITENAME | Mailu | 站点名（管理台/Webmail 菜单展示） |
WEBSITE | 空 | 面板菜单外链站点 URL |
LOGO_URL / LOGO_BACKGROUND | 空 | 自定义 Logo 与背景色 |
官方注意事项：以上路径都必须以 / 开头；WEBROOT_REDIRECT 不能指向未启用的功能（如 WEBMAIL=none 时指向 /webmail 会 404）。
💡 路径联动实测：部署篇
WEBROOT_REDIRECT=/admin生效后，访问https://127.0.0.1:8132/返回308 -> https://127.0.0.1:8132/admin/?homepage，未登录最终落到统一登录页/sso/login（HTTP 200）。
六、管理员自动创建组（Admin account - automatic creation）
| 参数 | 默认值 | 说明 |
|---|---|---|
INITIAL_ADMIN_ACCOUNT | 无 | 初始管理员本地部分 |
INITIAL_ADMIN_DOMAIN | 无 | 所属域（一般与 DOMAIN 相同） |
INITIAL_ADMIN_PW | 无 | 初始口令 |
INITIAL_ADMIN_MODE | create | 创建策略三选一：create（已存在则报错）、ifmissing（不存在才建）、update（不存在则建/存在则改口令） |
官方明确建议用 ifmissing 或 update：默认的 create 在每次重启服务时都会因账号已存在而抛异常。
⚠️ 自动建号实测：部署篇首次启动后，admin 日志输出
INFO:root:Creating initial admin account admin@example.com with mode ifmissing，全局管理员与所属域随之自动落库（CLIconfig-export user.email user.global_admin可见admin@example.com / global_admin: true）；重启后不重复创建，幂等。
七、高级设置组（Advanced settings）
| 参数 | 默认值 | 说明 |
|---|---|---|
AUTH_REQUIRE_TOKENS | False | 强制桌面客户端用应用专用令牌登录（不允许主口令），安全增强项 |
API_TOKEN | None | RESTful API 的 Bearer 令牌，最短 3 字符，用 API 必配。实测：带令牌请求 GET /api/v1/domain 返回 200，不带返回 401 |
CREDENTIAL_ROUNDS | 12 | 口令哈希轮数，调大增强抗离线破解、调小加快认证 |
SESSION_COOKIE_SECURE | True | 管理台 Cookie 的 secure 标志；仅纯 HTTP 访问管理台时才可关闭 |
SESSION_TIMEOUT | 3600 | 会话空闲超时（秒） |
PERMANENT_SESSION_LIFETIME | 108000 | 会话最长存活（秒） |
LOG_LEVEL | WARNING | 启动脚本的日志阈值（CRITICAL/ERROR/WARNING/INFO/DEBUG/NOTSET） |
LETSENCRYPT_SHORTCHAIN | False | TLS 握手是否发送 ISRG Root X1 短证书链（兼容 Android 7.1.1 以下，但降低现代设备性能） |
TLS_PERMISSIVE | true | 25 端口 STARTTLS 的密码套件是否保持最大兼容。官方强烈建议不要改（"any encryption beats no encryption"）；收紧会导致老服务器退信/明文/静默丢信 |
REAL_IP_HEADER / REAL_IP_FROM | 空 | 信任的反代头（如 X-Forwarded-For）与可信代理 IP 列表；只设前者不设后者是安全漏洞（可伪造源地址）。反代场景两个都要设 |
PROXY_PROTOCOL | 空 | front 启用 PROXY protocol 的端口列表；必须同时配 REAL_IP_FROM 且不能配 REAL_IP_HEADER，否则代理会被限速/封禁 |
PROXY_AUTH_WHITELIST | 空 | 外部代理统一认证（header 认证）的可信代理 CIDR，需同时出现在 REAL_IP_FROM；配套 PROXY_AUTH_HEADER（默认 X-Auth-Email）、PROXY_AUTH_CREATE（自动建号，注意不会自动建域）、PROXY_AUTH_LOGOUT_URL |
COMPOSE_PROJECT_NAME | mailu | 服务栈项目名前缀；多套 Mailu 并存时用它区分 |
DOMAIN_REGISTRATION | False | 是否允许用户自助注册域名（管理员在 UI 里看到注册开关） |
MASKED_NETWORKS | 空 | 日志中打码的网段（隐私合规用） |
SQLALCHEMY_DATABASE_URI | sqlite:////data/main.db | 管理库连接串；SQLALCHEMY_DATABASE_URI_ROUNDCUBE（默认 sqlite:////data/roundcube.db）同理 |
⚠️
API_TOKEN实测：配置API=true+API_TOKEN=q1w2e3r4后——$ curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8132/api/v1/domain 401 $ curl -sk -H 'Authorization: q1w2e3r4' -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8132/api/v1/domain 200
八、反病毒组（Antivirus settings）
| 参数 | 默认值 | 说明 |
|---|---|---|
ANTIVIRUS | clamav | 杀毒方案选择（clamav/none）；不启用 ClamAV 时内存需求从 3GB 降到 1GB（官方 requirements 页口径） |
ANTIVIRUS_ACTION | discard | 查出病毒的处理动作：discard（静默丢弃，发件方以为发成功）/ reject（SMTP 对话阶段拒收，发件方收到拒信） |
九、数据库与 Webmail 组
- 数据库：admin 与 Roundcube 均默认 SQLite。官方态度原文："the development team recommends against it（换 PostgreSQL/MariaDB）. Indeed, there is currently very little data to be stored and SQLite is deemed both sufficient, simpler and more reliable overall."——不要为"看起来更专业"换库；确需外接时用
SQLALCHEMY_DATABASE_URI=postgresql://...或mysql+mysqlconnector://...。 - Webmail（Roundcube）插件：
ROUNDCUBE_PLUGINS控制插件清单，默认启用archive, carddav, enigma, mailu, managesieve, markasjunk, zipdownload；设为mailu可禁用全部插件。插件级配置经overrides/roundcube/*.inc.php覆盖。
十、参数修改与生效指南
- 改
mailu.env→docker compose up -d（自动重建受影响服务）→docker compose ps观察健康状态； - 改 overrides →
docker compose up -d --force-recreate <服务>； - 升级版本号 → 改编排文件内各服务的版本号（如
2024.06.65→ 下一锁定版）与COMPOSE_PROJECT_NAME→docker compose pull && docker compose up -d； - 验证参数生效的三个抓手：SMTP 侧看 EHLO 能力串（
SIZE/STARTTLS）、Web 侧看响应码与跳转（curl -w '%{http_code} %{redirect_url}'）、数据侧用flask mailu config-export核对落库值。
十一、常见问题
Q1：改了参数但行为没变？ 见部署指南篇 Q4：env_file 只在服务重建时读取，restart 不够，必须 up -d 重建。
Q2：INITIAL_ADMIN_MODE=create 让服务重启报错？ 换 ifmissing/update（官方建议），或删掉这组变量改用 CLI flask mailu admin 手动创建。
Q3：WEBROOT_REDIRECT=/webmail 后根路径 404？ WEBMAIL=none 时 /webmail 路径不存在——跳转目标必须指向已启用的功能。
Q4：开了 REAL_IP_HEADER 反而限流误伤？ 只设 header 不设 REAL_IP_FROM 等于允许伪造来源。两个参数必须成对设置；用 PROXY protocol 时则必须 REAL_IP_HEADER 保持为空。
Q5：AUTH_RATELIMIT_IP 默认 5/hour 太紧把真实用户挡了？ 用 AUTH_RATELIMIT_EXEMPTION（网段白名单）或调大 AUTH_RATELIMIT_EXEMPTION_LENGTH（成功登录后免限速窗口）解决，不建议整体关闭。
十二、参考链接
- 官方配置参考：https://mailu.io/2024.06/configuration.html
- 官方部署要求：https://mailu.io/2024.06/compose/requirements.html
- Mailu 命令行官方文档：https://mailu.io/2024.06/cli.html
- Mailu API 官方文档：https://mailu.io/2024.06/api.html
- 本站相关文章：《Mailu Docker Compose 部署指南》《Mailu 2024.06.65 介绍与选型指南》