Ubuntu 22.04 安装 Mautic 指南

目标：在一台全新的 Ubuntu 22.04 服务器上完成 Mautic 7.2.1 社区版的完整安装，覆盖「生产包 + Web 安装向导」与「命令行安装」两条实测方案，并给出安装后配置、多版本共存、升级与卸载方法。本文所有命令与回显均来自真实安装实验，实验日期 2026-10-21。

一、实验环境与版本声明

服务器视角：一台 Ubuntu 22.04（jammy）x86_64 服务器，以 root 执行，可通过 SSH 登录；
网络：可访问外网（Ubuntu/ondrej/MariaDB 仓库、GitHub 下载）；本文实验通过 HTTP 代理 http://192.168.1.62:7897 访问外网，读者无代理时删除代理参数即可；
软件版本（实测）：Apache/2.4.52 (Ubuntu)、PHP 8.3.35（ondrej PPA）、MariaDB 10.11.19（官方仓库）、Postfix 3.6.4、cron、Composer 2.2.6（仅进阶方案需要）；
目标版本：Mautic 7.2.1 社区版（当前稳定版，2026-09-23 发布；生产包 SHA1 f419eff698a6e7d82f6b1dc5f6effb05973bb837，与官方 Releases 页公布的 SHA1 完全一致）；
端口约定：本实验主机 80 端口未被占用（ss -ltn 确认），Apache 直接监听 80；生产部署建议按需改用 443/HTTPS（见第六节）。

Mautic 7 对各组件的硬性要求（实测验证）：

组件	要求	实测值
PHP	`~8.2`（8.2 及以上）	8.3.35 ✅
数据库	MySQL 8.4.0+ 或 MariaDB 10.11.0+（安装器实测拒绝 MySQL 8.0）	MariaDB 10.11.19 ✅
PHP 扩展	pdo_mysql, curl, gd, intl, xml, mbstring, zip, imap, bcmath, soap	全部安装 ✅
PHP 设置	`max_execution_time ≥ 240`（向导环境检查页要求）	240 ✅
Web 服务器	Apache 2.x（mod_rewrite）或 Nginx	Apache 2.4.52 ✅
后台作业	cron + `bin/console mautic:*` 命令	cron 已装 ✅

⚠️ 注意：Ubuntu 22.04 官方源的 MySQL 8.0 与 PHP 8.1 都不满足 Mautic 7 要求，必须分别换用 MariaDB 官方仓库（或 MySQL 8.4 官方仓库）与 ondrej/php PPA。这是 Ubuntu 22.04 装 Mautic 7 的第一大坑，第八节有实测报错原文。

二、前置准备

2.1 系统检查

lsb_release -ds
# Ubuntu 22.04.x LTS
ss -ltn | grep -E ':(80|443|3306)\s' || echo "80/443/3306 端口空闲"
df -h / | tail -1   # 建议剩余空间 ≥ 5GB（生产包 101MB，解压后 548MB）
free -g | head -2   # 建议 ≥ 2GB 可用内存

2.2 安装基础工具与 Apache

apt-get update
apt-get install -y apache2 unzip curl cron
a2enmod rewrite
systemctl enable --now apache2 cron

2.3 安装 PHP 8.3（ondrej/php PPA）

Ubuntu 22.04 官方源最高只有 PHP 8.1，需添加 ondrej/php PPA：

apt-get install -y software-properties-common
add-apt-repository -y ppa:ondrej/php
apt-get update
apt-get install -y php8.3 libapache2-mod-php8.3 php8.3-mysql php8.3-curl \
  php8.3-gd php8.3-intl php8.3-xml php8.3-mbstring php8.3-zip \
  php8.3-imap php8.3-bcmath php8.3-soap
php -v | head -1
# PHP 8.3.35 (cli) (built: Sep 25 2026 05:16:32) (NTS)   ← 实测回显

调整向导环境检查的两项 PHP 设置（实测默认值 max_execution_time=30、memory_limit=128M，均不达标）：

sed -i 's/^max_execution_time = .*/max_execution_time = 240/' /etc/php/8.3/apache2/php.ini
sed -i 's/^memory_limit = .*/memory_limit = 512M/' /etc/php/8.3/apache2/php.ini
grep -E '^(max_execution_time|memory_limit)' /etc/php/8.3/apache2/php.ini
# max_execution_time = 240    ← 实测回显
# memory_limit = 512M         ← 实测回显

2.4 安装 MariaDB 10.11（官方仓库）

# 下载并运行官方仓库配置脚本（固定 10.11 版本线）
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash -s -- --mariadb-server-version=10.11
apt-get install -y mariadb-server mariadb-client
systemctl enable --now mariadb
mariadb --version
# mariadb  Ver 15.1 Distrib 10.11.19-MariaDB, for debian-linux-gnu (x86_64) ...  ← 实测回显

创建 Mautic 数据库与专用账号（生产环境请替换强密码）：

mariadb -e "CREATE DATABASE mautic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mautic'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL PRIVILEGES ON mautic.* TO 'mautic'@'localhost';
FLUSH PRIVILEGES;"
mariadb -e 'SELECT VERSION();'
# 10.11.19-MariaDB-ubu2204   ← 实测回显

2.5 安装本机邮件通道（Postfix，可选）

若没有第三方 SMTP 服务商，可先装一个本机 Postfix 作为 MTA（仅本机监听 25 端口，用于联调；生产对外发信仍需处理 SPF/DKIM/DMARC 或换用 SMTP 服务商）：

DEBIAN_FRONTEND=noninteractive apt-get install -y postfix   # 选择 "Local only"
systemctl enable --now postfix
systemctl is-active postfix
# active   ← 实测回显

三、方案 A：生产包 + Web 安装向导（推荐）

3.1 下载生产包

cd /opt
curl -L -o 7.2.1.zip https://github.com/mautic/mautic/releases/download/7.2.1/7.2.1.zip
sha1sum 7.2.1.zip
# f419eff698a6e7d82f6b1dc5f6effb05973bb837  7.2.1.zip   ← 与官方 Releases 页公布值一致

💡 也可用 https://www.mautic.org/download/latest（本次实验实测该地址返回 404，改用 GitHub Releases 直链成功下载，读者若遇 404 请用 Releases 直链）。

3.2 解压并设置权限

mkdir -p /var/www/mautic
unzip -q /opt/7.2.1.zip -d /var/www/mautic
chown -R www-data:www-data /var/www/mautic
du -sh /var/www/mautic
# 548M   ← 实测回显（含全部 vendor 依赖，无需再跑 composer install）
ls /var/www/mautic
# app  bin  config  media  plugins  public  templates  themes  var  vendor  ...  ← 实测目录结构

💡 注意：Mautic 7 的 Web 根目录就是解压目录本身（public 为资源入口由 .htaccess 控制）；bin/console、config/、var/ 都在这一层。

3.3 配置 Apache 虚拟主机

cat > /etc/apache2/sites-available/mautic.conf <<'EOF'
<VirtualHost *:80>
    ServerName mautic.example.com
    DocumentRoot /var/www/mautic

    <Directory /var/www/mautic>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/mautic_error.log
    CustomLog ${APACHE_LOG_DIR}/mautic_access.log combined
</VirtualHost>
EOF
a2ensite mautic && a2dissite 000-default
apache2ctl configtest
# Syntax OK   ← 实测回显
systemctl reload apache2
curl -sI http://localhost/ | head -3
# HTTP/1.1 302 Found
# Location: /installer          ← 实测回显：未安装时自动跳转安装向导

3.4 Web 安装向导（实测流程）

浏览器访问 http://<服务器IP或域名>/，自动跳转 /installer。实测 Mautic 7.2.1 向导共三步（官方 7.0 文档描述的四步 Email 配置环节在 7.2.1 实测中未出现，安装完成后在 Configuration 页配置即可）。

第 1 步：Environment Check（环境检查）

页面标题实测为 Mautic Installation - Environment Check，显示 "Ready to Install!" 与建议项（实测出现两条建议：站点 URL 应使用完全限定域名而非 IP、应启用 SSL）。表单中隐藏的 site_url 默认值为当前访问地址。点击 Continue 进入下一步。

第 2 步：Database Setup（数据库设置）

实测表单字段与本次填写值：

表单字段	实测填写值
Database Driver	pdo_mysql（唯一选项）
Host	127.0.0.1
Port	3306
Name	mautic
Table Prefix	留空
Username	mautic
Password	q1w2e3r4
Backup existing tables?	No
Prefix for backup tables	bak_

提交后向导自动建表（125 张数据表，实测约十几秒），随后进入第 3 步。

⚠️ 若数据库版本低于要求（如 MySQL 8.0），此步提交会直接报错，实测报错原文见第八节 Q1。

第 3 步：Administrative User（管理员账号）

实测表单字段：First Name、Last Name、Username、Email、Password。实测用简单密码 q1w2e3r4 提交被拒绝，页面报错原文：

Please enter a stronger password. Your password must use a combination of
upper and lower case, special characters and numbers.

改用 q1w2e3r4Admin!（含大小写+数字+特殊字符）后通过。提交后向导完成安装，浏览器实测直接跳转到 /s/login 登录页（并自动带出已登录会话，无需再输密码即可进入 Dashboard）。

登录后台：访问 http://<服务器IP或域名>/s/login，输入管理员账号密码，实测登录成功进入 Dashboard 页面。本文实验环境约定：管理员账号 admin，密码 q1w2e3r4Admin!。

四、方案 B：命令行安装（实测可复现）

生产包解压后也可全程不进浏览器，用官方 mautic:install 命令安装（适合脚本化/无人值守）。

4.1 准备第二套数据库（用于本实验的双实例演示）

mariadb -e "CREATE DATABASE mautic_cli CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mauticcli'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL PRIVILEGES ON mautic_cli.* TO 'mauticcli'@'localhost';
FLUSH PRIVILEGES;"
mkdir -p /var/www/mautic2
unzip -q /opt/7.2.1.zip -d /var/www/mautic2
chown -R www-data:www-data /var/www/mautic2

4.2 执行 CLI 安装

cd /var/www/mautic2
php bin/console mautic:install --force \
  http://mautic2.local \
  --db_host=127.0.0.1 --db_port=3306 \
  --db_name=mautic_cli --db_user=mauticcli --db_password=q1w2e3r4 \
  --db_backup_tables=false \
  --admin_firstname=Mautic --admin_lastname=Admin \
  --admin_username=admin --admin_email=admin@mautic.local \
  --admin_password=q1w2e3r4Admin!

实测完整回显：

Mautic Install
==============
Parsing options and arguments...
0 - Checking installation requirements...
Missing optional settings:
 * Mautic is configured to run without SSL, but is recommended to use SSL
   as it increases security, and is required for some features. Install SSL
   and change your site_url setting.

Ready to Install!
1 - Creating database...
1.1 - Creating schema...
1.2 - Loading fixtures...
2 - Creating admin user...
3 - Final steps...
================
Install complete
================

验证（实测）：/var/www/mautic2/config/local.php 已生成；mautic_cli 库建表 125 张，与 Web 向导结果一致。

⚠️ 实测说明 1：--force 作用是跳过上面的 SSL 建议确认；不加该参数时命令会停在 Continue with install anyway? [yes/no] 交互确认，脚本化场景务必带上（或用 --no-interaction，实测其默认答复会中止安装）。

⚠️ 实测说明 2：官方安装文档示例中的 --mailer_from_name / --mailer_from_email 参数在 7.2.1 实测中已不存在，传入会报 The "--mailer_from_name" option does not exist.；邮件参数需安装后在后台 Configuration 页配置（或改 config/local.php，见本专栏《Mautic 7 配置参数详解》）。

💡 CLI 安装亦分步可断点续跑：mautic:install <site_url> <step>，step 0=requirements/1=database/2=admin/3=configuration/4=final（--help 实测原文）。

4.3 为第二实例配置虚拟主机

sed 's/mautic.example.com/mautic2.example.com/; s|/var/www/mautic|/var/www/mautic2|' \
  /etc/apache2/sites-available/mautic.conf > /etc/apache2/sites-available/mautic2.conf
a2ensite mautic2 && systemctl reload apache2

在 DNS/hosts 中把 mautic2.example.com 指向本机后即可独立访问第二实例。

五、方案 C（进阶）：Composer 方式安装

Composer 方式适合需要二次开发或用 composer update 管理依赖的团队（转述官方文档：composer create-project mautic/recommended-project <版本> --no-interaction，代码在 <目录>/docroot 下，Apache 根目录应指向 docroot）。本实验未实测该路径（生产包方案已覆盖生产场景），读者采用时注意三点：

Ubuntu 22.04 源内 Composer 为 2.2.6（实测可用 apt install composer），Mautic 项目要求 Composer 2.x 即可运行；
Composer 安装需联网拉取数百个包，务必配置好代理或镜像；
安装后 Web 根目录是 docroot，与生产包方案的目录结构不同，Apache 配置需相应调整。

六、安装后配置说明

6.1 定时任务（必配，否则核心功能不运转）

以 www-data 身份配置 cron（实测 Mautic 7.2.1 的发送队列命令已更名，旧文档写的 mautic:emails:send 在 7.2.1 会报 CommandNotFoundException，详见第八节 Q5）：

crontab -u www-data -e

加入以下五行（实测 adopted 配置）：

*/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

各命令职责与实测回显详见本专栏《Mautic 7 常用 CLI 命令详解》；注意实测 systemctl enable --now cron 前提是已安装 cron 包（Ubuntu 22.04 默认未预装，apt-get install -y cron）。

6.2 常驻服务（systemd 托管）

Mautic 本身无需常驻应用进程（PHP 由 Apache 模块承载），需要保证 systemd 托管的有四项（本文安装时均已 enable）：

systemctl is-active apache2 mariadb postfix cron
# active / active / active / active   ← 实测回显

6.3 后台邮件通道配置

登录后台 → Settings 图标 → Configuration → Email Settings 页签，将 Mail Send 方式配置为 Send email via SMTP（Host 127.0.0.1、Port 25、无加密），或直接在 config/local.php 写入 mailer_dsn（实测值与联动行为见本专栏《Mautic 7 配置参数详解》）。

6.4 HTTPS 与防火墙

生产环境建议为域名申请 Let's Encrypt 证书（apt install certbot python3-certbot-apache 后 certbot --apache），安装向导的环境检查页也会给出启用 SSL 的建议（实测原文见 3.4）；
防火墙只需放行 80/443（ufw allow 80,443/tcp）；数据库端口 3306 不要对公网开放。

七、多版本共存、升级与卸载

7.1 多实例共存（实测）

本实验在同一台服务器上同时运行了两套独立实例：/var/www/mautic（库 mautic，Web 向导安装）与 /var/www/mautic2（库 mautic_cli，CLI 安装），互不干扰。共存的三个隔离点是：独立目录 + 独立数据库 + 独立 VirtualHost（域名区分）。cron 按实例分别指向各自的 bin/console 路径。

7.2 升级

小版本升级（如 7.2.1 → 7.2.x）用后台 Updates 页或命令行：

cd /var/www/mautic
php bin/console mautic:update:find     # 检查更新（实测当前已是最新版，无输出）
php bin/console mautic:update:apply    # 应用更新
php bin/console mautic:cache:clear

跨大版本（5/6 → 7）请按官方升级文档逐步执行（涉及 PHP/Symfony 基线变化），升级前务必 mysqldump 备份数据库与 config/local.php。

7.3 卸载

# 删除站点与代码
a2dissite mautic && rm /etc/apache2/sites-available/mautic.conf
rm -rf /var/www/mautic
crontab -u www-data -r        # 清理 cron
# 删除数据库与账号
mariadb -e "DROP DATABASE IF EXISTS mautic; DROP USER IF EXISTS 'mautic'@'localhost';"
# 如需连组件一起清掉
# apt-get remove --purge -y apache2 mariadb-server postfix && apt-get autoremove -y
systemctl reload apache2

八、常见问题排障实录（真实报错原文）

Q1：数据库版本太旧，向导数据库步骤报错

Ubuntu 22.04 官方源 MySQL 8.0 直接被 7.2.1 安装器拒绝，实测报错原文（数据库设置页红色错误框）：

Your database version (8.0.46-0ubuntu0.22.04.4) is too old for Mautic to
work correctly. Supported versions are MySQL 8.4.0 (or higher) and MariaDB
10.11.0 (or higher).

解决：卸载 mysql-server 并按 2.4 节安装 MariaDB 10.11（或改用 MySQL 8.4 官方仓库），重建库与账号后重试。

Q2：管理员密码复杂度被拒

向导第 3 步用简单密码提交被拒，实测报错原文：

Please enter a stronger password. Your password must use a combination of
upper and lower case, special characters and numbers.

解决：密码需同时含大写、小写、数字、特殊字符（Mautic 5.1 起强制）。

Q3：改了 config/local.php 后访问 500

实测原因：清缓存后 var/cache 归属 root，Web 进程无权限。解决：

chown -R www-data:www-data /var/www/mautic/var/cache

Q4：API 调用返回 api_disabled

实测报错：{"errors":[{"message":"API disabled. You need to enable the API in the API settings of Mautic's Configuration.","code":403,...}]}。解决：Configuration → API Settings 开启 API 与 HTTP Basic 认证（或在 config/local.php 加 'api_enabled' => true, 'api_enable_basic_auth' => true 后 mautic:cache:clear）。

Q5：mautic:emails:send 命令不存在

旧教程/官方文档中的发送队列命令在 7.2.1 实测已移除，报错原文（var/logs/mautic_prod-*.log）：

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

解决：改用 mautic:messages:send（5 代起邮件队列迁移到 Symfony Messenger，该命令有别名 mautic:campaigns:messagequeue）。

Q6：生产包缺组件导致建邮件 500

实测现象：生产包安装后通过 API/UI 创建带链接的 Email 时报 500，日志出现：

PHP Warning - include(/var/www/mautic/vendor/composer/../symfony/dom-crawler/Crawler.php):
Failed to open stream: No such file or directory

解决：进入实例目录补装该组件并恢复属主：

cd /var/www/mautic
composer require --no-scripts --no-interaction symfony/dom-crawler:^7.4
chown -R www-data:www-data vendor var/cache

7.2.1 Release Notes 自述已修复"production installs 缺组件"问题（PR #17265），但实测其生产包仍复现，读者遇到时按上述方法处理即可。

Q7：本机 Postfix 联调发送失败（STARTTLS 证书不匹配）

实测报错：Unable to connect with STARTTLS: stream_socket_enable_crypto(): Peer certificate subjectAltName did not match expected name '127.0.0.1'。原因：Postfix 自签证书的 CN/subjectAltName 与 127.0.0.1 不符，Symfony Mailer 默认校验对端证书。解决：mailer_dsn 追加关闭校验参数（仅限本机 MTA 场景）：

'mailer_dsn' => 'smtp://127.0.0.1:25?verify_peer=0',

修改后 php bin/console mautic:cache:clear 并修正 var/cache 属主，实测单发联系人返回 {"success":true}，postfix 日志记录完整 SMTP 事务（ehlo=2 starttls=1 mail=1 rcpt=1 data=1 quit=1 commands=7），email_stats 表 is_failed=0。

Q8：cron 装了却不跑

Ubuntu 22.04 默认没有 cron 包，crontab 命令不存在（实测报错 bash: crontab: command not found）。apt-get install -y cron && systemctl enable --now cron 后正常。

九、参考链接

Mautic 7 官方安装文档：https://docs.mautic.org/en/7.0/getting_started/how_to_install_mautic.html
官方需求页：https://www.mautic.org/download/requirements
Mautic 7.2.1 Releases 页（生产包与 SHA1）：https://github.com/mautic/mautic/releases/tag/7.2.1
MariaDB 仓库配置脚本：https://mariadb.org/download/ 与 https://r.mariadb.com/downloads/mariadb_repo_setup
ondrej/php PPA：https://launchpad.net/~ondrej/+archive/ubuntu/php
Mautic 知识库（cron 与排障）：https://kb.mautic.org/