版本：1.3.0

组织备份与恢复

AISIX Cloud 可以把一个组织导出为 gzip 压缩的 SQL 备份文件，并把它导入到另一套控制面版本相同的部署。控制台和 Admin API 两种操作方式在 Hybrid Cloud 和 On-Premises 中均可使用。完整备份文件保留凭据和证书状态，可用于备份，也可用于在持有所需主密钥的部署之间迁移。脱敏备份文件把凭据替换为合成值，可用于技术支持复现问题，也可用于在不共享源端密钥的前提下迁移组织。

选择备份文件类型

按目标部署能否安全使用源部署的主密钥来选择备份文件类型：

备份文件	用途	恢复前提
完整	备份一个组织，或在不替换其凭据的前提下迁移该组织。	目标必须运行相同的控制面版本，并持有解密该文件所需的每一把源端主密钥，包括仍在封装某个已存储值的已停用密钥。
脱敏	为排查问题而复现一个组织，或在不共享源端主密钥的前提下迁移其结构。	目标必须运行相同的控制面版本。导入时会用目标的主密钥重新加密这些合成凭据。在把导入后的组织用于生产流量之前，请替换这些合成凭据。

请按数据库备份的标准保管完整备份文件

完整备份文件包含真实凭据。凭据在配置表中仍是信封加密的，但投射给网关的配置文档中是其明文值。该文件还包含根证书颁发机构的私钥。请按照保管和传输数据库的同等要求保管和传输它。

导出一个组织

交互式导出请使用控制台；如需自动执行定时备份或生成支持文件，请使用 Admin API。

使用控制台

打开 Settings → Backup & restore。选择是否脱敏凭据、设置审计记录的时间窗口，并可选择是否包含请求遥测数据。选择 Download backup 导出备份文件。

对组织 owner，脱敏默认关闭。组织 admin 只能导出脱敏备份文件，因此该开关对他们保持打开且锁定。

使用 Admin API

导出前请先设置 Admin API 基础 URL 和一个 Admin Token：

# AISIX_CP 包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

以下请求下载一份完整备份文件，并使用服务端提供的文件名：

curl -fSL "${AISIX_CP}/data_export" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -OJ

添加 ?redact=true 可下载脱敏备份文件。该接口还接受以下参数：

参数	默认值	作用
`redact`	`false`	把凭据替换为合成值。
`audit_since`	导出时间前 30 天	以 RFC 3339 时间戳设置审计事件的时间下界。
`include_usage_events`	`false`	是否包含请求遥测数据。
`usage_since`	导出时间前 7 天	以 RFC 3339 时间戳设置用量事件的时间下界。未包含用量事件时该参数无效。

响应为 application/gzip。其 Content-Disposition 响应头给出的文件名形如：

aisix-export-<org-slug>-<UTC YYYYMMDDThhmmssZ>-full.sql.gz
aisix-export-<org-slug>-<UTC YYYYMMDDThhmmssZ>-redacted.sql.gz

响应头 X-Aisix-Export-Redacted 也会以 true 或 false 标识导出模式。

在保管或传输之前，请确认下载已完整：

export AISIX_BUNDLE="PATH_TO_DOWNLOADED_BUNDLE"
gzip -t "${AISIX_BUNDLE}"

脱敏导出对组织的 admin 和 owner 开放。具备数据导出读取权限的自定义角色也可以下载脱敏备份文件。完整导出仅限 owner。owner 使用 Admin Token 时，该 Token 必须具备 write scope；只读 Token 无法下载真实凭据。

审计事件和用量事件各自以 100000 行为上限，按时间由新到旧截取。达到上限不会导致导出失败，备份文件的清单会把相应的表标记为已截断。

同一组织同时只能运行一次导出，整套部署同时最多运行两次。超出任一限制的请求会收到 409 EXPORT_IN_PROGRESS。每次完成的导出都会新增一条审计事件，记录导出模式、参数、主密钥指纹、各表行数以及截断状态。

恢复一个组织

官方支持的导入方式会在一个数据库事务内应用整个备份文件。导入要么完整成功，要么什么都不改变。由于备份文件只包含数据、不包含数据库结构，目标必须运行与源端相同的控制面版本。

请按目标部署的状态选择操作步骤：

如果目标部署已存在用户或组织，请登录控制台并上传备份文件。这条路径在 Hybrid Cloud 和 On-Premises 中均可使用。
如果是灾难恢复到一套空的 On-Premises 部署，请启动所需服务，并以未鉴权方式调用导入接口。

恢复到已有数据的部署

以用户身份登录目标部署，打开 Settings → Backup & restore，使用 Restore from a file。该操作会拒绝 Admin Token。已登录的用户会成为每个被导入组织的 owner。

导入不会合并组织或用户。当备份文件中的某个组织或用户在目标上已存在时，导入会被拒绝。

恢复到空的 On-Premises 部署

前两个服务会创建接收备份数据的数据库结构，请在导入前启动它们：

准备一个空数据库。
启动 cp-api 并保持运行。它会执行数据库迁移，并提供导入接口。
启动 dp-manager。它内嵌的 Kine 后端会创建接收网关投射配置的表。

设置新部署的 Admin API 基础 URL 和备份文件路径：

# AISIX_CP 包含 /api，且不含尾部斜杠
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_BUNDLE="aisix-export-acme-20260916T101500Z-full.sql.gz"

上传备份文件。不要发送凭据：引导式导入仅在控制面中既没有用户也没有组织时可用。

curl -fS -X POST "${AISIX_CP}/data_import" \
  -H "Content-Type: application/gzip" \
  --data-binary "@${AISIX_BUNDLE}"

一旦存在任何用户或组织，未鉴权的引导入口即关闭。

完成一次迁移

只有目标持有解密所需的全部主密钥时，完整备份文件才能保留真实凭据。导入之后，请按响应中 ca 字段返回的结果执行相应的证书颁发机构操作。

如果两套部署不共享这些密钥，请使用脱敏备份文件。导入之后，请替换每一项合成凭据，包括模型服务提供方凭据、调用方 API Key、集成凭据以及账号密码。然后把该组织的网关注册到目标部署。请把这种方式视为配置迁移，而不是真实凭据的迁移。

完成一次完整恢复

查看导入成功响应中的 ca 值：

`ca` 取值	证书颁发机构的处理结果	需要执行的操作
`replaced`	备份文件中的证书颁发机构替换了目标上尚未使用的颁发机构。	重启 `cp-api` 和 `dp-manager`。两个进程都在启动时加载颁发机构。之后，恢复出来的网关即可继续使用其现有证书。
`unchanged`	备份文件携带的是同一个颁发机构，或没有携带。	无需任何证书相关操作。
`kept_target`	目标已用另一个颁发机构签发过证书，因此它保留了自己的颁发机构，并跳过了备份文件中的证书台账。	请把被导入组织的网关重新注册到目标部署。并查看 `warnings` 了解被跳过的证书状态。

被导入账号的密码保持不变。

完成一次脱敏恢复

使用密码 aisix-repro 登录任一被导入的账号。由于脱敏备份文件不包含源端的证书颁发机构和证书台账，目标会使用自己的证书颁发机构。请把被导入组织的网关重新注册到目标部署，以便它们获取新证书。

脱敏导入之后无需重启任何进程。

确认计费重置

导入会把该组织的套餐和计费记录重置为目标部署的默认值。无论是完整备份文件还是脱敏备份文件，无论目标是空的还是已有数据，都是如此。备份文件仍然保留源端的计费记录以便排查问题，但它们在导入之后不作为依据。

了解备份文件的内容

一份完整备份文件针对单个组织，包含以下数据：

环境、模型、凭据、路由与流量策略、API Key、团队和成员；
该组织的网关所读取的投射配置；
指定时间窗口内的审计事件；
按需包含的请求遥测数据；
相关的用户账号与成员关系，包括密码哈希；
仍以源部署主密钥封装的凭据；
根证书颁发机构私钥以及网关证书台账。

网关证书的私钥不包含在内，因为控制面只在签发证书时返回一次私钥，本身并不存储。

脱敏后的凭据

脱敏备份文件替换成的是已知的合成值，而不是空字符串。这样既保留了资源之间的关系，又能让恢复出来的配置在不暴露真实凭据的前提下正常加载。它不会为上游模型服务提供方或其它外部服务恢复出可用的凭据。

模型服务提供方密钥、MCP 与 A2A 密钥、安全护栏凭据、可观测性导出器凭据、通知渠道的 URL 与请求头，以及其它已存储的 Token，都会变成 REDACTED-<8 hex>。凭据类 URL 会变成 https://redacted.invalid/<8 hex>。
在同一个备份文件内，相同的值会得到相同的占位值，不同的值仍然彼此不同。每次导出使用独立的盐值，因此占位值在不同的导出之间会变化。
数据行和投射给网关的配置文档中存储的是 aisix-repro-<api_key_id> 的 SHA-256 哈希，因此由此派生的值能够通过鉴权。
账号密码会变成 aisix-repro。此前仅通过社交账号登录的账号也会得到这个合成密码；OAuth Token 会被清空。
证书颁发机构和证书台账会被排除。

名称、邮箱地址、由运维人员编写的模板与提示词、模型名称，以及地址型 URL 保持不变，因为复现配置需要它们。在把脱敏备份文件分享到组织之外前，请先检查这些信息。

脱敏备份文件中的加密字段以下面这把公开的复现密钥封装：

AISIX_CLOUD_MASTER_KEY=raNM05F3jUZE7D8C4aUZVhMFZOUSZ0wk6wkpJmgnQwE=

它的指纹是 230c4f58143b002f。官方支持的导入方式会用目标的主密钥重新加密这些字段，因此目标不需要这把密钥。切勿用这把复现密钥配置生产部署；控制面在启动时检测到该配置会打印告警。

备份文件清单

gzip 文件中按依赖顺序排列 SQL 数据，末尾是序列重置语句，不包含数据库结构。文件开头的注释包含针对该文件的说明，以及一行机器可读的清单：

-- AISIX-MANIFEST: {"format":"aisix-org-export/1", …}

字段	含义
`format`	备份文件的契约版本，当前为 `aisix-org-export/1`。
`cp_version`	生成该备份文件的控制面构建版本。
`migration_version`	控制面数据库结构中各基础表列布局的摘要，加上生成该文件的构建所携带的迁移标识。导入要求完全一致。
`generated_at`	导出时间，RFC 3339 格式。
`org_id`、`org_slug`	被导出的组织。
`redacted`	该备份文件是否包含合成凭据。
`ciphertext_key`	加密字段使用的是部署密钥还是复现密钥。
`master_key_fingerprint`	源部署当前生效密钥的指纹；脱敏备份文件中为那把公开的复现密钥的指纹。
`redaction_rules_version`	本次导出所使用的脱敏规则版本。
`tables`	每张表的行数、截断状态和时间窗口。

导入的限制与拒绝原因

备份文件最大为压缩后 1 GiB、解压后 8 GiB。

状态码	错误码	原因
409	`MIGRATION_VERSION_MISMATCH`	目标的数据库结构标识与备份文件不一致，通常是控制面版本不同。
409	`ORG_EXISTS`	备份文件中的某个组织在目标上已存在。
409	`USER_EXISTS`	备份文件中的某个用户在目标上已存在。
409	`OUT_OF_SCOPE_ROWS`	备份文件包含不属于其所声明组织的数据行，事务已回滚。
409	`PROJECTION_TABLE_MISSING`	`dp-manager` 尚未创建投射表，请在导入前启动它。
409	`MASTER_KEY_MISMATCH`	目标没有持有封装备份文件加密值的那把密钥。
409	`MASTER_KEY_UNAVAILABLE`	目标启动时未配置主密钥。
400	`INVALID_BUNDLE`	该文件不是有效的 AISIX 组织备份文件。
403	`FORBIDDEN`	目标不是空的，且请求未使用已登录用户的会话。
401	`INVALID_TOKEN`	提供的凭据无效或已过期。

导入成功时返回被导入的组织、各表行数、备份文件模式、证书颁发机构的处理结果、告警信息，以及由已登录用户执行导入时的新 owner ID：

{
  "imported": [
    {
      "id": "…",
      "slug": "acme"
    }
  ],
  "redacted": false,
  "rows": {
    "models": 42
  },
  "ca": "unchanged",
  "warnings": [],
  "owner_user_id": "…"
}

不要直接加载到数据库

备份文件中的 SQL 数据可以用 PostgreSQL 工具查看，但直接加载到数据库不是官方支持的恢复方式。启动 cp-api 创建数据库结构的同时，也会创建可能与完整备份文件中数据行冲突的控制面数据。AISIX 不提供另一套仅创建数据库结构的运维流程。

请使用导入接口进行恢复。它会校验备份文件的范围、在一个事务内应用所有数据行、处理证书颁发机构冲突、重新加密脱敏凭据，并重置计费状态。直接执行 SQL 加载会绕过这些保护措施，并可能在后续语句失败时留下不完整的恢复结果。

演练 On-Premises 升级

升级 On-Premises 控制面之前，请先导出一份完整备份文件。如需演练组织恢复，请在另一台主机上以全新数据库和所需主密钥部署当前的控制面版本，然后导入该备份文件。这样可以在数据库结构变更之前确认该组织能够被恢复。

如果升级失败，请使用升级 AISIX 要求的完整数据库备份恢复整套部署。如果只需恢复已导出的那个组织，请以上一个控制面版本、全新数据库和所需主密钥完成部署，然后导入升级前的备份文件。组织备份文件可以移植到另一台主机，而数据库备份保护的是整套部署。

选择备份文件类型​

导出一个组织​

使用控制台​

使用 Admin API​

恢复一个组织​

恢复到已有数据的部署​

恢复到空的 On-Premises 部署​

完成一次迁移​

完成一次完整恢复​

完成一次脱敏恢复​

确认计费重置​

了解备份文件的内容​

脱敏后的凭据​

备份文件清单​

导入的限制与拒绝原因​

不要直接加载到数据库​

演练 On-Premises 升级​