使用 Vercel 部署 Umami 网站统计服务 2026 最新教程

飔梦2025-02-142026-08-02

引言

Umami 是一款开源、自托管的网站分析工具，以隐私友好、轻量、界面清爽著称，是 Google Analytics 的理想替代方案。它不使用 Cookie、不收集个人身份信息，对 GDPR、CCPA 等隐私法规天然友好；追踪脚本仅约 2KB，对网站性能几乎没有影响。

2025年11月，Umami 正式发布 v3 大版本。这是一次包含破坏性变更的重大升级——v3 不再支持 MySQL，仅支持 PostgreSQL。如果你正在使用旧版 MySQL，升级前需要先完成数据迁移。

⚠️ 重要提醒：2025年11月起，Umami v3 已不再支持 MySQL，仅支持 PostgreSQL。本教程基于 v3 编写，请务必使用 PostgreSQL 数据库。

Umami 的主要特点

✅ 隐私保护：不使用 Cookie，不收集个人数据，符合 GDPR、CCPA 等隐私法规。
✅ 开源自托管：基于 MIT 许可，可自行部署，数据完全掌握在自己手中。
✅ 轻量高效：追踪脚本仅约 2KB，不影响网站性能。
✅ 实时分析：提供实时访问数据，包括页面浏览量、来源、设备类型、操作系统、地理位置等。
✅ 多网站管理：一次安装可跟踪无限数量的网站。
✅ 简单易用：直观的仪表盘，移动端适配良好。
✅ API 支持：提供完整的 REST API，方便与其他系统集成。
✅ v3 新特性：全新 UI、通用筛选器、Segments（分群）、Cohorts（同期群分析）、Links（短链追踪）、Pixels（像素追踪）、全新管理后台。
✅ v3.2 新特性（2026年6月发布）：热力图（点击/滚动双模式）、会话回放增强、收入报表改进、安全加固。

部署方式概览

部署方式	适用人群	优点	缺点
Vercel + PostgreSQL	个人/开发者	免费、自动 HTTPS、全球 CDN、配置简单	免费版有额度限制，vercel.app 域名国内被墙
Docker Compose	服务器用户	最通用、数据自托管、迁移方便	需自行维护服务器
Cloud / PaaS（Railway、Render 等）	中小团队	一键部署、免运维	部分平台需付费

本教程以 Vercel + PostgreSQL 部署为主线。

准备工作

GitHub 账号（用于 Fork 仓库与 Vercel 登录）
Vercel 账号（用 GitHub 快捷登录即可）
PostgreSQL 数据库（v3 已不再支持 MySQL，必须使用 PostgreSQL）
自己的域名（可选，但强烈推荐）

部署完成后 Vercel 会默认分配 *.vercel.app 三级域名，但该域名在大陆地区已被墙，建议绑定自有域名。

开始部署

1. Fork 官方仓库

前往官方仓库 github.com/umami-software/umami，点击右上角 Fork 到自己的 GitHub 账号下。

2. 准备 PostgreSQL 数据库

你可以在以下平台免费创建 PostgreSQL 数据库：

Neon（推荐，Vercel Postgres 的底层供应商）
Supabase
Vercel Dashboard 的 Storage 选项卡（实际由 Neon 提供）

创建后拿到连接串，格式如下：

postgresql://用户名:密码@主机:端口/数据库名

3. 在 Vercel 导入项目

打开 Vercel，使用 GitHub 快捷登录。
进入 Dashboard，点击 Add New → Project。
在 Import Git Repository 中选择 Continue With GitHub，授权 Vercel 访问你的仓库。
选中你 Fork 出来的 umami 仓库。

4. 配置环境变量

在部署前的 Environment Variables 区域添加以下变量：

变量名	值	说明
`DATABASE_URL`	你的 PostgreSQL 连接串	必填，唯一必需的变量
`APP_SECRET`	`openssl rand -hex 32` 生成的随机串	用于加密认证 token，每个实例应唯一
`TRACKER_SCRIPT_NAME`	自定义脚本名，如`analytics.js`	绕过广告拦截器
`COLLECT_API_ENDPOINT`	如`/my-collect`	自定义数据上报路径
`DISABLE_TELEMETRY`	`1`	禁用匿名遥测

⚠️ 关于 HASH_SALT 的重要说明：旧版教程中常见的 HASH_SALT 环境变量在 v3 中已被 APP_SECRET 取代。请不要再使用 HASH_SALT，直接使用 APP_SECRET 即可。

APP_SECRET 的生成方式：

openssl rand -hex 32

最后点击 Deploy，等待约 3 分钟部署完成。

5. 绑定自定义域名

进入 Vercel 项目的 Settings → Domains，添加你的域名并按提示配置 CNAME 记录。Vercel 会自动签发 SSL 证书。

6. 首次登录

打开你的 Umami 域名，使用默认账号登录：

用户名：admin
密码：umami

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

Docker Compose 部署（备选方案）

如果你有自己的服务器，Docker Compose 是更通用的方案：

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      APP_SECRET: replace-me-with-a-random-string
    depends_on:
      db:
        condition: service_healthy
    restart: always

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]

volumes:
  umami-db-data:

启动：

docker compose up -d

访问 http://服务器IP:3000 即可。

从 v2 / MySQL 迁移到 v3

如果你之前使用的是 v2 且数据库为 MySQL，升级到 v3 前需要先将数据迁移到 PostgreSQL。

官方提供了迁移指南：Migrate MySQL to PostgreSQL

迁移步骤概要：

备份现有 MySQL 数据库
按照官方指南将数据导出并导入 PostgreSQL
将环境变量中的 HASH_SALT 替换为 APP_SECRET
更新镜像到 v3 版本
启动新版本，确认 Prisma migration 顺利完成

注意：v3 是一次包含破坏性变更的大版本，不支持直接从 v2 MySQL 无缝升级，必须先完成数据迁移。

API

Umami 提供完整的 REST API，可用于自动化报表和数据集成：

官方 API 文档：漠北残月的博客教程
进阶教程：张洪HEO的教程

更新说明

本教程已针对 Umami v3 进行更新，主要变更：

项目	旧版 (v2)	新版 (v3)
数据库	MySQL / PostgreSQL	仅 PostgreSQL
认证密钥	`HASH_SALT`	`APP_SECRET`
UI	旧版界面	全新 UI
分析功能	基础筛选	Segments + Cohorts
追踪方式	仅脚本	新增 Links + Pixels
热力图	无	v3.2 新增