Umami开源网站分析工具本地部署指南-代码聚汇网

Umami开源网站分析工具本地部署指南

外币兑换

1. 项目概述

Umami 是一款轻量级的开源网站分析工具，它提供了简洁直观的数据可视化界面，能够帮助网站管理员追踪访问量、用户行为等关键指标。与传统的商业分析工具相比，Umami 更加注重隐私保护，不会收集用户的个人信息，也不会使用 Cookie 进行跟踪。

在实际应用中，很多企业和个人开发者希望将 Umami 部署在自己的服务器上，这样不仅可以完全掌控数据，还能避免第三方服务的限制和费用。本教程将详细介绍如何在本地环境中部署 Umami，并配置外部访问，让您能够随时随地查看网站分析数据。

2. 环境准备

2.1 硬件与软件要求

在开始部署之前，您需要准备以下环境：

一台运行 Linux 系统的服务器（推荐 Ubuntu 20.04 LTS 或更新版本）
至少 1GB 内存（2GB 以上更佳）
10GB 以上的可用磁盘空间
Node.js 14.x 或更高版本
PostgreSQL 12.x 或更高版本
Nginx 或 Apache 作为反向代理服务器

提示：虽然 Umami 对硬件要求不高，但如果您的网站访问量较大，建议适当增加服务器配置。

2.2 安装必要依赖

首先更新系统软件包并安装基础工具：

bash复制sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget build-essential

安装 Node.js 和 npm（以 Node.js 16.x 为例）：

bash复制curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs

验证安装：

bash复制node -v
npm -v

安装 PostgreSQL 数据库：

bash复制sudo apt install -y postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

3. Umami 部署流程

3.1 获取 Umami 源代码

克隆 Umami 的 GitHub 仓库：

bash复制git clone https://github.com/umami-software/umami.git
cd umami

安装项目依赖：

bash复制npm install

3.2 配置数据库

创建 PostgreSQL 数据库和用户：

bash复制sudo -u postgres psql

在 PostgreSQL 命令行中执行：

sql复制CREATE DATABASE umami;
CREATE USER umami WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE umami TO umami;
\q

3.3 配置 Umami

复制示例配置文件并编辑：

bash复制cp .env.example .env
nano .env

修改以下关键配置项：

code复制DATABASE_URL=postgresql://umami:your_secure_password@localhost:5432/umami
HASH_SALT=your_random_salt_string

注意：HASH_SALT 应该是一个长且随机的字符串，用于加密敏感数据。

3.4 数据库迁移与构建

运行数据库迁移：

bash复制npm run migrate

构建前端资源：

bash复制npm run build

3.5 启动 Umami

您可以选择以下方式之一运行 Umami：

开发模式（适合调试）：

bash复制npm start

生产模式（使用 PM2 进程管理）：

bash复制npm install -g pm2
pm2 start npm --name "umami" -- start
pm2 save
pm2 startup

4. 配置外部访问

4.1 设置防火墙

允许必要的端口通过防火墙：

bash复制sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

4.2 配置反向代理

安装并配置 Nginx：

bash复制sudo apt install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx

创建 Nginx 配置文件：

bash复制sudo nano /etc/nginx/sites-available/umami.conf

添加以下内容（替换 your_domain.com 为您的域名）：

code复制server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

启用配置并测试：

bash复制sudo ln -s /etc/nginx/sites-available/umami.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4.3 配置 HTTPS（可选但推荐）

安装 Certbot 获取 SSL 证书：

bash复制sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your_domain.com

证书会自动续订，您可以通过以下命令测试续订：

bash复制sudo certbot renew --dry-run

5. 初始设置与使用

5.1 访问 Umami 控制台

在浏览器中访问您的域名（如 https://your_domain.com），您将看到 Umami 的登录页面。

默认管理员账号：

用户名：admin
密码：umami

首次登录后请立即修改密码。

5.2 添加网站跟踪

登录后点击"设置" > "网站"
点击"添加网站"按钮
填写网站名称和域名
点击"保存"获取跟踪代码

将生成的 JavaScript 代码添加到您要跟踪的网站中，通常放在 <head> 标签内。

5.3 数据查看与分析

Umami 提供了多种数据视图：

实时访问数据
页面浏览量统计
访客地理位置分布
设备与浏览器信息
流量来源分析

6. 高级配置与优化

6.1 数据库备份策略

设置定期自动备份：

bash复制sudo nano /etc/cron.daily/umami_backup

添加以下内容：

bash复制#!/bin/bash
DATE=$(date +%Y-%m-%d)
sudo -u postgres pg_dump umami > /var/backups/umami_$DATE.sql
find /var/backups/ -name "umami_*.sql" -mtime +30 -exec rm {} \;

设置可执行权限：

bash复制sudo chmod +x /etc/cron.daily/umami_backup

6.2 性能优化

调整 PostgreSQL 配置：

bash复制sudo nano /etc/postgresql/12/main/postgresql.conf

修改以下参数（根据服务器内存调整）：

code复制shared_buffers = 256MB
effective_cache_size = 768MB
work_mem = 16MB
maintenance_work_mem = 64MB

重启 PostgreSQL 使配置生效：

bash复制sudo systemctl restart postgresql

6.3 监控与维护

设置基本的监控：

bash复制sudo apt install -y htop

定期检查系统资源使用情况：

bash复制htop
df -h
free -h

7. 常见问题与解决方案

7.1 安装依赖失败

问题：npm install 过程中出现错误

解决方案：

确保 Node.js 版本符合要求

清除 npm 缓存并重试：

bash复制npm cache clean --force
rm -rf node_modules package-lock.json
npm install

7.2 数据库连接问题

问题：应用启动时无法连接数据库

解决方案：

检查 .env 文件中的数据库连接字符串

确认 PostgreSQL 服务正在运行：

bash复制sudo systemctl status postgresql

检查数据库用户权限

7.3 反向代理配置错误

问题：通过域名访问时出现 502 Bad Gateway

解决方案：

确认 Umami 应用正在运行：
```
bash复制pm2 list
```

检查 Nginx 错误日志：

bash复制sudo tail -f /var/log/nginx/error.log

确保 Nginx 配置中的 proxy_pass 地址正确

7.4 数据收集延迟

问题：网站访问数据没有实时显示

解决方案：

确认跟踪代码已正确添加到网站
检查 Umami 是否配置了正确的时区
对于高流量网站，考虑增加服务器资源

8. 安全最佳实践

8.1 定期更新

保持系统和应用更新：

bash复制sudo apt update && sudo apt upgrade -y
cd /path/to/umami
git pull
npm install
npm run build
pm2 restart umami

8.2 防火墙配置

仅开放必要的端口：

bash复制sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

8.3 数据库安全

定期更改数据库密码

限制数据库仅允许本地连接：

bash复制sudo nano /etc/postgresql/12/main/pg_hba.conf

确保只有本地连接被允许：

code复制host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

8.4 应用安全

定期更改管理员密码
限制登录尝试次数（可通过 Nginx 配置实现）
定期检查应用日志：
```
bash复制pm2 logs umami
```

9. 扩展功能

9.1 多用户支持

Umami 支持创建多个用户并分配不同权限：

管理员可以创建新用户
可以为用户分配特定网站的查看权限
支持设置用户为只读或管理员权限

9.2 自定义指标

通过修改跟踪代码，可以收集自定义事件：

javascript复制umami.track('button-click', { button: 'sign-up' });

9.3 API 集成

Umami 提供了 REST API，可以与其他系统集成：

获取网站列表：GET /api/websites
获取统计数据：GET /api/websites/[id]/stats
创建新记录：POST /api/collect

10. 替代方案比较

虽然 Umami 是一个优秀的选择，但您也可以考虑其他开源分析工具：

工具名称	数据库支持	实时数据	隐私友好	安装复杂度
Umami	PostgreSQL	是	是	中等
Matomo	MySQL	是	是	较高
Plausible	PostgreSQL	是	是	中等
Ackee	MongoDB	否	是	较低

选择依据：

如果您需要成熟的解决方案，Matomo 功能最全面
如果重视简洁和性能，Umami 或 Plausible 是更好的选择
如果使用 MongoDB，可以考虑 Ackee

11. 性能调优实战

11.1 数据库索引优化

分析慢查询：

bash复制sudo -u postgres psql -d umami -c "SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;"

为常用查询添加索引：

sql复制CREATE INDEX idx_pageviews_website_id ON pageview (website_id);
CREATE INDEX idx_pageviews_created_at ON pageview (created_at);

11.2 应用层缓存

安装 Redis 作为缓存：

bash复制sudo apt install -y redis-server
sudo systemctl enable redis-server

配置 Umami 使用 Redis：

修改 .env 文件：

code复制REDIS_URL=redis://localhost:6379

11.3 负载均衡

对于高流量场景，可以设置负载均衡：

在多台服务器上部署 Umami
使用 Nginx 作为负载均衡器
配置共享数据库和 Redis 缓存

示例 Nginx 配置：

code复制upstream umami_servers {
    server 192.168.1.10:3000;
    server 192.168.1.11:3000;
    server 192.168.1.12:3000;
}

server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://umami_servers;
        # 其他代理配置...
    }
}

12. 数据迁移与升级

12.1 备份现有数据

完整备份流程：

bash复制# 备份数据库
sudo -u postgres pg_dump umami > umami_backup_$(date +%Y-%m-%d).sql

# 备份应用配置
tar czvf umami_config_$(date +%Y-%m-%d).tar.gz /path/to/umami/.env /path/to/umami/config

12.2 升级 Umami 版本

安全升级步骤：

查看当前版本：
```
bash复制git tag --points-at HEAD
```

获取最新代码：

bash复制git fetch --tags
git checkout tags/v1.2.0 -b v1.2.0

安装依赖并构建：
```
bash复制npm install
npm run build
```
运行数据库迁移：
```
bash复制npm run migrate
```
重启应用：
```
bash复制pm2 restart umami
```

12.3 数据恢复测试

定期测试备份有效性：

bash复制# 创建测试数据库
sudo -u postgres psql -c "CREATE DATABASE umami_test;"

# 恢复备份
sudo -u postgres psql -d umami_test -f umami_backup_2023-06-01.sql

# 验证数据
sudo -u postgres psql -d umami_test -c "SELECT COUNT(*) FROM pageview;"

13. 监控与告警

13.1 基础监控设置

安装并配置 Prometheus 和 Grafana：

bash复制# 安装 Prometheus
wget https://github.com/prometheus/prometheus/releases/download/v2.30.3/prometheus-2.30.3.linux-amd64.tar.gz
tar xvfz prometheus-*.tar.gz
cd prometheus-*/

# 配置 Prometheus
nano prometheus.yml

添加 Umami 监控目标：

yaml复制scrape_configs:
  - job_name: 'umami'
    static_configs:
      - targets: ['localhost:3000']

13.2 关键指标监控

需要监控的重要指标：

应用响应时间
数据库查询性能
服务器资源使用率
每日数据收集量
错误率

13.3 告警配置

设置阈值告警：

yaml复制# 在 Prometheus 告警规则文件中添加
groups:
- name: umami-alerts
  rules:
  - alert: HighErrorRate
    expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
    for: 10m
    labels:
      severity: critical
    annotations:
      summary: "High error rate on Umami instance"
      description: "Error rate is {{ $value }}"

14. 成本优化策略

14.1 服务器选型建议

不同规模网站的建议配置：

日均PV	推荐配置	预估月成本
<10K	1vCPU, 1GB RAM	$5
10K-100K	2vCPU, 4GB RAM	$20
100K-1M	4vCPU, 8GB RAM	$80
>1M	负载均衡集群	自定义

14.2 存储优化

清理旧数据：

sql复制-- 保留最近90天数据
DELETE FROM pageview WHERE created_at < NOW() - INTERVAL '90 days';

定期执行：

bash复制# 创建清理脚本
echo "DELETE FROM pageview WHERE created_at < NOW() - INTERVAL '90 days';" > /scripts/cleanup.sql

# 设置定时任务
(crontab -l 2>/dev/null; echo "0 3 * * * psql -U umami -d umami -f /scripts/cleanup.sql") | crontab -

14.3 按需扩展

云环境自动扩展策略：

设置 CPU 使用率超过70%时自动增加实例
配置自动缩放组
使用读写分离的数据库架构

15. 移动端适配

15.1 响应式设计

Umami 仪表板本身是响应式的，但需要注意：

确保跟踪代码在移动设备上正常工作
检查移动端用户代理识别准确性
优化移动设备的数据显示

15.2 移动应用集成

在原生移动应用中集成跟踪：

Android 示例（Kotlin）：

kotlin复制val url = "https://your_umami_domain.com/api/collect"
val payload = """
{
    "website": "your-website-id",
    "hostname": "app.yourdomain.com",
    "url": "/main-screen",
    "referrer": "",
    "language": "en-US",
    "screen": "1080x1920",
    "title": "Main Screen"
}
""".trimIndent()

val request = Request.Builder()
    .url(url)
    .post(payload.toRequestBody("application/json".toMediaType()))
    .build()

client.newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        Log.e("Umami", "Tracking failed", e)
    }
    
    override fun onResponse(call: Call, response: Response) {
        if (!response.isSuccessful) {
            Log.e("Umami", "Tracking failed: ${response.code}")
        }
    }
})

15.3 移动端特有指标

跟踪移动设备特有信息：

javascript复制umami.track({
    url: window.location.pathname,
    referrer: document.referrer,
    device: {
        type: /Mobi/.test(navigator.userAgent) ? 'mobile' : 'desktop',
        os: navigator.platform,
        screen: `${window.screen.width}x${window.screen.height}`
    }
});

16. 数据导出与分析

16.1 定期报告生成

设置自动数据导出：

bash复制# 安装依赖
sudo apt install -y jq

# 创建导出脚本
cat > /scripts/export_stats.sh <<'EOF'
#!/bin/bash
DATE=$(date +%Y-%m-%d)
API_KEY="your_admin_api_key"
WEBSITE_ID="your_website_id"

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://your_umami_domain.com/api/websites/$WEBSITE_ID/stats?start=2023-01-01&end=$DATE" \
  | jq . > /exports/umami_stats_$DATE.json
EOF

# 设置定时任务
(crontab -l 2>/dev/null; echo "0 2 * * * /bin/bash /scripts/export_stats.sh") | crontab -

16.2 自定义数据分析

使用 Python 分析导出的数据：

python复制import pandas as pd
import matplotlib.pyplot as plt

# 加载数据
data = pd.read_json('umami_stats_2023-06-01.json')

# 处理页面浏览数据
pageviews = pd.DataFrame(data['pageviews'])
pageviews['date'] = pd.to_datetime(pageviews['date'])
pageviews.set_index('date', inplace=True)

# 绘制趋势图
plt.figure(figsize=(12, 6))
pageviews['value'].plot(title='Daily Pageviews')
plt.xlabel('Date')
plt.ylabel('Pageviews')
plt.grid()
plt.savefig('pageviews_trend.png')

16.3 商业智能集成

将 Umami 数据导入 BI 工具（如 Metabase）：

配置 PostgreSQL 数据源
创建仪表板
设置定期刷新

示例 SQL 查询：

sql复制SELECT 
    DATE(created_at) AS day,
    COUNT(*) AS pageviews,
    COUNT(DISTINCT session_id) AS sessions
FROM 
    pageview
WHERE 
    website_id = 'your-website-id'
    AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY 
    day
ORDER BY 
    day DESC;

17. 多语言支持

17.1 界面语言切换

Umami 支持多语言界面：

在用户设置中选择语言
目前支持的语言包括英语、中文、法语等
社区可以贡献新的语言翻译

17.2 跟踪多语言网站

对于多语言网站，可以在跟踪代码中添加语言参数：

javascript复制umami.track({
    url: window.location.pathname,
    language: navigator.language || 'en-US'
});

然后在 Umami 中按语言筛选数据。

17.3 自定义翻译

添加新语言支持：

在 lang 目录下创建新的语言文件，如 lang/ja-JP.js
按照现有格式添加翻译
提交 Pull Request 到官方仓库

18. 隐私合规配置

确保符合 GDPR 要求：

在跟踪代码中添加数据收集同意检查
提供用户数据访问和删除接口
记录数据处理活动

修改后的跟踪代码示例：

javascript复制if (window.hasUserConsent()) {
    umami.track();
}

18.2 不跟踪(Do Not Track)支持

尊重用户的 DNT 设置：

javascript复制if (navigator.doNotTrack !== '1') {
    umami.track();
}

18.3 IP 匿名化

配置 Nginx 匿名化 IP：

code复制location /api/collect {
    proxy_pass http://localhost:3000;
    proxy_set_header X-Forwarded-For $remote_addr;
    # 其他配置...
}

然后在 Umami 中处理 IP 地址：

javascript复制function anonymizeIP(ip) {
    if (!ip) return null;
    return ip.split('.').slice(0, 2).concat(['0', '0']).join('.');
}

19. 社区支持与贡献

19.1 获取帮助

Umami 社区资源：

官方文档：https://umami.is/docs
GitHub Issues：https://github.com/umami-software/umami/issues
Discord 社区：https://discord.gg/4dz4zcXYrQ

19.2 贡献代码

贡献流程：

Fork 官方仓库
创建特性分支
提交 Pull Request
通过 CI 测试
等待代码审查

19.3 报告问题

有效的问题报告应包含：

Umami 版本
部署环境信息
重现步骤
预期与实际行为
相关日志和截图

20. 未来发展与路线图

Umami 的开发路线包括：

增强的数据可视化功能
更强大的 API 和 Webhook 支持
改进的用户权限管理系统
原生移动应用
更多的数据导出格式支持

您可以关注 GitHub 项目的 Milestones 了解最新进展。

Umami开源网站分析工具本地部署指南

1. 项目概述

2. 环境准备

2.1 硬件与软件要求

2.2 安装必要依赖

3. Umami 部署流程

3.1 获取 Umami 源代码

3.2 配置数据库

3.3 配置 Umami

3.4 数据库迁移与构建

3.5 启动 Umami

4. 配置外部访问

4.1 设置防火墙

4.2 配置反向代理

4.3 配置 HTTPS（可选但推荐）

5. 初始设置与使用

5.1 访问 Umami 控制台

5.2 添加网站跟踪

5.3 数据查看与分析

6. 高级配置与优化

6.1 数据库备份策略

6.2 性能优化

6.3 监控与维护

7. 常见问题与解决方案

7.1 安装依赖失败

7.2 数据库连接问题

7.3 反向代理配置错误

7.4 数据收集延迟

8. 安全最佳实践

8.1 定期更新

8.2 防火墙配置

8.3 数据库安全

8.4 应用安全

9. 扩展功能

9.1 多用户支持

9.2 自定义指标

9.3 API 集成

10. 替代方案比较

11. 性能调优实战

11.1 数据库索引优化

11.2 应用层缓存

11.3 负载均衡

12. 数据迁移与升级

12.1 备份现有数据

12.2 升级 Umami 版本

12.3 数据恢复测试

13. 监控与告警

13.1 基础监控设置

13.2 关键指标监控

13.3 告警配置

14. 成本优化策略

14.1 服务器选型建议

14.2 存储优化

14.3 按需扩展

15. 移动端适配

15.1 响应式设计

15.2 移动应用集成

15.3 移动端特有指标

16. 数据导出与分析

16.1 定期报告生成

16.2 自定义数据分析

16.3 商业智能集成

17. 多语言支持

17.1 界面语言切换

17.2 跟踪多语言网站

17.3 自定义翻译

18. 隐私合规配置

18.1 GDPR 合规

18.2 不跟踪(Do Not Track)支持

18.3 IP 匿名化

19. 社区支持与贡献

19.1 获取帮助

19.2 贡献代码

19.3 报告问题

20. 未来发展与路线图

内容推荐