前两天折腾了 Umami, 在如标题的环境中装了一晚上终于成功了, 这里也是复盘记录下踩到的坑

准备工作

下载

git clone https://github.com/mikecao/umami.git

如果是国内鸡, 可以使用 GHProxy 等代理来下载

git clone https://mirror.ghproxy.com/https://github.com/mikecao/umami.git

装环境

根据官方文档, Umami 需要 NodeJS 18.17+, MySQL 8.0+

查看 NodeJS 版本

node -v

如果低于 18.17, 则需要升级

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

node -v 已经升级到 18.17+ 版本即可

由于 MySQL 8.0 性能开销太大, 我的小鸡顶不住, 这里强行使用 5.7 继续安装过程, 后面会有踩坑的详细解决过程

安装

拉依赖

直接 npm install, 报依赖冲突, 尝试 npm install --legacy-peer-deps 强行安装, 报错:

npm ERR! code EINTEGRITY
npm ERR! Integrity checksum failed when using sha512: wanted sha512-TvB3LqF2VtP6yI6HXlRT5TxX98HKha6hCcrg9dwlPwNaedVNuQA9KgBdtWKgiyakyCTYHQ+KJeFEstNKfZr64w== but got sha512-VHu6UWgWLJykaSeI1M2DpZMVRLuGCOV91i5I81xnJuAI0MKHP7ZJ3my5naOQkzG10ris3hBr+o5RElF1wQ5IXA==.

搜到一个古老 issue , 里面提到的解决方法是必须用 yarn, 还得用 yarn2. 好吧, 那就装 yarn

国内鸡先换源

vi ~/.npmrc

编辑内容为

registry=https://npmreg.proxy.ustclug.org/

安装 yarn

npm install -g yarn

完成后 yarn --version, yarn已经装上了. 尝试 yarn install 依然报错, 那就升级 yarn2 吧

yarn set version berry

完成后 yarn --version, 版本已经不是 1.x 了, 升级成功

尝试 yarn install, 依然报错, 没招了, 删除重新拉下来 install 试试, Done with warnings, 终于成功了

构建

在 Umami 目录下创建 .env, 添加你的数据库配置, 格式如

DATABASE_URL=mysql://username:mypassword@localhost:3306/mydb

运行 yarn build, 报错:

ERROR: "build-db-client" exited with 129.
ERROR: "build-db" exited with 1.

搜不到什么有效信息, 没办法尝试逐个执行脚本. 查看 package.json, 发现 build 时运行的脚本有 check-env build-db check-db build-tracker build-geo build-app

尝试 npm run check-env, 通过; npm run build-db, 通过; npm run check-db, 报错:

✗ Command failed: prisma migrate deploy
Error: P3009

migrate found failed migrations in the target database, new migrations will not be applied. Read more about how to resolve migration issues in a production database: https://pris.ly/d/migrate-resolve
The `05_add_visit_id` migration started at 2024-06-11 14:04:38.450 UTC failed

查看运行的脚本, 这个 check-db 实际上是在 Migration DB, 搜索得知, MySQL 5.7 在升级时由于脚本中用到了 8.0 才有的特性会导致报错. 我们修改 Umami 目录 db/mysql/migrations/02_report_schema_session_data/migration.sql 中开头的

-- AlterTable
ALTER TABLE `event_data` RENAME COLUMN `event_data_type` TO `data_type`;
ALTER TABLE `event_data` RENAME COLUMN `event_date_value` TO `date_value`;
ALTER TABLE `event_data` RENAME COLUMN `event_id` TO `event_data_id`;
ALTER TABLE `event_data` RENAME COLUMN `event_numeric_value` TO `number_value`;
ALTER TABLE `event_data` RENAME COLUMN `event_string_value` TO `string_value`;

为 (注意脚本是否和我列出的版本有差异)

-- RenameColumns
ALTER TABLE `event_data` ADD COLUMN data_type INTEGER UNSIGNED AFTER event_data_type;
ALTER TABLE `event_data` ADD COLUMN date_value TIMESTAMP(0) AFTER event_date_value;
ALTER TABLE `event_data` ADD COLUMN event_data_id VARCHAR(36) AFTER event_id;
ALTER TABLE `event_data` ADD COLUMN number_value DECIMAL(19, 4) AFTER event_numeric_value;
ALTER TABLE `event_data` ADD COLUMN string_value VARCHAR(500) AFTER event_string_value;
 
UPDATE event_data
SET data_type = event_data_type,
    date_value = event_date_value,
    event_data_id = event_id,
    number_value = event_numeric_value,
    string_value = event_string_value;
 
ALTER TABLE `event_data` MODIFY data_type INTEGER UNSIGNED NOT NULL;
ALTER TABLE `event_data` MODIFY event_data_id VARCHAR(36) NOT NULL;
 
ALTER TABLE `event_data` DROP COLUMN event_data_type;
ALTER TABLE `event_data` DROP COLUMN event_date_value;
ALTER TABLE `event_data` DROP COLUMN event_id;
ALTER TABLE `event_data` DROP COLUMN event_numeric_value;
ALTER TABLE `event_data` DROP COLUMN event_string_value;
 
ALTER TABLE `event_data` ADD PRIMARY KEY(event_data_id);

修改完成后, 清空数据库重新 build-db 然后 check-db, 此时又报错:

✗ Command failed: prisma migrate deploy
Error: P3018

A migration failed to apply. New migrations cannot be applied before the error is recovered from. Read more about how to resolve migration issues in a production database: https://pris.ly/d/migrate-resolve

Migration name: 05_add_visit_id

Database error code: 1305

Database error:
FUNCTION amoe_umami.BIN_TO_UUID does not exist

Please check the query number 2 from the migration file.

搜索得知, 又是因为用到了 MySQL 8 中才有的函数 BIN_TO_UUID 导致出错. 这里我们通过在数据库中写一个自定义函数来解决这个问题. 修改 Umami 目录 db/mysql/migrations/05_add_visit_id/migration.sql 中大约 line8 的

BIN_TO_UUID(RANDOM_BYTES(16) & 0xffffffffffff0fff3fffffffffffffff | 0x00000000000040008000000000000000) uuid

为 (注意脚本是否和我列出的版本有差异)

UUIDv4() uuid

然后 root 登入 phpMyAdmin , 选中 Umami 使用的数据库名, 点击右边导航栏的程序, 点击添加程序, 程序名称 UUIDv4, 类型 FUNCTION, 参数清空, 返回类型 CHAR, 长度 36, 字符集 utf8mb4, 用户 root@localhost, 定义

BEGIN
   DECLARE hexStr CHAR(32);
   RETURN LOWER(CONCAT(
HEX(RANDOM_BYTES(4)), '-',
    HEX(RANDOM_BYTES(2)), '-4',
    SUBSTR(HEX(RANDOM_BYTES(2)), 2, 3), '-',
    CONCAT(HEX(FLOOR(ASCII(RANDOM_BYTES(1)) / 64)+8),SUBSTR(HEX(RANDOM_BYTES(2)), 2, 3)), '-',
    HEX(RANDOM_BYTES(6))
    ));

END

如下图示. 如果你使用其他工具, 添加方法可能会有所不同, 不多赘述

然后保存, 清空数据库里的表 (注意不是清空数据库: 数据库里还有我们的自定义函数), 重新 build-db 然后 check-db, 此时又报错:

✗ Command failed: prisma migrate deploy
Error: P3018

A migration failed to apply. New migrations cannot be applied before the error is recovered from. Read more about how to resolve migration issues in a production database: https://pris.ly/d/migrate-resolve

Migration name: 06_session_data

Database error code: 1064

Database error:
You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'COLUMN `event_key` TO `data_key`;

-- AlterTable
ALTER TABLE `session_data` RENA' at line 2

Please check the query number 3 from the migration file.

打开 Umami 目录 db/mysql/migrations/05_session_data/migration.sql , 搜索得知是约 line7-11 的脚本内容不兼容 MySQL 5.7, 修改原脚本内容

-- AlterTable
ALTER TABLE `event_data` RENAME COLUMN `event_key` TO `data_key`;

-- AlterTable
ALTER TABLE `session_data` RENAME COLUMN `event_key` TO `data_key`;

为 (注意脚本是否和我列出的版本有差异)

-- AlterTable
ALTER TABLE `event_data` CHANGE COLUMN `event_key` `data_key` VARCHAR(500);

-- AlterTable
ALTER TABLE `session_data` CHANGE COLUMN `event_key` `data_key` VARCHAR(500);

然后清空数据库里的表 (注意不是清空数据库: 数据库里还有我们的自定义函数), 重新 build-db 然后 check-db, 终于成功

然后 npm run build-tracker, 成功; npm run build-geo, 很慢, 查看脚本, 发现是下载 GeoIP 数据库. 我们修改 Umami 目录 scripts/build-geo.js, 给每个下载链接前面加上代理 https://mirror.ghproxy.com/, 重新 build-geo, 很快完成

然后npm run build-app, 一次完成

运行

yarn start, 报错 3000 端口被占用

打开 .env, 添加一行

PORT=54321

重新 yarn start-env, 成功运行~

参考文章

Umami Docs
Issue: verbose stack Error: Integrity checksum failed when using sha512: wanted sha512-T…== but got sha512-…==. 
Issue: can’t run on v2.3.0. Err msg: migrate found failed migrations in the target database
Issue: prisma migrate deploy Error: P3009
部署 Umami 访客统计系统 – 心盲博客
umami 升级记 — 能跑千万别折腾 – obaby@mars