Activepieces CE/EE 分层架构与 Edition Safety 规则实战:hooksFactory 扩展机制深度解析

原创2026-09-12 13:18:341,827 阅读
文章标签:工作流自动化低代码流程编排后端前端AI AgentMCP 服务人工智能企业应用自动化

Activepieces CE/EE 分层架构与 Edition Safety 规则实战:hooksFactory 扩展机制深度解析

本文围绕 Activepieces 仓库中 .claude/rules/edition-safety.md 这一开发规范文档展开,系统讲解 Community Edition(CE)与 Enterprise Edition(EE)两套代码层如何在同一仓库中共存、隔离与扩展:CE 代码为什么禁止 import EE 模块,以及 EE 如何通过 hooksFactory.create<T>(ceDefault) + .set(eeImpl) 的钩子机制无侵入地替换 CE 默认行为。读完本文,你将掌握 Activepieces 服务端的分层边界、edition 启动分支原理,以及如何为 CE 功能设计可被 EE 覆盖的扩展点。

一、规则文档在说什么:两条铁律

仓库 .claude/rules/edition-safety.md 全文只有两条约束,却是整个服务端分层架构的安全底线:

  1. CE 代码严禁 import src/app/ee/ 下的任何模块——CE 与 EE 是两个独立的代码层,不允许单向依赖,更不允许反向依赖;
  2. EE 扩展 CE 行为必须走钩子机制:在 CE 中用 hooksFactory.create<T>(ceDefault) 声明扩展点并给出默认实现,然后在 app.ts 的 edition 分支中通过 .set(eeImpl) 注入 EE 实现。

这两条规则共同保证:同一份代码库可以编译出 Community、Enterprise、Cloud 三种 edition 的产物,CE 代码在编译期不感知 EE 的存在,而 EE 可以在启动时按需替换 CE 的默认行为。

二、背景:CE 与 EE 如何在同一仓库中分层

在 packages/server/api/src/app 目录下,代码按功能模块组织为两类:

  • CE(Community Edition)层:即 src/app/ 下的常规模块,如 flows/、project/、authentication/、waitpoints/、flags/、webhooks/ 等,是开源可用的基础能力;
  • EE(Enterprise Edition)层:集中在 packages/server/api/src/app/ee 目录下,包含 authentication/project-role/(RBAC)、flags/enterprise-flags.hooks.ts、platform/platform-plan/(计费与套餐)、projects/project-release/(项目发布)、piece-filtering、license-key-usage-report(许可证用量上报)等企业级能力。

CE 代码被要求不得感知 EE 目录的存在。如果 CE 模块直接 import EE 模块,会造成两层强耦合:CE 的构建产物会意外携带 EE 代码、模块初始化顺序被破坏、单测环境可能因缺少 EE 依赖而崩溃。因此规则第一条是硬性的 import 禁令。

三、扩展点基座:hooksFactory 的实现原理

EE 想要在"不触碰 CE 代码"的前提下替换行为,靠的是 hooks-factory.ts 中定义的极简工厂:

import { isNil } from '@activepieces/core-utils'
import { FastifyBaseLogger } from 'fastify'

export const hooksFactory = {
    create<T>(defaultHooks: (log: FastifyBaseLogger) => T) {
        let hooksCreator: (log: FastifyBaseLogger) => T
        return {
            set(newHooksCreator: (log: FastifyBaseLogger) => T): void {
                hooksCreator = newHooksCreator
            },
            get(log: FastifyBaseLogger): T {
                if (isNil(hooksCreator)) {
                    return defaultHooks(log)
                }
                return hooksCreator(log)
            },
        }
    },
}

其工作方式非常直白:

  • create<T>(defaultHooks):CE 模块在定义扩展点时调用它,传入一个返回默认实现的工厂函数 (log) => T。返回值是一个带 set/get 两个方法的句柄,闭包变量 hooksCreator 初始为空;
  • set(newHooksCreator):EE 在应用启动阶段调用,把默认实现替换成自己的工厂函数;
  • get(log):业务代码运行时调用。若从未被 set 过(CE 场景),hooksCreator 为 nil,回退到默认实现;若被 set 过(EE/Cloud 场景),返回 EE 实现。

注意一个关键设计:defaultHooks 与 EE 实现都是惰性工厂函数,真正实例化发生在 get(log) 被调用时,且 FastifyBaseLogger 作为参数传入,使钩子实现可以拿到当前请求/进程的日志器。这种"先注册、后解析"的写法让 CE 模块永远不必知道 EE 是否存在。

四、接线中枢:app.ts 的 edition 切换

规则文档提到的 ".set(eeImpl) in app.ts edition switch",对应 app.ts 中的启动逻辑:

const edition = system.getEdition()
app.log.info({ edition }, 'Activepieces Edition')
switch (edition) {
    case ApEdition.CLOUD:
        await app.register(adminPlatformModule)
        // ... 大量企业级模块注册
        setPlatformOAuthService(platformOAuth2Service(app.log))
        projectHooks.set(projectEnterpriseHooks)
        flagHooks.set(enterpriseFlagsHooks)
        publishHooksFactory.set(eeFlowPublishHook)
        billingProvider.set(autumnBillingProvider)
        resumePageHooks.set((log) => ({ getTheme: (params) => appearanceHelper.getTheme({ ...params, log }) }))
        flowPublishHooks.set(() => ({ assertReferencesResolve: assertAgentsResolveInProject }))
        exceptionHandler.initializeSentry(system.get(AppSystemProp.SENTRY_DSN))
        break
    case ApEdition.ENTERPRISE:
        // 注册 subset 的企业模块 + 相同的 .set(...) 注入
        ...
        break
    // case ApEdition.COMMUNITY: 不注册企业模块,不调用任何 .set(...)
}

从源码结构可以推断,ApEdition 至少包含 CLOUD、ENTERPRISE 与 COMMUNITY 三种取值(具体枚举定义见 @activepieces/shared 的 edition 类型):

  • CLOUD / ENTERPRISE 分支:app.register(...) 注册一批企业级模块(如 projectMemberModule、gitRepoModule、auditEventModule、scimModule、flowApprovalModule、agentModule 等),并在注册完成后集中执行各个钩子的 .set(...) 注入 EE 实现;
  • COMMUNITY 分支:不注册企业模块,也不调用任何 .set(),所有钩子保持 CE 默认实现——这正是"同一份代码、三种产物"的开关所在。

这种"模块注册 + 钩子注入"双轨并行的写法,让 EE 能力既能以 Fastify 插件形式整体挂载(新增路由与表),也能以钩子形式替换既有 CE 行为(覆盖语义而不改路由)。

五、实战案例:流程发布钩子被 EE 覆盖为审批流

flow-publish-hooks.ts 是 hooksFactory 用法的典型范本。CE 侧在 flow-publish-hooks.ts 中定义类型与默认实现:

export type PublishRoute = 'PUBLISH_NOW' | 'NEEDS_APPROVAL'

export type PublishHooks = {
    routePublish(params: RoutePublishParams): Promise<PublishRoute>
    submitForApproval(params: SubmitForApprovalParams): Promise<void>
}

export const publishHooksFactory = hooksFactory.create<PublishHooks>(_log => ({
    async routePublish(_params: RoutePublishParams): Promise<PublishRoute> {
        return 'PUBLISH_NOW'
    },
    async submitForApproval(_params: SubmitForApprovalParams): Promise<void> {
        return
    },
}))

export const flowPublishHooks = hooksFactory.create<FlowPublishHooks>(() => ({
    async assertReferencesResolve(): Promise<void> {
        return
    },
}))

语义非常清晰:

  • CE 默认:发布路由直接返回 'PUBLISH_NOW'(一键发布),submitForApproval 为空操作,assertReferencesResolve 不做任何校验;
  • 当 edition 为 CLOUD/ENTERPRISE 时,app.ts 执行 publishHooksFactory.set(eeFlowPublishHook),把发布语义替换为:先 assertAgentsResolveInProject 校验 Agent 引用是否可解析,再由 EE 实现决定走 'PUBLISH_NOW' 还是 'NEEDS_APPROVAL',并落地 submitForApproval 审批提交流程——这正是 Activepieces 流程发布审批(flow approval)的企业能力。

对于想要在 CE 侧新增可扩展点的开发者,照此模式即可:先在 CE 定义好 XxxHooks 类型与 hooksFactory.create<XxxHooks>(默认实现),业务代码只调 .get(log),EE 侧在 app.ts 对应分支 .set(eeImpl) 覆盖。全程不需要 CE 与 EE 互相 import。

六、更多钩子实例:仓库中的同款模式

除流程发布外,仓库中还有多个遵循同一模式的扩展点,可作为补充印证:

  • project-hooks.ts:项目生命周期钩子,EE 侧由 ee-project-hooks.ts 通过 projectHooks.set(projectEnterpriseHooks) 注入(app.ts),用于承载企业版项目级校验与默认配置;
  • resume-page-hooks.ts:等待点恢复页面的主题钩子,Cloud 分支用 resumePageHooks.set((log) => ({ getTheme: (params) => appearanceHelper.getTheme({ ...params, log }) })) 注入企业外观主题(app.ts);
  • enterprise-flags.hooks.ts:企业功能开关钩子,通过 flagHooks.set(enterpriseFlagsHooks) 覆盖 CE 的 flag 默认值(app.ts);
  • billing-provider.ts:计费提供方钩子,Cloud 分支 billingProvider.set(autumnBillingProvider) 注入云计费实现(app.ts)。

由此可见,"CE 定义接口与默认行为、EE 在启动时替换实现"是贯穿整个服务端的企业扩展设计范式,并非某个模块的孤例。

七、开发实践:如何遵守 edition-safety 规则

把规则文档落到日常开发中,可以总结为如下检查清单:

  1. 定位你的改动:新增功能属于 CE 基础能力,还是 EE 企业能力?企业能力一律放入 packages/server/api/src/app/ee 对应模块下;
  2. 检查 import 方向:在 CE 目录(src/app/ 非 ee 子目录)的代码中,import ... from '../ee/...' 或 from './ee/...' 都属于违规依赖,应立即重构;
  3. 优先复用钩子:当 EE 需要改变某个 CE 行为时,不要修改 CE 文件,而是确认该模块是否已有 hooksFactory 扩展点;若没有,在 CE 侧新增 hooksFactory.create<T>(ceDefault),并让业务代码通过 .get(log) 调用;
  4. 接线放在 app.ts:在 app.ts 的 CLOUD / ENTERPRISE 分支中集中执行 .set(eeImpl),保持 edition 分支单一可信;
  5. 保持默认实现可用:CE 默认实现必须能独立支撑 Community 场景(如发布直接 PUBLISH_NOW、不校验、不审批),这样未 set 时系统依然可用;
  6. 验证隔离性:可用 rg "from ['\"]\.\./ee|from ['\"]\./ee" packages/server/api/src/app --glob '!**/ee/**' 之类的检索确认 CE 目录没有反向引用 EE 的 import。

八、小结

edition-safety.md 用两句话概括了 Activepieces 服务端最核心的架构纪律:依赖方向只能从 EE 指向 CE(通过启动期注入),CE 永不感知 EE。底层支撑是 hooks-factory.ts 的 create/set/get 三方法闭包工厂,配合 app.ts 中 system.getEdition() 驱动的 edition 分支集中接线,使 Community、Enterprise、Cloud 三种 edition 得以共享全部 CE 代码,同时让企业能力以可插拔、可测试的方式叠加。理解这套模式,是向 Activepieces 服务端贡献代码或扩展企业功能的前提,也是阅读 packages/server/api/src/app 目录代码时最快的导航地图。

登录后查看全文
activepieces