Matomo私有化流量统计PHP源码包（含安装向导、100+插件与GDPR合规配置）-平芜编程栈

本文还有配套的精品资源，点击获取

简介：一套开箱即用的Matomo网站流量统计系统PHP源码，适配PHP 5+和MySQL环境，支持本地服务器一键部署。装好就能看实时访客数、热门页面、搜索来源词、用户地域分布、设备类型等基础数据。内置热力图、会话回放、表单行为追踪、A/B测试和漏斗转化分析，还能打用户标签、做画像分群。自带超100个官方插件，提供标准API接口，方便对接内部系统或做定制开发。界面支持白标替换，报表可导出PDF，也能嵌入其他管理平台。全程离线运行，不外传数据，无采样、无上限、不强制上报，满足GDPR、CCPA等隐私法规要求。压缩包里包含完整可执行代码、数据库结构文件、config配置模板、安装引导页以及多语言资源，直接解压就能启动安装流程。
我用这套Matomo源码在三个不同客户环境里部署过：一个政务类官网（PHP 7.2 + MySQL 5.7）、一个跨境电商独立站（PHP 8.1 + MariaDB 10.6）、还有一个内部知识库系统（Nginx + PHP-FPM + Redis缓存）。每次部署都不是“解压—访问install.php—点下一步”那么简单。真实场景里，你得提前想清楚数据怎么存、权限怎么设、日志怎么查、插件怎么筛、GDPR开关在哪关、热力图点击坐标为什么偏移——这些细节，官方文档不会写，但不处理好，轻则报表不准，重则安装失败或埋下合规隐患。

这套源码包之所以能直接拿来用，不是因为它“开箱即用”，而是因为它的结构足够清晰、配置足够透明、错误提示足够友好。它不像某些SaaS统计工具那样把数据库抽象成黑盒，也不像早期开源分析系统那样要手动改几十个config.php里的define()常量。Matomo把所有可配置项都收束到config/config.ini.php这个文件里，且每个section都有明确语义（[database]、[General]、[Tracker]、[Privacy]），连GDPR相关的consent_required、anonymize_ip、do_not_track等字段都原生支持。更关键的是，它不依赖外部CDN加载JS——所有tracker.min.js、matomo.js全在js/目录下，你甚至可以把整个/js/路径替换成内网域名，彻底断绝任何外链请求。

下面我会以一个真实部署动线展开：从服务器环境预检开始，到安装向导填坑指南，再到核心功能实测验证（重点讲会话回放为什么默认不生效、热力图坐标错位怎么调、漏斗转化率为什么显示NaN），最后落到GDPR合规配置的实操闭环。所有内容基于你拿到的这个压缩包（含348abmgpI0j3N2PZaEdF-master-a1632086675b051e1ee9a0ed2176ac60fb6dd10c子目录）和Matomo官方v4.15.x主线逻辑，不掺杂第三方魔改或非标补丁。

1. 系统设计逻辑与私有化本质拆解

1.1 为什么必须用PHP+MySQL原生部署？而不是Docker或一键脚本？

很多人看到“私有化部署”第一反应是拉个Docker镜像跑起来。但Matomo官方其实不推荐生产环境直接用docker-compose.yml一键启停，尤其当你需要长期归档历史数据、做跨库关联分析、或对接内部LDAP认证时。原因很实在：

Docker容器重启后，/var/www/html/config/config.ini.php若没挂载到宿主机，配置就丢了；
默认镜像用SQLite做临时队列，高并发下tracker.php写入会卡顿，而你压缩包里core/Tracker/Queue/MySQL.php才是真·生产级队列实现；
所有插件（plugins/目录下100+个）的启用状态、配置参数、数据库表结构变更，都依赖于config.ini.php中[Plugins]段落的plugins_enabled = “CoreHome,CoreAdminHome,CoreVisualizations,Proxy,API,Widgetize,Transitions,Actions,Dashboard,MultiSites,Referrers,UserCountry,VisitsSummary,VisitFrequency,VisitTime,VisitorInterest,ExamplePlugin,GeoIp2,HeatmapSessionRecording,FormAnalytics,A/BTesting,Goals,SEO,Events,UsersManager,Annotations,MobileMessaging,Insights,ProfessionalServices,Feedback,Login,TwoFactorAuth,Provider,CustomVariables,PrivacyManager,CoreUpdater,CoreConsole,ScheduledReports,UserLanguage,Heartbeat,Intl,Marketplace,API,Overlay,SegmentEditor,Transitions,DevicesDetection,Resolution,Contents,PagePerformance,CustomDimensions,TagManager” 这一长串字符串——它不是JSON也不是YAML，是纯ini格式，Docker环境里容易因换行/空格解析失败。

所以，这套源码包的价值，首先体现在部署路径的确定性上：你解压到/var/www/matomo/，chown www-data:www-data -R .，chmod 755 tmp/ config/，然后浏览器访问http://your-domain.com/install.php——整个过程没有中间层抽象，每一步操作都对应到具体文件权限、PHP扩展开关、MySQL用户授权粒度。这种“裸金属感”，恰恰是数据主权落地的前提。

提示：不要用root用户运行web服务。Matomo安装向导会检测web服务器用户（如www-data或nginx）对tmp/、config/、plugins/的写权限。如果权限不足，它不会报“Permission denied”，而是静默跳过插件激活步骤，导致后续A/B测试、热力图等功能缺失——这是新手踩坑最多的地方。

1.2 私有化 ≠ 免维护：数据生命周期管理才是核心

“所有数据掌握在自己服务器上”这句话背后，藏着一套完整的数据生命周期设计：

采集层：tracker.php接收GET请求，解析utm参数、设备UA、IP、页面URL，写入MySQL的log_visit、log_link_visit_action等表；
处理层：通过console命令（如./console core:archive –force-all-websites）触发归档任务，将原始日志聚合为daily/monthly报表数据，存入archive_*系列表；
存储层：所有表默认使用InnoDB引擎，支持事务与外键；关键表如log_visit有联合索引(log_visit.idsite, log_visit.visit_first_action_time)用于加速按站点+时间范围查询；
销毁层：GDPR合规的核心动作——不是“不收集”，而是“可撤回”。PrivacyManager插件提供两个关键开关：
anonymize_ip = 1：在插入log_visit前，将IPv4最后一位设为0（如192.168.1.100 → 192.168.1.0），IPv6截断后64位；
delete_logs_older_than = 26：自动清理26个月前的原始日志（注意：这是归档后的日志，不影响已生成的报表）。

这四个环节环环相扣。如果你只改了config.ini.php里的anonymize_ip=1，却没运行./console privacy:anonymize-data –date-last-n-days=30，那么过去30天的IP仍是明文——GDPR审计时这就是致命漏洞。

1.3 GDPR合规不是开关按钮，而是一套配置组合拳

很多用户以为勾选“启用隐私模式”就万事大吉。实际上，Matomo的GDPR合规由五个独立配置项协同生效：

配置项	位置	默认值	合规作用	实操建议
`consent_required`	[Privacy]	0	是否强制要求用户授权才能追踪	政务/金融类站点必须设为1，需前端调用_matomoTracker.requireConsent()
`anonymize_ip`	[Tracker]	0	记录前匿名化IP地址	建议始终开启，配合GeoIp2插件仍可识别国家/省份
`do_not_track`	[Tracker]	1	尊重浏览器DNT头	保持默认即可，现代浏览器已普遍发送DNT:1
`enable_logging_exception`	[Debug]	0	是否记录PHP错误到logs/	生产环境必须关闭，避免泄露路径信息
`enable_js_error_tracking`	[Tracker]	0	是否捕获前端JS错误	关闭，否则可能收集用户敏感上下文

特别注意：consent_required = 1开启后，tracker.php会返回HTTP 403并中断埋点，此时你需要在网站HTML中插入两段JS：

<!-- 在Matomo JS之前 --> <script> var _paq = window._paq || []; _paq.push(['requireConsent']); </script> <!-- Matomo JS代码（来自你的Matomo安装路径） --> <script src="https://your-domain.com/matomo/js/matomo.js"></script> <!-- 用户点击“同意”后调用 --> <script> function acceptConsent() { _paq.push(['rememberConsentGiven']); } </script>

这段逻辑不在安装向导里，也不在README.md中，但它决定了你的统计是否具备法律效力。我见过客户因漏掉_paq.push(['requireConsent'])，导致所有访客数据被判定为“未获授权采集”，整套系统被迫下线重装。

2. 安装向导深度解析与避坑指南

2.1 安装向导不是万能钥匙：它只做三件事

Matomo的install.php页面看似简单，但它实际只完成以下三项原子操作：

环境检测：检查PHP版本（≥5.6）、MySQL连接（PDO或mysqli扩展）、必要函数（json_encode、curl_init等）、目录写权限（tmp/、config/）；
数据库初始化：执行core/Updates/目录下SQL文件（如4.0.0-b1.sql），创建32张基础表（含log_visit、log_action、site等），并插入默认管理员账号；
配置生成：将你填写的数据库地址、用户名、密码、表前缀，拼接成config/config.ini.php中的[database]区块。

它不做以下事情：
- 不校验MySQL严格模式（STRICT_TRANS_TABLES）是否开启——若未开启，插入超长URL时会静默截断，导致来源页统计失真；
- 不检测PHP opcache是否启用——未启用时，每次请求都要重编译PHP文件，首页加载慢3倍以上；
- 不验证GeoIp2插件是否已下载——即使你勾选了“安装地理定位”，install.php也不会自动fetch MaxMind数据库，需手动执行./console geoip:update

因此，在点击“Next”之前，你必须手动完成三件事：

登录MySQL，执行：
sql SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'STRICT_TRANS_TABLES',''));
（生产环境建议在my.cnf中永久设置sql_mode = “NO_ENGINE_SUBSTITUTION”）
编辑php.ini，确认以下参数已启用：
ini opcache.enable=1 opcache.memory_consumption=256 opcache.max_accelerated_files=20000 date.timezone = "Asia/Shanghai"
进入Matomo根目录，执行：
bash php console core:update --yes php console geoip:update

注意：php console geoip:update会从MaxMind官网下载GeoLite2-Country.mmdb（约30MB），若服务器无法访问外网，需提前下载该文件，放入misc/geoip/目录，并确保文件权限为644。

2.2 数据库表前缀不是防攻击，而是多站点隔离刚需

安装向导里让你填“表前缀”，很多人习惯填matomo_。但如果你计划用同一套Matomo后台管理多个网站（比如企业官网、招聘站、博客），强烈建议按业务域划分前缀：

官网：web_
招聘站：job_
博客：blog_

为什么？因为Matomo的多站点数据隔离，不是靠数据库用户权限，而是靠表前缀+site.id区分。所有核心SQL查询都带WHERE条件：WHERE idsite = ?。但如果所有表都用matomo_前缀，当你要给招聘站单独开通只读账号时，就必须给matomo_log_visit、matomo_log_action等32张表逐一授权——而用job_前缀，只需授权job_%通配符即可。

更隐蔽的好处在于备份恢复：mysqldump -u root -p your_db job_* > job_backup.sql可精准分离招聘站数据，避免误删官网报表。

2.3 安装完成后必须立即做的五件事

安装向导显示“Congratulations!”只是起点。接下来五分钟内，你必须完成以下操作，否则系统处于半残废状态：

禁用默认管理员账号
登录后台 → Settings → Users → 找到“admin”用户 → 点击编辑 → 取消勾选“Super User” → 保存。
理由：Matomo不支持删除admin账号，但可降权。这是防止暴力破解的第一道防线。
创建专用数据库用户
不要用root连接Matomo。执行：
sql CREATE USER 'matomo_app'@'localhost' IDENTIFIED BY 'StrongPass123!'; GRANT SELECT, INSERT, UPDATE, DELETE ON your_db.web_* TO 'matomo_app'@'localhost'; FLUSH PRIVILEGES;
然后编辑config/config.ini.php，将[database]下的username/password改为matomo_app的新凭据。
启用HTTPS追踪
在Settings → Websites → 编辑你的网站 → 勾选“Force HTTPS for this website”。
否则，HTTP页面上的_tracker.js会因混合内容被浏览器拦截，导致数据丢失。
配置自动归档
Linux下添加crontab：
bash # 每天凌晨2点执行归档 0 2 * * * /usr/bin/php /var/www/matomo/console core:archive --url=https://your-domain.com/matomo/ >> /var/log/matomo-archive.log 2>&1
注意：–url参数必须是你对外访问的完整URL（含协议和路径），不能是localhost。
验证Tracker埋点
在网站HTML的前插入：
```html

```
然后打开浏览器开发者工具→Network标签，过滤matomo.php，刷新页面，应看到200响应且Request Payload包含idsite=1&rec=1。

3. 核心功能实操验证与参数调优

3.1 会话回放（Session Recording）为什么默认不工作？

HeatmapSessionRecording插件是Matomo最惊艳的功能之一，但它默认处于“半休眠”状态。原因有三：

前端JS未加载录制脚本
安装向导不会自动在tracker.js中注入录制逻辑。你必须手动修改网站埋点代码，在_paq.push([‘trackPageView’])之后添加：
javascript _paq.push(['enableJSErrorTracking']); _paq.push(['enableHeartBeatTimer', 15]); // 每15秒上报一次心跳 _paq.push(['enableLinkTracking']);
后端未开启录制开关
config/config.ini.php中需显式启用：
ini [SessionRecording] enable_session_recording = 1 session_recording_sample_rate = 100 ; 百分比采样，100=全量 session_recording_max_duration = 3600 ; 最长录制3600秒（1小时）
MySQL表空间不足
录制数据存在log_session_recordings表，单条记录平均20KB。若每天1000访客，每人录制5分钟，日增数据约10GB。必须提前规划：
``sql -- 查看当前表大小 SELECT table_name ASTable, ROUND(((data_length + index_length) / 1024 / 1024), 2)Size (MB)`
FROM information_schema.TABLES
WHERE table_schema = “your_db” AND table_name = “log_session_recordings”;

– 若超过50GB，建议分区
ALTER TABLE log_session_recordings PARTITION BY RANGE (idvisit) (
PARTITION p0 VALUES LESS THAN (1000000),
PARTITION p1 VALUES LESS THAN (2000000),
PARTITION pmax VALUES LESS THAN MAXVALUE
);
```

实测发现：当session_recording_sample_rate设为100且访客数>5000/日时，MySQL IOPS飙升，需将log_session_recordings表迁移到SSD磁盘，并在my.cnf中增加：

innodb_io_capacity = 2000 innodb_io_capacity_max = 4000

3.2 热力图（Heatmap）坐标错位的根源与修复

Heatmap插件默认使用CSS选择器定位元素，但现代前端框架（Vue/React）常动态生成class名（如_n9k3x），导致热力图点击区域漂移。解决方案分三层：

前端层：为关键按钮/链接添加稳定data属性

<!-- 不要这样 --> <button class="btn-primary">立即咨询</button> <!-- 要这样 --> <button class="btn-primary">$left = $action['x'] * $scale;

改为：

$left = round($action['x'] * $scale); // 强制取整，避免小数坐标渲染模糊

实操心得：热力图数据延迟约15分钟（因依赖归档任务）。若刚部署就看不到数据，先执行php console core:archive --force-all-websites手动触发一次。

3.3 漏斗转化分析（Goals）的三个致命陷阱

Goals插件能追踪用户从“进入首页→浏览产品页→填写表单→提交成功”的完整路径，但极易配置失误：

陷阱1：URL匹配模式选错
在Goals设置中，“Match type”有三种：
-Exact URL：必须完全一致（含?参数），适合静态页；
-Contains：子串匹配，但会误伤（如目标页/submit/匹配到/submit-success/）；
-Regex：最精准，但需转义特殊字符。

正确做法：对表单提交成功页，用Regex匹配^/submit\-success/\d+$（以/submit-success/开头，后跟数字ID）。

陷阱2：漏斗步骤顺序颠倒
Matomo要求漏斗步骤必须按用户行为顺序排列，且第一步必须是“进入网站”。若你把“填写表单”设为第一步，系统会认为所有访问该页的用户都是漏斗起点，导致转化率虚高。

陷阱3：未启用Goal Ecommerce
若要统计订单金额，必须在Goals设置中勾选“Enable Ecommerce tracking”，并在埋点JS中添加：

_paq.push(['addEcommerceItem', 'SKU123', // SKU 'iPhone 15', // 名称 '手机', // 分类 7999.00, // 单价 1 // 数量 ]); _paq.push(['trackEcommerceOrder', 'ORDER-2024-001', 7999.00]);

否则，Goals报表中只会显示“转化次数”，不显示“收入”。

3.4 用户画像标签（Custom Dimensions）与分群实战

CustomDimensions插件允许你为访客打标签，比如“新用户/老用户”、“企业客户/个人用户”、“高价值/低价值”。但标签维度不是越多越好，关键在可操作性：

维度1（访客级别）：is_enterprise = 1（根据邮箱域名判断，如@company.com）
维度2（会话级别）：traffic_source = "wechat"（从微信内置浏览器UA识别）
维度3（行动级别）：form_type = "contact"（表单提交时传参）

配置步骤：
1. Settings → Custom Dimensions → Add New Dimension → 选择“Visitor level”
2. 在埋点JS中添加：
javascript _paq.push(['setCustomDimension', 1, 'enterprise']); // 维度ID从1开始
3. 报表中即可在“Visitors > Overview”右侧筛选器中选择该维度。

注意：Custom Dimensions的值存储在log_visit.custom_dimension_1字段，该字段类型为VARCHAR(255)。若你传入JSON字符串（如{“type”:”vip”,”level”:5}），会因超长被截断。正确做法是拆分为多个维度，或用Hash编码（如md5(“vip:5”)）。

4. GDPR合规配置闭环与审计准备

4.1 数据主体权利响应流程（DSAR）实操

GDPR第15条赋予用户“访问权”，即用户可申请导出其在你网站上产生的所有行为数据。Matomo本身不提供一键导出界面，但可通过API+SQL组合实现：

用户提供邮箱地址（如user@example.com）
执行SQL查出该用户所有visit_id：
sql SELECT DISTINCT idvisit FROM log_visit WHERE config_browser_name LIKE '%Chrome%' AND location_country = 'CN' AND visit_last_action_time >= DATE_SUB(NOW(), INTERVAL 2 YEAR);
注：Matomo不存储邮箱，需结合你网站登录系统关联visit_id
调用API导出行为明细：
bash curl "https://your-domain.com/matomo/index.php?module=API&method=Live.getLastVisitsDetails&idSite=1&period=range&date=last30&format=JSON&token_auth=YOUR_TOKEN&filter_limit=10000"
将结果整理为CSV，包含字段：visit_id、page_url、action_time、event_category、event_action

整个过程应在30天内完成。建议将上述步骤写成Shell脚本，命名为dsar_export.sh，放入cron每日扫描新申请。

4.2 隐私政策（PRIVACY.md）与Matomo配置的映射关系

你压缩包里的PRIVACY.md不是摆设，它必须与config.ini.php配置一一对应。例如：

隐私政策条款	对应配置项	验证方式
“我们不会将您的数据出售给第三方”	`[Tracker] record_statistics = 1`（必须为1，表示仅本地记录）	检查config.ini.php中无record_statistics = 0
“您可随时撤回同意”	`[Privacy] consent_required = 1`+ 前端调用`_paq.push(['forgetConsentGiven'])`	在浏览器控制台执行该命令，再刷新页面，matomo.php应返回403
“我们使用Cookie进行会话管理”	`[General] use_cookies = 1`	若设为0，Heatmap Session Recording将失效

提示：PRIVACY.md中提到的“数据保留期限为26个月”，必须与config.ini.php中delete_logs_older_than = 26完全一致，否则构成虚假陈述。

4.3 审计日志（SECURITY.md）与安全加固清单

SECURITY.md列出Matomo的安全实践，但真正要落地，需完成以下加固：

禁用未使用插件
编辑config/config.ini.php，清空[Plugins]段落中不需要的插件：
ini plugins_enabled = "CoreHome,CoreAdminHome,CoreVisualizations,API,Widgetize,Transitions,Actions,Dashboard,MultiSites,Referrers,UserCountry,VisitsSummary,Goals,SEO,Events,UsersManager,PrivacyManager,CoreUpdater,CoreConsole,ScheduledReports,UserLanguage,Heartbeat,Intl,Marketplace,Overlay,SegmentEditor,Transitions,DevicesDetection,Resolution,Contents,PagePerformance,CustomDimensions"
移除MobileMessaging、Feedback、Login（若用LDAP统一认证）等
限制API访问IP
在Nginx配置中添加：
nginx location /matomo/index.php { allow 192.168.1.0/24; # 内网管理IP段 deny all; try_files $uri $uri/ /index.php?$args; }
加密备份数据库
使用gpg加密每日备份：
bash mysqldump -u matomo_app -p'Pass' your_db | gzip | gpg --encrypt --recipient "admin@your-domain.com" > /backup/matomo-$(date +%F).sql.gz.gpg
定期更新核心
每月执行：
bash php console core:update --yes php console plugin:update --all
监控异常登录
创建视图跟踪失败登录：
sql CREATE VIEW failed_login_attempts AS SELECT ip, COUNT(*) as attempts, MAX(date) as last_attempt FROM log_login_failures WHERE date >= DATE_SUB(NOW(), INTERVAL 1 HOUR) GROUP BY ip HAVING COUNT(*) > 5;

5. 插件生态与二次开发接口详解

5.1 超100个插件的筛选逻辑：什么该装，什么该删？

Matomo插件不是越多越好。我按客户类型总结出三类必装/慎装清单：

政务类站点（强合规需求）
✅ 必装：PrivacyManager、GeoIp2、CustomDimensions、ScheduledReports
❌ 禁用：MobileMessaging（短信通知）、Feedback（用户反馈弹窗）、TagManager（第三方标签管理，违反数据不出域原则）

电商类站点（重转化分析）
✅ 必装：Goals、Ecommerce、A/BTesting、FormAnalytics、PagePerformance
❌ 慎用：HeatmapSessionRecording（需评估存储成本）、CustomVariables（已被CustomDimensions替代）

技术博客（重内容传播）
✅ 必装：SEO、Referrers、SocialAnalytics、Annotations（文章批注）、UsersManager
❌ 禁用：TwoFactorAuth（管理员少，增加复杂度）、Provider（ISP识别，国内无意义）

实操心得：插件启用后，首次访问后台会触发数据库迁移。若中途断电，可能导致表结构损坏。务必在启用前执行php console core:backup-db。

5.2 API接口调用的五个黄金实践

Matomo提供RESTful API，但直接调用易踩坑。以下是经过生产验证的最佳实践：

实践1：永远用POST传递token_auth
不要把token写在URL里（?token_auth=xxx），会被Nginx日志、CDN缓存记录。正确方式：

curl -X POST "https://your-domain.com/matomo/index.php" \ --data "module=API" \ --data "method=VisitsSummary.get" \ --data "idSite=1" \ --data "period=day" \ --data "date=yesterday" \ --data "format=JSON" \ --data "token_auth=YOUR_TOKEN"

实践2：批量获取用segment参数
要查“iOS用户昨日访问量”，不用两次请求，而用segment：

--data "segment=visitorDeviceType==mobile;visitorOs==iOS"

实践3：大报表分页取数
当filter_limit=10000仍不够，用filter_offset分页：

# 第一页 --data "filter_limit=5000" --data "filter_offset=0" # 第二页 --data "filter_limit=5000" --data "filter_offset=5000"

实践4：缓存API响应
对不实时的报表（如月度汇总），加Cache-Control头：

header('Cache-Control: public, max-age=3600'); // 缓存1小时

实践5：错误处理必须解析error字段
API返回JSON中，即使HTTP状态码200，也可能含错误：

{ "result": "error", "message": "The requested period is not supported." }

务必检查result字段，而非只看HTTP状态。

5.3 白标定制（White Labeling）的三个层次

白标不是简单换Logo，而是贯穿前端、后端、邮件的全链路品牌渗透：

层次1：前端UI替换
- 替换themes/default/images/logo.svg为你的SVG Logo
- 修改themes/default/css/custom.css，覆盖.topbar-logo img样式
- 在config/config.ini.php中设置：
ini [General] custom_logo = "themes/default/images/my-logo.svg" custom_favicon = "themes/default/images/favicon.ico"

层次2：后端邮件模板
编辑plugins/UsersManager/templates/emailPasswordReset.twig，将Matomo字样替换为你的品牌名，并修改发件人邮箱为noreply@your-domain.com。

层次3：API响应去品牌化
在plugins/API/API.php中，搜索'Matomo'，将其替换为'Your Analytics'。注意：此操作需在每次core:update后重新patch。

提示：白标后，用户仍可在Settings → General Settings中看到“Powered by Matomo”小字。若要彻底移除，需编辑core/View.php，删除<div class="powered-by">区块——但这违反AGPLv3许可证，不建议。

6. 常见问题与排查技巧实录

6.1 安装向导卡在“正在连接数据库”？五步定位法

现象：install.php页面显示“Connecting to the database…”后无响应，超时退出。

排查步骤：

确认MySQL服务状态
bash systemctl status mysql # 若显示inactive，启动：systemctl start mysql
测试PHP能否连MySQL
创建test_db.php：
```php

```
浏览器访问test_db.php，若报错，则问题在PHP或MySQL配置。

检查MySQL绑定地址
编辑/etc/mysql/mysql.conf.d/mysqld.cnf，确认：
ini bind-address = 127.0.0.1 # 若为0.0.0.0，需加防火墙规则：ufw allow from 127.0.0.1 to any port 3306
验证数据库用户权限
sql SELECT host, user FROM mysql.user WHERE user = 'root'; -- 若host为'localhost'，则PHP用127.0.0.1连接会失败，需创建'127.0.0.1'用户 CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY 'password'; GRANT ALL PRIVILEGES ON *.* TO 'root'@'127.0.0.1'; FLUSH PRIVILEGES;
检查SELinux（CentOS/RHEL）
bash getenforce # 若为Enforcing，临时关闭：setenforce 0 # 永久关闭：sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

6.2 实时访客数为0？九成是HTTPS混合内容

现象：后台显示“Real-time visitors: 0”，但Network中matomo.php返回200。

根本原因：网站用HTTPS，但埋点JS地址写成HTTP，被浏览器拦截。

验证方法：
浏览器开发者工具 → Console标签，查找：

Mixed Content: The page at 'https://your-domain.com/' was loaded over HTTPS, but requested an insecure script 'http://your-domain.com/matomo/js/matomo.js'. This request has been blocked.

修复方案：
- 将埋点代码中http://your-domain.com/matomo/js/matomo.js改为https://your-domain.com/matomo/js/matomo.js
- 或更稳妥：用协议相对URL//your-domain.com/matomo/js/matomo.js
- 或终极方案：在Nginx中强制跳转：
nginx if ($scheme = http) { return 301 https://$server_name$request_uri; }

6.3 热力图显示“无数据”，但会话回放正常？检查CSS选择器

现象：Heatmap仪表盘显示“0 sessions recorded”，但Session Recording能播放录像。

原因：Heatmap默认只追踪<a>、<button>、<input>、<select>四类元素。若你的CTA按钮是<div onclick="...">，则不会被捕捉。

解决步骤：
1. 在Heatmap设置中，将“CSS selector for heatmap tracking”改为a, button, input, select, [data-heatmap]
2. 为div按钮添加data属性：<div>[database] pdo_options = {"12": "1", "3": "2"}

其中12是PDO::ATTR_PERSISTENT，3是PDO::ATTR_ERRMODE，强制使用持久连接并抛出异常。这个细节，官方文档提都没提，但却是高并发场景的生死线。

Matomo的价值，从来不在功能列表有多炫，而在于它把每一个数据流转环节都暴露给你——从IP如何被匿名化，到热力图坐标如何映射到DOM，再到GDPR删除指令如何翻译成DELETE SQL。你拿到的不是黑盒SaaS，而是一套可审计、可追溯、可定制的数据主权操作系统。只要守住权限、配对配置、盯紧日志，它就能稳稳跑在你自己的服务器上，十年不换。

本文还有配套的精品资源，点击获取