Matomo Docker 迁移完整指南

本文记录一次将自托管 Matomo（Docker 部署）从旧服务器完整迁移到新服务器的全过程，包含高 CPU 问题排查、数据迁移、HTTPS 配置等步骤。域名统一使用 stats.example.com 作为示例。

一、环境说明

旧服务器 Docker Compose 结构（示例）

version: "3"

services:
  db:
    image: mariadb:10.11
    command: --max-allowed-packet=64MB
    restart: always
    volumes:
      - db:/var/lib/mysql:Z
    environment:
      - MYSQL_ROOT_PASSWORD=your_root_password
      - MARIADB_AUTO_UPGRADE=1
      - MARIADB_DISABLE_UPGRADE_BACKUP=1
    env_file:
      - ./db.env

  app:
    image: matomo:fpm-alpine
    restart: always
    links:
      - db
    volumes:
      - matomo:/var/www/html:z
    environment:
      - MATOMO_DATABASE_HOST=db
      - PHP_MEMORY_LIMIT=2048M
    env_file:
      - ./db.env

  web:
    image: nginx:alpine
    restart: always
    volumes:
      - matomo:/var/www/html:z,ro
      - ./matomo.conf:/etc/nginx/conf.d/default.conf:z,ro
    ports:
      - 7500:80

volumes:
  db:
  matomo:

关键点：
- 使用命名 volume matomo 挂载整个 /var/www/html
- 使用命名 volume db 存储数据库
- Nginx 监听宿主机 7500 端口，反向代理到 Matomo

二、高 CPU 问题排查与解决（迁移前建议先处理）

现象

早上查看 Matomo 报告时 CPU 经常飙到 100%，平时使用正常。

原因

Matomo 默认开启「浏览器触发汇总（Browser Archiving）」。当查看包含「今天」的报告时，如果数据尚未预先汇总，会实时执行 archiving 过程，在资源有限的服务器上极易打满 CPU。

解决方法

1. 关闭浏览器触发汇总

   • 登录 Matomo 后台 → 管理 → 系统 → 常规设置 → 报告汇总设置
   • 「从浏览器查看时汇总报告」设为 否
   • 「最多每隔 X 秒汇总一次」建议设为 3600（1 小时）

2. 配置自动汇总（Cron）

推荐使用宿主机 cron + docker exec 方式（简单可靠）：

# 编辑 crontab
crontab -e

# 每小时第 5 分钟执行一次汇总（可根据数据量调整频率）
5 * * * * docker exec matomo-app-1 php /var/www/html/console core:archive --url=https://stats.example.com/ >> /var/log/matomo-archive.log 2>&1

容器名请根据实际 docker ps 结果调整（示例中为 matomo-app-1）。

三、数据迁移步骤

1. 在旧服务器备份

# 备份数据库
docker exec matomo-db-1 mysqldump \
  --extended-insert --no-autocommit --quick --single-transaction \
  -u root -pyour_root_password matomo > matomo_db_backup_$(date +%F).sql

gzip matomo_db_backup_*.sql

# 备份 Matomo 文件（包含 config、plugins 等）
docker exec matomo-app-1 tar czf - -C /var/www/html . > matomo_files_backup_$(date +%F).tar.gz

# 备份配置文件
cp db.env db.env.backup
cp matomo.conf matomo.conf.backup
cp docker-compose.yml docker-compose.yml.backup

需要传输到新服务器的文件：
- matomo_db_backup_xxxx.sql.gz
- matomo_files_backup_xxxx.tar.gz
- db.env
- matomo.conf
- docker-compose.yml

2. 在新服务器恢复

# 创建目录
mkdir -p /var/www/matomo
cd /var/www/matomo

# 放入备份文件和配置文件后，启动数据库
docker compose up -d db
sleep 10

# 导入数据库
gunzip -c matomo_db_backup_xxxx.sql.gz | docker compose exec -T db \
  mysql -u root -pyour_root_password matomo

# 启动 app 容器（创建 volume）
docker compose up -d app

# 清空并恢复文件
docker compose exec app sh -c "rm -rf /var/www/html/*"
docker compose exec -T app tar xzf - -C /var/www/html < matomo_files_backup_xxxx.tar.gz

# 修复权限
docker compose exec app chown -R www-data:www-data /var/www/html

# 启动全部服务
docker compose up -d

3. 迁移后检查

• 访问 http://新服务器IP:7500，确认历史数据完整
• 检查 config/config.ini.php 中的 trusted_hosts[]（如域名有变化需添加）
• 重新配置 archiving cron（使用新服务器的容器名）
• 确认插件、自定义 logo 等是否正常

四、Nginx 反向代理 + HTTPS 配置

1. Nginx 配置示例（/etc/nginx/sites-available/stats.example.com）

server {
    listen 80;
    listen [::]:80;
    server_name stats.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name stats.example.com;

    ssl_certificate /etc/letsencrypt/live/stats.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/stats.example.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

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

启用配置：

ln -sf /etc/nginx/sites-available/stats.example.com /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

2. 申请证书（首次）

certbot --nginx -d stats.example.com

如果遇到 duplicate listen [::]:443 等错误，可先手动写好上述配置，再使用：

certbot certonly --nginx -d stats.example.com

3. 自动续期验证

# 检查定时任务
systemctl list-timers | grep certbot

# 干跑测试
certbot renew --dry-run

建议添加续期后自动重载 Nginx 的钩子：

mkdir -p /etc/letsencrypt/renewal-hooks/deploy
cat > /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh << 'EOF'
#!/bin/bash
systemctl reload nginx
EOF
chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

五、迁移后注意事项

1. Archiving Cron：必须在新服务器重新配置，并关闭浏览器触发汇总，否则高 CPU 问题会重现。
2. 域名变更：如果域名发生变化，需要更新所有网站的跟踪代码，并在 config.ini.php 中添加新域名到 trusted_hosts[]。
3. 数据丢失窗口：数据库导出到 DNS 切换完成期间，会有短暂的数据无法记录，建议在低流量时段操作。
4. 版本一致性：迁移时尽量使用相同版本的 Matomo 镜像，避免自动升级耗时过长。
5. 回退准备：旧服务器建议保留至少一周，确认新环境稳定后再清理。

六、常用命令速查

# 查看容器
docker ps

# 进入 Matomo 容器
docker exec -it matomo-app-1 sh

# 手动执行一次汇总
docker exec matomo-app-1 php /var/www/html/console core:archive --url=https://stats.example.com/

# 查看汇总日志
tail -f /var/log/matomo-archive.log

# 重启服务
cd /var/www/matomo && docker compose restart

文档版本：2026-08
适用场景：Matomo + Docker Compose（fpm-alpine + nginx + MariaDB）迁移

评论

Reply