Umami 3.0版本升级指南，平滑迁移，无需数据库命令

Posted on Feb 11, 2026

🔎 如果全新安装，请跳转至不依靠 1Panel 安装 Umami。

前言

官方升级教程如下 点击此处

本机环境如下，使用1panel v2.0面板，debian12，mysql升级到PostgreSQL

⚠️ 注意： 请提前做好数据库备份。

安装旧版V2.19的PostgreSQL版本的umami

首先安装v2.19的PostgreSQL版本的umami，正常安装即可，只需成功启动就可以将容器停止，1panel中如下图

转移数据库操作

打开数据库软件，如DBeaver ，Navicat等，本文使用的是DBeaver，第一个为mysql的umami，第二个为PostgreSQL的umami，

官方升级指南中提到Truncate the tables below. These tables will be populated from the MySQL import.
truncate table "_prisma_migrations";
truncate table "user"

此意为

  1. 删除表中的所有行（所有数据）
  2. 保留表结构（列定义、索引、约束等）
  3. 类似于 DELETE FROM table_name，但更快且不可回滚
  4. 会重置表的自增序列（如果有）
DBeaver会自动Truncate（截断）,所以无需关注官方升级指南中的内容

在表映射选项中，目标容器为PostgreSQL的umami

在数据加载设置中会弹出是否截断数据，选择是即可，然后一路向下在确认选项中选择继续，等待数据库复制完毕，数据较大的话复制时间较长，请耐心等待

升级v3.0的umami

卸载v2旧版本umami

此处推荐读者卸载v2版本的umami，请注意，在1panel面板中，卸载应用默认选择删除数据库，请取消勾选

安装v3新版本umami

安装时选择3.0版本及以上即可，数据库服务默认只有PostgreSQL，数据库名和数据库用户和用户密码安装v2.19的PostgreSQL版本的umami安装时所写即可，至此全部结束

不依靠1panel安装umami

创建一个docker-compose.yml,创建并填入以下内容后输入docker compose up -d或docker-compose up -d

services:
  # umami 服务配置
  umami:
    # 使用的镜像：从 Docker Hub 拉取 umamisoftware/umami 的最新版本
    image: umamisoftware/umami:latest
    # 容器运行后的名称
    container_name: umami
    # 重启策略：除非手动停止，否则容器退出时自动重启
    restart: unless-stopped
    # 端口映射：将宿主机的 127.0.0.1:3011 映射到容器的 3000 端口
    # 127.0.0.1 限制仅本机可访问，避免直接暴露服务到公网
    ports:
      - 127.0.0.1:3011:3000
    # 环境变量配置
    environment:
      # 数据库连接 URL，格式：postgresql://用户名:密码@主机:端口/数据库名
      # 请替换 username、password 为实际值，127.0.0.1:5432 为宿主机 PostgreSQL 地址
      DATABASE_URL: postgresql://username:password@127.0.0.1:5432/umami
      # 数据库类型，固定为 postgresql
      DATABASE_TYPE: postgresql
      # APP_SECRET 在此版本实际不起作用，仅为占位
      # APP_SECRET: umami_h6p5Nr
    # 健康检查配置：定期检测服务是否存活
    healthcheck:
      # 检测命令：通过 curl 请求容器内的心跳接口
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      # 每 5 秒检测一次
      interval: 5s
      # 单次检测超时时间 5 秒
      timeout: 5s
      # 连续失败 5 次后标记为不健康
      retries: 5
    # 以下是加入 1Panel 已存在网络的方法，一般无需使用
    # 如果 umami 需要与 1Panel 管理的其他容器通信，可取消注释并配置
    #networks:
    #  - 1panel-network  # 加入 1panel 创建的外部网络

# 声明网络（如使用上述 networks 配置则需要取消注释）
#networks:
  #1panel-network:
    #external: true  # 使用已存在的外部网络，不由当前 compose 创建

总结

umami3.0带来了许多改进和新特性，特别是解决安全问题，旧mysql版只需安照上述更新流程即可，常见问题询问ai即可解决，只要做好备份，一般而言不会有大问题。