1. 项目概述：为什么我花三周时间重装了五次AutoGPT才敢写这篇指南
AutoGPT不是个“装完就能跑”的玩具，它是个需要你亲手调教、反复验证、甚至要读懂报错日志里第7行那个 KeyError: 'execution_context' 到底在抱怨什么的生产级AI代理平台。我第一次在M1 Mac上跑起来时，前端页面空白，WebSocket连接失败，后台日志刷屏全是 psycopg2.OperationalError: connection refused ——这根本不是“配置错误”，而是PostgreSQL容器压根没等Supabase初始化完就急着去连它。后来我在Ubuntu 22.04 WSL2里又试了三次，每次卡在不同环节：一次是Docker Compose启动后前端npm run dev报 Module not found: Can't resolve 'react/jsx-runtime' ，一次是Agent Outputs面板始终不显示任何数据，还有一次是自定义Python块明明编译通过、注册成功，但拖进画布后直接灰掉不可用。这些都不是文档里写的“按步骤执行即可”，而是真实世界里每个技术人必须亲手踩过的坑。
所以这篇指南不叫“AutoGPT入门教程”，它叫《本地部署AutoGPT的实操手记：从环境崩坏到稳定运行的完整复盘》。它面向的是已经写过Python脚本、能看懂Docker日志、愿意为一个Agent多花两小时调试的工程师，而不是只想点几下鼠标就让AI替自己写周报的纯新手。核心关键词就三个： 本地部署、低代码构建、Python扩展 ——没有云服务、不依赖第三方托管、所有逻辑和数据都留在你自己的机器上。这意味着你得真正理解它的双层架构：前端Next.js负责拖拽画布和状态管理，后端FastAPI+PostgreSQL负责调度执行和持久化；而那套“Block即积木”的设计，表面是图形化，底层全是Python类继承和异步yield流控制。如果你只打算复制粘贴命令，那请现在关掉页面；如果你愿意跟我一起把每个 docker compose up -d 背后的17个容器状态、每个 .env 变量的实际作用、每块积木背后 run() 方法的执行生命周期都掰开揉碎，那咱们就开始。
2. 架构解构：为什么必须分清“Server”和“Frontend”，以及它们之间那条脆弱的WebSocket链路
2.1 两个进程，三种通信方式，一个致命依赖
AutoGPT平台绝非单体应用，它由两个完全独立的进程组成： autogpt_platform/backend （后端服务集群）和 autogpt_platform/frontend （前端UI）。它们之间不是简单的HTTP请求，而是三种通信机制并存的混合体：
- REST API（端口8006） ：用于创建Agent、保存Workflow、获取Marketplace列表等“一次性”操作。比如你在UI上点击“Save Agent”，前端会向
http://localhost:8006/api/v1/agents发一个POST请求，携带JSON格式的block连接关系和参数。 - WebSocket（端口8001） ：这是Agent真正“活起来”的关键。当你点击“Run Agent”，前端不是发个HTTP请求就完事，而是建立一个长连接，持续接收后端推送的执行状态：
{"event": "block_start", "block_id": "text_gen_abc123"}→{"event": "block_output", "output_key": "result", "value": "Hello world"}→{"event": "agent_complete", "duration_ms": 2450}。如果这个连接断了，你看到的永远是“Running…”转圈，而日志里可能只有一行websocket disconnected。 - 数据库直连（PostgreSQL端口5432） ：所有Agent配置、执行历史、用户账户都存在PostgreSQL里。但注意——后端服务本身并不直接连PostgreSQL，而是通过Prisma ORM连接Supabase实例。Supabase在这里扮演了“数据库网关+身份认证中间件”的双重角色。这就是为什么
docker compose up -d要等那么久：它得先拉起Supabase（含PostgreSQL+Realtime API+Auth服务），等Supabase健康检查通过（supabase status返回healthy），再启动FastAPI服务去连它。跳过这一步直接启FastAPI？必然报connection refused。
提示：验证这三层是否打通的最快方法是打开浏览器开发者工具（F12），切到Network标签页，然后做三件事：1）刷新页面，确认
/api/v1/marketplace返回200；2）点击“Run Agent”，在WS标签页里看到持续的心跳帧（ping/pong）；3）在Application → Storage → LocalStorage里搜索user_token，确认有值且未过期。三者缺一不可。
2.2 前端不是“界面”，而是状态协调器
很多人以为Next.js前端只是个漂亮外壳，其实它承担了远超UI渲染的职责。当你在画布上拖拽两个Block并连线时，前端做的不是“画一条线”，而是实时生成并维护一个DAG（有向无环图）结构：
{
"nodes": [
{ "id": "input_1", "type": "textInput", "data": { "default_value": "Hello" } },
{ "id": "llm_2", "type": "aiTextGenerator", "data": { "model": "gpt-3.5-turbo" } }
],
"edges": [
{ "source": "input_1", "target": "llm_2", "sourceHandle": "text", "targetHandle": "prompt" }
]
}
这个DAG对象会被序列化后，作为 workflow_definition 字段提交给后端。更关键的是，前端还负责 执行上下文管理 。比如你设置了一个定时任务（Scheduler Block），前端会计算下次触发时间，并将这个时间戳写入数据库；当时间到达，Supabase的Realtime API会推送一个事件给前端，前端再触发一次 /api/v1/agents/{id}/run 调用。整个过程，后端只管执行，前端才是那个“掐着表喊开始”的指挥官。
2.3 后端不是“服务器”，而是执行引擎集群
后端目录 autogpt_platform/backend 里藏着五个核心服务，它们各自独立运行，通过Redis消息队列协同：
| 服务名 | 端口 | 职责 | 关键依赖 |
|---|---|---|---|
api |
8006 | REST API入口，处理HTTP请求 | PostgreSQL, Redis |
ws |
8001 | WebSocket服务器，推送执行状态 | Redis, PostgreSQL |
executor |
— | 真正执行Agent逻辑的Worker | Redis（监听 execution_queue ） |
scheduler |
— | 定时任务调度器，触发周期性Agent | PostgreSQL（读取 scheduled_jobs 表） |
notification |
— | 发送邮件/Slack通知 | SMTP/Slack Webhook配置 |
注意： executor 和 scheduler 这两个服务 没有对外暴露端口 ，它们纯粹是后台Worker。当你点击“Run Agent”，流程是：前端 → api 服务 → 写入Redis队列 → executor Worker从队列取任务 → 执行Python Block → 将结果写回Redis → ws 服务从Redis读取并推送给前端。这种解耦设计保证了高并发下的稳定性，但也意味着——如果你只看到 api 和 ws 容器在运行，而 executor 容器因内存不足崩溃了，那么所有Agent都会卡在“Queued”状态，日志里却找不到明显错误。
实操心得：部署后第一件事，别急着建Agent，先用
docker ps确认5个后端容器（api, ws, executor, scheduler, notification）全在Up状态。再用docker logs -f autogpt_platform-executor-1盯住executor日志，看到
289
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
