数据备份与恢复

备份前了解范围

当前一致性物理备份适用于随实例部署的 MySQL 和 MinIO，包含私有配置、数据库、对象存储、工作空间源码、本地数据及 TLS 文件。外部数据库或外部对象存储应使用服务商的一致性备份机制。

备份会短暂停止生产服务，归档校验后重新启动。请安排在低峰期，并把副本保存到另一台服务器或独立存储。同盘副本不能防止整机或磁盘损坏。

配置 S3 兼容存储

由 system 管理员进入 系统设置 → 数据备份，新增或编辑配置。

字段	填写内容
Bucket	用于备份的存储桶；七牛云填写其 S3 空间名
Region	存储服务商提供的 S3 区域代码
Endpoint	S3 API 地址，不是网站地址，不附带桶名或目录；AWS S3 可留空
目录前缀 Prefix	备份专用目录，例如 kageos-backups，用于隔离文件与过期清理范围
访问凭证	对指定存储位置有上传、读取、列出和删除权限的专用凭证

点击“测试连接”会上传、读取并删除小对象，不会保存配置。测试通过后保存，配置每日时间和保留期，按需启用自动备份。

确认任务真的完成

宿主机执行器负责备份任务，生产安装的 timer 每五分钟检查一次计划。自动备份默认关闭，保存启用后才会按计划执行。

“立即备份”使用已保存配置；需要计划已启用且宿主机执行器就绪。查看执行结果，确认归档、重启验证和上传均完成。连接测试成功不代表完整备份已经成功。

手动备份与校验

源码部署在仓库根目录使用部署用户执行：

go run ./cmd/kagectl backup --output /mnt/kageos-backups
go run ./cmd/kagectl backup list
go run ./cmd/kagectl backup verify /mnt/kageos-backups/kageos-backup-20260923T020000Z.tar.gz

输出目录必须位于数据根目录之外。归档包含恢复密钥与业务数据，应限制访问。backup list 默认列出默认备份目录；自定义目录使用完整路径校验。

恢复前先做预检

go run ./cmd/kagectl restore /mnt/kageos-backups/kageos-backup-20260923T020000Z.tar.gz --dry-run

预检校验归档并检查镜像版本，不停止服务、不写入数据。恢复目标必须匹配备份中的平台、用户应用基础、MySQL 和 MinIO 镜像版本，并留出新旧两份数据的空间。

实际恢复需要显式 --force，会替换当前实例数据。先保留当前备份，核对目标实例、归档和预检结果，再由负责该实例的管理员执行。详细流程见源码备份与恢复说明。