如何 10 分钟自部署 ButterbaseDocker Compose 完全上手教程新手必读【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-ossButterbase 是一个开源的 Backend-as-a-ServiceBaaS平台把Postgres 数据库、用户认证、文件存储、无服务器函数、AI 网关和 MCP 服务整合在一套 API 里。本文手把手教你用Docker Compose 自部署Butterbase一条命令拉起完整后端无需注册任何云服务10 分钟内就能在本地跑通一个可用的 BaaS 平台。自部署前需要准备什么只需两个工具工具版本要求说明Docker较新版本含 Compose v2本地跑所有服务Node.js22执行迁移脚本和种子数据 本地部署开箱即用认证默认关闭、计费使用空实现、配额不限制非常适合学习和 PoC。一键克隆仓库记得带子模块packages/plugin目录是一个 git 子模块普通 clone 会导致该目录为空。请使用加速镜像仓库git clone --recurse-submodules https://gitcode.com/gh_mirrors/bu/butterbase-oss cd butterbase-oss如果之前已经 clone 过补一句git submodule update --init --recursive即可。安装依赖并配置环境变量npm ci cp .env.example .env默认本地配置基本不用改docker-compose.local.yml 已经帮你设好了 Redis、数据库连接等关键变量。所有可选项Sentry、OpenRouter、R2 等都在 .env.example 里注释说明。用 Docker Compose 启动整套服务docker compose -f docker-compose.local.yml up -d⏳ 首次运行会构建 control-api 镜像需要几分钟耐心等待即可。用下面的命令确认服务是否就绪docker compose -f docker-compose.local.yml ps curl -sf http://localhost:4000/health/ready这套 Compose 文件一次拉起11 个容器覆盖完整数据链路服务端口作用control-api4000主 API 入口内置 MCP/mcpdeno-runtime7133执行用户无服务器函数docs4321本地文档站control-plane-db5433平台元数据用户、应用、审计data-plane-db5435每个应用独立的业务数据库runtime-plane-db5437区域运行时热路径表pgbouncer / redis6432 / 6379连接池 计量与 KV 过期localstack4566本地 S3 兼容对象存储traefik80 / 8080本地路由可选手动执行数据库迁移迁移不会在容器启动时自动执行需要手动跑一次完整 SQL 按平面分目录存放db/control-plane/、db/runtime-plane/、db/data-plane/export NEON_PLATFORM_PRIMARY_URLpostgresql://butterbase:butterbase_devlocalhost:5433/butterbase_control export NEON_RUNTIME_PROJECT_ID_US_EAST_1postgresql://butterbase:butterbase_devlocalhost:5437/butterbase_runtime_us export BUTTERBASE_REGIONSus-east-1 npm run migrate:all⚠️ 不要直接用psql手动执行这些 SQL 文件请始终使用迁移脚本它会处理 scope 头部的作用域信息。种子一个本地开发用户本地配置关闭了认证所有请求会被归属到一个开发所有者。全新数据库里这个用户还不存在需要种一次子npm run seed:dev脚本会插入devbutterbase.local与dev-adminbutterbase.local两个用户幂等可重复执行对应源码见 scripts/seed-dev-user.ts。30 秒冒烟测试创建第一个应用本地认证是关闭的直接调用 API 就能建应用curl -X POST http://localhost:4000/init \ -H Content-Type: application/json \ -d {name: my-app} curl http://localhost:4000/apps看到返回的应用列表说明你的Butterbase 自部署已经彻底跑通 ✅部署完成后你能做什么本地实例与托管版使用同一套运行时数据面声明式 schema、自动 REST 接口auto-api、行级安全RLS、KV 存储、文件存储、Realtime、AI 网关和 RAG 全部可用。1️⃣ 对接 MCP 客户端MCP 服务已内嵌在 control-api 的/mcp路径services/mcp-server/AI 助手可以把你的整个后端当作工具箱来操作。2️⃣ 使用 CLI 和 SDK 开发仓库自带 packages/cli/butterbase命令行工具和 packages/sdk/TypeScript SDK脚手架、部署、管理一把梭。3️⃣ 克隆完整模板应用templates/ 里有两个生产级完整应用——CRM 和 AI 客服自带 schema、RLS 策略和 55 函数。模板浏览器中的 Clone 操作会把完整后端数据库、URL、API Key分叉成一个你拥有的新应用比如 butterbaseCRM 是一个带看板、AI 搜索和客户数据补全的开源 CRM而 butterSupport 是 AI 客服智能体支持为不同问题类型如 billing、password_reset单独配置自动回复或人工升级策略新手最常踩的 3 个坑❓ control-api 启动即退出日志报Missing KV_REDIS_URL_US_EAST_1一般是环境变量没应用上重建该容器即可docker compose -f docker-compose.local.yml up -d control-api❓/init或/apps返回 401 / User not found漏了种子用户步骤重新执行npm run seed:dev。❓ 想彻底重来一遍docker compose -f docker-compose.local.yml down -v docker compose -f docker-compose.local.yml up -d⚠️down -v会删除所有数据卷之后需要重跑迁移和种子用户。总结从克隆到跑通只需 6 条命令git clone --recurse-submodules获取代码npm ci cp .env.example .envdocker compose -f docker-compose.local.yml up -dnpm run migrate:allnpm run seed:devcurl http://localhost:4000/apps验证更多生产部署建议、认证开启方式API Key / Cognito和完整排障指南请阅读仓库根目录的 SETUP.md 与 README.md 中 Self-host 章节。现在你的 Butterbase 后端已经就绪开始构建第一个 AI 应用吧【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考