导入和导出 Realm

关于如何导入和导出 realm 的概述

在本指南中，您将了解使用 JSON 文件导入和导出 realm 的不同方法。

导出和导入到单个文件可能会产生大型文件，因此如果您的数据库包含超过 500 个用户，请导出到目录而不是单个文件。使用目录性能更好，因为目录提供程序为每个“页面”（一个用户文件）使用单独的事务。每个文件和每个事务的默认用户计数为 50。将此值增加到更大的数字会导致执行时间呈指数级增长。

在使用 kc.[sh|bat] import | export 命令之前，需要停止所有 Keycloak 节点。这确保了生成的操作不会与并发请求产生一致性问题。它还确保从与服务器实例相同的机器运行导入或导出命令不会导致端口或其他冲突。

提供数据库连接参数的选项

当使用下面的 export 和 import 命令时，Keycloak 需要知道如何连接到数据库，其中存储了关于 realm、客户端、用户和其他实体的信息。正如 配置 Keycloak 中所述，该信息可以作为命令行参数、环境变量或配置文件提供。对每个命令使用 --help 命令行选项以查看可用选项。

一些配置选项是构建时配置选项。默认情况下，如果 Keycloak 检测到构建时参数的更改，它将为 export 和 import 命令自动重建。

如果您已使用 配置 Keycloak 中概述的 build 命令构建了 Keycloak 的优化版本，请使用命令行选项 --optimized 让 Keycloak 跳过构建检查以获得更快的启动时间。执行此操作时，请从命令行中删除构建时选项，仅保留运行时选项。

如果您不使用 --optimized，请记住 import 或 export 命令将隐式地为您创建或更新优化的镜像 - 如果您从与服务器实例相同的机器运行该命令，这可能会影响您服务器的下一次启动。

将 Realm 导出到目录

要导出 realm，您可以使用 export 命令。调用此命令时，您的 Keycloak 服务器实例必须未启动。

bin/kc.[sh|bat] export --help

要将 realm 导出到目录，您可以使用 --dir <dir> 选项。

bin/kc.[sh|bat] export --dir <dir>

当将 realm 导出到目录时，服务器将为每个要导出的 realm 创建单独的文件。

配置用户导出方式

您还可以通过设置 --users <strategy> 选项来配置用户将如何导出。此选项的可用值包括

different_files

用户导出到不同的 json 文件中，具体取决于由 --users-per-file 设置的每个文件的最大用户数。这是默认值。

skip

跳过导出用户。

realm_file

用户将导出到与 realm 设置相同的文件中。对于名为“foo”的 realm，这将是“foo-realm.json”，其中包含 realm 数据和用户。

same_file

所有用户都导出到一个显式文件中。因此，对于一个 realm，您将获得两个 json 文件，一个包含 realm 数据，另一个包含用户。

如果您使用 different_files 策略导出用户，则可以通过设置 --users-per-file 选项来设置每个文件所需的用户数。默认值为 50。

bin/kc.[sh|bat] export --dir <dir> --users different_files --users-per-file 100

将 Realm 导出到文件

要将 realm 导出到文件，您可以使用 --file <file> 选项。

bin/kc.[sh|bat] export --file <file>

当将 realm 导出到文件时，服务器将使用同一个文件来存储所有要导出的 realm 的配置。

导出特定的 realm

如果您未指定要导出的特定 realm，则将导出所有 realm。要导出单个 realm，您可以按如下方式使用 --realm 选项

bin/kc.[sh|bat] export [--dir|--file] <path> --realm my-realm

导入文件命名约定

当您导出 realm 时，会使用特定的文件名约定，这也必须用于从目录导入或在启动时导入。要导入的 realm 文件必须命名为 <realm name>-realm.json。与 realm 关联的常规用户文件和联合用户文件必须命名为 <realm-name>-users-<file number>.json 和 <realm-name>-federated-users-<file number>.json。未能使用此约定将导致错误或用户文件未被导入。

从目录导入 Realm

要导入 realm，您可以使用 import 命令。调用此命令时，您的 Keycloak 服务器实例必须未启动。

bin/kc.[sh|bat] import --help

将 realm 导出到目录后，您可以使用 --dir <dir> 选项将 realm 导入回服务器，如下所示

bin/kc.[sh|bat] import --dir <dir>

当使用 import 命令导入 realm 时，您可以设置是否应跳过现有 realm，或者是否应使用新配置覆盖它们。为此，您可以按如下方式设置 --override 选项

bin/kc.[sh|bat] import --dir <dir> --override false

默认情况下，--override 选项设置为 true，以便始终使用新配置覆盖 realm。

从文件导入 Realm

要导入先前在单个文件中导出的 realm，您可以使用 --file <file> 选项，如下所示

bin/kc.[sh|bat] import --file <file>

在 Realm 配置文件中使用环境变量

您可以对任何 realm 配置使用占位符来解析来自环境变量的值。

使用占位符的 Realm 配置
{
    "realm": "${MY_REALM_NAME}",
    "enabled": true,
    ...
}

在上面的示例中，设置为 MY_REALM_NAME 环境变量的值将用于设置 realm 属性。

在启动期间导入 Realm

您还可以在服务器启动时使用 --import-realm 选项导入 realm。

bin/kc.[sh|bat] start --import-realm

当您设置 --import-realm 选项时，服务器将尝试从 data/import 目录导入任何 realm 配置文件。只有使用 .json 扩展名的常规文件才会从此目录中读取，子目录将被忽略。

对于 Keycloak 容器，导入目录是 /opt/keycloak/data/import

如果 realm 已存在于服务器中，则导入操作将被跳过。此行为背后的主要原因是避免重新创建 realm 并可能在服务器重启之间丢失状态。

要重新创建 realm，您应在启动服务器之前显式运行 import 命令。

使用管理控制台导入和导出

您还可以使用管理控制台导入和导出 realm。此功能与前面章节中描述的其他 CLI 选项不同，因为管理控制台仅提供部分导出 realm 的功能。在这种情况下，可以导出当前的 realm 设置，以及一些资源，如客户端、角色和组。使用此方法无法导出该 realm 的用户。

当使用管理控制台导出时，realm 和选定的资源始终导出到名为 realm-export.json 的文件中。此外，所有敏感值（如密码和客户端密钥）都将用 * 符号屏蔽。

要使用管理控制台导出 realm，请执行以下步骤

  1. 选择一个 realm。

  2. 单击菜单中的Realm 设置。

  3. 指向 realm 设置屏幕右上角的操作菜单，然后选择部分导出。

    将显示资源列表以及 realm 配置。

  4. 选择您要导出的资源。

  5. 单击导出。

从管理控制台导出的 realm 不适用于备份或服务器之间的数据传输。只有 CLI 导出才适用于备份或服务器之间的数据传输。
如果 realm 包含许多组、角色和客户端，则该操作可能会导致服务器在一段时间内对用户请求无响应。请谨慎使用此功能，尤其是在生产系统上。

以类似的方式，您可以导入先前导出的 realm。执行以下步骤

  1. 单击菜单中的Realm 设置。

  2. 指向 realm 设置屏幕右上角的操作菜单，然后选择部分导入。

    将出现一个提示，您可以在其中选择要导入的文件。根据此文件，您将看到可以与 realm 设置一起导入的资源。

  3. 单击导入。

您还可以控制如果导入的资源已存在，Keycloak 应执行的操作。存在以下选项

导入失败

中止导入。

跳过

跳过重复的资源，而不中止该过程

覆盖

将现有资源替换为正在导入的资源。

管理控制台部分导入还可以导入由 CLI export 命令创建的文件。换句话说，可以使用管理控制台导入由 CLI 创建的完整导出。如果文件包含用户，则这些用户也可以导入到当前 realm 中。
在此页面上
编辑本指南