ACAL Lynxus 入门指南

对于 Windows 用户，导航到 Lynxus 安装的文件夹。在此文件夹内有一个名为 bin 的子文件夹。导航到此子文件夹并运行 lynxus.cmd start。

这将启动 Lynxus 并使其在前台运行。要关闭 Lynxus，选择启动的窗口并在按住 Ctrl 键的同时按 C。

对于 Linux 和 macOS 用户，使用终端窗口导航到 Lynxus 安装的目录。要在前台运行 Lynxus，运行 bin/lynxus.sh run。这将使应用程序保持运行，直到用户按 Ctrl-C。届时，它将启动应用程序的关闭。

要在后台运行 Lynxus，改为运行 bin/lynxus.sh start。这将启动应用程序开始运行。要检查状态并查看 Lynxus 是否正在运行，执行命令 bin/lynxus.sh status。可以通过执行命令 bin/lynxus.sh stop 来关闭 Lynxus。

执行 bin/lynxus.sh start 会执行在后台启动 Lynxus 然后退出的 lynxus.sh 脚本。如果您希望 lynxus.sh 等待 Lynxus 完成调度所有组件后再退出，使用 --wait-for-init 标志和可选的超时（以秒为单位指定）：bin/lynxus.sh start --wait-for-init 120。如果未提供超时，将使用默认的 15 分钟超时。

如果 Lynxus 是通过 Homebrew 安装的，从文件系统的任何位置运行命令 lynxus start 或 lynxus stop 来启动或停止 Lynxus。

我们现在可以通过向画布添加处理器来开始创建数据流。为此，将处理器图标() 从屏幕左上角拖到画布中间（类似方格纸的背景）并放在那里。这将给我们一个对话框，允许我们选择要添加的处理器：

我们有很多选项可供选择。为了熟悉系统，假设我们只想将文件从本地磁盘带入 Lynxus。当开发人员创建处理器时，开发人员可以为该处理器分配"标签"。这些可以被视为关键字。我们可以通过在对话框右上角的筛选框中输入这些标签或处理器名称来筛选。输入您在想要从本地磁盘摄取文件时会想到的关键字。例如，输入关键字"file"将为我们提供几个处理文件的不同处理器。按术语"local"筛选也会很快缩小列表范围。如果我们从列表中选择处理器，我们将在对话框底部附近看到处理器的简要描述。这应该告诉我们处理器的确切功能。GetFile 处理器的描述告诉我们它从本地磁盘将数据拉入Lynxus，然后删除本地文件。然后我们可以双击处理器类型或选择它并选择`添加` 按钮。处理器将添加到画布上它被放置的位置。

现在我们添加了 GetFile 处理器，我们可以通过右键单击处理器并选择`配置` 菜单项来配置它。提供的对话框允许我们配置许多不同的选项，这些选项可以在用户指南 中阅读，但为了本指南的目的，我们将重点关注属性选项卡。一旦选择了属性选项卡，我们会得到一个我们可以为处理器配置的几个不同属性的列表。可用的属性取决于处理器的类型，通常对每种类型都不同。粗体的属性是必需的属性。在所有必需属性配置完成之前，处理器无法启动。GetFile 要配置的最重要属性是获取文件的目录。如果我们将目录名设置为 ./data-in，这将导致处理器开始获取Lynxus 主目录的 data-in 子目录中的任何数据。

我们可以选择为此处理器配置几个不同的属性。如果不确定特定属性的功能，我们可以将鼠标悬停在属性名称旁边的信息图标 () 上以阅读属性的描述。此外，显示的工具提示将提供该属性的默认值（如果存在），关于属性是否支持表达式语言的信息（参见下面的 表达式语言/在属性值中使用属性 部分），属性是否敏感并将在静态时加密，以及该属性以前配置值的历史记录。

为了使此属性有效，在 Lynxus 主目录中创建一个名为 data-in 的目录，然后单击 确定 按钮关闭对话框。

每个处理器都有一组定义的"关系"，它能够将数据发送到这些关系。当处理器完成处理FlowFile 时，它将其传输到这些关系之一。这允许用户根据处理结果配置如何处理 FlowFile。例如，许多处理器定义两个关系：success 和 failure。用户然后能够配置数据在处理器能够成功处理数据时以一种方式通过流路由，如果处理器由于某种原因无法处理数据，则以完全不同的方式通过流路由数据。或者，根据用例，它可能只是将两个关系路由到通过流的同一路由。

现在我们添加并配置了 GetFile 处理器并应用了配置，我们可以在处理器左上角看到一个警报图标 ()，表示处理器处于无效状态。将鼠标悬停在此图标上，我们可以看到 success`关系尚未定义。这仅仅意味着我们尚未告诉 Lynxus 如何处理处理器传输到 `success 关系的数据。

为了解决这个问题，让我们添加另一个处理器，我们可以将 GetFile 处理器连接到它，按照上述相同步骤。然而，这次我们只记录 FlowFile 存在的属性。为此，我们将添加 LogAttribute 处理器。

我们现在可以将 GetFile 处理器的输出发送到 LogAttribute 处理器。将鼠标悬停在 GetFile 处理器上，连接图标 () 将出现在处理器中间。我们可以将此图标从 GetFile 处理器拖到 LogAttribute处理器。这给我们一个对话框来选择我们想要为此连接包含哪些关系。因为 GetFile只有一个关系 success，它会自动为我们选择。

单击设置选项卡提供了一些配置此连接应如何行为的选项：

我们可以给连接命名，如果我们喜欢的话。否则，连接名称将基于所选关系。我们还可以为数据设置过期时间。默认情况下，它设置为"0 秒"，表示数据不应过期。但是，我们可以更改值，以便当此连接中的数据达到一定年龄时，它将自动被删除（并将创建相应的 EXPIRE 溯源事件）。

背压阈值允许我们指定队列允许变得多满，然后源处理器才不再被安排运行。这允许我们处理一个处理器能够比下一个处理器能够消费数据更快地产生数据的情况。如果沿途为每个连接配置背压，将数据带入系统的处理器最终将经历背压并停止带入新数据，以便我们的系统有能力恢复。

最后，我们在右侧有优先级排序器。这允许我们控制此队列中的数据如何排序。我们可以将优先级排序器从"可用优先级排序器"列表拖到"已选优先级排序器"列表以激活优先级排序器。如果激活了多个优先级排序器，它们将被评估，使得首先列出的优先级排序器将首先被评估，如果根据该优先级排序器确定两个 FlowFile 相等，将使用第二个优先级排序器。

为了本次讨论的目的，我们可以简单地单击 添加 将连接添加到我们的图中。我们现在应该看到警报图标已变为停止图标 ()。然而，LogAttribute 处理器现在无效，因为其 success 关系未连接到任何东西。让我们通过发出信号表明 LogAttribute 路由到 success 的数据应"自动终止"来解决这个问题，这意味着 Lynxus 应考虑 FlowFile 的处理完成并"丢弃"数据。为此，我们配置LogAttribute 处理器。在关系选项卡上，我们可以检查 success 关系旁边的 终止 框以自动终止数据。单击 应用 按钮将关闭对话框并显示两个处理器现在都已停止。

此时，我们的图上有两个处理器，但什么也没发生。要启动处理器，我们可以逐个单击每个处理器，然后右键单击并选择 启动 菜单项。或者，我们可以选择第一个处理器，然后在按住 Shift 键的同时选择另一个处理器以选择两者。然后，我们可以右键单击并选择 启动 菜单项。作为使用上下文菜单的替代方法，我们可以选择处理器，然后单击操作面板中的启动图标。

启动后，处理器左上角的图标将从停止图标变为运行图标。然后我们可以通过使用操作面板中的停止图标或 停止 菜单项来停止处理器。

一旦处理器启动，我们就不再能够配置它。相反，当我们右键单击处理器时，我们会获得查看其当前配置的选项。为了配置处理器，我们必须首先停止处理器并等待任何可能正在执行的任务完成。当前正在执行的任务数量显示在处理器右上角附近，但如果当前没有任务则不显示任何内容。

由于每个处理器都有能力公开多个不同的属性和关系，记住每个处理器的所有不同部分如何工作可能具有挑战性。为了解决这个问题，您可以右键单击处理器并选择 查看文档 菜单项。这将为您提供处理器的使用信息，例如处理器的描述、可用的不同关系、何时使用不同关系、处理器公开的属性及其文档，以及传入 FlowFile 上预期哪些 FlowFile 属性（如果有）和哪些属性（如果有）添加到传出 FlowFile。一些处理器还描述了完成它们常用用例所需的特定配置。

为用户提供将处理器拖放到图上的能力的工具栏包括几个其他组件，可用于构建数据流。这些组件包括输入和输出端口、漏斗、进程组和远程进程组。由于本文档的预期范围，我们不会在此讨论这些元素，但信息在构建数据流部分 的用户指南 中随时可用。

每个 FlowFile 都有最小属性集：

请注意，uuid、entryDate、lineageStartDate 和 fileSize 属性是系统生成的，无法更改。

Lynxus 提供几个不同的开箱即用处理器，用于从 FlowFile 提取属性。常用处理器列表可以在上面的 属性提取 部分找到。这也是构建自定义处理器的非常常见的用例。许多处理器被编写为理解特定数据格式并从FlowFile 的内容中提取相关信息，创建属性来保存该信息，以便然后可以做出关于如何路由或处理数据的决策。

除了拥有能够从 FlowFile 内容中提取特定信息到属性的处理器外，用户还通常希望在流的特定位置向每个 FlowFile 添加自己的用户定义属性。UpdateAttribute 处理器专门为此目的设计。用户能够通过单击属性选项卡右上角的"+"按钮在配置对话框中向处理器添加新属性。然后提示用户输入属性名称和值。对于由此 UpdateAttribute处理器处理的每个 FlowFile，将为每个用户定义的属性添加一个属性。属性的名称将与添加的属性名称相同。属性的值将与属性的值相同。

属性的值也可以包含表达式语言。这允许基于其他属性修改或添加属性。例如，如果我们想将处理文件的文件名和日期添加到文件名，我们可以通过添加名称为 filename 和值为 ${hostname()}-${now():format('yyyy-dd-MM')}-${filename} 的属性来实现。虽然这乍一看可能令人困惑，但下面关于 表达式语言/在属性值中使用属性 的部分将有助于澄清这里发生的事情。

除了始终添加定义的属性集外，UpdateAttribute 处理器具有高级 UI，允许用户配置一组规则，用于何时应添加哪些属性。要访问此功能，右键单击 UpdateAttribute处理器并选择 高级 菜单项。这将提供专门针对此处理器定制的 UI，而不是为所有处理器提供的简单属性表。在此 UI 内，用户能够配置规则引擎，本质上指定必须匹配的规则，以便将配置的属性添加到 FlowFile。

Lynxus 最强大的功能之一是能够基于属性路由 FlowFile。主要机制是 RouteOnAttribute 处理器。此处理器像 UpdateAttribute 一样，通过添加用户定义的属性来配置。可以通过单击处理器配置对话框属性选项卡右上角的"+"按钮来添加任意数量的属性。

每个 FlowFile 的属性将与配置的属性进行比较，以确定 FlowFile 是否满足指定的标准。每个属性的值预期是表达式语言表达式并返回布尔值。有关表达式语言的更多信息，请参见下面的 表达式语言/在属性值中使用属性 部分。

在针对 FlowFile 的属性评估提供的表达式语言表达式后，处理器根据所选的路由策略确定如何路由 FlowFile。最常见的策略是"路由到属性名称"策略。使用此策略，处理器将为每个配置的属性公开一个关系。如果 FlowFile 的属性满足给定表达式，FlowFile 的副本将被路由到相应的关系。例如，如果我们有一个名称为"begins-with-r"和值为"${filename:startsWith('r')}"的新属性，则任何文件名以字母 'r' 开头的 FlowFile 将被路由到该关系。所有其他 FlowFile 将被路由到 'unmatched'。

当我们从 FlowFile 的内容中提取属性并添加用户定义的属性时，除非我们有某种机制可以使用它们，否则它们对我们作为操作员没有多大用处。Lynxus 表达式语言允许我们在配置流时访问和操作 FlowFile 属性值。并非所有处理器属性都允许使用表达式语言，但许多允许。为了确定属性是否支持表达式语言，用户可以悬停在处理器配置对话框属性选项卡中的信息图标 () 上。这将提供显示属性描述以及属性是否支持表达式语言的工具提示。

对于确实支持表达式语言的属性，通过在开始 ${ 标签和结束`}` 标签内添加表达式来使用。表达式可以像属性名称一样简单。例如，要引用 uuid 属性，我们可以简单地使用值 ${uuid}。如果属性名称以字母以外的任何字符开头，或者如果它包含数字、字母、句点 (.) 或下划线 (_) 以外的字符，则需要引用属性名称。例如，${My Attribute Name}`将无效，但 `${'My Attribute Name'} 将引用属性 My Attribute Name。

除了引用属性值外，我们还可以对这些属性执行许多函数和比较。例如，如果我们想检查 filename 属性是否包含字母 'r' 而不注意大小写（大写或小写），我们可以通过使用表达式 ${filename:toLower():contains('r')} 来实现。注意这里的函数用冒号分隔。我们可以链接任意数量的函数来构建更复杂的表达式。同样重要的是要理解这里，即使我们调用 filename:toLower()，这不会以任何方式改变 filename 属性的值，而是只给我们一个新的值来处理。

我们还可以将一个表达式嵌入另一个表达式中。例如，如果我们想将 attr1 属性的值与`attr2` 属性的值进行比较，我们可以使用以下表达式：${attr1:equals( ${attr2} )}。

表达式语言包含许多不同的函数，可用于执行路由和操作属性所需的任务。存在用于解析和操作字符串、比较字符串和数值、操作和替换值以及比较值的函数。不同可用函数的完整解释超出了本文档的范围，但表达式语言指南 为每个函数提供了更详细的说明。

此外，此表达式语言指南内置于应用程序中，以便用户能够轻松查看哪些函数可用并在键入时查看其文档。当设置支持表达式语言的属性值时，如果光标在表达式语言开始和结束标签内，按 Ctrl + 空格键将提供所有可用函数的弹出窗口，并将提供自动补全功能。单击或使用键盘导航到弹出窗口中列出的函数之一将导致显示工具提示，解释函数的功能、它期望的参数以及函数的返回类型。

在组件工具栏下方的 Lynxus 屏幕顶部附近是一个称为状态栏的栏。它包含有关 Lynxus 当前健康状况的一些重要统计数据。活动线程数可以指示 Lynxus 当前工作有多努力，排队统计指示整个流中当前排队的 FlowFile 数量以及这些 FlowFile 的总大小。

如果 Lynxus 实例在集群中，我们还将在此处看到一个指示器，告诉我们集群中有多少节点以及当前有多少节点已连接。在这种情况下，活动线程数和队列大小指示当前连接的所有节点的总和。重要的是要注意，活动线程仅捕获图上处理器的线程。当按集群中的节点细分时（全局菜单 → 集群），活动线程计数更全面，包括这些以及任何其他线程（输入和输出端口、漏斗、远程进程组、报告任务等）

画布上的每个处理器、进程组和远程进程组都提供有关组件处理了多少数据的几个统计数据。这些统计提供有关过去五分钟内处理了多少数据的信息。这是一个滚动窗口，允许我们看到诸如处理器消耗的 FlowFile 数量以及处理器发出的 FlowFile 数量等事情。

处理器之间的连接也公开有关通过连接的项目的几个统计数据。

查看这些指标的历史值以及（如果集群）不同节点如何相互比较也可能很有价值。为了查看此信息，我们可以右键单击组件并选择 查看状态历史 菜单项。这将向我们显示一个图表，跨越自 Lynxus 启动以来的时间，或最多 24 小时，以较短者为准。此处显示的时间量可以通过更改属性文件中的配置来扩展或减少。

在此对话框的右上角是一个下拉列表，允许用户选择他们正在查看的指标。底部的图表允许用户选择图表的较小部分以放大。

除了每个组件提供的统计数据外，用户还想知道是否出现任何问题。虽然我们可以监控日志以查找任何有趣的内容，但让通知弹出在屏幕上更方便。如果处理器记录任何内容为 WARNING 或 ERROR，我们将在处理器右上角看到"公告指示器"出现。此指示器看起来像便签，将在事件发生后显示五分钟。将鼠标悬停在公告上提供有关发生事件的信息，以便用户不必筛选日志消息来查找它。如果在集群中，公告还将指示集群中哪个节点发出了公告。我们还可以在处理器配置对话框的设置选项卡中更改公告发生的日志级别。

如果框架发出公告，我们还将在屏幕右上角看到公告指示器高亮显示。全局菜单中有公告板选项。单击此选项将带我们到公告板，在那里我们可以看到 Lynxus 实例中发生的所有公告，并可以基于组件、消息等进行筛选。

一旦我们执行了搜索，我们的表将仅填充匹配搜索条件的事件。从这里，我们可以单击表右侧的烤肉串图标 () 并选择 查看详细信息 该事件：

从这里，我们可以看到该事件何时发生、事件影响了哪个 FlowFile、哪个组件（处理器等）执行了事件、事件花了多长时间，以及事件发生时数据在 Lynxus 中的总时间（总延迟）。

下一个选项卡提供事件发生时 FlowFile 上存在的所有属性的列表：

从这里，我们可以看到事件发生时 FlowFile 上存在的所有属性，以及这些属性的先前值。这允许我们知道哪些属性由于此事件而更改以及它们如何更改。此外，在右侧角有一个复选框，允许用户仅查看更改的属性。如果 FlowFile 只有少数属性，这可能不是特别有用，但当 FlowFile 有数百个属性时可能非常有帮助。

这非常重要，因为它允许用户理解 FlowFile 被处理的确切上下文。理解 FlowFile 为何以这种方式处理很有帮助，特别是当处理器使用表达式语言配置时。

最后，我们有内容选项卡：

此选项卡向我们提供有关 FlowFile 的内容存储在内容存储库中何处的信息。如果事件修改了 FlowFile 的内容，我们将看到"之前"（输入）和"之后"（输出）内容声明。然后我们获得下载内容或在 Lynxus 本身内查看内容的选项，如果数据格式是 Lynxus 知道如何渲染的格式。

此外，在选项卡的重播部分，有一个"重播"按钮，允许用户将 FlowFile 重新插入流中，并从事件发生的精确点重新处理它。这提供了非常强大的机制，因为我们能够实时修改流、重新处理 FlowFile，然后查看结果。如果结果不符合预期，我们可以再次修改流，并再次重新处理 FlowFile。我们能够执行流的迭代开发，直到它完全按预期处理数据。

除了查看溯源事件的详细信息外，我们还可以查看涉及的 FlowFile 的血统。单击表右侧的烤肉串图标 () 并选择 显示血统 该事件。这向我们提供数据在系统遍历时发生的确切情况的图形表示：

从这里，我们可以右键单击任何表示的事件并单击 查看详细信息 菜单项以查看 事件详细信息。此图形表示向我们显示数据发生了哪些确切事件。有几个"特殊"事件类型需要注意。如果我们看到 JOIN、FORK 或 CLONE 事件，我们可以右键单击并选择查找父级或展开。这允许我们查看创建的父 FlowFile 和子 FlowFile 的血统。

左下角的滑块允许我们查看这些事件发生的时间。通过左右滑动，我们可以查看哪些事件将延迟引入系统，以便我们非常了解系统中可能需要提供更多资源的地方，例如处理器的并发任务数。或者它可能揭示，例如，大部分延迟是由 JOIN 事件引入的，其中我们等待更多 FlowFile 连接在一起。无论哪种情况，轻松查看此发生位置的能力是非常强大的功能，将帮助用户了解企业如何运营。