diff --git a/docs-site/docs/features/multi-node.md b/docs-site/docs/features/multi-node.md
index 93ffdbe..800014f 100644
--- a/docs-site/docs/features/multi-node.md
+++ b/docs-site/docs/features/multi-node.md
@@ -224,6 +224,6 @@ Environment variables: `BACKUPX_AGENT_MASTER`, `BACKUPX_AGENT_TOKEN`, `BACKUPX_A
## Known limitations
- The Master is single-active because it uses embedded SQLite.
-- Encrypted backups are Master-only because Agents do not hold the Master encryption key.
+- Encrypted remote backups require upgrading both Master and Agent. The Agent receives only a record-specific derived key; the Master key stays on the Master. Newly created remote archives can be decrypted by the owning restore Agent or Master. Legacy Master-only BXENC1 archives must be restored on the Master. Back up the Master configuration encryption key: changing or losing it makes previous encrypted backups unreadable. Use HTTPS for Agent traffic.
- Remote directory browsing is a synchronous queue RPC with a 15-second timeout.
- Claimed commands that stop reporting progress are timed out according to the Master command monitor.
diff --git a/docs-site/docs/features/mysql-pitr.md b/docs-site/docs/features/mysql-pitr.md
new file mode 100644
index 0000000..d746218
--- /dev/null
+++ b/docs-site/docs/features/mysql-pitr.md
@@ -0,0 +1,42 @@
+---
+sidebar_position: 5
+---
+
+# MySQL binlog backups and point-in-time recovery
+
+Enable **MySQL binlog / point-in-time recovery (PITR)** in a MySQL task. BackupX creates a whole-instance `mysqldump` baseline, then archives all binary logs since that baseline. Each log archive depends only on its full baseline, not on intermediate backup records. Full baselines are refreshed every 24 hours by default (configurable from 1 to 720 hours).
+
+This is logical full backup plus binlog archiving, not XtraBackup or MariaBackup physical incremental backup. Supported servers are MySQL 8.0 / 8.4; install the MySQL 8.0.26+ `mysql`, `mysqldump` and `mysqlbinlog` clients on the execution node. MariaDB is outside this mode's compatibility scope.
+
+## Setup
+
+- Set the database name to `*`: PITR always includes the whole instance to preserve cross-database transactions.
+- Enable binary logging and use InnoDB. Avoid DDL during the full dump; nontransactional tables are not guaranteed consistent.
+- Use a fixed Master or Agent execution node. Dynamic node pools are unsupported.
+- Configure the task schedule for the required archive frequency. A five-minute schedule normally yields an RPO of approximately five minutes plus execution time.
+- Grant normal dump privileges plus log-position, brief read-lock and replication-read privileges (typically `REPLICATION CLIENT`, `REPLICATION SLAVE`, and `RELOAD`; consult your server version). Restore requires whole-instance write privileges and permission to set `sql_log_bin`.
+- Do not reset binary logs, reset GTIDs or reinitialize the source during the recovery window; doing so invalidates old log coordinates.
+- Keep source binlogs longer than the full-backup interval, archive interval and expected outage combined. BackupX does not change source log retention or purge logs. Missing logs, numbering gaps and changed server identity fail the archive. After correcting retention, wait for the next periodic full dump or create a new PITR task.
+- Compression, multiple storage targets, retention and encryption use the normal task controls. Remote encryption requires upgrading both Master and Agent. Protect Agent-to-MySQL connections with a trusted network or database TLS tunnel.
+
+The default Alpine Docker image supplies the MariaDB-compatible `mysql-client` package, not Oracle MySQL clients. For PITR, select a fixed Agent with Oracle MySQL 8.0.26+ clients installed, or supply a custom execution image with those tools. The default image's existing full-dump mode is unchanged. See the [Alpine package definition](https://pkgs.alpinelinux.org/package/v3.24/main/x86/mysql-client).
+
+## Restore
+
+Open a successful **MySQL binlog** record and choose Restore. Enter an optional RFC3339 timestamp with a time zone, such as `2026-11-14T12:30:00+08:00`. It must fall between baseline completion and the archive cutoff, excluding the cutoff second. Leave it empty to restore to the captured binary log position.
+
+The UI displays the available interval. Times are converted to UTC; replay uses `mysqlbinlog --stop-datetime`, applying events before the requested second. Subsecond precision is not guaranteed. The window ends at successfully archived logs and excludes later source transactions.
+
+Restore overwrites the **entire instance** currently configured in the task, including system objects and accounts. First point the task at an isolated recovery instance and verify business data. Import is not transactional; failure does not roll back already applied changes. Automated verification is unsupported for PITR; perform regular isolated recovery drills.
+
+The existing `POST /api/backup/records/:id/restore` endpoint accepts an optional `restoreTime` field:
+
+```json
+{"restoreTime":"2026-11-14T12:30:00+08:00"}
+```
+
+Automatic retention and manual deletion protect full baselines while retained binlog records depend on them. Effective retention can therefore exceed the configured maximum count.
+
+## Encryption and upgrades
+
+Agents receive only a record-specific derived key; the Master key stays on the Master. New encrypted remote artifacts use `BXENC2`, authenticating record identity, chunk order and an explicit end marker. Master can still decrypt legacy `BXENC1` archives; restore those legacy archives on Master. Back up the Master configuration encryption key: losing or replacing it makes old encrypted backups unreadable. Key rotation and automatic migration of old keys are not included.
diff --git a/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/multi-node.md b/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/multi-node.md
index 532ff43..3677724 100644
--- a/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/multi-node.md
+++ b/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/multi-node.md
@@ -222,6 +222,6 @@ backupx agent --help
## 已知限制
- Master 使用内置 SQLite,只支持单活。
-- 加密备份仅支持 Master 本机执行,因为 Agent 不持有 Master 加密密钥。
+- 远程加密备份需同时升级 Master 与 Agent。Agent 只获取当前备份记录的派生密钥,Master 主密钥不下发。新远程归档可在获授权的恢复 Agent 或 Master 解密;旧版 Master BXENC1 加密归档仍需在 Master 恢复。请备份 Master 配置加密密钥,丢失或更换会导致旧加密备份不可读。Agent 通信应使用 HTTPS。
- 远程目录浏览是同步队列 RPC,默认超时 15 秒。
- Agent 领取后长期不更新的命令会由 Master 超时监控处理。
diff --git a/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/mysql-pitr.md b/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/mysql-pitr.md
new file mode 100644
index 0000000..9a6e996
--- /dev/null
+++ b/docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/mysql-pitr.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 5
+---
+
+# MySQL 日志增量与指定时间点恢复
+
+MySQL 任务可以开启 **MySQL 日志增量 / 指定时间点恢复(PITR)**。首次和全量间隔到期时创建 `mysqldump` 全实例基线,其间归档**自该基线以来**的原始 binlog。每份日志归档只依赖一份全量,不依赖中间日志备份记录。恢复会自动下载并校验基线与日志,再按顺序应用。
+
+这是逻辑全量加 binlog 的恢复方案,不是 XtraBackup / MariaBackup 物理增量。当前兼容范围为 MySQL 8.0 / 8.4,执行节点需安装 MySQL 8.0.26+ 的 `mysql`、`mysqldump`、`mysqlbinlog` 客户端。MariaDB 不在此模式兼容范围内。
+
+## 配置
+
+1. 新建 MySQL 任务,填写数据库主机、端口和备份账号。
+2. 在策略步骤开启 PITR,数据库名称设为 `*`,表示整个实例。为保证跨库事务正确性,PITR 不提供单库筛选。
+3. 选择固定执行节点(Master 或 Agent);不支持节点池动态切换。
+4. 设置全量间隔,默认 24 小时,可设置 1–720 小时。计划执行频率决定 binlog 的归档间隔。例如每 5 分钟运行一次,正常情况下 RPO 约为 5 分钟加任务耗时。
+5. 配置存储目标、压缩、加密和保留策略。远程加密需要同时升级 Master 和 Agent。
+
+数据库必须开启 `log_bin`,使用 InnoDB。全量期间避免 DDL;非事务表无法保证一致性。备份账号除了常规 mysqldump 所需权限,还需查询日志位置、短暂读取锁和复制读取所需权限(通常包括 `REPLICATION CLIENT`、`REPLICATION SLAVE`、`RELOAD`,实际权限按数据库版本配置)。恢复账号必须拥有创建/覆盖全实例对象及设置 `sql_log_bin` 的权限。请给 Agent 到 MySQL 的网络连接配置可信网络或数据库 TLS 隧道。
+
+恢复窗口内请勿执行 RESET MASTER / RESET BINARY LOGS AND GTIDS 或重新初始化实例;这会使旧日志坐标失效。
+
+源端 binlog 保留期必须大于全量间隔、归档间隔和最大故障恢复时间之和;系统不会修改数据库保留参数,也不会自动清除源端 binlog。源日志被清理、日志编号不连续或服务器 UUID 变化时,本次归档失败,不会伪装成可恢复的备份。修复源端保留策略后,可等待下一次周期性全量,或新建 PITR 任务建立基线。
+
+默认 Alpine Docker 镜像安装的是 MariaDB 兼容的 `mysql-client`,不是 Oracle MySQL 客户端。使用 PITR 时,请选择已安装 Oracle MySQL 8.0.26+ 客户端的固定 Agent,或提供包含这些工具的自定义执行镜像。原有全量备份模式不受影响。参见 [Alpine 包定义](https://pkgs.alpinelinux.org/package/v3.24/main/x86/mysql-client)。
+
+## 恢复
+
+在成功的 **MySQL binlog** 记录详情点击恢复,可输入带时区的 RFC3339 时间,例如 `2026-11-14T12:30:00+08:00`。界面展示本条归档的可恢复范围。时间须在基线完成至日志截止之间,不包含截止秒;留空则恢复到记录捕获的日志位置。
+
+时间统一转换为 UTC,重放使用 `mysqlbinlog --stop-datetime`;它应用目标时间之前的事件,目标秒及其后事件不应用。时间分辨率为秒,不承诺亚秒精度。恢复窗口截至**已成功归档**的日志,不包含归档后的源端事务。
+
+恢复覆盖任务当前配置的**整个实例**,包括数据库与账号等系统对象。建议先把任务连接改到隔离的恢复实例,并实际验收业务数据。恢复不是事务性的,失败不自动回滚已导入的数据。当前不支持自动验证演练,应定期在隔离实例恢复并检查业务结果。
+
+API 使用现有 `POST /api/backup/records/:id/restore`,请求体可增加 `restoreTime`:
+
+```json
+{"restoreTime":"2026-11-14T12:30:00+08:00"}
+```
+
+自动保留和手动删除都会保护仍有日志备份依赖的全量基线,因此实际保留量可能超过最大份数。先删除或过期其日志记录后,基线才能清理。
+
+## 密钥与升级
+
+远程 Agent 仅获取记录专属派生密钥,新远程加密归档采用 `BXENC2`,包含记录身份、分块顺序与完整结束标记的认证。Master 仍可读取旧 `BXENC1` 归档。请保存 Master 配置加密密钥;仅保存备份文件而丢失此密钥无法恢复。该功能不轮换密钥,不自动处理旧主密钥迁移。
diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts
index 52f670c..15cd84e 100644
--- a/docs-site/sidebars.ts
+++ b/docs-site/sidebars.ts
@@ -40,6 +40,7 @@ const sidebars: SidebarsConfig = {
'features/storage-backends',
'features/sap-hana',
'features/sql-server',
+ 'features/mysql-pitr',
'features/multi-node',
'features/notifications',
],
diff --git a/server/internal/agent/client.go b/server/internal/agent/client.go
index 43f2b50..543f924 100644
--- a/server/internal/agent/client.go
+++ b/server/internal/agent/client.go
@@ -1,6 +1,7 @@
package agent
import (
+ "backupx/server/internal/backup"
"bytes"
"context"
"crypto/tls"
@@ -150,22 +151,26 @@ func (c *MasterClient) SubmitCommandResult(ctx context.Context, cmdID uint, succ
// TaskSpec 与 service.AgentTaskSpec 对齐
type TaskSpec struct {
- TaskID uint `json:"taskId"`
- Name string `json:"name"`
- Type string `json:"type"`
- SourcePath string `json:"sourcePath"`
- SourcePaths string `json:"sourcePaths"`
- ExcludePatterns string `json:"excludePatterns"`
- DBHost string `json:"dbHost"`
- DBPort int `json:"dbPort"`
- DBUser string `json:"dbUser"`
- DBPassword string `json:"dbPassword"`
- DBName string `json:"dbName"`
- DBPath string `json:"dbPath"`
- ExtraConfig string `json:"extraConfig"`
- Compression string `json:"compression"`
- Encrypt bool `json:"encrypt"`
- StorageTargets []StorageTargetConfig `json:"storageTargets"`
+ MySQLPITR bool `json:"mysqlPitr"`
+ MySQLBase *backup.MySQLCheckpoint `json:"mysqlBase,omitempty"`
+ BaseRecordID uint `json:"baseRecordId,omitempty"`
+ TaskID uint `json:"taskId"`
+ Name string `json:"name"`
+ Type string `json:"type"`
+ SourcePath string `json:"sourcePath"`
+ SourcePaths string `json:"sourcePaths"`
+ ExcludePatterns string `json:"excludePatterns"`
+ DBHost string `json:"dbHost"`
+ DBPort int `json:"dbPort"`
+ DBUser string `json:"dbUser"`
+ DBPassword string `json:"dbPassword"`
+ DBName string `json:"dbName"`
+ DBPath string `json:"dbPath"`
+ ExtraConfig string `json:"extraConfig"`
+ Compression string `json:"compression"`
+ EncryptionKey string `json:"encryptionKey,omitempty"`
+ Encrypt bool `json:"encrypt"`
+ StorageTargets []StorageTargetConfig `json:"storageTargets"`
}
// StorageTargetConfig 与 service.AgentStorageTargetConfig 对齐
@@ -178,9 +183,12 @@ type StorageTargetConfig struct {
}
// GetTaskSpec 拉取任务规格
-func (c *MasterClient) GetTaskSpec(ctx context.Context, taskID uint) (*TaskSpec, error) {
+func (c *MasterClient) GetTaskSpec(ctx context.Context, taskID uint, recordIDs ...uint) (*TaskSpec, error) {
var spec TaskSpec
path := fmt.Sprintf("/api/agent/tasks/%d", taskID)
+ if len(recordIDs) > 0 {
+ path += fmt.Sprintf("?recordId=%d", recordIDs[0])
+ }
if err := c.do(ctx, http.MethodGet, path, nil, &spec); err != nil {
return nil, err
}
@@ -189,16 +197,18 @@ func (c *MasterClient) GetTaskSpec(ctx context.Context, taskID uint) (*TaskSpec,
// RecordUpdate 与 service.AgentRecordUpdate 对齐
type RecordUpdate struct {
- Status string `json:"status,omitempty"`
- FileName string `json:"fileName,omitempty"`
- FileSize int64 `json:"fileSize,omitempty"`
- Checksum string `json:"checksum,omitempty"`
- StoragePath string `json:"storagePath,omitempty"`
- StorageTargetID uint `json:"storageTargetId,omitempty"`
- StorageTransferMode string `json:"storageTransferMode,omitempty"`
- StorageUploadResults []StorageResultItem `json:"storageUploadResults,omitempty"`
- ErrorMessage string `json:"errorMessage,omitempty"`
- LogAppend string `json:"logAppend,omitempty"`
+ MySQLCheckpoint *backup.MySQLCheckpoint `json:"mysqlCheckpoint,omitempty"`
+ BaseRecordID uint `json:"baseRecordId,omitempty"`
+ Status string `json:"status,omitempty"`
+ FileName string `json:"fileName,omitempty"`
+ FileSize int64 `json:"fileSize,omitempty"`
+ Checksum string `json:"checksum,omitempty"`
+ StoragePath string `json:"storagePath,omitempty"`
+ StorageTargetID uint `json:"storageTargetId,omitempty"`
+ StorageTransferMode string `json:"storageTransferMode,omitempty"`
+ StorageUploadResults []StorageResultItem `json:"storageUploadResults,omitempty"`
+ ErrorMessage string `json:"errorMessage,omitempty"`
+ LogAppend string `json:"logAppend,omitempty"`
}
type StorageResultItem struct {
@@ -251,7 +261,18 @@ func (c *MasterClient) UploadArtifact(ctx context.Context, recordID, targetID ui
}
// RestoreSpec 与 service.AgentRestoreSpec 对齐
+type RestoreArtifact struct {
+ BackupRecordID uint `json:"backupRecordId"`
+ FileName string `json:"fileName"`
+ StoragePath string `json:"storagePath"`
+ Checksum string `json:"checksum"`
+ EncryptionKey string `json:"encryptionKey,omitempty"`
+ Storage StorageTargetConfig `json:"storage"`
+}
+
type RestoreSpec struct {
+ RestoreTime *time.Time `json:"restoreTime,omitempty"`
+ Artifacts []RestoreArtifact `json:"artifacts,omitempty"`
RestoreRecordID uint `json:"restoreRecordId"`
BackupRecordID uint `json:"backupRecordId"`
TaskID uint `json:"taskId"`
@@ -267,6 +288,7 @@ type RestoreSpec struct {
DBPath string `json:"dbPath,omitempty"`
ExtraConfig string `json:"extraConfig,omitempty"`
Compression string `json:"compression"`
+ EncryptionKey string `json:"encryptionKey,omitempty"`
Encrypt bool `json:"encrypt"`
Storage StorageTargetConfig `json:"storage"`
StoragePath string `json:"storagePath"`
@@ -291,8 +313,11 @@ func (c *MasterClient) GetRestoreSpec(ctx context.Context, restoreRecordID uint)
return &spec, nil
}
-func (c *MasterClient) DownloadRestoreArtifact(ctx context.Context, restoreRecordID uint) (io.ReadCloser, error) {
+func (c *MasterClient) DownloadRestoreArtifact(ctx context.Context, restoreRecordID uint, recordIDs ...uint) (io.ReadCloser, error) {
path := fmt.Sprintf("/api/agent/restores/%d/artifact", restoreRecordID)
+ if len(recordIDs) > 0 {
+ path += fmt.Sprintf("?recordId=%d", recordIDs[0])
+ }
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
if err != nil {
return nil, err
diff --git a/server/internal/agent/executor.go b/server/internal/agent/executor.go
index 0a344c9..df5a785 100644
--- a/server/internal/agent/executor.go
+++ b/server/internal/agent/executor.go
@@ -17,6 +17,7 @@ import (
"backupx/server/internal/storage"
storageRclone "backupx/server/internal/storage/rclone"
"backupx/server/pkg/compress"
+ backupcrypto "backupx/server/pkg/crypto"
"go.uber.org/zap"
)
@@ -51,8 +52,7 @@ func (e *Executor) SetLogger(logger *zap.Logger) {
// ExecuteRunTask 处理 run_task 命令:拉规格 → 执行 runner → 压缩 → 上传 → 上报记录。
//
-// 注意:Agent 当前不支持 Encrypt=true(加密密钥不下发到 Agent,避免密钥扩散)。
-// 遇到启用加密的任务会向 Master 上报失败并返回错误。
+// 加密任务仅接收该备份记录的派生密钥,主密钥不离开 Master。
func (e *Executor) ExecuteRunTask(ctx context.Context, taskID, recordID uint) error {
if err := e.ensureTempDir(); err != nil {
e.reportRecordFailure(ctx, recordID, err.Error())
@@ -60,16 +60,11 @@ func (e *Executor) ExecuteRunTask(ctx context.Context, taskID, recordID uint) er
}
// 1) 拉取任务规格
- spec, err := e.client.GetTaskSpec(ctx, taskID)
+ spec, err := e.client.GetTaskSpec(ctx, taskID, recordID)
if err != nil {
e.reportRecordFailure(ctx, recordID, fmt.Sprintf("拉取任务规格失败: %v", err))
return err
}
- if spec.Encrypt {
- msg := "Agent 不支持加密备份(加密密钥仅在 Master 端持有)"
- e.reportRecordFailure(ctx, recordID, msg)
- return fmt.Errorf("%s", msg)
- }
e.appendLog(ctx, recordID, fmt.Sprintf("[agent] 开始执行任务 %s (type=%s)\n", spec.Name, spec.Type))
// 2) 构造 backup.TaskSpec 并找对应 runner
@@ -109,6 +104,16 @@ func (e *Executor) ExecuteRunTask(ctx context.Context, taskID, recordID uint) er
}
finalPath = compressedPath
}
+ if spec.Encrypt {
+ key, err := hex.DecodeString(spec.EncryptionKey)
+ if err == nil {
+ finalPath, err = backupcrypto.EncryptRecordFile(key, recordID, finalPath)
+ }
+ if err != nil {
+ e.reportRecordFailure(ctx, recordID, fmt.Sprintf("加密失败: %v", err))
+ return err
+ }
+ }
info, err := os.Stat(finalPath)
if err != nil {
e.reportRecordFailure(ctx, recordID, fmt.Sprintf("获取文件信息失败: %v", err))
@@ -172,7 +177,8 @@ func (e *Executor) ExecuteRunTask(ctx context.Context, taskID, recordID uint) er
reportCtx, cancel := agentFinalizationContext(ctx)
defer cancel()
if err := e.client.UpdateRecord(reportCtx, recordID, RecordUpdate{
- Status: "success",
+ Status: "success",
+ MySQLCheckpoint: result.MySQLCheckpoint, BaseRecordID: spec.BaseRecordID,
FileName: fileName,
FileSize: fileSize,
Checksum: checksum,
@@ -260,6 +266,7 @@ func buildBackupTaskSpec(spec *TaskSpec, startedAt time.Time, tempDir string) ba
sourcePaths := parseStringListField(spec.SourcePaths)
excludes := parseStringListField(spec.ExcludePatterns)
return backup.TaskSpec{
+ MySQLPITR: spec.MySQLPITR, MySQLBase: spec.MySQLBase,
ID: spec.TaskID,
Name: spec.Name,
Type: spec.Type,
@@ -367,7 +374,7 @@ func (e *Executor) DeleteStorageObject(ctx context.Context, targetType string, t
//
// 与 ExecuteRunTask 对称,但方向相反:
// - 下载:直连共享存储,或通过 Master 中转其本地磁盘对象
-// - 解密:当前 Agent 不支持加密恢复(密钥未下发),spec.Encrypt=true 会直接失败
+// - 解密:使用 Master 为该记录下发的派生密钥
// - 执行:backup.Registry.Runner(spec.Type).Restore
// - 上报:通过 UpdateRestore(status/logAppend)
func (e *Executor) ExecuteRestore(ctx context.Context, restoreRecordID uint) error {
@@ -381,11 +388,6 @@ func (e *Executor) ExecuteRestore(ctx context.Context, restoreRecordID uint) err
e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("拉取恢复规格失败: %v", err))
return err
}
- if spec.Encrypt {
- msg := "Agent 不支持加密恢复(加密密钥仅在 Master 端持有)"
- e.reportRestoreFailure(ctx, restoreRecordID, msg)
- return fmt.Errorf("%s", msg)
- }
e.appendRestoreLog(ctx, restoreRecordID, fmt.Sprintf("[agent] 开始恢复 %s (type=%s)\n", spec.TaskName, spec.Type))
tmpDir, err := os.MkdirTemp(e.tempDir, "restore-*")
@@ -395,82 +397,24 @@ func (e *Executor) ExecuteRestore(ctx context.Context, restoreRecordID uint) err
}
defer os.RemoveAll(tmpDir)
- // 1) 下载
- fileName := spec.FileName
- if strings.TrimSpace(fileName) == "" {
- fileName = filepath.Base(spec.StoragePath)
+ artifacts := spec.Artifacts
+ if len(artifacts) == 0 {
+ artifacts = []RestoreArtifact{{BackupRecordID: spec.BackupRecordID, FileName: spec.FileName, StoragePath: spec.StoragePath, Checksum: spec.Checksum, EncryptionKey: spec.EncryptionKey, Storage: spec.Storage}}
}
- artifactPath := filepath.Join(tmpDir, filepath.Base(fileName))
- e.appendRestoreLog(ctx, restoreRecordID, fmt.Sprintf("[agent] 下载备份文件 %s\n", spec.StoragePath))
- var reader io.ReadCloser
- if spec.Storage.TransferMode == storage.TransferModeMasterRelay {
- reader, err = e.client.DownloadRestoreArtifact(ctx, restoreRecordID)
- } else {
- var rawConfig map[string]any
- if len(spec.Storage.Config) > 0 {
- if err := jsonUnmarshalMap(spec.Storage.Config, &rawConfig); err != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解析存储配置失败: %v", err))
- return err
- }
- }
- provider, providerErr := e.storageRegistry.Create(ctx, spec.Storage.Type, rawConfig)
- if providerErr != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("创建存储客户端失败: %v", providerErr))
- return providerErr
- }
- reader, err = provider.Download(ctx, spec.StoragePath)
- }
- if err != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("下载备份失败: %v", err))
- return err
- }
- if err := writeReaderToLocal(artifactPath, reader); err != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("写入备份文件失败: %v", err))
- return err
- }
-
- // 2.5) 完整性校验:还原前比对下载对象的 SHA-256(与 Master 本地恢复路径一致)。
- // 拒绝还原损坏或被篡改的备份;早期无 checksum 的备份跳过(向后兼容)。
- if strings.TrimSpace(spec.Checksum) != "" {
- e.appendRestoreLog(ctx, restoreRecordID, "[agent] 校验备份完整性(SHA-256)\n")
- actual, sumErr := computeFileSHA256(artifactPath)
- if sumErr != nil {
- msg := fmt.Sprintf("计算校验和失败: %v", sumErr)
- e.reportRestoreFailure(ctx, restoreRecordID, msg)
- return fmt.Errorf("%s", msg)
- }
- if !strings.EqualFold(actual, spec.Checksum) {
- msg := "备份文件完整性校验失败:SHA-256 不匹配,文件可能已损坏或被篡改"
- e.reportRestoreFailure(ctx, restoreRecordID, msg)
- return fmt.Errorf("%s(期望 %s,实际 %s)", msg, spec.Checksum, actual)
- }
- e.appendRestoreLog(ctx, restoreRecordID, "[agent] 完整性校验通过\n")
- }
-
- // 3) 解压(Agent 不支持加密,遇到 .enc 会直接失败)
- preparedPath := artifactPath
- if strings.HasSuffix(strings.ToLower(preparedPath), ".enc") {
- msg := "检测到加密后缀,Agent 不支持加密恢复"
- e.reportRestoreFailure(ctx, restoreRecordID, msg)
- return fmt.Errorf("%s", msg)
- }
- if strings.HasSuffix(strings.ToLower(preparedPath), ".gz") {
- e.appendRestoreLog(ctx, restoreRecordID, "[agent] 解压 gzip 压缩\n")
- decompressed, err := compress.GunzipFile(preparedPath)
+ paths := make([]string, 0, len(artifacts))
+ for _, artifact := range artifacts {
+ item := *spec
+ item.BackupRecordID, item.FileName, item.StoragePath, item.Checksum, item.EncryptionKey, item.Storage = artifact.BackupRecordID, artifact.FileName, artifact.StoragePath, artifact.Checksum, artifact.EncryptionKey, artifact.Storage
+ dir, err := os.MkdirTemp(tmpDir, "artifact-*")
if err != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解压失败: %v", err))
+ e.reportRestoreFailure(ctx, restoreRecordID, err.Error())
return err
}
- preparedPath = decompressed
- }
- if strings.HasSuffix(strings.ToLower(preparedPath), ".zst") {
- e.appendRestoreLog(ctx, restoreRecordID, "[agent] 解压 zstd 压缩\n")
- decompressed, err := compress.UnzstdFile(preparedPath)
+ prepared, err := e.prepareRestoreArtifact(ctx, restoreRecordID, &item, dir)
if err != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解压失败: %v", err))
return err
}
- preparedPath = decompressed
+ paths = append(paths, prepared)
}
// 4) 运行 runner.Restore
@@ -481,9 +425,24 @@ func (e *Executor) ExecuteRestore(ctx context.Context, restoreRecordID uint) err
return err
}
logger := newRestoreLogger(ctx, e.client, e.logger, restoreRecordID)
- if err := runner.Restore(ctx, taskSpec, preparedPath, logger); err != nil {
- e.reportRestoreFailure(ctx, restoreRecordID, err.Error())
- return err
+ if spec.RestoreTime != nil {
+ taskSpec.RestoreTime = *spec.RestoreTime
+ }
+ if mysqlRunner, ok := runner.(*backup.MySQLRunner); ok {
+ for i, artifact := range paths {
+ prepared, err := mysqlRunner.PrepareRestore(ctx, taskSpec, artifact, logger)
+ if err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, err.Error())
+ return err
+ }
+ paths[i] = prepared
+ }
+ }
+ for _, preparedPath := range paths {
+ if err := runner.Restore(ctx, taskSpec, preparedPath, logger); err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, err.Error())
+ return err
+ }
}
// 5) 上报成功
@@ -587,3 +546,91 @@ func splitCommaOrNewline(s string) []string {
}
return result
}
+
+func (e *Executor) prepareRestoreArtifact(ctx context.Context, restoreRecordID uint, spec *RestoreSpec, tmpDir string) (string, error) {
+ // 1) 下载
+ fileName := spec.FileName
+ if strings.TrimSpace(fileName) == "" {
+ fileName = filepath.Base(spec.StoragePath)
+ }
+ artifactPath := filepath.Join(tmpDir, filepath.Base(fileName))
+ e.appendRestoreLog(ctx, restoreRecordID, fmt.Sprintf("[agent] 下载备份文件 %s\n", spec.StoragePath))
+ var reader io.ReadCloser
+ var err error
+ if spec.Storage.TransferMode == storage.TransferModeMasterRelay {
+ reader, err = e.client.DownloadRestoreArtifact(ctx, restoreRecordID, spec.BackupRecordID)
+ } else {
+ var rawConfig map[string]any
+ if len(spec.Storage.Config) > 0 {
+ if err := jsonUnmarshalMap(spec.Storage.Config, &rawConfig); err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解析存储配置失败: %v", err))
+ return "", err
+ }
+ }
+ provider, providerErr := e.storageRegistry.Create(ctx, spec.Storage.Type, rawConfig)
+ if providerErr != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("创建存储客户端失败: %v", providerErr))
+ return "", providerErr
+ }
+ reader, err = provider.Download(ctx, spec.StoragePath)
+ }
+ if err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("下载备份失败: %v", err))
+ return "", err
+ }
+ if err := writeReaderToLocal(artifactPath, reader); err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("写入备份文件失败: %v", err))
+ return "", err
+ }
+
+ // 2.5) 完整性校验:还原前比对下载对象的 SHA-256(与 Master 本地恢复路径一致)。
+ // 拒绝还原损坏或被篡改的备份;早期无 checksum 的备份跳过(向后兼容)。
+ if strings.TrimSpace(spec.Checksum) != "" {
+ e.appendRestoreLog(ctx, restoreRecordID, "[agent] 校验备份完整性(SHA-256)\n")
+ actual, sumErr := computeFileSHA256(artifactPath)
+ if sumErr != nil {
+ msg := fmt.Sprintf("计算校验和失败: %v", sumErr)
+ e.reportRestoreFailure(ctx, restoreRecordID, msg)
+ return "", fmt.Errorf("%s", msg)
+ }
+ if !strings.EqualFold(actual, spec.Checksum) {
+ msg := "备份文件完整性校验失败:SHA-256 不匹配,文件可能已损坏或被篡改"
+ e.reportRestoreFailure(ctx, restoreRecordID, msg)
+ return "", fmt.Errorf("%s(期望 %s,实际 %s)", msg, spec.Checksum, actual)
+ }
+ e.appendRestoreLog(ctx, restoreRecordID, "[agent] 完整性校验通过\n")
+ }
+
+ // 3) 校验后解密,再解压
+ preparedPath := artifactPath
+ if strings.HasSuffix(strings.ToLower(preparedPath), ".enc") {
+ key, err := hex.DecodeString(spec.EncryptionKey)
+ if err == nil {
+ preparedPath, err = backupcrypto.DecryptRecordFile(key, spec.BackupRecordID, preparedPath)
+ }
+ if err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解密失败: %v", err))
+ return "", err
+ }
+ }
+ if strings.HasSuffix(strings.ToLower(preparedPath), ".gz") {
+ e.appendRestoreLog(ctx, restoreRecordID, "[agent] 解压 gzip 压缩\n")
+ decompressed, err := compress.GunzipFile(preparedPath)
+ if err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解压失败: %v", err))
+ return "", err
+ }
+ preparedPath = decompressed
+ }
+ if strings.HasSuffix(strings.ToLower(preparedPath), ".zst") {
+ e.appendRestoreLog(ctx, restoreRecordID, "[agent] 解压 zstd 压缩\n")
+ decompressed, err := compress.UnzstdFile(preparedPath)
+ if err != nil {
+ e.reportRestoreFailure(ctx, restoreRecordID, fmt.Sprintf("解压失败: %v", err))
+ return "", err
+ }
+ preparedPath = decompressed
+ }
+
+ return preparedPath, nil
+}
diff --git a/server/internal/agent/executor_test.go b/server/internal/agent/executor_test.go
index 306fe30..130b282 100644
--- a/server/internal/agent/executor_test.go
+++ b/server/internal/agent/executor_test.go
@@ -2,9 +2,11 @@ package agent
import (
"archive/tar"
+ backupcrypto "backupx/server/pkg/crypto"
"bytes"
"context"
"crypto/sha256"
+ "encoding/hex"
"encoding/json"
"fmt"
"io"
@@ -419,3 +421,73 @@ func TestSQLServerSpecsPreserveInstanceAndTLS(t *testing.T) {
t.Fatal(err)
}
}
+
+func TestEncryptedAgentBackupAndRestoreRoundTrip(t *testing.T) {
+ source := filepath.Join(t.TempDir(), "source")
+ if err := os.Mkdir(source, 0700); err != nil {
+ t.Fatal(err)
+ }
+ file := filepath.Join(source, "hello.txt")
+ if err := os.WriteFile(file, []byte("original"), 0600); err != nil {
+ t.Fatal(err)
+ }
+ master := bytes.Repeat([]byte{7}, 32)
+ key := backupcrypto.RecordKey(master, 99)
+ provider := &agentTestStorageProvider{name: "ok", objects: map[string][]byte{}}
+ var final RecordUpdate
+ restored := false
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/api/agent/tasks/1":
+ if r.URL.Query().Get("recordId") != "99" {
+ t.Error("missing record scope")
+ }
+ writeAgentEnvelope(t, w, TaskSpec{TaskID: 1, Name: "encrypted", Type: "file", SourcePath: source, Compression: "gzip", Encrypt: true, EncryptionKey: hex.EncodeToString(key), StorageTargets: []StorageTargetConfig{{ID: 1, Type: "agent_test_storage", Config: json.RawMessage(`{"name":"ok"}`)}}})
+ case "/api/agent/records/99":
+ var update RecordUpdate
+ if err := json.NewDecoder(r.Body).Decode(&update); err != nil {
+ t.Fatal(err)
+ }
+ if update.Status != "" {
+ final = update
+ }
+ writeAgentEnvelope(t, w, map[string]string{"status": "ok"})
+ case "/api/agent/restores/5/spec":
+ writeAgentEnvelope(t, w, RestoreSpec{RestoreRecordID: 5, BackupRecordID: 99, TaskID: 1, TaskName: "encrypted", Type: "file", SourcePath: source, Encrypt: true, EncryptionKey: hex.EncodeToString(key), Storage: StorageTargetConfig{ID: 1, Type: "agent_test_storage", Config: json.RawMessage(`{"name":"ok"}`)}, StoragePath: final.StoragePath, FileName: final.FileName, Checksum: final.Checksum})
+ case "/api/agent/restores/5":
+ var update RestoreUpdate
+ if err := json.NewDecoder(r.Body).Decode(&update); err != nil {
+ t.Fatal(err)
+ }
+ if update.Status == "success" {
+ restored = true
+ }
+ writeAgentEnvelope(t, w, map[string]string{"status": "ok"})
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer server.Close()
+ executor := NewExecutor(NewMasterClient(server.URL, "token", false), t.TempDir())
+ executor.storageRegistry = storage.NewRegistry(&agentTestStorageFactory{providers: map[string]*agentTestStorageProvider{"ok": provider}})
+ if err := executor.ExecuteRunTask(context.Background(), 1, 99); err != nil {
+ t.Fatal(err)
+ }
+ if final.Status != "success" || !strings.HasSuffix(final.FileName, ".gz.enc") {
+ t.Fatalf("bad encrypted report: %+v", final)
+ }
+ data := provider.objects[final.StoragePath]
+ if !bytes.HasPrefix(data, []byte("BXENC2")) || bytes.Contains(data, []byte("original")) {
+ t.Fatal("uploaded plaintext")
+ }
+ if err := os.WriteFile(file, []byte("changed"), 0600); err != nil {
+ t.Fatal(err)
+ }
+ if err := executor.ExecuteRestore(context.Background(), 5); err != nil {
+ t.Fatal(err)
+ }
+ actual, err := os.ReadFile(file)
+ if err != nil || string(actual) != "original" || !restored {
+ t.Fatalf("roundtrip: %q %v success=%v", actual, err, restored)
+ }
+}
diff --git a/server/internal/backup/mysql_pitr.go b/server/internal/backup/mysql_pitr.go
new file mode 100644
index 0000000..ce36f76
--- /dev/null
+++ b/server/internal/backup/mysql_pitr.go
@@ -0,0 +1,350 @@
+package backup
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strconv"
+ "strings"
+ "time"
+)
+
+// MySQLCheckpoint describes a cumulative binlog archive rooted at one full dump.
+// All database names are included: database-level binlog filtering is unsafe for
+// cross-database transactions and statements using qualified table names.
+type MySQLCheckpoint struct {
+ ServerUUID string `json:"serverUuid"`
+ Source string `json:"source"`
+ StartFile string `json:"startFile"`
+ StartPosition uint64 `json:"startPosition"`
+ EndFile string `json:"endFile"`
+ EndPosition uint64 `json:"endPosition"`
+ CapturedAt time.Time `json:"capturedAt"`
+ BaselineAt time.Time `json:"baselineAt"`
+ Files []string `json:"files,omitempty"`
+ Full bool `json:"full"`
+}
+
+var binlogNamePattern = regexp.MustCompile(`^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\.[0-9]+$`)
+var dumpPositionPattern = regexp.MustCompile(`(?m)^-- CHANGE (?:REPLICATION SOURCE|MASTER) TO (?:SOURCE|MASTER)_LOG_FILE='([^']+)', (?:SOURCE|MASTER)_LOG_POS=([0-9]+);`)
+
+func MySQLPITREnabled(extra string) bool {
+ var options struct {
+ Enabled bool `json:"mysqlPitr"`
+ }
+ return json.Unmarshal([]byte(extra), &options) == nil && options.Enabled
+}
+
+func MySQLFullInterval(extra string) time.Duration {
+ var options struct {
+ Hours int `json:"fullIntervalHours"`
+ }
+ if json.Unmarshal([]byte(extra), &options) != nil || options.Hours <= 0 {
+ return 24 * time.Hour
+ }
+ return time.Duration(options.Hours) * time.Hour
+}
+
+func MySQLSource(db DatabaseSpec) string {
+ return fmt.Sprintf("%s:%d", strings.ToLower(strings.TrimSpace(db.Host)), db.Port)
+}
+
+func (c *MySQLCheckpoint) Validate() error {
+ if c == nil || c.ServerUUID == "" || c.Source == "" || !binlogNamePattern.MatchString(c.StartFile) || !binlogNamePattern.MatchString(c.EndFile) || c.StartPosition < 4 || c.EndPosition < 4 || c.CapturedAt.IsZero() || c.BaselineAt.IsZero() || c.CapturedAt.Before(c.BaselineAt) {
+ return errors.New("invalid MySQL PITR checkpoint")
+ }
+ if !c.Full {
+ if len(c.Files) == 0 || c.Files[0] != c.StartFile || c.Files[len(c.Files)-1] != c.EndFile {
+ return errors.New("incomplete MySQL binlog archive")
+ }
+ for i, name := range c.Files {
+ if !binlogNamePattern.MatchString(name) {
+ return errors.New("invalid binlog file name")
+ }
+ if i > 0 && !consecutiveBinlog(c.Files[i-1], name) {
+ return errors.New("gap in MySQL binlog sequence")
+ }
+ }
+ if c.StartFile == c.EndFile && c.EndPosition < c.StartPosition {
+ return errors.New("MySQL binlog position moved backwards")
+ }
+ }
+ return nil
+}
+
+func consecutiveBinlog(previous, next string) bool {
+ a, b := strings.LastIndexByte(previous, '.'), strings.LastIndexByte(next, '.')
+ if a < 0 || b < 0 || previous[:a] != next[:b] {
+ return false
+ }
+ x, e1 := strconv.ParseUint(previous[a+1:], 10, 64)
+ y, e2 := strconv.ParseUint(next[b+1:], 10, 64)
+ return e1 == nil && e2 == nil && y > x && y-x == 1
+}
+
+func mysqlConnectionArgs(db DatabaseSpec) []string {
+ return []string{"--host", db.Host, "--port", strconv.Itoa(db.Port), "--user", db.User}
+}
+
+func (r *MySQLRunner) query(ctx context.Context, db DatabaseSpec, sql string) (string, error) {
+ var out, stderr bytes.Buffer
+ args := append(mysqlConnectionArgs(db), "--batch", "--skip-column-names", "--execute", sql)
+ err := r.executor.Run(ctx, "mysql", args, CommandOptions{Stdout: &out, Stderr: &stderr, Env: mysqlEnv(db.Password)})
+ if err != nil {
+ return "", fmt.Errorf("query MySQL metadata: %w: %s", err, strings.TrimSpace(stderr.String()))
+ }
+ return strings.TrimSpace(out.String()), nil
+}
+
+func (r *MySQLRunner) checkpoint(ctx context.Context, db DatabaseSpec) (*MySQLCheckpoint, error) {
+ // Capture time before the log position, so the archive covers the entire advertised window.
+ meta, err := r.query(ctx, db, "SELECT @@server_uuid, UTC_TIMESTAMP(), @@global.log_bin")
+ if err != nil {
+ return nil, err
+ }
+ fields := strings.Split(meta, "\t")
+ if len(fields) != 3 || fields[2] != "1" {
+ return nil, errors.New("MySQL PITR requires MySQL 8.0+ with binary logging enabled")
+ }
+ captured, err := time.ParseInLocation("2006-01-02 15:04:05", fields[1], time.UTC)
+ if err != nil {
+ return nil, err
+ }
+ status, err := r.query(ctx, db, "SHOW BINARY LOG STATUS")
+ if err != nil {
+ status, err = r.query(ctx, db, "SHOW MASTER STATUS")
+ }
+ if err != nil {
+ return nil, err
+ }
+ pos := strings.Fields(status)
+ if len(pos) < 2 || !binlogNamePattern.MatchString(pos[0]) {
+ return nil, errors.New("missing MySQL binary log status")
+ }
+ offset, err := strconv.ParseUint(pos[1], 10, 64)
+ if err != nil || offset < 4 {
+ return nil, errors.New("invalid MySQL binary log position")
+ }
+ return &MySQLCheckpoint{ServerUUID: fields[0], Source: MySQLSource(db), EndFile: pos[0], EndPosition: offset, CapturedAt: captured}, nil
+}
+
+func (r *MySQLRunner) runPITR(ctx context.Context, task TaskSpec, writer LogWriter) (result *RunResult, err error) {
+ if task.StartedAt.IsZero() {
+ task.StartedAt = time.Now().UTC()
+ }
+ for _, tool := range []string{"mysql", "mysqldump", "mysqlbinlog"} {
+ if _, err := r.executor.LookPath(tool); err != nil {
+ return nil, fmt.Errorf("MySQL PITR requires %s (MySQL 8.0+ client tools)", tool)
+ }
+ }
+ names := normalizeDatabaseNames(task.Database.Names)
+ if len(names) != 1 || names[0] != "*" {
+ return nil, errors.New("MySQL PITR requires database name * (whole instance)")
+ }
+ var dir string
+ if task.TempDir != "" {
+ if err := os.MkdirAll(task.TempDir, 0700); err != nil {
+ return nil, err
+ }
+ dir, err = os.MkdirTemp(task.TempDir, "mysql-pitr-*")
+ } else {
+ dir, err = CreateTaskTempDir(task.Name, task.StartedAt)
+ }
+ if err != nil {
+ return nil, err
+ }
+ defer func() {
+ if err != nil {
+ err = errors.Join(err, os.RemoveAll(dir))
+ }
+ }()
+ dataDir := filepath.Join(dir, "pitr")
+ if err := os.Mkdir(dataDir, 0700); err != nil {
+ return nil, err
+ }
+ checkpoint, err := r.checkpoint(ctx, task.Database)
+ if err != nil {
+ return nil, err
+ }
+ base := task.MySQLBase
+ if base == nil {
+ dumpPath := filepath.Join(dataDir, "dump.sql")
+ output, err := os.OpenFile(dumpPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
+ if err != nil {
+ return nil, err
+ }
+ args := append(mysqlConnectionArgs(task.Database), "--single-transaction", "--quick", "--routines", "--triggers", "--events", "--no-tablespaces", "--source-data=2", "--set-gtid-purged=OFF", "--all-databases")
+ stderr := newLogLineWriter(writer, "mysqldump")
+ writer.WriteLine("创建 MySQL PITR 全实例基线(仅 InnoDB;期间请勿执行 DDL)")
+ runErr := r.executor.Run(ctx, "mysqldump", args, CommandOptions{Stdout: output, Stderr: stderr, Env: mysqlEnv(task.Database.Password)})
+ stderr.Flush()
+ if err := errors.Join(runErr, output.Close()); err != nil {
+ return nil, fmt.Errorf("create PITR baseline: %w: %s", err, stderr.collected())
+ }
+ // The coordinate is near the header; avoid reading the complete database into memory.
+ input, err := os.Open(dumpPath)
+ if err != nil {
+ return nil, err
+ }
+ header, readErr := io.ReadAll(io.LimitReader(input, 1<<20))
+ if err := errors.Join(readErr, input.Close()); err != nil {
+ return nil, err
+ }
+ match := dumpPositionPattern.FindSubmatch(header)
+ if len(match) != 3 || !binlogNamePattern.Match(match[1]) {
+ return nil, errors.New("mysqldump did not report a binary log coordinate")
+ }
+ position, err := strconv.ParseUint(string(match[2]), 10, 64)
+ if err != nil {
+ return nil, err
+ }
+ beforeUUID := checkpoint.ServerUUID
+ checkpoint, err = r.checkpoint(ctx, task.Database)
+ if err != nil {
+ return nil, err
+ }
+ if checkpoint.ServerUUID != beforeUUID {
+ return nil, errors.New("MySQL server changed during full backup")
+ }
+ checkpoint.StartFile, checkpoint.StartPosition = string(match[1]), position
+ checkpoint.BaselineAt = checkpoint.CapturedAt
+ checkpoint.Full = true
+ } else {
+ if err := base.Validate(); err != nil {
+ return nil, err
+ }
+ if !base.Full || base.Source != checkpoint.Source || base.ServerUUID != checkpoint.ServerUUID || checkpoint.CapturedAt.Before(base.CapturedAt) {
+ return nil, errors.New("MySQL source changed; create a new full baseline")
+ }
+ checkpoint.StartFile, checkpoint.StartPosition = base.StartFile, base.StartPosition
+ checkpoint.BaselineAt = base.BaselineAt
+ logs, err := r.query(ctx, task.Database, "SHOW BINARY LOGS")
+ if err != nil {
+ return nil, err
+ }
+ started := false
+ expectedSizes := map[string]uint64{}
+ for _, line := range strings.Split(logs, "\n") {
+ fields := strings.Fields(line)
+ if len(fields) < 2 {
+ return nil, errors.New("invalid MySQL binary log list")
+ }
+ name := fields[0]
+ if name == base.StartFile {
+ started = true
+ }
+ if !started {
+ continue
+ }
+ expectedSize, err := strconv.ParseUint(fields[1], 10, 64)
+ if err != nil || expectedSize < 4 {
+ return nil, errors.New("invalid binary log size")
+ }
+ expectedSizes[name] = expectedSize
+ checkpoint.Files = append(checkpoint.Files, name)
+ if name == checkpoint.EndFile {
+ break
+ }
+ }
+ if err := checkpoint.Validate(); err != nil {
+ return nil, fmt.Errorf("binlogs expired or incomplete; no recoverable archive created: %w", err)
+ }
+ for _, name := range checkpoint.Files {
+ args := append(mysqlConnectionArgs(task.Database), "--read-from-remote-server", "--raw", "--verify-binlog-checksum", "--result-file="+dataDir+string(filepath.Separator), name)
+ stderr := newLogLineWriter(writer, "mysqlbinlog")
+ runErr := r.executor.Run(ctx, "mysqlbinlog", args, CommandOptions{Stderr: stderr, Env: mysqlEnv(task.Database.Password)})
+ stderr.Flush()
+ if runErr != nil {
+ return nil, fmt.Errorf("archive binlog %s: %w: %s", name, runErr, stderr.collected())
+ }
+ info, err := os.Stat(filepath.Join(dataDir, name))
+ if err != nil {
+ return nil, err
+ }
+ if (name == checkpoint.EndFile && uint64(info.Size()) < checkpoint.EndPosition) || (name != checkpoint.EndFile && uint64(info.Size()) != expectedSizes[name]) {
+ return nil, errors.New("downloaded binlog is shorter than captured position")
+ }
+ }
+ writer.WriteLine(fmt.Sprintf("已归档基线以来的 %d 个 binlog;恢复范围截至 %s UTC", len(checkpoint.Files), checkpoint.CapturedAt.Format(time.DateTime)))
+ }
+ if err := checkpoint.Validate(); err != nil {
+ return nil, err
+ }
+ metadata, err := json.Marshal(checkpoint)
+ if err != nil {
+ return nil, err
+ }
+ if err := os.WriteFile(filepath.Join(dataDir, "checkpoint.json"), metadata, 0600); err != nil {
+ return nil, err
+ }
+ name := BuildArtifactName(task.Name, task.StartedAt, "pitr.tar")
+ artifact := filepath.Join(dir, name)
+ if err := packageBackupFiles(dataDir, artifact, writer); err != nil {
+ return nil, err
+ }
+ info, err := os.Stat(artifact)
+ if err != nil {
+ return nil, err
+ }
+ return &RunResult{ArtifactPath: artifact, FileName: name, TempDir: dir, Size: info.Size(), MySQLCheckpoint: checkpoint}, nil
+}
+
+// PrepareRestore verifies and decodes all PITR data before the caller imports a
+// baseline. The caller owns the artifact's parent temporary directory.
+func (r *MySQLRunner) PrepareRestore(ctx context.Context, task TaskSpec, artifact string, writer LogWriter) (string, error) {
+ if !strings.HasSuffix(artifact, ".pitr.tar") {
+ return artifact, nil
+ }
+ dir, err := os.MkdirTemp(filepath.Dir(artifact), "mysql-pitr-restore-*")
+ if err != nil {
+ return "", err
+ }
+ if err := extractTarArchive(artifact, dir); err != nil {
+ return "", err
+ }
+ raw, err := os.ReadFile(filepath.Join(dir, "checkpoint.json"))
+ if err != nil {
+ return "", err
+ }
+ var checkpoint MySQLCheckpoint
+ if err := json.Unmarshal(raw, &checkpoint); err != nil {
+ return "", err
+ }
+ if err := checkpoint.Validate(); err != nil {
+ return "", err
+ }
+ if !task.RestoreTime.IsZero() && (task.RestoreTime.Before(checkpoint.BaselineAt) || (!checkpoint.Full && !task.RestoreTime.Before(checkpoint.CapturedAt))) {
+ return "", errors.New("requested restore time is outside the archived MySQL window (end exclusive)")
+ }
+ if checkpoint.Full {
+ return filepath.Join(dir, "dump.sql"), nil
+ }
+ if _, err := r.executor.LookPath("mysqlbinlog"); err != nil {
+ return "", err
+ }
+ args := []string{"--verify-binlog-checksum", "--skip-gtids", "--disable-log-bin", "--start-position=" + strconv.FormatUint(checkpoint.StartPosition, 10), "--stop-position=" + strconv.FormatUint(checkpoint.EndPosition, 10)}
+ if !task.RestoreTime.IsZero() {
+ args = append(args, "--stop-datetime="+task.RestoreTime.UTC().Format(time.DateTime))
+ }
+ for _, name := range checkpoint.Files {
+ args = append(args, filepath.Join(dir, name))
+ }
+ // Decode completely before touching the database, so corrupt or missing logs cannot be partially replayed.
+ sqlPath := filepath.Join(dir, "replay.sql")
+ output, err := os.OpenFile(sqlPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0600)
+ if err != nil {
+ return "", err
+ }
+ var stderr bytes.Buffer
+ runErr := r.executor.Run(ctx, "mysqlbinlog", args, CommandOptions{Stdout: output, Stderr: &stderr, Env: []string{"TZ=UTC"}})
+ if err := errors.Join(runErr, output.Close()); err != nil {
+ return "", fmt.Errorf("decode MySQL binlog: %w: %s", err, stderr.String())
+ }
+ return sqlPath, nil
+}
diff --git a/server/internal/backup/mysql_pitr_test.go b/server/internal/backup/mysql_pitr_test.go
new file mode 100644
index 0000000..8bf8e14
--- /dev/null
+++ b/server/internal/backup/mysql_pitr_test.go
@@ -0,0 +1,182 @@
+package backup
+
+import (
+ "context"
+ "errors"
+ "io"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestMySQLPITRFullArchiveAndPointInTimeRestore(t *testing.T) {
+ ctx := context.Background()
+ now := time.Date(2026, 11, 14, 1, 0, 0, 0, time.UTC)
+ incremental := false
+ var decodedArgs []string
+ var restored []string
+ executor := &fakeCommandExecutor{runFunc: func(name string, args []string, options CommandOptions) error {
+ switch name {
+ case "mysql":
+ if options.Stdin != nil {
+ data, err := io.ReadAll(options.Stdin)
+ restored = append(restored, string(data))
+ return err
+ }
+ sql := args[len(args)-1]
+ var text string
+ switch sql {
+ case "SELECT @@server_uuid, UTC_TIMESTAMP(), @@global.log_bin":
+ text = "server-uuid\t2026-11-14 01:00:00\t1"
+ if incremental {
+ text = "server-uuid\t2026-11-14 02:00:00\t1"
+ }
+ case "SHOW BINARY LOG STATUS":
+ text = "mysql-bin.000002\t64"
+ if incremental {
+ text = "mysql-bin.000003\t80"
+ }
+ case "SHOW BINARY LOGS":
+ text = "mysql-bin.000001\t100\nmysql-bin.000002\t100\nmysql-bin.000003\t80"
+ default:
+ return errors.New("unexpected query: " + sql)
+ }
+ _, err := io.WriteString(options.Stdout, text)
+ return err
+ case "mysqldump":
+ if !containsArg(args, "--source-data=2") || !containsArg(args, "--all-databases") || containsArg(args, "--password") {
+ t.Fatalf("unsafe dump args %v", args)
+ }
+ _, err := io.WriteString(options.Stdout, "-- CHANGE REPLICATION SOURCE TO SOURCE_LOG_FILE='mysql-bin.000002', SOURCE_LOG_POS=32;\nCREATE DATABASE app;\n")
+ return err
+ case "mysqlbinlog":
+ if containsArg(args, "--raw") {
+ var prefix string
+ for _, arg := range args {
+ if strings.HasPrefix(arg, "--result-file=") {
+ prefix = strings.TrimPrefix(arg, "--result-file=")
+ }
+ }
+ return os.WriteFile(filepath.Join(prefix, args[len(args)-1]), make([]byte, 100), 0600)
+ }
+ decodedArgs = append([]string{}, args...)
+ if !reflect.DeepEqual(options.Env, []string{"TZ=UTC"}) {
+ t.Fatalf("binlog timezone: %v", options.Env)
+ }
+ _, err := io.WriteString(options.Stdout, "INSERT INTO app.events VALUES (1);")
+ return err
+ }
+ return errors.New("unexpected command")
+ }}
+ runner := NewMySQLRunner(executor)
+ task := TaskSpec{Name: "pitr", Type: "mysql", StartedAt: now, MySQLPITR: true, TempDir: t.TempDir(), Database: DatabaseSpec{Host: "db", Port: 3306, User: "backup", Password: "secret", Names: []string{"*"}}}
+ full, err := runner.Run(ctx, task, NopLogWriter{})
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer os.RemoveAll(full.TempDir)
+ if !full.MySQLCheckpoint.Full || full.MySQLCheckpoint.StartPosition != 32 {
+ t.Fatalf("full checkpoint: %+v", full.MySQLCheckpoint)
+ }
+ incremental = true
+ task.StartedAt = now.Add(time.Hour)
+ task.MySQLBase = full.MySQLCheckpoint
+ logs, err := runner.Run(ctx, task, NopLogWriter{})
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer os.RemoveAll(logs.TempDir)
+ if !reflect.DeepEqual(logs.MySQLCheckpoint.Files, []string{"mysql-bin.000002", "mysql-bin.000003"}) {
+ t.Fatalf("archive files: %v", logs.MySQLCheckpoint.Files)
+ }
+ task.RestoreTime = now.Add(30 * time.Minute)
+ if err := runner.Restore(ctx, task, full.ArtifactPath, NopLogWriter{}); err != nil {
+ t.Fatal(err)
+ }
+ if err := runner.Restore(ctx, task, logs.ArtifactPath, NopLogWriter{}); err != nil {
+ t.Fatal(err)
+ }
+ if len(restored) != 2 || !strings.Contains(restored[0], "CREATE DATABASE") || !strings.Contains(restored[1], "INSERT INTO") {
+ t.Fatalf("restore order: %v", restored)
+ }
+ for _, arg := range []string{"--start-position=32", "--stop-position=80", "--stop-datetime=2026-11-14 01:30:00", "--verify-binlog-checksum"} {
+ if !containsArg(decodedArgs, arg) {
+ t.Fatalf("missing %s in %v", arg, decodedArgs)
+ }
+ }
+ task.RestoreTime = now.Add(time.Hour)
+ if err := runner.Restore(ctx, task, logs.ArtifactPath, NopLogWriter{}); err == nil {
+ t.Fatal("accepted end-exclusive boundary")
+ }
+}
+
+func containsArg(args []string, value string) bool {
+ for _, arg := range args {
+ if arg == value {
+ return true
+ }
+ }
+ return false
+}
+
+func TestMySQLCheckpointRejectsGapsAndPaths(t *testing.T) {
+ now := time.Now().UTC()
+ good := MySQLCheckpoint{ServerUUID: "uuid", Source: "db:3306", StartFile: "bin.000001", StartPosition: 4, EndFile: "bin.000002", EndPosition: 80, BaselineAt: now, CapturedAt: now.Add(time.Hour), Files: []string{"bin.000001", "bin.000002"}}
+ if err := good.Validate(); err != nil {
+ t.Fatal(err)
+ }
+ for _, files := range [][]string{{"bin.000001", "bin.000003", "bin.000002"}, {"../bin.000001", "bin.000002"}, {"bin.000001"}, {"bin.000001", "other.000002"}} {
+ broken := good
+ broken.Files = files
+ if err := broken.Validate(); err == nil {
+ t.Fatalf("accepted %v", files)
+ }
+ }
+}
+
+func TestMySQLPITRRejectsExpiredLogsAndChangedSource(t *testing.T) {
+ now := time.Date(2026, 11, 14, 1, 0, 0, 0, time.UTC)
+ for _, mode := range []string{"expired", "changed", "short"} {
+ t.Run(mode, func(t *testing.T) {
+ executor := &fakeCommandExecutor{runFunc: func(name string, args []string, options CommandOptions) error {
+ if name == "mysqlbinlog" {
+ var prefix string
+ for _, arg := range args {
+ if strings.HasPrefix(arg, "--result-file=") {
+ prefix = strings.TrimPrefix(arg, "--result-file=")
+ }
+ }
+ return os.WriteFile(filepath.Join(prefix, args[len(args)-1]), []byte("short"), 0600)
+ }
+ query := args[len(args)-1]
+ text := ""
+ switch query {
+ case "SELECT @@server_uuid, UTC_TIMESTAMP(), @@global.log_bin":
+ text = "uuid\t2026-11-14 02:00:00\t1"
+ if mode == "changed" {
+ text = "another\t2026-11-14 02:00:00\t1"
+ }
+ case "SHOW BINARY LOG STATUS":
+ text = "bin.000002\t80"
+ case "SHOW BINARY LOGS":
+ text = "bin.000001\t80\nbin.000002\t80"
+ if mode == "expired" {
+ text = "bin.000002\t80"
+ }
+ default:
+ return errors.New("unexpected query")
+ }
+ _, err := io.WriteString(options.Stdout, text)
+ return err
+ }}
+ base := &MySQLCheckpoint{ServerUUID: "uuid", Source: "db:3306", StartFile: "bin.000001", StartPosition: 4, EndFile: "bin.000001", EndPosition: 80, BaselineAt: now, CapturedAt: now, Full: true}
+ _, err := NewMySQLRunner(executor).Run(context.Background(), TaskSpec{Name: "reject-" + mode, StartedAt: now, MySQLPITR: true, MySQLBase: base, Database: DatabaseSpec{Host: "db", Port: 3306, Names: []string{"*"}}}, NopLogWriter{})
+ if err == nil {
+ t.Fatal("accepted " + mode)
+ }
+ })
+ }
+}
diff --git a/server/internal/backup/mysql_runner.go b/server/internal/backup/mysql_runner.go
index 23392ac..daceeb2 100644
--- a/server/internal/backup/mysql_runner.go
+++ b/server/internal/backup/mysql_runner.go
@@ -27,6 +27,9 @@ func (r *MySQLRunner) Type() string {
}
func (r *MySQLRunner) Run(ctx context.Context, task TaskSpec, writer LogWriter) (*RunResult, error) {
+ if task.MySQLPITR {
+ return r.runPITR(ctx, task, writer)
+ }
if _, err := r.executor.LookPath("mysqldump"); err != nil {
return nil, fmt.Errorf("未找到 mysqldump 命令 (请确保服务器已安装 mysql-client 或 mariadb-client)")
}
@@ -83,6 +86,17 @@ func (r *MySQLRunner) Run(ctx context.Context, task TaskSpec, writer LogWriter)
}
func (r *MySQLRunner) Restore(ctx context.Context, task TaskSpec, artifactPath string, writer LogWriter) error {
+ if strings.HasSuffix(artifactPath, ".pitr.tar") {
+ prepared, err := r.PrepareRestore(ctx, task, artifactPath, writer)
+ if err != nil {
+ return err
+ }
+ return r.restoreSQL(ctx, task, prepared, writer)
+ }
+ return r.restoreSQL(ctx, task, artifactPath, writer)
+}
+
+func (r *MySQLRunner) restoreSQL(ctx context.Context, task TaskSpec, artifactPath string, writer LogWriter) error {
if _, err := r.executor.LookPath("mysql"); err != nil {
return fmt.Errorf("未找到 mysql 命令 (请确保服务器已安装 mysql-client 或 mariadb-client)")
}
diff --git a/server/internal/backup/retention/differential_test.go b/server/internal/backup/retention/differential_test.go
index e2bab07..ec6aa0f 100644
--- a/server/internal/backup/retention/differential_test.go
+++ b/server/internal/backup/retention/differential_test.go
@@ -1,7 +1,9 @@
package retention
import (
+ "context"
"testing"
+ "time"
"backupx/server/internal/model"
)
@@ -53,3 +55,37 @@ func TestProtectDifferentialBasesNoDiffsPassThrough(t *testing.T) {
t.Fatalf("no diffs should pass through unchanged, got %v", retentionRecIDs(got))
}
}
+
+func TestProtectMySQLBinlogBaseline(t *testing.T) {
+ all := []model.BackupRecord{{ID: 1, BackupKind: model.BackupKindFull}, {ID: 2, BackupKind: model.BackupKindBinlog, BaseRecordID: 1}}
+ if got := protectDifferentialBases(all, all[:1]); len(got) != 0 {
+ t.Fatal("deleted live binlog baseline")
+ }
+ if got := protectDifferentialBases(all, all); len(got) != 2 {
+ t.Fatal("expired chain not reclaimable")
+ }
+}
+
+func TestFailedBinlogDeletionKeepsBaseline(t *testing.T) {
+ now := time.Now().UTC()
+ old := now.Add(-72 * time.Hour)
+ repo := &fakeRecordRepository{records: []model.BackupRecord{
+ {ID: 3, BackupKind: model.BackupKindFull, StorageTargetID: 1, StoragePath: "new", CompletedAt: &now},
+ {ID: 2, BackupKind: model.BackupKindBinlog, BaseRecordID: 1, StorageTargetID: 1, StoragePath: "logs", CompletedAt: &old},
+ {ID: 1, BackupKind: model.BackupKindFull, StorageTargetID: 1, StoragePath: "full", CompletedAt: &old},
+ }}
+ provider := &fakeProvider{failKey: "logs"}
+ if _, err := NewService(repo).Cleanup(context.Background(), &model.BackupTask{ID: 1, MaxBackups: 1}, provider); err != nil {
+ t.Fatal(err)
+ }
+ for _, id := range repo.deleted {
+ if id == 1 {
+ t.Fatal("deleted full baseline after dependent cleanup failure")
+ }
+ }
+ for _, key := range provider.deleted {
+ if key == "full" {
+ t.Fatal("deleted baseline object")
+ }
+ }
+}
diff --git a/server/internal/backup/retention/service.go b/server/internal/backup/retention/service.go
index 6e632c9..c788f1e 100644
--- a/server/internal/backup/retention/service.go
+++ b/server/internal/backup/retention/service.go
@@ -104,6 +104,16 @@ func (s *Service) cleanup(ctx context.Context, task *model.BackupTask, resolvePr
repositoryProviders := make(map[uint]storage.StorageProvider)
touchedProviders := make(map[uint]storage.StorageProvider)
for _, record := range candidates {
+ if record.BackupKind == model.BackupKindFull {
+ count, err := s.records.CountDependentDifferentials(ctx, record.ID)
+ if err != nil {
+ result.Warnings = append(result.Warnings, fmt.Sprintf("check dependencies for record %d: %v", record.ID, err))
+ continue
+ }
+ if count > 0 {
+ continue
+ } // A dependent deletion may have failed earlier in this cleanup.
+ }
objects, objectErr := cleanupObjectsForRecord(record)
if objectErr != nil {
result.Warnings = append(result.Warnings, fmt.Sprintf("decode storage copies for record %d failed: %v", record.ID, objectErr))
@@ -209,7 +219,7 @@ func protectDifferentialBases(all []model.BackupRecord, candidates []model.Backu
}
protected := make(map[uint]struct{})
for _, r := range all {
- if r.BackupKind != model.BackupKindDifferential || r.BaseRecordID == 0 {
+ if (r.BackupKind != model.BackupKindDifferential && r.BackupKind != model.BackupKindBinlog) || r.BaseRecordID == 0 {
continue
}
if _, beingDeleted := deleting[r.ID]; beingDeleted {
diff --git a/server/internal/backup/retention/service_test.go b/server/internal/backup/retention/service_test.go
index 8cb8108..4a5fa0b 100644
--- a/server/internal/backup/retention/service_test.go
+++ b/server/internal/backup/retention/service_test.go
@@ -45,8 +45,24 @@ func (r *fakeRecordRepository) ListByTask(_ context.Context, _ uint) ([]model.Ba
func (r *fakeRecordRepository) ListSuccessfulByTask(_ context.Context, _ uint) ([]model.BackupRecord, error) {
return r.records, nil
}
-func (r *fakeRecordRepository) CountDependentDifferentials(context.Context, uint) (int64, error) {
- return 0, nil
+func (r *fakeRecordRepository) CountDependentDifferentials(_ context.Context, id uint) (int64, error) {
+ var count int64
+ for _, record := range r.records {
+ if record.BaseRecordID != id {
+ continue
+ }
+ deleted := false
+ for _, deletedID := range r.deleted {
+ if deletedID == record.ID {
+ deleted = true
+ break
+ }
+ }
+ if !deleted {
+ count++
+ }
+ }
+ return count, nil
}
func (r *fakeRecordRepository) Count(context.Context) (int64, error) { return 0, nil }
func (r *fakeRecordRepository) CountSince(context.Context, time.Time) (int64, error) { return 0, nil }
diff --git a/server/internal/backup/types.go b/server/internal/backup/types.go
index 5e08132..ba033af 100644
--- a/server/internal/backup/types.go
+++ b/server/internal/backup/types.go
@@ -22,6 +22,9 @@ type DatabaseSpec struct {
}
type TaskSpec struct {
+ MySQLPITR bool
+ MySQLBase *MySQLCheckpoint
+ RestoreTime time.Time
ID uint
Name string
Type string
@@ -49,11 +52,12 @@ type TaskSpec struct {
}
type RunResult struct {
- ArtifactPath string
- FileName string
- TempDir string
- Size int64
- StorageKey string
+ MySQLCheckpoint *MySQLCheckpoint
+ ArtifactPath string
+ FileName string
+ TempDir string
+ Size int64
+ StorageKey string
// Manifest 为全量备份产出的条目清单,供后续差异备份比对;差异备份运行时为 nil。
Manifest *Manifest
}
diff --git a/server/internal/http/agent_handler.go b/server/internal/http/agent_handler.go
index 7912390..0c9382d 100644
--- a/server/internal/http/agent_handler.go
+++ b/server/internal/http/agent_handler.go
@@ -114,6 +114,7 @@ func (h *AgentHandler) SubmitCommandResult(c *gin.Context) {
// GetTaskSpec Agent 拉取任务规格(含解密后的存储配置)。
func (h *AgentHandler) GetTaskSpec(c *gin.Context) {
+ c.Header("Cache-Control", "no-store")
node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))
if err != nil {
response.Error(c, err)
@@ -124,7 +125,16 @@ func (h *AgentHandler) GetTaskSpec(c *gin.Context) {
response.Error(c, err)
return
}
- spec, err := h.agentService.GetTaskSpec(c.Request.Context(), node, uint(id))
+ var recordIDs []uint
+ if value := c.Query("recordId"); value != "" {
+ recordID, parseErr := strconv.ParseUint(value, 10, 32)
+ if parseErr != nil || recordID == 0 {
+ c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": "无效的备份记录 ID"})
+ return
+ }
+ recordIDs = []uint{uint(recordID)}
+ }
+ spec, err := h.agentService.GetTaskSpec(c.Request.Context(), node, uint(id), recordIDs...)
if err != nil {
response.Error(c, err)
return
@@ -196,6 +206,7 @@ func (h *AgentHandler) UploadArtifact(c *gin.Context) {
// GetRestoreSpec Agent 拉取恢复规格。
func (h *AgentHandler) GetRestoreSpec(c *gin.Context) {
+ c.Header("Cache-Control", "no-store")
if h.restoreService == nil {
c.JSON(stdhttp.StatusServiceUnavailable, gin.H{"code": "RESTORE_SERVICE_DISABLED", "message": "restore service is not enabled"})
return
@@ -263,7 +274,16 @@ func (h *AgentHandler) DownloadRestoreArtifact(c *gin.Context) {
response.Error(c, err)
return
}
- artifact, err := h.restoreService.DownloadAgentArtifact(c.Request.Context(), node, uint(restoreID))
+ var recordIDs []uint
+ if value := c.Query("recordId"); value != "" {
+ id, err := strconv.ParseUint(value, 10, 32)
+ if err != nil || id == 0 {
+ c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": "无效的备份记录 ID"})
+ return
+ }
+ recordIDs = []uint{uint(id)}
+ }
+ artifact, err := h.restoreService.DownloadAgentArtifact(c.Request.Context(), node, uint(restoreID), recordIDs...)
if err != nil {
response.Error(c, err)
return
diff --git a/server/internal/http/backup_record_handler.go b/server/internal/http/backup_record_handler.go
index 0a9065b..66ece97 100644
--- a/server/internal/http/backup_record_handler.go
+++ b/server/internal/http/backup_record_handler.go
@@ -156,9 +156,13 @@ func (h *BackupRecordHandler) Restore(c *gin.Context) {
var body struct {
SelectedPaths []string `json:"selectedPaths"`
TargetPath string `json:"targetPath"`
+ RestoreTime string `json:"restoreTime"`
}
- _ = c.ShouldBindJSON(&body)
- detail, err := h.restoreService.StartSelective(c.Request.Context(), id, body.SelectedPaths, strings.TrimSpace(body.TargetPath), triggeredBy)
+ if err := c.ShouldBindJSON(&body); err != nil && err != io.EOF {
+ response.Error(c, apperror.BadRequest("INVALID_INPUT", "恢复请求格式不合法", err))
+ return
+ }
+ detail, err := h.restoreService.StartSelective(c.Request.Context(), id, body.SelectedPaths, strings.TrimSpace(body.TargetPath), triggeredBy, body.RestoreTime)
if err != nil {
response.Error(c, err)
return
diff --git a/server/internal/model/backup_record.go b/server/internal/model/backup_record.go
index 8734c19..e6b0538 100644
--- a/server/internal/model/backup_record.go
+++ b/server/internal/model/backup_record.go
@@ -11,12 +11,14 @@ const (
const (
// BackupKindFull 全量归档;BackupKindDifferential 差异归档;
// BackupKindRepository 为可独立恢复的 CDC 内容寻址快照。
+ BackupKindBinlog = "binlog"
BackupKindFull = "full"
BackupKindDifferential = "differential"
BackupKindRepository = "repository"
)
type BackupRecord struct {
+ MySQLCheckpoint string `gorm:"column:mysql_checkpoint;type:text" json:"-"`
ID uint `gorm:"primaryKey" json:"id"`
TaskID uint `gorm:"column:task_id;index;not null" json:"taskId"`
Task BackupTask `json:"task,omitempty"`
@@ -37,9 +39,9 @@ type BackupRecord struct {
// Locked 保留锁定(法律保留):为 true 时该备份不参与保留期/数量自动清理,
// 且禁止手动删除,直到显式解锁。用于保护合规快照、迁移前基线等关键备份。
Locked bool `gorm:"column:locked;not null;default:false;index" json:"locked"`
- // BackupKind 备份类型:full(全量)/ differential(差异)/ repository(CDC 快照)。
+ // BackupKind 备份类型:full / differential / repository / binlog(MySQL 日志归档)。
BackupKind string `gorm:"column:backup_kind;size:16;not null;default:'full';index" json:"backupKind"`
- // BaseRecordID 差异备份所基于的全量备份记录 ID(全量记录为 0)。
+ // BaseRecordID 差异或 MySQL 日志备份依赖的全量记录 ID(全量记录为 0)。
BaseRecordID uint `gorm:"column:base_record_id;index;not null;default:0" json:"baseRecordId"`
// Manifest 全量备份的条目清单(JSON),供后续差异备份比对;差异记录为空。
Manifest string `gorm:"column:manifest;type:text" json:"-"`
diff --git a/server/internal/model/restore_record.go b/server/internal/model/restore_record.go
index 46e8cee..0a1f78c 100644
--- a/server/internal/model/restore_record.go
+++ b/server/internal/model/restore_record.go
@@ -11,6 +11,7 @@ const (
)
type RestoreRecord struct {
+ RestoreTime *time.Time `gorm:"column:restore_time" json:"restoreTime,omitempty"`
ID uint `gorm:"primaryKey" json:"id"`
BackupRecordID uint `gorm:"column:backup_record_id;index;not null" json:"backupRecordId"`
BackupRecord BackupRecord `json:"backupRecord,omitempty"`
diff --git a/server/internal/repository/backup_record_repository.go b/server/internal/repository/backup_record_repository.go
index 8154fd9..d60eeed 100644
--- a/server/internal/repository/backup_record_repository.go
+++ b/server/internal/repository/backup_record_repository.go
@@ -151,11 +151,11 @@ func (r *GormBackupRecordRepository) ListSuccessfulByTask(ctx context.Context, t
return items, nil
}
-// CountDependentDifferentials 统计依赖某全量记录(作为基线)的成功差异备份数量。
+// CountDependentDifferentials 统计成功或执行中的差异/MySQL 日志对全量基线的依赖。
func (r *GormBackupRecordRepository) CountDependentDifferentials(ctx context.Context, baseID uint) (int64, error) {
var count int64
err := r.db.WithContext(ctx).Model(&model.BackupRecord{}).
- Where("base_record_id = ? AND backup_kind = ? AND status = ?", baseID, model.BackupKindDifferential, model.BackupRecordStatusSuccess).
+ Where("base_record_id = ? AND backup_kind IN ? AND status IN ?", baseID, []string{model.BackupKindDifferential, model.BackupKindBinlog}, []string{model.BackupRecordStatusSuccess, model.BackupRecordStatusRunning}).
Count(&count).Error
return count, err
}
diff --git a/server/internal/service/agent_service.go b/server/internal/service/agent_service.go
index 6325fff..97edd5c 100644
--- a/server/internal/service/agent_service.go
+++ b/server/internal/service/agent_service.go
@@ -19,6 +19,7 @@ import (
"backupx/server/internal/repository"
"backupx/server/internal/storage"
"backupx/server/internal/storage/codec"
+ backupcrypto "backupx/server/pkg/crypto"
"go.uber.org/zap"
)
@@ -176,6 +177,9 @@ func agentCommandFailureMessage(message string) string {
// AgentTaskSpec 给 Agent 返回的任务规格,包含解密后的存储配置,供 Agent 直接执行。
// 敏感信息:此接口仅供 Agent 调用(token 认证),避免通过公共 API 泄露。
type AgentTaskSpec struct {
+ MySQLPITR bool `json:"mysqlPitr"`
+ MySQLBase *backup.MySQLCheckpoint `json:"mysqlBase,omitempty"`
+ BaseRecordID uint `json:"baseRecordId,omitempty"`
TaskID uint `json:"taskId"`
Name string `json:"name"`
Type string `json:"type"`
@@ -190,6 +194,7 @@ type AgentTaskSpec struct {
DBPath string `json:"dbPath,omitempty"`
ExtraConfig string `json:"extraConfig,omitempty"`
Compression string `json:"compression"`
+ EncryptionKey string `json:"encryptionKey,omitempty"`
Encrypt bool `json:"encrypt"`
StorageTargets []AgentStorageTargetConfig `json:"storageTargets"`
}
@@ -204,7 +209,7 @@ type AgentStorageTargetConfig struct {
}
// GetTaskSpec 返回 Agent 执行任务所需的完整规格。
-func (s *AgentService) GetTaskSpec(ctx context.Context, node *model.Node, taskID uint) (*AgentTaskSpec, error) {
+func (s *AgentService) GetTaskSpec(ctx context.Context, node *model.Node, taskID uint, recordIDs ...uint) (*AgentTaskSpec, error) {
task, err := s.taskRepo.FindByID(ctx, taskID)
if err != nil {
return nil, err
@@ -215,6 +220,20 @@ func (s *AgentService) GetTaskSpec(ctx context.Context, node *model.Node, taskID
if err := s.ensureTaskSpecAccess(ctx, node, task); err != nil {
return nil, err
}
+ encryptionKey := ""
+ if task.Encrypt {
+ if len(recordIDs) != 1 || recordIDs[0] == 0 {
+ return nil, apperror.BadRequest("AGENT_ENCRYPTION_RECORD_REQUIRED", "加密备份需要升级 Agent 并指定备份记录", nil)
+ }
+ record, err := s.recordRepo.FindByID(ctx, recordIDs[0])
+ if err != nil {
+ return nil, err
+ }
+ if record == nil || record.TaskID != taskID || !recordBelongsToNode(record, task, node.ID) || record.Status != model.BackupRecordStatusRunning {
+ return nil, apperror.Unauthorized("BACKUP_RECORD_FORBIDDEN", "备份记录不属于当前节点的运行任务", nil)
+ }
+ encryptionKey = hex.EncodeToString(backupcrypto.RecordKey(s.cipher.Key(), record.ID))
+ }
// 解密数据库密码(若有)
dbPassword := ""
if task.DBPasswordCiphertext != "" {
@@ -261,7 +280,29 @@ func (s *AgentService) GetTaskSpec(ctx context.Context, node *model.Node, taskID
TransferMode: transferMode,
})
}
+ baseID, mysqlBase, err := resolveMySQLBase(ctx, s.recordRepo, task, node.ID, time.Now().UTC())
+ if err != nil {
+ return nil, err
+ }
+ if baseID > 0 {
+ if len(recordIDs) != 1 {
+ return nil, apperror.BadRequest("MYSQL_PITR_INVALID", "PITR 需要升级 Agent 并指定备份记录", nil)
+ }
+ record, err := s.recordRepo.FindByID(ctx, recordIDs[0])
+ if err != nil {
+ return nil, err
+ }
+ if record == nil || record.TaskID != taskID || !recordBelongsToNode(record, task, node.ID) || record.Status != model.BackupRecordStatusRunning {
+ return nil, apperror.Unauthorized("BACKUP_RECORD_FORBIDDEN", "备份记录不属于当前运行任务", nil)
+ }
+ record.BackupKind, record.BaseRecordID = model.BackupKindBinlog, baseID
+ if err := s.recordRepo.Update(ctx, record); err != nil {
+ return nil, err
+ }
+ }
return &AgentTaskSpec{
+ MySQLPITR: task.Type == model.BackupTaskTypeMySQL && backup.MySQLPITREnabled(task.ExtraConfig),
+ MySQLBase: mysqlBase, BaseRecordID: baseID,
TaskID: task.ID,
Name: task.Name,
Type: task.Type,
@@ -277,6 +318,7 @@ func (s *AgentService) GetTaskSpec(ctx context.Context, node *model.Node, taskID
ExtraConfig: task.ExtraConfig,
Compression: task.Compression,
Encrypt: task.Encrypt,
+ EncryptionKey: encryptionKey,
StorageTargets: storageTargets,
}, nil
}
@@ -393,6 +435,8 @@ func (s *AgentService) ensureTaskSpecAccess(ctx context.Context, node *model.Nod
// AgentRecordUpdate Agent 上报备份记录的最终状态。
type AgentRecordUpdate struct {
+ MySQLCheckpoint *backup.MySQLCheckpoint `json:"mysqlCheckpoint,omitempty"`
+ BaseRecordID uint `json:"baseRecordId,omitempty"`
Status string `json:"status"` // running | success | failed
FileName string `json:"fileName,omitempty"`
FileSize int64 `json:"fileSize,omitempty"`
@@ -517,6 +561,48 @@ func (s *AgentService) UpdateRecord(ctx context.Context, node *model.Node, recor
}
update.Checksum = strings.ToLower(strings.TrimSpace(update.Checksum))
}
+ if update.Status == model.BackupRecordStatusSuccess && task.Type == model.BackupTaskTypeMySQL && backup.MySQLPITREnabled(task.ExtraConfig) && update.MySQLCheckpoint == nil {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "Agent 未上报 PITR 元数据,请升级 Agent", nil)
+ }
+ if update.Status == model.BackupRecordStatusSuccess && task.Encrypt && !strings.HasSuffix(strings.ToLower(update.FileName), ".enc") {
+ return apperror.BadRequest("AGENT_ENCRYPTION_REQUIRED", "加密任务不能上报未加密产物", nil)
+ }
+ if update.MySQLCheckpoint != nil {
+ checkpoint := update.MySQLCheckpoint
+ if task.Type != model.BackupTaskTypeMySQL || !backup.MySQLPITREnabled(task.ExtraConfig) {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "任务未启用 MySQL PITR", nil)
+ }
+ if err := checkpoint.Validate(); err != nil {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", err.Error(), err)
+ }
+ if checkpoint.Source != backup.MySQLSource(backup.DatabaseSpec{Host: task.DBHost, Port: task.DBPort}) {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "MySQL 数据源不匹配", nil)
+ }
+ if !checkpoint.Full {
+ base, err := s.recordRepo.FindByID(ctx, update.BaseRecordID)
+ if err != nil {
+ return err
+ }
+ if base == nil || base.TaskID != task.ID || base.NodeID != record.NodeID || base.Status != model.BackupRecordStatusSuccess || base.BackupKind != model.BackupKindFull {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "MySQL 基线不存在或不匹配", nil)
+ }
+ var metadata backup.MySQLCheckpoint
+ if err := json.Unmarshal([]byte(base.MySQLCheckpoint), &metadata); err != nil {
+ return err
+ }
+ if metadata.ServerUUID != checkpoint.ServerUUID || metadata.StartFile != checkpoint.StartFile || metadata.StartPosition != checkpoint.StartPosition || !metadata.BaselineAt.Equal(checkpoint.BaselineAt) {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "MySQL 日志与基线不匹配", nil)
+ }
+ record.BackupKind, record.BaseRecordID = model.BackupKindBinlog, base.ID
+ } else {
+ record.BackupKind, record.BaseRecordID = model.BackupKindFull, 0
+ }
+ metadata, err := json.Marshal(checkpoint)
+ if err != nil {
+ return err
+ }
+ record.MySQLCheckpoint = string(metadata)
+ }
if update.Status != "" {
record.Status = update.Status
}
diff --git a/server/internal/service/agent_service_test.go b/server/internal/service/agent_service_test.go
index b5b4995..cbdfc1b 100644
--- a/server/internal/service/agent_service_test.go
+++ b/server/internal/service/agent_service_test.go
@@ -887,3 +887,35 @@ type failingUpdateTaskRepo struct {
func (r *failingUpdateTaskRepo) Update(context.Context, *model.BackupTask) error {
return r.err
}
+
+func TestAgentEncryptionKeyIsRecordScopedAndOwnerOnly(t *testing.T) {
+ svc, db, records, _, owner, other := newAgentServicePoolTestHarness(t)
+ ctx := context.Background()
+ if err := db.Model(&model.BackupTask{}).Where("id = ?", 1).Update("encrypt", true).Error; err != nil {
+ t.Fatal(err)
+ }
+ if _, err := svc.GetTaskSpec(ctx, owner, 1); err == nil {
+ t.Fatal("old Agent received encrypted task without record")
+ }
+ spec, err := svc.GetTaskSpec(ctx, owner, 1, 1)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if spec.EncryptionKey == "" || spec.EncryptionKey == fmt.Sprintf("%x", svc.cipher.Key()) {
+ t.Fatal("missing scoped key or exposed Master key")
+ }
+ if _, err := svc.GetTaskSpec(ctx, other, 1, 1); err == nil {
+ t.Fatal("other node received key")
+ }
+ record, err := records.FindByID(ctx, 1)
+ if err != nil {
+ t.Fatal(err)
+ }
+ record.Status = model.BackupRecordStatusSuccess
+ if err := records.Update(ctx, record); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := svc.GetTaskSpec(ctx, owner, 1, 1); err == nil {
+ t.Fatal("completed record received backup key")
+ }
+}
diff --git a/server/internal/service/backup_execution_service.go b/server/internal/service/backup_execution_service.go
index 88d7cef..f743a6e 100644
--- a/server/internal/service/backup_execution_service.go
+++ b/server/internal/service/backup_execution_service.go
@@ -856,6 +856,7 @@ func (s *BackupExecutionService) executeTask(ctx context.Context, task *model.Ba
backupKind := model.BackupKindFull
var baseRecordID uint
var manifestJSON string
+ var mysqlCheckpoint string
var repositoryProviders map[uint]storage.StorageProvider
completeRecord := func() {
persistCtx, cancel := finalizationContext(ctx)
@@ -878,6 +879,7 @@ func (s *BackupExecutionService) executeTask(ctx context.Context, task *model.Ba
result.BackupKind = backupKind
result.BaseRecordID = baseRecordID
result.Manifest = manifestJSON
+ result.MySQLCheckpoint = mysqlCheckpoint
}
result.LogContent = logger.String()
if finalizeErr := s.finalizeRecord(persistCtx, task, recordID, startedAt, result); finalizeErr != nil {
@@ -974,6 +976,27 @@ func (s *BackupExecutionService) executeTask(ctx context.Context, task *model.Ba
baseRecordID = baseID
logger.Infof("差异备份模式:基于全量备份 #%d 仅打包变更", baseID)
}
+ if spec.MySQLPITR {
+ baseID, base, err := resolveMySQLBase(ctx, s.records, task, task.NodeID, startedAt)
+ if err != nil {
+ errMessage = err.Error()
+ logger.Errorf("读取 MySQL 基线失败:%v", err)
+ return
+ }
+ spec.MySQLBase, baseRecordID = base, baseID
+ if baseID > 0 {
+ record, err := s.records.FindByID(ctx, recordID)
+ if err != nil || record == nil {
+ errMessage = "无法为 MySQL 日志归档保留基线"
+ return
+ }
+ record.BackupKind, record.BaseRecordID = model.BackupKindBinlog, baseID
+ if err := s.records.Update(ctx, record); err != nil {
+ errMessage = err.Error()
+ return
+ }
+ }
+ }
runner, err := s.runnerRegistry.Runner(spec.Type)
if err != nil {
errMessage = err.Error()
@@ -1001,6 +1024,18 @@ func (s *BackupExecutionService) executeTask(ctx context.Context, task *model.Ba
} else {
backupKind = model.BackupKindFull
}
+ if result.MySQLCheckpoint != nil {
+ metadata, err := json.Marshal(result.MySQLCheckpoint)
+ if err != nil {
+ errMessage = err.Error()
+ return
+ }
+ // Persist checkpoint with the terminal record, never advertise a failed upload as a baseline.
+ mysqlCheckpoint = string(metadata)
+ if !result.MySQLCheckpoint.Full {
+ backupKind = model.BackupKindBinlog
+ }
+ }
finalPath := result.ArtifactPath
if strings.EqualFold(task.Compression, "gzip") && !strings.HasSuffix(strings.ToLower(finalPath), ".gz") {
logger.Infof("开始压缩备份文件")
@@ -1249,6 +1284,7 @@ func (s *BackupExecutionService) finalizeRecord(ctx context.Context, task *model
record.BackupKind = result.BackupKind
record.BaseRecordID = result.BaseRecordID
record.Manifest = result.Manifest
+ record.MySQLCheckpoint = result.MySQLCheckpoint
}
record.DurationSeconds = int(completedAt.Sub(startedAt).Seconds())
record.ErrorMessage = strings.TrimSpace(result.ErrorMessage)
diff --git a/server/internal/service/backup_record_service.go b/server/internal/service/backup_record_service.go
index 308ebfa..793781c 100644
--- a/server/internal/service/backup_record_service.go
+++ b/server/internal/service/backup_record_service.go
@@ -43,6 +43,7 @@ type BackupRecordSummary struct {
}
type BackupRecordDetail struct {
+ MySQLCheckpoint *backup.MySQLCheckpoint `json:"mysqlCheckpoint,omitempty"`
BackupRecordSummary
LogContent string `json:"logContent"`
LogEvents []backup.LogEvent `json:"logEvents,omitempty"`
@@ -203,6 +204,12 @@ func toBackupRecordSummary(item *model.BackupRecord) BackupRecordSummary {
func toBackupRecordDetail(item *model.BackupRecord, logHub *backup.LogHub) *BackupRecordDetail {
detail := &BackupRecordDetail{BackupRecordSummary: toBackupRecordSummary(item), LogContent: item.LogContent}
+ if item.MySQLCheckpoint != "" {
+ var checkpoint backup.MySQLCheckpoint
+ if err := json.Unmarshal([]byte(item.MySQLCheckpoint), &checkpoint); err == nil {
+ detail.MySQLCheckpoint = &checkpoint
+ }
+ }
if item.Status == "running" && logHub != nil {
events := logHub.Snapshot(item.ID)
detail.LogEvents = events
diff --git a/server/internal/service/backup_task_service.go b/server/internal/service/backup_task_service.go
index 655de88..918cf12 100644
--- a/server/internal/service/backup_task_service.go
+++ b/server/internal/service/backup_task_service.go
@@ -564,9 +564,27 @@ func (s *BackupTaskService) validateInput(ctx context.Context, existing *model.B
return apperror.BadRequest("BACKUP_TASK_INVALID",
"固定执行节点与节点池标签只能选其一", nil)
}
- if input.Encrypt && (strings.TrimSpace(input.NodePoolTag) != "" || (fixedNode != nil && !fixedNode.IsLocal)) {
- return apperror.BadRequest("BACKUP_TASK_REMOTE_ENCRYPT_UNSUPPORTED",
- "远程节点暂不支持加密备份。请关闭加密,或将任务固定在 Master 本机执行。", nil)
+ if value, exists := input.ExtraConfig["mysqlPitr"]; exists {
+ if _, ok := value.(bool); !ok {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "mysqlPitr 必须为布尔值", nil)
+ }
+ }
+ if enabled, _ := input.ExtraConfig["mysqlPitr"].(bool); enabled {
+ if input.Type != "mysql" || strings.TrimSpace(input.DBName) != "*" {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "MySQL PITR 必须备份整个实例(数据库名称填写 *)", nil)
+ }
+ if strings.TrimSpace(input.NodePoolTag) != "" {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "MySQL PITR 请绑定固定执行节点,避免切换数据源", nil)
+ }
+ if input.VerifyEnabled {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "PITR 请在隔离实例演练恢复,暂不支持自动验证", nil)
+ }
+ if value, ok := input.ExtraConfig["fullIntervalHours"]; ok {
+ hours, ok := value.(float64)
+ if !ok || hours < 1 || hours > 720 || hours != float64(int(hours)) {
+ return apperror.BadRequest("MYSQL_PITR_INVALID", "全量间隔须为 1 至 720 小时的整数", nil)
+ }
+ }
}
if strings.EqualFold(strings.TrimSpace(input.BackupMode), model.BackupModeDifferential) {
if input.Type != model.BackupTaskTypeFile {
diff --git a/server/internal/service/backup_task_service_test.go b/server/internal/service/backup_task_service_test.go
index 120a0b5..1e77262 100644
--- a/server/internal/service/backup_task_service_test.go
+++ b/server/internal/service/backup_task_service_test.go
@@ -4,7 +4,6 @@ import (
"context"
"errors"
"path/filepath"
- "strings"
"testing"
"backupx/server/internal/apperror"
@@ -61,7 +60,7 @@ func newBackupTaskServiceForTest(t *testing.T) (*BackupTaskService, repository.S
return service, targets, tasks
}
-func TestBackupTaskServiceRejectsEncryptedRemoteTasks(t *testing.T) {
+func TestBackupTaskServiceAcceptsEncryptedRemoteTasks(t *testing.T) {
ctx := context.Background()
service, targets, _ := newBackupTaskServiceForTest(t)
service.SetNodeRepository(&nodeRepoStub{nodes: []model.Node{
@@ -84,8 +83,8 @@ func TestBackupTaskServiceRejectsEncryptedRemoteTasks(t *testing.T) {
MaxBackups: 10,
Encrypt: true,
})
- if err == nil || !strings.Contains(err.Error(), "远程节点暂不支持加密备份") {
- t.Fatalf("expected encrypted node-pool task to be rejected, got %v", err)
+ if err != nil {
+ t.Fatalf("expected encrypted node-pool task to be accepted, got %v", err)
}
created, err := service.Create(ctx, BackupTaskUpsertInput{
@@ -132,8 +131,8 @@ func TestBackupTaskServiceRejectsEncryptedRemoteTasks(t *testing.T) {
MaxBackups: 10,
Encrypt: true,
})
- if err == nil || !strings.Contains(err.Error(), "远程节点暂不支持加密备份") {
- t.Fatalf("expected encrypted fixed-node update to be rejected, got %v", err)
+ if err != nil {
+ t.Fatalf("expected encrypted fixed-node update to be accepted, got %v", err)
}
}
@@ -314,3 +313,32 @@ func TestSQLServerTaskValidation(t *testing.T) {
}
}
}
+
+func TestMySQLPITRTaskValidation(t *testing.T) {
+ ctx := context.Background()
+ svc, targets, _ := newBackupTaskServiceForTest(t)
+ if err := targets.Create(ctx, &model.StorageTarget{Name: "local", Type: "local_disk", Enabled: true, ConfigCiphertext: "ciphertext", ConfigVersion: 1, LastTestStatus: "unknown"}); err != nil {
+ t.Fatal(err)
+ }
+ cases := []struct {
+ name string
+ db string
+ pool string
+ verify bool
+ extra map[string]any
+ valid bool
+ }{
+ {name: "valid", db: "*", extra: map[string]any{"mysqlPitr": true, "fullIntervalHours": float64(24)}, valid: true},
+ {name: "one-db", db: "app", extra: map[string]any{"mysqlPitr": true}},
+ {name: "node-pool", db: "*", pool: "db", extra: map[string]any{"mysqlPitr": true}},
+ {name: "auto-verify", db: "*", verify: true, extra: map[string]any{"mysqlPitr": true}},
+ {name: "invalid-toggle", db: "*", extra: map[string]any{"mysqlPitr": "true"}},
+ {name: "fractional-interval", db: "*", extra: map[string]any{"mysqlPitr": true, "fullIntervalHours": 1.5}},
+ }
+ for _, tc := range cases {
+ _, err := svc.Create(ctx, BackupTaskUpsertInput{Name: tc.name, Type: "mysql", Enabled: true, DBHost: "db", DBPort: 3306, DBUser: "backup", DBPassword: "secret", DBName: tc.db, StorageTargetID: 1, NodePoolTag: tc.pool, VerifyEnabled: tc.verify, ExtraConfig: tc.extra, Compression: "gzip"})
+ if (err == nil) != tc.valid {
+ t.Fatalf("%s: valid=%v err=%v", tc.name, tc.valid, err)
+ }
+ }
+}
diff --git a/server/internal/service/execution_helpers.go b/server/internal/service/execution_helpers.go
index 9585f3e..27117b9 100644
--- a/server/internal/service/execution_helpers.go
+++ b/server/internal/service/execution_helpers.go
@@ -167,7 +167,8 @@ func buildBackupTaskSpec(cipher *codec.ConfigCipher, task *model.BackupTask, sta
excludePatterns := []string{}
if strings.TrimSpace(task.ExcludePatterns) != "" {
if err := json.Unmarshal([]byte(task.ExcludePatterns), &excludePatterns); err != nil {
- return backup.TaskSpec{}, apperror.Internal("BACKUP_TASK_DECODE_FAILED", "无法解析排除规则", err)
+ return backup.TaskSpec{
+ MySQLPITR: task.Type == model.BackupTaskTypeMySQL && backup.MySQLPITREnabled(task.ExtraConfig)}, apperror.Internal("BACKUP_TASK_DECODE_FAILED", "无法解析排除规则", err)
}
}
password := ""
diff --git a/server/internal/service/mysql_pitr.go b/server/internal/service/mysql_pitr.go
new file mode 100644
index 0000000..348a6d4
--- /dev/null
+++ b/server/internal/service/mysql_pitr.go
@@ -0,0 +1,44 @@
+package service
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "time"
+
+ "backupx/server/internal/backup"
+ "backupx/server/internal/model"
+ "backupx/server/internal/repository"
+)
+
+// Each log archive contains all binlogs since its full baseline; no intermediate
+// record is required for recovery, and the existing base retention lock applies.
+func resolveMySQLBase(ctx context.Context, records repository.BackupRecordRepository, task *model.BackupTask, nodeID uint, now time.Time) (uint, *backup.MySQLCheckpoint, error) {
+ if task.Type != model.BackupTaskTypeMySQL || !backup.MySQLPITREnabled(task.ExtraConfig) {
+ return 0, nil, nil
+ }
+ items, err := records.ListSuccessfulByTask(ctx, task.ID)
+ if err != nil {
+ return 0, nil, err
+ }
+ for _, item := range items {
+ if item.BackupKind != model.BackupKindFull || item.MySQLCheckpoint == "" || item.NodeID != nodeID {
+ continue
+ }
+ var checkpoint backup.MySQLCheckpoint
+ if err := json.Unmarshal([]byte(item.MySQLCheckpoint), &checkpoint); err != nil {
+ return 0, nil, fmt.Errorf("decode MySQL baseline: %w", err)
+ }
+ if err := checkpoint.Validate(); err != nil {
+ return 0, nil, err
+ }
+ if !checkpoint.Full {
+ return 0, nil, fmt.Errorf("invalid MySQL full baseline")
+ }
+ if now.Sub(item.StartedAt) >= backup.MySQLFullInterval(task.ExtraConfig) || checkpoint.Source != backup.MySQLSource(backup.DatabaseSpec{Host: task.DBHost, Port: task.DBPort}) {
+ return 0, nil, nil
+ }
+ return item.ID, &checkpoint, nil
+ }
+ return 0, nil, nil
+}
diff --git a/server/internal/service/mysql_pitr_test.go b/server/internal/service/mysql_pitr_test.go
new file mode 100644
index 0000000..21f9a02
--- /dev/null
+++ b/server/internal/service/mysql_pitr_test.go
@@ -0,0 +1,149 @@
+package service
+
+import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+ "time"
+
+ "backupx/server/internal/backup"
+ "backupx/server/internal/model"
+)
+
+func TestMySQLPITRMetadataPersistenceAndChain(t *testing.T) {
+ ctx := context.Background()
+ execution, _, tasks, _, records, _, _ := newExecutionTestServices(t)
+ task, err := tasks.FindByID(ctx, 1)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if task == nil {
+ t.Fatal("missing fixture task")
+ }
+ now := time.Now().UTC().Add(-2 * time.Hour).Truncate(time.Second)
+ task.Type = "mysql"
+ task.DBHost = "db"
+ task.DBPort = 3306
+ task.DBName = "*"
+ task.ExtraConfig = `{"mysqlPitr":true}`
+ if err := tasks.Update(ctx, task); err != nil {
+ t.Fatal(err)
+ }
+ checkpoint := backup.MySQLCheckpoint{ServerUUID: "uuid", Source: "db:3306", StartFile: "bin.000001", StartPosition: 4, EndFile: "bin.000001", EndPosition: 80, CapturedAt: now, BaselineAt: now, Full: true}
+ raw, err := json.Marshal(checkpoint)
+ if err != nil {
+ t.Fatal(err)
+ }
+ full := &model.BackupRecord{TaskID: task.ID, StorageTargetID: task.StorageTargetID, Status: model.BackupRecordStatusRunning, StartedAt: now}
+ if err := records.Create(ctx, full); err != nil {
+ t.Fatal(err)
+ }
+ if err := execution.finalizeRecord(ctx, task, full.ID, now, model.BackupRecord{Status: model.BackupRecordStatusSuccess, BackupKind: model.BackupKindFull, StoragePath: "full.pitr.tar", MySQLCheckpoint: string(raw)}); err != nil {
+ t.Fatal(err)
+ }
+ stored, err := records.FindByID(ctx, full.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if stored.MySQLCheckpoint != string(raw) {
+ t.Fatal("checkpoint lost in finalization")
+ }
+ id, base, err := resolveMySQLBase(ctx, records, task, 0, now.Add(time.Hour))
+ if err != nil || id != full.ID || base == nil {
+ t.Fatalf("base resolution: %d %+v %v", id, base, err)
+ }
+ if id, _, err := resolveMySQLBase(ctx, records, task, 0, now.Add(25*time.Hour)); err != nil || id != 0 {
+ t.Fatalf("old base not rotated: %d %v", id, err)
+ }
+ checkpoint.Full = false
+ checkpoint.EndFile = "bin.000002"
+ checkpoint.Files = []string{"bin.000001", "bin.000002"}
+ checkpoint.CapturedAt = now.Add(time.Hour)
+ raw, err = json.Marshal(checkpoint)
+ if err != nil {
+ t.Fatal(err)
+ }
+ log := &model.BackupRecord{TaskID: task.ID, StorageTargetID: task.StorageTargetID, Status: model.BackupRecordStatusSuccess, BackupKind: model.BackupKindBinlog, BaseRecordID: full.ID, StoragePath: "logs.pitr.tar", MySQLCheckpoint: string(raw), StartedAt: now.Add(time.Hour)}
+ if err := records.Create(ctx, log); err != nil {
+ t.Fatal(err)
+ }
+ service := &RestoreService{records: records}
+ chain, err := service.buildRestoreChain(ctx, log)
+ if err != nil || len(chain) != 2 || chain[0].ID != full.ID {
+ t.Fatalf("chain: %v %v", chain, err)
+ }
+ if err := execution.DeleteRecord(ctx, full.ID); err == nil {
+ t.Fatal("deleted baseline with retained binlogs")
+ }
+ log.MySQLCheckpoint = strings.ReplaceAll(log.MySQLCheckpoint, "uuid", "other")
+ if _, err := service.buildRestoreChain(ctx, log); err == nil {
+ t.Fatal("accepted mismatched server identity")
+ }
+}
+
+func TestMySQLPITRRestoreTimeAndAgentChain(t *testing.T) {
+ h := newRestoreTestHarness(t, true)
+ ctx := context.Background()
+ task, err := h.tasks.FindByID(ctx, 1)
+ if err != nil {
+ t.Fatal(err)
+ }
+ task.Type = "mysql"
+ task.DBHost = "db"
+ task.DBPort = 3306
+ task.DBName = "*"
+ task.ExtraConfig = `{"mysqlPitr":true}`
+ if err := h.tasks.Update(ctx, task); err != nil {
+ t.Fatal(err)
+ }
+ now := time.Now().UTC().Add(-2 * time.Hour).Truncate(time.Second)
+ checkpoint := backup.MySQLCheckpoint{ServerUUID: "uuid", Source: "db:3306", StartFile: "bin.000001", StartPosition: 4, EndFile: "bin.000001", EndPosition: 80, CapturedAt: now, BaselineAt: now, Full: true}
+ raw, err := json.Marshal(checkpoint)
+ if err != nil {
+ t.Fatal(err)
+ }
+ full := &model.BackupRecord{TaskID: task.ID, NodeID: task.NodeID, StorageTargetID: task.StorageTargetID, Status: model.BackupRecordStatusSuccess, BackupKind: model.BackupKindFull, StoragePath: "full.pitr.tar.enc", FileName: "full.pitr.tar.enc", MySQLCheckpoint: string(raw), StartedAt: now}
+ if err := h.records.Create(ctx, full); err != nil {
+ t.Fatal(err)
+ }
+ checkpoint.Full = false
+ checkpoint.EndFile = "bin.000002"
+ checkpoint.Files = []string{"bin.000001", "bin.000002"}
+ checkpoint.CapturedAt = now.Add(time.Hour)
+ raw, err = json.Marshal(checkpoint)
+ if err != nil {
+ t.Fatal(err)
+ }
+ log := &model.BackupRecord{TaskID: task.ID, NodeID: task.NodeID, StorageTargetID: task.StorageTargetID, Status: model.BackupRecordStatusSuccess, BackupKind: model.BackupKindBinlog, BaseRecordID: full.ID, StoragePath: "logs.pitr.tar.enc", FileName: "logs.pitr.tar.enc", MySQLCheckpoint: string(raw), StartedAt: now.Add(time.Hour)}
+ if err := h.records.Create(ctx, log); err != nil {
+ t.Fatal(err)
+ }
+ for _, value := range []string{"bad", now.Format("2006-01-02T15:04:05"), now.Add(-time.Second).Format(time.RFC3339), now.Add(time.Hour).Format(time.RFC3339)} {
+ if _, err := h.service.StartSelective(ctx, log.ID, nil, "", "tester", value); err == nil {
+ t.Fatalf("accepted invalid restore time %s", value)
+ }
+ }
+ target := now.Add(30 * time.Minute)
+ detail, err := h.service.StartSelective(ctx, log.ID, nil, "", "tester", target.Format(time.RFC3339))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if detail.RestoreTime == nil || !detail.RestoreTime.Equal(target) {
+ t.Fatal("restore time not preserved")
+ }
+ node, err := h.nodes.FindByID(ctx, task.NodeID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ spec, err := h.service.GetAgentRestoreSpec(ctx, node, detail.ID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(spec.Artifacts) != 2 || spec.Artifacts[0].BackupRecordID != full.ID || spec.Artifacts[1].BackupRecordID != log.ID || spec.Artifacts[0].EncryptionKey == spec.Artifacts[1].EncryptionKey || spec.RestoreTime == nil || !spec.RestoreTime.Equal(target) {
+ t.Fatalf("bad restore spec: %+v", spec)
+ }
+ if _, err := h.service.DownloadAgentArtifact(ctx, node, detail.ID, 999999); err == nil {
+ t.Fatal("downloaded object outside restore chain")
+ }
+}
diff --git a/server/internal/service/restore_service.go b/server/internal/service/restore_service.go
index 2f5febd..af28cef 100644
--- a/server/internal/service/restore_service.go
+++ b/server/internal/service/restore_service.go
@@ -2,6 +2,7 @@ package service
import (
"context"
+ "encoding/hex"
"encoding/json"
"errors"
"fmt"
@@ -18,6 +19,7 @@ import (
"backupx/server/internal/repository"
"backupx/server/internal/storage"
"backupx/server/internal/storage/codec"
+ backupcrypto "backupx/server/pkg/crypto"
)
// RestoreService 管理恢复记录生命周期并在集群中路由执行。
@@ -103,6 +105,7 @@ func (s *RestoreService) SetEventDispatcher(dispatcher EventDispatcher) {
// RestoreRecordSummary 列表项。
type RestoreRecordSummary struct {
+ RestoreTime *time.Time `json:"restoreTime,omitempty"`
ID uint `json:"id"`
BackupRecordID uint `json:"backupRecordId"`
TaskID uint `json:"taskId"`
@@ -135,7 +138,7 @@ func (s *RestoreService) Start(ctx context.Context, backupRecordID uint, trigger
// StartSelective 启动恢复。两个可选项均仅适用于本机文件备份:
// - selectedPaths 非空时仅恢复选中的文件/目录(及其子项),用于按需(选择性)恢复;
// - targetPath 非空时把归档恢复到该绝对目录而非原始源路径父目录(迁移/测试/并排恢复)。
-func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint, selectedPaths []string, targetPath string, triggeredBy string) (*RestoreRecordDetail, error) {
+func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint, selectedPaths []string, targetPath string, triggeredBy string, restoreTimes ...string) (*RestoreRecordDetail, error) {
record, err := s.records.FindByID(ctx, backupRecordID)
if err != nil {
return nil, apperror.Internal("BACKUP_RECORD_GET_FAILED", "无法获取备份记录", err)
@@ -179,8 +182,32 @@ func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint
}
}
+ var restoreTime *time.Time
+ if len(restoreTimes) > 0 && strings.TrimSpace(restoreTimes[0]) != "" {
+ parsed, err := time.Parse(time.RFC3339, strings.TrimSpace(restoreTimes[0]))
+ if err != nil {
+ return nil, apperror.BadRequest("MYSQL_PITR_TIME_INVALID", "恢复时间须为带时区的 RFC3339 格式", err)
+ }
+ parsed = parsed.UTC().Truncate(time.Second)
+ var checkpoint backup.MySQLCheckpoint
+ if task.Type != model.BackupTaskTypeMySQL || record.BackupKind != model.BackupKindBinlog || json.Unmarshal([]byte(record.MySQLCheckpoint), &checkpoint) != nil {
+ return nil, apperror.BadRequest("MYSQL_PITR_TIME_INVALID", "指定时间点恢复需要选择 MySQL binlog 备份", nil)
+ }
+ if err := checkpoint.Validate(); err != nil {
+ return nil, err
+ }
+ if parsed.Before(checkpoint.BaselineAt) || !parsed.Before(checkpoint.CapturedAt) {
+ return nil, apperror.BadRequest("MYSQL_PITR_TIME_INVALID", "恢复时间须处于全量基线完成至本次日志归档截止之间(不含截止秒)", nil)
+ }
+ parsed = parsed.UTC()
+ restoreTime = &parsed
+ }
+ if _, err := s.buildRestoreChain(ctx, record); err != nil {
+ return nil, apperror.BadRequest("RESTORE_CHAIN_INVALID", err.Error(), err)
+ }
restore := &model.RestoreRecord{
BackupRecordID: backupRecordID,
+ RestoreTime: restoreTime,
TaskID: record.TaskID,
NodeID: restoreNodeID,
TargetPath: targetPath,
@@ -226,7 +253,7 @@ func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint
// 本地节点:异步执行
run := func(runCtx context.Context) {
- s.executeLocally(runCtx, restore.ID, task, record, selectedPaths, targetPath)
+ s.executeLocally(runCtx, restore.ID, task, record, selectedPaths, targetPath, restoreTime)
}
if !s.async(run) {
message := "服务正在关闭,恢复任务未启动"
@@ -259,7 +286,7 @@ func (s *RestoreService) resolveRemoteNode(ctx context.Context, nodeID uint) *mo
}
// executeLocally 在 Master 本地执行恢复。
-func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, task *model.BackupTask, backupRecord *model.BackupRecord, selectedPaths []string, targetPath string) {
+func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, task *model.BackupTask, backupRecord *model.BackupRecord, selectedPaths []string, targetPath string, restoreTimes ...*time.Time) {
logger := backup.NewExecutionLogger(restoreID, s.logHub)
status := model.RestoreRecordStatusFailed
errMessage := ""
@@ -322,6 +349,9 @@ func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, tas
}
defer os.RemoveAll(tempDir)
+ if len(restoreTimes) > 0 && restoreTimes[0] != nil {
+ spec.RestoreTime = *restoreTimes[0]
+ }
// 恢复链:全量 → [自身];差异 → [基线全量, 自身],按序应用(全量铺底,差异覆盖并删除)。
chain, chainErr := s.buildRestoreChain(ctx, backupRecord)
if chainErr != nil {
@@ -329,6 +359,31 @@ func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, tas
logger.Errorf("%v", chainErr)
return
}
+ if mysqlRunner, ok := runner.(*backup.MySQLRunner); ok {
+ paths := make([]string, 0, len(chain))
+ for i := range chain {
+ artifact, err := s.downloadRestoreArtifact(ctx, &chain[i], tempDir, logger)
+ if err == nil {
+ artifact, err = mysqlRunner.PrepareRestore(ctx, spec, artifact, logger)
+ }
+ if err != nil {
+ errMessage = err.Error()
+ logger.Errorf("MySQL 恢复预检失败:%v", err)
+ return
+ }
+ paths = append(paths, artifact)
+ }
+ for _, artifact := range paths {
+ if err := runner.Restore(ctx, spec, artifact, logger); err != nil {
+ errMessage = err.Error()
+ logger.Errorf("MySQL 恢复失败:%v", err)
+ return
+ }
+ }
+ status = model.RestoreRecordStatusSuccess
+ logger.Infof("MySQL 恢复执行成功")
+ return
+ }
logger.Infof("开始执行 %s 恢复(恢复链含 %d 个备份)", spec.Type, len(chain))
for idx := range chain {
rec := chain[idx]
@@ -348,43 +403,17 @@ func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, tas
// restoreArtifact 下载、完整性校验、解密解压并通过 runner 应用单个备份记录的归档。
// 每个记录使用独立子目录,避免恢复链中基线/差异的同名归档相互覆盖。
func (s *RestoreService) restoreArtifact(ctx context.Context, record *model.BackupRecord, spec backup.TaskSpec, runner backup.BackupRunner, parentTempDir string, logger *backup.ExecutionLogger) error {
- provider, err := s.resolveProvider(ctx, record.StorageTargetID)
- if err != nil {
- return fmt.Errorf("创建存储客户端失败:%w", err)
- }
if record.BackupKind == model.BackupKindRepository {
- logger.Infof("读取 CDC 仓库快照:%s", record.StoragePath)
- if err := backup.NewRepositoryStore(s.cipher.Key()).Restore(ctx, provider, record.StoragePath, record.Checksum, spec, logger); err != nil {
- return fmt.Errorf("恢复 CDC 仓库快照失败:%w", err)
- }
- return nil
- }
- recDir, err := os.MkdirTemp(parentTempDir, fmt.Sprintf("rec-%d-*", record.ID))
- if err != nil {
- return fmt.Errorf("创建恢复子目录失败:%w", err)
- }
- fileName := record.FileName
- if strings.TrimSpace(fileName) == "" {
- fileName = filepath.Base(record.StoragePath)
- }
- artifactPath := filepath.Join(recDir, filepath.Base(fileName))
- logger.Infof("开始下载备份文件:%s", record.StoragePath)
- reader, err := provider.Download(ctx, record.StoragePath)
- if err != nil {
- return fmt.Errorf("下载备份文件失败:%w", err)
- }
- if err := writeReaderToFile(artifactPath, reader); err != nil {
- return fmt.Errorf("写入恢复文件失败:%w", err)
- }
- // 完整性校验:解密/解压前比对 SHA-256;早期无 checksum 的备份跳过(向后兼容)。
- if record.Checksum != "" {
- if err := verifyArtifactChecksum(artifactPath, record.Checksum); err != nil {
- return fmt.Errorf("完整性校验失败:%w", err)
+ provider, err := s.resolveProvider(ctx, record.StorageTargetID)
+ if err != nil {
+ return err
}
+ logger.Infof("读取 CDC 仓库快照:%s", record.StoragePath)
+ return backup.NewRepositoryStore(s.cipher.Key()).Restore(ctx, provider, record.StoragePath, record.Checksum, spec, logger)
}
- preparedPath, err := s.prepareArtifact(artifactPath, logger)
+ preparedPath, err := s.downloadRestoreArtifact(ctx, record, parentTempDir, logger)
if err != nil {
- return fmt.Errorf("准备恢复文件失败:%w", err)
+ return err
}
return runner.Restore(ctx, spec, preparedPath, logger)
}
@@ -392,16 +421,25 @@ func (s *RestoreService) restoreArtifact(ctx context.Context, record *model.Back
// buildRestoreChain 返回恢复某记录所需、按应用顺序排列的记录链:
// 全量 → [自身];差异 → [基线全量, 自身]。基线缺失/不可用时报错,杜绝残缺恢复。
func (s *RestoreService) buildRestoreChain(ctx context.Context, record *model.BackupRecord) ([]model.BackupRecord, error) {
- if record.BackupKind != model.BackupKindDifferential || record.BaseRecordID == 0 {
+ if record.BackupKind == model.BackupKindBinlog && record.BaseRecordID == 0 {
+ return nil, fmt.Errorf("MySQL 日志归档缺少全量基线")
+ }
+ if (record.BackupKind != model.BackupKindDifferential && record.BackupKind != model.BackupKindBinlog) || record.BaseRecordID == 0 {
return []model.BackupRecord{*record}, nil
}
base, err := s.records.FindByID(ctx, record.BaseRecordID)
if err != nil || base == nil {
return nil, fmt.Errorf("差异备份的基线全量 #%d 不存在,无法恢复", record.BaseRecordID)
}
- if base.Status != model.BackupRecordStatusSuccess || strings.TrimSpace(base.StoragePath) == "" {
+ if base.Status != model.BackupRecordStatusSuccess || strings.TrimSpace(base.StoragePath) == "" || base.TaskID != record.TaskID || base.BackupKind != model.BackupKindFull {
return nil, fmt.Errorf("差异备份的基线全量 #%d 不可用,无法恢复", record.BaseRecordID)
}
+ if record.BackupKind == model.BackupKindBinlog {
+ var full, logs backup.MySQLCheckpoint
+ if json.Unmarshal([]byte(base.MySQLCheckpoint), &full) != nil || json.Unmarshal([]byte(record.MySQLCheckpoint), &logs) != nil || full.Validate() != nil || logs.Validate() != nil || !full.Full || logs.Full || full.ServerUUID != logs.ServerUUID || full.Source != logs.Source || full.StartFile != logs.StartFile || full.StartPosition != logs.StartPosition || !full.BaselineAt.Equal(logs.BaselineAt) || base.NodeID != record.NodeID {
+ return nil, fmt.Errorf("MySQL 全量基线与日志归档不匹配,无法恢复")
+ }
+ }
return []model.BackupRecord{*base, *record}, nil
}
@@ -409,6 +447,9 @@ func backupKindLabel(kind string) string {
if kind == model.BackupKindRepository {
return "CDC 仓库快照"
}
+ if kind == model.BackupKindBinlog {
+ return "MySQL binlog"
+ }
if kind == model.BackupKindDifferential {
return "差异"
}
@@ -558,7 +599,18 @@ type RestoreRecordListInput struct {
// --- Agent 侧调用接口 ---
// AgentRestoreSpec 下发给 Agent 执行恢复的完整规格。
+type AgentRestoreArtifact struct {
+ BackupRecordID uint `json:"backupRecordId"`
+ FileName string `json:"fileName"`
+ StoragePath string `json:"storagePath"`
+ Checksum string `json:"checksum"`
+ EncryptionKey string `json:"encryptionKey,omitempty"`
+ Storage AgentStorageTargetConfig `json:"storage"`
+}
+
type AgentRestoreSpec struct {
+ RestoreTime *time.Time `json:"restoreTime,omitempty"`
+ Artifacts []AgentRestoreArtifact `json:"artifacts,omitempty"`
RestoreRecordID uint `json:"restoreRecordId"`
BackupRecordID uint `json:"backupRecordId"`
TaskID uint `json:"taskId"`
@@ -574,6 +626,7 @@ type AgentRestoreSpec struct {
DBPath string `json:"dbPath,omitempty"`
ExtraConfig string `json:"extraConfig,omitempty"`
Compression string `json:"compression"`
+ EncryptionKey string `json:"encryptionKey,omitempty"`
Encrypt bool `json:"encrypt"`
Storage AgentStorageTargetConfig `json:"storage"`
StoragePath string `json:"storagePath"`
@@ -598,7 +651,7 @@ func (s *RestoreService) GetAgentRestoreSpec(ctx context.Context, node *model.No
if restore == nil {
return nil, apperror.New(404, "RESTORE_RECORD_NOT_FOUND", "恢复记录不存在", nil)
}
- if restore.NodeID != node.ID {
+ if node == nil || restore.NodeID != node.ID || restore.Status != model.RestoreRecordStatusRunning {
return nil, apperror.Unauthorized("RESTORE_RECORD_FORBIDDEN", "恢复记录不属于当前节点", nil)
}
backupRecord, err := s.records.FindByID(ctx, restore.BackupRecordID)
@@ -624,35 +677,42 @@ func (s *RestoreService) GetAgentRestoreSpec(ctx context.Context, node *model.No
}
dbPassword = string(plain)
}
- // 解密备份时使用的存储目标
- target, err := s.targets.FindByID(ctx, backupRecord.StorageTargetID)
- if err != nil {
- return nil, err
- }
- if target == nil {
- return nil, apperror.BadRequest("BACKUP_STORAGE_TARGET_INVALID", "存储目标不存在", nil)
- }
// 拆开 sourcePaths
sourcePaths := []string{}
if strings.TrimSpace(task.SourcePaths) != "" {
_ = json.Unmarshal([]byte(task.SourcePaths), &sourcePaths)
}
- transferMode := storage.TransferModeDirect
- if backupRecord.StorageTransferMode == storage.TransferModeMasterRelay {
- transferMode = storage.TransferModeMasterRelay
+ chain, err := s.buildRestoreChain(ctx, backupRecord)
+ if err != nil {
+ return nil, err
}
- var configRaw []byte
- if transferMode == storage.TransferModeDirect {
- configRaw, err = s.cipher.Decrypt(target.ConfigCiphertext)
- if err != nil {
- return nil, fmt.Errorf("decrypt storage config: %w", err)
- }
- configRaw, err = storage.ConfigForAgent(configRaw)
+ artifacts := make([]AgentRestoreArtifact, 0, len(chain))
+ for _, rec := range chain {
+ itemTarget, err := s.targets.FindByID(ctx, rec.StorageTargetID)
if err != nil {
return nil, err
}
+ if itemTarget == nil {
+ return nil, apperror.BadRequest("BACKUP_STORAGE_TARGET_INVALID", "恢复链存储目标不存在", nil)
+ }
+ mode := storage.TransferModeDirect
+ var cfg []byte
+ if rec.StorageTransferMode == storage.TransferModeMasterRelay {
+ mode = storage.TransferModeMasterRelay
+ } else {
+ cfg, err = s.cipher.Decrypt(itemTarget.ConfigCiphertext)
+ if err != nil {
+ return nil, err
+ }
+ cfg, err = storage.ConfigForAgent(cfg)
+ if err != nil {
+ return nil, err
+ }
+ }
+ artifacts = append(artifacts, AgentRestoreArtifact{BackupRecordID: rec.ID, FileName: rec.FileName, StoragePath: rec.StoragePath, Checksum: rec.Checksum, EncryptionKey: hex.EncodeToString(backupcrypto.RecordKey(s.cipher.Key(), rec.ID)), Storage: AgentStorageTargetConfig{ID: itemTarget.ID, Type: itemTarget.Type, Name: itemTarget.Name, Config: json.RawMessage(cfg), TransferMode: mode}})
}
return &AgentRestoreSpec{
+ RestoreTime: restore.RestoreTime, Artifacts: artifacts,
RestoreRecordID: restore.ID,
BackupRecordID: backupRecord.ID,
TaskID: task.ID,
@@ -668,17 +728,12 @@ func (s *RestoreService) GetAgentRestoreSpec(ctx context.Context, node *model.No
DBPath: task.DBPath,
ExtraConfig: task.ExtraConfig,
Compression: task.Compression,
- Encrypt: task.Encrypt,
- Storage: AgentStorageTargetConfig{
- ID: target.ID,
- Type: target.Type,
- Name: target.Name,
- Config: json.RawMessage(configRaw),
- TransferMode: transferMode,
- },
- StoragePath: backupRecord.StoragePath,
- FileName: backupRecord.FileName,
- Checksum: backupRecord.Checksum,
+ Encrypt: strings.HasSuffix(strings.ToLower(backupRecord.FileName), ".enc"),
+ EncryptionKey: hex.EncodeToString(backupcrypto.RecordKey(s.cipher.Key(), backupRecord.ID)),
+ Storage: artifacts[len(artifacts)-1].Storage,
+ StoragePath: backupRecord.StoragePath,
+ FileName: backupRecord.FileName,
+ Checksum: backupRecord.Checksum,
}, nil
}
@@ -689,7 +744,7 @@ type AgentArtifactDownload struct {
// DownloadAgentArtifact opens a Master-local object for authenticated streaming
// back to the Agent that owns the restore record.
-func (s *RestoreService) DownloadAgentArtifact(ctx context.Context, node *model.Node, restoreID uint) (*AgentArtifactDownload, error) {
+func (s *RestoreService) DownloadAgentArtifact(ctx context.Context, node *model.Node, restoreID uint, recordIDs ...uint) (*AgentArtifactDownload, error) {
if node == nil {
return nil, apperror.Unauthorized("RESTORE_RECORD_FORBIDDEN", "恢复记录不属于当前节点", nil)
}
@@ -713,6 +768,23 @@ func (s *RestoreService) DownloadAgentArtifact(ctx context.Context, node *model.
if record == nil {
return nil, apperror.New(404, "BACKUP_RECORD_NOT_FOUND", "源备份记录不存在", nil)
}
+ if len(recordIDs) > 0 && recordIDs[0] != record.ID {
+ chain, err := s.buildRestoreChain(ctx, record)
+ if err != nil {
+ return nil, err
+ }
+ var selected *model.BackupRecord
+ for i := range chain {
+ if chain[i].ID == recordIDs[0] {
+ selected = &chain[i]
+ break
+ }
+ }
+ if selected == nil {
+ return nil, apperror.Unauthorized("RESTORE_RECORD_FORBIDDEN", "对象不在本次恢复链中", nil)
+ }
+ record = selected
+ }
target, err := s.targets.FindByID(ctx, record.StorageTargetID)
if err != nil {
return nil, err
@@ -832,6 +904,7 @@ func (s *RestoreService) getDetail(ctx context.Context, restoreID uint) (*Restor
func toRestoreRecordSummary(item *model.RestoreRecord, nodeName string) RestoreRecordSummary {
summary := RestoreRecordSummary{
+ RestoreTime: item.RestoreTime,
ID: item.ID,
BackupRecordID: item.BackupRecordID,
TaskID: item.TaskID,
@@ -850,3 +923,39 @@ func toRestoreRecordSummary(item *model.RestoreRecord, nodeName string) RestoreR
}
return summary
}
+
+func (s *RestoreService) downloadRestoreArtifact(ctx context.Context, record *model.BackupRecord, parentTempDir string, logger *backup.ExecutionLogger) (string, error) {
+ provider, err := s.resolveProvider(ctx, record.StorageTargetID)
+ if err != nil {
+ return "", err
+ }
+
+ recDir, err := os.MkdirTemp(parentTempDir, fmt.Sprintf("rec-%d-*", record.ID))
+ if err != nil {
+ return "", fmt.Errorf("创建恢复子目录失败:%w", err)
+ }
+ fileName := record.FileName
+ if strings.TrimSpace(fileName) == "" {
+ fileName = filepath.Base(record.StoragePath)
+ }
+ artifactPath := filepath.Join(recDir, filepath.Base(fileName))
+ logger.Infof("开始下载备份文件:%s", record.StoragePath)
+ reader, err := provider.Download(ctx, record.StoragePath)
+ if err != nil {
+ return "", fmt.Errorf("下载备份文件失败:%w", err)
+ }
+ if err := writeReaderToFile(artifactPath, reader); err != nil {
+ return "", fmt.Errorf("写入恢复文件失败:%w", err)
+ }
+ // 完整性校验:解密/解压前比对 SHA-256;早期无 checksum 的备份跳过(向后兼容)。
+ if record.Checksum != "" {
+ if err := verifyArtifactChecksum(artifactPath, record.Checksum); err != nil {
+ return "", fmt.Errorf("完整性校验失败:%w", err)
+ }
+ }
+ preparedPath, err := s.prepareArtifact(artifactPath, logger)
+ if err != nil {
+ return "", fmt.Errorf("准备恢复文件失败:%w", err)
+ }
+ return preparedPath, nil
+}
diff --git a/server/pkg/crypto/file_cipher.go b/server/pkg/crypto/file_cipher.go
index 8b86bef..4b71646 100644
--- a/server/pkg/crypto/file_cipher.go
+++ b/server/pkg/crypto/file_cipher.go
@@ -70,6 +70,24 @@ func EncryptFile(key []byte, sourcePath string) (string, error) {
}
func DecryptFile(key []byte, sourcePath string) (string, error) {
+ probe, err := os.Open(sourcePath)
+ if err != nil {
+ return "", err
+ }
+ probeHeader := make([]byte, len(recordFileMagic)+8)
+ _, readErr := io.ReadFull(probe, probeHeader)
+ closeErr := probe.Close()
+ if closeErr != nil {
+ return "", closeErr
+ }
+ if readErr == nil && string(probeHeader[:len(recordFileMagic)]) == recordFileMagic {
+ id := binary.BigEndian.Uint64(probeHeader[len(recordFileMagic):])
+ if uint64(uint(id)) != id {
+ return "", fmt.Errorf("invalid encrypted record ID")
+ }
+ return DecryptRecordFile(RecordKey(key, uint(id)), uint(id), sourcePath)
+ }
+
block, err := aes.NewCipher(key)
if err != nil {
return "", fmt.Errorf("create cipher: %w", err)
diff --git a/server/pkg/crypto/record_file.go b/server/pkg/crypto/record_file.go
new file mode 100644
index 0000000..a2e0e4a
--- /dev/null
+++ b/server/pkg/crypto/record_file.go
@@ -0,0 +1,144 @@
+package backupcrypto
+
+import (
+ "crypto/aes"
+ "crypto/cipher"
+ "crypto/hmac"
+ "crypto/rand"
+ "crypto/sha256"
+ "encoding/binary"
+ "errors"
+ "fmt"
+ "io"
+ "os"
+ "strings"
+)
+
+const recordFileMagic = "BXENC2"
+
+// RecordKey isolates each backup without distributing the Master encryption key.
+func RecordKey(masterKey []byte, recordID uint) []byte {
+ mac := hmac.New(sha256.New, masterKey)
+ fmt.Fprintf(mac, "backupx:record:v2:%d", recordID)
+ return mac.Sum(nil)
+}
+
+func EncryptRecordFile(key []byte, recordID uint, sourcePath string) (string, error) {
+ return transformRecordFile(key, recordID, sourcePath, true)
+}
+
+func DecryptRecordFile(key []byte, recordID uint, sourcePath string) (string, error) {
+ return transformRecordFile(key, recordID, sourcePath, false)
+}
+
+// V2 authenticates ordering, record identity and an explicit end marker, so
+// truncation and chunk reordering fail even without an external checksum.
+func transformRecordFile(key []byte, recordID uint, sourcePath string, encrypt bool) (result string, err error) {
+ if recordID == 0 || len(key) != 32 {
+ return "", errors.New("invalid record encryption key or record ID")
+ }
+ block, err := aes.NewCipher(key)
+ if err != nil {
+ return "", err
+ }
+ gcm, err := cipher.NewGCM(block)
+ if err != nil {
+ return "", err
+ }
+ source, err := os.Open(sourcePath)
+ if err != nil {
+ return "", err
+ }
+ defer source.Close()
+ header := make([]byte, len(recordFileMagic)+8)
+ copy(header, recordFileMagic)
+ binary.BigEndian.PutUint64(header[len(recordFileMagic):], uint64(recordID))
+ if !encrypt {
+ actual := make([]byte, len(header))
+ if _, err := io.ReadFull(source, actual); err != nil {
+ return "", err
+ }
+ if !hmac.Equal(actual, header) {
+ return "", errors.New("encrypted backup record mismatch or unsupported format")
+ }
+ }
+ targetPath := sourcePath + ".enc"
+ if !encrypt {
+ targetPath = strings.TrimSuffix(sourcePath, ".enc")
+ if targetPath == sourcePath {
+ targetPath += ".plain"
+ }
+ }
+ target, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+ if err != nil {
+ return "", err
+ }
+ defer func() {
+ err = errors.Join(err, target.Close())
+ if err != nil {
+ err = errors.Join(err, os.Remove(targetPath))
+ result = ""
+ }
+ }()
+ if encrypt {
+ if _, err := target.Write(header); err != nil {
+ return "", err
+ }
+ }
+ buffer := make([]byte, chunkSize)
+ aad := append(header, make([]byte, 8)...)
+ for sequence := uint64(0); ; sequence++ {
+ binary.BigEndian.PutUint64(aad[len(header):], sequence)
+ nonce := make([]byte, gcm.NonceSize())
+ if encrypt {
+ n, readErr := io.ReadFull(source, buffer)
+ if readErr != nil && readErr != io.EOF && readErr != io.ErrUnexpectedEOF {
+ return "", readErr
+ }
+ if _, err := rand.Read(nonce); err != nil {
+ return "", err
+ }
+ sealed := gcm.Seal(nil, nonce, buffer[:n], aad)
+ if _, err := target.Write(nonce); err != nil {
+ return "", err
+ }
+ if err := binary.Write(target, binary.BigEndian, uint32(len(sealed))); err != nil {
+ return "", err
+ }
+ if _, err := target.Write(sealed); err != nil {
+ return "", err
+ }
+ if n == 0 {
+ return targetPath, nil
+ }
+ } else {
+ if _, err := io.ReadFull(source, nonce); err != nil {
+ return "", fmt.Errorf("missing encrypted frame: %w", err)
+ }
+ var length uint32
+ if err := binary.Read(source, binary.BigEndian, &length); err != nil {
+ return "", err
+ }
+ if length < uint32(gcm.Overhead()) || length > uint32(chunkSize+gcm.Overhead()) {
+ return "", errors.New("invalid encrypted frame length")
+ }
+ sealed := make([]byte, length)
+ if _, err := io.ReadFull(source, sealed); err != nil {
+ return "", err
+ }
+ plain, err := gcm.Open(nil, nonce, sealed, aad)
+ if err != nil {
+ return "", fmt.Errorf("decrypt backup frame: %w", err)
+ }
+ if len(plain) == 0 {
+ if n, err := source.Read(buffer[:1]); n != 0 || err != io.EOF {
+ return "", errors.New("data after encrypted end marker")
+ }
+ return targetPath, nil
+ }
+ if _, err := target.Write(plain); err != nil {
+ return "", err
+ }
+ }
+ }
+}
diff --git a/server/pkg/crypto/record_file_test.go b/server/pkg/crypto/record_file_test.go
new file mode 100644
index 0000000..6683698
--- /dev/null
+++ b/server/pkg/crypto/record_file_test.go
@@ -0,0 +1,59 @@
+package backupcrypto
+
+import (
+ "bytes"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestRecordEncryption(t *testing.T) {
+ master := bytes.Repeat([]byte{7}, 32)
+ key := RecordKey(master, 42)
+ if bytes.Equal(key, master) || bytes.Equal(key, RecordKey(master, 43)) {
+ t.Fatal("keys are not isolated")
+ }
+ for _, size := range []int{0, 17, chunkSize + 29} {
+ payload := bytes.Repeat([]byte{9}, size)
+ src := filepath.Join(t.TempDir(), "backup.tar")
+ if err := os.WriteFile(src, payload, 0600); err != nil {
+ t.Fatal(err)
+ }
+ enc, err := EncryptRecordFile(key, 42, src)
+ if err != nil {
+ t.Fatal(err)
+ }
+ encrypted, err := os.ReadFile(enc)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, err := DecryptRecordFile(key, 43, enc); err == nil {
+ t.Fatal("accepted another record")
+ }
+ if _, err := DecryptRecordFile(RecordKey(master, 43), 42, enc); err == nil {
+ t.Fatal("accepted wrong key")
+ }
+ plain, err := DecryptFile(master, enc)
+ if err != nil {
+ t.Fatal(err)
+ }
+ got, err := os.ReadFile(plain)
+ if err != nil || !bytes.Equal(got, payload) {
+ t.Fatalf("round trip failed: %v", err)
+ }
+ for _, corrupt := range [][]byte{encrypted[:len(encrypted)-28], append(append([]byte{}, encrypted...), 0), append([]byte{}, encrypted...)} {
+ if len(corrupt) == len(encrypted) {
+ corrupt[len(corrupt)-1] ^= 1
+ }
+ if err := os.WriteFile(enc, corrupt, 0600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := DecryptRecordFile(key, 42, enc); err == nil {
+ t.Fatal("accepted corrupt/truncated ciphertext")
+ }
+ if _, err := os.Stat(src); !os.IsNotExist(err) {
+ t.Fatal("failed decryption retained plaintext")
+ }
+ }
+ }
+}
diff --git a/web/src/components/backup-records/BackupRecordLogDrawer.tsx b/web/src/components/backup-records/BackupRecordLogDrawer.tsx
index 3aa10e8..b2482ba 100644
--- a/web/src/components/backup-records/BackupRecordLogDrawer.tsx
+++ b/web/src/components/backup-records/BackupRecordLogDrawer.tsx
@@ -220,13 +220,13 @@ export function BackupRecordLogDrawer({
}
}
- async function handleConfirmRestore(targetPath?: string) {
+ async function handleConfirmRestore(targetPath?: string, restoreTime?: string) {
if (!recordId) {
return
}
setRestoreLoading(true)
try {
- const restore = await startRestoreFromBackup(recordId, undefined, targetPath)
+ const restore = await startRestoreFromBackup(recordId, undefined, targetPath, restoreTime)
Message.success('恢复已启动,正在打开日志')
setRestoreModalVisible(false)
setRestoreTask(null)
@@ -402,7 +402,7 @@ export function BackupRecordLogDrawer({
setRestoreModalVisible(false)
setRestoreTask(null)
}}
- onConfirm={(targetPath) => void handleConfirmRestore(targetPath)}
+ onConfirm={(targetPath, restoreTime) => void handleConfirmRestore(targetPath, restoreTime)}
/>