Webiny Sync System 开发指南：Blue/Green 环境同步架构、部署流程与 Resolver/Worker 源码实现-北京尧图网络

CMS后端前端【免费下载链接】webiny-jsOpen-source, self-hosted CMS platform on AWS serverless (Lambda, DynamoDB, S3). TypeScript framework with multi-tenancy, lifecycle hooks, GraphQL API, and AI-assisted development via MCP server. Built for developers at large organizations.项目地址https://gitcode.com/gh_mirrors/we/webiny-js点击查看免费下载本指南基于 packages/api-sync-system/DEVELOPMENT.md系统讲解 Webiny 开源仓库中 Sync System同步系统的核心概念如何在dev等环境中通过--env与--variant参数部署多个并行的 Webiny 实例让它们在同一个环境内自动互联、双向同步数据文件、用户等记录。读完本文你将掌握 Sync System 的完整部署命令、env/variant参数语义以及其底层 Resolver、Worker、Sync Handler 三大组件的真实源码结构与待办路线图。Sync System 是什么一个环境内多实例自动互联的同步层在 Webiny 中Sync System 是一套负责将**同一环境env下多个 Webiny 部署deployment**之间的数据保持一致的独立基础设施。它解决的核心问题是同一套 Webiny 系统可以部署多个副本例如blue与green两个 variant各自拥有独立的 DynamoDB、S3 与用户体系当用户在blue中创建或修改文件、用户等记录时这些变更需要自动同步到green反之亦然多个实例可以随时加入部署数量不限于两个只要使用不同的variant即可。从源码结构看这个能力被收敛在 packages/api-sync-system 这一个独立包中其package.json描述即为 Sync System.依赖webiny/aws-sdk、webiny/event-handler-aws、webiny/feature、webiny/plugins、zod等基础设施库。包内主要由三大部分组成对应三条不同的运行路径组件源码目录职责Sync Systempackages/api-sync-system/src/sync通过ApiGatewaySyncDecorator装饰 API Gateway 事件处理链拦截 DynamoDB 写操作并生成同步命令再通过 EventBridge 发布事件Resolverpackages/api-sync-system/src/resolver由 SQS 事件触发拉取各 deployment 的元数据与源数据将同步命令转换为目标 deployment 的 DynamoDB 写操作Workerpackages/api-sync-system/src/worker由 Lambda 触发执行跨系统拷贝类动作S3 文件复制、Cognito 用户创建/更新/删除三个组件的公开 API 全部从 packages/api-sync-system/src/index.ts 导出SyncResolverConfig/SyncResolverLambdaHandler、SyncWorkerConfig/SyncWorkerEventType/SyncWorkerEventHandler/SyncWorkerLambdaHandler以及SyncSystemConfig/ApiGatewaySyncDecorator。理解env与variant参数DEVELOPMENT.md 开篇首先澄清了两个关键参数env环境指 Webiny 的部署环境示例中一律使用dev。你也可以使用staging、prod等环境名variant变体用于在同一环境内区分多个并行部署的任意标识。示例使用blue和green但你完全可以用orange、black、car、horse、space等任意字符串。关键约束Sync System 与各个 Webiny 部署必须处于同一个env中因为 Sync System 会自动连接同一环境内的所有 Webiny 部署通过解析各部署写入 DynamoDB 的 deployment 记录。同一环境下可以使用任意数量的 variant唯一的硬性要求是每个部署使用不同的 variant。这一点可以从 packages/api-sync-system/src/resolver/deployment/Deployment.ts 得到印证Deployment类显式持有name、env、variant、region、services、version六个字段其中variant是可选字段string | undefined而getTable(type)方法根据 deployment 的services返回regular主 DynamoDB 表或opensearchOpenSearch 数据表两种表类型。也就是说Resolver 在同步时是按环境 variant 区域去定位目标表的。三步部署流程从 Sync System 到多实例安装1. 部署 Sync System在项目根目录执行yarn webiny deploy sync --envdev该命令将 Sync System 部署到dev环境。它对应的就是包中sync目录packages/api-sync-system/src/sync所承载的运行时能力包括createHandlersync/createHandler.ts与ApiGatewaySyncDecoratorsync/ApiGatewaySyncDecorator.ts。2. 部署blue与green两个 Webinyyarn webiny deploy --envdev --variantblue yarn webiny deploy --envdev --variantgreen这里串联意味着blue部署成功后才部署green。文档特别强调两个系统必须与 Sync System 处于同一环境Sync System 才能自动识别并连接它们。并且部署数量可以超过两个——只要保证 variant 不同即可。3. 安装 Webiny Blue 变体先查看部署信息找到bluevariant 的 Admin URLyarn webiny info然后在浏览器中打开该 Admin URL按照界面指引完成系统安装。安装完成后green系统也会被同步安装——这正是 Sync System 的核心价值一次安装多实例就绪。Resolver把源系统变更搬运到目标系统Resolver 是同步链条中的核心执行者由 resolver/SyncResolverLambdaHandler.ts 实现并通过SqsEventHandler.createImplementation注册为 SQS 事件处理器。其处理流程processResolverEvent可以概括为取配置tableName取自config.tableName || process.env.DB_TABLE若两者都为空则抛出WebinyErrorTable name variable is not set.建 FetchercreateFetcher({ maxRetries: 10, retryDelay: 1000, ... })按 deployment 的region创建 DynamoDB Document Client负责从源系统读取记录最多重试 10 次、每次间隔 1 秒拉取 DeploymentscreateDeploymentsFetcher从当前 region 读取所有 deployment 元数据即上面Deployment类对应的记录得到需要同步的目标集合建 StorercreateStorer同样按目标 deployment 的 region 写入数据且支持StorerAfterEachPlugin插件在每个写入完成后做后续处理变换与打包TransformHandlerRecordHandler配合createBundlerCommandBundle与TableBundle两种打包器将源记录转换成目标表的写命令执行createResolverApp(...).resolve({ records })逐个处理 SQS 消息中的记录。Resolver 还负责触发拷贝类动作在 SyncResolverLambdaHandler.ts 的execute中会依据config.createLambdaClient与config.awsWorkerLambdaArn || process.env.AWS_SYNC_WORKER_LAMBDA_ARN创建LambdaTrigger进而构造CopyFile/DeleteFile依赖 S3 客户端与CopyUser/DeleteUser依赖 Cognito Identity Provider 客户端再把它们注册进PluginsContainer供记录处理链调用。这正是文档 TODO 中提到给 Sync System handlers 传一堆方法的根源——详见下文配置注入部分。Worker跨系统执行文件复制与用户账号操作Worker 由 worker/SyncWorkerLambdaHandler.ts 实现注册为SyncWorkerEventHandler。其职责是接收 Resolver 通过LambdaTrigger发来的动作请求执行无法在 DynamoDB 层完成的跨系统操作createCopyFileAction/createDeleteFileAction基于 S3 客户端复制或删除文件createCreateUserAction/createUpdateUserAction/createDeleteUserAction基于 Cognito 客户端创建、更新、删除用户。动作类型定义在 worker/SyncWorkerEventType.ts动作分发由 worker/handler/WorkerActionHandler.ts 完成可扩展点是通过 worker/plugins/WorkerActionPlugin.ts 注册自定义动作。对应地Resolver 侧的记录类型插件位于 resolver/recordTypes/fileManager 与 resolver/recordTypes/users分别处理文件与用户的复制/删除语义。Sync System 的接入方式ApiGatewaySyncDecorator 与命令转换同步入口不是独立运行的 Lambda而是以装饰器形式挂在 API Gateway 事件处理器上。sync/ApiGatewaySyncDecorator.ts 的核心逻辑调用getManifest()sync/utils/manifest.ts读取同步 manifest若 manifest 缺失或没有sync.region打印[ApiGatewaySyncDecorator] Manifest not available — sync disabled.并直接放行同步被禁用通过createHandlersync/createHandler.ts构建同步处理器。createHandler会注册一批命令转换器CommandConverterBatchGet、Get、Query、Scan、BatchWrite、Put、Delete、Update默认值使用NullCommandValue并读取FilterOutRecordPlugin插件用于过滤不需要同步的记录用decorateClientWithHandlersync/attachToDynamoDbDocument.ts把 handler 挂到 Document Client 上从而拦截应用内部的 DynamoDB 写操作将其转换为同步命令在内层处理器执行结束后调用handler.flush()确保命令被批量发出事件通过 manifest 中的eventBusArn/eventBusName发布到 EventBridge见 sync/createHandler.ts。需要同步的写操作会在 EventBridge 上以synchronization-input事件名出现见 constants.ts之后由 Resolver 的 SQS 处理器消费。配置注入方式与文档中的依赖注入展望文档 TODO 中明确指出了当前实现的一个痛点Sync handlers 需要调用者传入大量creator 方法。当前SyncResolverConfigresolver/SyncResolverConfig.ts的接口确实包含export interface ISyncResolverConfig { tableName?: string; awsWorkerLambdaArn?: string; createDocumentClient(params: PartialDynamoDBClientConfig): PickDynamoDBDocument, send; createLambdaClient?(config: PartialLambdaClientConfig): PickLambdaClient, send; createS3Client?(config: S3ClientConfig): PickS3Client, send; createCognitoIdentityProviderClient?(config: PartialCognitoIdentityProviderClientConfig): PickCognitoIdentityProvider, send; plugins?: AllowedResolverPlugins[]; }即当前实际用法接近文档中的冗长版本const handler createSyncResolverHandler({ plugins: [], debug: process.env.DEBUG true, awsWorkerLambdaArn: process.env.AWS_SYNC_WORKER_LAMBDA_ARN, createS3Client, createLambdaClient, createDocumentClient, createCognitoIdentityProviderClient });而文档展望的理想形态是轻量版本——只需传入plugins、debug与awsWorkerLambdaArn三项const handler createSyncResolverHandler({ plugins: [], debug: process.env.DEBUG true, awsWorkerLambdaArn: process.env.AWS_SYNC_WORKER_LAMBDA_ARN });文档将其归结为 TODO 中的Implement Dependency Injection若引入依赖注入框架各 creator 方法createS3Client、createLambdaClient、createDocumentClient、createCognitoIdentityProviderClient即可由框架自动装配调用方无需逐个传入后续新增方法也不必改动调用点。这是当前包内尚未落地的演进方向。文档中的其他 TODO已知问题与演进路线DEVELOPMENT.md 还记录了若干待办事项理解它们有助于判断 Sync System 当前的成熟度与边界新增blueGreen、sync/resolver、sync/worker目录到用户项目目前需要把这些文件夹部署进用户项目也许做成一个 CLI 命令更佳Blue/Green 部署端到端测试文档给出完整的测试清单——创建api.bg.webiny.com、admin.bg.webiny.com、website.bg.webiny.com、preview.bg.webiny.com域名部署 blueGreen 应用确认域名指向正确在 blue/green 之间切换以测试 resolver并在两侧创建/更新记录、确认数据正确传递Cognito 用户迁移缺陷用户账号目前可以转移但密码没有迁移导致用户无法登录也无法重置密码计划通过实现一个登录函数——向用户邮箱发送验证码、凭验证码完成登录——来彻底解决删除记录的模型过滤目前模型过滤只在记录加入同步池时创建/更新生效而删除操作没有携带modelId无法过滤文档提出也许可以在 resolver 中实现过滤接入 pino 日志用 pino 替代现状按info、warn、error、debug等级别记录所有事件。从源码看当前 handler 在出错时使用console.error/console.log见 SyncResolverLambdaHandler.ts 与 SyncWorkerLambdaHandler.ts这也与仓库中 no-console-in-backend 的代码风格约束相呼应拆分 Resolver 插件把 file manager、users 的 resolver 插件迁移到各自独立的包中由对应包自行注册当前这些插件集中在 resolver/recordTypes 下。快速上手完整命令序列综合全文在dev环境跑通 Blue/Green 同步的完整命令序列为# 1. 部署 Sync System yarn webiny deploy sync --envdev # 2. 部署两个或多个Webiny 实例variant 必须不同 yarn webiny deploy --envdev --variantblue yarn webiny deploy --envdev --variantgreen # 3. 查看部署信息找到 blue 的 Admin URL 并完成安装 yarn webiny info安装好blue后green会自动完成安装此后在任一实例中创建/更新/删除的文件与用户记录会经由 DynamoDB 命令拦截 → EventBridge 事件 → ResolverSQS→ WorkerLambda的链路同步到另一实例。需要进一步阅读实现细节时可深入 packages/api-sync-system/src 的sync、resolver、worker三个子目录以及包内对应测试用例。赞分享CMS后端前端【免费下载链接】webiny-jsOpen-source, self-hosted CMS platform on AWS serverless (Lambda, DynamoDB, S3). TypeScript framework with multi-tenancy, lifecycle hooks, GraphQL API, and AI-assisted development via MCP server. Built for developers at large organizations.项目地址https://gitcode.com/gh_mirrors/we/webiny-js点击查看免费下载相关推荐从0到1搭建preact-render-to-stringExpress服务动态HTML生成教程从0到1搭建preact render to stringExpress服务动态HTML生成教程 preact render to string是一个强大的Webiny pg-os 后端 PG 到 OpenSearch 同步流Sync Stream流水线设计与实现指南Webiny pg os 后端 PG 到 OpenSearch 同步流Sync Stream流水线设计与实现指南导读本文围绕 PG to OpenSeaCMS后端前端在 Kubernetes 上使用 Argo Rollouts 实现 Blue/Green 部署devops-exercises 实操指南在 Kubernetes 上使用 Argo Rollouts 实现 Blue/Green 部署devops exercises 实操指南本指南基于 devo文档教程DevOps运维上一篇探秘 delete-tweets自动化删除推文的新工具下一篇如何在Lottie React Native中动态改变动画颜色完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Webiny Sync System 开发指南：Blue/Green 环境同步架构、部署流程与 Resolver/Worker 源码实现

相关推荐

驱动芯片绝缘安规标准详解：从爬电距离到PCB布局避坑指南

RISC-V编译选项-march与-mabi匹配原理与实战

STM32仿真项目：无需开发板的可设置电子时钟

更多资讯

MASTG iOS 非生产资源详解：如何识别并从生产构建中剔除调试日志、测试端点与开发凭据

AI 为什么能学习？以及AI 与人脑的本质差距是什么？

2026年SMT贴片打样与量产产线选型指南

智慧政务AI大模型应用方案：从私有化部署到RAG落地实践

Julep mem-mcp Phase 2 兼容：让 .ctx 提示词包在 dotctx 加载器中忠实落地

计及氢能的综合能源优化调度：Matlab建模与实现

今日更新

PHP htmlentities()函数用法讲解

AI Agent工程实战：从七要素到七个决策点的系统设计指南

AI入局芯片设计验证：验证收敛50倍加速的真相与应对

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？