Activepieces 自托管教程：用 Docker 部署第一个 AI 工作流

这篇教程会完成什么

你将部署一个可访问的 Activepieces 实例，并创建一条“Webhook → AI 分类 → 人工确认 → 表格写入”的测试流程。教程重点是安全边界和可恢复性，不把 Agent 直接连接到付款、删除或批量外发动作。

开始前需要准备

• 一台能运行 Docker Compose 的 Linux 服务器
• 一个域名或内网访问地址
• HTTPS 终止层，例如 Caddy、Nginx 或云负载均衡
• 一个模型提供商的 API Key
• 用于测试的表格或数据库
• 备份目录和最小权限的管理员账号

如果只是验证功能，可以先在本地运行。生产环境不要把编辑器端口直接暴露到公网。

第一步：准备部署目录

创建专用目录和环境文件，把数据库、Redis、应用密钥和公开地址放在环境变量中。不要把真实密钥提交到 Git，也不要把它们写进截图、日志或流程输入。

建议先固定一个版本号，而不是每次启动都拉取 latest。这样升级前可以做备份和回滚。

第二步：启动 Docker Compose

按照 Activepieces 当前官方文档提供的 Compose 模板启动服务。启动后先检查容器状态、数据库连接、队列和健康检查，再打开管理页面。

首次登录后立即：

• 修改管理员密码
• 开启 HTTPS
• 限制管理员和编辑器访问来源
• 创建单独的测试项目
• 为每个外部应用建立最小权限凭据

不要在没有鉴权的情况下把 Webhook URL 发给外部系统。

第三步：创建测试 Webhook

新建一个 Webhook 触发器，要求调用方携带随机 token 或签名。测试 payload 只包含虚构姓名、公司、需求和提交 ID。

流程第一步先保存提交 ID，后续写入前用它做幂等检查。这样网络重试不会重复创建联系人或工单。

第四步：加入 AI 分类步骤

新增模型动作，让它返回固定字段：

• lead_type：高意向、待培育、无效
• reason：简短判断依据
• next_action：联系、发送资料、人工复核
• confidence：高、中、低

提示词中明确：不能猜测预算、公司规模或联系方式；无法判断时返回待培育和低置信度。先用人工标注的样本测试一致性，再接入真实流量。

第五步：设置人工审批

AI 输出先写入审批表或发送到内部通知渠道，审批人确认后才允许写入测试 CRM。高意向、低置信度和字段缺失的结果必须进入人工队列。

生产上线初期建议保持“只生成草稿”模式，连续观察一周，再逐步放开低风险自动写入。

第六步：备份和日志

备份至少覆盖 Activepieces 配置、数据库和自定义凭据元数据。不要把 API Key 明文备份到公共目录。恢复演练要在另一套环境进行，确认工作流、连接器和管理员账号都能恢复。

日志要保留运行 ID、状态、耗时和错误类型，但应脱敏客户内容、Token 和模型上下文。为失败流程设置通知，不要让它无限重试。

常见错误

直接使用 latest 镜像

升级可能改变连接器、环境变量或数据结构。固定版本，先备份，再在测试环境验证。

Webhook 没有鉴权

公开 URL 很容易被滥用，至少加入签名、随机 token、限流和来源校验。

让 AI 直接执行不可逆动作

AI 分类和草拟可以自动化，付款、删除、对外承诺和权限变更必须人工确认。

忽略模型费用

自托管只解决应用部署，不会免除模型 API 成本。记录每次运行的输入长度、模型、重试和总费用。

什么时候改用其他工具

如果团队不想维护服务器和备份，Zapier Agents 更适合快速云端验证；如果流程需要复杂队列、代码和成熟节点生态，可以评估 n8n；如果核心是知识库、RAG 和 LLM 应用，Dify 可能更直接。

FAQ

Activepieces 适合生产环境吗？

可以，但前提是完成 HTTPS、权限、备份、升级、日志和恢复演练。不要因为能在本地启动就直接承载高风险业务。

需要自己部署数据库吗？

按官方当前部署方式决定。无论使用内置或外部数据库，都要确认持久化、备份和升级策略。

如何安全地测试 AI 工作流？

使用虚构数据、低权限凭据和可回滚目标，先记录输出和人工修正，再逐步扩大真实流量。