> ## 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 Server 端口 > 知行之桥SFTP Server 端口的配置和使用指南，该端口用于定义向内置 SFTP 服务器进行认证的客户端配置文件。 每个 SFTP Server 端口都定义一个唯一的客户端配置文件，可用于向 知行之桥 SFTP Server 进行认证。 ## 核心功能 * 内置基于 SSH 的安全文件服务器，支持多用户访问 * 灵活的认证方式，包括密码、公钥以及 Windows/AD 集成（Windows/AD 集成仅在 .NET 版中可用） * 独立的用户目录，支持自定义文件夹结构和附加路径 * 高级安全特性，包括登录尝试锁定和 IP 限制 * 支持临时文件扩展名以及操作完成后的文件自动移动 ## 概述 知行之桥 SFTP Server 端口主要在[个人设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/profiles.md)页面中配置。然后，可以为每个应有权访问服务器的交易伙伴创建单独的 SFTP Server 端口。SFTP Server 端口定义交易伙伴的凭据（用户名、密码和/或公钥），并在服务器上提供唯一的主目录。 每个用户的主目录都包含一个 *Send* 文件夹（客户端可从中下载文件）和一个 *Receive* 文件夹（客户端可向其中上传文件）。您可以在[高级选项卡](#高级选项卡)上重命名这些文件夹。SFTP 客户端没有访问 SFTP 服务器根目录的权限，这意味着 SFTP 客户端连接后应始终 *cd* 到 Send 或 Receive 目录。 SFTP Server 还支持 Windows/AD 认证。有关详细信息，请参阅 [Windows 身份验证](#windows-身份验证)。 ### 视频资源 观看此短视频，了解如何配置 SFTP Server。 [//player.bilibili.com/player.html?aid=616154397\&bvid=BV1Vh4y1L7QK\&cid=1203415338\&p=1](//player.bilibili.com/player.html?aid=616154397\&bvid=BV1Vh4y1L7QK\&cid=1203415338\&p=1) ## 个人设置配置 在与各个 SFTP Server 端口建立连接之前，必须先配置 SFTP Server 个人设置。单击导航栏上的**个人设置**，然后单击 **SFTP Server** 选项卡。 ### 服务器配置 *服务器实现设置。* | 设置 | 说明 | | - | - | | **端口** | SFTP 服务器侦听传入连接的端口。 | | **服务器证书** | 标识服务器的证书。 | | **证书密码** | 访问服务器证书所需的密码。 | | **登录横幅** | SFTP 客户端连接到服务器时显示的横幅。 | | **根目录** | 服务器的根目录。根目录中会为各个客户端配置文件（每个已配置的 SFTP Server 端口）创建子文件夹。每个客户端配置文件都包含一个 Send 文件夹（客户端可从服务器下载文件）和一个 Receive 文件夹（客户端可向服务器上传文件）。 | | **Windows 身份验证** | 选中此项可使用 Windows 身份验证而不是 SFTP Server 端口配置来认证用户。仅在 知行之桥 的 [.NET 版](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/installation/windows-edition.md)中可用。有关更多信息，请参阅 [Windows 身份验证](#windows-身份验证)。 | | **安全组** | 用于授予服务器访问权限的 Windows 组名称。可以是本地计算机上的组，也可以是域上的组。仅当选中**使用 Windows 身份验证**时适用。 | #### 账户锁定 *与锁定服务器访问相关的可选设置。* | 设置 | 说明 | | - | - | | **失败次数** | 用户被锁定前允许的失败登录尝试次数。 | | **锁定时间** | 用户被锁定的时长（以分钟为单位）。 | | **检测周期** | 保留失败登录尝试记录的时长（以分钟为单位）。 | #### 受信任的 IP 地址 **可信 IP 地址** 部分提供以下功能：
功能描述
**添加**输入新的 IP 地址范围。
**编辑**修改选定的 IP 地址范围。
**删除**从列表中删除选定的 IP 地址范围。
以下限制适用于此功能： > [!NOTE] > > 为了让客户端能够访问服务器，需要有清晰的网络路径。在云环境中，可能需要在三个地方进行更改： > > • 云控制台中的网络规则。 > > • 托管应用程序的机器上的防火墙规则。例如，在使用 Amazon AMI 时，可以使用 *简单防火墙*（UFW）来允许所需端口上的流量。Linux 环境中的常见策略是将流量从低于 1024 的端口转发到高于 1024 的非标准端口，同时将应用程序配置为使用非标准端口。这可以避免与非 root 用户绑定到低于 1024 的端口相关的权限问题。 > > • [安全](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/security.md) 选项卡的 [网络访问](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/network-access.md) 部分。 #### 日志 *用于管理日志创建和存储的设置。*
设置 描述
**日志级别** 端口生成的日志的详细程度。当请求支持时，请将其设置为 **Debug**。
**日志轮换间隔** 创建新日志文件之前等待的天数。
**日志删除间隔** 删除旧日志文件之前等待的天数。
#### 其他设置 *其他设置用于特定用例。* | 设置 | 说明 | | - | - | | **空闲超时** | 用户在没有活动的情况下超时之前必须经过的时间（以秒为单位）。 | | **允许文件过滤器** | 用于确定 SFTP 服务器接受哪些文件的 Glob 模式。可以使用负模式指示不应下载的文件（例如，-\*.tmp）。多个文件类型用逗号分隔（例如，\*.x12,\*.edi）。 | | **加密算法** | 协商算法时，双方各自发送其支持或允许的全部算法列表。每个方向所选用的算法是发送方列表中*第一个*接收方也支持的算法，因此请按优先顺序以逗号分隔的列表提供多个算法。可用算法包括：`aes256-ctr`、`aes192-ctr`、`aes128-ctr`、`aes256-cbc`、`aes192-cbc`、`aes128-cbc`、`3des-ctr`、`3des-cbc`、`blowfish-cbc`、`arcfour256`、`arcfour128`、`arcfour`、`cast128-cbc`、`aes256-gcm@openssh.com`、`aes128-gcm@openssh.com` 和 `chacha20-poly1305@openssh.com`。此字段默认为空，表示启用除 `arcfour`、`arcfour128` 和 `arcfour256` 之外的所有加密算法。 | | **其他设置** | 允许你以分号分隔的列表配置隐藏的个人设置（例如 `setting1=value1;setting2=value2`）。正常的用例和功能不应需要使用这些设置。 | ## 端口配置 配置 SFTP Server 个人设置后，请在“工作流”页面上为每个交易伙伴创建并配置单独的 SFTP Server 端口。 ### 设置选项卡 #### 配置
设置 描述
**端口 Id** 端口的静态、唯一标识符。
**端口类型** 显示端口类型及其用途的描述。
**端口描述** 一个可选字段，用于提供端口及其在流中的角色的自由格式描述。
#### 服务器状态 *端口底层服务的当前状态。可用状态如下：*
状态 描述
**活动** 服务正在运行。
**非活动** 服务已配置，但当前未运行。
**未配置** 底层配置文件或服务尚未设置。
点击**查看 SFTP 服务器个人设置**链接可在新选项卡中打开对应个人设置。 #### 用户配置 *向本地 SFTP 服务器进行认证所用的凭据。* | 设置 | 说明 | | - | - | | **用户** | 登录本地 SFTP 服务器所用的用户名凭据。 | | **认证模式** | 与 SFTP 服务器配合使用的认证类型。以下字段会因认证模式而异。 | | **密码** | 登录 SFTP 服务器所用的密码凭据。 | | **客户端证书** | 当选择**公钥**认证时，对应于客户端所用私有证书的公钥证书。 | #### 权限 *与 Send 和 Receive 文件夹读/写权限相关的设置。* | 设置 | 说明 | | - | - | | **Send 目录权限** | 使用复选框设置 *Send* 目录的读/写权限。这是下载文件的位置。 | | **Receive 目录权限** | 使用复选框设置 *Receive* 目录的读/写权限。这是上传文件的位置。 | ### 高级选项卡 #### 本地文件夹 *与客户端上传和下载文件的文件夹相关的设置。可在此处重命名默认文件夹。* | 设置 | 说明 | | - | - | | **输入文件夹 (Send)** | 放入 Send 文件夹的文件可供客户端下载。 | | **输出文件夹 (Receive)** | 客户端上传的文件应放入 Receive 文件夹。文件会保留在 Receive 文件夹中，或传递到工作流中的下一个端口。 | #### 附加路径 SFTP Server 端口允许公开输入和输出文件夹之外的路径。要配置附加路径，请按照以下步骤操作： 1. 使用**路径**字段指定应公开的附加路径。路径值相对于“个人设置”页面上定义的**根目录**。 2. 使用**读取**和**写入**复选框设置附加路径的权限。 3. 如果需要更多路径，请单击**新建**并对每个路径重复这些步骤。 例如，如果**根目录**设置为 `/var/opt/arc/sftpserver`，并添加了 `MyAdditionalPath` 附加路径，则它会映射到磁盘上的 `/var/opt/arc/sftpserver/MyAdditionalPath` 路径。 #### 高级设置 *先前类别中未包含的设置。* | 设置 | 说明 | | - | - | | **主目录** | 用户登录后的初始服务器路径。可以使用端口主目录、Send 或 Receive 文件夹，或已定义的[附加路径](#附加路径)。详情请参阅[主目录](#主目录)。 | | **允许文件过滤器** | 用于确定 SFTP 服务器接受哪些文件的 Glob 模式。可以使用负模式指示不应下载的文件（例如，-\*.tmp）。多个文件类型用逗号分隔（例如，\*.x12,\*.edi）。覆盖“个人设置”页面“服务器配置”部分中的**允许文件过滤器**选项。 | | **发送后移动文件** | 指定 *Send* 文件夹中的文件在被客户端下载后是否应移动到 *Sent* 文件夹。 | | **临时接收扩展名** | 具有匹配扩展名的文件不会记录在 Receive 表中，并且在重命名之前不会触发**接收后**事件。请提供逗号分隔的扩展名列表。 | | **超时** | 服务器在抛出超时错误之前等待连接响应的时长（以秒为单位）。 | | **保存 Subfolder** | 选中此项可向已接收的消息添加 *Subfolder* 标头。它表示相对于本地文件夹或附加路径的路径。 | | **断开连接时完成处理** | 选中后，将文件最终处理延迟到客户端断开连接，以便客户端执行重命名等额外操作。 | | **本地文件方案** | 用于为端口输出的消息分配文件名的方案。可以在文件名中动态使用宏来包含标识符和时间戳等信息。有关更多信息，请参阅[宏](#宏)。 | #### 消息 *消息设置确定端口如何搜索消息并在处理后管理它们。* **注意：**以下设置已弃用，默认处于隐藏状态。只有先前已启用这些设置或将其配置为非默认值的端口才会显示它们。若要保留成功处理的文件副本，请在工作流中右键单击该端口，选择**显示成功路径**，然后将成功路径连接到 [File 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/file.md)。
设置描述
**保存到已发送文件夹**（已弃用） 将端口处理的文件复制到 Sent 文件夹。默认禁用。保存到 Sent 文件夹中的文件不受[静态加密](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/encryption-at-rest.md)保护。
**已发送文件夹方案**（已弃用） 按所选时间间隔对 **Sent** 文件夹中的文件进行分组。仅在启用**保存到已发送文件夹**时适用。
#### 日志 *用于管理日志创建和存储的设置。*
设置 描述
**日志级别** 指定要记录在端口日志目录中的信息类型：
  • **None** - 不创建任何日志。
  • **Error** - 仅当端口遇到错误时才创建日志。
  • **Warning** - 仅当端口发出警告时才创建日志。
  • **Info** - 记录工作流的一般信息，包括任何错误和警告（如果适用）。
  • **Debug** - 记录成功和失败工作流的详细调试信息。
  • **Trace** - 记录成功和失败工作流的详细跟踪信息。
\*\*请注意：\*\***Debug** 和 **Trace** 级别的日志可能会记录敏感信息，包括消息内容和 SSL 证书。尽管连接属性（例如密码）被屏蔽了，但在与您的组织外部共享它们之前，请查看此级别的日志以避免泄漏敏感信息。
**日志文件夹结构** 指示端口根据选定的时间间隔将日志文件夹中的文件分组。例如，**Weekly** 选项指示端口每周创建一个新的子文件夹，并将该周的所有日志存储在该文件夹中。空白设置告诉端口将所有日志直接保存在日志文件夹中。对于处理许多事务的端口，使用子文件夹有助于保持日志的有序性并提高性能。
**保留消息副本** 指示端口在日志目录中保存最新消息副本的切换。请注意，端口每个子文件夹只保留一个消息，并且端口在再次运行时会覆盖以前保存的消息。
#### 其他设置 *特殊设置适用于特定用例。*
设置 描述
**其他设置** 允许在以分号分隔的列表中配置隐藏的端口设置，例如 `setting1=value1;setting2=value2`。正常的端口用例和功能不需要使用这些设置。
### 警报选项卡 *与配置通知相关的设置。* 在执行服务级别协议 (SLA) 之前，需要设置电子邮件通知以接收通知。默认情况下，知行之桥 使用 [通知](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/alerts.md) 选项卡上的全局设置。要为此端口使用其他设置，请启用 **覆盖全局设置**。 默认情况下，错误通知处于启用状态，这意味着每当出现错误时都会发送电子邮件。要关闭错误通知，请取消选中 **启用** 复选框。 输入 **主题**（必填）。勾选**允许在主题中使用 ArcScript**，即可在**主题**字段中使用 ArcScript。选中后会显示 **ArcScript 编辑器**按钮（![ArcScript 编辑器按钮](https://docs.kasoftware.com/26.4/images/rest_arcscript_editor.png)）。 （可选）输入以逗号分隔的**收件人**电子邮件地址列表。 ### SLA 选项卡 *与配置服务级别协议 (SLA) 相关的设置。* SLA 允许配置预期流程中端口发送或接收的数据量，并设置预期达到该数据量的时间范围。当 SLA 未达到时，知行之桥 会发送电子邮件警告用户，并将 SLA 标记为 *存在风险*，这意味着如果 SLA 未能尽快达到，则会被标记为 *已违反*。这让用户有机会介入并确定 SLA 未达到的原因，并采取适当的措施。如果在风险时间段结束时仍未达到 SLA，则会将 SLA 标记为已违反，并再次通知用户。 SLA 转换为 *存在风险* 或 *已违反* 状态时，也会写入[应用程序日志](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/activity.md#应用程序日志)，这意味着应用性能监控 (APM) 和日志采集工具也可以针对这些状态发出警报。 要定义 SLA，请启用 **预期数据量**，然后点击 **设置** 选项卡。 ![SLA Empty](https://docs.kasoftware.com/26.4/images/sla_empty.png) 以下示例显示了为端口配置的 SLA，该端口预计在周一至周五每天接收 1000 个文件。如果尚未收到 1000 个文件，则会在时间段结束前 1 小时发送风险通知。 ![SLA Configuration Example](https://docs.kasoftware.com/26.4/images/sla_defined.png) > [!NOTE] > > 如果有必要，可以关闭 SLA 通知。这在维护窗口期间非常有用。点击导航栏上的 **设置**，然后跳转到 **通知 > 通用通知**。点击平板和铅笔图标进行编辑，并取消勾选 **SLA 通知** 设置。 ## 建立连接 每个 SFTP Server 端口都代表单个交易伙伴的连接参数。交易伙伴应使用[个人设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/profiles.md)页面中的服务器设置（端口、服务器证书等）以及专用 SFTP Server 端口中的认证设置（用户和密码）连接到 SFTP 服务器。 每个交易伙伴都有一对 *Send* 和 *Receive* 目录，它们是根目录的子文件夹。伙伴从 Send 文件夹下载文件，并将文件上传到 Receive 文件夹。不允许客户端从根目录上传或下载文件。 ## 主目录 **主目录**设置控制客户端登录后的初始目录。可在端口的**高级**选项卡中配置。迁移自允许配置落地目录的 SFTP/FTP 软件，或客户端不会执行 `cd` 命令时，此设置尤其有用。 * **留空（默认）**：客户端进入端口主目录 `/`。 * **设置路径**：客户端登录后进入指定服务器路径；未切换目录的上传、下载和列出操作均在该目录中执行。 主目录必须是相对于端口[个人设置](#个人设置配置)中**根目录**解析的服务器路径，并匹配已配置的位置。有效位置包括： * `/`：端口主目录 * `//Send` * `//Receive` * 任意已定义的[附加路径](#附加路径)，例如 `/Staging` 服务器根目录 `/` 不是有效主目录。输入会被标准化，因此 `Receive`、`/Receive`、`\Receive` 和 `/Receive/` 被视为同一路径。保存时会验证路径；不存在或已删除的附加路径会被拒绝。 > [!NOTE] > > 主目录只设置登录时的初始目录，并非 chroot 或隔离区。客户端之后可访问的目录仍由[权限设置](#权限)控制。 ### 主目录与 SFTP 客户端远程路径 | SFTP 服务器主目录 | SFTP 客户端远程路径 | 最终工作目录 | | - | - | - | | *（空）* | *（空）* | `/` | | *（空）* | `/` | 权限错误 | | *（空）* | `Receive` | `//Receive` | | `/Test` | *（空）* | `/Test` | | `/Test` | `/` | 权限错误 | | `/Test` | `/` | `/` | ## Windows 身份验证 在“个人设置”选项卡的[服务器配置](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/sftp-server.md#服务器配置)部分启用 Windows 身份验证时，不需要单独的 SFTP Server 端口来授予对 SFTP Server 的登录访问权限。相反，您需要指定应被授予服务器访问权限的 Windows **安全组**名称。 启用 Windows 身份验证时，**根目录**个人设置支持 %User% 和 %Domain% 宏，用于为安全组中的不同用户建立不同的根目录。因此，启用 Windows 身份验证时，允许用户在根目录中上传/下载文件（使用 SFTP Server 端口进行认证时并非如此）。 文件上传到特定用户的文件夹后，可以使用 [File 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/file.md)将其输入到 知行之桥 工作流中。 ## 宏 在文件命名策略中使用宏可以提高组织效率和对数据的上下文理解。通过将宏合并到文件名中，可以动态地包含相关信息，例如标识符、时间戳和消息头信息，从而为每个文件提供有价值的上下文。这有助于确保文件名反映对组织重要的详细信息。 知行之桥 支持这些宏，它们都使用以下语法：`%Macro%`。
宏描述
ConnectorID替换为端口的 ConnectorID。
ConnectorName替换为端口名称。可用于在文件名或路径中包含连接名称，例如按生成备份文件的数据库连接标记文件。
Ext替换为端口当前正在处理的文件的文件扩展名。
Filename替换为端口当前正在处理的文件的文件名（包括扩展名）。
FilenameNoExt替换为端口当前正在处理的文件的文件名（不带扩展名）。
MessageId计算端口输出的消息的 MessageId。
RegexFilename:*pattern*将正则表达式模式应用于端口当前正在处理的文件的文件名。
Header:*headername*替换为端口正在处理的当前消息的目标消息头（`headername`）的值。
LongDate以常规格式计算系统的当前日期时间（例如，2024 年 1 月 24 日星期三）。
ShortDate以 yyyy-MM-dd 格式计算系统的当前日期时间（例如 2024-01-24）。
DateFormat:*format*以指定格式（`format`）计算系统的当前日期时间。有关可用的日期时间格式，请参阅 [示例日期格式](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#date-formats-with-literal-characters)。
Vault:*vaultitem*计算指定保管库项目的值。
### 示例 某些宏（例如 %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](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/global-settings-vault.md) 中项目的名称。例如，`%Vault:companyname%` 解析为存储在保管库中的 `companyname` 项的值。
  • %DateFormat:format%：其中 `format` 是可接受的日期格式（有关详细信息，请参阅 [示例日期格式](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#sample-date-formats)）。例如，`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%` 解析为文件上的日期和时间戳。
还可以创建更复杂的宏，如以下示例所示：
  • 将多个宏组合在一个文件名中：`%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%`
## 常见错误 ### 错误：Could not bind server socket: Permission denied. **原因** 尝试连接到 SFTP 服务器时，如果托管 知行之桥 的进程没有足够权限在指定端口上建立侦听器，就可能出现此错误。请注意，在某些情况下（例如 Linux 环境和在 Amazon AMI 中运行的托管实例），禁止访问 1024 以下的端口。 **解决方案** 选择其他端口，或将托管 知行之桥 的进程身份更改为具有绑定到该端口权限的身份。 知行之桥 的 Amazon AMI 托管版本使用 Ubuntu 操作系统，因此 知行软件 建议您使用 *Uncomplicated Firewall* (UFW) 管理端口权限问题。例如，在 知行之桥 中将 SFTP Server 设置为在端口 8022 上运行，并使用 UFW 在操作系统级别将端口 22 转发到 8022，如下所示： ``` ufw allow 22/tcp ufw allow 8022/tcp echo " *nat :PREROUTING ACCEPT [0:0] -A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 8022 COMMIT" >> /etc/ufw/before.rules ``` 如果您的环境使用其他 Linux 操作系统，知行软件 建议您绑定到受限范围以上的端口（例如，将 8022 用于 SFTP 流量），并使用 `iptables` 将所需端口上的传入请求路由到允许的端口： `iptables -t nat -I PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 8022` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.