ACAL Lynxus 工具包指南

概述

Lynxus 工具包包含多个命令行实用程序，用于在独立和集群环境中设置和支持 Lynxus。实用程序包括：

CLI — cli 工具使管理员能够与 Lynxus 和 Lynxus Registry 实例交互，以自动化任务，如部署版本化流和管理进程组及集群节点。

实用程序在 Lynxus 工具包安装的 bin 文件夹中的脚本执行。

Lynxus 工具包与 Lynxus 分开下载（请参阅 ACAL Lynxus 下载页面）。

在安全环境中运行的先决条件

对于安全节点和集群，应预先配置两个策略：

访问控制器——有权访问这些实用程序的用户应在 Lynxus 中通过创建具有查看和修改权限的"访问控制器"策略（/controller）进行授权
代理用户请求——如果之前未设置，应授权节点的身份（节点证书的 DN 值）代表用户代理请求

在安全环境中执行通知或节点管理器工具时，应使用 proxyDN 标志选项，以便正确识别被授权执行这些命令的用户。在非安全环境中，或在节点管理器工具上运行状态操作时，该标志被忽略。

Lynxus CLI

此工具提供专注于与 Lynxus 和 Lynxus Registry 交互的 CLI，以自动化任务，如从 Lynxus Registry 部署流到 Lynxus 实例或管理进程组和集群节点。

用法

CLI 工具包可以在独立模式下执行以执行单个命令，或在交互模式下进入交互式 shell。

执行单个命令：

./bin/cli.sh <command> <args>

启动交互式 shell：

./bin/cli.sh

显示帮助：

./bin/cli.sh -h

以下是可用命令：

demo quick-import
lynxus current-user
lynxus cluster-summary
lynxus connect-node
lynxus delete-node
lynxus disconnect-node
lynxus get-root-id
lynxus get-node
lynxus get-nodes
lynxus offload-node
lynxus list-reg-clients
lynxus create-reg-client
lynxus update-reg-client
lynxus get-reg-client-id
lynxus pg-import
lynxus pg-connect
lynxus pg-start
lynxus pg-stop
lynxus pg-create
lynxus pg-get-version
lynxus pg-stop-version-control
lynxus pg-change-version
lynxus pg-change-all-versions
lynxus pg-get-all-versions
lynxus pg-list
lynxus pg-status
lynxus pg-get-services
lynxus pg-create-service
lynxus pg-enable-services
lynxus pg-disable-services
lynxus pg-get-param-context
lynxus pg-set-param-context
lynxus pg-replace
lynxus pg-export
lynxus pg-delete
lynxus get-services
lynxus get-service
lynxus create-service
lynxus enable-services
lynxus disable-services
lynxus get-reporting-tasks
lynxus get-reporting-task
lynxus create-reporting-task
lynxus delete-reporting-task
lynxus start-reporting-tasks
lynxus stop-reporting-tasks
lynxus export-reporting-tasks
lynxus export-reporting-task
lynxus import-reporting-tasks
lynxus create-flow-analysis-rule
lynxus get-flow-analysis-rules
lynxus get-flow-analysis-rule
lynxus enable-flow-analysis-rules
lynxus disable-flow-analysis-rules
lynxus delete-flow-analysis-rule
lynxus list-users
lynxus create-user
lynxus list-user-groups
lynxus create-user-group
lynxus update-user-group
lynxus get-policy
lynxus update-policy
lynxus list-param-contexts
lynxus get-param-context
lynxus create-param-context
lynxus delete-param-context
lynxus set-inherited-param-contexts
lynxus remove-inherited-param-contexts
lynxus set-param
lynxus delete-param
lynxus export-param-context
lynxus import-param-context
lynxus merge-param-context
lynxus list-param-providers
lynxus get-param-provider
lynxus create-param-provider
lynxus delete-param-provider
lynxus fetch-params
lynxus set-param-provider-property
lynxus get-access-token
lynxus get-access-token-spnego
lynxus logout-access-token
lynxus get-controller-configuration
lynxus update-controller-configuration
lynxus change-version-processor
lynxus upload-nar
lynxus download-nar
lynxus delete-nar
lynxus list-nars
lynxus list-nar-component-types
lynxus create-asset
lynxus list-assets
lynxus get-asset
lynxus delete-asset
lynxus add-asset-reference
lynxus remove-asset-reference
registry current-user
registry list-buckets
registry create-bucket
registry delete-bucket
registry list-flows
registry create-flow
registry delete-flow
registry list-flow-versions
registry export-flow-version
registry import-flow-version
registry sync-flow-versions
registry transfer-flow-version
registry diff-flow-versions
registry upload-bundle
registry upload-bundles
registry list-bundle-groups
registry list-bundle-artifacts
registry list-bundle-versions
registry download-bundle
registry get-bundle-checksum
registry list-extension-tags
registry list-extensions
registry list-users
registry create-user
registry update-user
registry list-user-groups
registry create-user-group
registry update-user-group
registry get-policy
registry update-policy
registry update-bucket-policy
registry get-access-token
registry get-access-token-spnego
registry logout-access-token
registry export-all-flows
registry import-all-flows
session keys
session show
session get
session set
session remove
session clear
exit
help

显示特定命令的详细帮助：

./bin/cli.sh <command> -h

属性/参数处理

大多数命令需要为 Lynxus 或 Lynxus Registry 实例指定 baseUrl。

列出 Lynxus Registry 实例中存储桶的示例命令如下：

./bin/cli.sh registry list-buckets -u http://localhost:18080

为了避免在每个命令上指定 URL（以及 TLS 的其他可选参数），您可以定义包含重复参数的属性文件。

本地 Lynxus Registry 实例的属性文件示例如下：

 baseUrl=http://localhost:18080
 keystore=
 keystoreType=
 keystorePasswd=
 keyPasswd=
 truststore=
 truststoreType=
 truststorePasswd=
 proxiedEntity=

然后可以通过指定 -p 在命令上使用此属性文件：

./bin/cli.sh registry list-buckets -p /path/to/local-lynxus-registry.properties

然后您可以为计划交互的每个环境维护一个属性文件，例如开发、测试和生产环境。

除了在每个命令上指定属性文件外，您还可以设置默认属性文件，以便在未指定属性文件时使用。

默认属性文件使用 session 概念指定，该概念持久化到用户主目录中名为 .lynxus-cli.config 的文件中。

设置 Lynxus 默认属性文件的示例如下：

./bin/cli.sh session set lynxus.props /path/to/local-lynxus.properties

Lynxus Registry 的示例如下：

./bin/cli.sh session set lynxus.reg.props /path/to/local-lynxus-registry.properties

这会将上述属性写入用户主目录中的 .lynxus-cli.config，并允许在不指定 URL 或属性文件的情况下执行命令：

./bin/cli.sh registry list-buckets

上述命令现在将使用 local-lynxus-registry.properties 中的 baseUrl。

解析参数的顺序如下：

直接参数覆盖属性文件或会话中的任何内容
属性文件参数（-p）覆盖会话
当未指定其他内容时使用会话

安全配置

如果 Lynxus 和 Lynxus Registry 是安全的，则从 CLI 执行的命令需要建立 TLS 连接并以具有执行所需操作权限的用户身份进行身份验证。

目前 CLI 支持使用客户端证书和可选的代理实体进行身份验证。常见场景是从安装 Lynxus 或 Lynxus Registry 的节点之一运行 CLI，这允许 CLI 使用与 Lynxus/Lynxus Registry 实例相同的密钥库和信任库。

安全配置可以按命令指定，或在上一节描述的属性文件之一中指定。

以下示例适用于 Lynxus Registry，但相同概念适用于 Lynxus 命令。

示例 - 无代理实体的安全 Lynxus Registry

假设我们有一个包含"CN=user1, OU=LYNXUS"证书的密钥库，属性文件示例如下：

 baseUrl=https://localhost:18443
 keystore=/path/to/keystore.jks
 keystoreType=JKS
 keystorePasswd=changeme
 keyPasswd=changeme
 truststore=/path/to/truststore.jks
 truststoreType=JKS
 truststorePasswd=changeme

在此示例中，命令将以"CN=user1, OU=LYNXUS"身份执行。此用户需要是 Lynxus Registry 中的用户，访问存储桶的命令将仅限于此用户有权访问的存储桶。

示例 - 带代理实体的安全 Lynxus Registry

假设我们可以访问 Lynxus Registry 本身的密钥库，并且 Lynxus Registry 也配置为允许 Kerberos 或 LDAP 身份验证，属性文件示例如下：

 baseUrl=https://localhost:18443
 keystore=/path/to/keystore.jks
 keystoreType=JKS
 keystorePasswd=changeme
 keyPasswd=changeme
 truststore=/path/to/truststore.jks
 truststoreType=JKS
 truststorePasswd=changeme
 proxiedEntity=user1@LYNXUS.COM

在此示例中，keystore.jks 中的证书将用于 Lynxus Registry 服务器，例如"CN=localhost, OU=LYNXUS"。此身份需要在 Lynxus Registry 中定义为用户，并被授予"代理"权限。

"CN=localhost, OU=LYNXUS"将代理命令以 user1@LYNXUS.COM 身份执行。

交互式用法

在交互模式下，可以使用 tab 键执行自动补全。

例如，在空提示符下键入 tab 应显示第一个参数的可能命令：

#>
demo       exit       help       lynxus       registry   session

键入"lynxus "然后按 tab 将显示 Lynxus 的子命令：

#> lynxus
change-version-processor          delete-flow-analysis-rule         export-reporting-task             get-policy                        list-user-groups                  pg-export                         pg-delete
cluster-summary                   delete-node                       export-reporting-tasks            get-reg-client-id                 list-users                        pg-get-all-versions               pg-stop-version-control
connect-node                      delete-param                      fetch-params                      get-reporting-task                logout-access-token               pg-get-param-context              set-inherited-param-contexts
create-flow-analysis-rule         delete-param-context              get-access-token                  get-reporting-tasks               merge-param-context               pg-get-services                   remove-inherited-param-contexts
create-param-context              delete-param-provider             get-access-token-spnego           get-root-id                       offload-node                      pg-get-version                    set-param
create-param-provider             delete-reporting-task             get-controller-configuration      get-service                       pg-change-all-versions            pg-import                         set-param-provider-property
create-reg-client                 disable-flow-analysis-rules       get-flow-analysis-rule            get-services                      pg-change-version                 pg-list                           start-reporting-tasks
create-reporting-task             disable-services                  get-flow-analysis-rules           import-param-context              pg-connect                        pg-replace                        stop-reporting-tasks
create-service                    disconnect-node                   get-node                          import-reporting-tasks            pg-create                         pg-set-param-context              update-controller-configuration
create-user                       enable-flow-analysis-rules        get-flow-analysis-rules           list-param-contexts               pg-create-service                 pg-start                          update-policy
create-user-group                 enable-services                   get-param-context                 list-param-providers              pg-disable-services               pg-status                         update-reg-client
current-user                      export-param-context              get-param-provider                list-reg-clients                  pg-enable-services                pg-stop                           update-user-group

表示文件路径的参数，如 -p 或在会话中设置属性文件时，将自动补全正在键入的路径：

#> session set lynxus.props /tmp/
dir1/   dir2/   dir3/

输出

大多数命令支持指定 --outputType 参数的能力，或简写为 -ot。

目前输出类型可以是 simple 或 json。

交互模式下的默认输出类型是 simple，独立模式下的默认输出类型是 json。

list-buckets 的 simple 输出示例：

#> registry list-buckets -ot simple
My Bucket - 3c7b7467-0012-4d8f-a918-6aa42b6b9d39

list-buckets 的 json 输出示例：

#> registry list-buckets -ot json
[ {
  "identifier" : "3c7b7467-0012-4d8f-a918-6aa42b6b9d39",
  "name" : "My Bucket",
  "createdTimestamp" : 1516718733854,
  "permissions" : {
    "canRead" : true,
    "canWrite" : true,
    "canDelete" : true
  },
  "link" : {
    "params" : {
      "rel" : "self"
    },
    "href" : "buckets/3c7b7467-0012-4d8f-a918-6aa42b6b9d39"
  }
} ]

反向引用

使用交互式 CLI 时，常见场景是使用上一个结果中的 id 作为下一个命令的输入。反向引用提供了通过位置引用引用上一个命令结果的快捷方式。

并非每个命令都产生反向引用。要确定命令是否支持反向引用，请检查用法。

#> registry list-buckets help
列出当前用户有权访问的存储桶。 产生反向引用

利用反向引用的常见场景如下：

用户首先探索注册表实例中的可用存储桶

#> registry list-buckets
#   名称           标识符                                     描述
-   ------------   ------------------------------------   -----------
1   My Bucket      3c7b7467-0012-4d8f-a918-6aa42b6b9d39   (空)   2   Other Bucket   175fb557-43a2-4abb-871f-81a354f47bc2   (空)

然后用户使用反向引用查看其中一个存储桶中的流，引用上一个结果位置 1 中的存储桶 id

#> registry list-flows -b &1
使用位置 1 的反向引用 'My Bucket'   #   名称      标识符                                     描述
-   -------   ------------------------------------   ----------------
1   My Flow   06acb207-d2f1-447f-85ed-9b8672fe6d30   This is my flow.

然后用户使用反向引用查看流的版本，引用上一个结果位置 1 中的流 id

#> registry list-flow-versions -f &1
使用位置 1 的反向引用 'My Flow'   版本   日期                         作者                     消息
---   --------------------------   ------------------------   -------------------------------------
1     Tue, Jan 23 2018 09:48 EST   anonymous                  This is the first version of my flow.

用户部署流的版本 1，使用步骤 2 中存储桶和流 id 的反向引用

#> lynxus pg-import -b &1 -f &1 -fv 1
使用位置 1 的反向引用 'My Bucket'   使用位置 1 的反向引用 'My Flow'
9bd157d4-0161-1000-b946-c1f9b1832efd

步骤 4 能够引用步骤 2 的结果的原因是，步骤 3 中的 list-flow-versions 命令不产生反向引用，因此步骤 2 的结果仍然可用。

添加命令

要添加 Lynxus 命令，创建一个扩展 AbstractLynxusCommand 的新类：

public class MyCommand extends AbstractLynxusCommand {

  public MyCommand() {
      super("my-command");
  }

  @Override
  protected void doExecute(LynxusClient client, Properties properties)
          throws LynxusClientException, IOException, MissingOptionException, CommandException {
      // TODO 实现
  }

  @Override
  public String getDescription() {
      return "This is my new command";
  }
}

将新命令添加到 LynxusCommandGroup：

commands.add(new MyCommand());

要添加 Lynxus Registry 命令，执行相同步骤，但从 AbstractLynxusRegistryCommand 扩展，并将命令添加到 LynxusRegistryCommandGroup。

导出所有流

您可以使用 export-all-flows 执行以下任务：

列出所有存储桶
对于每个存储桶，列出所有流
对于每个流，列出所有版本
将每个版本导出到提供的目录

运行命令需要 --outputDirectory 参数。目录必须存在且权限正确设置。

导入所有流

您可以使用 import-all-flows 执行以下任务：

从 export-all-flows 创建的目录中列出所有代表流版本的文件
创建所有相应的存储桶
创建所有相应的流
导入所有相应的流版本

运行命令需要 2 个参数：

--input 参数表示从中读取文件的目录
--skipExisting 可选参数，配置如何处理现有流和流版本创建。如果提供，无论是否有缺失的流版本，都将跳过流和流版本创建。如果未提供，将创建缺失的流版本。

用法

import-all-flows 命令的输入源必须由 export-all-flows 命令创建。为避免迁移冲突，在此活动期间不应在 Lynxus Registry 中进行修改。具有相同名称的存储桶和流被视为相等。

导出所有流版本：

./bin/cli.sh registry export-all-flows -u http://localhost:18080 --outputDirectory "/my_dir/flow_exports"

导入所有流版本：

./bin/cli.sh registry import-all-flows -u http://localhost:18080 --input "/my_dir/flow_exports" --skipExisting

预期行为

用例 1：重新配置现有 Lynxus Registry

Lynxus 连接到 Lynxus Registry，Lynxus Registry 不更改，仅其配置更改。所有数据将被创建。

导出版本：

./bin/cli.sh registry export-all-flows -u http://localhost:18080 --outputDirectory "/my_dir/flow_exports"

停止注册表
切换提供程序
启动注册表

导入版本

./bin/cli.sh registry import-all-flows -u http://localhost:18080 --input "/my_dir/flow_exports" --skipExisting

用例 2：数据复制

Lynxus_1 连接到 Lynxus Registry_1，Lynxus_2 连接到 Lynxus Registry_2。

出于灾难恢复目的，Lynxus Registry_1 的数据需要通过计划作业定期复制到 Lynxus Registry_2。

Lynxus Registry_2 的初始版本需要由此工具创建。

将创建缺失的存储桶、流和版本。如果存储桶和流存在，将创建缺失的版本。

导出版本：

./bin/cli.sh registry export-all-flows -u http://lynxus-registry-1:18080 --outputDirectory "/my_dir/flow_exports"

导入版本：

./bin/cli.sh registry import-all-flows -u http://lynxus-registry-2:18080 --input "/my_dir/flow_exports"