跳到主要内容
版本:1.10.0

备份与恢复

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

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

选择恢复范围​

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

保护恢复集​

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

PostgreSQL 状态​

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

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

对于外部数据库,请把连接角色、它对数据库的所有权,以及 DBA 额外授予的模式权限纳入数据库恢复计划。单个数据库的转储不会保留集群全局角色,因此请在恢复前按外部数据库重新创建连接角色,并以该角色执行恢复,使其继续拥有控制面表。

上次由受支持的 1.6.0 至 1.7.0 版本控制面使用的数据库,可能仍保留授予 cp_api_app 的权限。这个角色由这些版本使用,当前控制面不会删除它。此类数据库的转储中包含引用该角色的语句。目标集群没有 cp_api_app 时,pg_restore 会对每条这类语句报错,其余内容照常恢复;使用 pg_restore --no-privileges 恢复可以避免这些错误。cp-api 每次启动时都会重新设置其自有函数的权限。如需从源集群删除该角色,请参见删除 cp_api_app 角色。

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

角色要求请参阅外部数据库。AISIX 不提供数据库备份命令,也不会替代数据库平台负责的备份工具和保留策略。

控制面对用量、审计等持续增长数据的保留期,以及如何规划和维护数据库,请参见数据库运维。

加密与认证机密信息​

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

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

部署配置​

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

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

发布版本信息​

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

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

存储、保留和访问​

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

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

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

备份 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 部署​

对于 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 内容。

创建面向变更的备份​

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

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

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

恢复控制面​

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

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

启动回滚版本前,请先恢复数据库。部署包的 AISIX_ALLOW_DOWNGRADE=1 覆盖项仅用于确认有意回滚,不能让不兼容或已迁移的数据库变得安全。请按照升级 AISIX Enterprise中相应安装方式的回滚流程操作。

如果数据库包含网关证书记录却没有 ca_root,优先恢复完整的数据库备份。全新引导覆盖项会创建新的证书颁发机构,并强制所有网关重新注册;它不会恢复丢失的密钥。请参阅恢复缺失的 CA Root。

回滚 Helm 控制面升级​

按升级 AISIX Enterprise中的步骤回滚网关后,使用此流程。设置控制面 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"

完成恢复控制面的步骤 1–3,在恢复 PostgreSQL 后保持写入方停止。然后将工作负载回滚到升级前的 Chart 修订:

helm rollback "$CP_RELEASE" <pre-upgrade-revision> \
--namespace "$CP_NAMESPACE" \
--wait \
--timeout "$CP_UPGRADE_TIMEOUT"

在恢复数据库和执行 Helm 回滚之间,不要让较新版本的工作负载重新启动。针对已恢复的 Release,完成恢复控制面的步骤 5–9。

演练恢复​

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

演练期间:

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

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

不能替代部署备份的内容​

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