Rocket.Chat 许可证引擎rocket.chat/license深度解析V2/V3 校验、licenses API 与离线授权【免费下载链接】Rocket.ChatThe Secure CommsOS™ for mission-critical operations项目地址: https://gitcode.com/GitHub_Trending/ro/Rocket.Chat本指南以 Rocket.Chat 仓库中rocket.chat/license包的 CHANGELOG.md 为主干结合其在ee/packages/license/src及服务端 REST API 中的源码实现系统讲解 Rocket.Chat 企业许可证License的工作机制V2/V3 两种 JWT 许可格式与运行时兼容、licenses.*端点族的验证与预览能力、offline标志对隔离网络air-gapped工作区的保护以及ROCKETCHAT_LICENSE环境变量的应用优先级。读完你将能理解一次许可证从注入、校验到影响运行时的完整调用链并知道应查看哪些源码与测试来进一步深入。一、包定位rocket.chat/license在仓库中的角色rocket.chat/license是 Rocket.Chat 在 monorepoee/packages/下的私有工具包当前版本 1.2.0与 CHANGELOG 顶部一致其 package.json 中定义了对rocket.chat/core-typings类型定义、rocket.chat/jwtJWT 解析、rocket.chat/logger日志以及bcrypt加密校验的依赖并提供build/test/typecheck等标准脚本。从 src 目录 的源码结构可以清晰看出这个包的核心职责文件/目录职责license.ts/licenseImp.ts许可证管理器主体加载、解析、校验、应用与状态上报applyLicense.ts将许可证写入工作区持久化到Enterprise_License设置v2/convertToV3.ts将 V2 许可证在运行时转换为 V3 格式validation/校验逻辑模块、用户数限制、过期时间等AirGappedRestriction.ts无许可证隔离环境的限制逻辑MockedLicenseBuilder.ts测试用许可证构造器多个*.spec.ts与校验、模块、限制相关的单元测试也就是说CHANGELOG 并不是一份流水账——它记录的是这个许可证引擎从诞生到如今的真实功能演进。下面我们把其中带 PR 编号的功能条目逐一拆解并结合源码验证。二、License 的两种形态V2 与 V3以及运行时以 V3 为准在 0.1.0 版本条目中CHANGELOG 明确记载了本包引入时的核心设计Implemented the License library, it is used to handle the functionality like expiration date, modules, limits, etc. Also added a version v3 of the license, which contains an extended list of features. v2 is still supported, since we convert it to v3 on the fly.这段描述确立了整个 license 引擎的基石许可证是 JWT 承载的结构化数据通过rocket.chat/jwt解析与验签V3 是信息更全的新格式扩展了特性modules/limits 等清单V2 不会立刻被废弃——任何 V2 许可证在加载后会被即时转换为 V3后续逻辑统一以 V3 结构处理。源码印证这一设计的关键点有三处在 license.ts 中convertToV3从./v2/convertToV3导入作为设置许可证的必经步骤之一第 274 行setLicenseV3(convertToV3(newLicense), ...)在预览校验路径中第 365 行逻辑为encryptedLicense.startsWith(RCV3_) ? decrypted : convertToV3(decrypted)——即根据密文前缀RCV3_判断是否已是 V3否则走转换转换函数的实现位于 ee/packages/license/src/v2/convertToV3.ts它把ILicenseV2映射为ILicenseV3并补齐 V3 所需字段例如将offline置为false第 18 行。可以推断RCV3_前缀不仅是版本标识也是加密方式切换的标记V2/V3 许可证分别使用不同的加解密与验签流程包内v2/子目录与token.ts等文件正承担这些差异处理。这种入口处统一升级为最新结构的模式让上层消费方永远只需面对 V3 一种数据形态显著降低后续功能分支维护成本。三、许可证如何进入工作区应用链路与ROCKETCHAT_LICENSE许可证进入 Rocket.Chat 工作区有两条典型途径通过管理界面把字符串写入Enterprise_License系统设置以及通过ROCKETCHAT_LICENSE环境变量在启动时注入。后者对容器化/自动化部署尤为重要。服务端的接入点位于 apps/meteor/ee/server/lib/license/startup.tsawait applyNewestLicense( License, settings.getstring(Enterprise_License) ?? , process.env.ROCKETCHAT_LICENSE ?? , );这里依次读取两个来源已持久化在系统设置Enterprise_License中的旧许可与process.env.ROCKETCHAT_LICENSE提供的新许可再调用applyNewestLicense决定最终生效者。1.2.0 的 Patch 条目对应 PR #41472修复的正是这条链路上的一个问题Fixes the license provided via theROCKETCHAT_LICENSEenvironment variable not being applied when it is newer than the one persisted in the workspace.即此前当环境变量携带的许可证版本更新签发时间更晚于已持久化的许可证时环境变量版可能不会被正确采用。从applyNewestLicense的命名与传参顺序可以推断它的职责是比较两者并选择较新者应用——该修复确保较新的许可始终生效这一语义在环境变量场景下也成立。这意味着在升级/续期场景中运维只需在启动参数里覆盖ROCKETCHAT_LICENSE即可让新许可即时接管而无需进入管理界面手工更新。另一个佐证位于 enforceFipsLicense.ts当 FIPS 环境需要许可证时错误信息会直接引导用户 Provide your license through theROCKETCHAT_LICENSEenvironment variable进一步说明环境变量是官方推荐的注入通道之一。四、licenses.*REST 端点族查询、添加与预览校验许可证的 HTTP 接口集中在服务端文件 apps/meteor/ee/server/api/licenses.ts。结合 CHANGELOG端点是一步步长出来的0.1.0 引入licenses.info1.2.0 新增licenses.validate。目前共有四个端点4.1GET /api/v1/licenses.info——查询当前许可状态需要认证authRequired: true无limits/license详情除非调用者拥有view-privileged-setting权限支持查询参数loadValues仅在拥有特权时生效用于加载当前值如当前活跃用户数等运行时数据见 licenses.ts响应含license对象若调用者还有manage-cloud权限会附带cloudSyncAnnouncement来自系统设置Cloud_Sync_Announcement_Payload见第 92-104 行。4.2POST /api/v1/licenses.add——应用新许可需要edit-privileged-setting权限请求体为{ license: 许可证字符串 }先经License.validateFormat(license)校验格式第 123 行失败返回Invalid license成功后把许可证写入系统设置Enterprise_License并通过notifyOnSettingChangedById(Enterprise_License)广播变更第 134-135 行触发运行中的工作区热更新。4.3POST /api/v1/licenses.validate——预览校验而不落库1.2.0 新增这是 1.2.0 版本的核心功能条目PR #40916Adds a newlicenses.validateREST endpoint that validates a Rocket.Chat license (V2 or V3 JWT) against the current workspace without applying it, so a license can be previewed before it is applied from the UI. A valid license responds with success; an invalid one responds with the validation behaviors that rejected it.实现要点licenses.ts同样要求edit-privileged-setting权限与{ license: 字符串 }请求体服务端调用License.validateLicenseForPreview(license)校验失败返回{ success: false, error: license-invalid, reasons: [...] }其中reasons数组携带所有拒绝该校验的行为明细例如哪些模块或限制无法满足校验成功则只返回{ success: true }不会写入Enterprise_License。该端点对应的底层实现在 ee/packages/license/src/license.ts核心逻辑第 365 行同样是非RCV3_前缀则先convertToV3再校验与正式应用路径保持一致——这正是它能在 UI 上先试后买地预览新许可而不影响当前工作区的根基。配套的单元测试位于 validateLicenseForPreview.spec.ts其中覆盖了非许可证字符串被拒、管理器未就绪时抛NotReadyForValidation、以及经MockedLicenseBuilder构造的合法/非法许可的成败路径。4.4GET /api/v1/licenses.maxActiveUsers——最大活跃用户数读取License.getMaxActiveUsers()与Users.getActiveLocalUserCount()返回{ maxActiveUsers: number | null, activeUsers: number }当许可证未定义上限时maxActiveUsers为null。四个端点对应的请求/响应类型校验均由rocket.chat/rest-typings包提供如isLicensesInfoProps、isLicensesAddProps、isLicensesValidateProps等并使用 AJV 编译的响应 schema见 licenses.ts保证端点的入参与出参在类型层与运行时双重受控。五、offline标志与隔离网络air-gapped工作区5.1offline标志从源头掐断出站连接1.2.0PR #411481.2.0 的另一个 Minor 条目描述了离线标志的语义Adds support for theofflinelicense flag, suppressing every outbound connection to Rocket.Chat Cloud services and the Push Gateway at its source, so air-gapped workspaces never initiate calls that would violate their security compliance.这是面向安全合规的设计当许可证携带offline: true时工作区不应该发起任何指向 Rocket.Chat Cloud 服务或推送网关Push Gateway的出站调用且抑制动作发生在源头而非请求发出后拦截——对必须满足物理/逻辑隔离air-gapped合规的组织这一点至关重要。源码中的证据链条非常完整状态判断入口 license.tsreturn this.getLicense()?.information.offline ?? false;即无许可时默认不视为 offline 场景之外的一个独立布尔消费方确实是源头级抑制例如fetchMarketplaceApps.ts 注释明确offline 许可在发出任何请求之前即拒绝fetchMarketplaceCategories.ts 同样在请求前拒绝apps/communication/rest.ts 注明 offline 许可在源头抑制 marketplace 请求测试覆盖见 license.spec.ts包含无许可时不视为 offline标准许可不视为 offline带 offline 标志时上报为 offline移除许可后停止上报 offline四个用例测试构造器 MockedLicenseBuilder.ts 提供withOffline(offline true)链式方法第 180-182 行方便在单测中造出带离线标志的许可。5.2 无许可证的 air-gapped 限制1.0.0PR #332411.0.0 的 Major 条目记录了对无许可证的 air-gapped 环境施加限制Adds restrictions to air-gapped environments without a license。与之对应服务端存在 apps/meteor/ee/server/lib/license/airGappedRestrictions.ts它会维护系统设置Cloud_Workspace_AirGapped_Restrictions_Remaining_Days隔离环境剩余可用天数并在变化时通过notifyOnSettingChangedById通知前端包内的 AirGappedRestriction.ts 与其 spec 则承载核心判定逻辑。结合上文ROCKETCHAT_LICENSE的引导文案可以推断隔离网络下若没有合法许可工作区会进入受限模式并提示通过环境变量注入许可从而解锁完整能力。六、围绕许可的测试基座rocket.chat/license是策略敏感的包因此自带较完备的测试资产可作为二次开发与故障排查的入口license.spec.ts加载、offline 标志上报、模块行为等主流程validateLicenseForPreview.spec.tslicenses.validate所依赖的预览校验逻辑getLicenseLimit.spec.ts用户数等 limits 的读取modules.spec.ts 与 AirGappedRestriction.spec.ts模块启用与隔离限制MockedLicenseBuilder.ts在测试中快速构造 V2/V3 许可并签名。配合 license.ts 中约第 274、353、457 行的三个关键锚点应用、预览校验、offline 读取足以追完一条许可证注入 → 版本归一化 → 校验 → 影响运行时行为的完整链路。七、版本演进小结对照 CHANGELOG版本类型关键内容0.1.0Minor引入 License 库过期时间/模块/limits 处理新增 V3 许可格式V2 运行时即时转换新增licenses.info端点1.0.0Major对无许可的 air-gapped 环境施加限制支持读取许可证中的 add-ons1.1.xPatch修复企业许可生效时仍误弹 premium 弹窗等问题1.2.0Minor新增licenses.validate预览校验端点支持offline标志从源头抑制出站请求1.2.0Patch修复ROCKETCHAT_LICENSE环境变量在比已持久化许可更新时未被应用的问题说明CHANGELOG 中其余大量Updated dependencies [...]记录是由 Changesets 自动生成的依赖升级流水账本包主要依赖rocket.chat/core-typings的对应版本其意义是追踪包间版本同步关系并不代表本包自身行为变化阅读时可将它们视为版本指纹而非功能说明。八、进一步阅读许可证核心逻辑ee/packages/license/src/license.ts、licenseImp.tsV2→V3 转换ee/packages/license/src/v2/convertToV3.ts服务端许可证 APIapps/meteor/ee/server/api/licenses.ts启动注入与优先级apps/meteor/ee/server/lib/license/startup.ts隔离网络限制AirGappedRestriction.ts、airGappedRestrictions.ts测试与构造器license.spec.ts、validateLicenseForPreview.spec.ts、MockedLicenseBuilder.ts【免费下载链接】Rocket.ChatThe Secure CommsOS™ for mission-critical operations项目地址: https://gitcode.com/GitHub_Trending/ro/Rocket.Chat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考