Fathom Lite数据库迁移最佳实践：零停机
项目地址: https://gitcode.com/gh_mirrors/fa/fathom 你是否曾因数据库迁移导致网站分析服务中断而烦恼？Fathom Lite作为一款注重隐私的网站分析工具，其数据连续性对业务监控至关重要。本文将详细介绍如何在不中断服务的情况下完成数据库结构升级，确保用户访问数据零丢失、分析服务零停机。读完本文后，你将掌握基于Golang后端的数据库平滑迁移全流程，包括迁移前准备、无停机执行步骤、异常回滚方案以及自动化迁移脚本编写。
迁移前的关键准备工作
在开始数据库迁移前，必须完成三项核心准备工作，这是确保零停机迁移的基础。首先需要备份现有数据，Fathom Lite使用SQLite/PostgreSQL/MySQL作为数据存储，不同数据库的备份命令略有差异。以PostgreSQL为例，使用pg_dump命令创建完整备份：
pg_dump -U username -d fathom > fathom_backup_$(date +%Y%m%d).sql
其次，需要检查当前Fathom版本与目标版本的迁移差异。通过阅读官方更新文档docs/Updating to the latest version.md，了解版本间的架构变化和迁移要求。特别注意数据库结构变更部分，例如从旧版本升级到支持多站点统计的新版本时，需要添加site_id字段到多个统计表格。
最后，准备迁移所需的工具和资源。确保系统中安装了与数据库类型匹配的迁移工具，如PostgreSQL的psql客户端或MySQL的mysql命令行工具。同时，下载最新版本的Fathom二进制文件，并存放在临时目录中：
wget https://gitcode.com/gh_mirrors/fa/fathom/releases/latest/download/fathom_linux_amd64.tar.gz -O /tmp/fathom_new.tar.gz
零停机迁移实施步骤
零停机迁移的核心在于采用"双写+切换"策略，通过创建临时表、并行写入、数据同步和流量切换四个步骤实现无缝迁移。这种方法已在Fathom Lite的官方迁移脚本中得到验证，如postgres/20_alter_referrer_stats_table.sql所示。
步骤一：创建新结构临时表
首先创建与目标结构一致的临时表，避免直接修改生产环境表结构。以访问来源统计表格daily_referrer_stats为例，官方迁移脚本通过重命名旧表并创建新表实现结构变更：
-- 重命名旧表为临时表
ALTER TABLE daily_referrer_stats RENAME TO daily_referrer_stats_old;
-- 创建符合新结构的表
CREATE TABLE daily_referrer_stats(
site_id INTEGER NOT NULL DEFAULT 1,
hostname_id INTEGER NOT NULL,
pathname_id INTEGER NOT NULL,
groupname VARCHAR(255) NULL,
pageviews INTEGER NOT NULL,
visitors INTEGER NOT NULL,
bounce_rate FLOAT NOT NULL,
known_durations INTEGER NOT NULL DEFAULT 0,
avg_duration FLOAT NOT NULL,
date DATE NOT NULL
);
步骤二：配置双写机制
修改Fathom Lite的API服务代码，使其同时向旧表和新表写入数据。这一步需要修改数据写入逻辑，以datastore/sqlstore/referrer_stats.go中的统计数据保存函数为例，添加对新表的写入操作：
// 伪代码示例：双写实现
func SaveReferrerStats(ctx context.Context, stats []*models.ReferrerStats) error {
// 写入旧表（保持原样）
if err := saveToOldTable(ctx, stats); err != nil {
return err
}
// 同时写入新表（新增逻辑）
return saveToNewTable(ctx, stats)
}
步骤三：同步历史数据
使用INSERT INTO ... SELECT语句从旧表向新表同步历史数据。官方迁移脚本采用LEFT JOIN方式关联外部表数据，确保数据完整性：
INSERT INTO daily_referrer_stats
SELECT
site_id,
h.id, -- 关联新的hostname_id
p.id, -- 关联新的pathname_id
groupname,
pageviews,
visitors,
bounce_rate,
known_durations,
avg_duration,
date
FROM daily_referrer_stats_old s
LEFT JOIN hostnames h ON h.name = s.hostname
LEFT JOIN pathnames p ON p.name = s.pathname;
数据同步过程中，可以通过监控以下指标确认同步进度：
- 已同步记录数与总记录数的比例
- 同步速率（条/秒）
- 新表与旧表的统计数据差异（如总访问量、独立访客数）
步骤四：切换读写流量
完成历史数据同步后，分两步切换流量：首先将读操作切换到新表，验证数据一致性；确认无误后，再将写操作切换到新表并移除双写逻辑。以Fathom Lite的配置文件修改为例：
# 迁移前配置
database:
tables:
referrer_stats: daily_referrer_stats_old
# 读操作切换后
database:
tables:
referrer_stats: daily_referrer_stats # 读取新表
referrer_stats_old: daily_referrer_stats_old # 保留旧表写入
# 写操作切换后（最终配置）
database:
tables:
referrer_stats: daily_referrer_stats # 读写新表
迁移验证与回滚方案
完成迁移后，需要从数据完整性、业务连续性和性能三个维度进行验证。数据完整性可通过对比新旧表的关键指标总和来确认，例如：
-- 验证总访问量是否一致
SELECT SUM(pageviews) FROM daily_referrer_stats;
SELECT SUM(pageviews) FROM daily_referrer_stats_old;
业务连续性验证需检查Fathom Lite的核心功能是否正常工作，包括：
- 实时访问数据是否正常显示在dashboard.js页面
- 历史趋势图表能否正确加载
- API接口api/referrer_stats.go返回数据是否完整
性能验证重点关注查询响应时间，特别是添加索引后的新表查询效率。Fathom Lite的迁移脚本通常会在数据同步后添加必要索引：
-- 添加索引提升查询性能
CREATE INDEX idx_referrer_stats_date ON daily_referrer_stats(date);
CREATE INDEX idx_referrer_stats_site_id ON daily_referrer_stats(site_id);
若验证过程中发现问题，需要执行回滚操作。回滚方案分为紧急回滚和计划回滚两种：
紧急回滚步骤：
- 将读操作切换回旧表
- 停止新表写入，仅保留旧表写入
- 恢复API服务配置到迁移前状态
计划回滚步骤：
- 通知用户服务将有短暂维护
- 停止Fathom Lite服务
- 执行数据回滚SQL脚本
- 启动服务并验证
自动化迁移脚本编写
为简化迁移流程，可基于Fathom Lite的CLI工具编写自动化迁移脚本。参考cli/server.go的命令结构，添加自定义迁移命令：
// 在main.go中注册迁移命令
func main() {
app := cli.NewApp()
app.Commands = []cli.Command{
// 现有命令...
{
Name: "migrate-db",
Usage: "Perform zero-downtime database migration",
Action: func(c *cli.Context) error {
return runMigration(c)
},
},
}
// ...
}
完整的自动化脚本应包含以下功能模块：
- 参数解析（数据库类型、地址、用户名等）
- 备份功能（自动调用pg_dump/mysqldump）
- 迁移执行（按步骤执行SQL脚本）
- 验证功能（自动对比关键指标）
- 回滚触发（发现异常时自动执行回滚）
以下是一个Bash自动化脚本示例，结合Fathom Lite的官方更新流程：
#!/bin/bash
set -e
# 配置参数
BACKUP_DIR="./backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/fathom_$TIMESTAMP.sql"
# 创建备份
mkdir -p $BACKUP_DIR
echo "Creating database backup: $BACKUP_FILE"
pg_dump -U fathom_user -d fathom > $BACKUP_FILE
# 执行迁移步骤
echo "Starting migration..."
fathom migrate-db --steps=prepare,double-write,sync,switch,verify
echo "Migration completed successfully!"
迁移案例与最佳实践总结
Fathom Lite的数据库迁移涉及多种场景，包括表结构变更、数据类型调整和索引优化等。以PostgreSQL数据库的数值精度调整为例，10_alter_numeric_column_precision.sql展示了如何修改列类型而不影响服务运行：
-- 调整数值类型精度
ALTER TABLE daily_site_stats ALTER COLUMN bounce_rate TYPE NUMERIC;
ALTER TABLE daily_page_stats ALTER COLUMN bounce_rate TYPE NUMERIC;
ALTER TABLE daily_referrer_stats ALTER COLUMN bounce_rate TYPE NUMERIC;
综合所有迁移场景，总结出以下最佳实践：
-
小步快跑原则：将大型迁移拆分为多个小型变更，如migrations目录中的版本化脚本所示，每个脚本只修改一个表或少量字段。
-
监控先行策略：在迁移前部署数据库性能监控，重点关注api/collect.go中的数据采集接口响应时间，设置告警阈值。
-
灰度发布思想：先在测试环境验证迁移方案，再在生产环境按流量比例逐步切换，如先迁移非核心统计表（如daily_referrer_stats），再迁移核心业务表。
-
文档即代码：迁移完成后，及时更新docs/Configuration.md和docs/FAQ.md，记录迁移后的新配置项和常见问题解决方案。
通过遵循以上实践，你可以像Fathom Lite官方迁移脚本那样，实现对复杂数据库结构变更的无缝管理，确保网站分析服务的持续可用和数据准确。
图：Fathom Lite的数据分析仪表板，迁移后的数据将继续支持此类实时统计功能，不会出现数据断层或服务中断。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
