【实用的开源工具】Matomo：功能最全的自托管网站统计（PHP + MySQL）

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-31，具体版本以官方为准。文中的命令来自官方文档和镜像说明，我没有在本文里逐条实际运行过，上线前请先在测试环境走一遍。

项目信息卡

官方要求（以文档为准，别只看仓库 README）

官方 Requirements 页面写的是：

• Web 服务器：Apache、Nginx、IIS、LiteSpeed 等。
• Matomo 4.16 和 Matomo 5：PHP 8，以及 MySQL 5.5 或更高版本、或 MariaDB。
• Matomo 6.0.0：PHP 8.1 或更新，MySQL 8.0 或更新，或 MariaDB 10.6 或更新。
• PHP 扩展 pdo 和 pdo_mysql，或者 mysqli（默认启用）。
• 推荐使用最新的 PHP 8.x（官方说更省内存、更快），数据库推荐 MySQL 8+ 或 MariaDB；另外建议装 php-curl、php-gd、php-cli、php-xml、php-mbstring 等扩展，其中 GD 用来生成迷你图和邮件报告里的图表。
• 数据库用户需要有创建和修改表的权限，官方列出的权限是：SELECT、INSERT、UPDATE、DELETE、CREATE、INDEX、DROP、ALTER、CREATE TEMPORARY TABLES、LOCK TABLES、FILE。
• 官方给的最低规模建议：每月 10 万页面浏览量以内，应用服务器 2 CPU、2 GB 内存、50 GB SSD，数据库可以同机；每月 100 万以内，应用服务器 4 CPU、8 GB 内存、250 GB SSD。

文档不一致提醒： 仓库里 5.x-dev 分支的 README 仍写着 “PHP 7.2.5 或更高、MySQL 5.5 或更高”，默认分支 6.x-dev 的 README 则写 “PHP 8.1.0、MySQL 8.0 或 MariaDB 10.6”，而官网 Requirements 页面对 Matomo 5 写的是 PHP 8。我以官网文档为准；不管哪个说法，都以安装向导里的“系统检查”结果为最终依据。

它能做什么

• 全功能的统计：官方 README 列出电商跟踪、目标跟踪、营销活动跟踪、自定义变量、邮件报告、自定义细分、地理位置、实时访客和地图等。
• 隐私选项：可以配置成更尊重访客隐私的方式，比如强制不使用 cookie（见下文）。
• 插件体系：功能以插件形式提供，官方说默认带 40 多个官方维护的插件，并有插件市场。
• API：可以通过 Matomo API 取出统计数据。
• 多网站、多用户：一个实例可以统计多个网站，并管理用户权限。

不太适合的场景：服务器很小、也不想维护 PHP 和 MySQL；或者你只想要最简单的几个数字。

和同类项目怎么选

下面只列我在各项目官方文档里核对过的事实，不涉及性能和“谁更好”的比较：

怎么选：习惯 PHP 加 MySQL 的传统环境，或者想要电商、目标、细分这类较完整的功能，Matomo 合适；想要更小的组件，可以看 Umami 和 Plausible。是否需要弹同意提示，取决于你所在地区的法规；官方说明某些配置下的 Matomo 可以在不征求同意的情况下使用，具体要看官方的 ePrivacy 和各国实施指南，请自己核对，这里不做合规结论。

部署方式一：官方 Docker Compose（推荐）

官方 Docker 指南说明：单容器方式（只跑 Matomo、连外部数据库）只适合测试，不适合生产；生产建议用 Docker Compose 的多容器方式，包含 Matomo、MariaDB 和一个负责自动归档的 cron 容器。

先建目录：

mkdir -p /opt/matomo && cd /opt/matomo

compose.yaml（结构来自官方 Docker 指南，我做了三处改动：Matomo 固定为 5.14.2、MariaDB 固定为 11.8、端口只绑定本机）：

services:
  db:
    image: mariadb:11.8
    container_name: matomo-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: 改成你的root密码
      MYSQL_DATABASE: matomo
      MYSQL_USER: matomo
      MYSQL_PASSWORD: 改成你的matomo库密码
    volumes:
      - matomo-db-data:/var/lib/mysql

  matomo:
    image: matomo:5.14.2
    container_name: matomo-app
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    environment:
      MATOMO_DATABASE_HOST: db
      MATOMO_DATABASE_USERNAME: matomo
      MATOMO_DATABASE_PASSWORD: 改成你的matomo库密码
      MATOMO_DATABASE_DBNAME: matomo
    volumes:
      - matomo-app-data:/var/www/html
    depends_on:
      - db

  cron:
    image: matomo:5.14.2
    container_name: matomo-cron
    restart: unless-stopped
    volumes:
      - matomo-app-data:/var/www/html
    entrypoint: >
      /bin/sh -c "while true; do
      php /var/www/html/console core:archive;
      sleep 300;
      done"
    depends_on:
      - db

volumes:
  matomo-db-data:
  matomo-app-data:

关于这几处改动：

• 官方示例写的是 mariadb:latest 和 matomo:latest、端口 "8080:80"。我把 Matomo 改为 5.14.2：Docker Hub 上 matomo 镜像的标签列表里能看到 5.14.2、5.14、5、latest 等；MariaDB 改成 11.8，我在 Docker Hub 查到这个标签存在。固定版本是通用的稳妥做法，改版本号之前请再确认标签存在。
• 端口绑定到 127.0.0.1，因为后面要用反向代理。Docker 发布的端口会绕过 ufw 之类的防火墙（通用经验）。
• 官方说明 cron 容器每 300 秒（5 分钟）运行一次 core:archive，大多数环境够用，流量很大时可以更频繁。matomo 和 cron 必须使用同一个镜像、挂载同一个应用卷。
• 数据量大时，可以给 matomo 和 cron 两个容器都加环境变量 PHP_MEMORY_LIMIT（官方示例是 512M），因为网页界面和归档进程都用 PHP。

启动并检查：

docker compose up -d
docker ps -a

然后打开 Matomo 的地址，走安装向导。数据库一步按官方写的填：服务器 db、用户名 matomo、你设置的密码、数据库名 matomo。

安装完成后，要关闭“浏览器触发归档”：官方说用了 cron 容器后，进入 Administration > System > General settings，取消勾选 “Archive reports when viewed from the browser”，让所有报表处理都交给 cron。

部署方式二：直接装在 PHP 环境上（传统方式）

如果你已经有 PHP + MySQL + Nginx/Apache 的服务器，官方安装流程是：

wget https://builds.matomo.org/matomo.zip
unzip matomo.zip

官方强调：不要从第三方下载 Matomo，文件可能被改过；官方提供 GPG 签名，可以验证下载包（做法见官方安装页面里链接的校验说明）。解压后会得到 matomo/ 目录，上传到站点目录。官方建议用 SSH（SCP/SFTP）传输，只有没有 SSH 时才用 FTP。

文件权限：官方建议让 Web 服务器可读所有文件，写权限只开放必须的目录（tmp/ 和 config/）。

然后在浏览器里打开这个地址，按“五分钟安装向导”走：欢迎页、系统检查、MySQL 数据库设置、创建超级用户（Superuser）、添加第一个网站、拿到 JavaScript 跟踪代码。官方建议为 Matomo 单独建一个数据库和一个只能访问该库的用户。

反向代理

Matomo 前面套 HTTPS 反向代理时，官方 FAQ 里需要关注的 Matomo 侧配置（在 config/config.ini.php 的 [General] 段）：

[General]
force_ssl = 1
assume_secure_protocol = 1

官方说，通过反向代理（https 到 http）安装时，assume_secure_protocol = 1 应该会在安装时自动加入；同时强烈建议也加上 force_ssl = 1，这样邮件里的链接也是 https，且所有 http 链接会跳转到 https。

访客 IP 来自代理头时，需要告诉 Matomo 读哪个头（以 X-Forwarded-For 为例，PHP 会把它变成大写并加前缀 HTTP_，所以配置里写 HTTP_X_FORWARDED_FOR）：

[General]
proxy_client_headers[] = HTTP_X_FORWARDED_FOR
proxy_host_headers[] = HTTP_X_FORWARDED_HOST

官方说这些通常会在安装时自动检测并写入；检测不到才需要手动加。官方还说明：从 Matomo 5 起，默认读取代理头里的最后一个 IP，防止伪造的 X-Forwarded-For；如果升级到 5 之后发现访客 IP 都变成内网地址，可能需要设置 proxy_ip_read_last_in_list = 0。

Nginx 一侧，官方文档没有为 Docker 部署给出专门的配置。下面是一个通用的最小示例（不是官方内容，请按自己环境调整并加上证书）：

server {
    listen 443 ssl;
    server_name analytics.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

另外官方有一条关于 Nginx 的安全提示：不用 Docker、自己配 Nginx 时，应使用官方的 Matomo Nginx 配置，确保 tmp/ 和 config/ 目录无法被网络访问。

第一次使用 / 把统计代码装到网站

1. 创建超级用户：安装向导里创建。官方说每个 Matomo 安装只有一个超级用户，可以添加网站、添加用户、改权限、开关插件，别丢了这个账号。
2. 添加第一个网站：向导里填名称和网址，之后也可以在后台继续添加。
3. 拿到跟踪代码：向导最后一步会给出 JavaScript 跟踪代码。之后找回的路径（来自官方开发者指南）：登录后点右上角齿轮（Administration），左侧菜单里的 “Tracking Code”（在 Measurables 或 Websites 菜单下），进入 “JavaScript Tracking”，选择网站，复制。
4. 贴到网站里：安装向导建议放在 </head> 前面，或者放在所有页面共用的页头文件里；开发者指南说紧跟 <body> 开始标签后或 <head> 里都可以。代码长这样（来自官方开发者指南，{$MATOMO_URL} 要换成你的地址，{$IDSITE} 换成网站编号，下面用 example 域名示意，请复制你自己后台里显示的那份）：

<!-- Matomo -->
<script type="text/javascript">
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//analytics.example.com/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', 1]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Code -->

1. 需要不使用 cookie：官方说，超级用户进入 Administration > Privacy > Anonymize data，勾选 “Force tracking without cookies”，跟踪脚本就不会再使用 cookie，服务器端也会忽略收到的跟踪 cookie。这个设置对所有网站生效，并会对数据准确性有一定影响。默认情况下，跟踪代码会设置第一方 cookie：_pk_id（访客 ID，默认 13 个月）、_pk_ses（会话，30 分钟）、_pk_ref（来源归因，6 个月）。
2. 官方有 WordPress、Shopify、Wix 等常见平台的接入指南，也有 Matomo for WordPress 插件，这里不展开。

归档（auto-archiving）cron：别漏掉

官方安装文档的说法：网站每天访问量超过几百次时，强烈建议设置自动归档的定时任务，让 Matomo 定期把报表算好；不设置的话，每次你查看报表时 Matomo 都要重新计算，会拖慢界面并增加数据库负载。

Docker 部署已经用上面的 cron 容器解决。传统部署在 /etc/cron.d/matomo-archive 里写（官方示例，请把路径和网址换成自己的）：

MAILTO="[email protected]"
5 * * * * www-data /usr/bin/php /path/to/matomo/console core:archive --url=https://analytics.example.com/ > /home/example/matomo-archive.log

然后在 config/config.ini.php 的 [General] 段加上：

[General]
browser_archiving_disabled_enforce = 1

官方还提醒：要定期检查归档任务发出的错误信息（发到 MAILTO 的邮箱，也会记到日志里），日志文件要放在 Web 服务器无法访问的位置。

更新与卸载

更新

Docker（官方 Docker 指南）：拉取新镜像并重建容器，只要卷还在，数据就保留。

cd /opt/matomo
# 先把 compose.yaml 里 matomo 和 cron 两处的标签改成要升级的版本（先确认标签存在）
docker compose pull matomo
docker compose up -d

官方还建议同时使用最新的数据库镜像，因为里面的系统包修复了已知漏洞。更新后 Matomo 可能提示需要更新数据库，在浏览器里按提示点更新（官方更新指南：数据库更新可能要几分钟，更新过程中不要关闭或刷新页面）。数据库很大的站点，官方建议在命令行执行 console core:update，并建议更新期间关闭跟踪和界面。Docker 里调用 console 的写法参考官方的 docker exec matomo-app php /var/www/html/console core:archive，把命令换成 core:update 即可（这是我的类推，官方没有直接给 Docker 版的 core:update 命令）。

传统部署：官方有两种方式。一键更新（在后台点更新提示），需要 Matomo 目录有写权限；手动三步：备份 config/config.ini.php，用最新的 matomo.zip 覆盖文件（unzip -o matomo.zip），再在浏览器里完成数据库更新。更新后，官方建议看一眼 System check 报告。

官方还提供 Long Term Support（LTS）：在 System > General Settings 的 Update Settings 里把 Release channel 选成 “Latest stable 5.X (Long Term Support version)”，就会停留在 Matomo 5 的最新版本。官方文档说，某个大版本的 LTS 至少在下一个大版本发布后继续支持 12 个月。

备份

更新前先备份，官方的备份页给出的数据库导出命令（把大写的占位符换成你的值）：

mysqldump --extended-insert --no-autocommit --quick --single-transaction MATOMO_DATABASE_NAME -uMATOMO_DATABASE_USERNAME -p > matomo_backup_database.sql

官方还说明要备份 config/config.ini.php（里面有数据库密码，要像对待数据库一样保管）。Docker 里怎么执行 mysqldump（比如 docker compose exec db …）官方没有写，请自己按环境调整。

卸载

官方 FAQ 的步骤：从所有被统计的网站上去掉跟踪代码；删除 matomo/ 目录里的所有文件；用 MySQL 客户端删除存放 Matomo 数据的数据库。

Docker 部署的对应通用做法（官方没写）：docker compose down 停止并删除容器、数据卷保留；确认数据不要了，再用 docker compose down -v 连同数据卷一起删除，这一步不可恢复。

踩坑清单

1. PHP 项目必须保持更新。 官方的安全文档建议：使用最新的 PHP、MySQL（或 MariaDB）、Web 服务器和操作系统，也要订阅 Matomo 的更新日志并保持 Matomo 为最新版本，发现安全问题时官方会尽快发布修复。再加一条通用建议：别在已停止安全维护的 PHP 版本上跑生产。
2. 官方 Docker 镜像不在 Matomo 的安全评估范围内。 官方 Docker 指南写明，安全测试针对的是 Matomo 代码本身，不包括容器镜像及其系统包。建议自己定期拉取新镜像和新的数据库镜像；对安全要求严格的话，官方建议自建镜像，或在官方镜像基础上更新系统包。
3. 单容器 docker run 只适合测试。 没有数据库管理，也没有归档任务，不适合生产。
4. 一定要持久化 /var/www/html。 配置文件、插件都在里面。没挂卷的话容器重建后，安装向导会再次出现、插件会消失。matomo 和 cron 容器必须挂同一个应用卷，否则 cron 容器可能找不到插件，造成报表不完整。
5. MYSQL_* 环境变量只在数据库卷第一次初始化时生效。 官方明确说，后面改这些值不会更新已有数据库卷，不要为了改密码而删有数据的卷。
6. 不设归档 cron，界面会越来越慢。 Docker 版用 cron 容器，并取消勾选“Archive reports when viewed from the browser”；传统版写 core:archive 的 cron 并设置 browser_archiving_disabled_enforce = 1。
7. 安装向导有 72 小时窗口。 从 Matomo 5.2.0 起，安装向导第一次被访问时会在 config.ini.php 里记下时间戳，超过 72 小时就拒绝再访问。要重置，手动删除配置文件里的 installation_first_accessed 一行。另外，向导没跑完之前，任何能访问到这个地址的人都可能抢先安装，所以我把端口绑定在本机、尽快完成安装（后半句是通用建议）。服务器时间不准也会让向导提前被锁。
8. 可信主机检查（Trusted Host Check）默认开启。 用没有登记的域名访问 Matomo 会显示警告。官方说明安装时使用的主机名会自动成为初始可信主机，所以如果你是用 127.0.0.1 或 SSH 隧道装的，之后用正式域名访问就可能报警告，需要在 Administration > System > General Settings > Trusted Matomo Hostname 里添加，或在 config/config.ini.php 里写 trusted_hosts[] = analytics.example.com。官方不建议用 enable_trusted_host_check = 0 关掉它。
9. 放在 HTTPS 反向代理后面要配 force_ssl 和 assume_secure_protocol，访客 IP 要配 proxy_client_headers[]。 否则链接是 http、IP 全是代理的地址。官方还说明：如果 Matomo 装在子路径下且代理做了路径改写，需要让代理传 X-Forwarded-Uri，并在 Matomo 配置里读取它；最省事的办法是用独立的子域名（这一句是通用建议）。
10. 数据库不能走会分流的负载均衡。 官方说明 Matomo 不能配合 ProxySQL 之类的 MySQL 负载均衡器使用，除非保证同一个连接里的查询总是发到同一台数据库服务器。数据库用户的权限要给够（上面那串），官方 FAQ 目录里还有专门一条讲升级时因为缺 INDEX 权限而失败。
11. 一定用 HTTPS 访问后台。 官方说，登录名、密码、token_auth 都会出现在服务器响应里，用明文能被人在网络上看到。建议同时开启双因素认证（Administration > Personal > Security）。
12. 默认会设置 cookie，是否需要同意提示由你判断。 默认跟踪代码设置的是第一方 cookie；强制无 cookie 能避免设置它们，但官方说明会影响数据准确性。合规结论请自己核对官方的隐私指南。
13. Matomo 6 还在测试阶段。 官方 Requirements 页面已经写了 6.0.0 需要 PHP 8.1+、MySQL 8.0+ 或 MariaDB 10.6+。现在生产环境用稳定版 5.x，升大版本前先确认你的 PHP 和数据库满足新要求。
14. 配置文件里有数据库密码。 config/config.ini.php 同时记录着安装状态，要备份，也要像数据库一样保管；安装完成后，官方建议把 config/ 的权限收紧（只读），仅 tmp/ 以及 js/piwik.js、js/matomo.js 需要写权限。注意收紧权限后，一键更新和从后台装插件会不可用，官方建议这时在 [General] 里设置 enable_auto_update = 0 并改为手动更新。

出处

• Matomo 仓库 README（说明、许可证、要求）
• Matomo 仓库 6.x-dev 分支 README
• 官方：Requirements for Matomo On-Premise（PHP、MySQL 要求和服务器规模建议）
• 官方：Matomo On-Premise 文档总览
• 官方：Installing Matomo On-Premise（下载、五分钟安装向导）
• 官方：Install Matomo with Docker
• 官方：Persisting Matomo data and plugins in Docker
• 官方：Docker Hub 官方镜像说明（环境变量、标签）
• 官方：How to set up Auto-Archiving (CRON)
• 官方：Update Matomo
• 官方：Matomo Long Term Support (LTS)
• 官方：Configure Matomo for security
• 官方：Manage secure access to the Matomo Installer（72 小时窗口）
• 官方：Trusted Host Check
• 官方：Matomo behind a proxy
• 官方：Backup and restore the Matomo data
• 官方：Uninstall Matomo
• 官方：Matomo 使用的 cookie
• 官方：Force tracking without cookies
• 官方开发者指南：JavaScript 跟踪（跟踪代码）