Umami v3 发布全面迁移 PostgreSQL 升级与数据迁移指南

Umami v3 正式发布了！
这次更新标志着 Umami 在性能和扩展性上的重大飞跃，告别 MySQL，全面拥抱 PostgreSQL。这不仅是数据库的迁移，更是一次全方位提升，旨在为用户带来更高效、更稳定的分析体验。
你可能正在为如何顺利完成从 v2 到 v3 的升级而头疼，不用担心！本指南将带你一步步完成 数据库迁移，确保数据无损、系统无缝过渡，让你轻松掌握所有关键细节。准备好迎接更强大的 PostgreSQL 支持，一起解锁 Umami v3 的全新功能吧！

全面理解 Umami v3 正式发布

Umami v3 正式发布，对我们这些依赖 隐私友好型网站分析（privacy-focused web analytics） 的团队来说，是一次真正意义上的「大版本跃迁」。这一版的核心变化，可以用三句话概括：彻底告别 MySQL、全面拥抱 PostgreSQL、性能与可维护性全面升级。

v3 核心更新与亮点功能

在 Umami v3 中，我们重点围绕「性能、可靠性、开发体验」做了系统级升级：

• 数据库层全面切换为 PostgreSQL
  • 原生支持复杂查询与统计逻辑
  • 在高并发、长周期数据分析场景下更加稳定
  • 更适合未来功能的扩展与数据建模
• Umami v3 新功能与体验优化（示例）
  • 更快的仪表盘加载与报表生成
  • 改进的事件追踪（Umami event tracking）与转化分析
  • 更精细的权限、站点与团队管理能力
  • 更一致且清晰的配置方式，便于在生产环境标准化部署
• 更贴合合规与隐私需求
  • 不依赖第三方广告生态，专注自托管与数据控制
  • 更适合在美国本地化、自建合规环境中使用

重大变更：告别 MySQL，转向 PostgreSQL

Umami v3 最大的 breaking change，就是：

不再支持 MySQL，仅支持 PostgreSQL。

这意味着：

• 现有基于 MySQL 的 Umami 部署，必须进行数据库迁移（MySQL to PostgreSQL migration） 才能升级到 v3
• 旧版本的 MySQL 数据库结构与查询逻辑，不能直接复用，需要进行 PostgreSQL schema conversion（模式转换）
• 所有部署脚本、Docker 配置、运维规范，都要以 PostgreSQL 为唯一数据库后端 进行调整

虽然这是一次硬切换，但它解决了很多长期困扰我们的现实问题：跨版本兼容性、统计查询复杂度限制、性能瓶颈、以及 MySQL 与 PostgreSQL 之间反复兼容的维护成本。

全面拥抱 PostgreSQL 的关键收益

选择 PostgreSQL 集成（Umami analytics PostgreSQL），本质上是在为未来买单，而不是为过去妥协。具体收益包括：

• 更强的分析性能
  • 对复杂聚合、窗口函数、时间序列查询支持更好
  • 数据量提升后，报表与统计依然保持可接受的响应速度
• 更可靠的数据一致性与事务能力
  • 对关键业务事件数据（如转化、漏斗）记录更加严谨
  • 降低数据错乱、统计不准的风险
• 更现代的生态与运维工具
  • 与主流云厂商（如 AWS RDS for PostgreSQL）深度兼容
  • 方便使用成熟的备份、监控、调优工具
  • 配合 Docker 与 Kubernetes，形成标准化的生产部署方案（Umami Docker deployment）
• 更适合长期演进的架构
  • 新增功能（例如复杂维度分析、自定义事件属性）可以自然落在 PostgreSQL 的强大特性之上
  • 减少为兼容多种数据库而牺牲架构设计的情况

对我来说，Umami v3 的这次升级，就是用一次性的迁移成本，换取未来几年的 性能上限、可维护性和产品进化空间。如果你正在寻找一个可在美国市场自托管、支持隐私合规、并能长期演进的分析工具，这一版的方向是非常清晰且值得跟进的。

升级前准备：搞清现状再动手

在动手升级到 Umami v3、完成 MySQL 向 PostgreSQL 迁移 之前，我会先把基础工作做扎实，否则线上一出问题，成本很高。

1. 评估现有环境和 MySQL

步骤化迁移指南

从 MySQL 导出数据

在迁移到 PostgreSQL 之前，首先需要从 MySQL 中导出所有相关数据。使用 MySQL 的 mysqldump 工具可以轻松导出数据库结构和数据。确保导出文件格式为 SQL 文件，以便后续的导入操作。

模式转换的考虑与工具

MySQL 与 PostgreSQL 在数据类型和表结构上存在一些差异，因此需要进行模式转换。这一步至关重要，可以使用开源工具如 pg_loader 来帮助自动化模式转换。通过工具处理，可以减少人工干预，确保转换后的数据结构在 PostgreSQL 中正常工作。

数据导入到 PostgreSQL

一旦完成模式转换，下一步是将数据导入 PostgreSQL。使用 PostgreSQL 自带的 psql 工具，可以将导出的 SQL 文件轻松导入到新的数据库中。在导入过程中，要特别注意字段类型和约束条件是否已正确迁移，以避免数据丢失或异常。

处理 Umami 特定数据与验证

Umami 特有的数据（如跟踪事件、用户设置等）在迁移时需要特别留意。确保这些数据的完整性和正确性，可以通过 Umami 的内置验证功能进行检测。验证过程中，检查每个表的数据是否准确映射，并确保没有遗漏任何重要信息。

升级 Umami 应用

对于 Umami v3，您可以选择 Docker 部署方式或手动安装路径。

Docker 部署

• 使用 PostgreSQL 镜像部署 Umami 应用是最简单的方式。您可以直接拉取官方的 Docker 镜像并配置 PostgreSQL 数据库。
• 在 Docker 环境中，确保 PostgreSQL 的配置与 Umami v3 的要求相匹配。通过修改 docker-compose.yml 文件来调整数据库连接和其他必要配置。

手动安装

• 如果您倾向于手动安装，可以根据官方文档执行安装步骤，确保所有依赖项、环境变量和 PostgreSQL 配置都得到正确设置。
• 手动安装时，特别注意数据库连接的参数，确保与 PostgreSQL 完全兼容。

集成新特性

• 升级到 Umami v3 后，确保所有新特性（如增强的数据追踪功能）都已正确集成，并进行适当配置。
• 例如，您可以配置新的事件追踪设置，确保数据分析与报告功能正常工作。

配置 PostgreSQL

• PostgreSQL 配置是升级过程中的关键步骤。需要根据 Umami 的需求调整数据库的连接池大小、日志级别等配置，确保系统在高负载下的性能和稳定性。

通过以上步骤，您可以顺利完成 Umami v3 的升级和配置，充分利用 PostgreSQL 带来的性能提升和新特性。

Umami v3 升级后性能优化与运维要点

利用 PostgreSQL 工具做性能调优

在完成 Umami v3 升级并迁移到 PostgreSQL 后，我第一步会先盯紧性能：

• 开启并定期跑 VACUUM (ANALYZE)，保持统计信息准确，避免查询计划变慢
• 对访问量巨大的统计表（如 pageview、event）按时间做 分区或归档，减小活跃数据量
• 使用 EXPLAIN ANALYZE 分析慢查询，适当增加索引（例如对 website_id、created_at 等字段建组合索引）
• 合理调整 PostgreSQL 核心参数：
  • shared_buffers：一般设为总内存的 25% 左右
  • work_mem：适度提高，避免大量临时磁盘排序
  • max_connections：配合连接池控制并发，而不是一味拉满

对需要处理跨境收款、结算类流水分析的业务，可以把埋点数据与已有的财务交易分析系统结合起来，用同一个 PostgreSQL 集群做统一查询，减少系统拆分带来的性能损耗。

安全加固最佳实践

Umami v3 用 PostgreSQL 后，数据库就是资产中枢，我会重点做这些安全动作：

• 为 Umami 单独创建 PostgreSQL 用户，只授予最小权限（最小化授权原则）
• 强制使用强密码与 TLS 加密连接，避免明文凭证在网络中流转
• 禁止公网直接访问数据库，只允许通过内网或 VPN 访问
• 定期备份并做 恢复演练，确认在故障或攻击后可以快速拉起新实例
• 记录数据库审计日志，关注异常登录、异常写入等行为

监控与日常维护

想让 Umami v3 长期稳定跑下去，监控必须是默认开启项：

• 核心监控指标：
  • CPU、内存、磁盘 I/O、连接数
  • 查询延迟、慢查询数量
  • 数据库大小与单表大小增长趋势
• 建议接入 Prometheus + Grafana 或类似 SaaS 监控服务，做可视化大盘
• 设定阈值告警（如连接数接近上限、磁盘使用率 > 80% 等），通过邮件或企业 IM 实时通知

面向增长的扩展策略

当网站流量持续提升，Umami v3 + PostgreSQL 也要提前规划扩展路线：

• 纵向扩展：
  • 升级数据库服务器配置（CPU、内存、SSD），这是最简单粗暴也最见效的方式
• 水平扩展：
  • 前端多实例部署（多 Umami 应用容器）+ 统一 PostgreSQL 后端
  • 使用连接池（如 pgbouncer）降低单库连接压力
  • 对历史数据做冷/热分离，把长期不常查询的埋点数据迁移到只读库或归档库
• 读写分离：
  • 对后台报表、历史分析类查询，可以挂到从库上跑，主库专注写入

只要性能调优、监控和扩展策略打好基础，Umami v3 在 PostgreSQL 上完全可以支撑中大型网站的隐私友好型分析需求，升级成本一次投入，后面就是长期复利。

Umami v3 升级常见问题排查（MySQL 到 PostgreSQL）

常见迁移坑与解决方案

字符集与编码错误（乱码、报错）

• 现象：导入 PostgreSQL 时出现编码错误，或事件数据、URL 出现乱码。
• 排查要点：
  • 确认 MySQL 导出使用 utf8mb4。
  • PostgreSQL 数据库与连接统一为 UTF8。
  • 导出命令中明确加上 –default-character-set=utf8mb4。
• 解决方法：重新导出一份干净的 MySQL 数据，确保整个链路都是 UTF-8。

常见问题

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

总结

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