Mail-in-a-Box v77 配置参数详解

Mail-in-a-Box v77 配置体系实测详解：mailinabox.conf 八个全局参数逐项解析、/home/user-data 数据根目录逐目录说明、备份/配额/反垃圾参数与重跑回填机制，全部参数值来自实测。

Mail-in-a-Box邮件服务器Mail-in-a-Box2026/10/21

Mail-in-a-Box v77 配置参数详解

目标：讲清 Mail-in-a-Box v77 的配置体系——8 个全局参数的真实值与生效机制、数据根目录逐目录用途、备份/配额/反垃圾等运行参数的查看与修改方法，以及"生成物与可持久编辑物"的边界（哪些文件改了会被重写、哪些能长久生效）。本文为配置篇：所有参数值、文件内容与修改效果均来自本站实测（2026-10-21），安装过程见 《Ubuntu 22.04 安装 Mail-in-a-Box 指南》。

一、环境信息

项目值
组件版本Mail-in-a-Box v77（安装日期 2026-10-21）
操作系统Ubuntu 22.04 LTS (jammy)，x86_64
主机名 / 邮箱域名box.example.com / example.com
公网 IP / 内网 IP182.54.113.29 / 10.0.0.3
数据根目录/home/user-data（STORAGE_ROOT 默认值）
示例账号me@example.com（管理员，示例密码 q1w2e3r4）

二、配置体系总览

Mail-in-a-Box 的配置分三层，理解"谁是生成物"是改配置不翻车的前提：

层位置性质改动方式
全局参数/etc/mailinabox.conf生成物（每次重跑 sudo mailinabox 会整体重写）改后必须重跑，重跑时旧值经 DEFAULT_* 变量回载（见第六节实测）
数据与状态/home/user-data/持久物（账号、证书、DNSSEC 密钥、备份都在这里）面板/API/CLI 正常操作，或按官方路径迁移
服务配置/etc/postfix/main.cf、/etc/dovecot/conf.d/*、/etc/nsd/zones/* 等生成物或受管物（重跑会被脚本按固定值回填）用官方工具改，改后重跑生效；想持久的改动要避开重跑回填点

一句话结论：数据（/home/user-data）是你要备份的一切；/etc/mailinabox.conf 与服务配置文件是脚本产物，重跑即按声明值重建。

三、/etc/mailinabox.conf 全局参数（共 8 个）

实测全文（cat /etc/mailinabox.conf）：

STORAGE_USER=user-data
STORAGE_ROOT=/home/user-data
PRIMARY_HOSTNAME=box.example.com
PUBLIC_IP=182.54.113.29
PUBLIC_IPV6=
PRIVATE_IP=10.0.0.3
PRIVATE_IPV6=
MTA_STS_MODE=enforce

逐项解析：

参数实测值作用谁在消费它
STORAGE_USERuser-data数据根目录属主的系统用户名（脚本自动创建该用户）权限管理：/home/user-data 及其下邮件数据的属主
STORAGE_ROOT/home/user-data数据根目录：邮件账号库、证书、DNSSEC、备份、Nextcloud 数据全在此几乎所有脚本与守护进程；整机迁移=迁移这个目录
PRIMARY_HOSTNAMEbox.example.com服务器正式主机名：TLS 证书 CN、Postfix myhostname、DNS 的 MX、面板地址都由它派生系统主机名（/etc/hostname）、Postfix、nginx、nsd、certbot
PUBLIC_IP182.54.113.29本机公网 IPv4DNS 区域文件（A 记录）、fail2ban 白名单变量、状态检查的 DNS 一致性比对
PUBLIC_IPV6空本机公网 IPv6（AAAA 记录），未启用为空同上（IPv6 侧）
PRIVATE_IP10.0.0.3内网 IPv4nsd 监听地址（权威 DNS 绑在内网网卡）、内网服务绑定
PRIVATE_IPV6空内网 IPv6，未启用为空同上
MTA_STS_MODEenforceMTA-STS 策略模式（RFC 8460：none/testing/enforce 三值），决定 /var/lib/mailinabox/mta-sts.txt 策略文件的 mode: 与 _mta-sts TXT 记录的发布web.sh（生成策略文件）、dns_update.py（生成 DNS 记录）

💡 关于 PUBLIC_IP 与 PRIVATE_IP 的关系：云主机 NAT 场景下两者不同（公网入口 IP ≠ 内网网卡 IP），脚本靠 icanhazip.com 探测公网值。如果公网 IP 变了（换机器/换弹性 IP），更新此文件后重跑 sudo mailinabox，DNS 记录与状态检查即修正。

四、数据根目录 /home/user-data 逐目录解析

实测目录树（ls -F /home/user-data/）：

backup/  dns/  mail/  mailinabox.version  owncloud/  owncloud-backup/  ssl/  www/
目录/文件实测内容说明
mail/users.sqlite、dkim/、mailboxes/、postgrey/、roundcube/、sieve/、spamassassin/邮件核心数据：users.sqlite 存全部账号/别名/权限（SQLite 单文件）；mailboxes/ 是真实邮件存储（Maildir）；dkim/ 存 DKIM 签名密钥；postgrey/db 存灰名单库；sieve/ 存用户过滤规则
ssl/ssl_certificate.pem@、ssl_private_key.pem、dh2048.pem、box.example.com-selfsigned-20261021.pem、lets_encrypt/证书中枢：lets_encrypt/ 是 certbot 的完整配置目录（账号、待签证书）；当前生效证书用符号链接切换（自签→Let's Encrypt 自动换链）；dh2048.pem 为安装时实测生成的 2048 位 DH 参数
dns/custom.yaml、dnssec/custom.yaml 存面板/API 添加的自定义 DNS 记录（实测初始为 {}）；dnssec/ 存区域签名密钥（丢失=全网 DNSSEC 作废，务必备份）
backup/cache/、encrypted/、secret_key.txt备份体系：encrypted/ 是默认本地备份目标；secret_key.txt 是 duplicity 的 GPG 加密密钥（丢了它备份就是乱码）
owncloud/Nextcloud 数据目录（含 config.php、数据文件、owncloud.db）日历/联系人/文件数据（组件名沿用 owncloud 目录名，实际跑的是 Nextcloud 27.1.11）
owncloud-backup/升级 Nextcloud 时的自动快照每次升级前自动创建，可手动清理旧版本
www/各域名静态站点根目录面板中为域名开启"静态网站"后的网页文件
mailinabox.version15数据库结构版本号（schema migration 版本，非组件版本 v77），由 setup/migrate.py 维护

五、运行参数详解

5.1 备份参数

查看（curl --user "$(cat /var/lib/mailinabox/api.key):" http://127.0.0.1:10222/system/backup/config，实测）：

{
  "enc_pw_file": "/home/user-data/backup/secret_key.txt",
  "file_target_directory": "/home/user-data/backup/encrypted",
  "min_age_in_days": 3,
  "ssh_pub_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB... root@box.example.com\n",
  "target": "file:///home/user-data/backup/encrypted"
}
参数默认值说明
targetfile:///home/user-data/backup/encrypted备份目标。支持 rsync://、S3（s3://）、Backblaze B2（b2://）等 duplicity 目标，改后每日备份自动上传
min_age_in_days3备份保留天数下限，超出后清理旧备份
enc_pw_file/home/user-data/backup/secret_key.txt加密口令文件路径（自动生成，勿动勿删）
ssh_pub_key自动生成 RSA 密钥若 target 是远程 SSH 主机，把该公钥加到对端 authorized_keys 实现免密推送

修改方式：面板 System → Backups，或 POST /system/backup/config。执行时机：每日 cron（实测 /etc/cron.d/mailinabox-nightly）：

21 1 * * *      root    (cd /root/mailinabox && management/daily_tasks.sh)

即每天 01:21 执行 daily_tasks.sh：跑 management/backup.py（结果邮件发管理员）；每周一额外跑 management/mail_log.py -t week 发送使用报告。

5.2 邮箱配额（quota）

实测（CLI 与 API 等价）：

$ management/cli.py user quota me@example.com
0                      # 0 = 不限额
$ management/cli.py user quota me@example.com 2G
OK                     # 设置为 2GB

配额作用于 Dovecot（邮箱容量），值支持 1G/500M 等后缀，0 为不限。Dovecot 侧由用户库的 quota 字段驱动，无需改配置文件。

5.3 反垃圾链路参数（按邮件流经顺序）

环节参数位置实测关键值
收件 RBL 黑名单/etc/postfix/main.cf（smtpd_recipient_restrictions）reject_rbl_client zen.spamhaus.org=127.0.0.[2..11]——命中 Spamhaus ZEN 即拒收
灰名单 postgrey/etc/default/postgrey（POSTGREY_OPTS）--inet=127.0.0.1:10023 --delay=180 --dbdir=/home/user-data/mail/postgrey/db——首次发件延迟 180 秒
内容过滤 SpamAssassin/etc/spamassassin/local.cfreport_safe 0、评分头注入（add_header all Score _SCORE_）、pyzor 集成
出站签名 OpenDKIM/home/user-data/mail/dkim/（密钥）+ DNS TXT 记录密钥由脚本生成，DNS 记录自动发布
策略服务postfix 调用 127.0.0.1:12340Mail-in-a-Box 自带的发信策略守护（限额/速率控制）
单信大小上限/etc/postfix/main.cf（message_size_limit）实测 134217728（128MB；nginx 侧同步配置，webmail/Z-Push 提交路径同限）

自定义追加规则的正确姿势：SpamAssassin 规则追加到 /etc/spamassassin/local.cf（脚本只回填固定行，不删追加内容）；postgrey 的延迟/白名单走 /etc/default/postgrey 与 /etc/cron.daily/mailinabox-postgrey-whitelist（每日自动拉取大厂白名单）。

5.4 自定义 DNS 记录

面板 DNS → Custom Records 与 API 落盘到 /home/user-data/dns/custom.yaml（实测初始 {}）。添加后自动并入区域文件 /etc/nsd/zones/example.com.txt（实测同目录有 .ds、.signed 后缀文件——区域是 DNSSEC 签名的，手工改区域文件会被下次 dns_update 覆盖，永远走 API/面板）。

5.5 面板与守护进程参数

项值说明
守护进程监听127.0.0.1:10222（实测 ss 输出）仅本机；对外经 nginx /admin/ 反代（/etc/nginx/conf.d/local.conf）
服务单元/lib/systemd/system/mailinabox.servicegunicorn 承载，开机自启
API 密钥文件/var/lib/mailinabox/api.key守护进程每次重启重新生成（详见 API 篇）
状态检查management/status_checks.py每日随 cron 执行，结果推送管理员邮箱

六、生效机制实测：重跑会重写什么

Mail-in-a-Box 的配置生效机制是声明式重放：sudo mailinabox（重跑 setup/start.sh）按脚本里的固定值重新写配置。本站做了两组实测：

实测 1：/etc/mailinabox.conf 的回载与持久化。 把 MTA_STS_MODE=enforce 改为 testing 后重跑，重跑完成时该值保持 testing，且 /var/lib/mailinabox/mta-sts.txt 的 mode: 同步变为 testing。机制：重跑时旧配置被备份到 /tmp/mailinabox.prev.conf 并以 DEFAULT_ 前缀回载（DEFAULT_MTA_STS_MODE=testing），重写 conf 时取 MTA_STS_MODE=${DEFAULT_MTA_STS_MODE:-enforce}——旧值经 DEFAULT_ 变量传递，所以改 conf 是有效的持久化方式*。

实测 2：服务参数被脚本回填。 同一轮实验中把 /etc/postfix/main.cf 的 message_size_limit 改为 26214400（25MB），重跑后被 setup/mail-postfix.sh 回填为 134217728（128MB）——Postfix/Dovecot 等服务配置是"受管物"，脚本按声明值覆盖。

两条由此而来的纪律：

  1. 编辑 mailinabox.conf 要保持 KEY=VALUE 干净格式。实测中用工具编辑后在文件里残留了一行注释格式的旧值，重跑时回载器把该行前缀化为 DEFAULT_#MTA_STS_MODE=... 触发解析错误，直接让重跑静默失败——set -e + 回载的组合对格式零容忍。
  2. 改服务参数后想持久：优先用组件自身机制（如 postgrey 走 /etc/default/postgrey），或在重跑后再改（接受下次重跑回填），或确认该参数不在脚本声明清单里。

顺带实测到的编辑工具：官方自带 tools/editconf.py（修改 KEY=VALUE 类配置文件的瑞士军刀）：

python3 tools/editconf.py /etc/postfix/main.cf message_size_limit=26214400

以及配置变更后的统一生效按钮：重跑 sudo mailinabox。本站实测重跑三次：全部完成配置重写（幂等提示如 Nextcloud is already latest version），但有两次在收尾的首用户检查处提前退出——重跑会先重启管理守护进程，若脚本在该窗口期调用 management/cli.py user 拿到空结果，会误判"还没有任何用户"而尝试重建管理员：重跑环境带 EMAIL_ADDR 且账号已存在时脚本以退出码 1 终止；不带时则会真的创建 me@<主机名> 的新账号（实测即多出一个，需手动移除）。重跑前清空 EMAIL_ADDR/EMAIL_PW 环境变量、并确认守护进程已在运行（systemctl is-active mailinabox），可避开该窗口；即便踩中，前序配置重写均已生效，损失仅是退出码。

七、常见问题

Q1：改了 /etc/mailinabox.conf 但没生效？ 该文件只是参数载体，生效靠重跑 sudo mailinabox。另注意公网 IP 类参数会被状态检查持续比对，改完重跑即对齐。

Q2：mailinabox.version 里的 15 和版本号 v77 什么关系？ 15 是数据结构（schema）迁移版本，由 setup/migrate.py 管理账号库/配置的结构升级；v77 是组件版本。升级 Mail-in-a-Box 的方式就是重跑官方安装脚本（自动拉取新 TAG），迁移版本号随之推进。

Q3：换服务器怎么迁移？ 数据全在 /home/user-data（含账号库、邮件、证书、DNSSEC 与备份加密密钥）：新机器装好同版本 Mail-in-a-Box 后停服务、同步该目录、改 PRIMARY_HOSTNAME/IP 相关参数、重跑即可。务必带上 backup/secret_key.txt 与 dns/dnssec/。

Q4：MTA-STS 该用哪个模式？ 新机器建议 testing 观察报告（TLSRPT），确认无兼容问题后切 enforce。切换方式即第六节实测路径：改 conf → 重跑。

八、参考链接

  1. 本站部署篇：《Ubuntu 22.04 安装 Mail-in-a-Box 指南》
  2. 官方仓库（setup/ 脚本即配置声明源）：https://github.com/mail-in-a-box/mailinabox
  3. MTA-STS 标准：https://datatracker.ietf.org/doc/html/rfc8460
  4. duplicity 备份后端：https://duplicity.gitlab.io/