集成故障排除指南
概述
集成系统由多个自动化的动态组件组成。排查那些表面上看不到的问题可能会让人望而生畏，但只要一步步地进行排查，就能定位并解决问题。
本故障排查指南可以帮助你了解这些动态组件和集成周期，并从整体上指导你如何排查相关问题。集成类型有很多，每种都有其独特之处，但它们的运行都依赖于相同的流程和动态组件。
适用范围
BarTender 2019 及更高版本
集成流程的组成部分
集成流程中有多个动态组件协同工作，实现打印任务的自动化。以下是每个组件的简要说明及其在流程中的作用。
服务
- BarTender 集成服务：该服务负责运行集成本身，启动和停止集成，并处理触发检测和处理。
- BarTender 打印调度服务：该服务处理标签文件，进行准备，并将其发送到打印队列。
- BarTender 系统服务：该服务负责服务之间以及与系统数据库之间的日志记录和通信。
打印引擎
打印引擎其实就是以服务形式运行的 BarTender Designer。在正在运行的进程列表中会显示为 bartend.exe。打印引擎由打印调度服务自动启动和关闭，用于实际打印标签。打印引擎默认具有以下特性：
- 打印调度服务会根据需要按需启动它们。如果集成负载较大，会自动开启更多实例。
- 它负责保持打印顺序（确保序列号和记录不会在标签纸上乱序）。
- 一次最多可处理 5 个文档，长时间未使用会自动关闭。
- 如果 60 分钟未被使用，打印调度服务会自动关闭它们。
打印引擎是自动化的。你无需手动打开或关闭它们，打印调度服务会自动处理。你最多可以拥有的打印引擎数量为 CPU 核心数的两倍。
集成周期
集成本质上是循环进行的。它们启动后会等待某个触发条件来激活工作。这个触发条件可以是文件、数据库中的记录、邮件、网络上的某些内容、基于时间的触发等。一旦检测到触发条件，集成就会开始处理数据并发送打印指令。紫色的打印调度框以外的所有内容都由集成服务处理。
通常情况下，任务被发送到队列后，打印调度服务向集成服务确认已完成，集成就会重新进入等待状态。
集成可能因以下几种原因进入停止状态：
- 这是一次性定时集成，不会重复执行。
- 在 Integration Builder、管理控制台中手动停止了集成，或服务被关闭。
- 集成系统发生故障且无法恢复。
由于集成系统包含多个动态组件，排查时请记住以下几点：
- 始终更新到最新的服务版本。这样可以避免遇到已修复的已知问题。
- 按顺序逐步排查集成周期的每一步，确保不是在修复上一步已经出错的内容。
- 如果需要帮助或遇到本指南未涵盖的问题，请联系技术支持！
在排查过程中，你需要访问集成文件（.btin）、标签文件（.btw）、任何数据库文件、触发数据（如果不是定时集成），以及 Integration Builder。
故障排查
权限问题在集成流程的许多环节中都很常见，尤其是在使用网络资源时。你可以通过点击集成标题，在“用户账户”部分输入信息，将集成权限提升到域账户。
请在此处设置权限，除非技术支持有特别说明，否则不要在集成服务上单独设置账户。同样，你也可以在 BarTender 系统服务上设置账户，集成服务会继承这些权限。
账户需具备以下条件，才能正常运行集成：
- 必须是本地管理员组成员（用于消息传递、访问临时文件、无障碍访问文件结构以获取标签等）
- 具备域级访问权限（用于访问网络打印机或网络驱动器）
- 组策略允许本地登录（没有这个权限无法运行服务或任务）
- 密码不应更改（避免因密码策略导致集成中断）
要排查集成流程，请点击每个步骤展开详细内容，逐步排查以定位问题：
启动集成
等待触发
集成启动后，就会等待触发条件到来。这一步看似无需排查，但如果你一直处于等待状态怎么办？如果触发条件始终没有到达怎么办？如果你遇到“什么都没发生”的情况，排查这一步可能有助于找到原因。
所有类型的集成都需要等待某个事件或内容出现，可能是文件、网络端口上的数据、表中的记录或特定时间。所有触发检测的设置都和上一步一样，位于 Integration 标题下的第一个子部分。
以下是常见集成类型可检查的内容：
文件集成
- 触发文件是否放在集成指定的扫描文件夹中？
- 触发文件是否符合预期的文件模式？比如集成在监控 .csv 文件，你却放了 .css 文件，文件模式就不匹配。
- 是否有其他集成先处理了这些文件？
数据库集成
- 数据是否插入到了正确的表中？
- 数据检测方式是否正确？比如集成在监控递增值，而你却更新了日期时间戳，检测方式就不匹配。
- 被监控的字段是否有递增，或者日期时间戳是否有更新？
Socket 和 Web 服务集成
- 数据是否发送到了正确的地址？
- 端口是否被防火墙阻挡？
关键要点
- 确保触发条件到达了正确的位置。
- 仔细检查是否有东西阻挡或抢先处理了触发条件。
检测后操作
和上一步类似，这一步看起来也应该能顺利进行。有时如果出现问题会直接报错，但有时只有在集成周期重复时问题才会显现。
这一步指的是集成收到数据后要执行的操作。只有两种类型的集成会用到检测后操作，其他类型可以跳过这一步。以下是常见有检测后操作的集成类型及排查要点：
文件集成
在所有集成类型中，这一步文件集成最容易出问题。如果检测后操作出错，集成会报错并提示问题所在。常见问题包括更改文件或文件夹的权限不足、文件路径错误等。
文件集成的检测后操作设置如下：
Socket 集成
在这一步，Socket 集成的问题不像文件集成那么明显。如果你的 Socket 集成流量较小，可能不会有问题，但如果流量较大，偶尔会出现这样的错误：“Error: Cannot access disposed object.”
出现这种情况是因为 Socket 在接收数据后没有及时关闭，导致新数据不断涌入。集成还没准备好处理新数据，就会把它当作无效数据直接丢弃，结果就是数据丢失，打印任务也会漏掉。
如果你发现有这种情况，可以参考这篇文章了解如何修复：运行 Socket 集成时报错：无法访问已释放的对象。
关键要点
- 这一步只适用于两种特定的集成类型。
- 这一步出错时不一定会有明显提示。
处理集成操作
集成操作是指您的集成在处理和打印标签时所执行的所有步骤。所有操作都会列在操作标题下方：
这个例子非常简单，只包含了一个打印操作。但有些集成可能包含多个步骤，比如循环、数据解析、输出消息或邮件，或条件语句。下面是一个更复杂的例子，通过一系列命名的“查找”和“删除”操作从触发器中解析数据，然后在“打印文档”操作中使用这些数据：
这样会增加此步骤的复杂性，也增加了出错的可能性。最好的方法是先从简单做起。将操作精简到最少，尽量减少步骤（通常只保留新建集成时默认的操作和处理数据所需的最基本操作），然后从这里开始。
- 去除多余的步骤。先保持最精简。
- 逐步添加每个步骤，并测试，确保问题不在该操作上。
这一环节最大的挑战是测试。如果问题出现在集成流程的后续步骤，那么在测试所有步骤时问题都会持续存在。即便如此，仔细检查本步骤的所有内容仍然非常重要。以下是集成最小步骤中常见的问题：
文档位置
要打印标签，集成当然必须能够打开文档。如果文档的位置或名称无效，集成通常会报文档错误，提示打开文档时出现问题。您可以在以下位置找到文档名称：
- 打印文档操作：在“文档”选项卡的“文档”部分。如果文档由变量决定，请追溯该变量的来源（通常来自数据库字段名、设置变量操作或某个查找操作），并确保该变量中的数据是准确的。
- 打印命令脚本操作：在触发数据的 /AF 参数中
- 打印 BTXML 操作：在触发数据的 <Format> 标签中
如果在“打印文档”操作中没有指定文档，启动集成时会立即报错，提示缺少文档。
打印机名称
就像没有文档无法打印一样，没有有效的打印机也无法打印。大多数情况下，集成会报错，通常是无效打印机错误或 Windows 错误代码 1801（Windows 无法使用该打印机）。后者属于 Windows 系统问题，不在本故障排查范围内。前者可以在以下位置找到：
- 打印文档操作：在“打印选项”选项卡的“打印机”字段中
- 打印命令脚本操作：在触发数据的 /P 参数中
- 打印 BTXML 操作：在触发数据的 <Printer> 标签中
如果没有指定打印机，集成会使用标签文件中保存的打印机。如果您的集成没有指定打印机，请在 BarTender Designer 中打开标签，进入 文件 > 打印，这里显示的就是集成正在使用的打印机。
有时，标签会被发送到意外的打印机，或者直接消失。这通常是因为打印机重定向系统启动，将打印任务发送到了第一个可用的打印机。如果遇到这种情况，请参考这篇文章解决问题：集成打印被发送到错误或随机的打印机。
数据库类型或字段名不匹配
如果您的集成使用了数据库并从集成接收数据，必须确保数据库类型一致。例如，您的标签连接的是逗号分隔值（CSV）数据库，但集成发送的数据是制表符分隔的，或者是完全不同的格式，比如 XML 数据。这会导致数据库类型不匹配，文档无法识别接收到的数据，可能会出现各种集成错误，提示数据库、字段或数据为空等问题。
此外，即使数据库类型一致，如果字段名称不同或顺序不同，也会导致类似的集成错误。
要再次确认数据库是否正确匹配，可以这样操作：
- 在 BarTender Designer 中打开标签文件，进入 文件 > 数据库连接设置。在此对话框中可以查看标签连接的字段名称和数据库类型。
- 还可以在该设置对话框中找到已连接数据库的名称，并在电脑上打开它，检查格式（如 CSV 与制表符分隔）以及字段名称。
- 将已连接的数据库与触发器中包含的数据进行对比。
如果您的标签数据库不是文本文件（或 BarTender 2019 R5 及以后版本的 Excel 文件），集成总会因数据库不匹配而失败。如果标签连接的是不受支持的数据库，您必须将连接更改为受支持的数据库，并重新配置标签上的对象以引用新的字段。
标签只显示默认数据
出现这种情况是因为集成在打印时没有将数据传递给标签。通常是因为集成没有被告知要这样做（默认行为），只会在“打印文档”操作中出现。以下是两种常见情况及其解决方法：
- 传递数据库信息：集成必须被告知要覆盖信息。这可以在“打印文档”操作的“打印选项”选项卡的“数据库覆盖”部分设置。您需要用 集成数据 或 EventData 覆盖数据库，才能将触发数据传递给标签。
- 未定义命名数据源：集成必须被告知如何将变量与标签上的命名数据源进行配对。如果发现“命名数据源”选项卡下缺少同名的数据源，请点击“文档”选项卡上的“导入文档设置”按钮，然后将导入的命名数据源与集成变量进行配对。
关键要点
- 为更好地排查本步骤问题，先将操作数量减少到最少，然后逐步添加，观察问题出现在哪一步。
- 数据问题在本步骤中很常见，及时修正可避免后续步骤出现问题。
生成打印 BTXML
集成流程中的打印部分依赖于一种格式化的 XML，称为 BTXML。它包含文档和打印机信息，以及您设置要传递给标签的触发文件中的任何数据。
虽然您可以自己创建 BTXML 并通过“打印 BTXML”操作发送到集成，但其实没必要！集成会自动将您在打印操作中的数据和设置转换为 BTXML。
如果您已经完成了前面步骤的所有故障排查，BTXML 会被正常转换，您可以进入下一步。
自动化打印
在集成流程循环前的最后一步，就是实际的打印。这一切都由“打印调度器”服务自动完成，流程非常简单。以下是本文顶部流程图中的一部分：
一旦 BTXML 脚本从上一步发送到打印调度器，这一步就会立即开始。该服务负责打开打印引擎，然后解析需要打开哪个标签文件（如果该文件还未在引擎中打开）。文档打开后，如果集成传递了数据（通过数据库覆盖或命名数据源），数据会被放入标签的正确位置。数据处理完成后，标签会被发送到 BTXML 中指定的打印机，或者如果未指定，则发送到标签文件中关联的打印机。
所有这些都是服务自动完成的，如果出现问题该怎么办？如何排查？由于前面步骤已经做了大部分工作，这一步的排查其实比想象中简单。
正如本指南开头所提到的，打印调度器服务使用的打印引擎其实就是以服务方式运行的 BarTender Designer。这意味着，您可以直接用 Designer 本身来排查本步骤的问题。
基础故障排查
在打印时，打印引擎会根据 BTXML 脚本的指令自动打印标签文件。如果您要模拟这个脚本，只需打开标签，进入 文件 > 打印，更改打印机名称，然后打印文档。虽然 BTXML 脚本还可以做一些额外操作，但这个简单的动作已经能让我们了解“看不见的”打印引擎正在发生什么。
打开和打印文档
打印引擎最基本的行为就是打开和打印文档。前面的步骤已经检查了文档是否在正确的位置，打开文档可以进一步确认打印引擎在打印时能否正常使用该文档。
- 尝试打开文档。能否正常打开？是否弹出错误或提示信息？
- 尝试打印文档。能否正常打印？是否弹出错误或警告？
如果出现了弹窗警告或错误，这些都可能影响自动打印流程。下一节会介绍如何处理这些弹窗。
错误和警告对话框
虽然打印引擎可以跳过大多数对话框，但有些对话框会导致打印被跳过或出错。有时，打印引擎不会将这些信息正确记录到集成日志中，因此在这里检查和观察这些对话框有助于发现问题。
以下是一些可能被跳过但仍可能导致集成问题的对话框示例：
- 页面调整对话框：当打印机的介质略有不同，BarTender 会自动调整标签。如果标签显示异常，可能是介质不同。请调整标签并用集成用的打印机保存，以防止该对话框弹出。
- 裁剪警告：在 BarTender 2019 早期版本中，这个警告会导致打印中断。如果打印在这里停止，请升级您的软件。
- TrueType 字体替换提示：可以在打印对话框中关闭该提示。该对话框无法被跳过，建议关闭。
以下是一些可能导致打印中断并报错的对话框，这些也可能出现在集成消息中：
- 页面大小错误对话框：如果模板设置为固定尺寸或尺寸超出打印机规格，集成自动调整文档时可能会弹出该提示。遇到这种情况，请进入 文件 > 页面设置，检查“页面”选项卡的详细信息和设置，并在“布局”选项卡检查列数和行数是否过多。
- 数据库连接错误：如果数据库文件被移动或无法访问，会出现此类错误。请通过 文件 > 数据库连接设置 重新建立连接并保存文档。
- 模板未引用数据库字段：请参阅 错误 3600：模板未引用任何数据库字段。
- 缺失图片或链接对象：如果链接的图片或对象被移动或所在网络位置不可用，会出现此错误。BarTender 不会打印，直到重新链接这些对象或图片。
- 提到 TMP 的错误：标签或链接资源可能已损坏。建议恢复标签备份或重新制作。
这并不是全部问题，但涵盖了排查过程中最常见的一些情况。
关键要点
- 这个自动化步骤可以通过 BarTender Designer 进行检查。
- 对话框通常能提示您问题所在。
其他故障排查
有时候，问题并不能直接在集成流程中发现。这里有一些额外的资源，可能会帮助你解决上文未提及的其他情况。
通用问题
集成突然停止
集成可能因为多种原因停止，其中一些原因在上文已有介绍。最常见但未提及的原因是资源突然不可用。这种情况在数据库集成和使用云存储位置的文件集成中最为常见。BarTender 2021 会在资源恢复可用时尝试重新启动集成，但早期版本则会直接停止集成。
如果你的集成突然停止，请检查日志中的最新错误，以确定原因。
文件集成
集成运行缓慢
导致文件集成运行缓慢的因素有很多，但这种类型的集成有其独特的影响因素。扫描文件夹的大小很重要。由于文件集成依赖于扫描文件夹以查找新文件，如果文件数量变得非常多，扫描时间就会越来越长，尤其是有更多文件被放入该文件夹时。
如果你的集成没有设置在处理完触发文件后删除或移动这些文件，这些触发文件会随着时间积累。如果你发现集成运行缓慢，尝试从扫描文件夹中移除已处理的触发文件，看看是否能提升速度。
数据库集成
重复记录或多次打印
如果数据库集成正在扫描某个表，而标签也连接到同一个表，你很可能会遇到标签重复打印的情况。请参考以下文章，了解如何解决此问题，以及如何正确设置数据库集成和标签：
集成读取记录缓慢
集成运行缓慢可能有多种原因，但数据库集成有其特殊情况。数据库集成会扫描整个表，以查找符合触发条件的新记录。如果数据库表变得非常大，随着记录数量增加，每次查询都会给数据库服务器带来更大压力，导致处理速度变慢。
建议定期清理数据库中未使用的记录，或设置集成在处理后删除记录，以减轻数据库和集成的压力。
Socket 集成
无法访问已释放对象错误
如果你发现集成跳过了某些标签，可能会在日志中看到“无法访问已释放对象”的错误。这意味着 socket 在作业之间没有正确关闭。要解决此问题，请参阅运行 Socket 集成时报错：无法访问已释放对象。
还需要帮助吗？联系我们！
虽然点击启动按钮或让集成自动启动看起来似乎无需排查，但这其实是集成周期的关键第一步。这一步会让集成开始监控触发条件。如果出现问题或触发位置不可用，集成就会一直等待，甚至可能报错。
不同类型的集成在集成文件中对此信息的命名不同，需正确配置才能正常工作。对于所有类型的集成，相关设置都在 Integration 部分的第一个子部分，会说明它在监控什么。在下图中，这是文件集成，因此子部分名称为“文件检测”，表示它在监控文件以触发集成。
这一步常见的问题通常与权限、文件名和触发设置有关。如果你在 Integration Builder 中尝试启动集成，通常会立即弹出错误提示。
以下是常见集成类型在此步骤中可能出现问题的场景：
文件集成
对于文件集成，权限和文件位置非常关键。
如果集成无法访问文件夹，通常会报权限错误或访问错误。建议扫描文件夹不要使用虚拟驱动器（即非物理驱动器），也不要放在“我的文档”或桌面上。
同样建议扫描文件夹只放在基于 Windows 的系统上。如果你打算用 Unix、Linux 或其他操作系统托管扫描目录，建议使用如 FTP 这样的云存储位置。
如果是网络文件夹，请提升集成的权限，确保有权访问。
数据库集成
能否访问数据库是关键。请确认以下内容：
这些设置都在连接设置对话框中。和排查标签上的数据库连接一样，通过“数据库连接设置...”按钮打开该对话框，可以判断数据库是否连接正常。如果不正常，会弹出错误提示。
Socket 集成
网络连接非常重要。如果无法建立连接，可以先检查连接本身。
集成需要一个空闲端口。如果端口上有其他程序在通信，集成通常会报错，提示端口不可用。和其他集成一样，错误信息通常会告诉你问题所在及解决方法。
关键要点
虽然每种集成在这一步的细节不同，但排查时有几个共同点：