> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SFTP 端口
> 知行之桥SFTP 端口的配置和使用指南。
export const CommonCacheCleanup = () => <>
知行之桥会自动清理资源缓存。此过程在每次接收周期的后台运行，删除远程服务器上已不存在的文件对应的过期缓存条目。这使得缓存大小始终保持在可管理范围内，无需任何手动操作。
默认情况下，文件保留 30 天，但您可以在高级选项卡的其他设置字段中使用 ResourceCacheRetentionDays 设置来调整保留时间以适应您的环境。例如，ResourceCacheRetentionDays=15 表示文件保留 15 天后将被删除。
;
export const CommonServerCommands = ({extraCommands}) => <>
这些选项允许您在端口执行期间的不同时间在目标服务器上执行自定义命令。
虽然下面描述的命令是普遍接受的，但在尝试使用命令之前，请务必与目标服务器管理员核实，以确保服务器可以接受该命令。
| 设置 | 描述 |
|---|
| After Connect | 连接后直接执行此命令。 |
| After Get | 下载每个文件后执行此命令。 |
| After Put | 上传每个文件后执行此命令。 |
| Before Get | 在下载每个文件之前执行此命令。 |
| Before Put | 在上传每个文件之前执行此命令。 |
以下是当将以下命令包含在上述字段中时可以提交给目标服务器的命令：
• onerror：传递 fail 参数以指示端口将来自自定义脚本的错误视为整个事务的错误。如果没有 fail，端口会记录任何异常并继续处理。
• cd：改变目录。
• mkdir：创建目录。
• rn 或 move：重命名或移动文件。
• del 或 rm：删除文件。
• rmdir：删除目录。
{extraCommands}
知行之桥通过这些命令支持以下宏。它们都使用以下语法：%Macro%。某些宏，例如 %Date% 和 %SourceFilename%，不需要参数，但其他宏则需要。带参数的宏使用以下语法：%Macro:argument%。
| 宏 | 描述 |
|---|
| MsgHeader:headername | 计算消息的消息头值（例如：%MsgHeader:headername%）。 |
| SourceFilename | 计算当前正在处理的文件的文件名（包括扩展名）。 |
| SourceFilenameNoExt | 计算当前正在处理的文件的文件名（不带扩展名）。 |
| Date | 以 yyyy-MM-dd 格式计算文件的上次修改日期（例如 2024-02-13）。 |
| DateTime | 以 yyyy-MM-dd'T'HH:mm:ss 格式计算文件上次修改的日期时间（例如 2024-02-13T08:14:22）。 |
| Time | 以 HH:mm:ss 格式计算文件的上次修改时间（例如 08:14:22）。 |
| DateTime.tz | 以 yyyy-MM-dd'T'HH:mm:ss zzz 格式计算文件上次修改的日期时间（例如 2024-02-13T08:14:22 PST）。 |
| Time.tz | 以 HH:mm:ss zzz 格式计算文件的上次修改时间（例如 08:14:22 PST）。 |
| DateFormat:format | 以指定格式（format）计算系统的当前日期时间。有关可用的日期时间格式，请参阅 示例日期格式。 |
示例：下载后，您希望将每个文件从下载文件夹移动到 History 子文件夹。使用 After Get 字段为 move 命令提供 %SourceFilename% 宏。
;
export const CommonProxySettings = () => <>
这是一组用于识别连接所经代理并对其进行身份验证的设置。默认情况下，本节使用 安全设置 页面的 代理设置 部分中的全局设置。清除此复选框可为您的端口提供特定的设置。
| 设置 | 描述 |
|---|
| 代理类型 |
基于代理的防火墙使用的协议。 |
| 代理主机 |
基于代理的防火墙的名称或 IP 地址。 |
| 代理端口 |
基于代理的防火墙的 TCP 端口。 |
| 代理用户 |
用于通过基于代理的防火墙进行身份验证的用户名。 |
| 代理密码 |
用于对基于代理的防火墙进行身份验证的密码。 |
| 身份验证方案 |
保留默认值 None 或选择以下身份验证方案之一：Basic、Digest、Proprietary 或 NTLM。 |
;
export const SlasTab = ({siteName = "知行之桥"}) => <>
与配置服务级别协议 (SLA) 相关的设置。
SLA 允许配置预期流程中端口发送或接收的数据量，并设置预期达到该数据量的时间范围。当 SLA 未达到时，{siteName} 会发送电子邮件警告用户，并将 SLA 标记为 存在风险，这意味着如果 SLA 未能尽快达到，则会被标记为 已违反。这让用户有机会介入并确定 SLA 未达到的原因，并采取适当的措施。如果在风险时间段结束时仍未达到 SLA，则会将 SLA 标记为已违反，并再次通知用户。
要定义 SLA，请启用 预期数据量，然后点击 设置 选项卡。
- 如果端口具有单独的发送和接收操作，请使用单选按钮指定 SLA 适用的方向。
- 在窗口的 预计至少 部分中：
- 设置预计处理的最小事务数量（交易量）
- 使用 每个 字段指定时间范围
- 指示 SLA 生效的时间。如果选择 开始于，请填写日期和时间字段。
- 勾选希望 SLA 生效的星期几对应的复选框。如有必要，请使用下拉菜单选择 每天。
- 在窗口的 将状态设置为“有风险” 部分中，指定应将 SLA 标记为有风险的时间。
- 默认情况下，只有在违反 SLA 的情况下才会发送通知。要更改此设置，请勾选 发送“有风险”通知。
以下示例显示了为端口配置的 SLA，该端口预计在周一至周五每天接收 1000 个文件。如果尚未收到 1000 个文件，则会在时间段结束前 1 小时发送风险通知。
如果有必要，可以关闭 SLA 通知。这在维护窗口期间非常有用。点击导航栏上的 设置，然后跳转到 通知 > 通用通知。点击平板和铅笔图标进行编辑，并取消勾选 SLA 通知 设置。
;
export const AlertsTab = ({siteNameShort = "知行之桥"}) => <>
与配置通知相关的设置。
在执行服务级别协议 (SLA) 之前，需要设置电子邮件通知以接收通知。默认情况下，{siteNameShort} 使用 通知 选项卡上的全局设置。要为此端口使用其他设置，请启用 覆盖全局设置。
默认情况下，错误通知处于启用状态，这意味着每当出现错误时都会发送电子邮件。要关闭错误通知，请取消选中 启用 复选框。
输入 主题（必填），然后（可选）输入以逗号分隔的 收件人 电子邮件列表。
;
export const Message = () => <>
消息设置确定端口如何搜索消息并在处理后管理它们。
| 设置 | 描述 |
|---|
| 保存到已发送文件夹 |
选中此项可将端口处理的文件复制到该端口的“已发送”文件夹中。 |
| 已发送文件夹方案 |
端口根据选定的时间间隔对 已发送 文件夹中的文件进行分组。例如，Weekly 选项指示端口每周创建一个新的子文件夹，并将本周发送的所有文件存储在该文件夹中。空白设置告诉端口将所有文件直接保存在 已发送 文件夹中。对于处理许多事务的端口，使用子文件夹可以帮助保持文件有序并提高性能。 |
;
export const MiscConnector = () => <>
特殊设置适用于特定用例。
| 设置 |
描述 |
| 其他设置 |
允许在以分号分隔的列表中配置隐藏的端口设置，例如 setting1=value1;setting2=value2。正常的端口用例和功能不需要使用这些设置。 |
;
export const Logging = () => <>
用于管理日志创建和存储的设置。
| 设置 |
描述 |
| 日志级别 |
指定要记录在端口日志目录中的信息类型：
- None - 不创建任何日志。
- Error - 仅当端口遇到错误时才创建日志。
- Warning - 仅当端口发出警告时才创建日志。
- Info - 记录工作流的一般信息，包括任何错误和警告（如果适用）。
- Debug - 记录成功和失败工作流的详细调试信息。
- Trace - 记录成功和失败工作流的详细跟踪信息。
请注意：Debug 和 Trace 级别的日志可能会记录敏感信息，包括消息内容和 SSL 证书。尽管连接属性（例如密码）被屏蔽了，但在与您的组织外部共享它们之前，请查看此级别的日志以避免泄漏敏感信息。 |
| 日志文件夹结构 |
指示端口根据选定的时间间隔将日志文件夹中的文件分组。例如，Weekly 选项指示端口每周创建一个新的子文件夹，并将该周的所有日志存储在该文件夹中。空白设置告诉端口将所有日志直接保存在日志文件夹中。对于处理许多事务的端口，使用子文件夹有助于保持日志的有序性并提高性能。 |
| 保留消息副本 |
指示端口在日志目录中保存最新消息副本的切换。请注意，端口每个子文件夹只保留一个消息，并且端口在再次运行时会覆盖以前保存的消息。 |
;
export const MacrosExamples = ({extraMacros = []}) => <>
某些宏（例如 %Ext% 和 %ShortDate%）不需要参数，但其他宏则需要。所有带有参数的宏都使用以下语法：%Macro:argument%
以下是带有参数的宏的一些示例：
- %Header:headername%：其中
headername 是消息上消息头的名称。
- %Header:mycustomheader% 解析为输入消息上设置的
mycustomheader 消息头的值。
- %Header:ponum% 解析为输入消息上设置的
ponum 消息头的值。
- %RegexFilename:pattern%：其中
pattern 是正则表达式模式。例如，%RegexFilename:^([\w][A-Za-z]+)% 匹配并解析为文件名中的第一个单词，并且不区分大小写（test_file.xml 解析为 test）。
- %Vault:vaultitem%：其中
vaultitem 是 vault 中项目的名称。例如，%Vault:companyname% 解析为存储在保管库中的 companyname 项的值。
- %DateFormat:format%：其中
format 是可接受的日期格式（有关详细信息，请参阅 示例日期格式）。例如，%DateFormat:yyyy-MM-dd-HH-mm-ss-fff% 解析为文件上的日期和时间戳。
{extraMacros.filter(item => item.example).map(item => - {item.example}
)}
还可以创建更复杂的宏，如以下示例所示：
- 将多个宏组合在一个文件名中：
%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%%EXT%
- 包括宏之外的文本：
MyFile_%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%
- 在宏中包含文本：
%DateFormat:'DateProcessed-'yyyy-MM-dd_'TimeProcessed-'HH-mm-ss%
;
export const MacrosTable = ({siteName = "知行之桥", extraMacros = []}) => <>
在文件命名策略中使用宏可以提高组织效率和对数据的上下文理解。通过将宏合并到文件名中，可以动态地包含相关信息，例如标识符、时间戳和消息头信息，从而为每个文件提供有价值的上下文。这有助于确保文件名反映对组织重要的详细信息。
{siteName} 支持这些宏，它们都使用以下语法：%Macro%。
| 宏 | 描述 |
|---|
| ConnectorID | 替换为端口的 ConnectorID。 |
| Ext | 替换为端口当前正在处理的文件的文件扩展名。 |
| Filename | 替换为端口当前正在处理的文件的文件名（包括扩展名）。 |
| FilenameNoExt | 替换为端口当前正在处理的文件的文件名（不带扩展名）。 |
| MessageId | 计算端口输出的消息的 MessageId。 |
| RegexFilename:pattern | 将正则表达式模式应用于端口当前正在处理的文件的文件名。 |
| Header:headername | 替换为端口正在处理的当前消息的目标消息头（headername）的值。 |
| LongDate | 以常规格式计算系统的当前日期时间（例如，2024 年 1 月 24 日星期三）。 |
| ShortDate | 以 yyyy-MM-dd 格式计算系统的当前日期时间（例如 2024-01-24）。 |
| DateFormat:format | 以指定格式（format）计算系统的当前日期时间。有关可用的日期时间格式，请参阅 示例日期格式。 |
| Vault:vaultitem | 计算指定保管库项目的值。 |
{extraMacros.map(item =>
| {item.name} |
{item.description} |
)}
;
export const Performance = () => <>
与端口资源分配相关的设置。
| 设置 |
描述 |
| 最大工作线程数 |
此端口上处理文件时从线程池中消耗的最大工作线程数。如果设置，则会覆盖 高级设置 页面的 性能设置 部分的默认设置。 |
| 最大文件数 |
分配给端口的每个线程发送的最大文件数。如果设置，则会覆盖 高级设置 页面的 性能设置 部分的默认设置。 |
;
export const siteNameShort = "知行之桥";
export const siteName = "知行之桥";
SFTP 端口可向远程 SFTP 服务器上传和下载文件。
## 核心功能
* 基于 SSH 的安全文件传输，支持公钥和密码认证
* 高级认证功能，包括基于证书的客户端认证
* 支持中断上传和下载的断点续传功能
* 高级 SSH 加密算法和服务器指纹验证
* 支持连接池和临时文件处理，确保传输可靠
* 可选缓存功能，确保仅下载新增或更新的文件
## 概述
每个 SFTP 端口都会上传到指定文件夹，并从远程 SFTP 服务器上的一组文件夹中下载。
在 {siteNameShort} 工作流中到达 SFTP 端口的文件会上传到目标上传文件夹，在目标下载文件夹中找到的文件会下载并进入 {siteNameShort} 工作流。端口支持上传和下载过滤器，以便仅发送和接收指定的文件名和/或文件扩展名。
## 端口配置
本节包含所有可配置的端口属性。
### 设置选项卡
#### 主机配置
*与建立到远程 SFTP 主机的连接相关的设置。*
| 设置 | 说明 |
| --------- | ---------------------------- |
| **端口 ID** | 端口的静态唯一标识符。 |
| **端口类型** | 显示端口名称及其功能说明。 |
| **端口描述** | 可选字段，用于提供端口及其在工作流中作用的自由格式描述。 |
| **远程主机** | SFTP 服务器的主机名或 IP 地址。 |
| **远程端口** | 连接 SFTP 服务器所用的端口。 |
#### 客户端认证
*与向 SFTP 服务器进行认证相关的设置。*
| 设置 | 说明 |
| ----------- | ------------------------------------------------------------------------ |
| **认证模式** | 与 SFTP 服务器配合使用的认证类型。 |
| **用户** | 登录 SFTP 服务器所用的用户名。 |
| **密码** | 登录 SFTP 服务器所用的密码。 |
| **客户端证书** | 公钥认证期间要使用的包含私钥的证书。仅当**认证模式**设置为**公钥**或**多因素认证**时可用。也可以使用**创建证书**按钮创建新证书。 |
| **客户端证书密码** | 访问**客户端证书**所需的密码。 |
#### 服务器认证
*与验证 SFTP 服务器身份相关的设置。*
| 设置 | 说明 |
| --------- | ---------------------------------------------------------------- |
| **服务器指纹** | 标识 SFTP 服务器证书的指纹。也可以将其设置为包含服务器公钥的证书文件。测试连接时，端口会提示您接受/信任服务器提供的指纹。 |
#### 上传
*与将文件上传到 SFTP 服务器相关的设置。*
| 设置 | 说明 |
| -------- | ------------------ |
| **远程路径** | 端口处理的文件会上传到此远程文件夹。 |
#### 下载
*与从 SFTP 服务器下载相关的设置。*
| 设置 | 说明 |
| ------------- | ----------------------------------------- |
| **远程路径** | 从中下载文件的远程文件夹。使用逗号分隔列表可指定多个路径。 |
| **文件掩码** | 用于确定应下载**远程路径**中哪些文件的 Glob 模式（例如，\*.txt）。 |
| **删除文件（接收后）** | 选中此项可从 SFTP 服务器删除已成功下载的文件。 |
#### 缓存
*与多次下载之间缓存和比较文件相关的设置。*
| 设置 | 说明 |
| ---------- | ------------------------------------------------- |
| **文件大小比较** | 选中此项可记录已下载文件名和大小。除非文件大小与上次下载不同，否则会跳过以前下载过的文件。 |
| **时间戳比较** | 选中此项可记录已下载文件名和最后修改时间戳。除非时间戳与上次下载不同，否则会跳过以前下载过的文件。 |
启用缓存后，文件名不区分大小写。例如，端口无法区分 `TEST.TXT` 和 `test.txt`。
### 高级选项卡
#### 服务器命令
#### 高级设置
*先前类别中未包含的设置。*
| 设置 | 说明 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **连接池** | 选中此项可让端口使用连接池来访问和存储连接。这在服务器限制登录尝试频率的场景中很有用。 |
| **下载排除的扩展名** | 端口不应下载的文件扩展名逗号分隔列表。 |
| **下载排除的前缀** | 前缀的逗号分隔列表，指示端口不要下载以指定前缀开头的文件名。 |
| **最大下载文件数** | 一个轮询间隔内从 SFTP 服务器下载的最大文件数。设置为 **-1** 表示允许下载所有文件。 |
| **最小文件大小** | 要处理的最小文件大小（以字节为单位）。如果正在上传的文件小于指定大小，则最终状态为 **Skipped**。对于正在下载的文件，端口会添加一个事务日志条目，指示该文件因大小而被跳过。 |
| **最大文件大小** | 要处理的最大文件大小（以字节为单位）。如果正在上传的文件大于指定大小，则最终状态为 **Skipped**。对于正在下载的文件，端口会添加一个事务日志条目，指示该文件因大小而被跳过。 |
| **监控文件增长** | 选中此项可让应用程序在轮询间隔之间存储远程文件的文件大小，并且仅下载大小不再变化的文件。这可以防止端口下载服务器上仍在写入过程中的文件。 |
| **递归** | 选中此项可下载目标远程路径子文件夹中的文件。接收到的文件会保留子目录。 |
| **恢复下载** | 如果启用，当文件下载期间发生错误时，端口会存储已下载的文件部分，并在下次下载尝试时尝试下载文件的其余部分。 |
| **恢复上传** | 如果启用，当文件上传期间发生错误时，端口会记录已传输的字节数，并在下一次上传尝试时尝试上传文件的其余部分。 |
| **SSH 加密算法** | SSH 加密期间要使用的算法逗号分隔列表。默认情况下，启用所有算法。{siteNameShort} 支持以下算法：aes256-ctr, aes256-cbc, aes192-ctr, aes192-cbc, aes128-ctr, aes128-cbc, 3des-ctr, 3des-cbc, cast128-cbc, blowfish-cbc, arcfour, arcfour128, arcfour256, [aes128-gcm@openssh.com](mailto:aes128-gcm@openssh.com), [aes256-gcm@openssh.com](mailto:aes256-gcm@openssh.com), [chacha20-poly1305@openssh.com](mailto:chacha20-poly1305@openssh.com) |
| **本地文件方案** | 用于为端口输出的消息分配文件名的方案。可以在文件名中动态使用宏来包含标识符和时间戳等信息。有关更多信息，请参阅[宏](#宏)。 |
| **接收过滤器** | 用于确定应从远程存储下载哪些文件的 Glob 模式过滤器（例如，\*.txt）。可以使用负模式指示不应下载的文件（例如，-\*.tmp）。当需要多个**文件掩码**模式时使用此设置。多个模式可以用逗号分隔；除非找到完全匹配项，否则后面的过滤器优先级更高。 |
| **临时下载扩展名** | 传输过程中附加到下载文件的临时文件扩展名。 |
| **临时上传扩展名** | 传输过程中附加到上传文件的临时文件扩展名。 |
| **临时上传前缀** | 传输过程中添加到上传文件前面的临时文件前缀。 |
| **临时上传路径** | 上传文件所用的远程 SFTP 服务器临时路径。传输完成后，文件会移动到永久上传路径。 |
| **超时** | 端口在抛出超时错误之前等待连接响应的持续时间。 |
| **等待通道关闭** | 选中此项可让端口在断开连接前等待服务器关闭 SSH 通道。如果在注销序列期间发生超时，应禁用此设置。 |
| **使用 GMT 文件时间** | 选中此项可让端口将文件时间戳读取为 GMT 时间，并使用该时间与本地缓存进行比较。如果不选中此项，来自服务器的时间戳在用于时间比较前会转换为本地时间。 |
| **处理延迟** | 放入**事务**选项卡的文件延迟处理的时间（以秒为单位）。这是一个旧版设置。最佳实践是[使用 File 端口](../flows/designing-a-flow#interacting-with-the-local-file-system)管理本地文件系统，而不是使用此设置。 |
#### 代理设置
#### 消息
#### 日志
#### 其他设置
### 自动化选项卡
#### 自动化设置
*与端口自动处理文件相关的设置。*
| 设置 | 说明 |
| ------------ | ------------------------------------------------------------------------- |
| **上传** | 到达端口的文件是否应自动上传。 |
| **重试间隔** | 失败上传重试前等待的分钟数。 |
| **最大重试次数** | 端口处理输入文件的最大次数。是否成功以服务器成功确认为准。如果将其设置为 0，端口会无限期重试该文件。 |
| **下载** | 端口是否应自动轮询远程下载路径以下载文件。 |
| **间隔** | 自动下载尝试之间的间隔。 |
| **经过整点的分钟数** | 小时计划的分钟偏移量。仅当上述间隔设置为\_每小时\_时适用。例如，如果此值设置为 5，自动化服务会在 1:05、2:05、3:05 等时间下载。 |
| **时间** | 尝试发生的具体时间。仅当上述间隔设置为\_每天\_、\_每周\_或\_每月\_时适用。 |
| **日期** | 尝试发生的日期。仅当上述间隔设置为\_每周\_或\_每月\_时适用。 |
| **分钟** | 尝试下载前等待的分钟数。仅当上述间隔设置为\_分钟\_时适用。 |
| **Cron 表达式** | 表示 Cron 表达式的五段字符串，用于确定尝试发生的时间。仅当上述间隔设置为\_高级\_时适用。 |
#### 性能
### 警报选项卡
### SLA 选项卡
## 建立连接
连接到远程 SFTP 服务器需要以下设置：
* 远程主机
* 远程端口
* 认证模式
* 用户
* 密码或客户端证书/证书密码
* 服务器指纹
测试与服务器的连接时，端口会提示您接受/信任服务器公钥的指纹。
## 上传文件
SFTP 端口会从**事务**选项卡上传文件。如果端口中启用了**上传自动化**，文件会自动上传到 SFTP 服务器。
**远程路径**应设置为远程 SFTP 服务器上要上传文件的文件夹。登录服务器后，应用程序会切换到指定文件夹。
如果有任何文件无法上传，端口会在**重试间隔**分钟过后再次尝试发送。此过程会持续到达到**最大重试次数**设置，随后端口会引发错误，并且不再自动发送该文件。
## 下载文件
下载的文件会显示在端口的**事务**选项卡中，或传递到工作流中的下一个端口。如果端口中启用了**下载自动化**，文件会自动从 SFTP 服务器下载；也可以单击“事务”选项卡上的**接收**按钮手动下载。
**远程路径**应设置为远程 SFTP 服务器上要从中下载文件的文件夹。登录服务器后，应用程序会切换到指定文件夹。**文件掩码**属性会过滤文件，以便仅从服务器下载与 Glob 模式匹配的文件名。
可以使用**删除文件（下载后）**设置在文件成功下载后将其从远程服务器删除。在“事务”选项卡上，单击**接收**按钮以测试设置并从服务器检索匹配的文件。
## 子文件夹标头
如果在**高级**选项卡上选中**递归**，当 SFTP 端口从**远程路径**接收文件时：
* 接收到的文件消息会在其元数据中包含 Subfolder 标头。
* 此标头包含文件接收来源的子文件夹，该子文件夹相对于 SFTP 端口中的**远程路径**。
* 其他支持发送操作中 Subfolder 标头的端口也支持此标头。
发送文件时，如果发送到 SFTP 端口**上传路径**的消息上存在 Subfolder 标头：
* 文件会放置在 Subfolder 标头指定的子文件夹中，该子文件夹相对于 SFTP 端口中的**上传路径**。
* 如果权限允许，会创建该子文件夹。
## 宏
### 示例