Matomo Docker 官方镜像完整使用指南：快速部署、持久化、安装向导与日志导入

• 文档

Matomo（原 Piwik）是一款开源、注重隐私保护的网站分析平台，而matomo是 Docker 官方镜像（Docker Official Images）项目中的一员，本文以仓库中 matomo/README.md 及其源文件 matomo/content.md 为核心，系统讲解如何用 Docker 启动 Matomo、配置数据持久化、通过环境变量完成安装向导，以及使用官方日志导入脚本。读完本文，你将掌握从一条docker run命令到完整可用的 Matomo 分析实例的全套实战技能。

Matomo（原名 Piwik）是什么

Matomo 是一个开源、可自托管的网站/应用分析平台，其核心卖点不止于"强大的分析能力"：

• 自由开源软件：源码开放，可自由使用与二次开发；
• 100% 数据所有权：数据完全保存在你自己的服务器上，不依赖第三方云服务；
• 用户隐私保护：支持匿名化、GDPR 合规等隐私友好特性；
• 以用户为中心的洞察：提供访问者行为、来源、转化等维度分析；
• 可定制、可扩展：支持插件体系与 API，可按需扩展功能。

在 Docker 官方镜像体系中，matomo镜像由 Matomo 社区贡献者维护（见 matomo/maintainer.md），并在 Docker Hub 的分类中归属于"monitoring-and-observability"（监控与可观测性），见 matomo/metadata.json。

镜像标签与架构支持

官方matomo镜像当前主要提供三类标签（基于 Matomo 5.14.0）：

在架构支持上，官方镜像覆盖了amd64、arm32v5、arm32v6、arm32v7、arm64v8、i386、ppc64le、riscv64、s390x共九种架构，可以按需拉取对应平台的镜像。

这些标签列表并不是手工维护在文档中的，而是由 .template-helpers/generate-dockerfile-links-partial.sh 通过bashbrew从 official-images 的 library 清单中动态抓取的——文档中标注的 Dockerfile 链接直接对应apache、fpm、fpm-alpine三套构建目录。

快速上手：一条命令启动 Matomo

最简单的方式是直接运行：

docker run -d --link some-mysql:db matomo

这行命令的前提是：你已经先启动了一个合适的 MySQL 或 MariaDB 数据库容器（例如some-mysql），并通过--link将其以别名db暴露给 Matomo 容器。Matomo 容器启动后会自动进入 Web 安装向导流程。

提示：--link属于 Docker 的遗留特性（legacy 网络连接方式），新版实践更推荐使用自定义网络 + 容器名解析，例如docker network create matomo-net后让 Matomo 与数据库容器加入同一网络，访问数据库时使用服务名。官方 README 中的最小示例仍以--link写法为准，两种方式对本文的安装向导配置同样适用。

数据持久化：让分析数据不随容器消失

默认情况下，容器内文件系统是临时的。Matomo 的 Web 根目录是/var/www/html，其中包含站点代码以及运行期生成的配置、插件、上传资源等，必须通过 Docker volume 持久化，否则容器重建后数据会丢失。

docker run -d -p 8080:80 --link some-mysql:db -v matomo:/var/www/html matomo

这条命令相比上一条增加了两个关键点：

• -p 8080:80：将容器内 Apache 的 80 端口映射到宿主机 8080 端口，之后通过http://localhost:8080访问；
• -v matomo:/var/www/html：创建并挂载一个名为matomo的命名卷，用于持久化 Matomo 应用数据。

除了应用数据卷，Matomo 的数据库数据（访问日志、配置等）默认存放在你自建的 MySQL/MariaDB 容器中，生产环境请同样为该数据库容器配置持久化卷。

Matomo 安装向导与数据库配置

容器启动后，浏览器访问映射端口即可进入配置向导页面。其中Database Setup（数据库设置）步骤是关键——如果你按照官方 Compose 示例（即数据库容器以服务名db提供）运行，请填写：

• Database Server（数据库服务器）：db
• Login（登录名）：对应MYSQL_USER环境变量的值
• Password（密码）：对应MYSQL_PASSWORD环境变量的值
• Database Name（数据库名）：对应MYSQL_DATABASE环境变量的值

其余选项保持默认即可继续，之后创建超级管理员（super user）账号完成安装。

除了向导页手动填写，官方镜像还支持通过环境变量预先配置 Matomo 数据库连接，这些变量会被 Matomo 的配置系统读取并写入config/config.ini.php：

例如：

docker run -d -p 8080:80 \ -v matomo:/var/www/html \ -e MATOMO_DATABASE_HOST=db \ -e MATOMO_DATABASE_USERNAME=matomo \ -e MATOMO_DATABASE_PASSWORD=secret \ -e MATOMO_DATABASE_DBNAME=matomo \ matomo

同时，PHP 的内存上限也可以通过环境变量调整：

• PHP_MEMORY_LIMIT：例如-e PHP_MEMORY_LIMIT=512M。当站点访问量较大或启用较多插件时，适当调高该值可以避免 PHP 内存不足（如Allowed memory size exhausted）错误。

Docker Compose 与日志导入

官方 Docker 仓库的.examples目录中提供了最小可用的 Docker Compose 编排示例（包含 Matomo 应用 + 数据库服务的完整定义），适合作为生产环境的起点。需要说明的是，本文仓库（docs）是 Docker 官方镜像的文档仓库，镜像本身的 Dockerfile 与 Compose 示例位于 Matomo 官方 Docker 源码仓库，本文档目录仅承载镜像描述文本（matomo/）。

使用官方日志导入脚本

Matomo 附带一个用 Python 编写的访问日志导入脚本misc/log-analytics/import_logs.py，可以离线解析 Apache/Nginx 等 Web 服务器日志并批量导入，适合迁移场景或补充历史数据。按 README 的说明，可以用一个一次性（--rm）容器来执行它，借助--volumes-from复用 Matomo 应用容器的文件系统：

docker run --rm \ --volumes-from="matomo-app-1" \ --link matomo-app-1 \ python:3-alpine \ python /var/www/html/misc/log-analytics/import_logs.py \ --url=http://ip.of.your.matomo.example \ --login=yourlogin \ --password=yourpassword \ --idsite=1 \ --recorders=4 \ /var/www/html/logs/access.log

各参数含义：

• --volumes-from="matomo-app-1"：挂载 Matomo 应用容器（Compose 默认命名matomo-app-1）的卷，从而访问/var/www/html下的脚本与日志；
• --url：Matomo 实例的访问地址；
• --login/--password：具备导入权限的 Matomo 用户凭据；
• --idsite：目标站点 ID（1为第一个站点）；
• --recorders：并行处理的记录器（recorder）数量，用于控制导入并发度；
• 最后一个参数：要导入的日志文件路径（示例为/var/www/html/logs/access.log）。

镜像变体（Image Variants）如何选择

matomo镜像提供多种风味（flavor），针对不同使用场景设计。

matomo:<version>（默认变体）

这是事实标准（de facto）的镜像。如果你不确定自己需要什么，通常选它就对了。它既可以作为一次性容器（挂载源码后启动即可运行应用），也可以作为构建其他镜像的基础镜像。该变体基于 Apache，开箱即带 Web 服务器，适合单容器快速部署。

matomo:<version>-alpine（Alpine 变体）

该变体基于 Alpine Linux 官方镜像。Alpine 的基础系统体积远小于大多数发行版基础镜像（约 5MB），因此最终镜像整体更瘦小。

适用场景：当"最终镜像体积尽可能小"是首要诉求时使用。

主要注意点：Alpine 使用musl libc而非glibc系列，因此对 libc 依赖较深或假设较多的软件，可能在使用中遇到兼容性问题。此外，为了压缩体积，Alpine 变体通常不带额外的相关工具（如git、bash），如果以此镜像为基础，需要在自己的 Dockerfile 中自行安装所需软件包。

选择建议：追求小体积、熟悉 musl 生态选 Alpine 变体；追求与 glibc 生态最大兼容、开箱即用选默认 Apache 变体；已有独立反向代理架构选fpm变体。

关于 GeoIP（地理位置库）

镜像内曾内置 MaxMind 的 GeoLite 数据（GeoIP 地理位置库），用于地理维度分析。但 MaxMind 自 2019 年 12 月起对 GeoLite2 数据库的访问与使用方式进行了重大变更（需要注册账号获取 license key 下载），因此文档中对"镜像自带 GeoLite 数据"的表述已被划除。实际使用地理分析功能时，请自行遵循 MaxMind 当前的数据获取与使用政策。

许可证说明

镜像内所包含软件（Matomo 本体）的许可证信息请查看 Matomo 官方仓库中的LEGALNOTICE文件（见 matomo/license.md）。

需要留意的是，与所有 Docker 镜像一样，该镜像中可能还包含来自基础发行版的其他软件（如 Bash 等），以及主软件的直接或间接依赖，它们各自适用不同许可证。使用预构建镜像时，镜像使用方有责任确保对镜像内所有软件的使用均符合相关许可证要求。

附：本文档在仓库中的生成机制

作为技术研究，这里补充说明本文档的"生产"链路，方便你在本仓库中继续深入：

• matomo/content.md 是镜像长描述（long description）的唯一真源，包含"软件简介"与"如何使用"两大板块；而 matomo/README.md 头部明确标注了DO NOT EDIT、IT IS AUTO-GENERATED；
• 仓库根目录的 update.sh 会把content.md、matomo/maintainer.md、matomo/github-repo、matomo/metadata.json 等文件与 .template-helpers/template.md 模板组合，替换%%CONTENT%%、%%LOGO%%、%%TAGS%%、%%ARCHES%%、%%LICENSE%%等占位符，最终生成matomo/README.md；
• 其中"Supported tags"章节由 .template-helpers/generate-dockerfile-links-partial.sh 调用bashbrew从 official-images 清单抓取标签并渲染，"Supported architectures"章节由 .template-helpers/arches.sh 生成；"Image Variants"章节则来自 .template-helpers/variant.md 与 .template-helpers/variant-alpine.md。

理解这条生成链路后，你就能明白：本文所有标签、架构、环境变量与使用示例，均直接来源于 Docker 官方镜像仓库的可验证文档与脚本，可以放心作为部署 Matomo 的参考依据。

• 文档