Umami通过Vercel+Neon部署方案

一、架构#

1
博客用户
2
    │
3
    ▼
4
Cloudflare CDN (博客静态站)
5
    │  加载 script.js
6
    ▼
7
Vercel (Umami Next.js 应用)
8
    │  读写数据
9
    ▼
10
Neon (Serverless PostgreSQL)

Cloudflare D1 基于 SQLite，Umami 仅支持 PostgreSQL，无法兼容。

二、第一步：创建 Neon 数据库#

1. 访问 neon.tech 注册
2. Create Project：
   • Project name：umami
   • Region：Singapore 或 Tokyo
   • Postgres version：默认 17
3. 进入 Dashboard → Connection String → 选择 Prisma → 进入 .env 复制
4. 复制 DATABASE_URL 连接字符串

三、第二步：Fork Umami 仓库#

访问 github.com/umami-software/umami，点击 Fork，保持默认设置。

四、第三步：确认 Prisma 7 适配#

Umami 最新版使用 Prisma 7，url 和 directUrl 不再支持在 schema.prisma 中配置，已移至 prisma.config.ts。Umami 项目根目录已自带 prisma.config.ts：

1
import 'dotenv/config';
2
import { defineConfig, env } from 'prisma/config';
3

4
export default defineConfig({
5
  datasource: {
6
    url: env('DATABASE_URL'),
7
  },
8
});

无需手动修改，只需确认 Fork 出来的版本中存在该文件。

五、第四步：部署到 Vercel#

1. 访问 vercel.com，GitHub 登录
2. Add New → Project，找到 Fork 的 umami 仓库，Import
3. 配置保持默认
4. Environment Variables 添加：

5. 点击 Deploy，等待 2-3 分钟，得到访问地址 umami-xxxx.vercel.app

六、第五步：首次登录和安全设置#

1. 访问部署地址，默认凭据：用户名 admin，密码 umami
2. 立即修改密码：Settings → Profile
3. 添加博客网站：主页 → Websites → Add website → 填写 Name 和 Domain
4. 点击进入该网站，浏览器地址栏 /websites/{id} 路径中的 UUID 即 Website ID；也可在网站设置页的 Tracking Code 面板里复制 data-website-id 的值

七、第六步：绑定自定义域名#

Vercel 的 .vercel.app 域名在国内可能被墙，绑定自定义域名解决。

1. Vercel 项目 → Settings → Domains → 添加域名（如 stats.yourdomain.com）
2. Vercel 会报错。去 Cloudflare DNS 添加记录：

⚠️ Proxy 必须关闭。Vercel 自带 CDN，开 Cloudflare Proxy 会冲突导致 SSL 问题。

3. 等待域名验证通过，Vercel 自动配置 SSL 证书
4. Vercel 显示黄色警告时点进去授权，Cloudflare 的 Target 会被自动更新
5. 验证成功

八、第七步：配置博客接入 Umami#

1
<script async src="https://你的Umami域名/script.js" data-website-id="你的 Website ID"></script>

1
analytics: {
2
    umamiAnalytics: {
3
        websiteId: "你的 Website ID",
4
        shareId: "你的 Share ID",   // 用于拉取公开统计，见第八步
5
        scriptUrl: "https://你的Umami域名/script.js",
6
        trackOutboundLinks: true,
7
        collectWebVitals: false,
8
    },
9
},

九、第八步：开启 Share URL（用于公开访问 UV/PV）#

通过 Umami 的 Share API，无需服务端鉴权即可在博客首页展示访问数据。

1
// 核心调用逻辑（简化版）
2
const shareRes = await fetch(`${statsBaseUrl}/api/share/${shareId}`);
3
const share = await shareRes.json();
4
const websiteId = share.websiteId || share.entityId;
5
const token = share.token || shareId;
6

7
const statsRes = await fetch(
8
  `${statsBaseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${Date.now()}`,
9
  {
10
    headers: {
11
      "x-umami-share-token": token,
12
      "x-umami-share-context": "1",
13
      "Content-Type": "application/json",
14
    },
15
  },
16
);
17
const data = await statsRes.json();
18
// data.uv / data.visitors → UV
19
// data.pv / data.pageviews → PV

十、第九步：数据容量管理#

新版 Umami（Prisma 7 版本）已移除 Data retention 设置与后台自动清理任务：网站设置里只剩 Edit / Tracking Code / Replay / Share / Data（Reset、Delete、Transfer）五个面板，设置导航只有 Preferences、Profile、Teams。旧教程「Data retention 设 1 年」的步骤不再适用，数据容量需要自行监控。

个人博客量级估算：一条事件记录约几百字节，日均几百 PV 的站点一年约 100-200 MB，Neon 免费版 0.5 GB 通常够用数年，平时无需处理。

建议做法：

1. 偶尔登录 Neon Dashboard → Project → Storage 查看存储用量
2. 逼近额度时两种清理方式任选：
   • 全量重置：Umami 后台 → 网站设置页 → Data 面板 → Reset data，一键清空该网站统计（最省事，浏览量从零重新累计）
   • 保留近期数据：在 Neon SQL Editor 中删除老数据，例如：

1
-- 删除一年前的事件
2
DELETE FROM website_event WHERE created_at < now() - interval '1 year';
3
-- 清理已无事件引用的 event_data
4
DELETE FROM event_data WHERE website_event_id NOT IN (SELECT event_id FROM website_event);
5
-- 删除已无任何事件的 session
6
DELETE FROM session WHERE session_id NOT IN (SELECT DISTINCT session_id FROM website_event);

十一、更新 Umami 版本#

进入 Fork 的 GitHub 仓库 → Sync fork → Update branch，Vercel 自动检测变更并重新部署。

十二、常见问题#

十三、保存清单#

⚠️ 数据库密码和管理员密码不要提交到 GitHub 或公开分享。Website ID 和 Share ID 可公开，前者已在页面 HTML 中暴露，后者是 Umami 设计的公开访问凭据。