如何备份和恢复 Kestra 的流程、密钥与执行数据

Kestra 企业版内置元数据备份功能。要实现完整灾难恢复，也可以使用后端工具直接备份底层数据库和内部存储。

备份与恢复只能通过 CLI 执行，没有对应的 REST API、界面或内置调度器。可以将 CLI 命令接入自己的 cron、CI/CD 或灾难恢复工具。

以下元数据命令假定 Kestra 在宿主机本地运行。如果通过 Docker 运行，请参阅后面的容器示例。

元数据备份与恢复（企业版）

Kestra Enterprise Edition 支持将一个实例的元数据备份后恢复到另一个实例，甚至可以跨 Kestra 版本、仓库后端或队列后端迁移。

为确保一致性，应在暂停 Kestra 时进行元数据备份和恢复。建议开始前启用维护模式。

包含哪些内容

元数据备份导出执行历史以外的所有资源类型。默认包含：应用、横幅、绑定、蓝图、凭据、仪表板、流程、组、邀请、紧急停止开关、KV 条目、命名空间文件、命名空间、角色、密钥（使用兼容密钥后端时）、安全集成、设置、租户、租户访问权限、测试套件、触发器、用户和工作节点组。

执行数据——执行记录、日志、指标、审计日志和测试运行——因体积较大而默认排除。使用 --include-data 可将它们纳入备份。

每次备份都会写入新的带时间戳归档，不覆盖已有文件。系统不会自动清理旧归档，需要自行管理保留策略。

备份元数据

备份实例元数据：

kestra backups create FULL

FULL 备份整个实例，包括所有租户和实例级资源，例如用户、设置、工作节点组及紧急停止开关。若只备份单个租户，使用 TENANT；它只包含该租户的数据，排除实例级资源。

要只备份指定资源类型，使用 --resources：

kestra backups create FULL --resources FLOW,KV_STORE,SECRET

可用资源名称包括：APP、BANNER、BINDING、BLUEPRINT、CREDENTIAL、DASHBOARD、EXECUTION、FLOW、GROUP、INVITATION、KILL_SWITCH、KV_STORE、LOG、METRIC、NAMESPACE、NAMESPACE_FILE、ROLE、SECRET、SECURITY_INTEGRATION、SETTING、TENANT、TENANT_ACCESS、TEST_SUITE、TRIGGER、USER 和 WORKER_GROUP。

备份选项：

• --tenant：用于 TENANT 备份，指定租户，默认为 default。
• --encryption-key：指定自定义加密密钥。省略时使用实例密钥 kestra.encryption.secret-key；两者都未配置则命令失败。
• --no-encryption：禁用加密，只适合向演示实例导入非敏感内容等用途。
• --include-data：包含执行记录、日志、指标、审计日志及测试运行；这些数据默认因体积较大而排除。

备份结束后，CLI 输出摘要及归档的内部存储 URI。以下为原文示例日志：

2024-09-17 16:33:12,706 INFO  create       io.kestra.ee.backup.BackupService Backup summary: [BINDING: 3, BLUEPRINT: 1, FLOW: 13, GROUP: 1, NAMESPACE: 1, ROLE: 6, SECRET: 1, SECURITY_INTEGRATION: 0, SETTING: 1, TENANT: 1, TENANT_ACCESS: 2, TRIGGER: 2, USER: 1]
2024-09-17 16:33:12,706 INFO  create       io.kestra.ee.backup.BackupService Backup instance created in 508 ms
Backup created: kestra:///backups/full/backup-20240917163312.kestra

完整归档位于 kestra:///backups/full/；租户归档位于 kestra:///backups/tenants/<tenant>/。

恢复元数据

使用备份命令返回的 URI 进行恢复：

kestra backups restore kestra:///backups/full/backup-20240917163312.kestra

多数资源类型的恢复具有幂等性。记录按稳定键执行 upsert，因此这些资源即使只恢复了一部分，也可以重新运行恢复。

LOG 和 METRIC 没有稳定标识符，始终执行插入而非 upsert。重复恢复这些类型会产生重复日志和指标。如果实例已经包含上次恢复的数据，重新运行时应通过 --resources 选择其他资源，排除这两类。

恢复命令会比较归档中的 Kestra 版本与当前实例版本，不一致时输出警告。警告不会阻止恢复，但在生产环境继续前应先检查。

恢复选项：

• --encryption-key：解密密钥。省略时使用实例密钥，两者都没有则失败。
• --to-tenant：把租户备份恢复到另一个租户，将每条记录的租户 ID 改为目标租户。不支持完整归档，对完整归档使用此选项会导致命令失败。
• --resources：只恢复指定资源类型，名称与 create 相同。

完成后的原文示例日志如下，时间与版本号按原文保留：

2024-09-17 16:41:06,065 INFO  restore      io.kestra.ee.backup.BackupService Restoring kestra:///backups/full/backup-20240917163312.kestra
2024-09-17 16:41:06,149 INFO  restore      io.kestra.ee.backup.BackupService Restoring FULL backup from Kestra version 2.0.0 created at 2024-09-17T16:33:12.700099909
2024-09-17 16:41:06,150 INFO  restore      io.kestra.ee.backup.BackupService Backup summary: [BINDING: 3, BLUEPRINT: 1, FLOW: 13, GROUP: 1, NAMESPACE: 1, ROLE: 6, SECRET: 1, SECURITY_INTEGRATION: 0, SETTING: 1, TENANT: 1, TENANT_ACCESS: 2, TRIGGER: 2, USER: 1]
2024-09-17 16:41:07,182 INFO  restore      io.kestra.ee.backup.BackupService Restore summary: [BINDING: 3, BLUEPRINT: 1, FLOW: 13, GROUP: 1, NAMESPACE: 1, ROLE: 6, SECRET: 1, SECURITY_INTEGRATION: 0, SETTING: 1, TENANT: 1, TENANT_ACCESS: 2, USER: 1, TRIGGER: 2]
Backup restored from URI: kestra:///backups/full/backup-20240917163312.kestra

示例：在 Docker 中备份和恢复

通过 docker exec 执行命令，使用 docker cp 在容器内外移动归档。原文示例包含 --no-encryption，因此只适用于前述非敏感演示内容；实际归档名应使用备份输出的名称。

## Create a full backup (with execution data) from inside the container
docker exec your_container bash -c "./kestra backups create FULL --include-data --no-encryption"

## Copy the backup file from the container to a local directory
docker cp your_container:/app/storage/backups/full/backup123.kestra .
## After upgrading Kestra, copy the backup back into the container
docker cp ./backup123.kestra your_container:/app/storage/backups/full/

## Restore the backup from inside the container
docker exec your_container bash -c "./kestra backups restore kestra:///backups/full/backup123.kestra"

使用后端工具进行完整备份和恢复

JDBC 后端

使用 JDBC 后端时，通过数据库原生工具备份和恢复 Kestra。

PostgreSQL

先停止 Kestra，使数据库处于稳定状态，然后备份：

pg_dump -h localhost -p 5432 -U <username> -d <database> -F tar -f kestra.tar

恢复：

pg_restore -h localhost -p 5432 -U <username> -d <database> kestra.tar

恢复完成后重新启动 Kestra。

MySQL

先停止 Kestra，再备份：

mysqldump -h localhost -P 3306 -u <username> -p'<password>' <database> > kestra.sql

恢复：

mysql -h localhost -P 3306 -u <username> -p'<password>' <database> < kestra.sql

恢复完成后重新启动 Kestra。

SQL Server

先停止 Kestra，再使用 SQL Server Management Studio 或 sqlcmd 创建备份：

BACKUP DATABASE [kestra] TO DISK = '/var/opt/mssql/backup/kestra.bak' WITH INIT;

恢复：

RESTORE DATABASE [kestra] FROM DISK = '/var/opt/mssql/backup/kestra.bak' WITH REPLACE;

恢复完成后重新启动 Kestra。这里保留原文的 SQL Server 段落；是否支持该后端须以实际 Kestra 版本为准，不能据此推断所有当前版本均支持。

Elasticsearch 与 Kafka 后端

使用 Elasticsearch 或 OpenSearch 后端时，通过 Elasticsearch 快照备份与恢复，随后从 Elasticsearch 重新初始化 Kafka。

本示例假定已配置名为 my_snapshot_repository 的快照仓库。配置选项见 Elasticsearch 快照文档。

创建快照：

## Kibana Dev Tools (Console) or curl (adjust host/auth as needed)
PUT _snapshot/my_snapshot_repository/kestra?wait_for_completion=true

原文恢复流程要求先删除所有 Kestra 索引，再从快照恢复；这会替换现有索引数据。以下是恢复请求：

POST _snapshot/my_snapshot_repository/kestra/_restore
{
  "indices": "kestra_*"
}

如果使用全新的 Kafka 集群，从 Elasticsearch 重新初始化 Kafka：

kestra sys-ee restore-queue

部分正在执行的状态仅存在于 Kafka，因此待完成的执行可能无法完全恢复。恢复完成后重新启动 Kestra。

内部存储

Kestra 的内部存储可以使用本地文件系统或对象存储。

• 本地文件系统：使用常规文件系统工具备份和恢复存储目录。
• 托管对象存储：启用跨区域复制，通常足以满足灾难恢复；也可以使用提供商的备份工具。
• 自托管对象存储，例如 MinIO：使用 Restic 等工具和／或配置复制。

---

原文：How to back up and restore flows, secrets, and execution data，Kestra 官方文档。版权归 Kestra 及相关权利人所有。