管理工具

Polaris 提供了一个供管理员管理元数据存储的工具。

该工具以 Docker 镜像形式提供：apache/polaris-admin-tool。它也可以作为二进制发行版的一部分下载。

📝 注意

该工具必须在构建时包含相应的数据库驱动，才能访问元数据存储数据库。默认构建包含了 PostgreSQL 和 NoSQL（MongoDB）后端的驱动。

使用方法

使用前，请确保管理工具与 Polaris 服务端的版本一致。要运行独立 JAR，请使用以下命令：

如果你下载了二进制发行版，可以按如下方式运行管理工具：

java -jar polaris-bin-<version>/admin/quarkus-run.jar --help

请确保将 <version> 替换为你所使用的 Polaris 实际版本。

如果要改为运行 Docker 镜像，请使用以下命令：

docker run apache/polaris-admin-tool:latest --help

Polaris 管理工具的基本用法概述如下：

Usage: polaris-admin-tool.jar [-hV] [COMMAND]
Polaris administration & maintenance tool
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help       Display help information about the specified command.
  bootstrap  Bootstraps realms and root principal credentials.
  purge      Purge realms and all associated entities.
  nosql      Sub-commands specific to NoSQL persistence.

配置

Polaris 管理工具必须使用与 Polaris 服务器相同的配置来运行。配置可以通过环境变量或系统属性完成。

至少需要配置 Polaris 管理工具，使其连接到 Polaris 服务器所使用的同一数据库。

有关配置数据库连接的更多信息，请参阅 Metastores 章节；有关完整的配置选项列表，请参阅配置参考。

注意：Polaris 在启动引导（bootstrap）过程中始终会在所配置的数据库下创建名为 polaris_schema 的 schema。

引导初始化 Realm 和主体凭据

bootstrap 命令用于引导初始化 Realm，并为 Polaris 服务器创建所需的主体凭据。该命令是幂等的，可以多次运行而不会产生任何问题。如果某个 Realm 已经完成引导初始化，再次运行 bootstrap 命令不会对该 Realm 产生任何影响。

如果你已下载二进制发行版，可以按如下方式运行 bootstrap 命令：

java -jar polaris-bin-<version>/admin/quarkus-run.jar bootstrap --help

你也可以使用 Docker 镜像来运行 bootstrap 命令：

docker run apache/polaris-admin-tool:latest bootstrap --help

bootstrap 命令的基本用法概述如下：

Usage: polaris-admin-tool.jar bootstrap [-hV] ([-r=<realm> [-r=<realm>]...
                                        [-c=<realm,clientId,clientSecret>]...
                                        [-p]] | [[-f=<file>]])
Bootstraps realms and root principal credentials.
  -h, --help                Show this help message and exit.
  -V, --version             Print version information and exit.
Standard Input Options:
  -c, --credential=<realm,clientId,clientSecret>
                            Root principal credentials to bootstrap. Must be of
                              the form 'realm,clientId,clientSecret'.
  -p, --print-credentials   Print root credentials to stdout
  -r, --realm=<realm>       The name of a realm to bootstrap.
File Input Options:
  -f, --credentials-file=<file>
                            A file containing root principal credentials to
                              bootstrap.

例如，要初始化 realm1 realm 并创建其根主体凭证，客户端 ID 为 admin、客户端密钥为 admin，你可以运行以下命令：

PostgreSQL 后端示例：

docker run --rm -it \
  --env="polaris.persistence.type=relational-jdbc" \
  --env="quarkus.datasource.username=<your-username>" \
  --env="quarkus.datasource.password=<your-password>" \
  --env="quarkus.datasource.jdbc.url=<jdbc-url-of-postgres>" \
  apache/polaris-admin-tool:latest bootstrap -r realm1 -c realm1,admin,admin

NoSQL（MongoDB）后端示例：

docker run --rm -it \
  --env="polaris.persistence.type=nosql" \
  --env="polaris.persistence.nosql.backend=MongoDb" \
  --env="quarkus.mongodb.database=polaris" \
  --env="quarkus.mongodb.connection-string=<mongodb-connection-string>" \
  apache/polaris-admin-tool:latest bootstrap -r realm1 -c realm1,admin,admin

如你所见，Polaris Admin Tool 必须使用适当的配置运行，才能连接到 Polaris 服务器所使用的同一数据库。配置可以通过环境变量（如上所示）或系统属性完成。

要了解应使用哪些配置选项，请阅读 Metastores 章节以及你所使用的特定元数据存储后端的文档。

清除 Realm 和主体凭据

purge 命令用于从 Polaris 服务器中删除 realm 和主体凭据。

⚠️ 警告

运行 purge 命令将删除与指定 realm 相关联的所有数据！这包括所有实体（catalog、namespace、表、视图、角色）、所有主体凭据、授权以及与这些 realm 关联的任何其他数据。

如果你已下载二进制发行版，可以按如下方式运行 purge 命令：

java -jar polaris-bin-<version>/admin/quarkus-run.jar purge --help

你也可以使用 Docker 镜像来运行 purge 命令：

docker run apache/polaris-admin-tool:latest purge --help

purge 命令的基本用法如下：

Usage: polaris-admin-tool.jar purge [-hV] -r=<realm> [-r=<realm>]...
Purge realms and all associated entities.
  -h, --help            Show this help message and exit.
  -r, --realm=<realm>   The name of a realm to purge.
  -V, --version         Print version information and exit.

例如，要清除 realm1 realm，可以运行以下命令：

PostgreSQL 后端示例：

docker run --rm -it \
  --env="polaris.persistence.type=relational-jdbc" \
  --env="quarkus.datasource.username=<your-username>" \
  --env="quarkus.datasource.password=<your-password>" \
  --env="quarkus.datasource.jdbc.url=<jdbc-url-of-postgres>" \
  apache/polaris-admin-tool:latest purge -r realm1

NoSQL（MongoDB）后端示例：

docker run --rm -it \
  --env="polaris.persistence.type=nosql" \
  --env="polaris.persistence.nosql.backend=MongoDb" \
  --env="quarkus.mongodb.database=polaris" \
  --env="quarkus.mongodb.connection-string=<mongodb-connection-string>" \
  apache/polaris-admin-tool:latest purge -r realm1

同样，必须以适当的配置运行 Polaris Admin Tool，才能连接到 Polaris 服务器所使用的同一数据库。配置可以通过环境变量（如上所述）或系统属性完成。

NoSQL 特定操作

nosql 管理工具命令用于执行 NoSQL 元数据存储的特定操作。

Usage: polaris-admin-tool.jar nosql [-hV] [COMMAND]
Sub-commands specific to NoSQL persistence.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  maintenance-info  Polaris NoSQL persistence maintenance information.
  maintenance-log   Show Polaris persistence maintenance log.
  maintenance-run   Run Polaris persistence maintenance.

运行 NoSQL 维护

使用 nosql maintenance-run 命令运行 NoSQL 维护。维护包括删除过期的数据库条目。

📝 注意

建议定期运行 nosql maintenance-run 命令，例如每天运行一次。

输出内容会显示一系列配置选项，其中大多数由该工具自动确定。

Maintenance configuration:
            created-at grace time: PT3H
                delete batch size: 10
                    retained runs: 50
            expected object count: 100000
         expected reference count: 100
              last-run multiplier: 1.100000
                  initialized FPP: 0.000010
                     expected FPP: 0.000050
  reference scan rate limit / sec: (unlimited)
  object    scan rate limit / sec: (unlimited)

其余输出是一份详细的维护运行报告。

NoSQL 维护的实现是自调优的，通常无需额外配置。

如果发现维护运行操作给数据库带来了过大的负载，可以调整扫描速率以降低负载。引用和对象扫描速率的选项分别是 polaris.persistence.nosql.maintenance.object-scan-rate-limit-per-second 和 polaris.persistence.nosql.maintenance.reference-scan-rate-limit-per-second，两者默认值均为「无限制」。让维护长时间运行是安全的，没有运行时长限制。或者，你也可以在非高峰时段以较高速率或默认的无限扫描速率运行维护。

📝 注意

nosql maintenance-run 命令可能会发出警告，提示并非所有可清除的数据库条目都已删除。在这种情况下，工具已经确定了将在下一次维护运行中生效的参数。该警告仅为提示信息，通常可以忽略。

预期的对象和引用数量是根据上次运行期间实际扫描到的对象和引用数量，乘以 count-from-last-run-multiplier 的值计算得出的。

如果频繁遇到此警告，尤其是连续多次维护运行都出现该警告，则说明写入数据库的数据量超出了预期。此时，应将 polaris.persistence.nosql.maintenance.count-from-last-run-multiplier 配置选项的值调高。其默认值为 1.1。

所有 NoSQL 维护配置选项都位于 polaris.persistence.nosql.maintenance 命名空间下。更多信息请参阅 Configuration Reference（配置参考）页面。

如果最近记录的维护运行尚未结束，nosql maintenance-run 命令将拒绝启动新的运行。如果已确认上一次运行已被放弃，可通过 --supersede-run=<run-id> 并传入失败消息中报告的运行 ID 来重新执行该命令。

除非确定上一次运行已不再活动，否则请避免替换（supersede）维护运行，因为这样做可能导致维护任务重叠，从而给数据库带来不必要的负载。

查看 NoSQL 维护运行日志

nosql maintenance-log 命令会显示最近一次 NoSQL 维护运行的日志。

该命令可用于审计和调试。

查看 NoSQL 维护信息

nosql maintenance-info 命令会显示生效的维护参数。这些信息也会在 nosql maintenance-run 命令的输出中显示。

管理工具

管理工具

使用方法

配置

引导初始化 Realm 和主体凭据

清除 Realm 和主体凭据

NoSQL 特定操作

运行 NoSQL 维护

查看 NoSQL 维护运行日志

查看 NoSQL 维护信息

评论