Drawgent 的思路是"把智能体画出来":节点、连线、参数都放在一块 Excalidraw 画布上,画完之后智能体就在这块画布上跑起来,边思考边把代码写进你指定的代码节点里。这篇教程从零开始,把它跑到"能在画布上实时看到代码逐行出现"为止。
适用场景
适合想把编码智能体从"聊天窗口"搬到"可视化流程图"的团队:需求梳理、任务拆解、代码生成、执行验证这几步用方框和箭头连起来,流程图本身就是配置,改图即改流程。也适合需要给非工程同事演示"智能体到底在干什么"的场景,因为它每一步都有可视化的节点状态。
环境与前置条件
操作系统:Linux(Ubuntu / Debian 系较常见)、macOS 均可;Windows 建议用 WSL2,直接在 PowerShell 里跑容器挂载目录容易碰到权限问题。
运行时:
- Docker 与 Docker Compose v2(具体最低版本以官方文档当前版本为准)
- 如果用源码方式启动,需要 Node.js 的 LTS 版本与 pnpm(版本要求以仓库 README 为准)
- 浏览器用 Chrome / Edge 的新版本即可,画布依赖 WebSocket,老版本内核对增量更新支持不好
硬件建议:
- 内存 8 GB 起步,同时跑前端、后端、数据库和代码执行沙箱,16 GB 更稳
- 磁盘预留 20 GB 以上,镜像和依赖体积不小,生成的工作区文件也会持续增长
- 显存不是必需项,除非把本地大模型也部署在同一台机器上
前置条件:
- 一个兼容 OpenAI 协议的大模型服务地址与 API Key(云端或本地推理服务都行)
- 一个准备让智能体读写的代码目录,例如
/home/you/projects/demo - 该目录最好先纳入 Git 管理,便于回滚智能体的改动
分步骤部署
第一步:获取代码并进入目录
```bash
git clone <Drawgent 仓库地址> drawgent
cd drawgent
```
仓库地址以官方页面为准。克隆完成后先读一遍 README 与 docker-compose.yml,确认服务名、默认端口和环境变量键名,后面所有命令都按这份文件来。
第二步:准备环境变量文件
```bash
cp .env.example .env
```
用编辑器打开 .env,填入模型服务与工作目录。下面是一份常见配置项的示例,键名以仓库内 .env.example 为准:
```dotenv
服务端口
WEB_PORT=3000
API_PORT=8000
任意兼容 OpenAI 协议的服务
LLM_BASE_URL=https://api.example.com/v1
LLM_API_KEY=sk-替换成你自己的密钥
LLM_MODEL=替换成服务商提供的模型名
让智能体读写的宿主目录,以及它在容器内的挂载点
WORKSPACE_HOST_DIR=/home/you/projects/demo
WORKSPACE_CONTAINER_DIR=/workspace
```
要点有两个:一是 API Key 只放后端环境变量,不要写进前端或画布元素里;二是工作目录挂载进去之后,智能体的文件读写才算真正落盘,否则只在容器里自娱自乐。
第三步:启动服务
```bash
docker compose up -d
```
这一步会拉镜像、建网络、起容器。首次执行时间较长,取决于网络速度。看到各服务状态变为 Started 或 Running 即为正常。
第四步:确认容器状态
```bash
docker compose ps
```
预期输出里每个服务的 STATUS 都是 Up,带健康检查的会显示 Up (healthy)。如果某个服务反复重启,直接看它的日志:
```bash
docker compose logs -f server
```
第五步:打开画布并连接服务
浏览器访问 http://<服务器地址>:3000(端口以 .env 实际配置为准)。页面加载出 Excalidraw 画布,右上角连接状态由灰变绿,说明前端已和后端建立 WebSocket 长连接。
如果部署在远程服务器上,注意用 Nginx 之类的反向代理转发时,必须把 Upgrade 和 Connection 头透传,否则画布会一直卡在"连接中"。
第六步:在画布上画出智能体的骨架
在画布上放几个矩形,双击输入角色名,再用箭头连起来,形成数据流向。常见的几种角色:
- 需求节点:写清楚这次要做什么,例如"给 demo 项目加一个读取 CSV 并输出统计的脚本"
- 上下文节点:指定要参考的文件或目录,例如
/workspace/src - 代码节点:智能体写代码的落点,对应一个真实文件路径
- 运行节点:执行命令,例如
python stats.py data.csv - 审查节点:对结果做检查,不通过则回流到代码节点
节点类型与命名规则以官方文档列出的为准。连线的方向就是信息传递的方向,箭头从"产出方"指向"消费方"。
第七步:绑定模型与工作目录
选中代码节点,在右侧属性面板里填写容器内的文件路径,例如 /workspace/stats.py。选中运行节点,填写要执行的命令。整个画布共用 .env 里那一套模型配置,不需要逐个节点填 Key。
这一步做完,画布上的图就从"示意图"变成了"可执行的配置"。
第八步:触发运行,观察实时写码
点画布上的运行按钮,或者节点自带的执行图标。后端会按图的有向顺序调度:先读需求与上下文,再调用模型生成内容,然后通过 WebSocket 把增量片段推给前端;前端拿到片段后用 Excalidraw 的场景更新接口把文字写进对应元素的文本属性。所以看到的效果就是代码节点里的代码一个字一个字地长出来,而不是跑完之后突然出现一大段。
运行节点执行时,输出会回填到该节点的副标题或备注区。审查节点判定不通过,箭头就会把控制流送回代码节点,重新生成一轮。
验证部署是否成功
按下面四条依次验证,全部通过说明链路是通的:
1. 服务健康检查
```bash
curl -fsS http://localhost:8000/healthz
```
返回 HTTP 200 与类似 {"status":"ok"} 的 JSON 即为正常。具体健康检查路径以官方文档为准。
2. 容器内能访问到挂载目录
```bash
docker compose exec server ls -l /workspace
```
能列出宿主目录里的文件,说明挂载生效。
3. 画布连得上
打开浏览器开发者工具,切到 Network → WS,能看到一条处于 101 Switching Protocols 的 WebSocket 连接,状态为 pending(持续连接)而不是失败。
4. 端到端跑通一次
触发一轮最简单的任务:需求节点写"创建 hello.py,打印一行文字",代码节点绑定 /workspace/hello.py,运行节点执行 python /workspace/hello.py。预期结果是画布上代码节点出现代码,运行节点出现输出,同时宿主机上能看到文件:
```bash
cat /home/you/projects/demo/hello.py
```
文件存在且内容与画布一致,就算部署成功了。
常见报错与解决
1. Error response from daemon: Ports are not available: bind: address already in use
→ 原因:3000 或 8000 端口已被其他进程占用。
→ 解决:先定位占用进程,再决定是停掉它还是换端口。
```bash
ss -ltnp | grep -E '3000|8000'
或者
lsof -i :3000
```
改端口的话,编辑 .env 中的 WEB_PORT / API_PORT,然后:
```bash
docker compose up -d
```
2. 画布右上角一直显示"连接中",控制台报 WebSocket connection to 'ws://...' failed
→ 原因:反向代理没有透传 WebSocket 升级头;或者页面是 https 而连接地址仍是 ws,被浏览器按混合内容拦截。
→ 解决:在 Nginx 的 location 块里补上这两行,然后 nginx -s reload:
```nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```
同时确认前端配置的后端地址是 wss:// 而非 ws://。排查阶段可以先直连 http://<IP>:<API_PORT> 验证是不是代理的问题。
3. 触发运行后提示 401 Unauthorized 或 invalid_api_key
→ 原因:LLM_API_KEY 填错、过期,或者 LLM_BASE_URL 少了 /v1 之类的路径后缀。
→ 解决:确认容器里读到的值,改完重建后端容器。
```bash
docker compose exec server env | grep -i llm
docker compose up -d --force-recreate server
```
4. 代码节点写入时报 EACCES: permission denied
→ 原因:容器内运行用户与宿主目录属主不一致,挂载进去后没有写权限。
→ 解决:先查容器内用户 ID,再把宿主目录属主改成它。
```bash
docker compose exec server id
sudo chown -R 1000:1000 /home/you/projects/demo
```
上面的 1000 以 id 命令实际输出为准。
5. 画布内容不刷新,或者多个标签页之间互相覆盖
→ 原因:同一份场景被多个标签页同时编辑,或者浏览器缓存了旧版前端。
→ 解决:关掉多余标签页,强制刷新(Ctrl/Cmd + Shift + R),必要时重启前端容器。
```bash
docker compose restart web
```
后续维护
备份:真正需要备份的是 .env(含密钥,注意权限)、数据库卷和你的工作目录代码。工作目录交给 Git 就好,体积数据卷用一次性容器打包:
```bash
docker run --rm \
-v drawgent_data:/data \
-v "$PWD/backup":/backup \
alpine tar czf /backup/data-$(date +%F).tgz -C /data .
```
卷名以 docker volume ls 实际输出为准。
升级:先备份,再看仓库的更新说明有没有数据库迁移步骤,然后三步走。
```bash
git pull
docker compose pull
docker compose up -d
```
如果新版改了环境变量,记得同步更新 .env。跨大版本升级时,建议先在测试环境跑一遍。
日志:给容器加上大小限制,避免日志把磁盘写满,在 docker-compose.yml 里配置:
```yaml
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
```
查看实时日志用 docker compose logs -f --tail=100。
监控:至少盯三件事——用 curl 定时探测健康检查接口、容器内存与 CPU 占用、以及模型 token 的消耗速度。画布上节点数量的增长也值得留意,节点越多,单轮调度消耗的 token 通常越高。
安全提醒:这套服务默认面向本机或内网,不要直接把带 API Key 的端口暴露到公网;确需外网访问时,在前面加一层带鉴权的反向代理。运行节点会执行真实命令,沙箱隔离能力要按官方文档的建议配置到位,别让智能体在宿主机上直接跑代码。