使用 phpEnv 本地集成环境部署 Umami 隐私统计系统并配置 PHP 自定义上报接口
一、为什么选择 Umami 作为网站统计工具
1.1 Umami 的核心优势
在网站运营过程中，数据统计是不可或缺的一环。传统的统计工具如 Google Analytics 功能强大，但存在两个明显问题：一是会收集大量用户个人信息，包括完整的 IP 地址、设备指纹等，在很多国家和地区面临合规风险；二是这些工具通常依赖第三方 Cookie，容易被浏览器或广告拦截插件屏蔽，导致统计数据失真。
Umami 是一款开源的轻量级网站统计工具，它的设计理念是"只统计必要的数据"。默认情况下，Umami 不会存储用户的完整 IP 地址，不会使用 Cookie 跟踪用户行为，也不会将数据传输给任何第三方服务器。所有数据都保存在你自己的数据库中，你完全掌控数据的去向。对于个人博客、企业官网、内部系统这类对隐私有要求的站点来说，Umami 是一个非常理想的选择。
1.2 Umami 的功能概览
尽管体量轻巧，Umami 提供的统计维度却相当实用。它能统计网站的页面浏览量（PV）、独立访客数（UV）、平均停留时长、跳出率等核心指标。在访客来源方面，可以查看直接访问、搜索引擎、外部链接等不同渠道的流量占比。在设备分析方面，能识别访客使用的浏览器类型、操作系统、屏幕尺寸等信息。此外，Umami 还支持自定义事件追踪，你可以统计按钮点击、表单提交、视频播放等特定交互行为。
Umami 的管理后台采用响应式设计，在手机上也能方便地查看数据。同时它提供了数据导出功能，支持将统计数据导出为 CSV 格式，方便进一步分析或归档。
二、phpEnv 集成环境简介与前期准备
2.1 phpEnv 是什么
phpEnv 是一款面向 Windows 平台的 PHP 集成开发环境，它将 PHP、MySQL、Nginx、Apache、Redis、Memcached 等常用服务打包在一起，通过图形化界面统一管理。对于不想花时间手动配置各种服务依赖的开发者来说，phpEnv 可以大幅降低环境搭建的门槛。它支持多版本 PHP 快速切换，内置 phpMyAdmin 数据库管理工具，还提供了站点管理、SSL 证书配置、端口监控等实用功能。
使用 phpEnv 部署 Umami 的好处在于，你不需要单独安装和配置 Node.js 运行环境之外的其他组件——数据库和 Web 服务器都已经就绪，只需要确认服务状态即可。
2.2 环境检查与版本要求
在开始部署之前，请确保 phpEnv 已经正确安装并启动。打开 phpEnv 主界面，确认以下服务的状态指示灯为绿色（运行中）：
- PHP 服务：Umami 的后端基于 Node.js 运行，但我们会通过 PHP 编写自定义统计接口与之对接，因此 PHP 版本建议选择 7.4 及以上。PHP 8.0 或 8.1 也是不错的选择，性能更好。
- MySQL 服务：Umami 使用关系型数据库存储统计数据，MySQL 5.7 及以上版本均可。phpEnv 默认安装的是 MySQL 5.7 或 8.0，完全满足需求。
- Nginx 服务：我们将使用 Nginx 作为反向代理服务器，把外部请求转发到 Umami 的 Node.js 服务端口上。
除了 phpEnv 中的服务外，还需要在系统中安装 Node.js 运行环境。Umami 要求 Node.js 版本在 14.0 以上，建议使用 Node.js 16.x 或 18.x LTS 版本。你可以在命令行中输入node -v来检查当前版本。如果没有安装，前往 Node.js 官网下载安装包即可。
三、Umami 安装与数据库配置
3.1 获取 Umami 源码
Umami 的源码托管在 GitHub 上。你可以通过以下两种方式获取代码：
第一种方式是使用 Git 直接克隆仓库。打开命令行工具，切换到 phpEnv 的网站根目录（默认路径为D:\phpEnv\www），执行：
git clone https://github.com/umami-software/umami.git
cd umami第二种方式是访问 Umami 的 GitHub 发布页面，下载最新版本的源码压缩包，解压后放到D:\phpEnv\www\umami目录中。
无论使用哪种方式，最终确保 Umami 的所有文件都在D:\phpEnv\www\umami这个路径下，后续的操作都将基于这个目录进行。
3.2 创建数据库
接下来需要在 MySQL 中为 Umami 创建一个专用的数据库。打开 phpEnv 主界面，点击 phpMyAdmin 按钮进入数据库管理页面。默认的用户名是root，密码是 phpEnv 安装时设置的 MySQL 密码（默认通常为空或者root，具体取决于你的安装配置）。
登录后，点击顶部导航的"新建"按钮，创建一个名为umami_db的数据库。字符集选择utf8mb4，排序规则选择utf8mb4_unicode_ci。utf8mb4 字符集能够完整支持包括 emoji 在内的所有 Unicode 字符，避免某些特殊字符在存储时出现乱码。
3.3 配置环境变量文件
Umami 使用.env文件来管理配置参数。在 Umami 根目录下，找到.env.example文件，将其复制一份并重命名为.env。然后用文本编辑器打开.env文件，修改以下关键配置项：
# 数据库配置
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=你的MySQL密码
DB_NAME=umami_db
# 应用配置
APP_SECRET=生成一个随机的长字符串作为加密密钥其中APP_SECRET是一个非常重要的安全参数，用于加密会话数据和生成签名。你可以使用在线随机字符串生成工具生成一个 32 位以上的随机字符串，或者直接在命令行中执行openshell -Command "[System.Web.Security.Membership]::GeneratePassword(32, 8)"来生成。
3.4 安装依赖与初始化数据表
打开命令行工具，切换到 Umami 的源码目录：
cd D:\phpEnv\www\umami首先安装项目依赖：
npm install这个过程可能需要几分钟时间，取决于你的网络速度。安装完成后，执行数据库迁移命令来创建 Umami 运行所需的数据表：
npm run migrate如果一切顺利，你会看到类似"Migration completed"的提示信息，说明数据表已经成功创建。此时可以打开 phpMyAdmin 查看umami_db数据库，应该能看到多张以umami_为前缀的数据表。
3.5 启动 Umami 服务
在 Umami 源码目录下执行以下命令启动服务：
npm run dev开发模式下，Umami 会同时启动前端和后端服务，默认监听 3000 端口。启动完成后，打开浏览器访问http://127.0.0.1:3000，你应该能看到 Umami 的登录页面。
默认的管理员账号信息如下：
- 用户名：
admin - 密码：
umami
重要提示：首次登录后，请立即在"设置 → 用户"中修改默认密码，避免安全风险。
四、配置 Nginx 反向代理
4.1 为什么需要反向代理
目前 Umami 运行在 3000 端口上，访问时需要显式指定端口号。在实际使用中，这种方式不够优雅，也不便于后期做 HTTPS 升级。通过 Nginx 反向代理，我们可以将外部对 8080 端口（或其他你喜欢的端口）的请求转发到内部的 3000 端口，用户访问时无需关心后端实际运行在哪个端口。
此外，反向代理还能带来额外好处：可以统一配置访问日志、设置请求超时时间、启用 Gzip 压缩提升加载速度，以及后续方便地配置 SSL 证书实现 HTTPS 访问。
4.2 Nginx 配置详解
在 phpEnv 中，Nginx 的站点配置文件通常位于D:\phpEnv\nginx\conf\vhost目录下。你可以新建一个umami.conf文件，写入以下配置：
server {
listen 8080;
server_name 127.0.0.1 www.pcppp.com;
location / {
proxy_pass http://127.0.0.1:3000;
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;
proxy_connect_timeout 60s;
proxy_read_timeout 60s;
}
}下面逐条解释这些配置的作用：
listen 8080：指定 Nginx 监听 8080 端口的入站请求。server_name：定义匹配的域名。这里同时配置了127.0.0.1和www.pcppp.com，如果你在 hosts 文件中将www.pcppp.com指向了127.0.0.1，就可以通过这个域名访问 Umami。proxy_pass：这是反向代理的核心指令，将所有请求转发到http://127.0.0.1:3000。proxy_set_header：这几行的作用是将客户端的真实信息传递给后端服务。比如X-Real-IP会传递访客的真实 IP 地址，X-Forwarded-Proto会告知后端当前使用的是 HTTP 还是 HTTPS 协议。
配置完成后，在 phpEnv 中重启 Nginx 服务。然后在浏览器中访问http://127.0.0.1:8080或http://www.pcppp.com:8080，应该能正常打开 Umami 的管理页面。
五、通过 PHP 编写自定义统计接口
5.1 为什么需要自定义 PHP 统计接口
Umami 本身提供了一个 JavaScript 跟踪脚本，只需要在网页中引入一段代码就能自动收集数据。但在某些特殊场景下，这种方式可能不够灵活。比如你运营的是一个纯 API 接口服务，没有前端页面可以嵌入 JS 脚本；或者你需要统计 PHP 后端处理的某些业务逻辑（如接口调用次数、定时任务执行情况）；又或者你希望对上报的数据做额外的加工处理后再发送给 Umami。
在这些情况下，通过 PHP 编写自定义统计接口就是一个很好的解决方案。PHP 作为服务端语言，可以在任何业务逻辑中调用统计上报代码，不受前端环境限制。
5.2 获取 Umami 的 API 凭证
在使用 PHP 对接 Umami 之前，需要先获取两个关键信息：Website ID 和 API Token。
登录 Umami 管理后台，在左侧导航点击"设置 → 网站"，点击"添加网站"按钮。填写以下信息：
- 名称：给你的网站起一个容易识别的名字，比如"我的PHP项目"
- 域名：填写
www.pcppp.com（或你实际使用的域名） - 时区：选择你所在的时区
创建完成后，点击该网站条目右侧的"编辑"按钮，在弹出的页面中可以看到一个 UUID 格式的 ID，这就是Website ID，请复制保存。
接下来获取 API Token。在左侧导航点击"设置 → 用户"，选择当前管理员用户，找到"API 密钥"部分，点击"生成密钥"按钮。生成的 Token 是一串长字符串，同样请复制保存。
5.3 PHP 统计上报代码实现
下面是一个完整的 PHP 统计上报示例，你可以将其保存为umami_tracker.php，然后在需要统计的页面中通过require_once引入：
<?php
/**
* Umami PHP 自定义统计上报类
*/
class UmamiTracker {
private $apiUrl;
private $websiteId;
private $token;
public function __construct($apiUrl, $websiteId, $token) {
$this->apiUrl = $apiUrl;
$this->websiteId = $websiteId;
$this->token = $token;
}
/**
* 上报页面浏览事件
*/
public function trackPageview($customUrl = null) {
$data = [
'type' => 'pageview',
'website' => $this->websiteId,
'url' => $customUrl ?? $_SERVER['REQUEST_URI'],
'referrer' => $_SERVER['HTTP_REFERER'] ?? '',
'userAgent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
'ip' => $_SERVER['REMOTE_ADDR']
];
return $this->sendRequest($data);
}
/**
* 上报自定义事件
*/
public function trackEvent($eventName, $eventData = []) {
$data = [
'type' => 'event',
'website' => $this->websiteId,
'url' => $_SERVER['REQUEST_URI'],
'event_name' => $eventName,
'event_data' => $eventData,
'userAgent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
'ip' => $_SERVER['REMOTE_ADDR']
];
return $this->sendRequest($data);
}
/**
* 发送 HTTP POST 请求到 Umami API
*/
private function sendRequest($data) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->apiUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $this->token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 5); // 设置5秒超时，避免影响主业务
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
// 记录日志（可选）
if ($httpCode !== 200) {
error_log("Umami上报失败: HTTP {$httpCode}, 错误: {$error}, 响应: {$response}");
}
return $httpCode === 200;
}
}
// 使用示例
$tracker = new UmamiTracker(
'http://127.0.0.1:3000/api/collect',
'你的Website ID',
'你的API Token'
);
// 上报页面浏览
$tracker->trackPageview();
// 如果需要上报自定义事件（比如用户点击了某个按钮）
// $tracker->trackEvent('button_click', ['button_id' => 'submit_form']);
?>5.4 代码关键点说明
这段代码封装了一个UmamiTracker类，提供了两个主要方法：trackPageview()用于上报页面浏览数据，trackEvent()用于上报自定义事件。在实际使用时，你可以根据业务需求灵活调用。
需要注意的是，统计上报请求不应该阻塞主业务流程。代码中设置了 5 秒的超时时间（CURLOPT_TIMEOUT），即使 Umami 服务暂时不可用，也不会影响你的 PHP 页面正常响应。另外，上报失败时通过error_log()记录日志而不是直接输出错误，避免将内部信息暴露给用户。
如果你需要在多个 PHP 项目中复用这个统计类，可以将其封装为一个 Composer 包，或者直接放到项目的公共库中统一引用。
六、隐私保护相关配置
6.1 Umami 的默认隐私策略
Umami 在设计之初就将隐私保护作为核心理念。默认情况下，它不会使用 Cookie 来标识用户，而是通过哈希算法将 IP 地址、User-Agent 等信息组合生成一个匿名标识符，并且该标识符每天都会自动重置。这意味着 Umami 可以统计独立访客数，但无法长期跟踪单个用户的行为轨迹。
同时，Umami 不会收集用户的姓名、邮箱、电话号码等个人身份信息。所有统计数据都是聚合后的匿名数据，无法直接关联到具体的个人。这种机制使得 Umami 在大多数情况下天然符合 GDPR（欧盟通用数据保护条例）、CCPA（加州消费者隐私法案）等隐私法规的要求。
6.2 进一步增强隐私保护的配置项
如果你对隐私保护有更严格的要求，可以通过修改.env文件中的配置项来进一步增强：
# 完全禁止收集IP相关信息
DISABLE_IP_TRACKING=true
# 完全关闭Cookie（默认已经是关闭状态，此配置确保万无一失）
DISABLE_COOKIE=true
# 设置数据保留天数，超过此天数的数据将自动清理
DATA_RETENTION_DAYS=30将DISABLE_IP_TRACKING设为true后，Umami 在接收上报数据时会直接丢弃 IP 地址字段，连匿名化处理都不做，从源头上杜绝了 IP 信息泄露的可能。
DATA_RETENTION_DAYS这个配置也非常实用。设置为 30 意味着系统会自动清理 30 天前的统计数据。对于只需要查看近期趋势的站点来说，这既能节省数据库空间，又能进一步降低数据泄露的风险——因为旧数据根本不存在了。
修改.env文件后，需要重启 Umami 服务使配置生效。
七、常见问题排查
7.1 数据库连接失败
如果启动 Umami 时提示数据库连接错误，首先检查.env文件中的数据库配置是否正确。常见问题包括：密码中包含特殊字符（如@、#等），需要在.env文件中用引号包裹；DB_HOST 填写为localhost但 MySQL 只监听127.0.0.1，可以尝试将 localhost 改为127.0.0.1。
另外，确认 phpEnv 中的 MySQL 服务确实处于运行状态。可以在命令行中执行mysql -u root -p尝试登录，如果登录失败，说明 MySQL 服务有问题，需要在 phpEnv 中检查 MySQL 的日志输出。
7.2 npm run dev 启动报错
如果执行npm run dev时出现错误，首先确认 Node.js 版本是否符合要求。执行node -v查看版本号，低于 14.0 需要升级。其次检查npm install是否完整执行，可以删除node_modules目录后重新执行npm install。如果某个依赖包下载失败，可以尝试切换 npm 镜像源：npm config set registry https://registry.npmmirror.com。
7.3 Nginx 反向代理无法访问
如果访问http://127.0.0.1:8080提示无法连接，首先检查 Nginx 是否成功重启。在 phpEnv 中查看 Nginx 状态，如果启动失败，可以查看D:\phpEnv\nginx\logs\error.log中的错误日志。常见原因是配置文件语法错误，比如缺少分号、括号不匹配等。
另外确认 8080 端口是否被其他程序占用。可以在命令行中执行netstat -ano | findstr 8080查看端口占用情况。如果被占用，可以修改 Nginx 配置中的listen端口为其他未被占用的端口。
7.4 PHP 上报接口返回错误
如果 PHP 统计代码执行后数据没有出现在 Umami 面板中，首先检查 PHP 的 cURL 扩展是否已启用。在 phpEnv 中点击 PHP 设置 → php.ini，确认extension=curl前面没有分号注释。其次检查 API Token 是否正确，注意 Token 字符串不要有多余的空格。最后确认 Umami 服务正在运行，且api/collect接口地址正确。
可以在 PHP 代码中临时添加var_dump($response)来查看 Umami API 的原始返回内容，通常会包含具体的错误信息，比如"Invalid token"或"Website not found"，根据提示逐一排查即可。
八、总结
通过 phpEnv 集成环境部署 Umami，整个流程可以分为环境准备、源码部署、数据库配置、反向代理设置和自定义统计对接五个主要步骤。phpEnv 帮我们解决了 Web 服务器和数据库的基础配置问题，让我们可以专注于 Umami 本身的部署和定制。
Umami 的隐私友好特性使其在当前越来越重视数据合规的环境下具有明显优势。配合 PHP 自定义统计接口，你可以将统计能力延伸到任何业务逻辑中，无论是传统的网页浏览统计，还是 API 调用监控、后端任务追踪，都能灵活实现。
对于想要快速搭建一个合规、轻量、可控的网站统计系统的开发者来说，这套方案值得尝试。后续你还可以探索 Umami 的更多高级功能，比如多用户权限管理、自定义仪表盘、数据导出分析等，进一步提升数据驱动运营的能力。