5分钟本地跑通Superflows：Docker+Supabase开发环境搭建完整指南

5分钟本地跑通Superflows：Docker+Supabase开发环境搭建完整指南

【免费下载链接】superflowsOpen-source toolkit to build an AI copilot for SaaS products项目地址: https://gitcode.com/gh_mirrors/su/superflows

Superflows 是一个用于给 SaaS 产品构建 AI 副驾（AI copilot）的开源工具包。本指南带你用 Docker + Supabase 在本地快速跑通 Superflows，全程只需 5 条命令，体验一个能调用你自己 API、用自然语言回答问题的 AI 助手。

为什么要在本地部署 Superflows？

Superflows 让你用几行代码就把 AI 助手嵌入自己的产品：用户用自然语言提问，助手自动调用产品的 API 端点完成任务，还能写代码做数据分析、画图表 📊。

本地开发环境最大的价值在于：

• 完全可控：数据库、鉴权、模型配置都在自己手里
• 快速迭代：修改 lib/ 下的提示词与工具函数后热更新生效
• 零成本实验：配合 Mock API 功能，不连真实接口也能调试助手行为

完整功能介绍可参考项目 README.md。

准备工作：2分钟装好前置工具

开始之前，请确认电脑上已安装以下 3 个工具 🧰：

💡Windows 用户注意：建议在 Git Bash 或 WSL 中操作（脚本为 bash 脚本），部分命令可能需要管理员权限。

第一步：克隆 Superflows 仓库

git clone https://gitcode.com/gh_mirrors/su/superflows cd superflows

仓库里已经内置了开发所需的全部配置，其中 docker/development/ 目录存放着一键初始化脚本和编排文件。

第二步：用 init.sh 一键初始化环境

这是整个流程中最"省心"的一步 🚀。初始化脚本位于 docker/development/init.sh，它会替你完成三件事：

1. 拉取 Supabase 本地 Docker 文件（稀疏检出，只取 docker 目录）
2. 自动合并生成.env配置文件（由项目 .env.example 与 Supabase 的模板拼接而成）
3. 启动并构建所有容器

cd docker/development chmod +x init.sh ./init.sh

Windows PowerShell 用户可以使用对应的 init-windows.ps1，流程完全一致。

首次运行需要拉取多个镜像，耐心等待几分钟即可。若中途看到Ctrl+C to stop the process提示，说明容器正在构建，属于正常现象。

第三步：在 .env 中填入 1 个密钥

初始化完成后，项目根目录已生成.env文件，其中数据库连接、Supabase 密钥等都已自动配置好默认值。你只需要填一个必填项：

OPENAI_API_KEY=sk-你的密钥

其余变量说明（参考 .env.example）：

小提示：数据库的 anon key 与 service_role key 由 Supabase 容器自动生成，Docker 模式下无需手动填写。

第四步：Docker Compose 一键启动

如果init.sh已成功跑完，服务其实已在运行；若想手动（重新）启动，使用：

docker compose up -d --build

编排逻辑定义在 docker/development/docker-compose.yml：superflows容器会在启动时自动执行数据库迁移（应用 supabase/migrations/ 下的全部 SQL），再进入npm run dev开发模式。应用镜像由 docker/development/Dockerfile 基于 node:alpine 构建，并将整个项目目录挂载为卷，改代码即可热更新，无需重建镜像。

启动后确认容器状态：

docker ps

看到superflows与supabase-db、kong等容器均为 Up 状态即代表成功 ✅

第五步：打开控制台，体验 AI 助手

打开浏览器访问 http://localhost:8080，你会看到开发者控制台：

• Playground：直接与助手对话，打开 Developer mode 可看到助手的"思考过程"
• Actions：管理助手可调用的 API 端点，支持通过 OpenAPI 规范一键上传
• Mock API Responses：不连真实接口也能验证助手行为
• Usage：跟踪用量，便于计费与限流

备选方案：不用 Docker，用 Supabase CLI 本地运行

如果你希望把 Supabase 跑在宿主机上（例如想直接调试数据库），可以走纯 npm 路线（README 中的 Local setup 章节）：

npm i npm install supabase --save-dev npx supabase start

supabase start会输出anon_api_key和service_role两个密钥，把它们填入.env（模板见 .env.example）即可。然后启动开发服务器：

make run

若没有安装make，等价命令是npm run dev（Makefile 中run目标，脚本定义在 package.json）。

⚠️ 如果你之前在别的项目用过 Supabase CLI，先执行supabase stop再启动，避免端口冲突。

常见问题：最快排障方法

总结：5 分钟，从克隆到跑通 AI 助手

回顾一下完整路径：克隆仓库 →init.sh初始化 → 填OPENAI_API_KEY→docker compose up -d --build→ 打开 http://localhost:8080。

至此你已经拥有了一个可自由定制的 Superflows 本地开发环境：修改 lib/prompts/ 调整提示词、在 Actions 页面对接自己的 API、用 Playground 实时验证效果。想要把助手嵌入真实产品，官方还提供了开箱即用的 React 组件，后续可以进一步探索 pages/playground.tsx 与 components/playground.tsx 的实现细节。Happy hacking 🛠️

【免费下载链接】superflowsOpen-source toolkit to build an AI copilot for SaaS products项目地址: https://gitcode.com/gh_mirrors/su/superflows