1Panel：Umami v2升级v3记录

前几天主包打开Umami查看近期访问数据的时候，收到v3版本的升级提示了。但奇怪的是1Panel一直没有推送更新，后来去社区看了才知道v2→v3的过程有破坏性更新（数据库强制切换到PostgreSQL了），所以官方就不支持大版本升级了。

查看了 Umami 官方提供的迁移指南，大概内容是教用户先手动导出Mysql数据，然后安装PostgreSQL版的 Umami 2.19.0 并执行数据导入。本身整个迁移过程就有点复杂，再加上 1Panel 还需要额外的卸载重装应用，就更麻烦了。

但我之前已经尝试过手动迁移mysql→sqlite了👌，这次升级挑战倒还有些兴奋。整个迁移过程我演练了两三次，中途有遇到一些问题但都解决了。下面是我整理的最终迁移方案。

一、升级前准备工作

1. 在 1Panel 上提前安装v3版本所需的PostgreSQL数据库应用；

2. 提前拉取相关的docker镜像（实时拉取镜像耗时太久了，先把镜像下好再执行转换、升级过程，可以减少Umami停机时间）

• ghcr.io/umami-software/umami:postgresql-v2.19.0（官方推荐的迁移版本）
• ghcr.io/umami-software/umami:3.1（v3最新版）

3. 在 1Panel 面板打开 Umami 容器的配置页，记录下图中标红的字段值（HTTP端口 和 哈希盐）；

二、导出兼容PostgreSQL的数据文件

1. 在云服务器的Mysql容器中执行数据库备份导出命令（❗ 我强烈推荐设置out_dir位置为/var/lib/mysql，因为这个文件夹被挂载到了主机目录，可以通过 1Panel 面板的 系统 → 文件 快速复制到其他位置）；

1
2
3
4
5
6
7

# username 数据库用户
# dbname   Umami的数据库名称
# out_dir  导出目录，我推荐使用/var/lib/mysql目录
mysqldump --no-create-info --default-character-set=utf8mb4 --quick --skip-add-locks \
-u [username] -p [dbname] > [out_dir]/umami_mysql_v2.sql

# 之后需要回车输入[username]账户对应的密码

2. 对导出的umami_mysql_v2.sql执行文本替换工作，以兼容 PostgreSQL 数据库；

1
2
3
4
5
6
7
8
9

# [out_dir] 自行替换为你设置的目录，我推荐使用/var/lib/mysql目录

# umami官方提供的转换语句
sed -i 's/`/"/g' [out_dir]/umami_mysql_v2.sql

# 我额外增加的转换语句，因为我遇到了下面这个报错
# ERROR:  syntax error at or near "newWindow"
# LINE 1: ...26d','error','null is not an object (evaluating \'newWindow....
sed -i "s/\\\'/''/g" [out_dir]/umami_mysql_v2.sql

3. 在映射的目录能找到umami_mysql_v2.sql文件，就代表上述步骤已经正确执行了；

三、安装PostgreSQL版的Umami应用，并导入数据

1. 在确认umami_mysql_v2.sql已经创建好的情况下，卸载Mysql版本的Umami应用（因为已经备份过数据库了，删不删数据库都可以；我的建议是先别删数据库，等整个迁移完成后再处理！）；

2. 在 1Panel 安装全新的umami:postgresql-v2.19.0应用，并记录下创建时的表名和数据库用户名（即使没记住也没关系，在 1Panel 后台的 数据库 → PostgreSQL 也可以看到以umami开头的数据库）；

3. 在 1Panel 中打开 PostgreSQL 容器的终端，执行清表命令；

1
2
3
4

psql -U [username] -d [dbname] -c '
TRUNCATE TABLE "_prisma_migrations" CASCADE;
TRUNCATE TABLE "user" CASCADE;
'

4. 复制之前的umami_mysql_v2.sql文件到 1Panel 的/opt/1panel/apps/postgresql/postgresql/data目录（后续在容器里打开/var/lib/postgresql目录，就可以看到复制过来的umami_mysql_v2.sql）

5. 再次打开 1Panel 的PostgreSQL容器，执行导入命令；

1
2
3
4

# 访问挂载目录
cd /var/lib/postgresql
# 执行合并命令
psql -U [username] -d [dbname] < umami_mysql_v2.sql

6. 记录下 Umami 2.19.0 应用的相关配置参数，然后卸载应用（记住不要勾选删除数据库！）

7. 在1Panel 应用中心安装 Umami 的v3版本，相关配置沿用刚记录的Umami 2.19.0版本的配置；

8. 等待v3版本的 Umami 运行数据库迁移脚本，只要刚才没有勾选“删除数据库”，它就会连接原有数据库并更新表结构。

运行完成后就可以访问网站了，如果遇到以下问题：

1. 登录页面点击登录提示Failed to execute 'json' on 'Response': Unexpected end of JSON input；
2. 登录成功后/dashboard页面白屏，F12控制台出现Error: Failed to find Server Action之类的JS报错信息；
3. 容器日志中也出现Error: Failed to find Server Action等错误日志

则可以按下列步骤尝试，应该能解决问题。

1. Ctrl+F5强制刷新网页；
2. 重启 umami 容器，等待启动完成后再访问；
3. 如果容器开启了反向代理，则清理一下反向代理缓存；

四、效果展示

现在，Umami版本成功升级到了 v3.1.0，所有功能正常，所有数据完整，这是我第一次手搓处理 1Panel 应用升级，回过头看还感觉有点刺激😂。又在线上安静得跑了两天 Umami 应用，全程没任何问题，我才最终删除了Mysql数据库和相应的容器（不得不提PostgreSQL相比Mysql内存占用小多了，只有它的一半👍）。