组织备份与恢复
组织备份与恢复仅适用于由客户运维控制面的 AISIX Enterprise。AISIX Enterprise 可以将单个组织导出为 gzip 压缩的 SQL 包，并恢复到运行相同版本的新安装控制面。完整包保留凭据和证书状态，适合备份或在具备所需主密钥的部署间迁移。脱敏包会用合成值替换凭据，适合支持问题复现或不共享源密钥的迁移。
AISIX Cloud 不向客户提供组织导出或恢复功能。如需恢复 Cloud 数据，请联系 API7 支持团队。
选择备份文件类型
按目标部署能否安全使用源部署的主密钥来选择备份 文件类型：
| 备份文件 | 用途 | 恢复前提 |
|---|---|---|
| 完整 | 备份一个组织，或在不替换其凭据的前提下迁移该组织。 | 目标必须是全新安装、运行相同的控制面版本，并持有解密该文件所需的每一把源端主密钥，包括仍在封装某个已存储值的已停用密钥。备份文件中的账号会取代目标的首个管理员，并保留各自的密码。 |
| 脱敏 | 为排查问题而复现一个组织，或在不共享源端主密钥的前提下迁移其结构。 | 目标必须是全新安装并运行相同的控制面版本。恢复时会用目标的主密钥重新加密这些合成凭据。目标的首个管理员会保留为该组织的 Owner，恢复出来的账号在其启用之前无法登录，每个调用方 API Key 在使用前都必须轮换。 |
完整备份文件包含真实凭据。凭据在配置表中仍是信封加密的，但投射给网关的配置文档中是其明文值。该文件还包含根证书颁发机构的私钥。请按照保管和传输数据库的同等要求保管和传输它。
导出一个组织
交互式导出请使用控制台；如需自动执行定时备份或生成支持文件，请使用 Admin API。
使用控制台
打开 Settings → Backup & restore。选择是否脱敏凭据、设置审计记录的时间窗口，并可选择是否包含请求遥测数据。选择 Download backup 导出备份文件。
对组织 owner，脱敏默认关闭。组织 admin 只能导出脱敏备份文件，因此该开关对他们保持打开且锁定。
使用 Admin API
导出前请先设置 Admin API 基础 URL 和一个 Admin Token：
# AISIX_CP 包含 /api，且不带结尾斜杠。
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_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。
导出还要求 dp-manager 至少针对该数据库启动过一次。它内嵌的 Kine 后端会创建存放各网关投射配置的表，而该表是每个备份包的组成部分，因此在 dp-manager 从未运行过的部署上导出会收到 409 DATA_EXPORT_UNAVAILABLE。先启动一次 dp-manager，然后重新导出。导入端点从另一侧表达了同一前提，对应 409 PROJECTION_TABLE_MISSING。每次完成的导出都会新增一条审计事件，记录导出模式、参数、主密钥指纹、各表行数以及截断状态。
恢复一个组织
恢复会将备份包加载到新安装的 AISIX Enterprise 控制面，替换该安装首次启动时创建的组织和管理员。它不会合并到已投入使用的部署中。完整备份包在一个数据库事务中应用，因此要么全部成功，要么不作任何更改。
准备全新的目标
- 在空数据库上安装与源端相同的控制面版本。备份文件只包含数据、不包含数据库结构，因此版本必须一致。
- 配置首个管理员。对于脱敏备份文件，请使用不在备份文件中的邮箱地址，因为脱敏恢复会保留该管理员。
- 对于完整备份文件，配置解密它所需的每一把主密钥。参见选择备份文件类型。
- 启动
cp-api和dp-manager。dp-manager会创建接收网关投射配置的表。部署包和 Helm 安装都会随整套服务启动它。 - 以首个管理员身份登录，并在控制台提示时修改初始密码。
恢复之前，不要在目标上做任何其他操作。恢复只接受仅包含首次启动所创建内容的安装：空的 Default 组织，以及作为唯一用户的首个管理员。只要存在环境、邀请、自定义角色、服务提供方密钥或任何其他组织级记录，或者存在其他组织或其他用户，恢复都会失败并返回 409 INSTANCE_NOT_FRESH。启动时未配置首个管理员的安装同样如此。遇到这种情况，请使用新的数据库重新安装。
上传备份文件
以首个管理员身份登录后，打开 Settings → Backup & restore，使用 Restore from a file。只有组织 Owner 能看到该选项，并且只接受已登录的会话：Admin Token 会被拒绝，即使是空数据库也不存在未鉴权的恢复方式。
备份文件中的组织会取代 Default 组织。用户账号的处理方式取决于备份文件类型。
完成一次完整恢复
完整恢复还会取代首个管 理员，并结束其所有会话。控制台会回到登录页：请使用备份文件中的某个账号及其原密码登录。所有恢复出来的账号都保留各自的密码。
登录页还会显示恢复对证书颁发机构做了什么处理，并在需要时提示重启 cp-api 和 dp-manager。只有 replaced 结果需要重启，因为两个进程都只在启动时加载颁发机构。导入响应通过 ca 字段报告同一处理结果：
ca 取值 | 证书颁发机构的处理结果 | 需要执行的操作 |
|---|---|---|
replaced | 备份文件中的证书颁发机构替换了目标上尚未使用的颁发机构。 | 重启 cp-api 和 dp-manager。两个进程都在启动时加载颁发机构。之后，恢复出来的网关即可继续使用其现有证书。 |
unchanged | 备份文件携带的是同一个颁发机构，或没有携带。 | 无需任何证书相关操作。 |
kept_target | 目标已用自己的颁发机构签发过网关证书，因此它保留了自己的颁发机构，并跳过了备份文件中的证书台账。 | 请把被导入组织的网关重新注册到目标部署。 |
即使目标被视为全新安装，也可能报告 kept_target：如果曾创建一个环境、注册过网关又删除了该环境，已签发的证书仍会留下。
完成一次脱敏恢复
脱敏恢复会保留首个管理员的登录状态，并使其成为恢复出来的组织的 Owner。Backup & restore 卡片会显示恢 复结果（包括证书颁发机构的处理结果），直到你选择 Open the restored organization 切换到该组织。恢复不会从备份文件中加载任何凭据：
- 账号。 每个恢复出来的账号都没有密码，无法登录，与通过 Create user 创建的成员相同。请在 Members 页面为需要访问控制台的人启用登录。
- 调用方 API Key。 每个 Key 保留其名称、模型、限流、绑定、到期时间和禁用状态，但没有可用的密钥值。在客户端使用之前，请轮换每个 Key，轮换会返回一个可用的值。
- 其他凭据。 服务提供方密钥、MCP 与 A2A 密钥、安全护栏和导出器凭据，以及通知渠道 URL 都是合成占位值。在该组织承载生产流量之前，请替换它们。
由于脱敏备份文件不包含源端的证书颁发机构和证书台账，目标会使用自己的证书颁发机构，处理结果始终为 unchanged。请把被导入组织的网关重新注册到目标部署，以便它们获取新证书。脱敏恢复之后无需重启任何进程。
如果脱敏备份文件中包含首个管理员自己的邮箱地址，恢复会被拒绝并返回 409 USER_EXISTS。请使用不在备份文件中的首个管理员邮箱地址重新安装目标。
完成一次迁移
只有目标持有解密所需的全部主密钥时，完整备份文件才能保留真实凭据。恢复之后， 请按登录页显示、响应中 ca 字段返回的证书颁发机构处理结果执行相应操作。
如果两套部署不共享这些密钥，请使用脱敏备份文件。恢复之后，请为账号启用登录、轮换调用方 API Key，并替换其他每一项合成凭据。然后把该组织的网关注册到目标部署。请把这种方式视为配置迁移，而不是真实凭据的迁移。
了解备份文件的内容
一份完整备份文件针对单个组织，包含以下数据：
- 环境、模型、凭据、路由与流量策略、API Key、团队和成员；
- 该组织的网关所读取的投射配置；
- 指定时间窗口内的审计事件；
- 按需包含的请求遥测数据；
- 相关的用户账号与成员关系，包括密码哈希；
- 仍以源部署主密钥封装的凭据；
- 根证书颁发机构私钥以及网关证书台账。
网关证书的私钥不包含在内，因为控制面只在签发证书时返回一次私钥，本身并不存储。
脱敏后的凭据
脱敏备份文件替换成的是已知的合成值，而不是空字符串。这样既保留了资源之间的关系，又能让恢复出来的配置在不暴露真实凭据的前提下正常加载。它不会为上游模型服务提供方或其它外部服务恢复出可用的凭据。
- 模型服务提供方密钥、MCP 与 A2A 密 钥、安全护栏凭据、可观测性导出器凭据、通知渠道的 URL 与请求头，以及其它已存储的 Token，都会变成
REDACTED-<8 hex>。凭据类 URL 会变成https://redacted.invalid/<8 hex>。 - 在同一个备份文件内，相同的值会得到相同的占位值，不同的值仍然彼此不同。每次导出使用独立的盐值，因此占位值在不同的导出之间会变化。
- 调用方 API Key 的哈希会变成
aisix-repro-<api_key_id>的 SHA-256 哈希，账号密码会变成aisix-repro。由于任何知道 ID 的人都能推导出这些值，官方支持的恢复方式不会加载它们：它会为每个调用方 API Key 设置一个没有任何明文与之对应的随机哈希，并以无密码状态恢复每个账号。参见完成一次脱敏恢复。 - 社交登录遗留的 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 | INSTANCE_NOT_FRESH | 目标包含首次启动所创建内容以外的数据，或启动时未配置首位管理员。参见准备全新目标。 |
| 409 | MIGRATION_VERSION_MISMATCH | 目标的 schema 标识与备份包不同，通常是控制面版本不一致。 |
| 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 | 已登录用户不是组织所有者。 |
| 403 | PASSWORD_CHANGE_REQUIRED | 首位管理员尚未更改初始密码。 |
| 401 | CONSOLE_SESSION_REQUIRED | 请求使用了 Admin Token。恢复仅接受已登录控制台的会话。 |
| 401 | NOT_AUTHENTICATED, INVALID_TOKEN | 请求没有已登录会话，或会话已过期。 |
恢复成功时返回被导入的组织、各表行数、备份文件模式和证书颁发机构的处理结果。warnings 数组仅为兼容而保留，始终为空；证书颁发机构的处理结果请读取 ca：
{
"imported": [
{
"id": "…",
"slug": "acme"
}
],
"redacted": false,
"rows": {
"models": 42
},
"ca": "unchanged",
"warnings": []
}
不要直接加载到数据库
备份文件中的 SQL 数据可以用 PostgreSQL 工具查看，但直接加载到数据库不是官方支持的恢复方式。启动 cp-api 创建数据库结构的同时，也会创建可能与完整备份文件中数据行冲突的控制面数据。AISIX 不提供另一套仅 创建数据库结构的运维流程。
请使用控制台中的恢复功能进行恢复。它会校验备份文件的范围、在一个事务内应用所有数据行、处理证书颁发机构冲突，并重新加密脱敏凭据。直接执行 SQL 加载会绕过这些保护措施，并可能在后续语句失败时留下不完整的恢复结果。
演练 AISIX Enterprise 升级
升级 AISIX Enterprise 控制面前，请导出完整包。要演练组织恢复，请在另一台宿主机上使用全新数据库和所需主密钥安装当前控制面版本，以首位管理员身份登录，然后恢复备份包。这可以在 schema 变更前确认组织能够恢复。
升级失败时，请使用升级 AISIX Enterprise要求的数据库备份恢复整个部署。如果只需恢复导出的组织，则应使用全新数据库和所需主密钥安装之前的控制面版本，以首位管理员身份登录，再恢复升级前的备份包。组织备份包可迁移到另一台宿主机，而数据库备份保护的是整个部署。