CKBox 迁移工具

本指南将向您展示如何将资产从旧系统（如 CKFinder 或 Easy Image）迁移到 CKBox。您还将找到有关如何在迁移后将系统中的旧 URL 替换为 CKBox 链接的信息。

# 使用迁移工具

迁移工具是一个 CLI 应用程序，旨在将您的资产在系统之间迁移。它内置支持 Easy Image 和 CKFinder，您还可以创建自定义适配器以从任何源迁移文件。

# 安装

在安装迁移工具之前，请确保您已安装 NodeJS 版本 18.x 或更高版本。有关安装 NodeJS 的说明，请访问 [https://node.org.cn/en/download/package-manager 此页面]。

然后，您可以从源代码下载并构建迁移工具

git clone git@github.com:ckbox-io/migration-tool.git
cd migration-tool
npm install
npm run build

# 准备迁移

为了迁移您的资产，您需要配置与您的源存储和 CKBox 的连接。首先，准备 CKBox 连接的配置。

# 配置 CKBox 连接

在您下载迁移工具的目录中创建一个 config.json 文件。您可以复制并使用 config.template.json 作为您自己配置的模板。

您需要提供访问凭据（即环境 ID 和访问密钥）。您可以在身份验证指南中了解有关 CKBox 凭据的更多信息。您还应提供 serviceOrigin URL。如果您是 SaaS 客户端，它应该指向 https://api.ckbox.io。对于本地部署版本，您需要将此值设置为指向 CKBox 本地应用程序的 REST API 的 URL。

{
    "ckbox": {
        "accessCredentials": {
            "environmentId": "<ENVIRONMENT_ID>",
            "accessKey": "<ACCESS_KEY>"
        },
        "workspaceId": "<WORKSPACE_ID>",
        "serviceOrigin": "<SERVICE_ORIGIN>"
    }
}

可选地，您也可以指定 workspaceId。如果您没有指定，所有文件都将上传到默认工作区。在工作区指南中详细了解工作区。

CKBox 连接配置选项列表

选项名称	描述
ckbox.assetsCredentials.environmentId	迁移的目标环境。
ckbox.assetsCredentials.accessKey	用于签署授权令牌的访问密钥。
ckbox.workspaceId	迁移的目标工作区（可选）。
ckbox.serviceOrigin	设置用于 CKBox REST API 的来源。

# 准备源存储

源存储配置取决于您要迁移的系统类型。如果您要从 CKFinder 或 Easy Image 迁移，您可以使用内置支持并使用以下示例。对于其他系统，您需要实现自己的 SourceStorageAdapter。有关从自定义存储迁移的更多信息，请参阅本文档。

# CKFinder

要从 CKFinder 迁移资产，您必须为 ckfinder 设置 type，设置连接器 URL，并添加用于身份验证的标头。

{
    "source": {
        "type": "ckfinder",
        "options": {
            "connectorPath": "https://127.0.0.1:8080/ckfinder/connector",
            "authentication": {
                "headers": {
                    "Cookie": "PHPSESSID=e0baf7e705e40f7e7dea7fa3d04a5a79"
                }
            }
        }
    },
    "ckbox": {
        ...
    }
}

CKFinder 连接配置选项列表

选项名称	描述
source.type	必须设置为 `ckfinder`。
source.options.connectorPath	设置用于 CKFinder REST API 的来源。
source.options.authentication.headers	设置身份验证所需的标头。

# Easy Image

要从 Easy Image 迁移资产，您必须将 type 设置为 easy-image，设置 REST API 来源 URL，并添加访问凭据。

您可以在 CKEditor 云服务授权指南中找到有关 Easy Image 凭据的更多信息。

{
    "source": {
        "type": "easy-image",
        "options": {
            "accessCredentials": {
                "environmentId": "<ENVIRONMENT_ID>",
                "accessKey": "<ACCESS_KEY>"
            },
            "serviceOrigin": "<SERVICE_ORIGIN>"
        }
    },
    "ckbox": {
        ...
    }
}

Easy Image 连接配置选项列表

选项名称	描述
source.type	必须设置为 `easy-image`。
source.options.assetsCredentials.environmentId	迁移的源环境。
source.options.assetsCredentials.accessKey	用于签署授权令牌的访问密钥。
source.options.serviceOrigin	设置用于 Easy Image REST API 的来源。

# 检查配置

在迁移之前，建议先通过在试运行模式下运行迁移工具来验证配置。此命令将验证连接并扫描源存储以查看它是否可以访问资源。

npm start -- --dry-run

# 运行迁移

要启动迁移，您需要执行以下命令

npm start

此命令将在您的 CKBox 实例中创建类别、文件夹并上传资产。

# 将旧 URL 替换为应用程序中的新 URL

迁移过程完成后，迁移工具会生成一个文件，其中映射了旧 URL 与新 URL。文件名将具有格式 ckbox_mapped_URLs_[migration time].txt。您可以使用此文件将应用程序中的旧 URL 替换为新 URL。

该文件包含 URL 对，每对 URL 占一行。源文件的 URL 和已迁移文件的 URL 由制表符分隔。

# 故障排除

如果出现任何问题，迁移工具将在 ckbox_migrator_[migration time].log 文件中生成日志。它包含有关所发生问题的详细说明。

您还应该注意，即使其中一项资源迁移失败，迁移工具也会尝试迁移剩余的资源。您将在控制台中收到有关此问题的消息，因此您可以检查日志以获取更多信息。如果您发现某些资源迁移失败，但其他资源没有失败，则必须首先检查并修复问题（例如调整源系统或 CKBox 的权限）。然后，您可以

尝试手动上传失败的资产。
或者，您可以通过从 CKBox 中删除资源并再次尝试迁移来恢复迁移。