Mautic 7 配置参数详解

目标：讲清 Mautic 7.2.1 的配置体系与关键参数，并对核心参数给出「改 → 生效 → 验证」的实测闭环。本文所有报错原文与回显均来自真实实验（Apache 2.4.52 + PHP 8.3.35 + MariaDB 10.11.19 + Ubuntu 22.04），实验日期 2026-10-21；安装步骤见本专栏部署篇。

一、配置体系与文件布局

Mautic 7 的配置分四层，生效优先级从高到低：

实测的文件布局（生产包方案 A 安装后）：

/var/www/mautic/
├── .env                  # APP_ENV=prod, APP_DEBUG=0（实测内容）
├── config/
│   └── local.php         # 实例参数，本文所有键值都改在这里
├── app/config/config.php # 框架级默认（Bundle 参数聚合，一般不动）
├── var/cache/            # 缓存（改配置后需清）
├── var/logs/             # 实测日志文件：mautic_prod-2026-10-21.php / prod-2026-10-21.php
└── bin/console           # CLI 入口（mautic:cache:clear 等命令）

⚠️ 代际差异：Mautic 4 及更早版本的实例参数在 app/config/config_local.php，Mautic 5 起迁移到根目录 config/local.php（7.2.1 实测确认）。网上旧教程若教改 app/config/config_local.php 在 Mautic 7 已无效。

config/local.php 的完整结构（实测 7.2.1 向导刚装完的原始键集，本实验后续修改已标注）：

<?php
$parameters = array(
    'db_driver' => 'pdo_mysql',
    'db_host' => '127.0.0.1',
    'db_host_ro' => null,              // 读库地址（读写分离预留）
    'db_table_prefix' => null,
    'db_port' => '3306',
    'db_name' => 'mautic',
    'db_user' => 'mautic',
    'db_password' => 'q1w2e3r4',
    'db_backup_tables' => 0,           // 实测：向导里选 No 的落盘值
    'db_backup_prefix' => 'bak_',
    'db_server_version' => null,
    'secret_key' => '1e0f2520...(64 位十六进制，安装时自动生成，已部分脱敏)',
    'site_url' => 'http://localhost',
    // ——以下为本实验实测追加——
    'api_enabled' => true,
    'api_enable_basic_auth' => true,
    'mailer_dsn' => 'smtp://127.0.0.1:25?verify_peer=0',
    'mailer_from_name' => 'Mautic Admin',
    'mailer_from_email' => 'admin@mautic.local',
);

改配置的标准流程（实测必需，否则改动不生效或 500）：

vi /var/www/mautic/config/local.php
chown www-data:www-data /var/www/mautic/config/local.php          # 实测：编辑后属主易变成 root
php /var/www/mautic/bin/console mautic:cache:clear                 # 以 www-data 身份执行
chown -R www-data:www-data /var/www/mautic/var/cache               # 实测：清缓存后必须归还属主

二、关键参数逐项实测

2.1 数据库参数（db_* 系列）

• db_driver：实测仅 pdo_mysql 一个选项（连接 MySQL/MariaDB 均用它）；
• db_host / db_port / db_name / db_user / db_password：连接五要素，向导生成后一般不再动；改库密码时这里要同步；
• db_host_ro：读写分离时只读库地址，默认 null（单机部署保持 null）；
• db_table_prefix：表前缀，实测默认 null（无前缀，125 张表直接建在库下）；安装时确定，装后不建议再改；
• db_backup_tables / db_backup_prefix：更新流程重建表时是否先备份旧表，实测默认 0 / bak_；升级场景建议改为 1；
• db_server_version：留 null 自动探测（实测 MariaDB 10.11 下无需指定）。

验证闭环（实测）：mariadb mautic -e 'SELECT COUNT(*) FROM information_schema.tables WHERE table_schema="mautic";' 返回 125，与向导安装产物一致。

2.2 secret_key（安装时自动生成）

64 位十六进制随机串，实测样例 1e0f25209b3e...（作用：CSRF/加密类字段等内部用途）。实测特性：安装时一次性生成，不要手改；多实例部署时每实例独立生成。若泄露（如配置文件误提交到公开仓库）需要按官方文档轮换。本实验实例是一次性实验环境，密钥已随实例废弃。

2.3 site_url（站点基准 URL）

• 作用：邮件里的跟踪链接、公开链接、webhook 回调都以它为基准；本机联调实测值为 http://localhost，生产必须改为完全限定域名（如 https://mautic.example.com）；
• 向导第 1 步的环境检查页实测会给出两条建议：站点 URL 应使用完全限定域名而非 IP、应启用 SSL——对应生产配置点；
• 修改后需 mautic:cache:clear 生效。

2.4 API 开关（api_enabled / api_enable_basic_auth）——实测闭环

• api_enabled：REST API 总开关，实测默认关闭；
• api_enable_basic_auth：允许 HTTP Basic 认证调 API（OAuth2 之外的轻量方式），实测默认关闭。

实测闭环过程：

1. 默认状态调 API：curl -u admin:<密码> http://localhost/api/contacts 实测返回 HTTP 403 与报错原文：

{"errors":[{"message":"API disabled. You need to enable the API in the API settings of Mautic's Configuration.","code":403,...}]}

2. 在 config/local.php 追加两个键（等价于后台 Configuration → API Settings 的两个开关）：

'api_enabled' => true,
'api_enable_basic_auth' => true,

3. 清缓存（见第一节流程）后复测：GET /api/contacts 实测返回 HTTP 200、{"total":"0","contacts":{}}——参数立即生效，无需重启 Apache。

💡 生产建议：Basic 认证适合脚本/内网联调；对外仍建议 OAuth2 并限流。API 能力清单见本专栏 CLI/API 进阶篇。

2.5 邮件参数（mailer_dsn / mailer_from_*）——实测闭环

Mautic 5+ 的发送通道基于 Symfony Mailer，核心键是 mailer_dsn（实测默认值来自 EmailBundle：smtp://localhost:1025，即假设你本机 1025 端口有 MTA——Ubuntu 22.04 装的 Postfix 监听 25，所以必改）。相关键：

• mailer_dsn：传输 DSN，格式 scheme://user:pass@host:port?option=value；
• mailer_from_name / mailer_from_email：默认发件人名称/地址（实测值 Mautic Admin / admin@mautic.local）；
• 向导环节：7.2.1 的 Web 向导实测已无 Email 配置步骤（官方 7.0 文档描述的四步流程中第 4 步在实测中未出现），邮件参数安装后在后台 Configuration → Email Settings 或本文件配置。

实测闭环过程（本机 Postfix 联调）：

1. 初次配置 'mailer_dsn' => 'smtp://127.0.0.1:25'，向联系人发信实测失败，返回报错原文：

Unable to connect with STARTTLS: stream_socket_enable_crypto():
Peer certificate subjectAltName did not match expected name `127.0.0.1'

原因：Postfix 自签证书的 subjectAltName 与 127.0.0.1 不匹配，Symfony Mailer 默认校验对端证书。

2. 追加 DSN 参数关闭本机场景的对端校验：'mailer_dsn' => 'smtp://127.0.0.1:25?verify_peer=0'，清缓存后重发实测返回 {"success":true}；email_stats 表实测 is_failed=0，Postfix 日志记录完整 SMTP 事务：

Oct 21 03:31:10 mautic-server postfix/smtpd[21375]: connect from localhost[127.0.0.1]
Oct 21 03:31:10 mautic-server postfix/smtpd[21375]: disconnect from localhost[127.0.0.1]
  ehlo=2 starttls=1 mail=1 rcpt=1 data=1 quit=1 commands=7

3. 常用 DSN 形态速查（Symfony Mailer 语法，Mautic 7 实测沿用）：

⚠️ verify_peer=0 仅限本机回环 MTA 联调；对公网 SMTP 必须保持证书校验。密码写进 local.php 时注意该文件权限（实测属主应为 www-data，且不要提交到代码仓库）。

2.6 PHP 层参数（max_execution_time / memory_limit）

• 安装向导环境检查页要求 max_execution_time ≥ 240（实测原文见部署篇）；Ubuntu 22.04 + PHP 8.3 默认 30，实测改为 240 通过检查；
• memory_limit 实测默认 128M，批量导入/导出与 Campaign 重建场景建议 512M；
• CLI 进程另有独立的 /etc/php/8.3/cli/php.ini（实测 CLI 默认 max_execution_time=0 不限时长，cron 任务无需处理）。

2.7 缓存与日志路径（cache_path / log_path）

向导第 1 步表单里的隐藏默认值实测为：

• cache_path：%kernel.project_dir%/var/cache
• log_path：%kernel.project_dir%/var/logs

多实例或大流量场景可把缓存挪到独立磁盘（改这里+清缓存生效）。实测日志文件按天滚动：var/logs/mautic_prod-2026-10-21.php（业务日志，排障先看它）与 Symfony 层的 prod-2026-10-21.php。

三、cron 任务配置（必配）

Mautic 的联系人细分、Campaign 触发、队列发送全靠系统 cron 驱动——不配 cron 时界面正常但自动化全部静默失效，这是最常见的新手事故。Mautic 7.2.1 实测的命令清单与推荐频率：

实测配置步骤（Ubuntu 22.04 需先 apt-get install -y cron，系统默认不带）：

crontab -u www-data -e

写入（实测采用的配置）：

*/5  * * * * /usr/bin/php /var/www/mautic/bin/console mautic:segments:update     --env=prod >/dev/null 2>&1
*/10 * * * * /usr/bin/php /var/www/mautic/bin/console mautic:campaigns:trigger   --env=prod >/dev/null 2>&1
*/10 * * * * /usr/bin/php /var/www/mautic/bin/console mautic:campaigns:rebuild   --env=prod >/dev/null 2>&1
*/5  * * * * /usr/bin/php /var/www/mautic/bin/console mautic:messages:send       --env=prod >/dev/null 2>&1
0    * * * * /usr/bin/php /var/www/mautic/bin/console mautic:maintenance:cleanup --env=prod >/dev/null 2>&1

验证（实测回显）：

crontab -u www-data -l     # 逐行回显如上，确认已装载
systemctl is-active cron   # active

命令手动验证实测（不经过 cron，直接跑）：

• mautic:segments:update：有变更时输出进度，实测回显：

Rebuilding contacts for segment 1
1 total contact(s) to be added in batches of 300
 0/1 [>---------------------------]   0%
 1/1 [============================] 100%
0 total contact(s) to be removed in batches of 300
1 contact(s) affected

无变更时静默退出（无输出，退出码 0）。

• mautic:messages:send：实测回显 Processing message queue / Messages sent: 0（队列空时为 0）；
• mautic:campaigns:trigger / mautic:campaigns:rebuild：无已发布 Campaign 时实测无输出、退出码 0；
• mautic:maintenance:cleanup --dry-run --days-old=365：实测输出受影响行数表格（Audit log entries 0 / UTM tag history 0 / User notifications 0 / User tokens 0 / Visitor page hits 0 ...），加 --dry-run 只统计不删除。

四、多环境与多实例的配置隔离

本专栏部署篇在同一台服务器实测了双实例共存（/var/www/mautic + /var/www/mautic2），配置层隔离点：

1. 每实例一份 config/local.php（含各自的 secret_key、site_url、db_name）；
2. cron 按实例指向各自绝对路径的 bin/console；
3. .env 的 APP_ENV=prod 保持一致；调试需求时才临时改 APP_DEBUG=1（实测生产包默认 0，排障后务必改回）；
4. 后台 Configuration 页面的图形化改动同样落到各自 local.php，两实例互不影响。

五、常见配置坑排障（实测）

Q1：改了 config/local.php 不生效或 500——清缓存命令用了 root 身份导致 var/cache 属主错乱。实测流程：chown -R www-data:www-data var/cache 后恢复。编辑文件本身也要保持属主为 www-data。

Q2：后台 Configuration 页保存的值和 local.php 不一致——页面改动会即时写回 local.php，但部分参数（如缓存路径类）需 mautic:cache:clear 才运行时生效；以 local.php 内容为事实来源核对。

Q3：mautic:emails:send 在 cron 里静默失败——命令已于 5 代后移除，7.2.1 实测报 CommandNotFoundException（建议列表里给出替代命令 mautic:messages:send）；旧教程 cron 配置必须迁移，否则邮件永远不发。

Q4：API 403 api_disabled——api_enabled 默认关闭，见 2.4 节闭环。

Q5：本机 Postfix 发信 STARTTLS 报错——mailer_dsn 加 ?verify_peer=0，见 2.5 节闭环。

Q6：装完没配 cron，Campaign/细分永远不动——见第三节；先 systemctl is-active cron 再核对 crontab -u www-data -l。

六、参考链接

• Mautic 官方 Configuration 文档：https://docs.mautic.org/en/7.0/configuration/settings.html
• 官方 Cron 作业说明：https://docs.mautic.org/en/7.0/getting_started/how_to_install_mautic.html#command-line-installation
• Symfony Mailer DSN 语法：https://symfony.com/doc/7.4/mailer.html
• Mautic EmailBundle 默认参数源码：https://github.com/mautic/core-lib/blob/7.2.1/app/bundles/EmailBundle/Config/config.php
• 本专栏部署篇（本实验的安装过程）：Ubuntu 22.04 安装 Mautic 指南
• 本专栏 CLI 篇（cron 命令逐条详解）：Mautic 7 常用 CLI 命令详解