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

• 后端
• 前端
• 企业应用
• MCP 服务

本篇技术指南以 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 模块，并对外提供两类能力：

模块依赖方面，插件同时引入了@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 中定义：

由默认值推导出的 API 路径如下：

• API 根地址：{ACTIVEPIECES_BASE_URL}/api/v1
• 连接端点：{API}/app-connections
• MCP Server 端点：{API}/mcp-servers
• Piece 名称常量：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.js>=22、Yarn>=1.22，peerDependencies 为@nestjs/common与@nestjs/core（^11.1.26），内部依赖@gauzy/common、@gauzy/config、@gauzy/contracts、@gauzy/core、@gauzy/plugin、@gauzy/utils等平台包，并以@nestjs/axios+axios作为 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()中完成三件事：

1. 按provider = ACTIVE_PIECES查找或创建全局集成记录（Integration）；
2. 在当前租户下查找或创建「集成租户」（IntegrationTenant），并写入api_key与is_enabled=true两个设置项；
3. 若租户已存在集成记录，则对既有设置做原地合并更新（保留数据库主键），而非重复插入。

成功后返回{ "integrationTenantId": "..." }，该 ID 是后续所有连接与 MCP 管理接口的入参。

四、连接管理（Connection Management）详解

连接管理的所有接口都挂在@Controller('/integration/activepieces')下（见 activepieces.controller.ts），并统一受TenantPermissionGuard与Permissions装饰器双重保护。

4.1 创建 / 更新连接（Upsert）

POST /api/integration/activepieces/connection

请求体由 CreateActivepiecesIntegrationDto 定义：

服务端upsertConnection()（activepieces.service.ts）会构造标准 upsert 请求体并 POST 到/app-connections：

• externalId：gauzy-tenant-{tenantId}，若传了organizationId则追加-org-{organizationId}，作为当前租户的唯一外部标识；
• pieceName：固定为Ever-gauzy；
• type：SECRET_TEXT，value.secret_text承载 accessToken；
• metadata：写入tenantId、organizationId（缺省为'default'）、createdAt（ISO 时间戳）与gauzyVersion: '1.0.0'，供后续按租户过滤使用。

成功后，插件会把access_token、connection_id、project_id（JSON 数组序列化）与is_enabled=true持久化到当前租户的集成设置中，并返回 ActivePieces 的连接对象（额外附带integrationId）。

4.2 列出连接

GET /api/integration/activepieces/connections/:integrationId

查询参数由 ActivepiecesConnectionsListQueryDto 校验：

4.3 查询与删除

4.4 状态查询与集成信息

• GET /integration/activepieces/status/:integrationId：读取is_enabled设置（兼容布尔与 JSON 字符串两种存储形态），返回{ "enabled": true | false }；
• GET /integration/activepieces/integration-tenant/:integrationId：返回包含integration与settings关联关系的集成租户完整信息。

五、MCP Server 管理详解

MCP（Model Context Protocol）Server 管理接口挂在@Controller('/integration/activepieces/mcp')下（见 activepieces-mcp.controller.ts），核心服务实现位于 activepieces-mcp.service.ts。

更新请求体由 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类型（Omit<IActivepiecesMcpServer, 'token'>）一一对应。

MCP 服务在底层封装了统一的request()帮助方法（activepieces-mcp.service.ts）：统一注入Authorization: Bearer {apiKey}请求头、设置8 秒超时，并把 Axios 错误统一转换为HttpException。

六、API Key 解析顺序与错误处理

两个服务都实现了「租户优先、全局兜底」的 API Key 解析策略（见 activepieces.service.ts）：

1. 若传入integrationTenantId，先查询当前租户下该集成租户的设置，命中api_key则直接使用；
2. 未命中时回退读取全局配置configService.get('activepieces')?.apiKey（即GAUZY_ACTIVEPIECES_API_KEY）；
3. 两者皆无则抛出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，主要包括：

连接类型ActivepiecesConnectionType：SECRET_TEXT、OAUTH2、CLOUD_OAUTH2、PLATFORM_OAUTH2、BASIC_AUTH、CUSTOM_AUTH。本插件创建连接时固定使用SECRET_TEXT。

连接范围ActivepiecesConnectionScope：当前仅PROJECT。

连接状态ActivepiecesConnectionStatus：ACTIVE、ERROR。

持久化设置名ActivepiecesSettingName：插件在集成租户的settings表中使用以下键名：

连接对象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:tscexecutor，main指向 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 Key（Bearer头）调用外部平台；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 版本能力。

十、快速验证流程（实战清单）

1. 安装插件包并在 Ever Gauzy 应用中注册IntegrationActivepiecesPlugin；
2. 设置环境变量GAUZY_ACTIVEPIECES_API_KEY，或调用POST /integration/activepieces/setup保存租户级 Key；
3. 调用POST /integration/activepieces/connection创建 Ever-gauzy piece 的连接（SECRET_TEXT类型），保存返回的integrationId；
4. 通过GET /integration/activepieces/connections/:integrationId?projectId=...核对连接列表；
5. 通过GET /integration/activepieces/mcp?projectId=...查看 MCP Server，用PATCH /:serverId更新配置，用POST /:serverId/rotate轮换令牌；
6. 运行yarn nx test plugin-integration-activepieces验证插件行为，再按需执行构建与发布流程。

• 后端
• 前端
• 企业应用
• MCP 服务