Umami 3.0 升级教程：从 v2 平滑迁移

前言

这是一份关于如何将已部署的 Umami 统计系统更新到 3.0 版本的详细教程。如果你是按照我之前的

更新前的准备

1. 备份数据库

在进行任何更新操作之前，强烈建议先备份数据库数据，以防万一出现问题可以快速回滚。

# 进入到 Umami 目录
cd /www/wwwroot/visitors.ybyq.wang/umami

# 备份数据库数据
docker-compose exec db pg_dump -U umami umami > umami_backup_$(date +%Y%m%d_%H%M%S).sql

备份文件会保存在当前目录下，文件名包含时间戳，方便识别。

2. 记录当前版本

查看当前运行的 Umami 版本，以便后续确认更新是否成功：

docker-compose exec umami cat /app/package.json | grep version

更新步骤

1. 进入项目目录

cd /www/wwwroot/visitors.ybyq.wang/umami

2. 停止当前运行的容器

docker-compose down

这个命令会停止并删除容器，但不会删除数据卷，你的统计数据是安全的。

3. 拉取最新代码

我已经同步了官方最新版本到 Gitee仓库，现在直接拉取更新：

git pull origin master

如果提示有本地修改冲突，可以先备份 docker-compose.yml 文件：

cp docker-compose.yml docker-compose.yml.backup

然后强制拉取：

git fetch --all
git reset --hard origin/master

之后再恢复你的配置文件：

cp docker-compose.yml.backup docker-compose.yml

4. 检查配置文件

Umami 3.0 可能会有一些配置变化，检查 docker-compose.yml 文件是否需要更新。

主要关注以下配置：

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-3.0.0
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:你的密码@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: 你的随机字符串
    depends_on:
      db:
        condition: service_healthy
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: 你的密码
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  umami-db-data:

确保你的数据库密码等配置信息保持一致。

5. 拉取最新镜像

docker-compose pull

这个命令会从 Docker Hub 拉取最新的 Umami 镜像，可能需要很长时间，请耐心等待。

6. 重新启动服务

docker-compose up -d

容器会自动完成数据库迁移和服务启动。

7. 查看容器状态

docker-compose ps

确保所有容器都处于 Up 状态。

8. 查看日志

如果容器启动失败，可以查看日志排查问题：

# 查看 Umami 容器日志
docker-compose logs -f umami

# 查看数据库容器日志
docker-compose logs -f db

按 Ctrl + C 退出日志查看。

验证更新

1. 检查版本号

访问你的 Umami 网站，登录后台，在设置页面可以看到当前版本号。

或者使用命令查看：

docker-compose exec umami cat /app/package.json | grep version

Umami 3.0 新特性

Umami 3.0 带来了许多改进：

• 全新的 UI 设计：更现代化的界面，更好的用户体验
  
• 性能优化：查询速度更快，页面加载更流畅

• 新增功能：

  • 改进的事件追踪
  • 更强大的过滤器
  • 自定义报告功能
  • API 增强
• 安全性提升：修复了已知的安全漏洞

详细更新日志可以查看 Umami 官方发布说明。

常见问题

1. 更新后无法启动

症状：执行 docker-compose up -d 后容器自动停止

解决方法：

# 查看详细日志
docker-compose logs umami

# 如果是数据库连接问题，检查 DATABASE_URL 配置
# 如果是数据库迁移失败，可以尝试手动执行迁移
docker-compose exec umami npm run db-migrate

2. 数据丢失

症状：更新后统计数据消失

解决方法：

# 检查数据卷是否存在
docker volume ls | grep umami

# 如果数据卷存在，检查数据库连接
docker-compose exec db psql -U umami -d umami -c "SELECT COUNT(*) FROM website;"

# 如果需要恢复备份
docker-compose exec -T db psql -U umami -d umami < umami_backup_你的备份文件.sql

3. 端口冲突

症状：提示 3000 端口已被占用

解决方法：
修改 docker-compose.yml 中的端口映射：

ports:
  - "3001:3000"  # 将宿主机端口改为 3001

然后更新宝塔反向代理配置，将目标地址改为 http://127.0.0.1:3001。

4. 镜像拉取失败

症状：docker-compose pull 时下载很慢或失败

解决方法：

• 首先确认镜像标签是否正确。Umami 官方不提供 latest，常用为按数据库区分的标签：

  • Postgres：ghcr.io/umami-software/umami:postgresql-latest
  • MySQL：ghcr.io/umami-software/umami:mysql-latest
  • 常见拼写错误：postgresgl-latest（少了 q）会导致 manifest unknown

• 可配置 Docker 镜像加速，或固定到明确版本：

  image: ghcr.io/umami-software/umami:postgresql-v3.0.0  # 指定具体版本

5. Docker 网络错误（iptables/DOCKER 链）

症状：failed to create network ... Error response from daemon: Failed to Setup IP tables: Unable to enable SKIP DNAT rule: ... iptables: No chain/target/match by that name.

解决方法（依次尝试）：

# 1) 重建 Docker 的 iptables 链并清理网络
docker-compose down
sudo systemctl restart docker
docker network prune -f
docker-compose up -d

# 2) 若仍失败，切到 iptables-legacy（按发行版选择其中一组命令）
# Debian/Ubuntu
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
# CentOS/Alibaba Linux
# sudo alternatives --set iptables /usr/sbin/iptables-legacy
# sudo alternatives --set ip6tables /usr/sbin/ip6tables-legacy
sudo systemctl restart docker
docker-compose up -d

# 3) 仍不行，确保内核模块已加载
sudo modprobe ip_tables iptable_nat
sudo systemctl restart docker
docker-compose up -d

回滚操作

如果更新后出现严重问题，可以回滚到之前的版本：

1. 停止容器

docker-compose down

2. 恢复代码

# 查看之前的提交记录
git log --oneline

# 回退到之前的版本（替换 commit_id）
git reset --hard <之前的commit_id>

3. 恢复数据库（如果需要）

# 启动数据库容器
docker-compose up -d db

# 等待数据库启动
sleep 10

# 恢复备份
docker-compose exec -T db psql -U umami -d umami < umami_backup_你的备份文件.sql

4. 重新启动服务

docker-compose up -d

总结

Umami 3.0 带来了许多改进和新特性，更新过程相对简单。只要做好备份，按照步骤操作，一般不会遇到大问题。如果遇到问题，可以参考常见问题部分，或在评论区留言交流。

参考链接

• Umami GitHub 仓库
• Umami 官方文档
• Umami 3.0 发布说明
• Docker Compose 文档