Activepieces Platform 配置深度解析顶层租户模型、品牌与认证管理以及平台删除的级联清理机制【免费下载链接】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/activepiecesPlatform平台是 Activepieces 中最顶层的租户命名空间每一个安装实例至少拥有一个 Platform它统管品牌形象Logo、颜色、favicon、认证设置邮箱登录开关、允许登录域名、联邦 SSO以及通过PlatformPlan驱动的功能开关与配额限制。本文基于仓库内brain/knowledge/platform-editions-ee/platform-configuration.md文档结合服务端、共享模型与前端源码完整梳理 Platform 的实体模型、服务层方法、REST 端点、前端交互细节以及平台删除时先切断、后清理的两拍式 teardown 机制帮助你彻底掌握在 Activepieces 中配置与运维平台租户的能力。一、Platform 是什么所有版本通用的顶层租户在 Activepieces 的租户模型中Platform 是最高一级的命名空间。每个安装至少有一个平台它拥有三类核心资产品牌BrandingLogo、主题颜色、favicon认证Auth邮箱登录开关emailAuthEnabled、允许登录的域名列表allowedAuthDomains、联邦 SSOOAuth2 SAML套餐PlatformPlan驱动功能开关feature flags与配额限制limits。从版本分布看Cloud 上一个用户可以拥有多个平台多租户CE/EE 自托管部署通常只有一个平台。该功能在所有版本中均可用Available in all editions只是不同版本开放的能力不同——例如 CE 使用固定的OPEN_SOURCE_PLAN而usage用量数据只在非 Community 版本返回。实体与字段platform实体承载的核心字段如下完整 zod 模型见 platform.model.tsTypeORM 实体见 platform.entity.ts字段类型说明ownerIdApId平台所有者用户 ID指向user表namestring平台名称primaryColorstring主色十六进制themeColorsjsonb, nullable完整主题色为null时从前端品牌派生默认主题logoIconUrl/fullLogoUrl/favIconUrlstring品牌图片 URLcloudAuthEnabled/googleAuthEnabledboolean云认证 / Google 认证开关默认trueemailAuthEnabledboolean邮箱登录开关allowedAuthDomainsstring[]允许登录的域名白名单enforceAllowedAuthDomainsboolean是否强制校验允许域名allowedEmbedOriginsstring[]允许嵌入的来源embed 白名单ssoDomain/ssoDomainVerificationstring / jsonbSSO 域名及其校验状态federatedAuthProvidersjsonb联邦认证配置OAuth2 SAML列定义中select: false默认不随查询返回autoCreatePersonalProjectsboolean登录后是否自动创建个人项目默认truepinnedPiecesstring[]置顶的 piece 列表pieceSelectorConfigjsonb, nullablePiece 选择器配置为null时使用默认标签页需要特别注意的是federatedAuthProviders在 platform.entity.ts 中带有select: false即普通查询默认不会读取它只有显式addSelect才能拿到对应服务层的getOneWithFederatedAuthOrThrow。此外实体上还有两个约束值得留意ssoDomain上有唯一索引idx_platform_sso_domain仅在非 NULL 时生效ownerId → user的外键是ON DELETE RESTRICT这条约束直接决定了平台删除时的顺序详见后文。默认值与创建流程创建平台时服务层会写入一组确定的默认值见 platform.service.tsprimaryColor缺省为defaultTheme.colors.primary.defaultLogo/favicon 缺省为defaultTheme.logos.*emailAuthEnabled: true、autoCreatePersonalProjects: true、enforceAllowedAuthDomains: false、allowedAuthDomains: []federatedAuthProviders: { saml: null }、pinnedPieces: []、pieceSelectorConfig: null、allowedEmbedOrigins: []。在 Cloud 的 onboarding 场景下createPlatformWithProject会用一把create-platform-${identityId}的 Redis 分布式锁串行执行创建 owner 用户 → 创建平台 → 创建个人项目ProjectType.PERSONAL→ 轮换 token 版本 → 上报注册事件并且对创建到一半中断的状态做了幂等恢复已存在 owner 则复用并链接已创建未链接 owner 的平台则补链接linkOwnerToPlatform。个人项目的命名规则是platformName去掉结尾的Platform后缀加上Project或以s Project结尾。二、PlatformPlan功能开关、配额与计费相关字段PlatformPlan是平台的能力清单由 platform.model.ts 的 zod 模型定义大致可分成四类功能开关FeatureFlagtablesEnabled、eventStreamingEnabled、environmentsEnabled、analyticsEnabled、auditLogEnabled、embeddingEnabled、aiProvidersEnabled、chatEnabled、agentsEnabled、workerGroupsEnabled、managePiecesEnabled、manageTemplatesEnabled、customAppearanceEnabled、projectRolesEnabled、globalConnectionsEnabled、customRolesEnabled、apiKeysEnabled、ssoEnabled、secretManagersEnabled、scimEnabled、showPoweredBy等。这些开关的枚举定义在FeatureFlagId中是前端渲染与后端鉴权的共同依据。不可消耗配额UnconsumableteamProjectsLimit团队项目数、usersLimit座位数、activeFlowsLimit活跃流程数。可消耗配额ConsumableapCreditsAP 积分、appSumoAiCreditsAppSumo AI 积分。计费/许可字段includedCredits、licenseKey、licenseExpiresAt、projectsLimit、billedTeamProjectsLimit、scheduledUsersLimit、workerGroupId。此外模型保留了几个已废弃字段带deprecated注释dedicatedWorkers、canary以及customDomainsEnabled自定义域名功能已移除仅保留列以兼容旧库——现代实现统一使用workerGroupId指向 worker 组。版本差异也很关键在 Community 版本中getPlan直接返回固定的OPEN_SOURCE_PLANusage返回undefined见 platform.service.ts因此 CE 自托管不存在额度计费概念。主题色与 Piece 选择器配置PlatformThemeColors定义了完整的可自定义主题色结构avatar、blue-link、danger、selection以及primarydark/light/medium、warndefault/light/dark、successdefault/light三组色板每个颜色都必须是HEX_COLOR_PATTERN/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/匹配的十六进制值。PieceSelectorConfig由一组tabs组成每个 tab 的kind为BUILTIN或CUSTOM。内置 tab 有五种EXPLORE、APPS、UTILITY、AI_AND_AGENTS、APPROVALS自定义 tab 必须有非空titlezod refine 校验Custom tabs must have a name可配置icon、hidden、pieceNames与sections分组展示。pieceSelectorConfig为null时前端回退到默认 tab。三、platformService服务层方法与职责划分服务层platform.service.ts围绕platformRepo提供以下核心方法方法用途create以默认值创建平台并把 owner 用户关联到平台、触发onPlatformCreated初始化套餐createPlatformWithProject注册/onboarding 专用分布式锁保护下创建平台 个人项目幂等恢复中断状态update更新品牌、认证、piece 配置可选地联动更新plangetOneWithPlanAndUsageOrThrow返回平台 套餐 用量Cloud/EE 的完整视图getOneWithPlanOrThrow只返回平台 套餐不含 usage用于鉴权守卫listPlatformsForIdentityWithAtleastProject列出某身份拥有且有项目的平台供平台切换器使用getOldestPlatform按created ASC取最老平台CE 单平台解析的入口hasSamlConfigured判断平台是否配置过 SAMLgetOneWithFederatedAuthOrThrow显式读取敏感的federatedAuthProvidersupdate中有两个值得注意的细节SAML 配置前置校验写入federatedAuthProviders.saml前先检查套餐是否开启ssoEnabled否则抛FEATURE_DISABLED配置 SAML 还要求ssoDomainVerification.status VERIFIED即SSO 域名必须先完成校验。SAML 缓存失效更新 SAML 后调用invalidateSamlClientCache(params.id)清掉缓存的 SAML 客户端保证新配置立即生效。返回给调用方之前所有方法都会经过stripFederatedAuth把federatedAuthProviders从对象中剔除——敏感的 SSO 数据默认不出服务层。四、REST 端点查询、更新、资产下载与删除平台相关端点集中在 platform.controller.ts由platformModule注册到 Fastify 应用入口见 platform.module.ts 与 app.ts。GET /v1/platforms/:id —— 获取平台plan usage鉴权securityAccess.publicPlatform([PrincipalType.USER, PrincipalType.SERVICE])同时兼容 API keySERVICE principal调用返回PlatformWithoutSensitiveDataSAML 敏感数据被剥离只保留saml: {}占位或nullUSER principal 的响应会被重写见 platform.controller.tsplan.chatEnabled被替换为按用户计算的 chat 可见性chatVisibilityHelper.resolveChatEnabledForUser嵌入式用户embedded的licenseKey会被置为null。POST /v1/platforms/:id —— 更新平台鉴权platformAdminOnly([PrincipalType.USER])且req.principal.platform.id必须等于路径中的:id否则抛AUTHORIZATION请求体是multipart因为要上传 Logo通过attachMultipartFieldsToBody预处理器把 JSON 字符串字段解析回对象见 platform.request.ts 的jsonFromMultipart三个图片字段logoIcon、fullLogo、favIcon会先经fileService.uploadPublicAssetFileType.PLATFORM_ASSET上传得到 URL 后再随其他字段一起落库——即品牌文件更新必须先走公共资产上传可更新字段与校验规则UpdatePlatformRequestBodyname仅校验SAFE_STRING_PATTERN不允许.和/、primaryColor、themeColors、federatedAuthProviders、cloudAuthEnabled、googleAuthEnabled、emailAuthEnabled、autoCreatePersonalProjects、allowedAuthDomains、enforceAllowedAuthDomains、pinnedPieces、pieceSelectorConfig、allowedEmbedOrigins。allowedEmbedOrigins的校验值得展开单个 origin 最长 300 字符协议仅限http:/https:且支持https://*.example.com形式的通配符子域校验逻辑见 platform.request.ts。DELETE /v1/platforms/:id —— 删除平台仅 Cloud仅 Cloud 版本注册该路由if (edition ApEdition.CLOUD)且必须是平台 ownerplatformToEditMustBeOwnedByCurrentUser存在有效订阅时拒绝删除hasActiveSubscription(platformPlan.plan)为真则抛DOES_NOT_MEET_BUSINESS_REQUIREMENTS提示先取消订阅再删除删除不是即时的先调度一个延迟约 7 天PLATFORM_PURGE_DELAY_DAYS的一次性系统任务HARD_DELETE_PLATFORMjobId: hard-delete-platform-${platformId}最多重试 25 次、固定 60 秒退避然后立即执行切断访问beginPlatformTeardown最后向 owner 发送确认邮件发送失败只记日志不阻塞删除。GET /v1/platforms/assets/:id —— 公共资产下载公开路由securityAccess.public()按文件 ID 读取PLATFORM_ASSET/USER_PROFILE_PICTURE类型的文件以Content-Disposition: attachment返回mimetype 从元数据读取。品牌 Logo、favicon 正是通过该端点对外提供。五、前端交互useCurrentPlatform 与 Appearance 表单的逐字段门控前端通过 React Query 消费平台数据核心 hook 在 platform-hooks.tsuseCurrentPlatform()以当前登录会话的platformId为 key[platform, currentPlatformId]staleTime10 秒返回{ platform, refetch, setCurrentPlatform }useDeletePlatform()调用删除 API 后跳转/sign-inuseUpdateLisenceKey()激活 license key成功后失效平台、flags 与订阅相关缓存。关键 Gotcha平台名称在 CE/未授权版本也可修改平台配置界面位于Settings Platform Setup General其 Appearance 表单实现在 appearance-section.tsx。从源码看该表单并非整体锁定而是逐字段门控第 80 行计算brandingLocked !platform.plan.customAppearanceEnableddisabled{brandingLocked}只作用于 Logo、图标、favicon 与主题色输入框Platform Name输入框不受此门控且提交时formdata.append(name, name)位于if (!brandingLocked)块之外。因此即使是一个 Community 或未授权平台也能在 Appearance 界面修改平台名称——整个表单从上往下读像是全锁实际只有品牌相关字段被锁。对应地API 层的UpdatePlatformRequestBody.name同样不加版本门控仅校验SAFE_STRING_PATTERN不允许.//。这是一个容易被误解的特性在排查为什么 CE 也能改名字时务必知道它是逐字段设计。六、平台删除的两拍式机制先切断后清理平台删除是本仓库中设计最精细、坑最多的流程完整决策记录见 000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md实现位于 platform-teardown-jobs.ts。第一拍请求返回即切断访问beginPlatformTeardownuser.status只被交互式登录读取触发器调度器、BullMQ 队列、API key 产生的 SERVICE principal 全都无视它。所以切断必须做四件事见 platform-teardown-jobs.ts把所有成员的user.status置为INACTIVE阻止交互登录删除平台全部api_key否则 SERVICE principal 能在窗口期内重新启用流程遍历所有流程通过正规的CHANGE_STATUS操作禁用FlowOperationType.CHANGE_STATUS→FlowStatus.DISABLED从而让triggerSourceService.disable注销 webhook、从 BullMQ 中移除 cron 与轮询调度——直接写status列不会解除触发器武装调用drainFlows清理队列中的遗留工作batchDeleteByFlowId。其中第 3 步对单个流程禁用失败时会降级为强制调用triggerSourceService.disable并直接更新状态列确保没有新 webhook 再放行新运行。关键顺序purge 任务在切断之前就已完成调度因此即使切断过程抛异常最坏结果也是如期清理但切断得不干净而不是全员失联且无人能重试。第二拍约 7 天后由单个 HARD_DELETE_PLATFORM 任务清理清理任务刻意不是单事务——每张表一条语句、每条语句可安全重复执行25 次重试可以从列表中间恢复而不是跨整租户持锁导致首次超时丢全部进度。删除顺序由 schema 强制顺序为再次执行禁用与排空对已切断的租户是 no-op删piece_metadata、app_connection逐个删除项目先批量删项目关联的 cell/record/field/table/flow_run/trigger_event/file再删项目行删signing_key删那些没有任何外键可达的 12 张表file平台级、project_role、user_invitation、mcp_oauth_token、mcp_oauth_authorization_code、variable、concurrency_pool、tool_search_index等piece_metadata、app_connection在前已删批量删除审计事件audit_event按 5000 条分块删platform行——让 14 条CASCADE外键清掉其余数据最后删user行并清理不再被任何存活用户引用的user_identity防止把另一个平台的用户登出。约束决定了顺序而不是偏好project与signing_key对platform(id)是RESTRICT是仅存的两个阻塞者tag、piece_tag曾是NO ACTION因功能废弃已被删表移除platform.ownerId → user是RESTRICT所以平台行必须先于 owner 的user行删除project.ownerId → user是NO ACTION所以项目必须先于任何用户删除还有一个连环陷阱piece_metadata.archiveId → file是RESTRICT而file.projectId → project是CASCADE因此自定义 piece 存档必须在删文件之前删除——这就是piece_metadata排在前面的原因。平台删不掉的诊断口诀某租户删除失败而另一个成功几乎总是新增了一张带RESTRICT外键的表阻塞者而不是成员数量问题。因为user、file、app_connection、piece_metadata、project_member、project_role、user_invitation、mcp_oauth_token、mcp_oauth_authorization_code、variable、concurrency_pool、tool_search_index这 12 张表都带platformId却没有任何外键——它们既不阻塞也不级联只会悄悄产生孤儿行任何 teardown 都必须显式删除它们绝不能因为列存在就推断有级联行为。对开发者的约定任何携带platformId的新实体应当把外键声明为ON DELETE CASCADE否则就必须把表名手工加进 platform-teardown-jobs.ts 的删除清单该清单由人工维护CI 不会检查。另外把成员置为INACTIVE就完事是一个危险误解INACTIVE 只挡登录调度器、队列和 SERVICE principal 都不读user.status切断平台必须按上述四件事逐项执行。七、完整 Gotchas 清单平台名称在所有版本都可改appearance-section.tsx按字段门控品牌输入唯独Platform Name与formdata.append(name, ...)在if (!brandingLocked)之外API 侧name同样无版本门控仅校验SAFE_STRING_PATTERN。逐项目project的 piece/action/trigger 可见性由 piece sets 管理不是平台——pinnedPieces/pieceSelectorConfig只管选择器呈现不做运行期可见性控制。GET 响应按调用者重写USER principal 拿到的是按用户生效的plan.chatEnabled嵌入式用户的licenseKey被置空。更新 SAML 会失效缓存invalidateSamlClientCache保证新 SAML 配置立即生效。usage只在非 Community 版本填充CE 使用OPEN_SOURCE_PLAN不返回用量。品牌文件先上传后落库Logo/favicon 更新走fileService.uploadPublicAsset得到 URL 再保存。platformId列 ≠ 外键12 张表带列无 FK删除平台时必须显式清理不能依赖级联。阻塞删除的约束只有project与signing_keyRESTRICT删除失败先查pg_constraint看是否新增了阻塞外键。删除顺序被ownerId → user的 RESTRICT 强制平台行先删owner 的 user 行后删项目必须先于任何用户删除。新实体规范带platformId的新实体声明ON DELETE CASCADE否则按名加入 teardown 清单。INACTIVE 只停登录必须通过CHANGE_STATUS禁用全部流程注销 webhook、移除调度、batchDeleteByFlowId排空队列、删除api_key否则流程仍在运行。八、关键文件速查服务端整个平台切片packages/server/api/src/app/platform/——module、controller、service、TypeORM 实体、getPlatformIdForRequest工具platform.utils.ts删除/清理实现platform-teardown-jobs.ts——HARD_DELETE_PLATFORM处理器与控制器调用的stopPlatformExecution切断逻辑共享 zod 模型与请求体packages/core/shared/src/lib/management/platform/——Platform、PlatformWithoutSensitiveData、PlatformPlan、PieceSelectorConfig、UpdatePlatformRequestBodyplatform.model.ts、platform.request.ts前端 React Query hookplatform-hooks.ts——useCurrentPlatform()品牌表单appearance-section.tsx决策记录000026-delete-platform-is-a-cloud-owner-action-purged-by-one-cascading-job.md删除机制的完整论证含 schema 级证据。文中涉及的文件路径均以仓库根目录为基准与文档标注的校验日期2026-07-17一致。若你的部署遇到平台删除失败、CE 改品牌被锁但改名可用、或新增租户表后清理不干净等问题对照本文的 Gotchas 与 teardown 清单逐项排查即可。【免费下载链接】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），仅供参考