halo/docs/backup-and-restore.md

# 备份和恢复 Proposal

## Motivation

目前，Halo 2.x 支持多种数据库：H2、MySQL、MariaDB、Microsoft SQL Server、Oracle 和
PostgreSQL，虽然数据库有备份和恢复的功能，但是仍然缺少应用级别的备份和恢复功能。Halo
的数据不仅限于数据库中的数据，还包含工作目录下的数据，例如主题、插件和日志等。

## Goals

- 全站备份，包括数据库中的数据和工作目录的数据。
- 全站恢复，包括恢复数据库中的数据和工作目录的数据。
- 用户可控制备份文件存储的时间。
- 对于工作目录的数据，用户可选择性备份和恢复。
- 用户可指定备份权限到任意用户。

## Non-Goals

- 仅备份部分自定义资源。
- 仅备份和恢复文章 Markdown。
- 定时备份。
- 加密备份文件。
- 备份文件自动上传至对象存储。

## Use Cases

- 从某种数据库（例如：H2）迁移至另外的数据库（例如：MySQL），不会因为 SQL 的兼容性而影响迁移。
- 定时完整备份 Halo，并存储至对象存储，一旦发生意外可随时恢复。

## Requirements

- 仅支持 2.8.x 及以上的 Halo。
- 恢复的数据的 creationTimestamp 可能会被当前时间覆盖。

## Draft

恢复数据之前需要完整备份当前 Halo，以便恢复过程中发生错误导致无法回滚。

备份文件将存储在 `${halo.work-dir}/backups/halo-full-backup-2023.07.03-17:52:59.zip`。

备份整站可能需要大量的时间，所以我们需要创建自定义模型（Backup）用于保存用户创建备份的请求，并异步执行备份操作，最终将结果反馈至自定义模型数据中。

Backup 模型样例如下：

- 备份成功样例

```yaml
apiVersion: migration.halo.run/v1alpha1
kind: Backup
metadata:
  name: halo-full-backup-xyz
  creationTimestamp: 2023.07.04-10:25:30
spec:
  format: zip
  autoDeleteWhen: 2023.07.10-00:00:00Z
status:
  phase: Succeeded
  startTimestamp: 2023.07.04-10:25:31
  completionTimestamp: 2023.07.04-10:26:30
  filename: halo-full-backup-2023-07-04-10-25-30.zip
  size: 1024 # data unit: bytes
```

- 备份失败样例

```yaml
apiVersion: migration.halo.run/v1alpha1
kind: Backup
metadata:
  name: halo-full-backup-xyz
  creationTimestamp: 2023.07.04-10:25:30
spec:
  compressionFormat: zip | 7z | tar | tar.gz # 压缩格式
status:
  startTimestamp: 2023.07.04-10:25:31
  # Pending: 刚刚创建好 Backup 资源，等待 Reconciler reconcile。
  # Running: Reconciler 正在备份 Halo。
  # Succeeded: Reconciler 成功执行备份 Halo 操作。
  # Failed: 备份 Halo 失败。
  phase: Failed
  failureReason: DatabaseConnectionReset | UnsupportedCompression # 机器可识别的信息
  failureMessage: The database connection reset. # 人类可阅读的信息
```

同时，BackupReconciler 将负责备份操作，并更新 Backup 数据。

请求示例如下：

```text
POST /apis/migration.halo.run/v1alpha1/backups
Content-Type: application/json
```

### 备份

准备好所有的备份内容后，需要计算摘要并保存，以便后期恢复校验备份文件完整性使用。

#### 数据库备份和恢复

因为 Halo 的 [Extension 设计](https://github.com/halo-dev/rfcs/tree/main/extension)，所以 Halo 的在数据库中的数据备份相对比较简单，只需要简单备份
ExtensionStore 即可。恢复同理。

#### 工作目录备份和恢复

Halo 工作目录样例如下所示：

```text
├── application.yaml
├── attachments
│   └── upload
│       └── image_2023-06-09_16-24-41.png
├── db
│   └── halo-next.mv.db
├── indices
│   └── posts
│       ├── _a.cfe
│       ├── _a.cfs
│       ├── _a.si
│       ├── segments_h
│       └── write.lock
├── keys
│   ├── id_rsa
│   └── id_rsa.pub
├── logs
│   ├── halo.log
│   ├── halo.log.2023-06-01.0.gz
│   ├── halo.log.2023-06-02.0.gz
│   ├── halo.log.2023-06-05.0.gz
│   └── halo.log.2023-06-26.0.gz
├── plugins
│   ├── PluginCommentWidget-1.5.0.jar
│   ├── PluginFeed-1.1.1.jar
│   ├── PluginSearchWidget-1.0.0.jar
│   ├── PluginSitemap-1.0.2.jar
│   └── configs
└── themes
    ├── theme-earth
    │   ├── README.md
    │   ├── settings.yaml
    │   ├── templates
    │   │   ├── archives.html
    │   │   ├── assets
    │   │   │   ├── dist
    │   │   │   │   ├── main.iife.js
    │   │   │   │   └── style.css
    │   │   │   └── images
    │   │   │       ├── default-avatar.svg
    │   │   │       └── default-background.png
    │   │   ├── author.html
    │   │   ├── category.html
    │   │   ├── error
    │   │   │   └── error.html
    │   │   ├── index.html
    │   │   ├── links.html
    │   │   ├── modules
    │   │   │   ├── category-filter.html
    │   │   │   ├── category-tree.html
    │   │   │   ├── featured-post-card.html
    │   │   │   ├── footer.html
    │   │   │   ├── header.html
    │   │   │   ├── hero.html
    │   │   │   ├── layout.html
    │   │   │   ├── post-card.html
    │   │   │   ├── sidebar.html
    │   │   │   ├── tag-filter.html
    │   │   │   └── widgets
    │   │   │       ├── categories.html
    │   │   │       ├── latest-comments.html
    │   │   │       ├── popular-posts.html
    │   │   │       ├── profile.html
    │   │   │       └── tags.html
    │   │   ├── page.html
    │   │   ├── post.html
    │   │   ├── tag.html
    │   │   └── tags.html
    │   └── theme.yaml
```

备份时需要过滤 `db`、backups` 和 `indices` 目录。

#### 备份文件结构

备份文件主要包含自定义资源（`extensions.data`）和工作目录（`workdir.data`）的数据。

- `extensions.data`

前期可考虑使用 JSON 来存储所有的 ExtensionStore 数据。

- `workdir.data`

对工作目录进行 `ZIP` 压缩。

- config.yaml（备份配置）

主要用于描述 `extensions.data` 和 `workdir.data` 压缩格式，后续可扩展备份与恢复相关的配置。例如：

```yaml
compressions:
  extensions: json | others
  workdir: zip | others
```

前期可不实现该功能。

### 恢复

用户通过上传备份文件的方式进行恢复。当且仅当博客未初始化阶段才能进行恢复操作，否则可能会造成数据不一致。

请求示例如下：

```text
POST /apis/migration.halo.run/v1alpha1/restorations
Content-Type: multipart/form-data; boundary="boundary"

'''
--boundary
Content-Disposition: form-data; name="backupfile"; filename="halo-full-backup.zip"
Content-Type: application/zip
'''
```

恢复步骤如下：

1. 解压缩备份文件。
2. 校验备份文件的完整性。
2. 恢复所有 ExtensionStore。
3. 覆盖当前工作目录。
4. 备份完成。

> 需要注意内存占用问题。

## TBDs

- 数据备份期间可能会存在数据的创建、更新和删除。

我们将忽略这些数据变化。

- 是否支持在初始化博客后恢复数据？

支持。不过可能会覆盖掉已有的数据。