包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载Matomo 是一款实时 Web 分析web analytics应用在 NixOS 中通过services.matomo模块以声明式方式部署模块自动配置 php-fpm 作为后端并可选地生成一套针对 Matomo 加固过的 nginx 虚拟主机。本文以 matomo.md 文档为主体结合 matomo.nix 模块源码、集成测试 与 Matomo 打包定义完整讲解从数据库准备、浏览器初始化、每小时自动归档到备份与迁移的实战流程。读完本文你将掌握如何在 NixOS 上从零部署一套生产可用的 Matomo 实例并能理解每个配置选项背后的 systemd 单元与 php-fpm 池实现。模块概览php-fpm nginx 的声明式组合该模块的核心设计思路是Matomo 本体以只读方式安装在 Nix store 中模块负责在/var/lib/matomo下生成可变数据目录并通过 php-fpm 池phpfpm-matomo为 PHP 代码提供 FastCGI 执行通道。模块文档matomo.md明确指出Matomo 不支持自动化安装流程即无法像其他应用那样由模块替你完成初始化因此首次配置必须在浏览器中的 Matomo 安装向导中手动完成模块只负责把服务端基础设施PHP 运行时、Web 服务器、数据库权限、数据目录全部就绪。从模块源码matomo.nix看启用后模块会同时创建系统用户matomo主目录为/var/lib/matomo源码users.users.${user}处oneshot 服务matomo-setup-update.service负责数据目录初始化、包升级时的数据库core:updateoneshot 服务matomo-archive-processing.service与每小时定时器用于报表归档php-fpm 池phpfpm-matomo可选 nginx 虚拟主机services.matomo.hostname。最小可用配置启用模块与数据库在configuration.nix中启用模块并同时启用 MariaDB或 MySQL与 nginx{ config, pkgs, ... }: { services.matomo { enable true; # nginx 与 webServerUser 二者必须设置其一详见下文选项说明 nginx { }; }; services.mysql { enable true; package pkgs.mariadb; }; services.nginx.enable true; }这正是 nixos/tests/matomo.nix 中集成测试所用的基础配置形态。测试脚本会依次等待mysql.service、phpfpm-matomo.service、nginx.service就绪然后验证matomo.js、js/piwik.js、matomo.php跟踪 API均可通过 HTTP 访问并检查首页出现Matomo Installation安装向导标题。模块源码中的断言assertions强制要求services.matomo.nginx与services.matomo.webServerUser至少设置一个否则求值会直接报错。若同时设置两者模块会给出警告nginx已设置时webServerUser会被忽略应将其移除。配置选项详解以下选项全部定义于 matomo.nix 的options.services.matomo部分。enable类型bool默认false。开启 Matomo 的 php-fpm 后端。如前述必须配合nginx或webServerUser之一使用。package类型包默认pkgs.matomo。指定 Matomo 版本。当前仓库中打包版本为5.13.0见 pkgs/by-name/ma/matomo/package.nix。该包从builds.matomo.org拉取官方 tar 包将全部文件装入share/目录作为 Web 根并生成matomo-console包装命令内部执行share/console。nginx类型nullOr (submodule)默认null。设置后模块会创建以services.matomo.hostname为 server_name 的 nginx 虚拟主机且内置对 Matomo 合理的默认值。置为{}即可在不做任何定制的情况下启用虚拟主机。关键默认行为源码中通过recursiveUpdate覆盖 vhost-options.nix 的默认值forceSSL true强制 HTTP 301 跳转 HTTPSenableACME true自动通过 Lets Encrypt ACME 签发证书。模块注释给出的理由是登录凭据与 Matomo 数据属于敏感信息不应明文传输。可定制项示例源码example字段services.matomo.nginx { serverAliases [ matomo.${config.networking.domain} stats.${config.networking.domain} ]; enableACME false; # 例如已有证书时关闭 ACME };完整可定制项还包括listen、addSSL、onlySSL、sslCertificate、http2、basicAuth、locations等均可参考 vhost-options.nix 中的定义。hostname类型str默认matomo.${config.networking.fqdnOrHostName}。Matomo 对外访问的 URL 主机名不含 https 前缀。默认值形如matomo.你的主机名若部署在matomo.yourdomain.org这类独立域名下应显式设置services.matomo.hostname matomo.yourdomain.org;该值同时用于 nginx 虚拟主机名、ACME 证书申请域名以及归档服务执行matomo-console core:archive --urlhttps://${cfg.hostname}时的目标 URL。它还是旧选项services.matomo.periodicArchiveProcessingUrl的迁移目标见下文「迁移与兼容」。webServerUser类型nullOr str默认null示例lighttpd。不使用 nginx 时例如改用 lighttpd、Apache、Caddy 等必须将此项设为该 Web 服务器运行用户的用户名模块据此设置 FastCGI socket 的属主listen.owner使 Web 服务器进程有权限连接services.phpfpm.pools.name.socket。该场景下需自行将index.php、matomo.php以及旧名piwik.php的请求转发给该 socket详见下文「使用 nginx 之外的 Web 服务器」。periodicArchiveProcessing类型bool默认true。启用每小时自动归档。关闭后仍可手动通过systemctl start matomo-archive-processing.service触发。数据库准备无密码 UNIX_SOCKET 认证Matomo 需要独立的数据库与用户。模块不会自动创建数据库文档matomo.md要求你自行配置 MariaDB/MySQL 数据库与用户随后在浏览器安装向导中填写凭据。推荐的方案是利用unix_socket 认证插件实现无密码认证仅允许系统用户matomo以数据库用户matomo的身份登录且无需密码其他用户一律拒绝。MariaDB 下执行INSTALL PLUGIN unix_socket SONAME auth_socket; CREATE DATABASE matomo; CREATE USER matomolocalhost IDENTIFIED WITH unix_socket; GRANT ALL PRIVILEGES ON matomo.* TO matomolocalhost;MySQL 下执行INSTALL PLUGIN auth_socket SONAME auth_socket.so; CREATE DATABASE matomo; CREATE USER matomolocalhost IDENTIFIED WITH auth_socket; GRANT ALL PRIVILEGES ON matomo.* TO matomolocalhost;随后在浏览器安装向导中数据库用户填matomo、数据库名填matomo、密码留空。采用 socket 认证的前提是数据库主机为本地localhost。值得注意的细节打包定义中专门携带了一个补丁 make-localhost-default-database-host.patch把安装向导中“数据库服务器”字段的默认值从127.0.0.1改为localhost——因为 unix socket 认证只对localhost生效而基于密码的认证对两者都适用。这印证了文档中的提示若数据库不在同一台主机则应改用基于密码的认证。浏览器初始化与matomo-setup-update服务模块文档强调“自动安装不被 Matomo 支持”首次部署时需要访问https://matomo.你的域名/按向导填写数据库凭据、管理员账号生成并放置 JavaScript 跟踪代码。在幕后模块的 oneshot 服务matomo-setup-update.service源码 matomo.nix 中systemd.services.matomo-setup-update负责以StateDirectory创建/var/lib/matomo及其misc子目录目录模式2770setgid 组读写允许通过matomo组进行管理与备份preStart若检测到旧版遗留目录/var/lib/piwik自动迁移至/var/lib/matomo修正属主与权限ugrwX,o-rwx在包升级时清理tmp/以避免升级问题维护current-package符号链接指向当前包主体脚本将包内share/config模板复制到数据目录若检测到config.ini.php中已含[database]段即安装已完成则自动执行matomo-console core:update --yes完成数据库升级。该服务通过requiredBy/before挂接在phpfpm-matomo.service之前且requires/after数据库服务确保任何 PHP 请求执行前数据目录与数据库均已就绪。升级包时php-fpm 通过restartTriggers [ cfg.package ]在包变更时重启见源码中systemd.services.${phpExecutionUnit}部分。归档处理每小时定时器与浏览器触发Matomo 的报表需要定期从原始访问记录聚合生成。模块自带两个单元matomo-archive-processing.serviceoneshot以matomo用户运行matomo-console core:archive --urlhttps://${cfg.hostname}其 CPU 调度策略为CPUSchedulingPolicyidle、IO 调度为IOSchedulingClassidle源码serviceConfig即仅在系统空闲时占用资源避免影响业务matomo-archive-processing.timerOnCalendar hourly、Persistent yes、AccuracySec 10m即每小时触发一次归档若机器当时休眠/关机则在下次启动后补跑。启用自动归档后文档建议在 Matomo 后台Administration System General Settings中关闭“浏览器触发归档”disable browser triggers for Matomo archiving并可将报表更新周期限制为每小时一次让归档完全交给 systemd 定时器驱动。对于删除旧访客日志Administration System Privacy中的隐私清理功能文档特别强调如果你已经积累了历史数据务必先手动执行一次systemctl start matomo-archive-processing.service并确认无错误退出确保报表已归档后再删除源日志否则原始访问数据将永久丢失。该功能开关对应模块选项periodicArchiveProcessing默认true关闭后定时器不再创建归档仅可手动触发。备份与恢复文档给出的备份策略非常精简且明确——只需备份两样东西MySQL 数据库可用mysqldump等常规工具导出/var/lib/matomo/config/config.ini.php配置文件。由于config.ini.php可能包含 MySQL 密码等敏感信息模块为其设置了严格权限数据目录统一o-rwxphp-fpm 服务UMask 0007。读取该文件需要使用matomo组的用户或 root 权限。恢复场景下matomo-setup-update.service的preStart会重新修正/var/lib/matomo的属主与权限chown -R matomo:matomo、chmod -R ugrwX,o-rwx因此从备份还原后无需手工调整权限——模块的初始化逻辑会自动兜底这也是文档未展开、但从源码可以确认的实现细节。已知问题JavaScript 跟踪器“不可写”警告Matomo 安装完成后后台可能提示 JavaScript trackermatomo.js不可写。文档明确指出这是预期行为可以放心忽略——因为 Matomo 本体安装在只读的 Nix store 中。除非你确实需要依赖“可写 tracker”的插件这类插件要求动态修改matomo.js否则无需处理。从打包定义package.nix可以看到配套设计Matomo 的运行时可变状态通过PIWIK_USER_PATH环境变量重定向到/var/lib/matomo包内bootstrap.php被替换为支持从环境变量读取该路径的版本从而让只读安装与可变数据目录共存GeoIP2 路径默认配置也被补丁修正change-path-geoip2-5.x.patch避免指向 Nix store 内的只读路径。使用 nginx 之外的 Web 服务器文档与源码均支持替换 Web 服务器。核心要点将指向index.phpWeb 界面与piwik.php跟踪端点旧名新版亦为matomo.php的请求通过 FastCGI 转发到模块生成的 unix socketservices.phpfpm.pools.matomo.socket。模块源码在services.nginx.virtualHosts中提供了完整的参考 nginx 配置可直接作为其他服务器的对照模板关键规则包括/与 /index.php解析到 index.php 并 fastcgi_pass 到 socket /matomo.php、 /piwik.php跟踪端点fastcgi_pass 到 socket~* ^.\.php$除上述入口外任何 PHP 文件一律返回 403~ ^/(?:core|lang|misc)/禁止访问内部目录~* \.(?:bat|git|ini|sh|txt|tpl|xml|md)$禁止下载辅助文件 /robots.txt直接返回User-agent: *\nDisallow: /\n阻止爬虫 /matomo.js、 /piwik.jsexpires 1M让浏览器缓存跟踪脚本一个月。使用其他 Web 服务器时除 FastCGI 转发外还应参照这套规则复刻等价的安全约束限制 PHP 执行面、封锁敏感目录与文件。同时不要忘记将services.matomo.webServerUser设置为该服务器的运行用户模块据此设置 socket 属主为listen.ownerlisten.mode 0660保证 socket 可被 Web 服务器进程访问。迁移与兼容从 piwik 到 matomo模块通过imports机制维护了完整的兼容迁移路径源码开头services.piwik.enable→services.matomo.enableservices.piwik.webServerUser→services.matomo.webServerUserservices.piwik.nginx→services.matomo.nginxservices.matomo.periodicArchiveProcessingUrl→services.matomo.hostname已移除的phpfpmProcessManagerConfig新旧名称均被移除替代方案是直接使用services.phpfpm.pools.name.settings此外preStart中的目录迁移逻辑会在检测到旧数据目录/var/lib/piwik存在时自动mv到/var/lib/matomo数据迁移基本透明。在包层面旧版本别名matomo_5也已于 2025 年 10 月转为抛错见 pkgs/top-level/aliases.nix统一使用matomo属性名。生产部署核对清单综合文档与源码上线前请逐项确认services.matomo.nginx或services.matomo.webServerUser已设置二者必居其一services.matomo.hostname已按实际域名显式设置不要依赖默认值MariaDB/MySQL 已建库建号本地部署优先使用 unix_socket 无密码认证远程数据库则使用密码认证浏览器完成安装向导后在后台关闭“浏览器触发归档”交给matomo-archive-processing.timer若启用日志删除先手动运行systemctl start matomo-archive-processing.service确认归档成功备份方案覆盖数据库与/var/lib/matomo/config/config.ini.php若更换 Web 服务器已按模块参考配置转发index.php/matomo.php/piwik.php并复刻安全规则。结语NixOS 的services.matomo模块把 Matomo 部署中容易出错的环节——PHP 运行时、FastCGI socket 权限、nginx 加固、定时归档、升级时的数据库迁移——全部声明式地固化下来同时保留了浏览器安装向导与手动数据库准备的灵活性。理解本文涉及的 模块源码、集成测试 与 包定义你就能在 NixOS 上稳定运维一套自托管、无外部依赖的 Web 分析系统并随时依据文档 matomo.md 核对官方推荐做法。赞分享包管理器操作系统【免费下载链接】nixpkgsNix Packages collection NixOS项目地址https://gitcode.com/GitHub_Trending/ni/nixpkgs点击查看免费下载相关推荐Nginx虚拟主机流量状态模块nginx-module-vts安装与配置指南Nginx虚拟主机流量状态模块nginx module vts安装与配置指南 1. 项目基础介绍和主要的编程语言 项目基础介绍 Nginx虚拟主机流量状态模后端可观测性指标监控Laradock Nginx 服务完全指南站点配置、SSL、上传限制与 PHP-FPM 联调Laradock Nginx 服务完全指南站点配置、SSL、上传限制与 PHP FPM 联调 Laradock 内置的 Nginx 容器是整套开发环境默认的后端开发工具DevOpsPHP 生产环境部署指南虚拟/独立服务器上的 nginxPHP-FPM 与 Apache 方案PHP 生产环境部署指南虚拟/独立服务器上的 nginxPHP FPM 与 Apache 方案 本指南源自 php the right way https:文档教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考