备份与恢复
只有同时保存 PostgreSQL 数据，以及解释这些数据所需的密钥和配置，AISIX Enterprise 才能恢复。数据库备份缺少匹配的主密钥，会使加密凭据无法读取。配置文件没有匹配的数据库，也无法重建组织、资源或现有网关信任的证书颁发机构。
应将数据库、加密密钥、部署配置和软件版本视为同一个恢复集。请保留每项资产的匹配副本，将整个恢复集作为敏感数据保护，并在依赖它执行升级回滚或灾难恢复之前演练恢复流程。
选择恢复范围
| 目标 | 所需保护措施 |
|---|---|
| 恢复完整的 AISIX Enterprise 控制面 | 同时备份完整 PostgreSQL 状态、匹配的密钥、部署配置和软件版本。 |
| 回滚升级 | 在升级前立即创建恢复集。启动旧版控制面前，先恢复数据库。 |
| 迁移或复现单个组织 | 使用组织备份与恢复。备份包只能恢复到新安装的控制面，不能替代完整部署备份。 |
| 控制面短暂中断期间保持网关服务 | 配置离线韧性。网关快照缓存用于维持服务连续性，不是控制面备份。 |
保护恢复集
使用以下资产构建恢复集，并将其存储和保留在部署故障域之外。
PostgreSQL 状态
控制面数据库包含组织、环境、用户、模型、策略、加密凭据、投射到网关的配置、审计和用量数据，以及根证书颁发机构与网关证书账本。请备份整个数据库，不要只选择个别应用表。
使用 PostgreSQL 感知的备份方式，或与 PostgreSQL 协调一致的存储快照。不要把正在运行的数据库卷当作普通文件复制。备份必须同时保留 public、auth schema，以及 dp-manager 创建的 Kine 表。
对于外部数据库，请把连接角色、所有权和所需权限纳入数据库恢复计划。即使单库 dump 包含引用 cp_api_app 的授权，它也不会保留集群全局角色。请选择一种恢复策略：
- 保留带有
NOSUPERUSER NOBYPASSRLS NOINHERIT NOLOGIN属性的cp_api_app，并恢复依赖 该角色的所有权和权限语句； - 省略这些语句，让
cp-api在启动时重新创建角色和授权。
两种角色契约请参阅外部数据库。AISIX 不提供数据库备份命令，也不会替代数据库平台负责的备份工具和保留策略。
控制面对用量、审计等持续增长数据的保留期，以及如何规划和维护数据库，请参见数据库运维。
加密与认证 Secret
当前主密钥用于加密已保存的服务提供方与集成凭据，以及根证书颁发机构的私钥。请保留当前密钥、其密钥 ID，以及仍可能封装某个已存储值的每个退役密钥。数据库无法恢复丢失的必要主密钥材料。
还要保留数据库凭据，以及配置了邮件时的 SMTP 密码。1.5.x 或更早版本部署的恢复集还包括该版本的控制台认证 Secret（BETTER_AUTH_SECRET 或 secrets.betterAuthSecret），1.5.x 及更早版本启动时需要它。请将这些值保存在 Secret 管理系统或加密备份中，其访问控制至少应与数据库备份同等严格。
部署配置
请保留用于定位和暴露恢复后服务的配置，包括公开控制面与 dp-manager URL、数据库连接、私有 CA 挂载、镜像覆盖项和网络访问设置。还要保留默认安 装包或 Chart 之外提供的所有额外环境变量和 Kubernetes Secret。
若使用另一个部署的配置恢复数据库，可能导致认证失败、密文不可读，或证书颁发机构与网关证书记录不匹配。
发布版本信息
记录备份时的控制面安装包或 Chart 版本，以及实际生效的镜像引用。恢复时先使用该版本。启动更高版本可能会在验证恢复前迁移数据库，而使用更低版本启动更新 schema 的数据库不受支持。
请保留固定版本的安装包或经过测试的获取方式；对于隔离网络部署尤其如此。单独记录有意设置的镜像覆盖项，因为它们可能跨越常规安装包或 Chart 升级而继续存在。
存储、保留和访问
恢复集表示数据库、Secret、配置和软件版本之间的逻辑匹配；这些产物不必存放在同一位置。将加密密钥与已加密的数据库备份分开存储，可以降低单一存储位置泄露的影响，但恢复清单必须标明匹配的副本。
至少保留一份位于部署主机、集群和存储故障域之外的恢复副本。为每份副本定义恢复点目标、备份频率、保留期和删除控制。对传输中和静态备份加密，限制访问，并在恢复集清单中记录校验和或其它完整性信号。
定期确认保留的安装包或 Chart 版本及所有外部 Secret 来源仍可获取。若数据库备份对应的主密钥或软件已经丢失，该备份无法恢复。
备份 Docker Compose 部署
打包部署将 PostgreSQL 数据存储在 aisix-self-hosted_pgdata 卷中，并将部署 Secret 和设置保存在 ./aisix-self-hosted/.env。数据卷在执行 ./run.sh down 和解压新安装包后仍会保留，但后续安装包不包含 .env，也无法从数据卷重建它。
请一起保留以下资产：
| 资产 | 必要性 |
|---|---|
完整 PostgreSQL 备份或一致的 aisix-self-hosted_pgdata 快照 | 恢复全部控制面和证书状态。 |
.env | 保留数据库密码、主密钥与密钥 ID、SMTP 设置、URL、版本固定值，以及镜像或运行时覆盖项。1.5.x 或更早版本的 .env 还包含控制台认证 Secret。 |
| 匹配的安装包或固定版本的安装包位置 | 恢复与备份数据库 schema 匹配的脚本、Compose 定义和默认镜像集合。 |
| 外部文件和本地部署定制 | 恢复私有 CA 证书和其它未存储在 PostgreSQL 中、由运维人员管理的输入。 |
创建冷卷快照时，请先停止堆栈，使 PostgreSQL 不再写入，随后为完整卷创建快照，再重新启动同一个安装。在线备份应使用可提供一致恢复点的 PostgreSQL 感知工具。恢复正常变更活动前，请验证备份可以读取。
不要把安装包归档当作 Secret 备份。解压另一个安装包会保留已有 .env，但不会重建丢失的 .env。
备份 Helm 部署
对于 Helm 安装，请通过负责各项资产的系统保留同一个恢复集：
| 资产 | 保护位置或方式 |
|---|---|
| 内置 PostgreSQL | 使用数据库感知流程或协调一致的卷快照备份 PostgreSQL PVC。 |
| 外部 PostgreSQL | 使用数据库服务提供的备份、时间点恢复和角色管理流程。 |
| 主密钥、SMTP 密码，以及 1.5.x 或更早版本的控制台认证 Secret | 保留 Chart 渲染的 Secret、api.smtp.existingSecret 指定的已有 Secret，以及提供这些值的受保护来源。 |
| 数据库和可选服务角色凭据 | 保留已配置的现有 Secret，或渲染它们的受保护值来源。 |
| 实际生效的 Helm values 和发布历史 | 保留 values 来源、Chart 版本、命名空间、release 名称、镜像 tag 和有意设置的覆盖项。 |
| 额外挂载的 Secret、ConfigMap 和 CA 文件 | 通过其所属 Secret 或配置系统进行备份。 |
Chart 使用 helm.sh/resource-policy: keep 标记主要应用 Secret，因此普通 Helm uninstall 不会删除它。该注解无法防止命名空间或集群丢失；请单独备份其来源或加密副本。
导出的 Helm values 可能包含数据库密码和应用 Secret，应按敏感数据处理。values 引用现有 Secret 时，只备份 values 并不能保留 Secret 内容。
创建面向变更的备份
执行升级或其它会影响 schema 的变更前：
- 确认当前控制面版本和实际生效的镜像覆盖项。
- 创建一致的 PostgreSQL 备份。
- 获取匹配的 Compose
.env或 Helm values 与 Secret 来源。 - 将备份时间、数据库身份、部署名称、软件版本、存储位置和完整性校验和记录为同一个恢复集清单。
- 验证备份产物可读，且仍能获取所需凭据和固定版本的软件。
在获取这些内容期间不要执行无关的配置变更或密钥轮换。如果数据库或其加密密钥集合发生变化，请创建新的恢复集。
恢复控制面
如条件允许，请先恢复到隔离目标。在确认结果之前，阻止恢复后的控制面发送通知、访问生产服务提供方或接受生产网关连接。
- 选择一个完整恢复集，并获取匹配的安装包或 Chart 版本。
- 恢复部署配置和 Secret 来源，包括数据库所需的所有主密钥。
- 在控制面服务停止时恢复 PostgreSQL。对于外部数据库，重新创建文档要求的连接角色和权限。如果备份包含引用
cp_api_app的授权，请在恢复数据库前使用上述属性重新创建该内部角色。如果备份省略依赖角色的所有权和权限语句，让cp-api在启动时重新创建内部角色和授权。 - 通过正常的 Compose 或 Helm 部署路径启动匹配版本的控制面。
- 检查启动日志，确认
cp-api和dp-manager均已健康，且没有数据库、主密钥、迁移或ca_root错误。 - 使用恢复出的数据库中的账号登录，并验证组织、环境、资源和网关注册信息。恢复出的数据库已经有用户，因此无论首个管理员设置如何，
cp-api都不会创建首个管理员。 - 确认网关可以向
dp-manager进行身份认证，且资源投射达到预期 revision。 - 如果存在安全的测试服务提供方，请通过非生产网关发送受控请求，并确认响应和已配置的遥测数据。
- 只有在这些检查通过后，才重新启用外部集成和生产网关连接。
启动回滚版本前，请先恢复数据库。部署包的 AISIX_ALLOW_DOWNGRADE=1 覆盖项仅用于确认有意回滚，不能让不兼容或已迁移的数据库变得安全。请按照升级 AISIX Enterprise中相应安装方式的回滚流程操作。
如果数据库包含网关证书记录却没有 ca_root，优先恢复完整的数据库备份。全新引导覆盖项会创建新的证书颁发机构，并强制所有网关重新注册；它不会恢复丢失的密钥。请参阅恢复缺失的 CA Root。
演练恢复
只有成功恢复过的备份才经过验证。请根据部署风险和变更频率，定期在隔离环境中演练。
演练期间：
- 从记录的恢复集恢复数据库、Secret、配置和匹配的软件；
- 验证加密资源能够加载且没有主密钥错误；
- 确认证书颁发机构和网关证书记录存在；
- 登录并检查具有代表性的组织和环境资源；
- 连接非生产网关并验证资源投射；
- 发送受控请求并验证响应和已配置的遥测数据；
- 记录恢复耗时、所需手动操作和缺失的外部依赖。
演练结束后，应修正备份流程，而不是把不可重复的临时处理写成操作说明。流程或所需资产清单发生变化时，请创建新的恢复集。
不能替代部署备份的内容
- 网关快照缓存可在控制面暂时中断时保留最近接受的网关配置，但无法重建控制面。
- 脱敏的组织备份包会有意移除实时凭据和证书颁发机构状态。
- 完整组织备份包只覆盖一个组织，并且只能恢复到全新安装的控制面，取代该安装的首个组织和管理员。它可以迁移，但不是完整控制面备份。
- 安装包归档包含软件和部署模板，不包含生成的
.env或 PostgreSQL 数据。 - Helm release 元数据不能替代数据库或外部管理的 Secret 内容。