Activepieces 流程模板Templates体系深度解析实体模型、API 路由与多版本分发机制【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesActivepieces 的 Templates模板是一套可复用的流程Flow与数据表Table蓝图库用户可以在模板画廊中浏览、一键导入并在此基础上继续搭建自己的自动化流程。本文基于 brain/knowledge/flows-execution/templates.md 展开结合仓库源码深入讲解模板的实体设计、/v1/templatesAPI 全路由、三种模板类型OFFICIAL / CUSTOM / SHARED的权限模型、Cloud 与自托管CE/EE的差异分发机制以及模板入库前的校验与 pieces 提取流程。读完本文你将理解模板从创建、校验、存储、列表过滤到前端导入的完整调用链并能在自托管环境中正确配置与排障。一、Templates 是什么可复用的流程蓝图库在 Activepieces 中Templates 是用户可以直接浏览、导入并在此基础上继续构建的流程以及数据表蓝图集合。与从零搭建流程不同模板在保存之前会经过严格的校验并且其中的 piece组件名称会被提取出来写入一个可搜索的pieces数组以便用户在模板库中按包含哪些组件进行快速筛选。一句话概括模板 经过校验的 FlowVersionTemplate 集合 可检索的元数据名称、摘要、分类、标签、pieces。从源码结构看模板相关代码分布在以下模块均为仓库根目录相对路径服务端 APIpackages/server/api/src/app/template/controller、module、service、entity、validator、community-templates 云代理企业版扩展packages/server/api/src/app/ee/template/platform-template.service.ts共享类型定义packages/core/shared/src/lib/management/template/前端 API 客户端packages/web/src/features/templates/api/前端组件与路由packages/web/src/features/templates/components/、packages/web/src/app/routes/templates/二、核心数据模型Template 实体与三种类型2.1 Template 实体字段Template实体的 Zod schema 定义在 packages/core/shared/src/lib/management/template/template.ts主要字段如下字段类型说明namestring模板名称summarystring一句话摘要用于列表展示descriptionstring详细描述typeTemplateTypeOFFICIAL/CUSTOM/SHARED之一statusTemplateStatusPUBLISHED可见或ARCHIVED隐藏platformIdstring \| null所属平台null表示官方模板flowsFlowVersionTemplate[]jsonb内嵌的流程版本模板数组tablesTableTemplate[]jsonb可选的关联数据表模板tagsTemplateTag[]jsonb标签数组每个标签含title与colorcategoriestext[]带索引分类数组piecestext[]带索引从 flows 中提取的组件名数组blogUrlstring \| null关联的博客文章地址metadataMetadata \| nulljsonb任意元数据authorstring作者对应的 TypeORM 实体见 packages/server/api/src/app/template/template.entity.ts其中flows、tables、tags、metadata均以jsonb存储而categories与pieces是 PostgreSQL 原生数组列并建立了三个索引idx_template_pieces列piecesidx_template_categories列categoriesidx_template_platform_id列platformId实体还声明了与platform表的多对一关系onDelete: CASCADE当平台被删除时其 CUSTOM 模板会级联清理。2.2 TemplateTypeOFFICIAL / CUSTOM / SHARED三种类型的语义定义于 template.tsOFFICIAL由 Activepieces 官方策划AP-curatedplatformId null。在 Cloud 上直接存在数据库中在自托管版本中则通过社区模板代理从云端拉取见下文版本差异。CUSTOM平台自有的模板platformId指向创建它的平台需要平台计划标志manageTemplatesEnabled开启才能使用。SHARED通过一次性分享 URL 产生的临时分享模板不可被列表查询template.service.ts的list方法对 SHARED 类型直接抛出校验错误Shared templates are not supported to being listed。2.3 TemplateStatusPUBLISHED / ARCHIVEDPUBLISHED可见可被列表接口返回ARCHIVED隐藏。列表查询在服务层强制附加status PUBLISHED过滤条件见 template.service.ts因此归档模板不会出现在公开列表中。2.4 FlowVersionTemplate被剥离运行时字段的流程版本FlowVersionTemplate是FlowVersion的一个裁剪版本template.ts它通过omit去掉了运行时才需要的字段id、flowId、created、updated数据库标识与时间戳state运行状态updatedBy、agentIds、connectionIds、backupFilesnotes重新声明为可选以兼容旧版 JSON 模板这样得到的纯结构流程版本可以直接内嵌进模板行导入时再由前端/服务端重建为完整的 FlowVersion。与之配套的还有TableTemplate含name、externalId、fields、status、trigger、datadata支持 CSV 类型的TableDataState使模板可以携带预置的数据表结构。2.5 请求体 Schema创建、更新与列表查询的请求体定义在 packages/core/shared/src/lib/management/template/template.requests.tsCreateTemplateRequestBodyname、summary、description必填tagsTemplateTag[]、blogUrl、metadata可选author、categories必填type必填flowsFlowVersionTemplate[]可选。UpdateTemplateRequestBody所有字段均可选额外支持status用于发布/归档。ListTemplatesRequestQuerytype可选、pieces数组、tags数组、search、category均可选。三、API 路由全解析/v1/templates模板模块在 template.module.ts 中注册templateController挂载在/v1/templates前缀下。完整路由清单见 template.controller.ts方法路径说明安全级别GET/v1/templates/categories获取分类列表securityAccess.public()GET/v1/templates/:id按 ID 获取单个模板securityAccess.public()GET/v1/templates公开列表官方 自定义合并securityAccess.unscoped(ALL_PRINCIPAL_TYPES)POST/v1/templates创建模板securityAccess.publicPlatform([USER, SERVICE])POST/v1/templates/:id更新模板同上DELETE/v1/templates/:id删除模板仅平台所有者同上此外templateModule还注册了/v1/templates-telemetry前缀的遥测路由见 template-telemetry.controller.ts。3.1 GET /v1/templates/categories在Cloud版本中返回TEMPLATES_CATEGORIES标志位的值通过flagService读取见 flags/flag.service.ts在CE/EE自托管版本中转发到communityTemplates.getCategories()从云端拉取分类列表。3.2 GET /v1/templates/:id先尝试从本地数据库读取templateService.getOne若不存在非 Cloud 版本回退到communityTemplates.getOrThrow(id)从https://cloud.activepieces.com/api/v1/templates/:id代理获取Cloud 版本直接抛出ENTITY_NOT_FOUND。3.3 GET /v1/templates公开列表列表接口的核心逻辑在 template.controller.ts由两个函数拼接结果loadOfficialTemplatesOrReturnEmpty如果查询指定了type且不等于OFFICIAL直接返回空数组否则在 Cloud 上从本地库查询platformId null的官方模板在自托管上通过communityTemplates.list代理云端。loadCustomTemplatesOrReturnEmpty如果查询指定了type且不等于CUSTOM直接返回空数组否则解析 principal 的平台 ID——UNKNOWN/WORKER/ONBOARDING类型的 principal 没有平台返回空随后检查该平台计划的manageTemplatesEnabled标志未开启时静默返回空数组不报错。最终响应体为{ data: [...officialTemplates, ...customTemplates], next: null, previous: null }SeekPage 分页结构。3.4 POST /v1/templates创建创建接口的preValidation钩子会先对请求体中的flows执行migrateFlowVersionTemplateList迁移处理存量流程的 schema 演进再按类型分发CUSTOM要求当前用户必须是平台所有者platformMustBeOwnedByCurrentUserplatformId取当前 principal 的平台SHARED不做平台绑定OFFICIAL直接抛出校验错误Official templates are not supported to being created——官方模板只能由 Activepieces 后台维护。随后调用templateService.create返回201 Created。3.5 POST /v1/templates/:id更新与 DELETE /v1/templates/:id更新/删除前会先读取目标模板并按其类型做权限判定OFFICIAL与SHARED抛出AUTHORIZATION错误Cannot update official or shared templates/Cannot delete official or shared templates不可通过 API 修改或删除CUSTOM要求平台所有者身份并通过assertTemplateBelongsToPlatform二次校验template.platformId principal.platform.id不匹配则报Template does not belong to your platform。删除成功返回204 No Content。四、创建与校验template-validator 的 validateAndPrepare所有写入数据库的模板无论官方还是自定义都要经过 template-validator.ts 的validateAndPrepare校验其流程为flows 必填校验flows为空时抛出Flows are required。逐条重建最小 FlowVersioncreateMinimalFlowVersion用临时占位值id: temp-id、flowId: temp-flow-id、state: DRAFT、updatedBy: null等把FlowVersionTemplate还原成可操作的FlowVersion。执行 IMPORT_FLOW 操作构造FlowOperationType.IMPORT_FLOW请求交由flowVersionValidationUtil的prepareRequest做导入前的校验与规范化如组件/触发器的合法性检查再通过flowOperations.apply应用到最小 FlowVersion 上。PostgreSQL 安全净化对每个 flow 调用sanitizeObjectForPostgresql剔除不适合入库的运行时字段。提取 piecesflowPieceUtil.getUsedPieces(flow.trigger)遍历 trigger 树收集所有用到的 piece 名再经Set去重得到pieces数组——这正是列表接口按 pieces 过滤的数据来源。templateService.createtemplate.service.ts在拿到校验结果后根据类型分派OFFICIAL / SHARED 直接templateRepo().saveplatformId透传官方模板为 nullCUSTOM 则委托给 EE 的platformTemplateService().createplatform-template.service.ts后者同样写入template表但带上了platformId。更新路径类似只有flows非空时才重新执行validateAndPrepare并刷新piecesCUSTOM 模板的更新同样走 EE 服务其中对flows[0]重新提取pieces用于覆盖旧值。五、列表过滤机制ArrayOverlap / ArrayContains / ILIKEtemplateService.listtemplate.service.ts构建查询的方式非常典型是理解模板检索性能的关键pieces 过滤ArrayOverlap(pieces)——数组列与查询数组有交集即命中OR 语义利用idx_template_pieces索引category 过滤ArrayContains([category])——分类数组包含查询值AND 语义利用idx_template_categories索引type platformId 过滤OFFICIAL 要求platformId IS NULLCUSTOM 要求传入platformId缺失直接报校验错误且两者都附加type等值条件status 过滤恒为Equal(TemplateStatus.PUBLISHED)归档模板不出现在列表中tags 过滤由于tags是 jsonb 数组使用原生 SQL 子查询(SELECT array_agg(tag-title) FROM jsonb_array_elements(template.tags) tag) :tags::text[]实现标签标题集合包含匹配search 模糊搜索(template.name ILIKE :search OR template.summary ILIKE :search OR template.description ILIKE :search)search参数被包裹成%...%通配符。响应通过paginationHelper.createPage(templates, null)包装成{ data, next, previous }的 SeekPage 结构。值得注意的是前端搜索输入有 300ms 防抖见 templates-hook.ts 中的useDebounce(search, 300)并且列表/分类数据带有 5 分钟staleTime缓存。六、版本差异Cloud 直存 vs 自托管云端代理官方模板的存储方式随发行版本不同而不同这是模板体系最需要注意的差异点见 community-templates.service.tsCloud官方模板直接存在于 Cloud 的数据库中platformId null列表与单查均走本地库CE / EE自托管官方模板不落本地库而是在请求时通过communityTemplates代理到https://cloud.activepieces.com/api/v1/templates列表、单查、分类三类接口均代理返回结构原样透传。因此自托管实例在离线或无法访问cloud.activepieces.com时官方模板画廊将不可用但 CUSTOM 模板不受影响。同时自托管实例还会通过sendToCloud把模板遥测事件回传给 Cloud 的同一路由详见第八节形成本地浏览器 → 本地 API → Cloud API的两级链路。七、CUSTOM 模板与 manageTemplatesEnabled 计划标志自定义模板是平台Platform级别的能力受订阅计划控制创建、更新、删除 CUSTOM 模板均要求调用者同时满足平台所有者身份与模板属于该平台两个条件列表接口在返回 CUSTOM 模板前会通过platformService.getOneWithPlanOrThrow检查platform.plan.manageTemplatesEnabled未开启时静默返回空数组template.controller.ts——这是文档中特别强调的 Gotcha不会报错只会看起来没有自定义模板该标志在 CE 中默认关闭需要平台计划开启后才能使用自定义模板功能OFFICIAL 与 CUSTOM 的差异在列表接口中体现为loadOfficialTemplatesOrReturnEmpty不受任何计划标志约束而loadCustomTemplatesOrReturnEmpty受manageTemplatesEnabled约束。八、模板遥测/v1/templates-telemetry/event 的双重调用方POST /v1/templates-telemetry/eventtemplate-telemetry.controller.ts是一个容易被误判的路由它同时服务两类调用方只有其中一方是中继角色不能按发行版本或简单开关来放行本地浏览器直接上报路由是securityAccess.public()前端 templates-telemetry-api.ts 直接向它 POSTVIEW、INSTALL、EXPLORE_VIEW三类事件共四个调用点自托管向 Cloud 中继自托管实例通过sendToCloud把事件转发到 Cloud 的同名路由。由于VIEW/INSTALL/EXPLORE_VIEW只走这一条路径如果把该路由当作已被上游同意过的中继跳而直接放行就会让所有选择退出遥测的自托管用户的事件被静默解锁。因此控制器通过platformUtils.getPlatformIdForRequest解析请求对应的平台服务层在该平台行存在时按其设置门控而platformId为 null 表示真正的中继场景Cloud 上无 principal 的请求其projectId/templateId属于发送方部署的数据库此时才原样转发。另外ACTIVATE/DEACTIVATE事件来自trigger-source-service携带真实projectId通过项目维度门控。实现细节上sendToCloud/sendToInternal使用的是原生fetch而非safeHttp/apAxios这是既有实现之所以安全是因为两个 URL 均为硬编码。九、前端集成从浏览到导入的完整交互前端模板体验由三部分组成见 packages/web/src/features/templates/API 客户端templates-api.ts 封装了getTemplate、create、update、list、delete、getCategories六个方法分别对应上文六个后端路由数据层 hookstemplates-hook.ts 基于 TanStack Query 提供useTemplateCategories5 分钟缓存、useTemplate、useAllOfficialTemplates、useTemplates带防抖搜索 分类筛选状态同步到 URL query 参数以及useCreateTemplate/useUpdateTemplate/useBulkDeleteTemplate三个 mutation成功后失效custom-templates缓存并 toast 提示UI 组件components/ 下包括模板浏览对话框templates-browse-dialog.tsx、导入模板对话框use-template-dialog.tsx、分享模板share-template.tsx和探索卡片explore-template-card.tsx公开画廊页面packages/web/src/app/routes/templates/ 提供模板画廊入口页index.tsx、分类视图all-categories-view.tsx、selected-category-view.tsx、category-section.tsx、category-filter-carousel.tsx与空态视图empty-templates-view.tsx。在 Web 端模板导入本质上就是将模板中的FlowVersionTemplate重建为真实 FlowVersion 并写入当前项目的过程——服务端已经保证入库的模板 flows 是纯净结构前端只需补齐运行时字段即可。十、Gotchas 清单模板体系的关键注意事项结合知识库文档与源码以下是最容易踩坑的点自定义模板依赖计划标志manageTemplatesEnabled关闭时CUSTOM 列表静默返回空数组、无任何报错排查看不到自定义模板问题时先检查平台计划。OFFICIAL / SHARED 不可变二者无法通过 API 更新或删除对 CUSTOM 的写操作会双重校验平台归属template.platformId principal.platform.id。SHARED 不可列出list接口对 SHARED 类型直接抛VALIDATION错误分享模板只能通过分享 URL 定向访问。自托管依赖云端CE/EE 的官方模板、分类均实时代理自cloud.activepieces.com网络不可达时官方模板功能不可用。schema 迁移创建/更新的preValidation钩子会执行migrateFlowVersionTemplateList见 flows/flow-version/migrations/index.ts用于处理存量流程版本的结构演进写入前完成迁移可避免历史模板导入失败。性能设计pieces与categories是反规范化denormalized 索引化的数组列专为高频过滤查询设计tags走 jsonb 数组聚合查询。列表只返回PUBLISHED状态模板。十一、关键文件索引服务端入口template.module.ts、template.controller.ts、template.service.ts校验器template-validator.ts实体与索引template.entity.ts云端代理community-templates.service.tsEE 自定义模板platform-template.service.ts遥测template-telemetry.controller.ts及其同目录 service共享类型与请求 schemapackages/core/shared/src/lib/management/template/前端客户端 / 组件 / hooks / 画廊路由packages/web/src/features/templates/、packages/web/src/app/routes/templates/【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考