Documentation Home
MySQL 8.0 参考手册

6.4.4.14 在密钥环密钥库之间迁移密钥

密钥环迁移将密钥从一个密钥库复制到另一个密钥库，使 DBA 能够将 MySQL 安装切换到另一个密钥库。成功的迁移操作会产生以下结果：

  • 目标密钥库包含它在迁移之前拥有的密钥，以及来自源密钥库的密钥。

  • 源密钥库在迁移前后保持不变（因为密钥是复制的，而不是移动的）。

如果要复制的密钥已经存在于目标密钥库中，则会发生错误，并且目标密钥库将恢复到其迁移前的状态。

密钥环使用密钥环组件和密钥环插件管理密钥库。这与迁移策略有关，因为源密钥库和目标密钥库的管理方式决定了特定类型的密钥迁移是否可能以及执行它的过程：

  • 从一个密钥环插件迁移到另一个：MySQL 服务器有一种提供此功能的操作模式。

  • 从密钥环插件迁移到密钥环组件：从 MySQL 8.0.24 开始，MySQL 服务器具有提供此功能的操作模式。

  • 从一个密钥环组件迁移到另一个： mysql_migrate_keyring实用程序提供此功能。mysql_migrate_keyring从 MySQL 8.0.24 开始可用。

  • 从密钥环组件迁移到密钥环插件：没有提供此功能。

以下部分讨论离线和在线迁移的特征，并描述如何执行迁移。

离线和在线关键迁移

密钥迁移是离线或在线的：

  • 离线迁移：当您确定本地主机上没有正在运行的服务器正在使用源或目标密钥库时使用。在这种情况下，迁移操作可以将密钥从源密钥库复制到目标，而运行中的服务器不可能在操作期间修改密钥库内容。

  • 在线迁移：当本地主机上正在运行的服务器正在使用源密钥库时使用。在这种情况下，必须注意防止该服务器在迁移期间更新密钥库。这涉及连接到正在运行的服务器并指示它暂停密钥环操作，以便可以将密钥从源密钥库安全地复制到目的地。密钥复制完成后，允许正在运行的服务器恢复密钥环操作。

计划密钥迁移时，请使用这些要点来决定它应该离线还是在线：

  • 不要执行涉及正在运行的服务器正在使用的密钥库的脱机迁移。

  • 在在线迁移期间暂停密钥环操作是通过连接到正在运行的服务器并将其全局 keyring_operations系统变量设置为OFF密钥复制之前和密钥复制 ON之后来实现的。这有几个含义：

    • keyring_operations 在 MySQL 5.7.21 中引入，因此只有当运行服务器来自 MySQL 5.7.21 或更高版本时，才可以进行在线迁移。如果正在运行的服务器较旧，您必须停止它，执行离线迁移，然后重新启动它。其他地方提及的所有迁移说明 keyring_operations 均受此条件约束。

    • 用于连接到正在运行的服务器的帐户必须具有修改所需的权限 keyring_operations。这些特权是 ENCRYPTION_KEY_ADMIN对任 一特权SYSTEM_VARIABLES_ADMIN 或已弃用SUPER 特权的补充。

    • 如果在线迁移操作异常退出（例如，如果它被强制终止），则有可能 keyring_operations在正在运行的服务器上保持禁用状态，使其无法执行密钥环操作。在这种情况下，可能需要连接到正在运行的服务器并 keyring_operations 使用以下语句手动启用： 

      SET GLOBAL keyring_operations = ON;

  • 在线密钥迁移提供了在单个正在运行的服务器上暂停密钥环操作。如果多个正在运行的服务器正在使用所涉及的密钥库，要执行迁移，请使用涉及多个正在运行的服务器的 密钥迁移中描述的过程。

使用迁移服务器进行密钥迁移
笔记

仅当运行的服务器允许套接字连接或使用 TLS 的 TCP/IP 连接时，才支持使用迁移服务器的在线密钥迁移；例如，当服务器在 Windows 平台上运行并且只允许共享内存连接时，它不受支持。

如果在支持密钥迁移的特殊操作模式下调用，则 MySQL 服务器将成为迁移服务器。迁移服务器不接受客户端连接。相反，它只运行足够长的时间来迁移密钥，然后退出。迁移服务器向控制台报告错误（标准错误输出）。

迁移服务器支持以下迁移类型：

  • 从一个密钥环插件迁移到另一个。

  • 从密钥环插件迁移到密钥环组件。此功能从 MySQL 8.0.24 开始可用。较旧的服务器仅支持从一个密钥环插件迁移到另一个，在这种情况下，这些说明中涉及密钥环组件的部分不适用。

迁移服务器不支持从一个密钥环组件迁移到另一个。对于这种类型的迁移，请参阅 使用 mysql_migrate_keyring 实用程序进行密钥迁移。

要使用迁移服务器执行密钥迁移操作，请确定指定涉及哪些密钥环插件或组件所需的密钥迁移选项，以及迁移是离线还是在线：

  • 要指示源密钥环插件和目标密钥环插件或组件，请指定以下选项：

    和 选项--keyring-migration-source 向 --keyring-migration-destination 服务器表示它应该以密钥迁移模式运行。对于密钥迁移操作，这两个选项都是必需的。每个插件或组件都使用其库文件的名称指定，包括任何特定于平台的扩展名，例如 .so或.dll. 源和目标必须不同，并且迁移服务器必须同时支持它们。

  • 对于离线迁移，不需要额外的密钥迁移选项。

  • 对于在线迁移，某些正在运行的服务器当前正在使用源或目标密钥库。要调用迁移服务器，请指定指示如何连接到正在运行的服务器的其他关键迁移选项。这是必要的，以便迁移服务器可以连接到正在运行的服务器并告诉它在迁移操作期间暂停密钥环使用。

    使用以下任何选项都表示在线迁移：

有关密钥迁移选项的更多详细信息，请参阅 第 6.4.4.18 节，“密钥环命令选项”。

使用指示源和目标密钥库以及迁移是离线还是在线的密钥迁移选项启动迁移服务器，可能还有其他选项。请牢记以下注意事项：

  • 可能需要其他服务器选项，例如两个密钥环插件的配置参数。例如，如果keyring_file是源或目标， keyring_file_data如果密钥环数据文件位置不是默认位置，则必须设置系统变量。可能还需要其他非密钥环选项。指定这些选项的一种方法是使用--defaults-file命名包含所需选项的选项文件。

  • 迁移服务器期望路径名选项值是完整路径。相对路径名可能无法按预期解析。

  • 在密钥迁移模式下调用服务器的用户不能是root操作系统用户，除非--user使用非root用户名指定选项以该用户身份运行服务器。

  • 以密钥迁移模式运行服务器的用户必须具有读取和写入任何本地密钥环文件的权限，例如基于文件的插件的数据文件。

    如果您从不同于通常用于运行 MySQL 的系统帐户调用迁移服务器，它可能会创建服务器在正常操作期间无法访问的密钥环目录或文件。假设 mysqld通常以 mysql操作系统用户身份运行，但您以 isabel. 迁移服务器创建的任何新目录或文件都归 isabel. 当服务器作为mysql操作系统用户尝试访问 拥有的文件系统对象时，后续启动失败isabel。

    为避免此问题，请以 root操作系统用户身份启动迁移服务器并提供一个 选项，通常用于运行 MySQL 的系统帐户在哪里。或者，在迁移之后，检查与密钥环相关的文件系统对象，并在必要时使用chown、 chmod或类似命令更改它们的所有权和权限，以便运行的服务器可以访问这些对象。 --user=user_nameuser_name

两个密钥环插件之间离线迁移的示例命令行（在一行中输入命令）： 

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=keyring_encrypted_file.so
  --keyring_encrypted_file_password=password

两个密钥环插件之间在线迁移的示例命令行： 

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=keyring_encrypted_file.so
  --keyring_encrypted_file_password=password
  --keyring-migration-host=127.0.0.1
  --keyring-migration-user=root
  --keyring-migration-password=root_password

要在目标是密钥环组件而不是密钥环插件时执行迁移，请指定 --keyring-migration-to-component 选项，并将组件命名为 --keyring-migration-destination 选项的值。

从密钥环插件到密钥环组件的离线迁移示例命令行： 

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-to-component
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=component_keyring_encrypted_file.so

请注意，在这种情况下，未 keyring_encrypted_file_password指定任何值。组件数据文件的密码列在组件配置文件中。

从密钥环插件在线迁移到密钥环组件的示例命令行： 

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
  --keyring-migration-to-component
  --keyring-migration-source=keyring_file.so
  --keyring-migration-destination=component_keyring_encrypted_file.so
  --keyring-migration-host=127.0.0.1
  --keyring-migration-user=root
  --keyring-migration-password=root_password

密钥迁移服务器执行如下迁移操作：

  1. （仅限联机迁移）使用连接选项连接到正在运行的服务器。

  2. （仅限联机迁移） keyring_operations在正在运行的服务器上禁用。

  3. 为源密钥库和目标密钥库加载密钥环插件/组件库。

  4. 将密钥从源密钥库复制到目标。

  5. 卸载源和目标密钥库的密钥环插件/组件库。

  6. （仅限联机迁移） keyring_operations在运行的服务器上启用。

  7. （仅限联机迁移）断开与正在运行的服务器的连接。

如果在密钥迁移期间发生错误，目标密钥库将恢复到其迁移前的状态。

在线密钥迁移操作成功后，可能需要重新启动正在运行的服务器：

  • 如果正在运行的服务器在迁移之前正在使用源密钥库，并且应该在迁移之后继续使用它，则不需要在迁移之后重新启动它。

  • 如果正在运行的服务器在迁移之前正在使用目标密钥库并且应该在迁移后继续使用它，则应该在迁移后重新启动它以加载所有迁移到目标密钥库的密钥。

  • 如果正在运行的服务器在迁移前使用源密钥库，但在迁移后应该使用目标密钥库，则必须重新配置它以使用目标密钥库并重新启动。在这种情况下，请注意，虽然正在运行的服务器在迁移过程中暂停修改源密钥库，但在迁移和后续重启之间的间隔期间不会暂停。应注意服务器在此间隔期间不会修改源密钥库，因为任何此类更改都不会反映在目标密钥库中。

使用 mysql_migrate_keyring 实用程序进行密钥迁移

mysql_migrate_keyring实用程序将密钥从一个密钥环组件迁移到另一个。它不支持涉及密钥环插件的迁移。对于这种类型的迁移，请使用以密钥迁移模式运行的 MySQL 服务器；请参阅 使用迁移服务器进行密钥迁移。

要使用mysql_migrate_keyring 执行密钥迁移操作 ，请确定指定涉及哪些密钥环组件所需的密钥迁移选项，以及迁移是离线还是在线：

  • 要指示源和目标密钥环组件及其位置，请指定以下选项：

    • --source-keyring：管理要迁移的密钥的源密钥环组件。

    • --destination-keyring：要将迁移的密钥复制到的目标密钥环组件。

    • --component-dir：包含密钥环组件库文件的目录。这通常是 plugin_dir本地 MySQL 服务器的系统变量值。

    所有三个选项都是强制性的。每个密钥环组件名称都是一个组件库文件名，没有指定任何特定于平台的扩展名，例如 .so或.dll. 例如，要使用库文件为 的组件component_keyring_file.so，请将选项指定为 --source-keyring=component_keyring_file。源和目标必须不同，并且 mysql_migrate_keyring必须同时支持它们。

  • 对于脱机迁移，不需要其他选项。

  • 对于在线迁移，某些正在运行的服务器当前正在使用源或目标密钥库。在这种情况下，请指定 --online-migration 表示在线迁移的选项。此外，指定指示如何连接到正在运行的服务器的连接选项，以便 mysql_migrate_keyring可以连接到它并告诉它在迁移操作期间暂停密钥环使用。

    该 --online-migration 选项通常与以下连接选项结合使用：

    • --host：运行服务器所在的主机。这始终是本地主机，因为 mysql_migrate_keyring只能在本地组件管理的密钥库之间迁移密钥。

    • --user, --password: 用于连接到正在运行的服务器的帐户凭据。

    • --port：对于 TCP/IP 连接，要连接到正在运行的服务器上的端口号。

    • --socket：对于 Unix 套接字文件或 Windows 命名管道连接，要连接到正在运行的服务器上的套接字文件或命名管道。

有关所有可用选项的描述，请参阅 第 4.6.8 节，“mysql_migrate_keyring — 密钥环密钥迁移实用程序”。

使用指示源和目标密钥库以及迁移是离线还是在线的选项 启动mysql_migrate_keyring ，可能还有其他选项。请牢记以下注意事项：

假设您要将密钥从 迁移 component_keyring_file到 component_keyring_encrypted_file，并且本地服务器将其密钥环组件库文件存储在 /usr/local/mysql/lib/plugin.

如果没有正在运行的服务器使用密钥环，则允许离线迁移。像这样调用 mysql_migrate_keyring（在一行中输入命令）： 

mysql_migrate_keyring
  --component-dir=/usr/local/mysql/lib/plugin
  --source-keyring=component_keyring_file
  --destination-keyring=component_keyring_encrypted_file

如果正在运行的服务器正在使用密钥环，则您必须改为执行在线迁移。在这种情况下， --online-migration 必须给出该选项，以及指定要连接到哪个服务器和要使用的 MySQL 帐户所需的任何连接选项。

以下命令执行在线迁移。它使用 TCP/IP 连接和 admin帐户连接到本地服务器。该命令提示输入密码，您应该在出现提示时输入密码： 

mysql_migrate_keyring
  --component-dir=/usr/local/mysql/lib/plugin
  --source-keyring=component_keyring_file
  --destination-keyring=component_keyring_encrypted_file
  --online-migration --host=127.0.0.1 --user=admin --password

mysql_migrate_keyring执行迁移操作如下：

  1. （仅限联机迁移）使用连接选项连接到正在运行的服务器。

  2. （仅限联机迁移） keyring_operations在正在运行的服务器上禁用。

  3. 为源密钥库和目标密钥库加载密钥环组件库。

  4. 将密钥从源密钥库复制到目标。

  5. 卸载源和目标密钥库的密钥环组件库。

  6. （仅限联机迁移） keyring_operations在运行的服务器上启用。

  7. （仅限联机迁移）断开与正在运行的服务器的连接。

如果在密钥迁移期间发生错误，目标密钥库将恢复到其迁移前的状态。

在线密钥迁移操作成功后，可能需要重新启动正在运行的服务器：

  • 如果正在运行的服务器在迁移之前正在使用源密钥库，并且应该在迁移之后继续使用它，则不需要在迁移之后重新启动它。

  • 如果正在运行的服务器在迁移之前正在使用目标密钥库并且应该在迁移后继续使用它，则应该在迁移后重新启动它以加载所有迁移到目标密钥库的密钥。

  • 如果正在运行的服务器在迁移前使用源密钥库，但在迁移后应该使用目标密钥库，则必须重新配置它以使用目标密钥库并重新启动。在这种情况下，请注意，虽然正在运行的服务器在迁移过程中暂停修改源密钥库，但在迁移和后续重启之间的间隔期间不会暂停。应注意服务器在此间隔期间不会修改源密钥库，因为任何此类更改都不会反映在目标密钥库中。

涉及多个正在运行的服务器的关键迁移

在线密钥迁移提供了在单个正在运行的服务器上暂停密钥环操作。如果多个正在运行的服务器正在使用所涉及的密钥库，要执行迁移，请使用以下过程：

  1. 手动连接到每个正在运行的服务器并设置 keyring_operations=OFF. 这确保没有正在运行的服务器正在使用源或目标密钥库，并满足脱机迁移所需的条件。

  2. 使用迁移服务器或 mysql_migrate_keyring为每个暂停的服务器执行离线密钥迁移。

  3. 手动连接到每个正在运行的服务器并设置 keyring_operations=ON.

所有运行的服务器都必须支持 keyring_operations系统变量。任何不需要的服务器都必须在迁移前停止并在迁移后重新启动。