一、架构#

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. 进入网站看板 → 右上角 Edit → 复制 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 后台 → Settings → Websites → 你的网站 → Data retention，建议设为 1 年，避免超出 Neon 0.5 GB 免费额度。

十一、更新 Umami 版本#

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

十二、常见问题#

十三、保存清单#

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