Strapi 数据迁移 WebSocket 协议解析Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapiStrapi 的远程数据迁移Data Transfer功能通过 WebSocket 在源端push或目标端pullStrapi 服务器之间建立一条结构化消息通道。本篇基于仓库文档 01-websocket.md 与packages/core/data-transfer的源码实现讲清楚三件事WebSocket 服务端只接受哪些传输命令transfer commands以及它们必须按什么顺序发送消息分发器dispatcher的dispatchCommand/dispatchTransferStep/dispatchTransferAction三个方法各自承担什么职责以及从建连到关闭的完整传输生命周期连接、初始化、动作、分步流式传输、关闭如何运转包括超时重试机制的源码级细节。读完后你将能够理解 Strapi 远程迁移协议的消息契约并能基于 remote-source 提供者 的bootstrap()方法实现或调试自定义的 WebSocket 迁移客户端。1. 传输命令与消息分发器远程 WebSocket 服务器只接受特定的 WebSocket 消息——文档将其称为transfer commands。这些命令必须按特定顺序发送如果服务器收到意外的消息会返回错误消息。因此协议本质上是一个严格有序的命令 → 响应对话而非自由的双工数据流。文档指出客户端应创建一个消息分发器对象message dispatcher来向服务器发送消息实现位于 strapi/providers/utils.ts。阅读源码后可以确认createDispatcher()的完整签名为export const createDispatcher ( ws: WebSocket, retryMessageOptions: RetryMessageOptions { retryMessageMaxRetries: 5, retryMessageTimeout: 30000, }, reportInfo?: (message: string) void ) { /* ... */ }从源码结构看分发器的返回值正是文档所描述的三个方法外加内部dispatch与传输状态访问器1.1 dispatchCommand —— 开启与结束传输接受用于打开和关闭传输的command。源码中分发器校验的命令集合定义在 remote/handlers/constants.tsexport const VALID_TRANSFER_COMMANDS [init, end, status] as const;其中文档重点描述的两个命令init初始化连接返回transferID此后本次传输中的所有消息都必须携带该 transferIDend结束连接。init命令还支持携带params。在 remote-source 提供者的initTransfer()中可以看到实际用法当需要校验资产字节完整性时客户端会在 init 参数中声明checksums: true服务器若支持则回传checksums: true完成协商const query this.dispatcher?.dispatchCommand({ command: init, ...(wantsChecksums ? { params: { transfer: pull, checksums: true } } : {}), });此外从Handler接口remote/handlers/abstract.ts可以看到服务器侧还定义了status命令与init、end并列于VALID_TRANSFER_COMMANDS中。1.2 dispatchTransferStep —— 阶段切换与数据流式传输用于在传输的阶段step/stage之间切换并流式传输传输的实际数据。接受的action取值start携带step值阶段名称表示开始该阶段stream可发送任意多条携带step值与正在发送的data例如实体数组、资产块end携带step值表示该阶段结束。在 utils.ts 的dispatchTransferStep中可以看到stream类型的消息会要求data字段并且所有 step 消息都会自动附加attachTransfer: true即自动补上 transferID。1.3 dispatchTransferAction —— 触发服务端动作用于触发与本地提供者等价的动作。文档列出的 action 值bootstrapgetMetadatabeforeTransfergetSchemasrollback仅 destination 方向close完成一次传输但不关闭连接文档提示完整且精确的消息定义见packages/core/data-transfer/dist/strapi/remote/handlers/pull.d.ts与push.d.ts——这是构建产物dist中的类型声明。在未构建的源码仓库中对应的运行时实现与类型契约位于 remote/handlers/pull.ts、remote/handlers/push.ts 以及协议类型目录 types/remote/protocol其中client/transfer/pull.ts、push.ts、commands.ts分别定义了客户端消息结构可作为阅读精确消息定义的入口。2. 传输生命周期原文档用一张 Mermaid 时序图完整刻画了一次传输的全过程各阶段依次为连接阶段 → 初始化阶段 → 传输动作阶段 → 传输步骤阶段流式→ 关闭阶段。下面逐阶段展开并补充源码证据。2.1 连接阶段WebSocket 建连与鉴权当 Strapi 服务器启用了数据迁移功能即设置了admin.transfer.token.salt配置值且server.transfer.remote.enabled未设为false时Strapi 会创建两个 WebSocket 服务器路由分别为/admin/transfer/runner/pull与/admin/transfer/runner/push。源码中的路径常量印证了这一点见 remote/constants.tsexport const TRANSFER_PATH /transfer/runner as const; export const TRANSFER_METHODS [push, pull] as const;建立连接在以上路由上打开 WebSocket 连接时需要在Authorization头中提供有效的迁移 token 作为 Bearer TokenAuthorization: Bearer transfer_token服务器校验 token 后建立连接。文档建议参考 remote 提供者的bootstrap()方法了解初始连接的建立方式。remote-source 的bootstrap()给出了完整的建连示例async bootstrap(diagnostics?: IDiagnosticReporter): Promisevoid { const { url, auth } this.options; const wsProtocol url.protocol https: ? wss: : ws:; const wsUrl ${wsProtocol}//${url.host}${trimTrailingSlash(url.pathname)}${TRANSFER_PATH}/pull; // 未定义 auth 时尝试公开访问迁移 if (!auth) { ws await connectToWebsocket(wsUrl, undefined, this.#diagnostics); } // 常见的 token 鉴权这应是主要的鉴权方式 else if (auth.type token) { const headers { Authorization: Bearer ${auth.token} }; ws await connectToWebsocket(wsUrl, { headers }, this.#diagnostics); } else { throw new ProviderValidationError(Auth method not available, { check: auth.type, ... }); } this.ws ws; this.dispatcher createDispatcher(this.ws, retryMessageOptions, (message) this.#reportInfo(message) ); const transferID await this.initTransfer(); this.dispatcher.setTransferProperties({ id: transferID, kind: pull }); await this.dispatcher.dispatchTransferAction(bootstrap); }可以观察到几个与文档呼应的细节HTTP(S) 地址会被转换为wss:/ws:协议后拼接/transfer/runner/pull鉴权只支持token类型Bearer 头其余类型抛出ProviderValidationError建连后立即创建 dispatcher、执行init拿到 transferID再发出bootstrap动作——这正是文档生命周期图中Connection → Initialization → Actions顺序的真实代码落点。HTTP 状态码语义文档未展开但源码中有明确约定connectToWebsocket 对握手阶段的非 101 响应做了分类处理401→Failed to initialize the connection: Authentication Error403→Failed to initialize the connection: Authorization Error404→Failed to initialize the connection: Data transfer is not enabled on the remote host其他状态码 →Unexpected server response ${statusCode}这为排查连接失败类问题提供了直接依据404 意味着远端服务器未启用数据迁移功能而不是网络不通。事件监听器挂载文档指出WebSocket 创建后应立即挂载以下监听器open处理连接成功建立close管理连接终止error处理连接与传输错误message处理来自服务器的入站消息。在仓库实现中connectToWebsocket内部挂载了openresolve Promise、unexpected-response、message用于转发diagnostic诊断消息到诊断报告器和error四个处理器而close/message的完整挂载则由 dispatcher 与流式读取逻辑按阶段动态注册见下文 2.4 的拉取流监听。2.2 初始化阶段客户端发送初始命令建立传输服务器响应唯一的transferIDconst transferID await dispatcher.dispatchCommand(init); // 此后所有后续消息都必须携带该 transferID从源码看init的响应载荷除transferID外还可携带协商结果如checksums客户端随后调用setTransferProperties({ id: transferID, kind: pull })把 transferID 与传输方向存入 dispatcher 内部状态。dispatcher 的dispatch内部逻辑会在options.attachTransfer为真时自动执行Object.assign(payload, { transferID: state.transfer?.id })utils.ts#L58-L60所以业务代码无需手动为每条消息附加 transferID。2.3 传输动作阶段通过dispatchTransferAction顺序执行的动作bootstrap初始化传输环境getMetadata获取传输元数据beforeTransfer执行迁移前准备getSchemas获取内容类型 schemas用于源端与目标端之间的校验。remote-source 提供者中的getMetadata()与getSchemas()正是这两个动作的直接调用async getMetadata(): PromiseIMetadata | null { const metadata await this.dispatcher?.dispatchTransferActionIMetadata(getMetadata); return metadata ?? null; }2.4 传输步骤阶段数据流式传输这是实际数据传输发生的主阶段依次处理不同类型的数据schemas、entities、assets、links、configuration阶段开始dispatchTransferStep(action: start, step)数据流式传输dispatchTransferStep(action: stream, step, data)阶段结束dispatchTransferStep(action: end, step)重试机制数据传输期间如果在retryMessageTimeout内未收到服务器响应系统最多重试retryMessageMaxRetries次超时自动重试超过最大重试次数则中止传输。源码给出了具体默认值与实现方式createDispatcher的默认参数为retryMessageMaxRetries: 5、retryMessageTimeout: 3000030 秒。dispatch 内部通过setInterval每retryMessageTimeout毫秒重发一次同一载荷计数超过retryMessageMaxRetries后以ProviderError(error, Request timed out)拒绝该 Promise。值得注意的是仓库中的两处工程化增强体现了该协议在实际大规模迁移中的调优思路长窗口覆盖dispatch支持retryOverrides选项可对单条消息临时合并更长的重试窗口。remote-source 中定义了ASSETS_START_RETRY_OVERRIDES { retryMessageTimeout: 120_000, retryMessageMaxRetries: 30 }因为 pull 端在收到assets阶段的start前要先跑estimateAssetTotals数据库流式统计大媒体库场景可能超过默认 30 秒窗口。#startStep(assets)调用时即传入该覆盖值。资产停滞检测拉取资产时除了消息级重试还设有独立的streamTimeout默认 300_000 毫秒监测单个资产长时间无进展超时则销毁对应资产流Asset ${assetID} transfer timed out。消息确认拉取方向下服务器推来的流式数据帧由客户端逐帧回发{ uuid }作为确认#respond服务器端则用confirm()It sends a message to the client and waits for a confirmation见 Handler 接口实现同一语义。这保证了stream 一条、确认一条的可靠流。2.5 关闭阶段清理动作发送 close 动作dispatchTransferAction(close);发送 end 命令dispatchCommand({ command: end, params: { transferID } });连接终止按逆序移除事件监听器先移除message再error、open、close关闭 WebSocket 连接。仓库中 remote-source 的close()展示了第一步与连接关闭的结合先dispatchTransferAction(close)完成传输再对 ws 注册一次性close回调后调用ws.close()连接真正关闭时才 resolve——这与文档close 动作不关闭连接由客户端显式关闭的描述一致。3. 消息超时与重试模型原文档用一张状态图描述了消息-响应协议的状态迁移Init → Ready → Dispatching → WaitingResponse → (Retrying | Ready) → Error并说明因为传输依赖消息→响应协议如果 WebSocket 服务器无法回复例如网络不稳定连接就会停摆。为此每个提供者的选项中都包含retryMessageOptions在达到给定超时后重发消息并在给定次数的失败重试后中止传输。结合源码该模型可以细化为以下可验证事实配置项默认值行为源码依据retryMessageTimeout30000ms每经过该时长仍未收到匹配 uuid 的响应则重发同一条消息utils.ts#L84-L96 的setInterval(sendPeriodically, retryMessageTimeout)retryMessageMaxRetries5发送计数超过该值后以ProviderError(error, Request timed out)中止当前消息retryOverrides无单条消息级覆盖如 assetsstart使用120000/30remote-source#L37-L40streamTimeoutpull 资产300000ms单个资产无进展无新远端块、无完成写入达到该时长即中止remote-source#L185-L201响应匹配机制是这套重试能够安全工作的关键每条出站消息都会附加随机uuidrandomUUID()onResponse处理器只在response.uuid uuid时才解析并 resolve/reject否则把监听重新挂回ws.once(message, onResponse)utils.ts#L98-L132。这保证了重发产生的重复帧、或诊断类旁路消息不会污染当前请求的响应解析。错误响应还会按step字段细化为不同类型的异常transfer→ProviderTransferError、validation→ProviderValidationError、initialization→ProviderInitializationError。从 errors/providers.ts 可进一步追溯这些异常类的定义用于在自定义客户端中做分类处理。4. 小结如何落地这套协议基于文档与源码一次自定义的远程迁移客户端应遵循如下要点建连向远端 Strapi 的/admin/transfer/runner/pushpush 方向远端为目的地或/admin/transfer/runner/pullpull 方向远端为源建立ws/wss连接并按需在Authorization: Bearer transfer_token头中携带迁移 tokenurl协议只允许http:/https:assertValidProtocol。顺序严格init→bootstrap/getMetadata/beforeTransfer/getSchemas→ 每个 step 的start→ 若干stream→end→close动作 →end命令 → 关闭连接乱序会得到服务器错误。transferID 全程携带init返回后所有 transfer 消息自动或手动附带 transferID。为慢操作放宽窗口默认 30 秒 × 5 次重试适合大多数消息但统计量大、数据量大的步骤如 assetsstart应使用retryOverrides放宽窗口避免误报Request timed out。流式数据要确认pull 方向下服务器推送的流式帧需要以{ uuid }回应形成可靠的逐帧确认闭环。本文全部内容以 docs/docs/docs/01-core/data-transfer/02-providers/05-remote-strapi/01-websocket.md 的协议描述为骨架并以 packages/core/data-transfer 中的分发器实现strapi/providers/utils.ts、pull/push 处理器strapi/remote/handlers与 remote-source 提供者strapi/providers/remote-source/index.ts作为实现级佐证相关行为还可参考 packages/core/data-transfer/src/strapi/providers/remote-source/tests与 remote-destination/tests下的 checksum 协商、资产流等测试用例。需要提醒的是该文档带有experimental标签协议细节命令集合、消息字段以当前仓库版本的类型定义为准。【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Strapi 数据迁移 WebSocket 协议解析：Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期
Strapi 数据迁移 WebSocket 协议解析Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapiStrapi 的远程数据迁移Data Transfer功能通过 WebSocket 在源端push或目标端pullStrapi 服务器之间建立一条结构化消息通道。本篇基于仓库文档 01-websocket.md 与packages/core/data-transfer的源码实现讲清楚三件事WebSocket 服务端只接受哪些传输命令transfer commands以及它们必须按什么顺序发送消息分发器dispatcher的dispatchCommand/dispatchTransferStep/dispatchTransferAction三个方法各自承担什么职责以及从建连到关闭的完整传输生命周期连接、初始化、动作、分步流式传输、关闭如何运转包括超时重试机制的源码级细节。读完后你将能够理解 Strapi 远程迁移协议的消息契约并能基于 remote-source 提供者 的bootstrap()方法实现或调试自定义的 WebSocket 迁移客户端。1. 传输命令与消息分发器远程 WebSocket 服务器只接受特定的 WebSocket 消息——文档将其称为transfer commands。这些命令必须按特定顺序发送如果服务器收到意外的消息会返回错误消息。因此协议本质上是一个严格有序的命令 → 响应对话而非自由的双工数据流。文档指出客户端应创建一个消息分发器对象message dispatcher来向服务器发送消息实现位于 strapi/providers/utils.ts。阅读源码后可以确认createDispatcher()的完整签名为export const createDispatcher ( ws: WebSocket, retryMessageOptions: RetryMessageOptions { retryMessageMaxRetries: 5, retryMessageTimeout: 30000, }, reportInfo?: (message: string) void ) { /* ... */ }从源码结构看分发器的返回值正是文档所描述的三个方法外加内部dispatch与传输状态访问器1.1 dispatchCommand —— 开启与结束传输接受用于打开和关闭传输的command。源码中分发器校验的命令集合定义在 remote/handlers/constants.tsexport const VALID_TRANSFER_COMMANDS [init, end, status] as const;其中文档重点描述的两个命令init初始化连接返回transferID此后本次传输中的所有消息都必须携带该 transferIDend结束连接。init命令还支持携带params。在 remote-source 提供者的initTransfer()中可以看到实际用法当需要校验资产字节完整性时客户端会在 init 参数中声明checksums: true服务器若支持则回传checksums: true完成协商const query this.dispatcher?.dispatchCommand({ command: init, ...(wantsChecksums ? { params: { transfer: pull, checksums: true } } : {}), });此外从Handler接口remote/handlers/abstract.ts可以看到服务器侧还定义了status命令与init、end并列于VALID_TRANSFER_COMMANDS中。1.2 dispatchTransferStep —— 阶段切换与数据流式传输用于在传输的阶段step/stage之间切换并流式传输传输的实际数据。接受的action取值start携带step值阶段名称表示开始该阶段stream可发送任意多条携带step值与正在发送的data例如实体数组、资产块end携带step值表示该阶段结束。在 utils.ts 的dispatchTransferStep中可以看到stream类型的消息会要求data字段并且所有 step 消息都会自动附加attachTransfer: true即自动补上 transferID。1.3 dispatchTransferAction —— 触发服务端动作用于触发与本地提供者等价的动作。文档列出的 action 值bootstrapgetMetadatabeforeTransfergetSchemasrollback仅 destination 方向close完成一次传输但不关闭连接文档提示完整且精确的消息定义见packages/core/data-transfer/dist/strapi/remote/handlers/pull.d.ts与push.d.ts——这是构建产物dist中的类型声明。在未构建的源码仓库中对应的运行时实现与类型契约位于 remote/handlers/pull.ts、remote/handlers/push.ts 以及协议类型目录 types/remote/protocol其中client/transfer/pull.ts、push.ts、commands.ts分别定义了客户端消息结构可作为阅读精确消息定义的入口。2. 传输生命周期原文档用一张 Mermaid 时序图完整刻画了一次传输的全过程各阶段依次为连接阶段 → 初始化阶段 → 传输动作阶段 → 传输步骤阶段流式→ 关闭阶段。下面逐阶段展开并补充源码证据。2.1 连接阶段WebSocket 建连与鉴权当 Strapi 服务器启用了数据迁移功能即设置了admin.transfer.token.salt配置值且server.transfer.remote.enabled未设为false时Strapi 会创建两个 WebSocket 服务器路由分别为/admin/transfer/runner/pull与/admin/transfer/runner/push。源码中的路径常量印证了这一点见 remote/constants.tsexport const TRANSFER_PATH /transfer/runner as const; export const TRANSFER_METHODS [push, pull] as const;建立连接在以上路由上打开 WebSocket 连接时需要在Authorization头中提供有效的迁移 token 作为 Bearer TokenAuthorization: Bearer transfer_token服务器校验 token 后建立连接。文档建议参考 remote 提供者的bootstrap()方法了解初始连接的建立方式。remote-source 的bootstrap()给出了完整的建连示例async bootstrap(diagnostics?: IDiagnosticReporter): Promisevoid { const { url, auth } this.options; const wsProtocol url.protocol https: ? wss: : ws:; const wsUrl ${wsProtocol}//${url.host}${trimTrailingSlash(url.pathname)}${TRANSFER_PATH}/pull; // 未定义 auth 时尝试公开访问迁移 if (!auth) { ws await connectToWebsocket(wsUrl, undefined, this.#diagnostics); } // 常见的 token 鉴权这应是主要的鉴权方式 else if (auth.type token) { const headers { Authorization: Bearer ${auth.token} }; ws await connectToWebsocket(wsUrl, { headers }, this.#diagnostics); } else { throw new ProviderValidationError(Auth method not available, { check: auth.type, ... }); } this.ws ws; this.dispatcher createDispatcher(this.ws, retryMessageOptions, (message) this.#reportInfo(message) ); const transferID await this.initTransfer(); this.dispatcher.setTransferProperties({ id: transferID, kind: pull }); await this.dispatcher.dispatchTransferAction(bootstrap); }可以观察到几个与文档呼应的细节HTTP(S) 地址会被转换为wss:/ws:协议后拼接/transfer/runner/pull鉴权只支持token类型Bearer 头其余类型抛出ProviderValidationError建连后立即创建 dispatcher、执行init拿到 transferID再发出bootstrap动作——这正是文档生命周期图中Connection → Initialization → Actions顺序的真实代码落点。HTTP 状态码语义文档未展开但源码中有明确约定connectToWebsocket 对握手阶段的非 101 响应做了分类处理401→Failed to initialize the connection: Authentication Error403→Failed to initialize the connection: Authorization Error404→Failed to initialize the connection: Data transfer is not enabled on the remote host其他状态码 →Unexpected server response ${statusCode}这为排查连接失败类问题提供了直接依据404 意味着远端服务器未启用数据迁移功能而不是网络不通。事件监听器挂载文档指出WebSocket 创建后应立即挂载以下监听器open处理连接成功建立close管理连接终止error处理连接与传输错误message处理来自服务器的入站消息。在仓库实现中connectToWebsocket内部挂载了openresolve Promise、unexpected-response、message用于转发diagnostic诊断消息到诊断报告器和error四个处理器而close/message的完整挂载则由 dispatcher 与流式读取逻辑按阶段动态注册见下文 2.4 的拉取流监听。2.2 初始化阶段客户端发送初始命令建立传输服务器响应唯一的transferIDconst transferID await dispatcher.dispatchCommand(init); // 此后所有后续消息都必须携带该 transferID从源码看init的响应载荷除transferID外还可携带协商结果如checksums客户端随后调用setTransferProperties({ id: transferID, kind: pull })把 transferID 与传输方向存入 dispatcher 内部状态。dispatcher 的dispatch内部逻辑会在options.attachTransfer为真时自动执行Object.assign(payload, { transferID: state.transfer?.id })utils.ts#L58-L60所以业务代码无需手动为每条消息附加 transferID。2.3 传输动作阶段通过dispatchTransferAction顺序执行的动作bootstrap初始化传输环境getMetadata获取传输元数据beforeTransfer执行迁移前准备getSchemas获取内容类型 schemas用于源端与目标端之间的校验。remote-source 提供者中的getMetadata()与getSchemas()正是这两个动作的直接调用async getMetadata(): PromiseIMetadata | null { const metadata await this.dispatcher?.dispatchTransferActionIMetadata(getMetadata); return metadata ?? null; }2.4 传输步骤阶段数据流式传输这是实际数据传输发生的主阶段依次处理不同类型的数据schemas、entities、assets、links、configuration阶段开始dispatchTransferStep(action: start, step)数据流式传输dispatchTransferStep(action: stream, step, data)阶段结束dispatchTransferStep(action: end, step)重试机制数据传输期间如果在retryMessageTimeout内未收到服务器响应系统最多重试retryMessageMaxRetries次超时自动重试超过最大重试次数则中止传输。源码给出了具体默认值与实现方式createDispatcher的默认参数为retryMessageMaxRetries: 5、retryMessageTimeout: 3000030 秒。dispatch 内部通过setInterval每retryMessageTimeout毫秒重发一次同一载荷计数超过retryMessageMaxRetries后以ProviderError(error, Request timed out)拒绝该 Promise。值得注意的是仓库中的两处工程化增强体现了该协议在实际大规模迁移中的调优思路长窗口覆盖dispatch支持retryOverrides选项可对单条消息临时合并更长的重试窗口。remote-source 中定义了ASSETS_START_RETRY_OVERRIDES { retryMessageTimeout: 120_000, retryMessageMaxRetries: 30 }因为 pull 端在收到assets阶段的start前要先跑estimateAssetTotals数据库流式统计大媒体库场景可能超过默认 30 秒窗口。#startStep(assets)调用时即传入该覆盖值。资产停滞检测拉取资产时除了消息级重试还设有独立的streamTimeout默认 300_000 毫秒监测单个资产长时间无进展超时则销毁对应资产流Asset ${assetID} transfer timed out。消息确认拉取方向下服务器推来的流式数据帧由客户端逐帧回发{ uuid }作为确认#respond服务器端则用confirm()It sends a message to the client and waits for a confirmation见 Handler 接口实现同一语义。这保证了stream 一条、确认一条的可靠流。2.5 关闭阶段清理动作发送 close 动作dispatchTransferAction(close);发送 end 命令dispatchCommand({ command: end, params: { transferID } });连接终止按逆序移除事件监听器先移除message再error、open、close关闭 WebSocket 连接。仓库中 remote-source 的close()展示了第一步与连接关闭的结合先dispatchTransferAction(close)完成传输再对 ws 注册一次性close回调后调用ws.close()连接真正关闭时才 resolve——这与文档close 动作不关闭连接由客户端显式关闭的描述一致。3. 消息超时与重试模型原文档用一张状态图描述了消息-响应协议的状态迁移Init → Ready → Dispatching → WaitingResponse → (Retrying | Ready) → Error并说明因为传输依赖消息→响应协议如果 WebSocket 服务器无法回复例如网络不稳定连接就会停摆。为此每个提供者的选项中都包含retryMessageOptions在达到给定超时后重发消息并在给定次数的失败重试后中止传输。结合源码该模型可以细化为以下可验证事实配置项默认值行为源码依据retryMessageTimeout30000ms每经过该时长仍未收到匹配 uuid 的响应则重发同一条消息utils.ts#L84-L96 的setInterval(sendPeriodically, retryMessageTimeout)retryMessageMaxRetries5发送计数超过该值后以ProviderError(error, Request timed out)中止当前消息retryOverrides无单条消息级覆盖如 assetsstart使用120000/30remote-source#L37-L40streamTimeoutpull 资产300000ms单个资产无进展无新远端块、无完成写入达到该时长即中止remote-source#L185-L201响应匹配机制是这套重试能够安全工作的关键每条出站消息都会附加随机uuidrandomUUID()onResponse处理器只在response.uuid uuid时才解析并 resolve/reject否则把监听重新挂回ws.once(message, onResponse)utils.ts#L98-L132。这保证了重发产生的重复帧、或诊断类旁路消息不会污染当前请求的响应解析。错误响应还会按step字段细化为不同类型的异常transfer→ProviderTransferError、validation→ProviderValidationError、initialization→ProviderInitializationError。从 errors/providers.ts 可进一步追溯这些异常类的定义用于在自定义客户端中做分类处理。4. 小结如何落地这套协议基于文档与源码一次自定义的远程迁移客户端应遵循如下要点建连向远端 Strapi 的/admin/transfer/runner/pushpush 方向远端为目的地或/admin/transfer/runner/pullpull 方向远端为源建立ws/wss连接并按需在Authorization: Bearer transfer_token头中携带迁移 tokenurl协议只允许http:/https:assertValidProtocol。顺序严格init→bootstrap/getMetadata/beforeTransfer/getSchemas→ 每个 step 的start→ 若干stream→end→close动作 →end命令 → 关闭连接乱序会得到服务器错误。transferID 全程携带init返回后所有 transfer 消息自动或手动附带 transferID。为慢操作放宽窗口默认 30 秒 × 5 次重试适合大多数消息但统计量大、数据量大的步骤如 assetsstart应使用retryOverrides放宽窗口避免误报Request timed out。流式数据要确认pull 方向下服务器推送的流式帧需要以{ uuid }回应形成可靠的逐帧确认闭环。本文全部内容以 docs/docs/docs/01-core/data-transfer/02-providers/05-remote-strapi/01-websocket.md 的协议描述为骨架并以 packages/core/data-transfer 中的分发器实现strapi/providers/utils.ts、pull/push 处理器strapi/remote/handlers与 remote-source 提供者strapi/providers/remote-source/index.ts作为实现级佐证相关行为还可参考 packages/core/data-transfer/src/strapi/providers/remote-source/tests与 remote-destination/tests下的 checksum 协商、资产流等测试用例。需要提醒的是该文档带有experimental标签协议细节命令集合、消息字段以当前仓库版本的类型定义为准。【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考