Umami | Vercel + Neon 部署 Umami | 部署文档#

架构图#

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

免费额度够不够？#

服务	免费额度	Umami 实际消耗	够用？
Vercel Hobby	100万次函数调用/月，100 GB-Hours 执行时长	个人博客约 1-5 万次/月	✅ 绰绰有余
Neon Free	0.5 GB 存储/项目，100 CU-hours/项目	Umami 数据约 50-200 MB/年	✅ 绰绰有余

个人博客（< 10万 PV/月）完全免费运行，不用担心。

为什么不用 Cloudflare D1？#

Cloudflare D1 基于 SQLite，而 Umami 要求 PostgreSQL，两者 SQL 方言和连接方式完全不同，无法兼容。Umami 官方也尚未合并 Cloudflare Workers 部署支持（PR #3475），即使合并也需要外部 PostgreSQL。

第一步：创建 Neon 数据库#

访问 neon.tech，用 GitHub 或邮箱注册
点击 Create Project，填写：
- Project name：umami（随意）
- Region：选 Singapore 或 Tokyo（离中国最近）
- Postgres version：默认 17 即可
创建完成后，进入 Dashboard → Connection String → 选择Prisma -> 进入.env复制
复制 DATABASE_URL 连接字符串

第二步：Fork Umami 仓库#

访问 github.com/umami-software/umami
点击右上角 Fork 按钮
保持默认设置，点击 Create fork

第三步：适配 Prisma 7（重要！不需要配置，只需要看看自己的版本对不对的上）#

Umami 最新版使用了 Prisma 7，它有重大破坏性变更：url 和 directUrl 不再支持在 schema.prisma 中配置，而是移到了 prisma.config.ts。

确认 `prisma.config.ts`（Umami 已自带）#

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
});

prisma.config.ts 中的 url 读取环境变量 DATABASE_URL，用于 Prisma Migrate 执行数据库迁移。

第四步：部署到 Vercel#

访问 vercel.com，用 GitHub 账号登录
点击 Add New → Project
在列表中找到你 Fork 的 umami 仓库，点击 Import
配置项目保持默认
展开 Environment Variables 部分，添加变量：

Name	Value
`DATABASE_URL`	Neon 中拿到的 prisma 连接字符串

点击 Deploy，等待 2-3 分钟
部署成功后，你会得到访问地址：umami-xxxx.vercel.app

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

访问 https://umami-xxxx.vercel.app
默认凭据：用户名 admin，密码 umami
立即修改密码：Settings → Profile
添加你的博客网站：回到主页 → Websites → Add website →NAME(随便一个名字)→Domain(你网站地址)
保存后获取：点进去→看板右上角Edit→复制Website ID

第六步：绑定自定义域名（推荐）#

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

在 Vercel 项目中，快速到达https://vercel.com/你项目名字/umami/settings/domain，总之就是进到你部署的umami里面左侧找到Domains。找到你部署的域名→编辑→更改Domain
输入你的域名，如 stats.yourdomain.com
点击 Add Domain
Vercel会报错，
去 Cloudflare Dashboard → 你的域名 → DNS → Add record：

Type	Name	Target	Proxy status
CNAME	`stats`	`cname.vercel-dns.com`	关闭（灰色云朵）

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

等待域名验证通过（通常几分钟），Vercel 自动配置 SSL 证书
Vercel 过一会你会看到黄色警告，点进去页面，点击授权即可，他会更改cf的Target
再次查看Vercel你会发现成功了

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

通用接入方式#

在你的网站 <head> 中添加以下脚本：

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

将 src 替换为你的 Umami 地址，data-website-id 替换为在 Umami 后台获取的 Website ID。

可选参数#

参数	说明	示例
`data-auto-track="false"`	禁用自动追踪，手动控制页面访问上报	需要手动调用 `umami.track()`
`data-do-not-track="true"`	尊重浏览器的 Do Not Track 设置	不追踪启用了 DNT 的用户
`data-domains="example.com"`	仅在指定域名下追踪	多个域名用逗号分隔

各框架接入示例#

HTML 静态站：

1
<head>
2
  <script async src="https://stats.example.com/script.js" data-website-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></script>
3
</head>

Next.js：

1
export default function RootLayout({ children }) {
2
  return (
3
    <html>
4
      <head>
5
        <script async src="https://stats.example.com/script.js" data-website-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></script>
6
      </head>
7
      <body>{children}</body>
8
    </html>
9
  );
10
}

Vue / Nuxt：

1
export default defineNuxtConfig({
2
  app: {
3
    head: {
4
      script: [
5
        { async: true, src: "https://stats.example.com/script.js", "data-website-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" },
6
      ],
7
    },
8
  },
9
});

Hexo：

在主题的 _config.yml 中添加自定义脚本配置，或直接修改 layout/layout.ejs 的 <head> 部分。

Hugo：

在 layouts/partials/head.html 中添加 script 标签。

本项目爆改的Firefly 模板#

本博客模板已内置 Umami 组件，只需修改 src/config/siteConfig.ts：

1
analytics: {
2
    umamiAnalytics: {
3
        websiteId: "你的 Website ID",
4
        scriptUrl: "https://你的Umami域名/script.js",
5
        trackOutboundLinks: true,
6
        collectWebVitals: false,
7
    },
8
},

第八步：配置公开统计面板#

登录 Umami 后台
点击你的网站 → 右上角 Edit
找到 Share URL 选项
勾选要公开的内容（推荐只勾选 Traffic → Overview）
保存后复制生成的分享链接，格式：https://stats.yourdomain.com/share/xxxxxxxxx
直接重定向到Umami 分享链接

第九步：设置数据自动清理#

登录 Umami 后台
Settings → Websites → 你的网站 → Data retention
设置保留时间，建议 1 年
保存

确保数据库不会超出 Neon 的 0.5 GB 免费额度。

更新 Umami 版本#

进入你 Fork 的 GitHub 仓库
点击 Sync fork → Update branch
Vercel 会自动检测到代码变更并重新部署

常见问题排查#

问题	解决方案
`P1012: The datasource property url is no longer supported`	Prisma 7 破坏性变更，需从 `schema.prisma` 中删掉 `url` 和 `directUrl`，连接配置由 `prisma.config.ts` 接管
国内访问 `.vercel.app` 很慢/打不开	绑定自定义域名，Cloudflare DNS 中关闭 Proxy
SSL 警告 `sslmode "prefer" is treated as alias for "verify-full"`	将 `sslmode=require` 改为 `sslmode=verify-full` 可消除警告，不影响功能
公开统计面板样式和别人的不一样	Umami 不同版本分享页面样式不同，这是前端代码决定的，后台无配置项可切换

保存清单#

部署完成后，请妥善保存以下信息：

项目	存放位置
Neon 数据库密码	Neon Dashboard → Settings → Database
Neon 连接字符串	Neon Dashboard → Connection Details
Umami 管理员账号	Umami 后台 → Settings → Profile
Website ID	Umami 后台 → Edit Website
Umami 公开数据分享链接	Umami 后台 → Edit Website → Share URL
Vercel 项目地址	Vercel Dashboard
Umami 自定义域名	Vercel → Settings → Domains

⚠️ 请勿将数据库密码和 Umami 管理员密码提交到 GitHub 或公开分享。

Umami | Vercel + Neon 部署 Umami | 部署文档#

架构图#

免费额度够不够？#

为什么不用 Cloudflare D1？#

第一步：创建 Neon 数据库#

第二步：Fork Umami 仓库#

第三步：适配 Prisma 7（重要！不需要配置，只需要看看自己的版本对不对的上）#

确认 `prisma.config.ts`（Umami 已自带）#

第四步：部署到 Vercel#

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

第六步：绑定自定义域名（推荐）#

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

通用接入方式#

可选参数#

各框架接入示例#

本项目爆改的Firefly 模板#

第八步：配置公开统计面板#

第九步：设置数据自动清理#

更新 Umami 版本#

常见问题排查#

保存清单#

评论区

音乐

Umami | Vercel + Neon 部署 Umami | 部署文档

Umami | Vercel + Neon 部署 Umami | 部署文档#

架构图#

免费额度够不够？#

为什么不用 Cloudflare D1？#

第一步：创建 Neon 数据库#

第二步：Fork Umami 仓库#

第三步：适配 Prisma 7（重要！不需要配置，只需要看看自己的版本对不对的上）#

确认 prisma.config.ts（Umami 已自带）#

第四步：部署到 Vercel#

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

第六步：绑定自定义域名（推荐）#

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

通用接入方式#

可选参数#

各框架接入示例#

本项目爆改的Firefly 模板#

第八步：配置公开统计面板#

开启 Share URL#

第九步：设置数据自动清理#

更新 Umami 版本#

常见问题排查#

保存清单#

评论区

音乐

确认 `prisma.config.ts`（Umami 已自带）#