新闻详情

新闻详情

首页 / 资讯中心 / 详情

Ever Gauzy × ActivePieces 自动化集成插件全指南:连接与 MCP Server 管理实战

发布时间:2026/11/22 11:56:05来源:尧图网络
Ever Gauzy × ActivePieces 自动化集成插件全指南:连接与 MCP Server 管理实战
后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载本篇技术指南以 integration-activepieces/README.md 为骨架深入剖析 Ever Gauzy 与 ActivePieces 自动化平台之间的官方集成插件gauzy/plugin-integration-activepieces。文章覆盖插件的安装、构建、测试与发布流程并基于仓库源码逐项拆解「连接管理」与「MCP Server 管理」两大核心能力对应的 REST 接口、配置项与底层实现原理。读完本文你将能够在自己的 NestJS / Ever Gauzy 应用中完成 ActivePieces 集成配置、连接资源的增删查改以及 MCP Server 的更新与令牌轮换。一、插件概览为 Ever Gauzy 接入 ActivePieces 自动化平台ActivePieces 是一个开源的 AI 自动化平台允许用户通过可视化流程Flows把各类应用与 AI Agent 串联起来。Ever Gauzy开源商业管理平台覆盖 ERP/CRM/HRM/ATS/PM 等模块通过本插件以租户Tenant维度管理 ActivePieces 上的资源所有 API 调用统一使用 ActivePieces 平台的 API Key 进行鉴权——该能力按官方说明需要ActivePieces Platform / Enterprise 版本才能使用。插件在 activepieces.module.ts 中声明为标准的 NestJS 模块并对外提供两类能力能力域服务控制器功能连接管理Connection Managementactivepieces.service.tsactivepieces.controller.ts为 Ever-gauzy piece 创建、列出、查询、删除 ActivePieces 应用连接MCP Server 管理activepieces-mcp.service.tsactivepieces-mcp.controller.ts列出、更新、轮换 ActivePieces MCP Server 的令牌模块依赖方面插件同时引入了gauzy/core中的集成基础设施IntegrationModule、IntegrationTenantModule、IntegrationSettingModule、IntegrationMapModule等以及RoleModule/RolePermissionModule/UserModule等核心模块并通过HttpModule.register({ baseURL: ACTIVEPIECES_API_URL })统一向 ActivePieces API 发起 HTTP 请求。作为 Gauzy 插件体系的成员integration-activepieces.plugin.ts 使用Plugin()装饰器注册实现IOnPluginBootstrap与IOnPluginDestroy生命周期接口在插件启动与销毁时输出日志同时暴露configuration回调允许对主插件配置对象进行自定义修改后再返回。二、环境变量与全局配置插件运行依赖两类全局配置均在 activepieces.config.ts 与 config/activepieces.ts 中定义配置项环境变量默认值说明ACTIVEPIECES_BASE_URLACTIVEPIECES_BASE_URLhttps://cloud.activepieces.comActivePieces 平台根地址自托管部署时可替换apiKeyGAUZY_ACTIVEPIECES_API_KEY空字符串全局 API Key作为租户级 Key 缺失时的兜底由默认值推导出的 API 路径如下API 根地址{ACTIVEPIECES_BASE_URL}/api/v1连接端点{API}/app-connectionsMCP Server 端点{API}/mcp-serversPiece 名称常量Ever-gauzy连接创建时使用的 pieceName环境变量GAUZY_ACTIVEPIECES_API_KEY同时在 environment.ts 与 environment.prod.ts 中被读取并通过registerAs(activepieces)注册到 NestJS Config 体系供服务层以this.configService.get(activepieces)?.apiKey的方式访问。三、安装、注册与集成初始化3.1 安装插件使用你偏好的包管理器安装npm install gauzy/plugin-integration-activepieces # 或 yarn add gauzy/plugin-integration-activepieces从 package.json 可以看出该包的运行时约束Node.js22、Yarn1.22peerDependencies 为nestjs/common与nestjs/core^11.1.26内部依赖gauzy/common、gauzy/config、gauzy/contracts、gauzy/core、gauzy/plugin、gauzy/utils等平台包并以nestjs/axiosaxios作为 HTTP 客户端rxjs处理异步请求流。3.2 在应用中注册插件对外导出IntegrationActivepiecesPlugin见 src/index.ts将其加入应用的插件集合即可完成挂载import { IntegrationActivepiecesPlugin } from gauzy/plugin-integration-activepieces; // 应用配置 plugins 数组中追加 plugins: [ IntegrationActivepiecesPlugin ]3.3 通过 REST 接口初始化集成注册完成后调用POST /api/integration/activepieces/setup并携带 API Key 完成租户级初始化需要INTEGRATION_ADD权限{ apiKey: sk-..., organizationId: 可选不传则按租户维度保存 }请求体由 SetupActivepiecesIntegrationDto 校验apiKey为必填字符串。服务端在 activepieces.service.ts 的setupIntegration()中完成三件事按provider ACTIVE_PIECES查找或创建全局集成记录Integration在当前租户下查找或创建「集成租户」IntegrationTenant并写入api_key与is_enabledtrue两个设置项若租户已存在集成记录则对既有设置做原地合并更新保留数据库主键而非重复插入。成功后返回{ integrationTenantId: ... }该 ID 是后续所有连接与 MCP 管理接口的入参。四、连接管理Connection Management详解连接管理的所有接口都挂在Controller(/integration/activepieces)下见 activepieces.controller.ts并统一受TenantPermissionGuard与Permissions装饰器双重保护。4.1 创建 / 更新连接UpsertPOST /api/integration/activepieces/connection请求体由 CreateActivepiecesIntegrationDto 定义字段必填说明accessToken是ActivePieces 访问令牌示例ap_1234567890abcdefprojectId是连接将被创建到的 ActivePieces 项目 ID示例proj_1234567890abcdefconnectionName否连接显示名缺省时使用Ever Gauzy - {tenantId}服务端upsertConnection()activepieces.service.ts会构造标准 upsert 请求体并 POST 到/app-connectionsexternalIdgauzy-tenant-{tenantId}若传了organizationId则追加-org-{organizationId}作为当前租户的唯一外部标识pieceName固定为Ever-gauzytypeSECRET_TEXTvalue.secret_text承载 accessTokenmetadata写入tenantId、organizationId缺省为default、createdAtISO 时间戳与gauzyVersion: 1.0.0供后续按租户过滤使用。成功后插件会把access_token、connection_id、project_idJSON 数组序列化与is_enabledtrue持久化到当前租户的集成设置中并返回 ActivePieces 的连接对象额外附带integrationId。4.2 列出连接GET /api/integration/activepieces/connections/:integrationId查询参数由 ActivepiecesConnectionsListQueryDto 校验参数必填约束 / 默认值说明projectId是非空字符串目标项目 IDcursor否字符串分页游标scope否枚举ActivepiecesConnectionScope当前仅PROJECT连接范围pieceName否字符串按 piece 名过滤displayName否字符串按显示名过滤status否枚举ActivepiecesConnectionStatusACTIVE/ERROR按状态过滤limit否整数1–100默认 10返回条数4.3 查询与删除接口说明GET /integration/activepieces/connections/tenant/:integrationId/:projectId获取当前租户自己的连接列表服务端拉取项目连接后用metadata.tenantId 当前租户ID二次过滤GET /integration/activepieces/connection/:integrationId读取集成租户设置中的connection_id随后向 ActivePieces 拉取单条连接详情DELETE /integration/activepieces/connection/:integrationId删除连接需要INTEGRATION_DELETE权限返回 204未找到连接记录时返回 4044.4 状态查询与集成信息GET /integration/activepieces/status/:integrationId读取is_enabled设置兼容布尔与 JSON 字符串两种存储形态返回{ enabled: true | false }GET /integration/activepieces/integration-tenant/:integrationId返回包含integration与settings关联关系的集成租户完整信息。五、MCP Server 管理详解MCPModel Context ProtocolServer 管理接口挂在Controller(/integration/activepieces/mcp)下见 activepieces-mcp.controller.ts核心服务实现位于 activepieces-mcp.service.ts。方法路径权限说明GET/integration/activepieces/mcp?projectId...INTEGRATION_VIEW按项目列出 MCP Server支持limit、cursor、name过滤GET/integration/activepieces/mcp/tenant?projectId...INTEGRATION_VIEW返回当前租户的 MCP Server按名称包含租户 ID 或gauzy过滤GET/integration/activepieces/mcp/:serverIdINTEGRATION_VIEW查询单个 ServerserverId缺失或为空时返回 400PATCH/integration/activepieces/mcp/:serverIdINTEGRATION_EDIT更新 Server 名称与工具列表POST/integration/activepieces/mcp/:serverId/rotateINTEGRATION_EDIT轮换 Server 令牌请求体为空更新请求体由 ActivepiecesMcpUpdateDto 定义name非空字符串与tools非空数组均可选每个 tool 项支持id、type、pieceMetadata对象与flowId字段且字符串字段会先trim再校验。服务端通过POST请求${MCP_SERVERS_URL}/{serverId}与${MCP_SERVERS_URL}/{serverId}/rotate完成更新与令牌轮换。安全细节所有 MCP 相关响应在返回前都会经过sanitizeMcpServer()处理——用解构方式剔除token字段只把公开数据id、name、projectId、tools等暴露给调用方。该脱敏逻辑与 contracts 中定义的IActivepiecesMcpServerPublic类型OmitIActivepiecesMcpServer, token一一对应。MCP 服务在底层封装了统一的request()帮助方法activepieces-mcp.service.ts统一注入Authorization: Bearer {apiKey}请求头、设置8 秒超时并把 Axios 错误统一转换为HttpException。六、API Key 解析顺序与错误处理两个服务都实现了「租户优先、全局兜底」的 API Key 解析策略见 activepieces.service.ts若传入integrationTenantId先查询当前租户下该集成租户的设置命中api_key则直接使用未命中时回退读取全局配置configService.get(activepieces)?.apiKey即GAUZY_ACTIVEPIECES_API_KEY两者皆无则抛出InternalServerErrorException提示设置环境变量或先执行setupIntegration。值得一提的容错逻辑在upsertConnection()中即使当前租户尚未执行过setupIntegration找不到集成租户插件也不会中断而是记录 warning 并回退到全局GAUZY_ACTIVEPIECES_API_KEY继续调用 ActivePieces API。错误处理上服务层对 HTTP 调用使用 RxJS 的catchError管道401 响应映射为UnauthorizedException其他响应包装为InternalServerErrorException/HttpException并保留原始状态码与错误消息来自error.response.data.error.message。七、数据模型与设置项Contracts 层插件依赖的 ActivePieces 数据模型集中在 packages/contracts/src/lib/activepieces-integration-config.model.ts主要包括连接类型ActivepiecesConnectionTypeSECRET_TEXT、OAUTH2、CLOUD_OAUTH2、PLATFORM_OAUTH2、BASIC_AUTH、CUSTOM_AUTH。本插件创建连接时固定使用SECRET_TEXT。连接范围ActivepiecesConnectionScope当前仅PROJECT。连接状态ActivepiecesConnectionStatusACTIVE、ERROR。持久化设置名ActivepiecesSettingName插件在集成租户的settings表中使用以下键名设置名枚举值用途API_KEYapi_key租户级 API KeyACCESS_TOKENaccess_token连接访问令牌REFRESH_TOKENrefresh_token刷新令牌预留TOKEN_TYPE/EXPIRES_IN/EXPIRES_AT同名令牌元数据预留CONNECTION_IDconnection_idActivePieces 连接 IDPROJECT_IDproject_id项目 ID 数组JSON 序列化IS_ENABLEDis_enabled集成启用标记CLIENT_ID/CLIENT_SECRET/CALLBACK_URL/POST_INSTALL_URL/STATE_SECRET同名OAuth 流程预留字段连接对象IActivepiecesConnection完整字段包括id、created、updated、externalId、displayName、type、pieceName、projectIds、platformId、scope、status、ownerId、owner、metadata、flowIds、integrationId。MCP Server 对象IActivepiecesMcpServer则包含id、created、updated、name、projectId、token、agentId、tools每个 tool 带pieceMetadata与flow信息。八、构建、测试与发布该插件在 Nx 工作区中注册为库项目plugin-integration-activepieces见 project.json构建产物输出到dist/packages/plugins/integration-activepieces。8.1 构建yarn nx build plugin-integration-activepieces构建使用nx/js:tscexecutormain指向 src/index.ts并把包内*.md作为资产一并拷贝到产物目录。8.2 运行单元测试yarn nx test plugin-integration-activepieces测试由nx/jest:jestexecutor 驱动使用仓库统一的 jest.config.ts 配置。8.3 发布构建完成后进入产物目录执行 npm 发布cd dist/packages/plugins/integration-activepieces npm publish该包以gauzy/plugin-integration-activepieces当前版本0.1.0命名遵循 AGPL-3.0 许可协议。九、从源码结构看实现要点与使用限制租户隔离是设计主线从 externalId 命名规则gauzy-tenant-{tenantId}、连接的 metadata 租户标记到getTenantConnections()/getTenantMcpServers()的二次过滤插件的所有资源操作都以当前请求上下文RequestContext.currentTenantId()为边界可安全运行在多租户部署中。双重鉴权HTTP 层使用 ActivePieces API KeyBearer头调用外部平台Ever Gauzy 侧则依赖TenantPermissionGuard与INTEGRATION_ADD/INTEGRATION_VIEW/INTEGRATION_EDIT/INTEGRATION_DELETE权限控制接口访问。面向自托管可配置通过ACTIVEPIECES_BASE_URL环境变量即可指向私有部署的 ActivePieces 实例GAUZY_ACTIVEPIECES_API_KEY则用于提供全局兜底密钥。使用前提按照 README 说明平台级 API Key 仅在 ActivePieces 的 Platform / Enterprise 版本中可用社区自托管部署是否支持取决于你所使用的 ActivePieces 版本能力。十、快速验证流程实战清单安装插件包并在 Ever Gauzy 应用中注册IntegrationActivepiecesPlugin设置环境变量GAUZY_ACTIVEPIECES_API_KEY或调用POST /integration/activepieces/setup保存租户级 Key调用POST /integration/activepieces/connection创建 Ever-gauzy piece 的连接SECRET_TEXT类型保存返回的integrationId通过GET /integration/activepieces/connections/:integrationId?projectId...核对连接列表通过GET /integration/activepieces/mcp?projectId...查看 MCP Server用PATCH /:serverId更新配置用POST /:serverId/rotate轮换令牌运行yarn nx test plugin-integration-activepieces验证插件行为再按需执行构建与发布流程。赞分享后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载相关推荐在 Ever Gauzy 中集成 Activepiecesgauzy/plugin-integration-activepieces-ui 插件深度解析在 Ever Gauzy 中集成 Activepiecesgauzy/plugin integration activepieces ui 插件深度解析 导后端前端企业应用MCP 服务Cog 机器学习模型容器化实战从 cog.yaml 到生产级 HTTP 推理服务Cog 机器学习模型容器化实战从 cog.yaml 到生产级 HTTP 推理服务 Cog 是一个面向机器学习模型的开源容器化工具让你用一份 cog.yaml后端前端企业应用MCP 服务在 Modal 无服务器 GPU 上按需部署 Tabby完整实操指南在 Modal 无服务器 GPU 上按需部署 Tabby完整实操指南 Modal 是一个 serverless GPU 平台通过它运行 Tabby 可以实现后端前端企业应用MCP 服务上一篇Go 夜读Go 开发者 Vim 环境配置全解析.vimrc 完整方案下一篇rn-fetch-blob开发者进阶手册自定义配置与扩展开发创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/21 14:14:45

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/21 14:14:26

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/21 21:08:55

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/22 1:51:41

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/21 19:02:25

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/21 14:13:11

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉