Umami3.0版本升级教程：从 v2 平滑迁移
前言
这是一份关于如何将已部署的 Umami2.0 统计系统更新到 3.0 版本的详细教程。如果你是按照我之前的 [post cid="381" /]部署的，那么这篇教程将帮助你平滑升级到最新版本。
更新前的准备
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/umami2. 停止当前运行的容器
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.yml4. 检查配置文件
Umami3.0 可能会有一些配置变化，检查 docker-compose.yml 文件是否需要更新。
主要关注以下配置：
[collapse status="false" title="展开查看 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:[/collapse]
确保你的数据库密码等配置信息保持一致。
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 versionUmami 3.0 新特性
Umami3.0 带来了许多改进：
- 全新的 UI 设计：更现代化的界面，更好的用户体验
- 性能优化：查询速度更快，页面加载更流畅
新增功能：
- 改进的事件追踪
- 更强大的过滤器
- 自定义报告功能
- API 增强
- 安全性提升：修复了已知的安全漏洞
详细更新日志可以查看 Umami 官方发布说明。
常见问题
1. 更新后无法启动
症状：执行 docker-compose up -d 后容器自动停止
解决方法：
# 查看详细日志
docker-compose logs umami
# 如果是数据库连接问题，检查 DATABASE_URL 配置
# 如果是数据库迁移失败，可以尝试手动执行迁移
docker-compose exec umami npm run db-migrate2. 数据丢失
症状：更新后统计数据消失
解决方法：
# 检查数据卷是否存在
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_你的备份文件.sql3. 端口冲突
症状：提示 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
- Postgres：
可配置 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 down2. 恢复代码
# 查看之前的提交记录
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_你的备份文件.sql4. 重新启动服务
docker-compose up -d总结
Umami3.0 带来了许多改进和新特性，更新过程相对简单。只要做好备份，按照步骤操作，一般不会遇到大问题。如果遇到问题，可以参考常见问题部分，或在评论区留言交流。
