配置文件

本节介绍如何通过静态配置文件来配置连接器。如果您更喜欢通过代码配置连接器，或者需要对配置进行动态更改，请参考通过代码配置.

CKFinder WebApp 使用两个配置文件

Web.config – ASP.NET Web 应用程序的主要设置和配置文件。它包含一个包含连接器配置的部分，在本节文章中解释。
config.js – 一个可选的客户端配置的文件，在 API 文档文章中关于设置 JavaScript 配置解释。

连接器配置

以下选项可以在 Web.config 文件的 <ckfinder /> 部分中设置

属性名称	类型	描述
`cacheControlSeconds`	`整数`	配置各种 CKFinder 组件的缓存生命周期。
`checkDoubleExtension`	`布尔值`	是否允许具有双文件扩展名的文件。
`checkSizeAfterScaling`	`布尔值`	指示上传图像的文件大小必须在缩放后（如果需要）针对资源配置中定义的 `maxSize` 设置进行检查。否则，大小会在上传后立即检查。
`disallowUnsafeCharacters`	`布尔值`	禁止创建名称包含 IIS Web 服务器上不安全的字符的文件夹和上传文件。由于 IIS 和经典 ASP 的安全问题，建议启用此选项。
`enableCsrfProtection`	`布尔值`	在连接器中启用 CSRF 保护。默认的 CSRF 保护机制基于双提交 Cookie.
`enableVerboseLogging`	`布尔值`	是否启用异常的详细日志记录。
`overwriteOnUpload`	`布尔值`	更改 CKFinder 上传与文件夹中已存在的文件同名的文件时的默认行为。如果启用，则不会自动重命名文件，而是会覆盖现有文件。
`secureImageUploads`	`布尔值`	是否在上传图像文件时执行额外的检查。如果设置为 `true`，则连接器将不接受具有非有效图像的图像扩展名的文件。

此示例演示了一个示例 <license /> 部分

<ckfinder overwriteOnUpload="false"
checkDoubleExtension="true"
disallowUnsafeCharacters="false"
secureImageUploads="true"
checkSizeAfterScaling="true"
enableVerboseLogging="true">
    <!--
连接器的配置子部分：图像、缩略图、后端等。
    -->
</ckfinder>

许可证

<license /> 子部分定义了 CKFinder 许可证。它有两个属性

属性名称	类型	描述
`name`	`字符串`	许可证名称。
`key`	`字符串`	许可证密钥。

本节不是必需的，但是，如果它不存在或任何属性丢失或无效，CKFinder 将以演示模式运行。

此示例演示了一个示例 <license /> 部分

图像

<images /> 子部分定义了图像的设置。它具有以下属性

属性名称	类型	描述
`maxHeight`	`整数`	上传图像的最大高度。如果图像大小大于指定的大小，则图像将调整为定义的尺寸。
`maxWidth`	`整数`	上传图像的最大宽度。如果图像大小大于指定的大小，则图像将调整为定义的尺寸。
`quality`	`整数`	创建图像的质量，范围从 1 到 100。质量值越小，调整大小后的图像尺寸越小。请注意，最佳质量值约为 80-90。

<images /> 子部分可能包含 <sizes /> 元素，该元素包含一系列 <size /> 元素，这些元素定义了可以从 CKFinder 中轻松选择并传递到外部应用程序（例如 CKEditor）的图像大小，而无需手动调整图像大小。

注意：如果 maxWidth 或 maxHeight 的值为 0，则禁用限制。

<size /> 元素具有以下属性

属性名称	类型	描述
`height`	`整数`	图像的高度边界。
`name`	`字符串`	用作“选择缩略图”上下文菜单中条目的标签。特定条目的翻译标签取自语言文件，例如 `small` 将翻译为 `lang.image["small"]`。如果当前语言没有设置翻译密钥，则使用英文版本。如果找不到英文版本，则使用未翻译的字符串（第一个字母设置为大写）。
`quality`	`整数`	调整大小后的图像质量，范围从 1 到 100。
`width`	`整数`	图像的宽度边界。

可以包含在 <images /> 子部分中的最后一个元素是 <threshold />。这是一个低级内部配置选项，CKFinder 在应用程序的各个部分中显示图像预览时使用它。如果 CKFinder 在其缓存中有一个已调整大小的图像版本，并且图像的大小几乎与请求的大小相同（在定义的阈值内），CKFinder 将使用该图像。

此选项通过以下方式提高性能：

避免拥有太多具有几乎相同大小的图像副本。
避免每次预览时都缩放图像。

<threshold /> 元素具有以下属性

属性名称	类型	描述
`percent`	`整数`	缓存图像和请求图像之间宽度和高度的最大差异百分比。
`pixels`	`整数`	缓存图像和请求图像之间宽度和高度的最大差异像素。

此示例演示了一个示例 <images /> 子部分

<images maxWidth="1280" maxHeight="720" quality="80">
<sizes>
<size name="small" width="480" height="320" quality="80" />
<size name="medium" width="600" height="480" quality="80" />
<size name="large" width="800" height="600" quality="80" />
</sizes>
<threshold pixels="80" percent="10" />
</images>

缩略图

<thumbnails /> 子部分定义了缩略图的设置。它具有以下属性

属性名称	类型	描述
`fileSystem`	`字符串`	用于缩略图的文件系统的名称。它必须在 `<fileSystems />` 部分中定义。
`folder`	`字符串`	存储缩略图的路径和文件夹名称。

<thumbnails /> 子部分应包含 <sizes /> 元素，该元素包含一系列 <size /> 元素，这些元素定义了允许创建的缩略图大小。

<size /> 元素具有以下属性

属性名称	类型	描述
`height`	`整数`	缩略图的高度边界。
`quality`	`整数`	缩略图的质量，范围从 1 到 100。
`width`	`整数`	缩略图的宽度边界。

此示例演示了一个示例 <thumbnails /> 部分

<thumbnails folder="__thumbs" fileSystem="default">
<sizes>
<size width="150" height="150" quality="90" />
<size width="300" height="300" quality="80" />
</sizes>
</thumbnails>

后端

<backends /> 子部分定义了连接器的文件系统后端。

每个文件系统都由一个 <backends /> 元素表示，该元素具有以下属性

属性名称	类型	描述
`name`	`字符串`	文件系统的名称。必须是唯一的。
`adapter`	`字符串`	文件系统的类型。必须等于在 FileSystemFactory 中注册的值之一。对于 WebApp，可能的值为 `local`、`dropbox`、`azure`、`s3` 和 `ftp`。
`useProxyCommand`	`布尔值`	存储在此文件系统中的文件的链接是否应该指向 `Proxy` 命令。

<backends /> 元素可能包含一系列 <option /> 元素，这些元素定义了特定于文件系统的选项。

每个 <option /> 元素都必须定义以下属性

属性名称	类型	描述
`name`	`字符串`	选项的名称。
`value`	`字符串`	选项的值。

此示例演示了一个示例 <fileSystems /> 部分

<backends>
<backend name="default" adapter="local" useProxyCommand="true">
<option name="root" value="userfiles" />
</backend>
<backend name="remote" adapter="dropbox">
<option name="accessToken" value="ACCESSTOKEN" />
<option name="root" value="ckfinder_files" />
</backend>
</backends>

本地后端

类型为 local 的本地文件系统后端。

选项名称	描述
`root`	本地文件系统上根文件夹的路径。
`baseUrl` 可选	用于直接访问 CKFinder 文件的基 URL。此 URL 必须与 CKFinder 用户文件存储的目录相对应。

此示例演示了一个示例本地后端

<backend name="myBackend" adapter="local">
<option name="root" value="C:\Files" />
<option name="baseUrl" value="http://example.com/" />
</backend>

Dropbox 后端

类型为 dropbox 的 Dropbox 后端。此后端允许您将 Dropbox 帐户中的任何现有文件夹附加到 CKFinder。

选项名称	描述
`root` 可选	Dropbox 帐户中根文件夹的路径。
`accessToken`	Dropbox 帐户的访问令牌。
`baseUrl` 可选	用于直接访问 Dropbox 上的 CKFinder 文件的基 URL（如果您使用的是公共文件夹，则可以找到所有公共文件的通用前缀）。

此示例演示了一个示例 Dropbox 后端

<backend name="myBackend" adapter="dropbox">
<option name="root" value="Files" />
<option name="accessToken" value="YOUR-ACCESS-TOKEN" />
<option name="baseUrl" value="http://example.com/" />
</backend>

要将 CKFinder 与 Dropbox 一起使用，您需要为您的 Dropbox 帐户生成一个应用程序令牌。要生成令牌，请访问 Dropbox App Console 并创建一个新应用程序，如以下屏幕截图所示

创建 Dropbox 应用程序令牌

请注意，在创建应用程序时，您可以定义此应用程序可访问的文件夹。在上面的示例中，允许访问整个 Dropbox 帐户。

Azure 后端

类型为 azure 的 Azure 存储后端。此后端允许您将 Azure 存储附加到 CKFinder。

选项名称	描述
`account`	帐户的名称。
`container`	容器的名称。
`key`	帐户的访问密钥。
`root` 可选	Azure 存储帐户中容器中根文件夹的路径。
`baseUrl` 可选	用于直接访问 Azure 上的 CKFinder 文件的基 URL。

此示例演示了一个示例 Azure 存储后端

<backend name="myBackend" adapter="azure">
<option name="root" value="Files" />
<option name="account" value="YOUR-ACCOUNT-NAME" />
<option name="key" value="YOUR-ACCESS-KEY" />
<option name="container" value="CKFinderContainer" />
<option name="baseUrl" value="http://example.com/" />
</backend>

Amazon S3 后端

一个类型为 s3 的 Amazon S3 后端。此后端允许您将 Amazon S3 存储连接到 CKFinder。

选项名称	描述
`bucket`	存储桶的名称。
`key`	帐户的访问密钥。
`secret`	您帐户的密钥。
`region`	S3 区域的名称。有关区域及其端点的列表，请参阅 http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
`root` 可选	Amazon S3 帐户中存储桶中根文件夹的路径。
`baseUrl` 可选	用于直接访问 Amazon S3 上 CKFinder 文件的基 URL（如果文件是公开可见的，您可以找到它们的公共前缀，例如 http://s3-eu-west-1.amazonaws.com/bucket）。
`signatureVersion` 可选	区域的签名版本（默认设置为 `4`）。有关区域及其支持的签名版本的列表，请参阅 http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region.

此示例演示了一个 Amazon S3 后端样本

<backend name="myBackend" adapter="s3">
<option name="root" value="Files" />
<option name="secret" value="YOUR-SECRET" />
<option name="key" value="YOUR-KEY" />
<option name="bucket" value="CKFinderBucket" />
<option name="region" value="eu-west-1" />
<option name="baseUrl" value="http://example.com/" />
</backend>

FTP 后端

一个类型为 ftp 的 FTP 后端。此后端允许您在 CKFinder 中从 FTP 服务器获取文件。

选项名称	描述
`host`	FTP 服务器的主机名。
`port`	FTP 服务器的端口号。
`userName`	连接到 FTP 服务器的用户名。
`password`	连接到 FTP 服务器的密码。
`root` 可选	FTP 服务器中根文件夹的路径。
`ftpEncryption` 可选	要使用的加密模式。有效值为：none、ssl、tls。
`baseUrl` 可选	用于直接访问 FTP 服务器上 CKFinder 文件的基 URL。

此示例演示了一个 FTP 后端样本

<backend name="myBackend" adapter="ftp">
<option name="root" value="Files" />
<option name="host" value="localhost" />
<option name="port" value="21" />
<option name="userName" value="ckfinder" />
<option name="password" value="secret*password" />
<option name="ftpEncryption" value="tls" />
<option name="baseUrl" value="http://example.com/" />
</backend>

资源类型

资源类型不过是一种将文件分组到不同路径下的方式，每个路径都有不同的配置设置。资源类型在 CKFinder 中表示为“根文件夹”。每个资源类型可以使用不同的后端。

默认情况下，CKFinder 配置文件附带两个配置好的样本资源类型：Files 和 Images。对配置的资源类型数量没有限制。您可以更改或删除默认资源类型，但请确保至少配置一种资源类型。

<resourceTypes /> 子部分定义了可用的资源类型。每个资源类型由一个 <resourceType /> 元素表示，该元素具有以下属性

属性名称	类型	描述
`name`	`字符串`	资源类型的机器友好的名称，将用于 CKFinder UI 和服务器连接器之间的通信。必须是唯一的。
`backend`	`字符串`	后端的名称。它必须在 `<backends />` 部分中定义。
`folder`	`字符串`	文件系统上文件的路径。
`allowedExtensions`	`字符串`	您希望允许使用 CKFinder 上传的文件扩展名。`NO_EXT` 值可用于没有扩展名的文件。
`deniedExtensions`	`字符串`	您不希望使用 CKFinder 上传的文件扩展名。仅当 `allowedExtensions` 留空时才应设置它。`NO_EXT` 值可用于没有扩展名的文件。
`maxSize`	`整数`	允许上传的最大文件大小（以字节为单位）。
`lazyLoad`	`布尔值`	如果设置为 `true`，则 Init 命令不会检查资源类型是否包含子文件夹。此选项对于远程后端特别有用，因为 `Init` 命令将更快执行，因此 CKFinder 的启动速度也将更快。建议将其设置为 `true` 以用于远程后端。

重要提示：建议始终使用 allowedExtensions 设置，而不是 deniedExtensions。如果您将 allowedExtensions 留空并向 deniedExtensions 列表添加一个扩展名，例如 pdf，则设置将允许上传除 pdf 扩展名文件（例如 .php 或 .exe 文件）以外的所有其他文件。

此示例演示了一个 <resourceTypes /> 子部分样本

<resourceTypes>
<resourceType name="Files" folder="files" maxSize="1000000" allowedExtensions="doc,txt,zip" backend="default" />
<resourceType name="Images" folder="images" allowedExtensions="bmp,gif,jpeg,jpg,png" backend="default" />
</resourceTypes>

访问控制

访问控制列表 (ACL) 是一项功能，它允许您的用户获得不同的权限来使用 CKFinder 文件夹和文件。默认设置允许每个用户对所有选项具有完全权限。

<accessControl /> 子部分定义了 ACL。每个规则由一个 <rule /> 元素表示，该元素具有以下属性

属性名称	类型	描述
`resourceType`	`字符串`	资源类型的名称掩码（请参阅资源类型）。
`role`	`字符串`	提供 ACL 设置的用户的角色掩码。
`fileDelete` 可选	`enumeration`	用户是否可以删除文件。可能的值为：`allow`、`deny` 和 `inherit`。
`fileRename` 可选	`enumeration`	用户是否可以重命名文件。可能的值为：`allow`、`deny` 和 `inherit`。
`fileUpload` 可选	`enumeration`	用户是否可以创建（例如上传）文件。可能的值为：`allow`、`deny` 和 `inherit`。
`fileView` 可选	`enumeration`	用户是否可以查看文件内容。可能的值为：`allow`、`deny` 和 `inherit`。
`folder`	`字符串`	将使用限制的文件夹的路径掩码。
`folderCreate` 可选	`enumeration`	用户是否可以创建文件夹。可能的值为：`allow`、`deny` 和 `inherit`。
`folderDelete` 可选	`enumeration`	用户是否可以删除文件夹。可能的值为：`allow`、`deny` 和 `inherit`。
`folderRename` 可选	`enumeration`	用户是否可以重命名文件夹。可能的值为：`allow`、`deny` 和 `inherit`。
`folderView` 可选	`enumeration`	用户是否可以查看文件列表。可能的值为：`allow`、`deny` 和 `inherit`。
`imageResize` 可选	`enumeration`	选择图像时，用户是否可以将其调整为配置文件中预定义的尺寸。可能的值为：`allow`、`deny` 和 `inherit`。
`imageResizeCustom` 可选	`enumeration`	选择图像时，用户是否可以将其调整为任何尺寸。可能的值为：`allow`、`deny` 和 `inherit`。

注意：imageResize 和 imageResizeCustom 属性对应于“选择调整大小”功能，该功能会自动创建所选图像的调整大小版本。它们不会影响在 CKFinder 的图像编辑器（“编辑”功能）中修改的图像的调整大小。

可以定义多个 ACL 条目。子文件夹从其父级的定义继承其默认设置。

关于掩码

掩码可能包含

星号 (*) 字符，它将匹配零个或多个字符。
问号 (?) 字符，它将完全匹配一个字符。

文件夹的示例掩码

掩码	`/path/to/folder`	`/another path/to/folder`	`/path/ o/folder`	`/path/to/nowhere`
`/path/to/folder`	是	否	否	否
`*/to/folder`	是	是	否	否
`/path/?o/folder`	是	否	是	否
`/path/??/*`	是	否	是	是

此示例演示了一个 <accessControl /> 部分样本

<accessControl>
<rule role="*"
resourceType="*"
folder="*"
folderView="allow"
folderCreate="allow"
folderRename="allow"
folderDelete="allow"
fileView="allow"
fileUpload="allow"
fileRename="allow"
fileDelete="allow"
imageResize="allow"
imageResizeCustom="allow" />
<rule role="User"
resourceType="Files"
folder="/"
folderView="allow"
folderCreate="allow"
folderRename="allow"
folderDelete="deny"
fileView="allow"
fileUpload="deny"
fileRename="deny"
fileDelete="deny" />
</accessControl>

HTML 扩展名

可能允许在数据的前 1kB 中使用 HTML 代码的文件类型。

有时在上传文件时，可能会发生文件在其数据的前几千字节中包含 HTML 代码。仅当文件扩展名在 htmlExtensions 中指定时，CKFinder 才会上传包含 HTML 代码的文件。

请注意，此功能仅执行一组非常基本的检查以检测文件内容的前 1kB 中的类似 HTML 的数据，以保护用户免受例如意外上传包含 HTML 内容且扩展名错误的文件的影响。

<htmlExtensions /> 子部分包含 <extension /> 元素的集合，这些元素具有以下属性

属性名称	类型	描述
`name`	`字符串`	允许包含 `HTML` 代码的文件的扩展名。

此示例演示了一个 <htmlExtensions /> 子部分样本

<htmlExtensions>
<extension name="html" />
<extension name="htm" />
<extension name="xml" />
<extension name="js" />
</htmlExtensions>

隐藏的文件夹

不应在 CKFinder 中显示的文件夹，无论其位置如何。

<hideFolders /> 子部分包含 <folder /> 元素的集合，这些元素具有以下属性

属性名称	类型	描述
`name`	`字符串`	要隐藏的文件夹名称的掩码。

此示例演示了一个 <hideFolders /> 子部分样本

<hideFolders>
<folder name=".*" />
<folder name="__thumbs" />
</hideFolders>

隐藏的文件

不应在 CKFinder 中显示的文件，无论其位置如何。

<hideFiles /> 子部分包含 <file /> 元素的集合，这些元素具有以下属性

属性名称	类型	描述
`name`	`字符串`	要隐藏的文件名称的掩码。

此示例演示了一个 <hideFiles /> 子部分样本

<hideFiles>
<folder name=".*" />
<folder name="Changelog.txt" />
</hideFiles>

插件

<plugins /> 子部分定义了要在连接器中启用的插件。

每个插件都用一个<plugin />元素表示，该元素具有以下属性

属性名称	类型	描述
`name`	`字符串`	插件的名称。它还定义了插件所在的文件夹名称。

<plugin />元素可以包含一个<option />元素集合，这些元素定义特定于插件的选项。

每个 <option /> 元素都必须定义以下属性

属性名称	类型	描述
`name`	`字符串`	选项的名称。
`value`	`字符串`	选项的值。

此示例演示了一个示例<plugins />子节

<plugins>
<plugin name="FirstPlugin">
<option name="pluginOption" value="pluginValue" />
<option name="pluginOptionCollection" value="collectionValue1" />
<option name="pluginOptionCollection" value="collectionValue2" />
<option name="pluginOptionCollection" value="collectionValue3" />
</plugin>
<plugin name="SecondPlugin" />
</plugins>

角色配置

默认情况下，连接器从.AspNet.ApplicationCookiecookie中传递的声明中提取角色。连接器本身不执行任何身份验证，由另一个应用程序来对用户进行身份验证并设置cookie。

注意：在 IIS 下，身份验证 cookie 使用 MachineKey.Encrypt 方法进行加密。这意味着 CKFinder 应该托管在与执行身份验证的应用程序相同的机器上。或者，机器密钥可以在 Web.config 中设置。有关更多信息，请参阅 MSDN。

要更改角色提取方法，请实现 IAuthenticator 接口，并使用 ConnectorBuilder.SetAuthenticator 方法将其分配给连接器。

仅 WebApp 配置选项

示例项目 WebApp 包含 Web.config 文件的 <appSettings /> 部分中存在的两个附加选项

ckfinderAllowedRole – 允许访问 CKFinder 的用户角色掩码。
ckfinderRoute – CKFinder 连接器的路由。它是连接器监听命令的虚拟路径。它应与 CKFinder JavaScript 客户端的 connectorPath 保持同步。

目录