从 v1 迁移到 v2

Umami v2 引入了重新设计的架构和一些破坏性更改。

破坏性更改

• API 端点发生了变化，并且新增了一些端点。更多信息请参见 API。
• 追踪脚本文件名由 umami.js 更名为 script.js。
• collect API 端点从 /api/collect 改名为 /api/send。
• 追踪器不再使用 CSS 类名触发事件，改为使用 HTML 数据属性。更多信息请参见 事件追踪。
• 全局 umami JavaScript 对象上的方法已更改。现在只有一个 .track() 方法，以及新的事件数据发送方式。 详见 追踪器功能。
• 环境变量 TRACKER_SCRIPT_NAME 不再向脚本名追加 .js 后缀。更多信息请参见 环境变量。

数据迁移

由于架构变化，v1 数据库中的数据需要转换为 v2 格式。 为了协助迁移，我们创建了一个脚本 @umami/migrate-v1-v2，可以帮助你迁移所有数据。

要求

• 数据库架构必须与最新的 v1 版本（v1.4.0）同步。脚本会查询 prisma 的 migrations 表，以确保已运行最新的迁移。

重要提示

• 使用前请先备份目标数据库。如果迁移过程中断，可能会导致数据丢失。
• 对于数据量较大的用户（超过 500 万条），迁移过程可能较长，请合理规划时间。
• 该脚本不会将任何事件数据迁移到 v2。
• 迁移完成后，脚本会询问是否删除 v1 的表。
• 如果发现 event_data 表中有数据，该表会被重命名为 v1_event_data，但不会被删除。

故障排除

• 如果你的 DATABASE_URL 是 localhost，迁移时无法连接数据库，尝试改为使用 IP 地址，例如：127.0.0.1。

运行迁移

运行迁移脚本有两种方式。

在 Umami 文件夹内运行

如果可以访问应用程序的终端，可以使用此方式。 确保应用已经构建完成。如果未构建，请先运行 yarn build。

cd umami
npx @umami/migrate-v1-v2@latest

独立运行

如果无法访问应用程序文件夹，比如部署在 Vercel 或 Netlify 上，请使用此方式。

安装

git clone https://github.com/umami-software/migrate-v1-v2.git
cd migrate-v1-v2
yarn install
yarn build

配置

创建 .env 文件，定义如下变量：

DATABASE_URL={连接字符串}

运行

yarn start

Docker 迁移

进入正在运行的 Docker 容器。可以通过 docker ps 输出找到容器名称。

docker exec -ti -u 0 <应用容器名> sh

运行迁移脚本。

npx @umami/migrate-v1-v2@latest

成功运行迁移后，界面应如下所示：