activepieces/activepieces · 上手攻略

仓库：activepieces/activepieces
链接：https://github.com/activepieces/activepieces
分类：skill
作者：spark
更新：2026-07-13

是什么

Activepieces 是一个开源的「AI 自动化 / Workflow Automation」平台，定位和 Zapier、Make（原 Integromat）、n8n 直接对标，README 自己也写「An open source replacement for Zapier」。它把 GitHub、Slack、Notion、Google Sheets、OpenAI、Anthropic、Discord、Telegram、SMTP 等几百个第三方服务抽象成一个个叫 Piece 的积木块（TypeScript 写的 npm 包），用户用拖拽的方式把它们连成 Flow，让数据在「Trigger（触发器）→ Action（动作）→ Branch / Loop / Code → Human Input」之间跑。

它最不一样的地方是 AI-First + MCP：内置 AI Piece（OpenAI / Anthropic Claude / Google Gemini / DeepSeek / Groq / OpenRouter 都直接能用），并把所有 Piece 同时作为 MCP server 暴露 —— 也就是说你在 Activepieces 里写好的每一个连接器（飞书、Notion、Slack…），既能在自己的 Flow 里用，也能被 Claude Desktop / Cursor / Windsurf 当 MCP tool 来调。这一点是它和 n8n / Zapier 最大的差异点。

后端基于 TypeScript / NestJS，UI 是 React 拖拽画布，社区版（packages/ 下的代码）MIT 开源；packages/ee/ 下的企业版功能（多 SSO、审计、品牌定制等）走商业 License，自托管用到 EE 包需要拿到 license。

解决什么问题

Zapier / Make 太贵，n8n 自托管门槛高：Zapier 涨价、Make 复杂操作扣 credit；n8n 自托管相对重、UI 没那么顺手。Activepieces 想做「云端体验 + 完全自托管 + 比 n8n 更现代 UI」的中间档。
AI 流程要写一堆 prompt + 工具调用：单独写 OpenAI Function Calling / Anthropic Tool Use 代码，做一次性的工具路由、错误重试、上下文维护很麻烦。Activepieces 的 AI Piece 让你在画布里就把「调模型 → 取结果 → 调下一个工具」接好。
企业内部跨 SaaS 集成：HR 表单 → Notion 建页 → Slack 通知 → Gmail 发邮件，常见需求直接拖就行；非工程师也能改。
让 LLM 客户（Cline / Cursor / Claude Desktop）有真实可调工具：开发者用 Activepieces 编排好一个「查客户订单 + 发 Slack 通知」流程，把它当 MCP server 接进 Claude Desktop，模型就能直接「替我查订单并发 Slack」。

快速安装

A. Docker Compose（推荐自托管）

git clone https://github.com/activepieces/activepieces.git
cd activepieces
cp .env.example .env
# 按需要改 AP_FRONTEND_URL / AP_POSTGRES 之类的项
docker compose -p activepieces up

注意：老教程里用的是 docker-compose（带连字符的 v1 写法），现在已经不维护；请用 Docker 自带的 docker compose（空格）。Docker Desktop 自带 Compose v2。

启动后浏览器开 http://localhost:8080（端口以你 .env 里 AP_FRONTEND_URL / 端口映射为准）就能看到 Onboarding。

升级时：

docker compose pull
docker compose -p activepieces up -d

最新镜像 tag 在 Docker Hub：activepieces/activepieces（搜得到 0.86.2 等具体版本号，注：本攻略写于 2026-07-13，实际生产请以 Docker Hub 的 latest 标签或你锁定的版本为准）。

B. 单容器跑（最轻量，适合本地 demo）

社区贴里有这条命令，开箱默认用 PGlite（嵌入式 Postgres）+ Memory Redis：

docker run -d -p 8080:80 \
  -v ~/.activepieces:/root/.activepieces \
  -e AP_REDIS_TYPE=MEMORY \
  -e AP_DB_TYPE=PGLITE \
  -e AP_FRONTEND_URL="http://localhost:8080" \
  activepieces/activepieces:latest

坑：用 localhost:8080 时能从本机访问，但同局域网别的机器拿 IP 访问经常出现「白屏」（前端 hardcode 了 localhost 的资源路径）—— 这条在社区帖 community.activepieces.com/t/.../11807 有详细报告。生产 / 跨机访问请用 Docker Compose 并通过反向代理（Nginx / Caddy / Traefik）走域名，并设好 AP_FRONTEND_URL=https://your.domain。

C. 开发环境（要贡献 Piece / 改前端）

仓库是 monorepo（packages/），主仓 README 推荐用官方文档里的开发者起步指南：

git clone https://github.com/activepieces/activepieces.git
cd activepieces
pnpm install
pnpm run start
# 详细命令以 docs/install/development-environment.md 为准

D. 用 Activepieces 当 MCP Server

让 Claude Desktop / Cursor / Windsurf 直接调你 Activepieces 上的 Flow：

在 Activepieces UI 里创建一个 Flow，选触发器为「MCP」（这就是把 Flow 暴露成 MCP 端点）。
拿这个 Flow 的 MCP URL（形如 https://<your-host>/api/v1/mcp/<flow-id>），按 https://www.activepieces.com/docs/build-pieces/mcp/overview 配到客户端。

具体 JSON 因版本不同会有差，以官方文档为准。

核心用法

1. 拖一个最简单的 Flow

Trigger：选 Schedule（定时）或 Webhook（HTTP 触发）。
Action：选 HTTP 或 Gmail / Slack / Google Sheets。
把右侧字段填好 → Test Flow → Publish。

2. 在 Code Piece 里用 NPM 包

Code Piece 不是裸 JS 沙箱 —— 它能直接 require('axios') 这种 npm 包，这是它相对 n8n 的一个明显卖点：

// Code piece: 调一个外部 API
import axios from 'axios';

export const code = async (inputs) => {
  const { email } = inputs;
  const resp = await axios.get(
    `https://api.example.com/users/${encodeURIComponent(email)}`
  );
  return { status: resp.status, name: resp.data.name };
};

顶上还有个 Ask AI 按钮：非工程师写不出代码时，可以直接让内置 AI 帮你「清洗这堆数据」（在 Code Piece 里点 Ask AI 即可，README 原文）。

3. AI Piece + Prompt 拼接

把上一个 Action 的输出（用 {{step_1.body.name}} 这种 mustache 语法）拼进 Prompt，调 OpenAI / Anthropic Claude / Gemini / DeepSeek：

System: 你是一个严谨的客服助手。
User: 客户名 {{step_1.body.name}}，问题 {{step_2.text}}。请给一段不超过 80 字的回复。

下一步再接 Gmail Piece，把模型回复用模板渲染后发出去。

4. Human-in-the-Loop

Human Input Piece（/pieces/forms 或 /pieces/chat-interface）能让 Flow 跑到某一步时停下，发个审批链接 / 表单 / 聊天窗口给运营人员，等人点了再继续。完全自托管场景里这是审批流绕不开的一环。

5. 自己写一个 Piece（最像 Next.js Plugin）

packages/pieces/<name>/ 下新建一个子包，导出 createCustomAction / createCustomTrigger，然后 pnpm install 就能在画布里看到。这是 Activepieces 强项之一：Piece 是 TypeScript npm 包，热重载、IDE 智能提示齐全（README 原话）。

最小骨架（节选自官方 Contributor Guide）：

// packages/pieces/my-app/src/lib/actions/create-user.ts
import { createAction, Property } from '@activepieces/pieces-framework';

export const createUser = createAction({
  name: 'create_user',
  displayName: 'Create User',
  description: 'Create a new user in MyApp',
  props: {
    email: Property.ShortText({ displayName: 'Email', required: true }),
  },
  async run({ auth, propsValue }) {
    // ...call your API
    return { ok: true, email: propsValue.email };
  },
});

典型适用场景

SaaS 内部自动化：销售线索进 CRM → Slack 通知销售 → Google Sheets 入档 → 7 天后自动回访邮件。
AI 内容流水线：RSS 抓文章 → AI 摘要 + 翻译 → 写回 Notion / 推 Telegram 频道。
客服 / 工单路由：Webhook 接 Stripe / Intercom → AI 分类 → 派单到不同 Slack channel。
把内部工具暴露给 AI Agent：用 Activepieces 当 MCP server，省去自己写 OpenAI Function Calling 路由。
个人 / 团队 zero-budget 自动化：Zapier 收费后最常见的迁移目标。

不太适合：

极大规模（每秒上千次触发）的工业级集成 —— 这是 Zapier / Make / Temporal 的领域。
强实时数据流（Kafka 类场景）—— Activepieces 是 workflow，不是 streaming engine。

坑与注意

Pieces 总数版本漂移：README 写「280+ pieces」是发布时的快照；官网 activepieces.com/pieces 实际展示 755 pieces（以 2026-07-13 抓取为准），数字持续增长，写文档时按你看到的版本为准。
许可证分两段：packages/ 下社区版是 MIT；packages/ee/ 是商业 EE License。自托管一旦启用 EE 内的功能（SSO、品牌白标、审计日志、用户管理增强等），需要联系 Activepieces 拿 license key，违反协议商用会被找。
TypeScript / Node 版本：社区版要求 Node.js 20+（具体以 package.json 的 engines 字段为准，自托管前先看一眼）。
数据持久化：Docker Compose 方式必须用外置 Postgres + Redis；单机 PGlite + Memory Redis 只适合 demo，重启数据可丢。
AP_FRONTEND_URL 设错 → 前端白屏：跨机访问 / 反代场景必须把外部 URL 写进 .env，不能只改端口。
MCP 暴露粒度：每个 Flow 是一个 MCP tool / endpoint；要让模型能调得到，先把 Flow 切换成「发布」状态，再看 MCP 端点是否带鉴权（生产环境必加 token / IP 白名单）。
版本更新快：社区反馈它的迭代节奏比 n8n 快，UI 改版频繁；生产部署建议显式 pin tag，不要直接 latest。

与同类对比

Zapier / Make —— 云端 SaaS，零运维但贵、lock-in；Activepieces 可以完全自托管。
n8n —— 同样开源可自托管，但 AI 集成弱、MCP 是后加的；Activepieces 把 AI + MCP 作为 first-class 卖点。
Apache Airflow / Temporal / Prefect —— 偏数据工程 / 长时间 workflow 调度，UI 偏工程师；Activepieces 偏业务人员也能用的 no-code 体验。
Huginn —— 老牌自托管 ifttt 替代，UI 古老、生态小。
Dify / Flowise（LLM workflow 方向） —— 偏 LLM orchestration（agent、prompt 工程）；Activepieces 偏通用 SaaS 集成，AI 只是一类 Piece。

一句话推荐结论

如果你既想要 n8n 那种「可自托管 + 数据在自己机器上」的安全感，又想要 Zapier 那种现代画布的爽感，并且要把自动化成果直接当 MCP server 接进 Claude / Cursor，Activepieces 是当下最顺手的选择；个人和中小团队自托管直接 Docker Compose 拉起来就能用，企业版功能再去联系官方拿 license。