导入和导出领域

关于如何导入和导出领域的概述

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

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

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

提供数据库连接参数选项

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

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

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

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

将领域导出到目录

要导出领域，可以使用 export 命令。在调用此命令时，您的 Keycloak 服务器实例不能启动。

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

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

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

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

配置用户导出方式

您还可以通过设置 --users <strategy> 选项来配置用户导出方式。此选项可用的值是

different_files

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

skip

跳过导出用户。

realm_file

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

same_file

所有用户都导出到一个显式文件。因此，您将为一个领域获得两个 JSON 文件，一个包含领域数据，一个包含用户。

如果您使用 different_files 策略导出用户，可以通过设置 --users-per-file 选项来设置每个文件要包含多少用户。默认值为 50。

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

将领域导出到文件

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

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

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

导出特定领域

如果您没有指定要导出的特定领域，则会导出所有领域。要导出单个领域，可以使用 --realm 选项，如下所示

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

从目录导入领域

要导入领域，可以使用 import 命令。在调用此命令时，您的 Keycloak 服务器实例不能启动。

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

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

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

使用 import 命令导入领域时，您可以设置是否跳过现有领域，或者是否应该用新的配置覆盖它们。为此，您可以设置 --override 选项，如下所示

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

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

从文件导入领域

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

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

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

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

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

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

在启动时导入领域

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

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

设置 --import-realm 选项时，服务器将尝试从 data/import 目录导入任何领域配置文件。仅读取使用 .json 扩展名的普通文件，忽略子目录。

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

如果服务器中已经存在领域，则会跳过导入操作。这种行为背后的主要原因是为了避免重新创建领域，并可能在服务器重新启动之间丢失状态。

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

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

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

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

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

  1. 选择一个领域。

  2. 在菜单中单击领域设置。

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

    将出现资源列表以及领域配置。

  4. 选择要导出的资源。

  5. 单击导出。

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

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

  1. 在菜单中单击领域设置。

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

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

  3. 单击导入。

您还可以控制如果导入的资源已经存在，Keycloak 应该执行什么操作。这些选项存在

Fail import

中止导入。

Skip

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

Overwrite

用要导入的资源替换现有资源。

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