# 备份与恢复

只有同时保存 PostgreSQL 数据，以及解释这些数据所需的机密信息和配置，AISIX Enterprise 控制面才能恢复。数据库备份缺少匹配的主密钥，会使加密凭据无法读取。配置文件没有匹配的数据库，也无法重建组织、资源或现有网关信任的证书颁发机构。

应将数据库、加密密钥、部署配置和软件版本视为同一个恢复集。请保留每项资产的匹配副本，将整个恢复集作为敏感数据保护，并在依赖它执行升级回滚或灾难恢复之前演练恢复流程。

## 选择恢复范围[​](#choose-the-recovery-scope "选择恢复范围的直接链接")

| 目标                               | 所需保护措施                                                                                                                                                |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 恢复完整的 AISIX Enterprise 控制面 | 同时备份完整 PostgreSQL 状态、匹配的机密信息、部署配置和软件版本。                                                                                          |
| 回滚升级                           | 在升级前立即创建恢复集。启动旧版控制面前，先恢复数据库。                                                                                                    |
| 迁移或复现单个组织                 | 使用[组织备份与恢复](https://docs.apiseven.com/ai-gateway/cloud/organization-backup-and-restore.md)。备份包只能恢复到新安装的控制面，不能替代完整部署备份。 |
| 控制面短暂中断期间保持网关服务     | 配置[离线韧性](https://docs.apiseven.com/ai-gateway/cloud/offline-resilience.md)。网关快照缓存用于维持服务连续性，不是控制面备份。                          |

## 保护恢复集[​](#protect-the-recovery-set "保护恢复集的直接链接")

使用以下资产构建恢复集，并将其存储和保留在部署故障域之外。

### PostgreSQL 状态[​](#postgresql-state "PostgreSQL 状态的直接链接")

控制面数据库包含组织、环境、用户、模型、策略、加密凭据、投射到网关的配置、审计和用量数据，以及根证书颁发机构与网关证书账本。请备份整个数据库，不要只选择个别应用表。

使用 PostgreSQL 感知的备份方式，或与 PostgreSQL 协调一致的存储快照。不要把正在运行的数据库卷当作普通文件复制。备份必须同时保留 `public`、`auth` 模式，以及 `dp-manager` 创建的 Kine 表。

对于外部数据库，请把连接角色、它对数据库的所有权，以及 DBA 额外授予的模式权限纳入数据库恢复计划。单个数据库的转储不会保留集群全局角色，因此请在恢复前按[外部数据库](https://docs.apiseven.com/ai-gateway/on-premises/external-database.md)重新创建连接角色，并以该角色执行恢复，使其继续拥有控制面表。

上次由受支持的 1.6.0 至 1.7.0 版本控制面使用的数据库，可能仍保留授予 `cp_api_app` 的权限。这个角色由这些版本使用，当前控制面不会删除它。此类数据库的转储中包含引用该角色的语句。目标集群没有 `cp_api_app` 时，`pg_restore` 会对每条这类语句报错，其余内容照常恢复；使用 `pg_restore --no-privileges` 恢复可以避免这些错误。`cp-api` 每次启动时都会重新设置其自有函数的权限。如需从源集群删除该角色，请参见[删除 `cp_api_app` 角色](https://docs.apiseven.com/ai-gateway/on-premises/upgrade.md#remove-the-cp_api_app-role)。

从运行 1.6.0 至 1.7.0 版本的控制面获取的恢复集，需要用对应版本的软件恢复。这些版本仍使用 `cp_api_app`，并要求连接角色具备 `CREATEROLE` 和 `BYPASSRLS`。恢复时请按对应版本的文档操作。

角色要求请参阅[外部数据库](https://docs.apiseven.com/ai-gateway/on-premises/external-database.md)。AISIX 不提供数据库备份命令，也不会替代数据库平台负责的备份工具和保留策略。

控制面对用量、审计等持续增长数据的保留期，以及如何规划和维护数据库，请参见[数据库运维](https://docs.apiseven.com/ai-gateway/on-premises/database-operations.md)。

### 加密与认证机密信息[​](#encryption-and-authentication-secrets "加密与认证机密信息的直接链接")

当前主密钥用于加密已保存的服务提供方与集成凭据，以及根证书颁发机构的私钥。请保留当前密钥、其密钥 ID，以及仍可能封装某个已存储值的每个退役密钥。数据库无法恢复丢失的必要主密钥材料。

还要保留数据库凭据，以及配置了邮件时的 SMTP 密码。请将这些值保存在机密信息管理系统或加密备份中，其访问控制至少应与数据库备份同等严格。

### 部署配置[​](#deployment-configuration "部署配置的直接链接")

请保留用于定位和暴露恢复后服务的配置，包括公开控制面与 `dp-manager` URL、数据库连接、私有 CA 挂载、镜像覆盖项和网络访问设置。还要保留默认安装包或 Chart 之外提供的所有额外环境变量和 Kubernetes Secret。

若使用另一个部署的配置恢复数据库，可能导致认证失败、密文不可读，或证书颁发机构与网关证书记录不匹配。

### 发布版本信息[​](#release-identity "发布版本信息的直接链接")

记录备份时的控制面安装包或 Chart 版本，以及实际生效的镜像引用。恢复时先使用该版本。启动更高版本可能会在验证恢复前迁移数据库，而不支持使用旧版控制面连接采用较新结构的数据库。

请保留固定版本的安装包或经过测试的获取方式；对于隔离网络部署尤其如此。单独记录有意设置的镜像覆盖项，因为它们可能跨越常规安装包或 Chart 升级而继续存在。

### 存储、保留和访问[​](#storage-retention-and-access "存储、保留和访问的直接链接")

恢复集表示数据库、机密信息、配置和软件版本之间的逻辑匹配；这些产物不必存放在同一位置。将加密密钥与已加密的数据库备份分开存储，可以降低单一存储位置泄露的影响，但恢复清单必须标明匹配的副本。

至少保留一份位于部署主机、集群和存储故障域之外的恢复副本。为每份副本定义恢复点目标、备份频率、保留期和删除控制。对传输中和静态备份加密，限制访问，并在恢复集清单中记录校验和或其它完整性信号。

定期确认保留的安装包或 Chart 版本及所有外部机密信息来源仍可获取。若数据库备份对应的主密钥或软件已经丢失，该备份无法恢复。

## 备份 Docker Compose 部署[​](#back-up-a-docker-compose-deployment "备份 Docker Compose 部署的直接链接")

打包部署将 PostgreSQL 数据存储在 `aisix-self-hosted_pgdata` 卷中，并将部署机密信息和设置保存在 `./aisix-self-hosted/.env`。数据卷在执行 `./run.sh down` 和解压新安装包后仍会保留，但后续安装包不包含 `.env`，也无法从数据卷重建它。

请一起保留以下资产：

| 资产                                                         | 必要性                                                                                |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| 完整 PostgreSQL 备份或一致的 `aisix-self-hosted_pgdata` 快照 | 恢复全部控制面和证书状态。                                                            |
| `.env`                                                       | 保留数据库密码、主密钥与密钥 ID、SMTP 设置、URL、版本固定值，以及镜像或运行时覆盖项。 |
| 匹配的安装包或固定版本的安装包位置                           | 恢复与备份数据库结构匹配的脚本、Compose 定义和默认镜像集合。                          |
| 外部文件和本地部署定制                                       | 恢复私有 CA 证书和其它未存储在 PostgreSQL 中、由运维人员管理的输入。                  |

创建冷卷快照时，请先停止堆栈，使 PostgreSQL 不再写入，随后为完整卷创建快照，再重新启动同一个安装。在线备份应使用可提供一致恢复点的 PostgreSQL 感知工具。恢复正常变更活动前，请验证备份可以读取。

不要把安装包归档当作机密信息备份。解压另一个安装包会保留已有 `.env`，但不会重建丢失的 `.env`。

## 备份 Helm 部署[​](#back-up-a-helm-deployment "备份 Helm 部署的直接链接")

对于 Helm 安装，请通过负责各项资产的系统保留同一个恢复集：

| 资产                                    | 保护位置或方式                                                                                      |
| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 内置 PostgreSQL                         | 使用数据库感知流程或协调一致的卷快照备份 PostgreSQL PVC。                                           |
| 外部 PostgreSQL                         | 使用数据库服务提供的备份、时间点恢复和角色管理流程。                                                |
| 主密钥和 SMTP 密码                      | 保留 Chart 渲染的 Secret、`api.smtp.existingSecret` 指定的已有 Secret，以及提供这些值的受保护来源。 |
| 数据库和可选服务角色凭据                | 保留已配置的现有 Secret，或渲染它们的受保护值来源。                                                 |
| 实际生效的 Helm values 和发布历史       | 保留 values 来源、Chart 版本、命名空间、release 名称、镜像标签和有意设置的覆盖项。                  |
| 额外挂载的 Secret、ConfigMap 和 CA 文件 | 通过负责这些资源的机密信息管理系统或配置系统备份。                                                  |

Chart 使用 `helm.sh/resource-policy: keep` 标记主要应用 Secret，因此普通 Helm uninstall 不会删除它。如果命名空间或集群丢失，该注解无法保护此 Secret；请单独备份其来源或加密副本。

导出的 Helm values 可能包含数据库密码和应用机密信息，应按敏感数据处理。values 引用现有 Secret 时，只备份 values 并不能保留 Secret 内容。

## 创建面向变更的备份[​](#take-a-change-scoped-backup "创建面向变更的备份的直接链接")

执行升级或其它会影响数据库结构的变更前：

1. 确认当前控制面版本和实际生效的镜像覆盖项。
2. 创建一致的 PostgreSQL 备份。
3. 获取匹配的 Compose `.env`，或匹配的 Helm values 和机密信息来源。
4. 将备份时间、数据库身份、部署名称、软件版本、存储位置和完整性校验和记录为同一个恢复集清单。
5. 验证备份产物可读，且仍能获取所需凭据和固定版本的软件。

在获取这些内容期间不要执行无关的配置变更或密钥轮换。如果数据库或其加密密钥集合发生变化，请创建新的恢复集。

## 恢复控制面[​](#restore-the-control-plane "恢复控制面的直接链接")

如条件允许，请先恢复到隔离目标。在确认结果之前，阻止恢复后的控制面发送通知、访问生产服务提供方或接受生产网关连接。

1. 选择一个完整恢复集，并获取匹配的安装包或 Chart 版本。
2. 恢复部署配置和机密信息来源，包括数据库所需的所有主密钥。
3. 在控制面服务停止时恢复 PostgreSQL。对于外部数据库，先重新创建文档要求的连接角色并授予所需权限。如果备份包含引用 `cp_api_app` 的授权，请参见 [PostgreSQL 状态](#postgresql-state)。
4. 通过正常的 Compose 或 Helm 部署路径启动匹配版本的控制面。
5. 检查启动日志，确认 `cp-api` 和 `dp-manager` 均已健康，且没有数据库、主密钥、迁移或 `ca_root` 错误。
6. 使用恢复出的数据库中的账号登录，并验证组织、环境、资源和网关注册信息。恢复出的数据库已经有用户，因此无论首个管理员设置如何，`cp-api` 都不会创建首个管理员。
7. 确认网关可以向 `dp-manager` 进行身份认证，且[资源投射](https://docs.apiseven.com/ai-gateway/cloud/resource-projection.md)达到预期修订版本。
8. 如果可以访问安全的测试服务提供方，请通过非生产网关发送受控请求，并确认响应和已配置的遥测数据。
9. 只有在这些检查通过后，才重新启用外部集成和生产网关连接。

启动回滚版本前，请先恢复数据库。部署包的 `AISIX_ALLOW_DOWNGRADE=1` 覆盖项仅用于确认有意回滚，不能让不兼容或已迁移的数据库变得安全。请按照[升级 AISIX Enterprise](https://docs.apiseven.com/ai-gateway/on-premises/upgrade.md#roll-back)中相应安装方式的回滚流程操作。

如果数据库包含网关证书记录却没有 `ca_root`，优先恢复完整的数据库备份。全新引导覆盖项会创建新的证书颁发机构，并强制所有网关重新注册；它不会恢复丢失的密钥。请参阅[恢复缺失的 CA Root](https://docs.apiseven.com/ai-gateway/reference/on-premises-configuration.md#recover-a-missing-ca-root)。

### 回滚 Helm 控制面升级[​](#roll-back-a-helm-control-plane-upgrade "回滚 Helm 控制面升级的直接链接")

按[升级 AISIX Enterprise](https://docs.apiseven.com/ai-gateway/on-premises/upgrade.md#roll-back)中的步骤回滚网关后，使用此流程。设置控制面 Release、命名空间和回滚超时：

```
export CP_NAMESPACE="aisix"

export CP_RELEASE="aisix-cp"

export CP_UPGRADE_TIMEOUT="35m"
```

列出 Release 历史，找出升级前成功运行的修订：

```
helm history "$CP_RELEASE" --namespace "$CP_NAMESPACE"
```

停止控制面 API 和数据面管理器的数据库写入方：

```
kubectl scale deployment \

  --namespace "$CP_NAMESPACE" \

  --selector "app.kubernetes.io/instance=$CP_RELEASE,app.kubernetes.io/component in (api,dpm)" \

  --replicas 0
```

扩缩容命令会在 Pod 完成终止前返回。等待它们被删除：

```
kubectl wait pod \

  --namespace "$CP_NAMESPACE" \

  --selector "app.kubernetes.io/instance=$CP_RELEASE,app.kubernetes.io/component in (api,dpm)" \

  --for=delete \

  --timeout="$CP_UPGRADE_TIMEOUT"
```

完成[恢复控制面](#restore-the-control-plane)的步骤 1–3，在恢复 PostgreSQL 后保持写入方停止。然后将工作负载回滚到升级前的 Chart 修订：

```
helm rollback "$CP_RELEASE" <pre-upgrade-revision> \

  --namespace "$CP_NAMESPACE" \

  --wait \

  --timeout "$CP_UPGRADE_TIMEOUT"
```

在恢复数据库和执行 Helm 回滚之间，不要让较新版本的工作负载重新启动。针对已恢复的 Release，完成[恢复控制面](#restore-the-control-plane)的步骤 5–9。

## 演练恢复[​](#rehearse-recovery "演练恢复的直接链接")

只有成功恢复过的备份才经过验证。请根据部署风险和变更频率，定期在隔离环境中演练。

演练期间：

* 从记录的恢复集恢复数据库、机密信息、配置和匹配的软件；
* 验证加密资源能够加载且没有主密钥错误；
* 确认证书颁发机构和网关证书记录存在；
* 登录并检查具有代表性的组织和环境资源；
* 连接非生产网关并验证资源投射；
* 发送受控请求并验证响应和已配置的遥测数据；
* 记录恢复耗时、所需手动操作和缺失的外部依赖。

演练结束后，应修正备份流程，而不是把不可重复的临时处理写成操作说明。流程或所需资产清单发生变化时，请创建新的恢复集。

## 不能替代部署备份的内容[​](#what-does-not-replace-a-deployment-backup "不能替代部署备份的内容的直接链接")

* 网关快照缓存可在控制面暂时中断时保留最近接受的网关配置，但无法重建控制面。
* 脱敏的组织备份包会有意移除有效凭据和证书颁发机构状态。
* 完整组织备份包只覆盖一个组织，并且只能恢复到全新安装的控制面，取代该安装的首个组织和管理员。它可以迁移，但不是完整控制面备份。
* 安装包归档包含软件和部署模板，不包含生成的 `.env` 或 PostgreSQL 数据。
* Helm release 元数据不能替代数据库或外部管理的 Secret 内容。
