Mautic 7 常用 CLI 命令详解

目标：系统讲解 Mautic 7.2.1 的命令行面（bin/console），覆盖运维必用的 mautic 命令空间逐条详解与实测回显，并厘清 CLI 与 REST API 的分工。本文所有回显均来自真实安装实验（Ubuntu 22.04 + Apache 2.4.52 + PHP 8.3.35 + MariaDB 10.11.19，双实例环境），实验日期 2026-10-21。

一、CLI 面总览

Mautic 基于 Symfony Console 构建，唯一入口是应用目录下的 bin/console。实测 php bin/console list 共列出 168 条命令，其中 mautic 命名空间 55 条（营销业务核心），其余为 Symfony 框架命令（cache、debug、doctrine、config、messenger、translation 等）。日常运维真正高频使用的是下表的 12 条：

命令	用途	典型频率
`mautic:segments:update`	按条件重建动态细分列表	每 5 分钟
`mautic:campaigns:trigger`	触发 Campaign 的定时事件	每 10 分钟
`mautic:campaigns:rebuild`	按细分重建 Campaign 成员	每 10 分钟
`mautic:messages:send`	处理消息队列（邮件发送主力）	每 5 分钟
`mautic:broadcasts:send`	列表广播群发	群发场景
`mautic:email:fetch`	拉取收件箱（退信/投诉）	每 5-10 分钟
`mautic:maintenance:cleanup`	过期数据清理	每日
`mautic:import` / `mautic:export`	批量导入/导出联系人	一次性/按需
`mautic:contacts:deduplicate`	联系人去重	按需
`mautic:update:find` / `mautic:update:apply`	检查/应用升级	升级时
`mautic:install`	命令行安装	初始化
`mautic:cache:clear`	清空缓存	改配置后

实测确认 Mautic 7 代际的命令更名（旧教程失效点）：mautic:emails:send 已删除（队列机制迁移到 Symfony Messenger），实测调用报错原文见第七节；替代命令为 mautic:messages:send。

二、基础用法

cd /var/www/mautic          # 进入实例目录（多实例时注意区分）
php bin/console --version
# 7.2.1                      ← 实测回显
php bin/console list        # 列出全部 168 条命令
php bin/console list mautic # 只看 mautic 命名空间（55 条）
php bin/console <命令> --help  # 任何命令的参数明细

通用全局选项（Symfony Console 提供，实测可用）：--env=prod（生产环境，cron 配置建议显式携带）、--no-interaction（无人值守）、-q/--quiet（静默）、-v/-vv/-vvv（详细度）。

通用锁机制：批处理类命令（segments/campaigns/messages/maintenance）内置执行锁，默认锁模式 pid（--help 实测原文），可用 --bypass-locking 强制并行、--lock_mode=flock|redis 换锁实现——并行跑多个实例分片时使用，日常勿动。

三、核心命令逐条详解

3.1 mautic:segments:update —— 细分列表重建

Description:
  Update contacts in smart segments based on new contact data.

Usage:
  mautic:segments:update [options]
  mautic:segments:rebuild          ← 实测存在等价别名

常用选项（实测 --help）：

选项	说明
`-b, --batch-limit[=N]`	每轮处理批次大小，默认 300
`-m, --max-contacts[=N]`	每个细分本次最多处理联系人数，默认全部
`-i, --list-id[=ID]`	只重建指定细分
`-d, --exclude[=ID]`	排除指定细分（可多值）

实测回显（用 API 建好 1 个联系人 + 1 个 endsWith 条件细分后执行）：

$ php bin/console 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），监控脚本应以退出码而非输出判断。

3.2 mautic:campaigns:trigger —— Campaign 定时事件触发

Description:
  Trigger timed events for published campaigns.

Usage:
  mautic:campaigns:trigger [options]

常用选项（实测 --help）：

选项	说明
`-i, --campaign-id[=ID]`	只触发指定 Campaign
`--campaign-limit[=N]`	每个 Campaign 处理的联系人数上限
`--contact-id` / `--contact-ids=CSV`	只针对指定联系人触发
`--min-contact-id` / `--max-contact-id`	按 ID 区间分片（多进程并行时用）
`--thread-id[=N]`	并行进程编号（配合分片）

实测行为：当前实例无已发布 Campaign 时执行无任何输出、退出码 0。配合 --thread-id 与 --min/max-contact-id 可做水平分片的触发集群（官方设计的多进程模式）。

3.3 mautic:campaigns:rebuild —— Campaign 成员重建

Description:
  Rebuild campaigns based on contact segments.

Usage:
  mautic:campaigns:rebuild [options]
  mautic:campaigns:update          ← 实测存在等价别名

把细分（Segment）成员变化同步进 Campaign 成员表，与 mautic:segments:update 组成上下游：细分先更新，Campaign 再重建。选项风格与 3.1 一致（-i 指定 Campaign、批量与锁参数）。实测在无 Campaign 时静默、退出码 0。

3.4 mautic:messages:send —— 消息队列发送（邮件主力）

Description:
  Process sending of messages queue.

Usage:
  mautic:messages:send [options]
  mautic:campaigns:messagequeue    ← 实测存在等价别名

常用选项（实测 --help）：

选项	说明
`-c, --channel[=CHANNEL]`	指定通道（email/sms）
`-i, --channel-id=ID`	指定消息实体 ID（如 email ID）
`-m, --message-id=ID`	处理特定排队消息
`-l, --limit[=N]`	本次最多处理条数
`-b, --batch[=N]`	每批条数，默认 50

实测回显：

$ php bin/console mautic:messages:send
Processing message queue
Messages sent: 0

⚠️ 这是 Mautic 5+ 的队列发送命令；mautic:emails:send 在 7.2.1 已不存在，旧教程 cron 若仍配旧命令会永久静默失败（实测报错原文与迁移方法见第七节）。

3.5 mautic:broadcasts:send —— 列表广播群发

Description:
  Process contacts pending to receive a channel broadcast.

Usage:
  mautic:broadcasts:send [options]

常用选项（实测 --help）：-c 指定通道、-i 指定该通道实体 ID、--min/max-contact-id 分片、-l 单次加载联系人数上限。

实测回显（无待发广播时输出空表格）：

+---------+--------+----------+
| Channel | # sent | # failed |
+---------+--------+----------+

指向「列表类型 Email」的广播发送（对整段人群按频次策略慢慢发）；给单个联系人发信走 API 的 POST /api/emails/{id}/contact/{contactId}/send（实测返回 {"success":true}，见 3.8）。

3.6 mautic:maintenance:cleanup —— 过期数据清理

Description:
  Updates the Mautic application        （实测 7.2.1 的 Description 文案即为如此，疑似上游笔误，实义为数据清理）

Usage:
  mautic:maintenance:cleanup [options]

选项（实测 --help 全文）：

选项	说明
`-d, --days-old[=N]`	清理多少天前的记录，默认 365
`-r, --dry-run`	只统计不删除
`-g, --gdpr`	按 GDPR 要求删除非活跃用户数据
`-x, --lock_mode[=MODE]`	锁模式 pid/flock/redis
`-t, --timeout=SEC`	进程假死超时强解

实测回显（dry-run，全新实例）：

$ php bin/console mautic:maintenance:cleanup --dry-run --days-old=365
+--------------------+------------------+
| Record type        | Records affected |
+--------------------+------------------+
| Audit log entries  | 0                |
| UTM tag history    | 0                |
| User notifications | 0                |
| User tokens        | 0                |
| Visitor page hits  | 0                |
+--------------------+------------------+

💡 生产建议：先 --dry-run 评估量级，确认后去掉参数正式执行；GDPR 场景用 -g。

3.7 mautic:install / mautic:update:find / mautic:update:apply

mautic:install（命令行安装，部署篇方案 B 实测完整流程）：

Usage:
  mautic:install [options] [--] <site_url> [<step>]

Arguments:
  site_url    Site URL.
  step        Install process start index. 0 for requirements check, 1 for
              database, 2 for admin, 3 for configuration, 4 for final step.
Options:
  -f, --force   Do not ask confirmation if recommendations triggered.

实测要点：无 SSL 时会停在 Continue with install anyway? [yes/no] 确认，脚本化必须 --force（或 --no-interaction，实测其默认答复为中止）；实测官方文档示例中的 --mailer_* 参数在 7.2.1 已不存在。

mautic:update:find（检查更新）与 mautic:update:apply（应用更新）：

php bin/console mautic:update:find    # 实测当前已是 7.2.1 最新版：无输出、退出码 0
php bin/console mautic:update:apply   # 有更新包时执行升级（升级前务必备库）

3.8 实测可用的验证组合（联系人→细分→发信闭环）

本实验实测跑通的最小验证链，可直接用于装后验收：

开 API（api_enabled + api_enable_basic_auth，见配置篇 2.4）后建联系人与细分：

curl -u admin:<密码> -X POST http://localhost/api/contacts/new \
  -H 'Content-Type: application/json' \
  -d '{"firstname":"Test","lastname":"Contact","email":"test.contact@example.com"}'
# 实测返回 {"contact":{"id":1,...}}

curl -u admin:<密码> -X POST http://localhost/api/segments/new \
  -H 'Content-Type: application/json' \
  -d '{"name":"Test Segment","alias":"test-segment","isPublished":true,
       "filters":[{"glue":"and","object":"lead","field":"email",
                   "type":"email","operator":"endsWith",
                   "properties":{"filter":"example.com"}}]}'
# 实测返回 {"list":{...,"id":1,...}}

CLI 驱动业务流转：

php bin/console mautic:segments:update     # 实测输出 "1 contact(s) affected"
curl -u admin:<密码> -X POST http://localhost/api/emails/1/contact/1/send
# 实测返回 {"success":true}（邮件参数就绪时）

四、常用命令速查表（cron 就绪版）

*/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
*/10 * * * * /usr/bin/php /var/www/mautic/bin/console mautic:email:fetch         --env=prod >/dev/null 2>&1
0    * * * * /usr/bin/php /var/www/mautic/bin/console mautic:maintenance:cleanup --env=prod >/dev/null 2>&1

排障三连（手动跑看输出/退出码）：

php bin/console mautic:cache:clear          # 配置改动后必跑；实测返回空、退出码 0
php bin/console mautic:segments:update -v   # -v 看细节
php bin/console mautic:maintenance:cleanup --dry-run

五、运维组合实践（实测经验）

执行顺序：细分更新（segments:update）→ Campaign 重建（campaigns:rebuild）→ 事件触发（campaigns:trigger）→ 队列发送（messages:send）。cron 按表错峰 5/10 分钟天然满足依赖顺序；
监控：这些命令成功时多数静默，建议监控退出码 + Mautic 后台 Dashboard 的发送统计；var/logs/mautic_prod-日期.php 是第一现场（实测排障案例：CommandNotFoundException 就是从这里发现的）；
大批量：segments:update -m 限制单次处理量防止 DB 压力尖峰；水平扩展用 campaigns:trigger --thread-id + --min/max-contact-id 分片并行（选项实测存在）；
锁冲突：cron 频率过高导致上一轮未跑完时，锁机制会让下一轮直接退出（实测设计行为），可在监控中识别为正常；强制并行需显式 --bypass-locking。

六、CLI 与 REST API 的边界（实测）

CLI 与 API 各管一半：CLI 管后台批处理与运维，API 管业务系统对接与实时读写。实测分工：

CLI 无法创建联系人/Campaign 实体（这是 API 的活），API 无法直接驱动队列清空（这是 messages:send 的活）；
API 前置条件（实测）：api_enabled + api_enable_basic_auth 打开并清缓存，否则实测返回 403 api_disabled；
实测 API 调用形如 curl -u admin:<密码> http://localhost/api/contacts（返回 {"total":"0","contacts":{}}）；
实测版本差异点：Mautic 7 的细分筛选 operator 词汇已换成 =、!empty、endsWith 等新写法（旧教程的 ends with/notempty 实测报 The selected choice is invalid），且 properties.filter 才是取值字段——对接 API 前先跑一次最小 create 验证词表。

七、常见报错实录（实测原文）

Q1：调用了已删除的旧命令

mautic.ERROR: Symfony\Component\Console\Exception\CommandNotFoundException:
Command "mautic:emails:send" is not defined.  Did you mean one of these?
    mautic:broadcasts:send     mautic:email:fetch     mautic:email:sendwinner
    mautic:emails:fetch     mautic:messages:send

（来源：var/logs/mautic_prod-2026-10-21.php 实测捕获；迁移到 mautic:messages:send 即可。）

Q2：无人值守升级/安装卡在确认——加 --force（Continue with install anyway? [yes/no] 确认项实测存在）。

Q3：--mailer_from_name 报 The "--mailer_from_name" option does not exist.——7.2.1 的 mautic:install 已无邮件参数（实测捕获），装后在后台 Configuration 配置。

Q4：命令静默没有输出——多数批处理命令在"无事可做"时就是静默（实测 segments/campaigns 皆如此），用退出码和后台数据判断，别把静默当故障。

八、参考链接

Symfony Console 官方文档（底层框架）：https://symfony.com/doc/7.4/console.html
Mautic CLI 安装文档：https://docs.mautic.org/en/7.0/getting_started/how_to_install_mautic.html#installing-with-command-line
Mautic 开发者文档（REST API/Webhooks）：https://developer.mautic.org/
Mautic 7.2.1 源码 console 入口：https://github.com/mautic/mautic/blob/7.2.1/bin/console
本专栏关联篇目：Mautic 7 介绍与选型指南、Ubuntu 22.04 安装 Mautic 指南、Mautic 7 配置参数详解