Modoboa 2.11.1 配置参数详解

目标：把 Modoboa 2.11.1 的配置参数一次讲全——既覆盖部署生成的实例配置文件（Django settings.py），也覆盖管理面板"Settings → Modoboa → Parameters"背后由参数注册表驱动的全部平台参数（默认值、类型、含义），并给出经 API 实测的修改回路。文中默认值均自 2.11.1 运行实例的参数注册表逐项导出（2026-10-21 实测）。

一、环境信息

• 实测环境：Ubuntu 22.04.5 LTS，Modoboa 2.11.1（pip 安装，/opt/modoboa/env，实例目录 /home/modoboa/instance），PostgreSQL 14 + Redis 6 + Nginx/uWSGI，部署于 2026-10-21（安装过程见同专栏《Ubuntu 22.04 安装 Modoboa 指南》）
• 取证方法：默认值来自运行实例的参数注册表（modoboa.parameters.tools.registry，2.11.1 源码内建）；生效值经 GET /api/v2/parameters/global/<组>/ 实测读取；修改经 PUT 实测并回读验证
• 适用版本：Modoboa 2.11.x（其他版本参数集合可能增减，以 python manage.py shell 中读取注册表为准）

二、配置体系总览

Modoboa 的配置分三层，修改入口与生效方式各不相同：

三层的优先级关系：平台参数只在"面板行为"层面起作用（限额、反垃圾联动、DKIM 存储路径、界面主题等），运行边界（数据库地址、ALLOWED_HOSTS、队列连接等）永远由 settings.py 决定。排查问题先分清"改的是哪一层"。

关键差异解读：与其他邮件管理面板把全部配置写单一配置文件不同，Modoboa 的平台参数走"代码内默认值 + 数据库覆盖"模式——注册表（serializer）定义参数名、类型、默认值与帮助文案，UI 与 API 读写的是同一份数据库 JSON。好处是参数自带类型校验与文档；代价是看"当前实际值"必须查库或调 API，不能只看文件。

三、实例级配置 settings.py 逐组解析

以下为 deploy 生成的 settings.py 中运维必须掌握的键（2.11.1 实测文件节选）：

3.1 安全与会话

3.2 应用注册

3.3 数据与队列

3.4 语言与时区

deploy --lang/--timezone 写入 LANGUAGE_CODE 与 TIME_ZONE；面板显示语言按用户参数覆盖。

四、平台参数逐组详解（参数注册表）

以下 11 组参数为 2.11.1 注册表内建全局参数（所有默认值均为 2.11.1 源码实测导出）。查看与修改：面板 Settings → Modoboa → Parameters（分组即下列组名）；API 方式见第五章。默认值为空/null 表示未预设（需按需填写）。

4.1 General（core 组，界面入口"General"）

口令与认证：

LDAP 全家桶（authentication_type=ldap 时生效）：

界面与主题：

版本检查与统计上报：

账号治理与分页：

4.2 Administration（admin 组）

DNS/邮件记录体检（新建域名时的自动检查）：

DKIM：

域名与邮箱默认值：

别名策略：

4.3 Limits（limits 组）

4.4 Statistics（maillog 组）

4.5 PDF Credentials（pdfcredentials 组）

4.6 DMARC（dmarc 组）

4.7 IMAP Migration（imap_migration 组）

4.8 Automatic replies（autoreply 组）

4.9 Sieve filters（sievefilters 组）

4.10 Calendars（calendars 组，对接 Radicale）

4.11 Webmail（webmail 组）

参数间联动提示：admin.dkim_keys_storage_dir 为空时面板生成 DKIM 只入库不落盘；webmail.imap_server 指向的 Dovecot 不通时 Webmail 登录报错但面板正常——这类"参数指向外部组件"的项是排障第一入口。

五、参数查看与修改实测（API 回路）

平台参数在面板上分组呈现；自动化运维可用 REST API 直改（完整认证方式见同专栏《Modoboa 2.11.1 管理 API 使用详解》）。

读取（实测回显，节选）：

$ curl -s -H 'Host: mail.example.com' -H "Authorization: Token <TOKEN>" \
    http://127.0.0.1/api/v2/parameters/global/core/ | python3 -m json.tool | head -25
{
    "label": "General",
    "params": {
        "authentication_type": "local",
        "password_scheme": "sha512crypt",
        "rounds_number": 70000,
        "update_scheme": true,
        "default_password": "ChangeMe1!",
        "random_password_length": 8,
        "allow_special_characters": false,
        "update_password_url": null,
        "password_recovery_msg": null,
        "sms_password_recovery": false,
        "sms_provider": null,
        "ldap_server_address": "localhost",
        "ldap_server_port": 389,
        ...
    }
}

修改与回读（实测：PUT 200 → 回读确认 → 复原）：

$ curl -s -o /dev/null -w 'update PUT: %{http_code}\n' \
    -H 'Host: mail.example.com' -H "Authorization: Token <TOKEN>" \
    -X PUT http://127.0.0.1/api/v2/parameters/global/core/ \
    -H 'Content-Type: application/json' -d '{"items_per_page": 50}'
update PUT: 200
$ # 回读 items_per_page = 50；复原同接口 PUT 回 30，再次回读 = 30

落库位置（实测查询）：修改后的值整体写入 core_localconfig._parameters（JSONB），未改过的参数走注册表默认值：

modoboa=# SELECT substring(_parameters::text,1,150) FROM core_localconfig;
 {"core": {"ldap_bind_dn": "", "ldap_secured": "none", "rss_feed_url": null, ...

用户级参数：同模式，端点为 /api/v2/parameters/user/<组>/（界面：用户菜单 → Settings），默认值同样由注册表定义，本篇不展开。

六、常见问题（FAQ）

Q1：改了面板参数，为什么行为没变？ 先确认改的是对的一层：队列/数据库/域名白名单等运行边界在 settings.py（改完要重启 uWSGI 与 worker）；面板参数即时生效但个别项被 worker 缓存，重启 modoboa-worker-* 服务观察。另注意 enable_admin_limits（用户级限额）与 enable_domain_limits（域名级限额）是两把独立开关。

Q2：rrd_rootdir 默认在 /tmp/modoboa 有风险吗？ 有。/tmp 常被 tmpfs 或重启清理，图表历史会丢；生产改为 /var/lib/modoboa/rrd 并确保运行用户可写。

Q3：DKIM 密钥生成了但 OpenDKIM 不签？ 检查 admin.dkim_keys_storage_dir：为空则不落盘；填了但 OpenDKIM 进程用户读不到也会失败。目录属主与 OpenDKIM 配置（KeyTable/SigningTable）需对应。

Q4：如何关掉面板对公网 modoboa.org 的版本检查/统计上报？ core.check_new_versions、core.send_statistics、core.enable_api_communication 三项置 False（离线内网部署建议全关）。

Q5：口令策略在哪配？ core.password_scheme（散列方案）、core.rounds_number（轮数）、core.default_password（新账号默认口令）、core.random_password_length、core.allow_special_characters。注意 password_scheme 与 Dovecot 认证方案必须一致，否则 Webmail/IMAP 认证失败。

Q6：怎么批量导出全部参数做备份？

for app in core admin limits maillog pdfcredentials dmarc imap_migration autoreply sievefilters calendars webmail; do
  curl -s -H 'Host: mail.example.com' -H "Authorization: Token $TOKEN" \
    "http://127.0.0.1/api/v2/parameters/global/$app/" > "params-$app.json"
done

七、参考链接

• 官方文档站（Parameters 相关说明）：https://modoboa.readthedocs.io/
• Modoboa 主仓库（参数注册表源码 modoboa/*/apps.py 与 parameters/）：https://github.com/modoboa/modoboa
• 站内同专栏：《Ubuntu 22.04 安装 Modoboa 指南》、《Modoboa 2.11.1 介绍与选型指南》、《Modoboa 2.11.1 管理 API 使用详解》