Umami 3.0 升级实录：1Panel 下数据库迁移至 PostgreSQL

Umami 3.0 升级实录：1Panel 面板下 MySQL/MariaDB 到 PostgreSQL 数据迁移。

两个月前我还在纠结 Umami 只支持 PostgreSQL, MySQL，而服务器又只安装了 MariaDB，只能一通折腾才让它跑在 MariaDB 上。谁能想到，仅仅两个月后，Umami V3 宣布数据库竟然只支持 PostgreSQL^[1]。当初废了不少功夫采用 MariaDB 存储数据，如今最终还是得迁移到 PostgreSQL。停在 v2.19.0 虽然是一种解决方案，但固步自封终究不是长久之计。

一、迁移并升级

Umami 文档提供的迁移教程如下：Migrate MySQL to PostgreSQL。总结下来，整体流程包括：① 安装 PostgreSQL 版本的 Umami 获取表结构；② 从 MySQL/MariaDB 导出 Umami 表数据；③ 将数据导入 PostgreSQL；④ 升级 Umami 容器至最新版。由于官方文档较为简略，实际操作过程中踩坑不少。本文对整个过程进行了整理归纳，特此记录。

基础环境：1Panel 面板，Umami V2.19.0 Docker 部署，MySQL/MariaDB 数据库。

约定：MySQL or PostgreSQL 中 Umami 所使用的数据库名称、用户均为 umami，MySQL 容器名称为 MySQL，PostgreSQL 容器名称为 PostgreSQL。

① 获取 PostgreSQL 版表结构

首先，在 1Panel 面板的“已安装应用”中获取 MySQL 版 Umami 容器（以下简称“旧容器”）的哈希盐。随后手动执行一次备份，并将备份记录下载至本地。接着卸载该应用（注意：不要勾选“删除备份”和“删除数据库”选项）。然后重新安装 Umami（以下简称“过渡容器”），版本为 V2.19.0，数据库服务选择 PostgreSQL，哈希盐设置为旧容器的哈希盐值。启动过渡容器后，等待其自动初始化表结构。

接着，在 1Panel 面板的“数据库管理”选项中，对 PostgreSQL 的 umami 数据库手动执行一次初始化备份。随后终端运行以下命令，清空 _prisma_migrations 和 user 两张表^[2]。

docker exec -i -e PGPASSWORD=数据库密码 PostgreSQL psql -U umami -d umami -c 'truncate table "_prisma_migrations"; truncate table "user";'

TIP：可在 1Panel 面板中再主动执行一次 “清除数据” 后的数据库备份。

② 从 MySQL 中导出数据

官方文档建议使用 mysqldump 工具导出数据库记录，但 1Panel 安装的容器版 MySQL/MariaDB 默认并不包含该工具。鉴于前一步已通过 PostgreSQL 初始化获得了 Umami 的表结构，目前所需的仅是原数据库中的记录数据，因此此处可以继续使用 1Panel 面板的数据库备份功能，手动对 MySQL/MariaDB 的 Umami 数据库进行备份并下载记录至本地。

我们只保留包含 INSERT 的语句行，其他所有内容一律删除。具体来说，仅保留形如以下结构的语句：

INSERT INTO `表名` VALUES ('数据1'), ('数据2');

最后，为了兼容 PostgreSQL 的语法规范，需要对 SQL 文件进行一次全局字符替换^[3]：

• 将 \' 全局替换为 ''，以正确表示字符串中的单引号；

• 将反引号 ` 全局替换为双引号 "，以符合 PostgreSQL 对标识符的引用方式。

# 替换 \' 为 ''
sed -i "s/\\\'/''/g" umami.sql

# 替换反引号 ` 为双引号 "
sed -i 's/`/"/g' umami.sql

转换效果示例：

-- 原始 SQL 语句
INSERT INTO `test` VALUES (1, 'It\'s fine');

-- 替换后 SQL 语句
INSERT INTO "test" VALUES (1, 'It''s fine');

③ 将数据导入 PostgreSQL

将处理后的 SQL 文件上传至服务器，并在相同目录下通过终端执行以下命令导入数据：

docker exec -i -e PGPASSWORD=数据库密码 PostgreSQL psql -U umami -d umami  < umami.sql

导入完成后，重启过渡容器，随后可通过网页端验证迁移是否成功，并检查是否存在异常情况。

④ 升级 Umami 容器至最新版

卸载过渡容器，同样不要勾选“删除备份”和“删除数据库”选项。随后重新安装 Umami，版本为 V3.0.0，哈希盐设置为旧容器的哈希盐值，数据库配置为过渡容器中 umami 数据库的名称、用户名和密码。启动容器后，待日志中出现如下内容代表升级成功：

Umami  | > umami@3.0.0 check-db /app
Umami  | > node scripts/check-db.js
Umami  | 
Umami  | ✓ DATABASE_URL is defined.
Umami  | ✓ Database connection successful.
Umami  | ✓ Database version check successful.
Umami  | Prisma schema loaded from prisma/schema.prisma
Umami  | Datasource "db": PostgreSQL database "umami", schema "public" at "PostgreSQL:5432"
Umami  | 
Umami  | 14 migrations found in prisma/migrations
Umami  | Applying migration `14_add_link_and_pixel`
Umami  | The following migration(s) have been applied:
Umami  | 
Umami  | migrations/
Umami  |   └─ 14_add_link_and_pixel/
Umami  |     └─ migration.sql
Umami  |       
Umami  | All migrations have been successfully applied.
Umami  | 
Umami  | ✓ Database is up to date.
Umami  | 
Umami  | > umami@3.0.0 update-tracker /app
Umami  | > node scripts/update-tracker.js
Umami  | 
Umami  | > umami@3.0.0 start-server /app
Umami  | > node server.js
Umami  | 
Umami  |    ▲ Next.js 15.5.3
Umami  |    - Local:        http://localhost:3000
Umami  |    - Network:      http://0.0.0.0:3000
Umami  |  ✓ Starting...
Umami  |  ✓ Ready in 573ms

二、后续与附录

Umami 镜像

如果你不使用 1Panel 应用商店安装 Umami，需要留意容器镜像名称略有改动：

• umamisoftware/umami:postgresql-v2.19.0
• umamisoftware/umami:3.0.0

数据库工具

相比于终端下改写数据库，为何不直接使用诸如 DataGrip 的工具改写数据库呢？利用 SSH 隧道连接上服务器数据库后，还可以调用本地的 mysqldump 工具导出 SQL 文件。