| # 备份与还原 |
|
|
| ## 概述 |
|
|
| OpenClaw 使用 Hugging Face Dataset 作为备份存储后端，支持增量备份、分卷压缩、动态备份策略等企业级功能。 |
|
|
| ## 核心概念 |
|
|
| ### 备份类型 |
|
|
| | 类型 | 说明 | |
| |------|------| |
| | **完整备份 (Full)** | 备份所有指定文件和目录 | |
| | **增量备份 (Incremental)** | 仅备份自上次备份以来变化的文件 | |
| | **分卷 (Split)** | 将大备份分割成多个小文件（默认500MB），是完整/增量备份的可选处理方式 | |
| | **加密 (Encrypted)** | 使用 AES-256-CBC 加密归档文件，是完整/增量备份的可选处理方式 | |
|
|
| ### 两层元数据设计 |
|
|
| 系统使用两层元数据文件： |
|
|
| #### 1. 备份文件名命名规则 |
|
|
| 备份文件名格式：`openclaw-backup-{时间戳}-{类型}[-split].tar.gz` |
|
|
| **组成部分**： |
| - `{时间戳}`：格式 `YYYYMMDD-HHmmss`，如 `20260413-120000` |
| - `{类型}`： |
| - `full`：完整备份 |
| - `inc`：增量备份 |
| - `[-split]`：可选后缀，表示分卷备份 |
|
|
| **类型后缀规则**： |
| | 类型 | 后缀 | 示例 | |
| |------|------|------| |
| | 单文件完整备份 | `full` | `openclaw-backup-20260413-120000-full.tar.gz` | |
| | 单文件增量备份 | `inc` | `openclaw-backup-20260414-060000-inc.tar.gz` | |
| | 分卷完整备份 | `full-split` | `openclaw-backup-20260414-090000-full-split.tar.gz` | |
| | 分卷增量备份 | `inc-split` | `openclaw-backup-20260414-150000-inc-split.tar.gz` | |
|
|
| **注意**： |
| 1. 分卷文件在主文件名后加 `.part-{aa,ab,...}` 后缀 |
| 2. 分卷数量由归档后实际大小决定（超过 `OPENCLAW_BACKUP_SPLIT_SIZE` 默认500MB时分卷） |
| 3. `-split` 后缀仅用于区分分卷备份（完整和增量都适用） |
| 4. 加密归档在原文件名后加 `.enc` 后缀（如 `openclaw-backup-20260413-120000-full.tar.gz.enc`） |
| 5. 加密与分卷可同时使用，加密后分卷的文件名格式：`原名.tar.gz.enc.part-{aa,ab,...}` |
|
|
| #### 2. 备份索引文件（每个备份独立） |
|
|
| 每个备份上传后都会在远端创建一个对应的元数据索引文件，命名格式为 `{归档名}.meta.json`。 |
|
|
| **示例远端存储结构**（按文件名/时间排序）： |
|
|
| ``` |
| Dataset根目录/ |
| ├── latest-backup.json ← 与backups/同级，必须在根目录下 |
| └── backups/ |
| ├── openclaw-backup-20260413-120000-full.tar.gz.meta.json ← 单文件完整备份 |
| ├── openclaw-backup-20260413-120000-full.tar.gz |
| ├── openclaw-backup-20260414-060000-inc.tar.gz.meta.json ← 单文件增量备份 |
| ├── openclaw-backup-20260414-060000-inc.tar.gz |
| ├── openclaw-backup-20260414-072200-inc.tar.gz.meta.json ← 单文件增量备份 |
| ├── openclaw-backup-20260414-072200-inc.tar.gz |
| ├── openclaw-backup-20260414-081100-full.tar.gz.meta.json ← 单文件完整备份 |
| ├── openclaw-backup-20260414-081100-full.tar.gz |
| ├── openclaw-backup-20260414-090000-full-split.tar.gz.part-aa ← 分卷完整备份 |
| ├── openclaw-backup-20260414-090000-full-split.tar.gz.part-ab |
| ├── openclaw-backup-20260414-090000-full-split.tar.gz.meta.json |
| ├── openclaw-backup-20260414-150000-inc-split.tar.gz.part-aa ← 分卷增量备份 |
| ├── openclaw-backup-20260414-150000-inc-split.tar.gz.part-ab |
| ├── openclaw-backup-20260414-150000-inc-split.tar.gz.meta.json |
| ├── openclaw-backup-20260414-152400-inc-split.tar.gz.part-aa ← 分卷增量备份 |
| ├── openclaw-backup-20260414-152400-inc-split.tar.gz.part-ab |
| └── openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json |
| ``` |
|
|
| **说明**：按文件名（时间）升序排列。每个分卷备份的文件组顺序为：分卷卷 → meta.json（分卷后原tar.gz不再保留）。 |
|
|
| **索引文件内容分场景示例**： |
|
|
| **场景A：单文件完整备份** |
| ```json5 |
| // openclaw-backup-20260413-120000-full.tar.gz.meta.json |
| { |
| "volumes": ["openclaw-backup-20260413-120000-full.tar.gz"], |
| "is_split": false, |
| "backup_type": "full", |
| "chain_id": "abc123", |
| "parent": null, |
| "created_at_utc": "2026-04-13T12:00:00", |
| "file_count": 42, |
| "archive_size": 1258291200, |
| "checksum": "sha256:def456...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| ```json5 |
| // openclaw-backup-20260414-081100-full.tar.gz.meta.json |
| { |
| "volumes": ["openclaw-backup-20260414-081100-full.tar.gz"], |
| "is_split": false, |
| "backup_type": "full", |
| "chain_id": "xyz789", |
| "parent": null, |
| "created_at_utc": "2026-04-14T08:11:00", |
| "file_count": 42, |
| "archive_size": 1258291200, |
| "checksum": "sha256:def456...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| **场景B：单文件增量备份** |
| ```json5 |
| // openclaw-backup-20260414-060000-inc.tar.gz.meta.json |
| { |
| "volumes": ["openclaw-backup-20260414-060000-inc.tar.gz"], |
| "is_split": false, |
| "backup_type": "incremental", |
| "chain_id": "abc123", |
| "parent": "openclaw-backup-20260413-120000-full.tar.gz.meta.json", |
| "created_at_utc": "2026-04-14T06:00:00", |
| "file_count": 5, |
| "archive_size": 52428800, |
| "checksum": "sha256:ghi789...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| ```json5 |
| // openclaw-backup-20260414-072200-inc.tar.gz.meta.json |
| { |
| "volumes": ["openclaw-backup-20260414-072200-inc.tar.gz"], |
| "is_split": false, |
| "backup_type": "incremental", |
| "chain_id": "abc123", |
| "parent": "openclaw-backup-20260414-060000-inc.tar.gz.meta.json", |
| "created_at_utc": "2026-04-14T07:22:00", |
| "file_count": 3, |
| "archive_size": 52428800, |
| "checksum": "sha256:ghi789...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| **场景C：分卷完整备份** |
| ```json5 |
| // openclaw-backup-20260414-090000-full-split.tar.gz.meta.json |
| { |
| "volumes": [ |
| "openclaw-backup-20260414-090000-full-split.tar.gz.part-aa", |
| "openclaw-backup-20260414-090000-full-split.tar.gz.part-ab" |
| ], |
| "is_split": true, |
| "backup_type": "full", |
| "chain_id": "xyz789", |
| "parent": null, |
| "created_at_utc": "2026-04-14T09:00:00", |
| "file_count": 128, |
| "archive_size": 2147483648, |
| "checksum": "sha256:jkl012...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| **场景D：分卷增量备份** |
| ```json5 |
| // openclaw-backup-20260414-150000-inc-split.tar.gz.meta.json |
| { |
| "volumes": [ |
| "openclaw-backup-20260414-150000-inc-split.tar.gz.part-aa", |
| "openclaw-backup-20260414-150000-inc-split.tar.gz.part-ab" |
| ], |
| "is_split": true, |
| "backup_type": "incremental", |
| "chain_id": "xyz789", |
| "parent": "openclaw-backup-20260414-090000-full-split.tar.gz.meta.json", |
| "created_at_utc": "2026-04-14T15:00:00", |
| "file_count": 64, |
| "archive_size": 1073741824, |
| "checksum": "sha256:mno345...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| ```json5 |
| // openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json |
| { |
| "volumes": [ |
| "openclaw-backup-20260414-152400-inc-split.tar.gz.part-aa", |
| "openclaw-backup-20260414-152400-inc-split.tar.gz.part-ab" |
| ], |
| "is_split": true, |
| "backup_type": "incremental", |
| "chain_id": "xyz789", |
| "parent": "openclaw-backup-20260414-150000-inc-split.tar.gz.meta.json", |
| "created_at_utc": "2026-04-14T15:24:00", |
| "file_count": 8, |
| "archive_size": 1073741824, |
| "checksum": "sha256:mno345...", |
| "version": "2.1", |
| "created_by": "openclaw-backup" |
| } |
| ``` |
|
|
| **场景E：加密备份（单文件）** |
| ```json5 |
| // openclaw-backup-20260414-160000-full.tar.gz.meta.json |
| { |
| "volumes": ["openclaw-backup-20260414-160000-full.tar.gz.enc"], |
| "is_split": false, |
| "backup_type": "full", |
| "chain_id": "enc001", |
| "parent": null, |
| "created_at_utc": "2026-04-14T16:00:00", |
| "file_count": 42, |
| "archive_size": 1300234240, |
| "checksum": "sha256:enc123...", |
| "version": "2.1", |
| "created_by": "openclaw-backup", |
| "encrypted": true, |
| "encryption_algorithm": "AES-256-CBC" |
| } |
| ``` |
|
|
| **场景F：加密+分卷备份** |
| ```json5 |
| // openclaw-backup-20260414-170000-full.tar.gz.meta.json |
| { |
| "volumes": [ |
| "openclaw-backup-20260414-170000-full.tar.gz.enc.part-aa", |
| "openclaw-backup-20260414-170000-full.tar.gz.enc.part-ab", |
| "openclaw-backup-20260414-170000-full.tar.gz.enc.part-ac" |
| ], |
| "is_split": true, |
| "backup_type": "full", |
| "chain_id": "enc002", |
| "parent": null, |
| "created_at_utc": "2026-04-14T17:00:00", |
| "file_count": 128, |
| "archive_size": 3221225472, |
| "checksum": "sha256:enc456...", |
| "version": "2.1", |
| "created_by": "openclaw-backup", |
| "encrypted": true, |
| "encryption_algorithm": "AES-256-CBC" |
| } |
| ``` |
|
|
| **字段说明**： |
|
|
| | 字段 | 说明 | |
| |------|------| |
| | `volumes` | 归档文件列表（单文件时为单个元素，分卷时包含所有分卷） | |
| | `is_split` | 是否分卷备份 | |
| | `backup_type` | `full`（完整）或 `incremental`（增量） | |
| | `chain_id` | 备份链标识，同一链的所有备份共享此ID（详见下方生成规则） | |
| | `parent` | 父备份的 `.meta.json` 文件路径（完整备份为null） | |
| | `created_at_utc` | 备份创建时间（UTC） | |
| | `file_count` | 归档内包含的文件数量 | |
| | `archive_size` | 所有归档文件总大小（字节） | |
| | `checksum` | 所有归档合并后的SHA256校验和 | |
| | `version` | 元数据格式版本 | |
| | `created_by` | 创建工具标识 | |
| | `encrypted` | 是否加密（可选，默认为false） | |
| | `encryption_algorithm` | 加密算法（可选，如 `AES-256-CBC`） | |
|
|
| **chain_id 生成规则**： |
| |
| 1. **首次创建链**：生成新的 UUID 前8位作为 chain_id |
| 2. **增量备份**：继承父备份的 chain_id |
| 3. **独立完整备份**：生成新的 chain_id（即使上一个链未完成） |
| 4. **分卷备份**：继承父备份的 chain_id |
| |
| #### 2. latest-backup.json（最新备份软索引） |
| |
| 位于 Dataset 根目录（与 backups/ 同级）. |
| |
| ```json5 |
| { |
| "dataset": "GGSheng/page-backup", |
| "latest": "backups/openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json", |
| "is_split": true, |
| "created_at_utc": "2026-04-14T15:24:00" |
| } |
| ``` |
| |
| **注意**：此文件仅存储最新备份的名称，不包含完整信息。完整信息在 `{归档名}.meta.json` 中。 |
| |
| #### 3. 归档内部元数据（last-backup-metadata.json） |
| |
| 在备份过程中，元数据会先写入本地 `work_dir`，然后打包进 tar.gz 归档内部，最后随归档上传到远端。归档内部元数据包含完整的备份信息（与 `.meta.json` 内容一致），用于归档自验证、链合并判断以及下一次增量备份的 parent 确定： |
| |
| ```json5 |
| { |
| "version": "2.1", |
| "backup_type": "incremental", |
| "chain_id": "abc123", |
| "parent": "openclaw-backup-20260414-060000-inc.tar.gz.meta.json", |
| "volumes": ["openclaw-backup-20260414-060000-inc.tar.gz"], |
| "checksum": "sha256:abc123...", |
| "created_at_utc": "2026-04-14T15:24:00", |
| "last_backup_time": "2026-04-14T15:24:00", |
| "file_count": 10, |
| "archive_size": 5242880, |
| "is_latest": true, |
| "created_by": "openclaw-backup" |
| } |
| ``` |
| |
| **说明**： |
| - `volumes`：当前备份包含的所有卷文件（单文件为列表，分卷备份为 `part-*` 文件列表） |
| - `checksum`：归档的 SHA256 校验和 |
| - `file_count`：备份的文件数量 |
| - `archive_size`：归档原始大小（字节） |
| - `is_latest`：标记是否为最新备份（用于链管理） |
| - `last_backup_time`：上一次备份的时间戳（UTC），用于判断增量备份的时间间隔 |
| - 完整的备份信息同时存储在远端的 `.meta.json` 中 |
| |
| **重要说明**：`last-backup-metadata.json` 存储在本地 `work_dir`（默认 `/tmp/openclaw-backup`），容器重启后可能丢失。因此系统设计为**以远程元数据为真理源**：每次备份启动时会从远程 `latest-backup.json` 和最新的 `.meta.json` 获取链信息，确保即使本地元数据丢失也能正确构建备份链。 |
| |
| ### 增量备份链 (Backup Chain) |
| |
| 增量备份通过 `parent` 字段形成链表： |
| |
| **备份链路图**（两条独立链）： |
| |
| ``` |
| 【链 abc123】 |
| 完整备份 chain_id: "abc123" |
| openclaw-backup-20260413-120000-full.tar.gz.meta.json |
| parent: null |
| ↑ |
| │ parent |
| │ |
| 增量备份 #1 chain_id: "abc123" |
| openclaw-backup-20260414-060000-inc.tar.gz.meta.json |
| parent: "openclaw-backup-20260413-120000-full.tar.gz.meta.json" |
| ↑ |
| │ parent |
| │ |
| 增量备份 #2 chain_id: "abc123" |
| openclaw-backup-20260414-072200-inc.tar.gz.meta.json |
| parent: "openclaw-backup-20260414-060000-inc.tar.gz.meta.json" |
| ``` |
| |
| ``` |
| 【链 xyz789】（包含最新备份） |
| 完整备份 #1 chain_id: "xyz789" |
| openclaw-backup-20260414-081100-full.tar.gz.meta.json |
| parent: null |
| ↑ |
| │ (独立链，无父子关系) |
| |
| 完整备份 #2 chain_id: "xyz789" |
| openclaw-backup-20260414-090000-full-split.tar.gz.meta.json |
| parent: null |
| ↑ |
| │ parent |
| │ |
| 增量备份 #1 chain_id: "xyz789" |
| openclaw-backup-20260414-150000-inc-split.tar.gz.meta.json |
| parent: "openclaw-backup-20260414-090000-full-split.tar.gz.meta.json" |
| ↑ |
| │ parent |
| │ |
| 增量备份 #2 (最新) chain_id: "xyz789" |
| openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json |
| parent: "openclaw-backup-20260414-150000-inc-split.tar.gz.meta.json" |
| ↑ |
| │ latest |
| │ |
| latest-backup.json → "backups/openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json" |
| ``` |
| |
| **说明**： |
| - `081100-full` 和 `090000-full` 都是完整备份（parent: null），分属同一 chain_id 但互无父子关系 |
| - 同一 chain_id 表示这些备份共享同一个备份链标识，用于分组和校验 |
| - 恢复时沿 `parent` 链路回溯即可 |
| |
| **恢复流程**：从 latest-backup.json 获取最新备份 → 下载其 meta.json → 沿 parent 回溯到完整备份 → 按顺序合并。 |
| |
| ### 远端存储混合场景示例 |
| |
| 假设存在以下远端存储结构（包含完整备份链、多次增量、分卷等）： |
| |
| ``` |
| Dataset: GGSheng/page-backup |
| │ |
| ├── latest-backup.json ← 指向最新备份（位于根目录） |
| │ {"latest": "backups/openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json"} |
| │ |
| └── backups/ |
| ├── openclaw-backup-20260413-120000-full.tar.gz.meta.json ← 单文件完整备份1 |
| ├── openclaw-backup-20260413-120000-full.tar.gz |
| ├── openclaw-backup-20260414-060000-inc.tar.gz.meta.json ← 单文件增量备份1 |
| ├── openclaw-backup-20260414-060000-inc.tar.gz |
| ├── openclaw-backup-20260414-072200-inc.tar.gz.meta.json ← 单文件增量备份2 |
| ├── openclaw-backup-20260414-072200-inc.tar.gz |
| ├── openclaw-backup-20260414-081100-full.tar.gz.meta.json ← 单文件完整备份2 |
| ├── openclaw-backup-20260414-081100-full.tar.gz |
| ├── openclaw-backup-20260414-090000-full-split.tar.gz.meta.json ← 分卷完整备份 |
| ├── openclaw-backup-20260414-090000-full-split.tar.gz.part-aa |
| ├── openclaw-backup-20260414-090000-full-split.tar.gz.part-ab |
| ├── openclaw-backup-20260414-150000-inc-split.tar.gz.meta.json ← 分卷增量备份1 |
| ├── openclaw-backup-20260414-150000-inc-split.tar.gz.part-aa |
| ├── openclaw-backup-20260414-150000-inc-split.tar.gz.part-ab |
| ├── openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json ← 分卷增量备份2 |
| ├── openclaw-backup-20260414-152400-inc-split.tar.gz.part-aa |
| └── openclaw-backup-20260414-152400-inc-split.tar.gz.part-ab |
| ``` |
| |
| **场景说明**： |
| |
| | 文件名 | 类型 | chain_id | parent | |
| |--------|------|----------|--------| |
| | 20260413-120000-full | 单文件完整备份 | abc123 | null | |
| | 20260414-060000-inc | 单文件增量备份 | abc123 | 20260413-120000-full.meta.json | |
| | 20260414-072200-inc | 单文件增量备份 | abc123 | 20260414-060000-inc.meta.json | |
| | 20260414-081100-full | 单文件完整备份 | xyz789 | null | |
| | 20260414-090000-full-split | 分卷完整备份 | xyz789 | null | |
| | 20260414-150000-inc-split | 分卷增量备份 | xyz789 | 20260414-090000-full-split.meta.json | |
| | 20260414-152400-inc-split | 分卷增量备份 | xyz789 | 20260414-150000-inc-split.meta.json | |
| |
| **恢复任意备份的流程**： |
| |
| 1. 确定目标备份（如 `openclaw-backup-20260414-090000-full-split.tar.gz`） |
| 2. 下载其 `.meta.json` 获取分卷信息和父备份引用 |
| 3. 如有父备份，继续下载父备份的 `.meta.json` |
| 4. 按顺序合并所有归档 |
| 5. 恢复到目标目录 |
| |
| --- |
| |
| ## 备份流程 |
| |
| ### 整体架构 |
| |
| ``` |
| ┌─────────────────────────────────────────────────────────────────┐ |
| │ 外部 Cron 调度 (每30分钟，由cron定义) │ |
| │ OPENCLAW_BACKUP_CRON="*/30 * * * *" │ |
| └─────────────────────────────────────────────────────────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────────────────────────────────────────────────┐ |
| │ openclaw-backup-cron.sh │ |
| │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ |
| │ │ 环境准备 │→ │ 判断备份类型│→ │ 创建归档 │→ │ 分卷处理│ │ |
| │ │ 加载环境变量│ │ 完整/增量 │ │ (动态策略) │ │ (如需要)│ │ |
| │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │ |
| │ │ │ |
| │ ▼ │ |
| │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐│ |
| │ │ 清理旧备份 │← │ 上传文件 │← │ 创建meta.json ││ |
| │ │ │ │ 分卷/归档 │ │ 更新latest-backup.json ││ |
| │ └─────────────┘ └─────────────┘ └─────────────────────────────┘│ |
| └─────────────────────────────────────────────────────────────────┘ |
| ``` |
| |
| ### 详细步骤 |
| |
| #### 1. 环境准备 |
| |
| 脚本从以下位置加载环境变量： |
| - `/etc/profile.d/openclaw-env.sh` |
| - `/root/.env.d/openclaw-backup.env` |
| |
| 关键环境变量： |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_BACKUP_DATASET_REPO` | (必填) | 备份存储的Dataset仓库 | |
| | `OPENCLAW_BACKUP_SOURCE_DIR` | `/root/.openclaw` | 备份源目录 | |
| | `OPENCLAW_BACKUP_WORK_DIR` | `/tmp/openclaw-backup` | 临时工作目录 | |
| | `OPENCLAW_BACKUP_SPLIT_SIZE` | `500` | 分卷大小（MB），超过此大小则分卷 | |
| | `OPENCLAW_BACKUP_KEEP_COUNT` | `48` | 保留的备份数量 | |
| | `OPENCLAW_INCREMENTAL_BACKUP` | `true` | 是否启用增量备份功能（`true`=增量模式，`false`=每次完整备份） | |
| | `OPENCLAW_INCREMENTAL_INTERVAL_MINUTES` | `10` | 增量备份间隔（分钟），距上次备份>=此时间时执行增量备份 | |
| | `OPENCLAW_BACKUP_ENCRYPTION_ENABLED` | `false` | 是否启用加密备份（`true`=启用，`false`=禁用） | |
| | `OPENCLAW_BACKUP_ENCRYPTION_PASSWORD` | (必填) | 加密密码（建议使用 HF Space Secrets 管理） | |
| |
| **注意**：`OPENCLAW_INCREMENTAL_INTERVAL_MINUTES` 控制的是"每隔多久执行增量备份"。外部 cron 每30分钟触发一次，如果距上次备份时间未超过此间隔，则不执行任何备份；如果超过此间隔，则执行增量备份。 |
| |
| #### 2. 获取远程链信息（真理源） |
| |
| **关键设计**：由于本地 `last-backup-metadata.json` 存储在 `/tmp/openclaw-backup`（容器重启后可能丢失），系统以**远程元数据为真理源**。 |
| |
| ``` |
| 备份启动时： |
| │ |
| ├─→ 下载 latest-backup.json |
| │ |
| └─→ 下载 latest .meta.json |
| │ |
| ├─→ last_backup_time → 用于判断距上次备份的时间间隔 |
| ├─→ parent_meta_path → 用于增量备份链的 parent 引用 |
| ├─→ chain_id → 用于标识同一备份链 |
| └─→ volumes → 用于分卷备份的文件列表 |
| ``` |
| |
| 此步骤确保即使本地元数据丢失，也能正确构建备份链。 |
| |
| #### 3. 动态备份策略 |
| |
| 系统根据文件变化率和预估大小自动调整备份参数： |
| |
| ``` |
| 预估大小判断: |
| ├── < 500MB → 小文件，快压缩(级别3)，单文件备份 |
| ├── 500MB-2GB → 中等文件，平衡压缩(级别6)，单文件备份 |
| └── > 2GB → 大文件，最大压缩(级别9) |
| |
| 变化率调整: |
| ├── > 10文件/分钟 → 高变化率，降低压缩级别优先速度 |
| └── < 2文件/分钟 → 低变化率，提高压缩级别，可能跳过备份 |
| ``` |
| |
| **分卷触发**：归档完成后，检查归档实际大小是否超过 `OPENCLAW_BACKUP_SPLIT_SIZE`（默认500MB）。如果超过，则自动启用分卷。预估大小 `> 2GB` 只是提示系统采用最大压缩级别，但最终是否分卷由实际大小决定。 |
| |
| #### 4. 判断备份类型 |
| |
| 根据以下条件判断是否执行完整备份或增量备份： |
| |
| ``` |
| INCREMENTAL_BACKUP = false? |
| ├── YES → 执行完整备份（每次都备份所有文件，创建新链） |
| └── NO ↓ |
| 首次备份 或 手动触发完整备份? |
| ├── YES → 执行完整备份（备份所有文件，创建新链） |
| └── NO ↓ |
| |
| 距上次备份时间 >= INCREMENTAL_INTERVAL ? |
| ├── YES → 执行增量备份（只打包变化的文件，继承链） |
| └── NO → 跳过本次备份（等待下次 cron 触发） |
| ``` |
| |
| **说明**： |
| - 完整备份：创建新的备份链，生成新的 `chain_id` |
| - 增量备份：继承父备份的 `chain_id` |
| - 外部 cron 每30分钟触发一次，只有满足时间条件才执行增量备份 |
| - `OPENCLAW_INCREMENTAL_BACKUP=false` 时，每次都执行完整备份 |
| - 归档完成后检查大小，超过 `OPENCLAW_BACKUP_SPLIT_SIZE` 则自动分卷 |
| |
| #### 5. 创建归档 |
| |
| 根据策略创建 tar.gz 归档： |
| |
| **完整备份归档结构**: |
| ``` |
| openclaw-backup-20260414-120000-full.tar.gz |
| ├── openclaw-state/ # 主状态目录 |
| │ ├── config.json |
| │ └── ... |
| ├── root-config/ # 额外目录 |
| ├── root-ssh/ # SSH配置 |
| └── last-backup-metadata.json # 备份链元数据 |
| ``` |
| |
| **增量备份归档结构**: |
| ``` |
| openclaw-backup-20260414-130000-inc.tar.gz |
| ├── openclaw-state/ # 仅变化的文件 |
| │ └── changed-file.txt |
| ├── root-config/ # 仅变化的额外目录 |
| └── last-backup-metadata.json # 包含chain_id和parent信息 |
| ``` |
| |
| **分卷备份归档结构**： |
| 分卷备份的原始 tar.gz 归档结构与完整/增量相同，只是在归档完成后被分割成多个 part 文件。 |
| |
| ``` |
| # 归档前的原始结构（分卷完整备份为例） |
| openclaw-backup-20260414-090000-full.tar.gz |
| ├── openclaw-state/ # 主状态目录 |
| ├── root-config/ |
| ├── root-ssh/ |
| └── last-backup-metadata.json # 分卷前记录原始归档名 |
| |
| # 分割后的文件 |
| openclaw-backup-20260414-090000-full.tar.gz.part-aa # 包含 last-backup-metadata.json |
| openclaw-backup-20204-090000-full.tar.gz.part-ab # 包含 last-backup-metadata.json |
| ``` |
| |
| **分卷文件中 `last-backup-metadata.json` 的内容说明**： |
| |
| 每个分卷 part 文件内部都包含相同的 `last-backup-metadata.json`（因为是通过 split 分割原始 tar.gz 得到的）。其内容在分卷**前**确定： |
| |
| ```json5 |
| { |
| "version": "2.1", |
| "backup_type": "full", |
| "chain_id": "xyz789", |
| "parent": null, |
| "volumes": ["openclaw-backup-20260414-090000-full.tar.gz"], // 分卷前为原始归档名 |
| "checksum": "sha256:abc123...", |
| "created_at_utc": "2026-04-14T09:00:00", |
| "last_backup_time": "2026-04-14T09:00:00", |
| "file_count": 128, |
| "archive_size": 2147483648, |
| "is_latest": true, |
| "created_by": "openclaw-backup" |
| } |
| ``` |
| |
| **注意**：`volumes` 字段在分卷前记录原始归档名，分卷后通过 `_update_volumes_in_metadata()` 更新为本地的 `last-backup-metadata.json`，但**分卷文件内部的副本不会改变**。上传到远端的 `.meta.json` 文件由程序生成，其 `volumes` 字段会被更新为所有分卷文件名列表： |
| ```json5 |
| { |
| "volumes": [ |
| "openclaw-backup-20260414-090000-full.tar.gz.part-aa", |
| "openclaw-backup-20260414-090000-full.tar.gz.part-ab" |
| ], |
| ... |
| } |
| ``` |
| |
| #### 6. 分卷处理（如需要） |
| |
| 当备份超过 `OPENCLAW_BACKUP_SPLIT_SIZE`（默认500MB）时，使用 `split` 命令分割： |
| |
| ```bash |
| split -b 500M openclaw-backup-20260414-120000-full.tar.gz \ |
| openclaw-backup-20260414-120000-full.tar.gz.part- |
| # 生成: part-aa, part-ab, part-ac... |
| ``` |
| |
| #### 7. 上传到 HuggingFace |
| |
| **分卷备份上传**： |
| 1. 所有分卷卷文件（如 `openclaw-backup-20260414-090000-full-split.tar.gz.part-aa`, `openclaw-backup-20260414-090000-full-split.tar.gz.part-ab`） |
| 2. `.meta.json` 元数据索引文件 |
| |
| **单文件备份上传**： |
| 1. `.tar.gz` 归档文件 |
| 2. `.meta.json` 元数据索引文件 |
| |
| **统一上传顺序**： |
| 1. 所有分卷卷文件（如有） |
| 2. 单文件归档文件（如有） |
| 3. `.meta.json` 元数据索引文件 |
| 4. 更新 `latest-backup.json` 指向最新备份的 `.meta.json` |
| |
| **注意**：`latest-backup.json` 存储最新备份的 `.meta.json` 路径（如 `backups/openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json`），恢复时直接下载它获取完整信息。 |
| |
| #### 8. 清理旧备份 |
| |
| 保留最近 `OPENCLAW_BACKUP_KEEP_COUNT`（默认48）个备份： |
| |
| ```python |
| # 清理逻辑（简化） |
| all_backups = list_repo_files() # 获取所有备份文件 |
| valid_backups = [] |
| for backup in sorted(all_backups, key=timestamp, reverse=True): |
| if "-split.tar.gz" in backup: |
| # 分卷备份：检查所有卷是否都存在 |
| if all_volumes_exist(backup): |
| valid_backups.append(backup) |
| elif backup.endswith(".meta.json"): |
| # 元数据文件：分卷备份直接保留（.tar.gz已被分割） |
| # 单文件备份需检查归档是否存在 |
| main_archive = backup.replace(".meta.json", "") |
| if "-split" in main_archive or archive_exists(main_archive): |
| valid_backups.append(backup) |
| else: |
| valid_backups.append(backup) |
| |
| # 删除超过keep_count的旧备份 |
| for backup in valid_backups[keep_count:]: |
| delete(backup) |
| ``` |
| |
| --- |
| |
| ## 还原流程 |
| |
| ### 整体流程 |
| |
| ``` |
| ┌─────────────────────────────────────────────────────────────────┐ |
| │ openclaw-restore.sh │ |
| │ │ |
| │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐ │ |
| │ │ 下载索引 │→ │ 解析备份链 │→ │ 按顺序下载归档 │ │ |
| │ │ latest.json │ │ 下载meta.json│ │ (从完整到最新) │ │ |
| │ │ │ │ 沿parent回溯 │ │ 合并分卷(如需要) │ │ |
| │ └──────────────┘ └──────────────┘ └────────────────────────┘ │ |
| │ │ │ |
| │ ▼ │ |
| │ ┌────────────────────────┐ │ |
| │ │ 恢复到目标目录 │ │ |
| │ │ │ │ |
| │ └────────────────────────┘ │ |
| └─────────────────────────────────────────────────────────────────┘ |
| ``` |
| |
| ### 详细步骤 |
| |
| #### 1. 下载备份索引 |
| |
| 从 HuggingFace Dataset 下载 `latest-backup.json`，获取最新备份的 `.meta.json` 路径： |
| ```json |
| { |
| "latest": "backups/openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json", |
| "created_at_utc": "2026-04-14T15:24:00" |
| } |
| ``` |
| |
| #### 2. 解析备份链（下载所有 meta.json） |
| |
| 从最新备份开始，沿 `parent` 字段回溯到完整备份，下载所有需要的 `.meta.json`： |
| |
| ```bash |
| # 回溯下载流程（从新到旧收集） |
| hf download GGSheng/page-backup backups/openclaw-backup-20260414-152400-inc-split.tar.gz.meta.json |
| # → parent: "openclaw-backup-20260414-060000-inc.tar.gz.meta.json" |
| |
| hf download GGSheng/page-backup backups/openclaw-backup-20260414-060000-inc.tar.gz.meta.json |
| # → parent: "openclaw-backup-20260413-120000-full.tar.gz.meta.json" |
| |
| hf download GGSheng/page-backup backups/openclaw-backup-20260413-120000-full.tar.gz.meta.json |
| # → parent: null (完整备份) |
| ``` |
| |
| 回溯完成后，收集到的 meta.json 列表需要反转，得到完整备份链（从旧到新）： |
| ``` |
| 合并顺序: [20260413-120000(full), 20260414-060000(inc), 20260414-152400(inc-split)] |
| ``` |
| |
| #### 3. 按顺序下载归档文件 |
| |
| 根据备份链**从旧到新**依次下载归档并合并： |
| |
| - **分卷备份**：下载所有分卷卷文件（如 `part-aa`, `part-ab`），然后合并 |
| - **单文件备份**：直接下载 `.tar.gz` 文件 |
| |
| ```python |
| # 按顺序下载并合并归档 |
| chain = [full_meta, inc1_meta, inc2_meta] # 从完整备份到最新 |
| merged = {} |
| |
| for meta in chain: |
| # 下载归档（分卷则先合并） |
| # volumes 格式: ["backups/xxx.part-aa", "backups/xxx.part-ab"] 或 ["backups/xxx.tar.gz"] |
| volumes = meta["volumes"] |
| |
| if meta["is_split"]: |
| # 下载所有分卷，合并为一个临时文件 |
| with open("temp.tar.gz", "wb") as out: |
| for vol in sorted(volumes): |
| download(vol) |
| with open(vol, "rb") as inp: |
| out.write(inp.read()) |
| archive = "temp.tar.gz" |
| else: |
| archive = volumes[0] |
| download(archive) |
| |
| # 校验完整性 |
| assert calculate_checksum(archive) == meta["checksum"] |
| |
| # 提取并合并到merged |
| for file in extract(archive): |
| merged[file.path] = file # 后者覆盖前者 |
| ``` |
| |
| #### 4. 恢复文件 |
| |
| 将合并后的文件恢复到配置的目标目录： |
| |
| | 归档内容 | 恢复路径 | |
| |----------|----------| |
| | `openclaw-state/` | `OPENCLAW_BACKUP_SOURCE_DIR` | |
| | `root-config/` | `OPENCLAW_BACKUP_ROOT_CONFIG_DIR` | |
| | `root-ssh/` | `OPENCLAW_BACKUP_ROOT_SSH_DIR` | |
| | 其他 | 按配置恢复 | |
| |
| #### 5. 指定备份恢复 |
| |
| 恢复时可以指定任意备份，系统会自动完成备份链回溯和合并。 |
| |
| **通过环境变量指定**： |
| ```bash |
| # 指定要恢复的归档文件名（不含路径，包含.tar.gz扩展名） |
| # 系统会自动添加 .meta.json 后缀 |
| export OPENCLAW_RESTORE_ARCHIVE="openclaw-backup-20260414-090000-full-split.tar.gz" |
| |
| # 执行恢复 |
| python3 /opt/openclaw-hf/openclaw_hf/backup.py restore |
| ``` |
| |
| **恢复流程**： |
| 1. 系统根据 `OPENCLAW_BACKUP_PATH_PREFIX` 构造元数据文件路径 |
| 2. 解析备份链：下载 `.meta.json` 并沿 `parent` 回溯到完整备份 |
| 3. 按顺序下载归档并合并（从完整备份到最新） |
| 4. **如果归档加密**（`encrypted: true`），使用 `OPENCLAW_BACKUP_ENCRYPTION_PASSWORD` 解密 |
| 5. 恢复到目标目录 |
| |
| **示例**：假设指定恢复 `openclaw-backup-20260414-090000-full-split.tar.gz`（一个分卷完整备份）： |
| |
| ``` |
| 指定归档 → openclaw-backup-20260414-090000-full-split.tar.gz |
| ↓ 系统添加后缀 → openclaw-backup-20260414-090000-full-split.tar.gz.meta.json |
| ↓ 下载 .meta.json: is_split=true, volumes=["backups/...part-aa", "backups/...part-ab"] |
| ↓ parent: null (完整备份，无需回溯) |
| ↓ |
| Step 3: |
| （1）下载所有分卷: part-aa, part-ab |
| （2）合并分卷为完整归档 |
| （3）如果 encrypted=true，解密归档 |
| Step 4: 提取文件到目标目录 |
| ``` |
| |
| **加密恢复注意事项**： |
| - 如果备份是加密的但未提供 `OPENCLAW_BACKUP_ENCRYPTION_PASSWORD`，恢复会失败并报错 |
| - 加密备份与普通备份可以共存于同一 Dataset 中，恢复时自动识别 |
| |
| --- |
| |
| ## 备份调度 |
| |
| ### Cron 配置 |
| |
| 默认每30分钟执行一次备份检查： |
| |
| ```bash |
| OPENCLAW_BACKUP_CRON="*/30 * * * *" |
| ``` |
| |
| ### 调度执行 |
| |
| 由 `openclaw-entrypoint.sh` 启动： |
| ```bash |
| # 在容器启动时设置cron |
| echo "$OPENCLAW_BACKUP_CRON root /usr/local/bin/openclaw-backup-cron.sh" >> /etc/crontab |
| ``` |
| |
| ### 执行保障 |
| |
| - **健康检查**：备份前可选执行 `--check`，失败时尝试 `--repair` |
| - **重试机制**：默认3次重试，间隔递增（10s, 20s, 30s） |
| - **看门狗**：作为最后防线，确保备份按时执行 |
| |
| ### 并发执行控制 |
| |
| 备份使用文件锁机制防止并发执行： |
| |
| ```python |
| lock_path = "/tmp/openclaw-backup/openclaw-backup.lock" |
| lock_fd = open(lock_path, "w") |
| try: |
| fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB) # 非阻塞获取锁 |
| except (OSError, IOError): |
| print("backup skipped: another backup is already in progress") |
| return None |
| ``` |
| |
| **流程**： |
| 1. 尝试获取排他锁（`LOCK_EX | LOCK_NB`） |
| 2. 如果锁被占用，跳过本次备份 |
| 3. 备份完成后释放锁 |
| |
| **注意**：如果备份任务执行时间超过 cron 间隔（例如30分钟），新的备份任务会跳过，确保不会同时执行两个备份。 |
| |
| --- |
| |
| ## 环境变量参考 |
| |
| ### 必需变量 |
| |
| | 变量 | 说明 | |
| |------|------| |
| | `OPENCLAW_BACKUP_DATASET_REPO` | HuggingFace Dataset 仓库ID (如 `GGSheng/page-backup`) | |
| |
| ### 备份配置 |
| |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_BACKUP_SOURCE_DIR` | `/root/.openclaw` | 备份的源目录 | |
| | `OPENCLAW_BACKUP_WORK_DIR` | `/tmp/openclaw-backup` | 临时工作目录 | |
| | `OPENCLAW_BACKUP_PATH_PREFIX` | `backups` | 仓库内的路径前缀 | |
| | `OPENCLAW_BACKUP_PRIVATE` | `true` | 是否创建为私有仓库 | |
| |
| ### 增量备份 |
| |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_INCREMENTAL_BACKUP` | `true` | 启用增量备份 | |
| | `OPENCLAW_INCREMENTAL_INTERVAL_MINUTES` | `10` | 增量备份间隔（分钟），每隔此时间执行一次增量备份 | |
| |
| **注意**：此变量控制增量备份的执行频率，非完整备份间隔。外部 cron 每30分钟触发一次，如果距上次备份未超过此间隔则跳过。超过此间隔则执行增量备份。 |
| |
| ### 性能调优 |
| |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_BACKUP_COMPRESSION_LEVEL` | `6` | 压缩级别 (1-9，9最大) | |
| | `OPENCLAW_BACKUP_SPLIT_SIZE` | `500M` | 分卷大小，空=不分卷 | |
| | `OPENCLAW_BACKUP_SIZE_WARNING_MB` | `1500` | 备份大小警告阈值(MB) | |
| | `OPENCLAW_BACKUP_KEEP_COUNT` | `48` | 保留备份数量 | |
| |
| ### 动态备份策略 |
| |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_DYNAMIC_BACKUP` | `true` | 启用动态策略 | |
| | `OPENCLAW_DYNAMIC_SMALL_THRESHOLD_MB` | `500` | 小文件阈值 | |
| | `OPENCLAW_DYNAMIC_MEDIUM_THRESHOLD_MB` | `2000` | 中等文件阈值 | |
| | `OPENCLAW_DYNAMIC_HIGH_CHANGE_RATE` | `10` | 高变化率阈值（文件/分钟） | |
| | `OPENCLAW_DYNAMIC_LOW_CHANGE_RATE` | `2` | 低变化率阈值（文件/分钟） | |
| |
| ### 额外目录和文件 |
| |
| 通过环境变量配置额外的备份内容： |
| |
| ```bash |
| # 额外目录格式: "归档名:/路径" |
| OPENCLAW_BACKUP_EXTRA_DIRS="root-config:/root/.config,root-ssh:/root/.ssh" |
| |
| # 额外文件格式: "归档名:/路径" |
| OPENCLAW_BACKUP_EXTRA_FILES="bt-default:/www/server/panel/default.pl,root-bashrc:/root/.bashrc" |
| ``` |
| |
| ### 健康检查 |
| |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_BACKUP_HEALTH_CHECK_ENABLED` | `false` | 启用健康检查 | |
| | `OPENCLAW_BACKUP_HEALTH_CHECK_BEFORE` | `false` | 备份前检查 | |
| | `OPENCLAW_BACKUP_HEALTH_CHECK_AFTER` | `false` | 备份后检查 | |
| | `OPENCLAW_BACKUP_MAX_RETRIES` | `3` | 最大重试次数 | |
| |
| ### 恢复配置 |
| |
| | 变量 | 默认值 | 说明 | |
| |------|--------|------| |
| | `OPENCLAW_RESTORE_ARCHIVE` | (空) | 指定恢复的归档文件名（不含路径），如 `openclaw-backup-20260414-090000.tar.gz`。默认为空时恢复最新备份。 | |
| |
| **注意**：恢复时系统会自动查找 `{OPENCLAW_RESTORE_ARCHIVE}.meta.json` 获取备份的完整信息（volumes分卷列表、parent链路上游、chain_id等），无需单独指定元数据文件。 |
| |
| --- |
| |
| ## 使用示例 |
| |
| ### 首次部署 |
| |
| ```bash |
| # 在 bootstrap-hf.sh 中配置 |
| export OPENCLAW_BACKUP_DATASET_REPO="GGSheng/page-backup" |
| export OPENCLAW_INCREMENTAL_BACKUP="true" |
| export OPENCLAW_BACKUP_KEEP_COUNT="48" |
| ``` |
| |
| ### 手动触发备份 |
| |
| ```bash |
| python3 /opt/openclaw-hf/openclaw_hf/backup.py backup |
| ``` |
| |
| ### 手动触发恢复 |
| |
| ```bash |
| python3 /opt/openclaw-hf/openclaw_hf/backup.py restore |
| ``` |
| |
| **注意**：`backup.py` 和 `restore` 操作均通过环境变量配置，不支持命令行参数指定备份文件或其他选项。相关配置通过 `OPENCLAW_RESTORE_*` 系列环境变量指定（详见环境变量参考）。 |
| |
| ### 查看备份状态 |
| |
| ```bash |
| # 查看最新备份索引 |
| hf download GGSheng/page-backup backups/latest-backup.json |
| cat backups/latest-backup.json |
| ``` |
| |
| --- |
| |
| ## 故障排除 |
| |
| ### 备份失败 |
| |
| 1. 检查网络连接和 HF_TOKEN 权限 |
| 2. 查看日志：`/var/log/openclaw/backup.log` |
| 3. 确认 Dataset 仓库存在且有写入权限 |
| |
| ### 恢复失败 |
| |
| 1. 确认备份元数据完整 |
| 2. 检查恢复目标目录有足够空间 |
| 3. 元数据版本不兼容时，系统会以兼容模式尝试恢复 |
| |
| ### 大文件备份超时 |
| |
| - 启用分卷备份：`OPENCLAW_BACKUP_SPLIT_SIZE="500M"` |
| - 增加 HuggingFace 下载超时：`HF_HUB_DOWNLOAD_TIMEOUT=300` |
| |
| --- |
| |
| ## 元数据版本兼容性 |
| |
| | 版本 | 说明 | |
| |------|------| |
| | 1.0 | 初始版本 | |
| | 2.0 | 支持增量备份链 | |
| | 2.1 | 增强兼容性检查 | |
| |
| 系统支持向后兼容，降级使用时会有警告但不影响基本功能。 |
| |
