Skip to main content

数据传输

🌐 Data transfer

Page summary:

strapi transfer 命令在两个具有相同模式的 Strapi 实例之间传输数据，使用传输令牌进行授权和身份验证，从而传输内容、文件和配置。

🌐 The strapi transfer command streams data between two Strapi instances with identical schemas, transferring content, files, and configuration using transfer tokens for authorization and authentication.

strapi transfer 命令是 数据管理功能 的一部分，用于将数据从一个 Strapi 实例流式传输到另一个 Strapi 实例。transfer 命令使用严格的模式匹配，这意味着你的两个 Strapi 实例需要完全相同，唯一的区别是包含的数据。默认的 transfer 命令会传输你的内容（实体和关系）、文件（资源）、项目配置以及模式。该命令允许你传输数据：

🌐 The strapi transfer command is part of the Data Management feature and streams your data from one Strapi instance to another Strapi instance. The transfer command uses strict schema matching, meaning your two Strapi instances need to be exact copies of each other except for the contained data. The default transfer command transfers your content (entities and relations), files (assets), project configuration, and schemas. The command allows you to transfer data:

  • 从本地 Strapi 实例到远程 Strapi 实例
  • 从远程 Strapi 实例到本地 Strapi 实例

以下文档详细说明了可用于自定义数据传输的选项。传输命令及所有可用选项均通过 Strapi CLI 运行。

🌐 The following documentation details the available options to customize your data transfer. The transfer command and all of the available options are run using the Strapi CLI.

Caution
  • 如果你在目标实例中使用 SQLite 数据库，当 transfer 操作正在运行时，其他数据库连接将被阻塞。
  • 管理员用户和 API 令牌不会转移。
  • 如果你的项目使用 websockets 或 Socket.io，这个命令会失败。请参见 故障排除。

CLI 命令包含以下参数：

🌐 The CLI command consists of the following arguments:

选项描述
--to目标 Strapi 实例上 /admin 端点的完整 URL
（例如 --to https://my-beautiful-strapi-website/admin）
--to-token从 Strapi 目标实例转移令牌。
--from要从中提取数据的远程 Strapi 实例的 /admin 端点的完整 URL（例如，--from https://my-beautiful-strapi-website/admin）
--from-token从 Strapi 源实例转移令牌。
--force自动对所有提示回答“是”，包括可能具有破坏性的请求，并以非交互方式运行。
--exclude使用逗号分隔的数据类型来排除数据。可用的数据类型有：content、files、config 和 media-library（排除上传的二进制文件和上传的内容类型记录）。
--only仅包含这些数据。可用的类型有：content、files 和 config。
--exclude-content-types要排除的内容类型 UID 的逗号分隔列表。任何涉及被排除类型的实体记录和关联链接都会被跳过。
--only-content-types要包含的内容类型 UID 的逗号分隔列表。只会传输列出的类型的实体记录和关联链接。
--throttle在每个传输的实体之间注入人工延迟的时间（毫秒）。
--no-checksums禁用资源的端到端 SHA-256 校验和验证。当源实例和目标实例都支持校验和验证时，默认启用校验和验证。
--verbose启用详细日志。

必须提供 --to 或 --from，但不能同时提供两个。

🌐 Either --to or --from is required, and you cannot pass both.

Tips
  • 在对远程实例运行命令之前，为了熟悉该命令，请参阅在本地测试数据传输。
  • 将你的传输令牌存储到环境变量中可能会更方便，以避免复制/粘贴。只需确保这些令牌不会被推送到公共仓库。

生成传输令牌​

🌐 Generate a transfer token

Prerequisites

盐转移令牌应在管理员面板配置文件中定义。

🌐 A salt transfer token should be defined in the admin panel configuration file.

strapi transfer 命令需要目标实例发放的传输令牌。要在管理面板中生成传输令牌，请按照 用户指南 中的说明操作。

🌐 The strapi transfer command requires a transfer token issued by the destination instance. To generate a transfer token in the admin panel use the instructions in the User Guide.

令牌的转移可以在管理面板中进行，你还可以在这里管理基于角色的令牌权限，包括 view、create、read、regenerate 和 delete。

🌐 Transfer tokens are managed from the admin panel, where you can also manage role-based permissions to tokens including view, create, read, regenerate, and delete.

设置并运行数据传输​

🌐 Setup and run the data transfer

启动数据传输取决于你是要将数据推送到远程实例还是从远程拉取数据：

🌐 Initiating a data transfer depends on whether you want to push data to a remote instance or to pull data from the remote:

Caution

远程 Strapi 实例必须用 start 命令运行，而不是 develop 命令。

🌐 The remote Strapi instance must be running with the start command, not the develop command.

  1. 启动目标实例的 Strapi 服务器。
  2. 在新的终端窗口中，导航到源实例的根目录。
  3. 运行以下最小命令以启动传输，确保 destinationURL 是管理面板的完整 URL（即 URL 包含 /admin 部分）：
terminal
yarn strapi transfer --to destinationURL
  1. 当出现提示时添加转移令牌。
  2. 在命令行提示符下回答 是 或 否："传输将删除远程 Strapi 上的现有数据！你确定要继续吗？"

一旦传输开始，命令会在终端中实时报告进度，包括准备步骤、各阶段进度以及计时和预估剩余时间。

🌐 Once the transfer starts, the command reports live progress in the terminal, including preparation steps, per-stage progress, and timing with an estimated time remaining.

一次转移能替代和保留什么​

🌐 What a transfer replaces and preserves

5.52.2The preserve-versus-replace behavior described below is clarified and logged by the CLI since Strapi 5.52.2.

--only 和 --exclude 缩小了传输的范围。两者都接收一个用逗号分隔且类型之间没有空格的字符串：content、files 和 config，另外 media-library 仅用于 --exclude。模式(schema)永远不能被排除，因为模式匹配用于 strapi transfer。

当你使用任一选项时，只有你指定的阶段会在目标上受到影响：

🌐 When you use either option, only the stages you name are affected on the destination:

  • 被省略的阶段会被保留。 当一个阶段未被传输时，该阶段的目标数据将保持不变。
  • 已转移的阶段将被替换。 你在转移中包含的任何阶段都会完全替换该阶段的目标数据，除了管理员类型和被忽略的类型，如 plugin::content-releases.release，这些类型总是会被保留。

阶段过滤和内容类型过滤是独立的，可以组合使用。阶段过滤器（--only 和 --exclude）用来选择哪些类型的数据可以移动。内容类型过滤器（--only-content-types 和 --exclude-content-types）则限制在内容阶段可以移动的内容类型。

🌐 Stage filtering and content-type filtering are independent and can be combined. Stage filters (--only and --exclude) select which kinds of data move. Content-type filters (--only-content-types and --exclude-content-types) narrow which content types move within the content stage.

例如：在保留目标配置的同时刷新内容​

🌐 Example: refresh content while preserving destination config

仅刷新源实例的内容，同时保留目标实例的配置：

🌐 To refresh only content from a source instance while keeping the destination instance's configuration:

terminal
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token --only content

每个预设对应不同的传输阶段：content 包括实体和链接，也就是内容类型行，包括媒体库数据库记录及其关联。files 涉及资源阶段，也就是 public/uploads 下的上传二进制文件。config 涵盖核心存储和 webhook。不管这些预设如何，模式总是会被传输。

🌐 Each preset maps to transfer stages: content covers entities and links, meaning content-type rows, including media library database records, and their relations. files covers the assets stage, meaning the upload binaries under public/uploads. config covers the core store and webhooks. Schemas are always transferred, independently of these presets.

Warning

媒体分布在两个预设中。files 预设只涵盖二进制文件，而媒体库数据库记录（plugin::upload.file 和 plugin::upload.folder）属于 content。所以单独使用 --exclude files 只能跳过资源阶段：记录仍会被传输，目标端可能会出现指向从未传输的二进制文件的记录。要同时保留两者，请使用 --exclude media-library。

🌐 Media is split across two presets. The files preset covers only the binaries, while the media library database records (plugin::upload.file and plugin::upload.folder) belong to content. So --exclude files alone only skips the assets stage: the records still transfer, and the destination can end up with records pointing to binaries that were never transferred. To preserve both, use --exclude media-library.

标志已传输目标上保留的内容
默认 strapi transfer内容、文件、配置仅管理员和忽略类型
--only content内容配置和上传的二进制文件
--only files文件内容和配置
--only config配置内容和文件
--only content,files内容和文件配置
--exclude content文件和配置内容
--exclude files内容和配置上传的二进制文件
--exclude media-library不含上传类型的内容和配置上传的二进制文件、plugin::upload.file 和 plugin::upload.folder

示例：仅传输文件​

🌐 Example: only transfer files

terminal
yarn strapi transfer --to https://example.com/admin --only files

示例：从传输中排除文件​

🌐 Example: exclude files from transfer

terminal
yarn strapi transfer --to https://example.com/admin --exclude files

在传输过程中筛选内容类型​

🌐 Filter content types during transfer

5.51.0This feature requires Strapi version 5.51.0 or later.

--exclude-content-types 和 --only-content-types 选项让你可以把传输限定到特定的内容类型。这两个选项都接受以逗号分隔的内容类型 UID 列表（例如 api::article.article）。未知的 UID 会在启动时根据 Strapi 的 schema 进行验证。所有实体记录以及涉及被排除类型的关系链接都会自动跳过。

🌐 The --exclude-content-types and --only-content-types options let you scope a transfer to specific content types. Both options accept a comma-separated list of content-type UIDs (for example, api::article.article). Unknown UIDs are validated against the Strapi schema at startup. Both entity records and any relation links touching an excluded type are skipped automatically.

Warning: Restore behavior
  • 当你使用 --exclude-content-types 时，被排除类型的数据会在目标位置保留：在传输前不会被清除。
  • 当你使用 --only-content-types 时，预传输清理只会针对列出的 UID，而其他目标上的内容会保持不变。

例如：排除特定内容类型的传输​

🌐 Example: exclude specific content types from transfer

terminal
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token \
  --exclude-content-types api::article.article

例如：仅传输特定内容类型​

🌐 Example: transfer only specific content types

terminal
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token \
  --only-content-types api::article.article,api::category.category

绕过所有 transfer 命令行提示​

🌐 Bypass all transfer command line prompts

使用 strapi transfer 命令时，你需要确认转移操作会删除现有的数据库内容。--force 标志可以让你跳过这个提示。这个选项在以编程方式实现 strapi transfer 时很有用。如果你使用 --force 选项，必须在传输令牌中传入 --to-token 选项。

🌐 When using the strapi transfer command, you are required to confirm that the transfer will delete the existing database contents. The --force flag allows you to bypass this prompt. This option is useful for implementing strapi transfer programmatically. You must pass the --to-token option with the transfer token if you use the --force option.

Caution

--force 选项会绕过所有关于内容删除的警告。删除只涵盖实际传输的阶段：如果你使用 --only 或 --exclude 过滤阶段，被省略的阶段会被保留。参见 传输会替换和保留什么。

🌐 The --force option bypasses all warnings about content deletion. The deletion only covers the stages that are actually transferred: if you filter stages with --only or --exclude, the omitted stages are preserved. See What a transfer replaces and preserves.

示例：使用 --force 绕过 transfer 命令行提示​

🌐 Example: bypass the transfer command line prompts with --force

terminal
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token --force

音调转移性能与验证​

🌐 Tune transfer performance and verification

有两个选项可以调整传输的运行方式，而不是它所传输的内容：

🌐 Two options adjust how a transfer runs rather than what it carries:

  • --no-checksums 会禁用应用于资源的端到端 SHA-256 校验和验证。当源和目标都支持时，验证默认是开启的，它可以保证资源完整到达，所以只有在排查问题时才关闭它。
  • --verbose 会打印详细日志，这在转账失败却没有明显原因时特别有用。

使用 --from 拉取时，资源流还取决于 transfer.remote.assetIdleTimeoutMs 服务器选项，它限制了在传输中资源流在没有前进的情况下可持续的最长时间，超时则会中止传输。默认值是 300000，也就是 5 分钟。详见 服务器配置文档。

🌐 When pulling with --from, asset streaming also depends on the transfer.remote.assetIdleTimeoutMs server option, which caps how long an asset stream may go without forward progress before the transfer aborts. It defaults to 300000, meaning 5 minutes. See the server configuration documentation.

示例：禁用校验和验证​

🌐 Example: disable checksum verification

terminal
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token \
  --no-checksums

禁用远程数据传输​

🌐 Disable remote data transfer

在 服务器配置 文件中使用 transfer.remote.enabled 选项可以禁用远程数据传输。结合管理面板中可用的 RBAC 权限，这可以帮助你保护你的 Strapi 应用。

🌐 Remote data transfer is disabled with the transfer.remote.enabled option in the server configuration file. Combined with the RBAC permissions available in the admin panel, this can help you secure your Strapi application.

/config/server.js
module.exports = ({ env }) => ({
  // …
  transfer: {
    remote: {
      enabled: false,
    },
  },
});
Caution

在 Strapi v4 中，这由 STRAPI_DISABLE_REMOTE_DATA_TRANSFER 环境变量控制，但现在不再支持：设置它会显示警告，并且不会有任何效果。参见 已移除对某些环境选项的支持。

🌐 In Strapi v4 this was controlled by the STRAPI_DISABLE_REMOTE_DATA_TRANSFER environment variable, which is no longer supported: setting it now logs a warning and has no effect. See Removed support for some environment options.

故障排除​

🌐 Troubleshooting

在 nginx 反向代理后传输失败。 一个传输会打开 WebSocket 连接，当代理不转发连接升级时会失败。Nginx 指南 中的服务器块通过 proxy_http_version 1.1 以及 Upgrade 和 Connection 头部转发它。两者都是必需的：没有 proxy_http_version 1.1 升级根本不会发生，无论设置了哪些头部。

连接被拒绝，目标是 localhost。 尝试将地址改为 http://127.0.0.1:1337/admin。

传输失败，并且项目使用了 websockets。 当使用 websockets 或 Socket.io 时，transfer 命令会失败。可以暂时禁用它们，或者确保 websocket 服务器运行在与 Strapi 服务器不同的端口，或者在 Strapi 内的特定路由上运行。

On this page