Vendure 3.x 版本演进与安全加固实战指南从 CHANGELOG 看头部电商平台的迭代脉络【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure本文以开源无头电商平台 Vendure基于 TypeScript、NestJS 与 GraphQL 构建的官方 CHANGELOG.md 为主线系统梳理 v3.0 至 v3.7 版本的安全公告、核心功能、性能优化与破坏性变更并结合仓库源码如packages/core/src/get-api-security-warnings.ts、packages/core/src/config/auth/entity-access-control-strategy.ts深入剖析关键机制。读完本文你将理解 Vendure 的安全模型演进方向、多商户与多渠道架构的扩展方式以及升级到最新版本时必须执行的配置与迁移动作。一、CHANGELOG 文档定位为什么它是一份“技术路线图”仓库根目录下的 CHANGELOG.md 记录了 Vendure v3.0.02024-07-17到 v3.7.32026-09-01的全部发布内容并按Security安全、Fixes修复、Features功能、Perf性能与BREAKING CHANGE破坏性变更分类。与一般流水账式更新日志不同这份文档的 3.7.x 安全小节详细描述了漏洞成因、攻击面与修复后的行为变化本身就具备“安全加固手册”的阅读价值同时 v3.6.0 与 v3.7.0 的 Feature 清单则勾勒出了 Vendure 从“单体管理后台”向“多渠道 Dashboard API Key 行级权限”演进的产品方向。v2 及更早版本的变更记录分别归档在 CHANGELOG_v2.md 与 CHANGELOG_v1.md当前文档只覆盖 3.x 主线。二、3.7.x 安全公告深度解读账户接管、IDOR 与 CSRFv3.7.32026-09-01与 v3.7.22026-08-03是 3.x 系列中安全补丁最密集的两个版本修复的漏洞全部由 GitHub 安全公告security advisory负责任披露涉及 core、asset-server-plugin 与 dashboard 多个包。2.1 未认证的 SSO 客户账户接管最严重的是registerCustomerAccount的账户接管漏洞对应公告 GHSA-wr5h-x3x6-4h23攻击者可以利用外部/SSO 认证账户尚未设置密码的空档通过该变更接管客户账户。修复后的行为变化非常关键值得逐条对照registerCustomerAccount不再保存调用方提供的密码。当邮箱已通过其他认证策略存在账户且尚无密码时系统改为向该邮箱发送验证令牌密码必须通过携带令牌调用verifyCustomerAccount才能设置——无论authOptions.requireVerification取值如何此类客户都无法在注册后立即登录。调用方提交的firstName、lastName、phoneNumber及自定义字段在 User 已存在时全部被忽略。从 v3.7.0 引入的约束可以追溯这一漏洞的根源外部认证现在只在外部邮箱已验证时才会将登录关联到既有账户自定义AuthenticationStrategy必须在返回的用户数据上对已验证邮箱设置verified: true否则拒绝账户关联创建全新账户不受影响。2.2 跨渠道 IDOROrder、Asset 与管理员数据越权3.7.x 修复了一组**跨渠道 IDORInsecure Direct Object Reference**问题即攻击者在当前渠道不可见某个实体时仍能通过直接指定 ID 操作它订单支付、退款、履约fulfillment与客户备注操作中的跨渠道 IDORGHSA-7qvr-c5vf-xxfhassignToChannel/removeFromChannel变更及duplicateEntity变更中源实体的渠道作用域缺失GHSA-422x-jq57-j238、GHSA-f94w-2928-x43pupdateChannel/deleteChannel变更的渠道作用域问题GHSA-22x4-937q-5fr5createProductOption中ProductOptionGroup查找的渠道作用域GHSA-gg28-cx38-jxxr管理员读取越权administrators/administrator查询现在只返回调用者角色有权管辖的管理员渠道作用域管理员不再能看到仅属于其他渠道的职员GHSA-37j3-p93w-fq6wv3.7.2 补充修复了adjustDraftOrderLine未授权访问GHSA-hc75-2v4j-x372、updateAdministrator密码重置导致的提权GHSA-v85r-wfgv-jcqc、Promotion/FacetValue 删除与 Asset/StockLocation 更新的跨渠道写 IDORGHSA-fp4j-ff6j-9793、GHSA-rgjm-ff27-p2hf。修复后的统一行为是当目标实体在当前活动渠道不可见时上述变更抛出错误此前会静默成功。这保证了多渠道商户场景下“看不见即不可操作”的最小权限原则。2.3 账号枚举时序攻击与登录 CSRFv3.7.3 关闭了无本地密码账户剩余的账号枚举时序侧信道GHSA-c63h-3vvx-48ph此前 v3.5.3 已为NativeAuthenticationStrategy修复过一轮时序攻击CVE-2026-25050。新增apiOptions.csrfPrevention选项用于阻止Login CSRF跨站 HTML 表单可以发起顶层导航 POST 一个login变更无需 CORS 许可在访客浏览器中种下会话 Cookie。该选项默认false开启后所有上传文件或使用 GET 执行查询的客户端都必须发送Apollo-Require-Preflight请求头vendure/admin-ui、vendure/dashboard与vendure/testing已经支持。在源码层面这一机制由 packages/core/src/get-api-security-warnings.ts 中的getCsrfPreventionWarning()与getCorsConfigWarning()实现bootstrap()启动时会检查apiOptions.cors是否处于“反射任意 Originorigin: true 允许凭据credentials: true”的不安全组合并据此输出警告NODE_ENV test时跳过。该文件还指出当会话 Cookie 配置为sameSite: none或false时跨站请求会携带 Cookie风险会被放大建议在生产环境显式设置 Origin 白名单例如{ origin: [https://storefront.example.com], credentials: true }。2.4 资产服务器的 XSS 与文件类型加固v3.7.3 对asset-server-plugin做了两处重要加固SVG 存储型 XSSGHSA-f4r3-h6jf-4m29通过加固资产响应头解决。现在资产服务器对每个资产发送X-Content-Type-Options: nosniff和Content-Security-Policy并对标记型资产SVG、HTML、XML使用Content-Disposition: attachment——直接打开这类资产的 URL 会变成下载而非渲染img src内嵌图片不受影响。相关提交还“将沙箱 CSP 限定到标记类型使 PDF 能内联渲染”。file-type升级core 与 asset-server-plugin 均将file-type提升到^21.3.1修复畸形 ASF 输入导致无限循环的问题GHSA-5v7r-6r5c-r473。注意 v21 将四种 MIME 类型重命名为 IANA 注册名audio/x-flac→audio/flac、video/x-matroska→video/matroska、application/x-apache-arrow→application/vnd.apache.arrow.file、application/x-parquet→application/vnd.apache.parquet。如果在assetOptions.permittedFileTypes中显式列过旧值必须更新否则相关上传会被拒绝默认通配配置image/*、video/*、audio/*、.pdf不受影响。2.5 任务数据中的会话令牌泄漏Admin API 返回的任务Job数据不再包含会话令牌GHSA-32jm-mf7r-7qw5。需要特别注意的是升级只能阻止新的泄漏历史任务记录中可能已存在令牌因此升级后应清理已完结settled的任务数据并考虑使现有管理员会话失效。文档同时说明由于阻止RequestContext.serialize()持久化令牌会改变RequestContext.session的类型这部分完整落地要等到下一个 minor 版本。三、v3.6 / v3.7 核心能力从功能清单到源码实现v3.6.02026-03-31与 v3.7.02026-07-01是 3.x 中功能密度最高的两个 minor 版本以下能力均有对应源码可查。3.1 API Key 支持v3.6.0新增 API Key 机制对应 issue #3815为服务到服务machine-to-machine集成提供不依赖会话的认证方式。v3.7.2 修复了“通过 Key 所有者解析 API-Key 会话上的 Administrator”的问题说明 API Key 会话同样会解析出管理员身份用于权限判断。Dashboard 在 v3.6.0 同步提供了 API Keys 管理界面并支持 bearer token 认证。3.2 SettingsStore全局与作用域配置存储v3.4.0v3.6.0 完善v3.4.0 引入SettingsStore用于持久化全局与渠道作用域的配置项并随之要求一次非破坏性数据库迁移新建 settings 表。v3.4.2 对SettingsStoreService的方法签名做了规范ctx参数移至第一位旧顺序仍可用但建议更新- SettingsStoreService.getT(key, ctx) - SettingsStoreService.getMany(keys, ctx) - SettingsStoreService.setT(key, value, ctx) - SettingsStoreService.setMany(values, ctx) SettingsStoreService.getT(ctx, key) SettingsStoreService.getMany(ctx, keys) SettingsStoreService.setT(ctx, key, value) SettingsStoreService.setMany(ctx, values)v3.5.0 为其补充了读写权限支持#3828v3.6.0 新增 Dashboard 的 Settings Store 管理页面。3.3 EntityAccessControlStrategy行级访问控制v3.6.0这是 3.6 最重要的架构级能力#4451目前标注为developer preview / experimental。接口定义位于 packages/core/src/config/auth/entity-access-control-strategy.ts提供三层控制门控层canAccess(ctx, permissions)在 AuthGuard 中每次请求调用一次完全替代默认权限判定逻辑返回false则拒绝ForbiddenError。自定义策略应继承DefaultEntityAccessControlStrategy并调用super.canAccess()保留默认行为。预加载prepareAccessControl?(ctx)可选的异步阶段用于预取卖家 ID、品类分配等数据缓存到WeakMapRequestContext, ...供同步方法使用。文档特别警告此阶段中的数据库查询必须用rawConnection.getRepository()而不能用 RequestContext 感知的getRepository(ctx, ...)否则会触发访问控制 Proxy 造成无限递归。行级applyAccessControl?(qb, entityType, ctx)对每个实体查询同步修改 TypeORMSelectQueryBuilder。当实现了该方法时TransactionalConnection.getRepository()返回 Proxyfind、findOne、findAndCount、count等仓库方法以及createQueryBuilder()的getMany、getOne、getRawMany、stream等终结方法都会在真正执行前套用 ACL。所有标准数据访问路径ListQueryBuilder.build()、findOneInChannel()、findByIdsInChannel()都会经过它。未实现该方法时零开销不创建 Proxy。接口 JSDoc 自带一个卖家作用域过滤示例通过qb.innerJoin(...channels).andWhere(__acl_ch.sellerId IN (:...aclSellerIds))只让卖家看到自己渠道下的商品——这正是多商户multi-vendor场景的行级隔离基础。3.4 CustomerChannelAssignmentStrategy 与 OrderLineDiscountDistributionStrategyv3.7.0CustomerChannelAssignmentStrategy#4863控制客户在注册/创建时自动分配渠道的策略配合默认实现DefaultCustomerChannelAssignmentStrategy见 packages/core/src/config/auth/default-customer-channel-assignment-strategy.ts可自定义多渠道下客户的归属逻辑。OrderLineDiscountDistributionStrategy#4818让订单行折扣分摊proration规则可配置化默认实现见 packages/core/src/config/order/default-order-line-discount-distribution-strategy.ts。此前折扣分摊逻辑写死在订单计算器中现在可通过策略注入自定义。配套新特性优惠券码校验改为大小写不敏感#4419BREAKINGCouponRemovedDuringCheckoutError加入AddPaymentToOrderResult#4683生产环境拒绝默认 superadmin 密码启动#4718BREAKINGOrderTaxCalculationStrategy、onBeforeAppListen钩子、BootstrappedEvent、异步OrderMergeStrategy、addItemsToOrder批量加购、Shop API 设置订单币种等。3.5 匿名遥测v3.6.0新增匿名遥测采集模块#4192并在 v3.7.2 演进到 schema v2加入心跳与策略/集成/功能采用度信号#4933v3.6.5 修复了 Vercel/Netlify 与 ESM 下遥测数据静默丢失的问题。遥测实现位于 packages/core/src/telemetry可在配置中关闭。3.6 Dashboard 与 CLI生态工具的快速迭代从 v3.2 到 v3.7vendure/dashboardReact Vite TanStack Router 的新版管理界面成为迭代主力v3.5.0 完成 25 种语言本地化、多币种价格、库存多地点控制、数据表保存视图saved views、Zod v4 支持v3.6.0 加入 API Keys 管理、Option Groups 管理、Settings Store 页面、工具栏扩展点与 ActionBar 扩展v3.7.0 支持自定义 React Provider、TanStack Router 插件选项、useExperimentalBundle预打包模式与 focal point 编辑器v3.7.3 允许草稿订单内联创建客户与地址、支持多渠道批量分配。vendure/cli在 v3.7.0 新增dev/build/start生命周期命令与可分发的 Agent skill、doctor项目体检命令#4777v3.6.0 新增 Radix 到 Base UI 的codemod迁移命令v3.5.0 引入schema命令并强化 monorepo含 Nx 风格检测。CLI 源码见 packages/cli/src/commands。四、性能优化专题3.x 各版本的关键 Perf 条目CHANGELOG 的 Perf 章节记录了大量可复现的性能改进以下是值得关注的代表性条目v3.7.3移除每请求的库存查询雪崩stock query stampede#5224。v3.7.1关系自定义字段改用请求作用域的 DataLoader 批量解析。v3.6.5findByCustomerId消除 productVariant 关系的 N1 查询#4653。v3.6.4Dashboard 减少重型关系查询#4743。v3.6.3产品-渠道分配改用查询关系策略避免 OOM#4669优化缓冲任务 payload 大小core 与 BullMQ 两侧。v3.6.0orderPlacedAtOrder 表与createdAtJobItem 表新增索引需非破坏性迁移BREAKING。v3.5.3集合查询实现productVariantCount#4132。v3.5.2修复自引用关系实体的慢查询#4020。v3.3.6优化订单与订单行的关系加载策略#3652。v3.3.3BullMQ 任务列表查询优化#3590。v3.2.0移除重复的促销检查调用。v3.1.3优化apply-collection-filters任务与数据库缓冲任务 payload。v3.1.0订单合并效率提升FacetValueChecker引入缓存推荐改为通过Injector获取见下文破坏性变更。v3.0.xPostgres v16 慢order查询修复#3037默认EntityIdStrategy下跳过 ID 编解码addItemToOrder路径与featuredAsset解析优化。五、破坏性变更清单升级前必读升级到 3.x 各版本前以下 BREAKING CHANGE 需要逐一核对v3.7.0 起优惠券码大小写不敏感仅当你用同一码的不同大小写指向不同 Promotion 时才受影响生产环境使用默认 superadmin 密码将拒绝启动必须先修改外部认证账户关联要求邮箱已验证自定义AuthenticationStrategy需对已验证邮箱返回verified: trueemail-plugin的mjml从 v4→v5、nodemailer从 v6→v9使用 MJML 模板或自定义 transport 需复查nestjs/terminus不再是传递依赖v3.6 起已弃用外部组件健康检查自有健康检查代码需显式添加该依赖。v3.6.0Order/JobItem 新增索引、SettingsStore 新表均需非破坏性迁移Mollie 插件要求mollie/api-client4.3.3。v3.4.xSettingsStoreService方法ctx参数移到首位。v3.2.0DefaultCachePlugin需迁移给expiresAt列加precision(3)仅影响缓存记录。v3.1.0默认舍入逻辑修正——Math.round(value) * quantity改为Math.round(value * quantity)FacetValueChecker建议改用injector.get(FacetValueChecker)以获得缓存收益。v3.0.0所有核心包许可证切换为 GPL v3.0详见 LICENSE.md 与 license/license-faq.md。六、升级行动清单结合安全修复的落地建议综合 3.7.x 安全公告的“行为变化”章节升级时建议按以下清单执行配置层在生产环境为apiOptions.cors.origin设置显式白名单避免origin: truecredentials: true组合如需抵御 Login CSRF开启apiOptions.csrfPrevention: true并确认所有上传文件或 GET 查询的客户端发送Apollo-Require-Preflight头。数据层升级后清理已完结的任务数据历史 Job 记录可能含会话令牌并考虑使现有管理员会话失效更新assetOptions.permittedFileTypes中的旧 MIME 名称。密码层生产环境务必修改默认 superadmin 密码否则 v3.7.0 无法启动外部认证策略需为已验证邮箱返回verified: true。迁移层执行 3.6.0 的索引与 SettingsStore 建表迁移、3.2.0 的expiresAt精度迁移。依赖层复核mjmlv5 与nodemailerv9 的升级影响为自有健康检查代码显式引入nestjs/terminus。七、结语从 CHANGELOG.md 可以清晰看到 Vendure 3.x 的演进主线安全上从被动补洞走向主动加固启动期安全警告、CSRF 防护、渠道作用域强制、行级访问控制 API功能上从传统 Admin UI 转向 React 版 Dashboard 与 API Key 生态架构上通过*Strategy家族CustomerChannelAssignmentStrategy、OrderLineDiscountDistributionStrategy、EntityAccessControlStrategy把更多硬编码行为变成可插拔策略。对于维护多商户、多渠道 Vendure 实例的团队而言这份 CHANGELOG 本身就是一份不可多得的升级与安全审计手册结合仓库内 packages/core/src/get-api-security-warnings.ts 与 packages/core/src/config/auth/entity-access-control-strategy.ts 等源码阅读可以进一步验证文档描述与实际实现的一致性为生产环境的安全配置提供可靠依据。【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vendure 3.x 版本演进与安全加固实战指南：从 CHANGELOG 看头部电商平台的迭代脉络
Vendure 3.x 版本演进与安全加固实战指南从 CHANGELOG 看头部电商平台的迭代脉络【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure本文以开源无头电商平台 Vendure基于 TypeScript、NestJS 与 GraphQL 构建的官方 CHANGELOG.md 为主线系统梳理 v3.0 至 v3.7 版本的安全公告、核心功能、性能优化与破坏性变更并结合仓库源码如packages/core/src/get-api-security-warnings.ts、packages/core/src/config/auth/entity-access-control-strategy.ts深入剖析关键机制。读完本文你将理解 Vendure 的安全模型演进方向、多商户与多渠道架构的扩展方式以及升级到最新版本时必须执行的配置与迁移动作。一、CHANGELOG 文档定位为什么它是一份“技术路线图”仓库根目录下的 CHANGELOG.md 记录了 Vendure v3.0.02024-07-17到 v3.7.32026-09-01的全部发布内容并按Security安全、Fixes修复、Features功能、Perf性能与BREAKING CHANGE破坏性变更分类。与一般流水账式更新日志不同这份文档的 3.7.x 安全小节详细描述了漏洞成因、攻击面与修复后的行为变化本身就具备“安全加固手册”的阅读价值同时 v3.6.0 与 v3.7.0 的 Feature 清单则勾勒出了 Vendure 从“单体管理后台”向“多渠道 Dashboard API Key 行级权限”演进的产品方向。v2 及更早版本的变更记录分别归档在 CHANGELOG_v2.md 与 CHANGELOG_v1.md当前文档只覆盖 3.x 主线。二、3.7.x 安全公告深度解读账户接管、IDOR 与 CSRFv3.7.32026-09-01与 v3.7.22026-08-03是 3.x 系列中安全补丁最密集的两个版本修复的漏洞全部由 GitHub 安全公告security advisory负责任披露涉及 core、asset-server-plugin 与 dashboard 多个包。2.1 未认证的 SSO 客户账户接管最严重的是registerCustomerAccount的账户接管漏洞对应公告 GHSA-wr5h-x3x6-4h23攻击者可以利用外部/SSO 认证账户尚未设置密码的空档通过该变更接管客户账户。修复后的行为变化非常关键值得逐条对照registerCustomerAccount不再保存调用方提供的密码。当邮箱已通过其他认证策略存在账户且尚无密码时系统改为向该邮箱发送验证令牌密码必须通过携带令牌调用verifyCustomerAccount才能设置——无论authOptions.requireVerification取值如何此类客户都无法在注册后立即登录。调用方提交的firstName、lastName、phoneNumber及自定义字段在 User 已存在时全部被忽略。从 v3.7.0 引入的约束可以追溯这一漏洞的根源外部认证现在只在外部邮箱已验证时才会将登录关联到既有账户自定义AuthenticationStrategy必须在返回的用户数据上对已验证邮箱设置verified: true否则拒绝账户关联创建全新账户不受影响。2.2 跨渠道 IDOROrder、Asset 与管理员数据越权3.7.x 修复了一组**跨渠道 IDORInsecure Direct Object Reference**问题即攻击者在当前渠道不可见某个实体时仍能通过直接指定 ID 操作它订单支付、退款、履约fulfillment与客户备注操作中的跨渠道 IDORGHSA-7qvr-c5vf-xxfhassignToChannel/removeFromChannel变更及duplicateEntity变更中源实体的渠道作用域缺失GHSA-422x-jq57-j238、GHSA-f94w-2928-x43pupdateChannel/deleteChannel变更的渠道作用域问题GHSA-22x4-937q-5fr5createProductOption中ProductOptionGroup查找的渠道作用域GHSA-gg28-cx38-jxxr管理员读取越权administrators/administrator查询现在只返回调用者角色有权管辖的管理员渠道作用域管理员不再能看到仅属于其他渠道的职员GHSA-37j3-p93w-fq6wv3.7.2 补充修复了adjustDraftOrderLine未授权访问GHSA-hc75-2v4j-x372、updateAdministrator密码重置导致的提权GHSA-v85r-wfgv-jcqc、Promotion/FacetValue 删除与 Asset/StockLocation 更新的跨渠道写 IDORGHSA-fp4j-ff6j-9793、GHSA-rgjm-ff27-p2hf。修复后的统一行为是当目标实体在当前活动渠道不可见时上述变更抛出错误此前会静默成功。这保证了多渠道商户场景下“看不见即不可操作”的最小权限原则。2.3 账号枚举时序攻击与登录 CSRFv3.7.3 关闭了无本地密码账户剩余的账号枚举时序侧信道GHSA-c63h-3vvx-48ph此前 v3.5.3 已为NativeAuthenticationStrategy修复过一轮时序攻击CVE-2026-25050。新增apiOptions.csrfPrevention选项用于阻止Login CSRF跨站 HTML 表单可以发起顶层导航 POST 一个login变更无需 CORS 许可在访客浏览器中种下会话 Cookie。该选项默认false开启后所有上传文件或使用 GET 执行查询的客户端都必须发送Apollo-Require-Preflight请求头vendure/admin-ui、vendure/dashboard与vendure/testing已经支持。在源码层面这一机制由 packages/core/src/get-api-security-warnings.ts 中的getCsrfPreventionWarning()与getCorsConfigWarning()实现bootstrap()启动时会检查apiOptions.cors是否处于“反射任意 Originorigin: true 允许凭据credentials: true”的不安全组合并据此输出警告NODE_ENV test时跳过。该文件还指出当会话 Cookie 配置为sameSite: none或false时跨站请求会携带 Cookie风险会被放大建议在生产环境显式设置 Origin 白名单例如{ origin: [https://storefront.example.com], credentials: true }。2.4 资产服务器的 XSS 与文件类型加固v3.7.3 对asset-server-plugin做了两处重要加固SVG 存储型 XSSGHSA-f4r3-h6jf-4m29通过加固资产响应头解决。现在资产服务器对每个资产发送X-Content-Type-Options: nosniff和Content-Security-Policy并对标记型资产SVG、HTML、XML使用Content-Disposition: attachment——直接打开这类资产的 URL 会变成下载而非渲染img src内嵌图片不受影响。相关提交还“将沙箱 CSP 限定到标记类型使 PDF 能内联渲染”。file-type升级core 与 asset-server-plugin 均将file-type提升到^21.3.1修复畸形 ASF 输入导致无限循环的问题GHSA-5v7r-6r5c-r473。注意 v21 将四种 MIME 类型重命名为 IANA 注册名audio/x-flac→audio/flac、video/x-matroska→video/matroska、application/x-apache-arrow→application/vnd.apache.arrow.file、application/x-parquet→application/vnd.apache.parquet。如果在assetOptions.permittedFileTypes中显式列过旧值必须更新否则相关上传会被拒绝默认通配配置image/*、video/*、audio/*、.pdf不受影响。2.5 任务数据中的会话令牌泄漏Admin API 返回的任务Job数据不再包含会话令牌GHSA-32jm-mf7r-7qw5。需要特别注意的是升级只能阻止新的泄漏历史任务记录中可能已存在令牌因此升级后应清理已完结settled的任务数据并考虑使现有管理员会话失效。文档同时说明由于阻止RequestContext.serialize()持久化令牌会改变RequestContext.session的类型这部分完整落地要等到下一个 minor 版本。三、v3.6 / v3.7 核心能力从功能清单到源码实现v3.6.02026-03-31与 v3.7.02026-07-01是 3.x 中功能密度最高的两个 minor 版本以下能力均有对应源码可查。3.1 API Key 支持v3.6.0新增 API Key 机制对应 issue #3815为服务到服务machine-to-machine集成提供不依赖会话的认证方式。v3.7.2 修复了“通过 Key 所有者解析 API-Key 会话上的 Administrator”的问题说明 API Key 会话同样会解析出管理员身份用于权限判断。Dashboard 在 v3.6.0 同步提供了 API Keys 管理界面并支持 bearer token 认证。3.2 SettingsStore全局与作用域配置存储v3.4.0v3.6.0 完善v3.4.0 引入SettingsStore用于持久化全局与渠道作用域的配置项并随之要求一次非破坏性数据库迁移新建 settings 表。v3.4.2 对SettingsStoreService的方法签名做了规范ctx参数移至第一位旧顺序仍可用但建议更新- SettingsStoreService.getT(key, ctx) - SettingsStoreService.getMany(keys, ctx) - SettingsStoreService.setT(key, value, ctx) - SettingsStoreService.setMany(values, ctx) SettingsStoreService.getT(ctx, key) SettingsStoreService.getMany(ctx, keys) SettingsStoreService.setT(ctx, key, value) SettingsStoreService.setMany(ctx, values)v3.5.0 为其补充了读写权限支持#3828v3.6.0 新增 Dashboard 的 Settings Store 管理页面。3.3 EntityAccessControlStrategy行级访问控制v3.6.0这是 3.6 最重要的架构级能力#4451目前标注为developer preview / experimental。接口定义位于 packages/core/src/config/auth/entity-access-control-strategy.ts提供三层控制门控层canAccess(ctx, permissions)在 AuthGuard 中每次请求调用一次完全替代默认权限判定逻辑返回false则拒绝ForbiddenError。自定义策略应继承DefaultEntityAccessControlStrategy并调用super.canAccess()保留默认行为。预加载prepareAccessControl?(ctx)可选的异步阶段用于预取卖家 ID、品类分配等数据缓存到WeakMapRequestContext, ...供同步方法使用。文档特别警告此阶段中的数据库查询必须用rawConnection.getRepository()而不能用 RequestContext 感知的getRepository(ctx, ...)否则会触发访问控制 Proxy 造成无限递归。行级applyAccessControl?(qb, entityType, ctx)对每个实体查询同步修改 TypeORMSelectQueryBuilder。当实现了该方法时TransactionalConnection.getRepository()返回 Proxyfind、findOne、findAndCount、count等仓库方法以及createQueryBuilder()的getMany、getOne、getRawMany、stream等终结方法都会在真正执行前套用 ACL。所有标准数据访问路径ListQueryBuilder.build()、findOneInChannel()、findByIdsInChannel()都会经过它。未实现该方法时零开销不创建 Proxy。接口 JSDoc 自带一个卖家作用域过滤示例通过qb.innerJoin(...channels).andWhere(__acl_ch.sellerId IN (:...aclSellerIds))只让卖家看到自己渠道下的商品——这正是多商户multi-vendor场景的行级隔离基础。3.4 CustomerChannelAssignmentStrategy 与 OrderLineDiscountDistributionStrategyv3.7.0CustomerChannelAssignmentStrategy#4863控制客户在注册/创建时自动分配渠道的策略配合默认实现DefaultCustomerChannelAssignmentStrategy见 packages/core/src/config/auth/default-customer-channel-assignment-strategy.ts可自定义多渠道下客户的归属逻辑。OrderLineDiscountDistributionStrategy#4818让订单行折扣分摊proration规则可配置化默认实现见 packages/core/src/config/order/default-order-line-discount-distribution-strategy.ts。此前折扣分摊逻辑写死在订单计算器中现在可通过策略注入自定义。配套新特性优惠券码校验改为大小写不敏感#4419BREAKINGCouponRemovedDuringCheckoutError加入AddPaymentToOrderResult#4683生产环境拒绝默认 superadmin 密码启动#4718BREAKINGOrderTaxCalculationStrategy、onBeforeAppListen钩子、BootstrappedEvent、异步OrderMergeStrategy、addItemsToOrder批量加购、Shop API 设置订单币种等。3.5 匿名遥测v3.6.0新增匿名遥测采集模块#4192并在 v3.7.2 演进到 schema v2加入心跳与策略/集成/功能采用度信号#4933v3.6.5 修复了 Vercel/Netlify 与 ESM 下遥测数据静默丢失的问题。遥测实现位于 packages/core/src/telemetry可在配置中关闭。3.6 Dashboard 与 CLI生态工具的快速迭代从 v3.2 到 v3.7vendure/dashboardReact Vite TanStack Router 的新版管理界面成为迭代主力v3.5.0 完成 25 种语言本地化、多币种价格、库存多地点控制、数据表保存视图saved views、Zod v4 支持v3.6.0 加入 API Keys 管理、Option Groups 管理、Settings Store 页面、工具栏扩展点与 ActionBar 扩展v3.7.0 支持自定义 React Provider、TanStack Router 插件选项、useExperimentalBundle预打包模式与 focal point 编辑器v3.7.3 允许草稿订单内联创建客户与地址、支持多渠道批量分配。vendure/cli在 v3.7.0 新增dev/build/start生命周期命令与可分发的 Agent skill、doctor项目体检命令#4777v3.6.0 新增 Radix 到 Base UI 的codemod迁移命令v3.5.0 引入schema命令并强化 monorepo含 Nx 风格检测。CLI 源码见 packages/cli/src/commands。四、性能优化专题3.x 各版本的关键 Perf 条目CHANGELOG 的 Perf 章节记录了大量可复现的性能改进以下是值得关注的代表性条目v3.7.3移除每请求的库存查询雪崩stock query stampede#5224。v3.7.1关系自定义字段改用请求作用域的 DataLoader 批量解析。v3.6.5findByCustomerId消除 productVariant 关系的 N1 查询#4653。v3.6.4Dashboard 减少重型关系查询#4743。v3.6.3产品-渠道分配改用查询关系策略避免 OOM#4669优化缓冲任务 payload 大小core 与 BullMQ 两侧。v3.6.0orderPlacedAtOrder 表与createdAtJobItem 表新增索引需非破坏性迁移BREAKING。v3.5.3集合查询实现productVariantCount#4132。v3.5.2修复自引用关系实体的慢查询#4020。v3.3.6优化订单与订单行的关系加载策略#3652。v3.3.3BullMQ 任务列表查询优化#3590。v3.2.0移除重复的促销检查调用。v3.1.3优化apply-collection-filters任务与数据库缓冲任务 payload。v3.1.0订单合并效率提升FacetValueChecker引入缓存推荐改为通过Injector获取见下文破坏性变更。v3.0.xPostgres v16 慢order查询修复#3037默认EntityIdStrategy下跳过 ID 编解码addItemToOrder路径与featuredAsset解析优化。五、破坏性变更清单升级前必读升级到 3.x 各版本前以下 BREAKING CHANGE 需要逐一核对v3.7.0 起优惠券码大小写不敏感仅当你用同一码的不同大小写指向不同 Promotion 时才受影响生产环境使用默认 superadmin 密码将拒绝启动必须先修改外部认证账户关联要求邮箱已验证自定义AuthenticationStrategy需对已验证邮箱返回verified: trueemail-plugin的mjml从 v4→v5、nodemailer从 v6→v9使用 MJML 模板或自定义 transport 需复查nestjs/terminus不再是传递依赖v3.6 起已弃用外部组件健康检查自有健康检查代码需显式添加该依赖。v3.6.0Order/JobItem 新增索引、SettingsStore 新表均需非破坏性迁移Mollie 插件要求mollie/api-client4.3.3。v3.4.xSettingsStoreService方法ctx参数移到首位。v3.2.0DefaultCachePlugin需迁移给expiresAt列加precision(3)仅影响缓存记录。v3.1.0默认舍入逻辑修正——Math.round(value) * quantity改为Math.round(value * quantity)FacetValueChecker建议改用injector.get(FacetValueChecker)以获得缓存收益。v3.0.0所有核心包许可证切换为 GPL v3.0详见 LICENSE.md 与 license/license-faq.md。六、升级行动清单结合安全修复的落地建议综合 3.7.x 安全公告的“行为变化”章节升级时建议按以下清单执行配置层在生产环境为apiOptions.cors.origin设置显式白名单避免origin: truecredentials: true组合如需抵御 Login CSRF开启apiOptions.csrfPrevention: true并确认所有上传文件或 GET 查询的客户端发送Apollo-Require-Preflight头。数据层升级后清理已完结的任务数据历史 Job 记录可能含会话令牌并考虑使现有管理员会话失效更新assetOptions.permittedFileTypes中的旧 MIME 名称。密码层生产环境务必修改默认 superadmin 密码否则 v3.7.0 无法启动外部认证策略需为已验证邮箱返回verified: true。迁移层执行 3.6.0 的索引与 SettingsStore 建表迁移、3.2.0 的expiresAt精度迁移。依赖层复核mjmlv5 与nodemailerv9 的升级影响为自有健康检查代码显式引入nestjs/terminus。七、结语从 CHANGELOG.md 可以清晰看到 Vendure 3.x 的演进主线安全上从被动补洞走向主动加固启动期安全警告、CSRF 防护、渠道作用域强制、行级访问控制 API功能上从传统 Admin UI 转向 React 版 Dashboard 与 API Key 生态架构上通过*Strategy家族CustomerChannelAssignmentStrategy、OrderLineDiscountDistributionStrategy、EntityAccessControlStrategy把更多硬编码行为变成可插拔策略。对于维护多商户、多渠道 Vendure 实例的团队而言这份 CHANGELOG 本身就是一份不可多得的升级与安全审计手册结合仓库内 packages/core/src/get-api-security-warnings.ts 与 packages/core/src/config/auth/entity-access-control-strategy.ts 等源码阅读可以进一步验证文档描述与实际实现的一致性为生产环境的安全配置提供可靠依据。【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考