Day 04 / 共 20 天 · 第 1 周 核心概念

运行平台

让它跑起来。SuperAGI 是六服务的完整平台，今天用 docker compose 启动它，并从两个 entrypoint 脚本看清启动步骤。

📍 你在整门课的位置 · 第 1 周 核心概念（D1-5）· 概念够了，今天把整台机器真正跑起来
D01 全景架构→ D02 Agent→ D03 工具→ D04 运行平台→ D05 完整旅程· 第2周 Agent执行· 第3周 工具/记忆/资源· 第4周 平台/异步/生态
L01

一键启动

cd SuperAGI
cp config_template.yaml config.yaml   # 填 OPENAI_API_KEY 等
docker compose up --build
# 浏览器打开 http://localhost:3000
读法：一条命令拉起整个平台，3000 端口就是 GUI，能可视化创建智能体。先在 config.yaml 填好至少一个 LLM 的 key（OpenAI 等）。
L02

六个服务（Day 01 复习+深化）

🤔 不就是跑个 AI 智能体吗，为什么要六个容器这么"重"？ 你可能想：一个 Python 进程调调 LLM 不就完了？为什么要 backend、celery、gui、redis、postgres、nginx 六个东西一起上？
💡 一句话本质：六个容器 = 六个"单一职责"，各干一件事、可独立扩展 这是把玩具脚本升级成生产系统的代价，也是它的价值：proxy 管入口、gui 管界面、backend 管接单、celery 管干活、postgres 管数据、redis 管队列+向量。每个只做一件事——某一环压力大就单独加实例（比如多开几个 celery），互不牵连。下面这段服务清单，你正好对着"谁负责什么"读。
贯穿今天的类比是"一家餐厅开业"：docker compose up = 拉闸开门营业；六服务 = 六个岗位（大堂经理 proxy、服务员 gui、前台收银 backend、后厨 celery、仓库账本 postgres、订单小票夹 redis）；开门前的准备（下工具、跑迁移）= 进货摆桌；seeding = 开业先把招牌菜备好。
# docker-compose.yaml 六服务
backend         # FastAPI（等 Postgres 就绪后启动）
celery          # 同镜像，跑 Celery worker（后台执行智能体）★
gui             # Next.js 前端
super__redis    # redis-stack-server（broker + 向量存储）
super__postgres # postgres:15（库 super_agi_main）
proxy           # nginx，ports "3000:80"（用户入口）
读法：super__redis 用的是 redis-stack-server——不只是普通 Redis，还带向量搜索能力（既做 Celery 消息队列，也能当向量库，Day 13）。proxy(Nginx) 是唯一对外暴露的端口。

👶 小白：我就想跑个 demo，能不能别整六个容器，直接 python 跑一个脚本？

👨‍🏫 老师：跑得起来，但会失去 SuperAGI 的灵魂。少了 celery + redis，就没有"后台一步步自我重排"的循环（Day 02 的啊哈点），智能体没法断点续跑、没法并发；少了 postgres，进度和 Feed 没处存，崩一次全丢。这六个岗位不是摆设，正是它们把"一个会崩的脚本"撑成了"可运维的平台"。本地 docker compose up 一键全拉起，其实并不费事。

L03

API 容器启动步骤

entrypoint.sh 揭示了 backend 容器的启动顺序：

1python superagi/tool_manager.py —— 下载工具
2install_tool_dependencies.sh —— 装工具依赖
3alembic upgrade head —— 跑数据库迁移
4uvicorn main:app --port 8001 --reload —— 起 API
为什么启动前要下工具、跑迁移？ ① 下工具：智能体要用的工具代码得先下载到本地（工具市场，Day 12）。② 跑迁移：alembic upgrade head 把数据库表结构升级到最新——否则新版本的字段没建，代码会报错。这些是"服务能正常工作的前提"，必须在起 API 之前就绪。和 AutoGPT/OpenHands 的启动迁移一个道理。wait-for-it.sh super__postgres:5432 确保先等数据库起来。
启动阶段此刻发生什么餐厅类比
wait-for-it postgres等数据库端口通了才继续等仓库开门
tool_manager.py下载工具代码到本地进货
alembic upgrade head把表结构升到最新版按最新菜单改后厨
uvicorn main:app起 API，开始接单开门营业
💥 顺序反了会出什么事故（错误驱动）：如果不跑迁移就直接起 API——代码里 SELECT ... resource_summary 一查，数据库里根本没这一列，直接 column does not exist 崩溃；或者工具还没下载，智能体一调工具就 ModuleNotFound。就像没进货、没按新菜单改后厨就开门迎客，客人一点菜就露馅。所以这几步必须卡在 uvicorn 之前。
L04

Celery 容器

entrypoint_celery.sh：下工具/装依赖后跑 celery -A superagi.worker worker --beat --loglevel=info。

注意 --beat --beat 表示这个 Celery 进程既是 worker（执行任务）又是 beat（定时调度器）。beat 负责周期性触发任务（Day 17）——比如每 5 分钟检查有没有到点的定时智能体、每 2 分钟唤醒等待中的工作流。backend（接单）和 celery（干活+定时）分成两个容器，同一个镜像——回忆 Day 01 的"接单快、干活慢"分离。
⚠️ 常见误解：小白看到 backend 和 celery 用同一个镜像，常以为"那不就是同一个东西、跑两遍浪费吗？"。其实同镜像只是为了打包省事（代码都在里面），两个容器跑的是完全不同的进程——一个 uvicorn（接单），一个 celery worker --beat（干活+定时）。同一家餐厅，前台和后厨用的是同一本《员工手册》，但干的活天差地别。
L05

startup seeding

main.py 的 @app.on_event("startup")（main.py:194）在启动时做初始化播种：注册本地/市场工具（register_toolkits），并用 AgentWorkflowSeed/IterationWorkflowSeed 内置几套工作流（Goal Based、Fixed/Dynamic Task、Sales、Recruitment、SuperCoder）。

📝 seeding 的"输入" → 新用户第一次打开看到的"输出" 启动脚本触发（大意）：register_toolkits() + AgentWorkflowSeed.build_goal_based_agent() 等一串播种函数。
于是新用户零配置打开 GUI 就能看到：工作流下拉里已有 Goal Based Workflow / Fixed Task Workflow / Dynamic Task Workflow；工具区已装好文件、搜索等 toolkit。
不播种的话，界面空空如也，新用户根本无从下手。（这些 build_* 函数就在 agent/workflow_seed.py，Day 07 精读。）
为什么要"播种"内置工作流？ 新用户第一次打开平台，如果什么都没有（没工具、没工作流），无从下手。启动时自动"播种"一批预置工作流和工具——新用户开箱就能选"目标驱动"工作流、就有搜索/文件等工具用。这些内置工作流（Day 07 讲）定义了智能体"按什么流程干活"的几种模式。好产品让新用户"零配置就能开始"——seeding 就是为此。
L06

Nginx 反向代理

nginx/default.conf：对外暴露 3000 端口（映射到容器 80），把 /api 转给 backend、其余转给 GUI。

🧑 浏览器:3000 proxy (Nginx)看 URL 路径分发 gui (Next.js)页面/静态资源 backend (FastAPI):8001 接口 其余路径 → /api/* → 对浏览器只有一个地址 :3000 → 同源、无跨域、只暴露一个端口
Nginx 反向代理：所有请求都打 :3000，按路径分流——/api/* 给 backend、其余给 gui。浏览器眼里只有一个同源地址。
为什么要反向代理？ 前端（GUI）和后端（API）是两个服务、不同端口。如果让浏览器直接分别访问两个端口，会有跨域问题、也不优雅。Nginx 作为"统一入口"：所有请求都打 3000，Nginx 看路径分发——/api/* 给后端、其余给前端。于是对浏览器来说只有一个地址（同源，无跨域），部署也只暴露一个端口。反向代理是多服务 Web 应用的标准前置。
L07

配置文件

config_template.yaml（复制成 config.yaml）集中放所有配置：各家 LLM key（OPENAI/PALM/REPLICATE/HUGGING）、MODEL_NAME、MAX_MODEL_TOKEN_LIMIT、DB/Redis 连接、存储类型（FILE/S3）、TOOLS_DIR、JWT/加密 key、各工具凭据（Google 搜索、邮件、GitHub、Jira、Slack…）。

配置集中化：一个 yaml 管所有——换模型改 MODEL_NAME、换存储改 STORAGE_TYPE、接工具填对应凭据。Day 19 会深入配置和部署变体（本地 LLM、GPU 等）。今天记住：所有可调的旋钮都在 config.yaml。
L08

今日小结 + 动手

🧠 今天你应该能回答

  • 怎么启动平台？六个服务各是什么？
  • API 容器启动前为什么要下工具、跑迁移？
  • Celery 的 --beat 是什么？为什么 backend/celery 分开？
  • startup seeding 为什么重要？
  • Nginx 反向代理解决什么？配置在哪？
🗣️ 一句话复述今天 docker compose up 就是"一家六岗位餐厅拉闸开业"——开门前先进货（下工具）、按最新菜单改后厨（跑迁移）、备好招牌菜（seeding），大堂经理（Nginx）在门口按需分流客人，前台（backend）和后厨（celery）各司其职。

✋ 动手

grep -nE '(backend|celery|gui|super__|proxy):' docker-compose.yaml
cat entrypoint.sh entrypoint_celery.sh
sed -n '194,247p' main.py | head -40      # startup seeding
grep -nE 'API_KEY|MODEL_NAME|STORAGE_TYPE|REDIS_URL|DB_URL' config_template.yaml | head
明天预告 · Day 05（第1周收官）：把前四天串成故事线——一次 agent 运行的完整旅程：从 GUI 创建 → API 建 Execution 入队 → Celery worker 一步步自主循环 → Feed 流回 GUI。
← Day 03 工具 Day 05 · 完整旅程 →