Uptime-Kuma 数据迁移最佳实践指南

在服务器迁移场景中，Uptime-Kuma 的数据迁移需要特别注意其特殊的存储机制。传统基于 JSON 的备份还原功能已被弃用，开发者推荐采用更可靠的文件系统级迁移方案。

迁移方案选择

当前版本（1.23.13）中，项目已明确弃用内置的备份还原功能。这是由于 JSON 序列化/反序列化过程中存在诸多不可控因素，容易导致数据不一致问题。作为替代方案，建议采用以下两种专业级迁移方式：

1. 完整数据目录迁移
   直接复制整个 data 目录（默认位于应用根目录），这种方式保留了完整的 SQLite 数据库文件和附件资源，确保数据完整性。

2. 数据库导出导入
   对于使用 SQLite 的用户，可采用 .dump 命令生成数据库脚本；MariaDB/MySQL 用户则建议使用官方导出工具。

详细操作指南

文件系统迁移步骤

1. 停止运行中的 Uptime-Kuma 服务
2. 定位数据存储目录（通常包含 database.sqlite 文件）
3. 使用 rsync 或 scp 进行跨服务器传输
4. 执行校验和验证（推荐使用 sha256sum）
5. 在新服务器恢复目录结构
6. 重新启动服务

注意事项

• 迁移过程中建议维护服务停机时间窗口
• 对于 Docker 部署环境，需特别注意 volume 挂载点的实际路径
• 大规模监控配置迁移后，建议逐一验证监控项状态
• 跨版本迁移时需确认数据库兼容性

技术原理说明

Uptime-Kuma 采用 SQLite 作为默认存储引擎，所有配置数据和监控记录都保存在单个数据库文件中。这种设计虽然提升了性能，但也带来了迁移时的特殊要求：

1. 原子性保证：直接复制数据库文件比逐条导出更能保证事务完整性
2. 外键约束：关联数据在导出过程中容易丢失约束关系
3. 文件锁机制：运行时迁移可能导致数据库损坏

对于生产环境，建议建立定期备份机制，将 data 目录纳入常规备份计划。通过结合文件系统快照和数据库导出工具，可以构建多层次的灾备方案。