Butterbase 核心概念入门：App、控制面、运行面与数据面三平面架构详解

Butterbase 核心概念入门App、控制面、运行面与数据面三平面架构详解【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss初次接触Butterbase开源后端即服务Backend-as-a-Service平台时最容易听混的一组术语就是App应用、控制面Control Plane、运行面Runtime Plane和数据面Data Plane。本文用最少的代码、最多的直觉带你一次看懂 Butterbase 的核心概念和三平面架构帮你快速建立对整个平台的完整心智模型 。Butterbase 是什么一句话版本Butterbase 是一个面向 AI 时代的开源后端平台你不需要自己拼装数据库、登录认证、文件存储、函数和 AI 网关——Postgres 数据库、用户认证、对象存储、Serverless 函数、AI 网关、MCP 服务器全部开箱即用并且每个能力都可以通过 MCP 工具直接被 AI Agent 调用。你可以把它理解为一个会把自己当成工具箱递给 AI 的后端云平台。核心概念一App应用在 Butterbase 里App 是资源隔离的基本单位。每创建一个 App你就同时得到了一整套完整后端独立的数据库含独立的 schema 与行级安全策略独立的 API 基础 URL 与 API Key独立的函数、存储桶、实时通道、KV 命名空间理解这一点很关键用户数据、计算资源和平台元信息都是围绕 App 来组织和隔离的。后面讲到的三个平面本质上就是围绕 App 管理不同类型数据与资源的地方。核心概念二三平面架构Butterbase 把 Postgres 数据库拆成三个相互独立的平面每个平面承担不同的职责。这是理解 Butterbase 架构最重要的部分1️⃣ 控制面Control Plane——平台的管理后台控制面存放的是平台级元数据用户账户、App 的注册信息、订阅与计费、审计日志、API Key 等。它回答的是谁拥有哪些 App、用了多少资源这类问题。数据库迁移脚本位于 db/control-plane/从 001_initial_schema.sql 到 123_plans_credit_floor_zero.sql 共 120 个迁移文件可以完整看到平台元数据的演进史对应的服务入口是 services/control-api/——一个 Fastify 应用承担所有公开 API并在/mcp路径内嵌了 MCP 服务器2️⃣ 运行面Runtime Plane——高频运行时状态运行面存放请求热路径上的运行时表KV 暴露规则、实时通道、会话状态、用量计量、AI 调用日志等。它介于纯元数据和用户数据之间特点是访问频率高、与具体区域Region绑定。迁移脚本位于 db/runtime-plane/例如 008_usage_meters.sql用量计量、029_ai_responses.sqlAI 调用记录负责执行用户代码的运行时就部署在这个平面旁边services/deno-runtime/Deno 隔离执行 Serverless 函数、services/agent-runtime/Python 编写的长时 Agent 执行器3️⃣ 数据面Data Plane——你的用户数据数据面存放每个 App 真正的业务数据。每个 App 在这里获得隔离的 schema并通过行级安全Row-Level Security, RLS策略保证用户只能访问自己的数据。迁移脚本位于 db/data-plane/其中 004_rls_helpers.sql 和 005_rls_role_based.sql 展示了 RLS 辅助体系的构建方式数据库与 RLS 的详细文档见 core-concepts/database.md 和 core-concepts/row-level-security.md记忆口诀控制面管账运行面管忙数据面管数据。三平面的官方定义可以直接在 README.md 的 Architecture 一节找到README.md 还配有一张完整的架构图。一次请求在三个平面间如何流转以用户调用你 App 的 API为例三个平面各干各的控制面验证 API Key / 会话是否有效、这个 App 属于谁、配额是否用尽运行面读取本次请求所需的运行时状态KV 规则、实时通道、写入一条用量/审计记录数据面真正读写你 App 的表RLS 策略在 SQL 层面拦截越权访问三者物理上独立本地开发时分别运行在 5433 / 5437 / 5435 端口见 SETUP.md 的本地服务表逻辑上又通过 App ID 串联互不干扰。这也是 Butterbase 能做到多租户隔离 区域Region级部署的基础。快速认识代码库结构结合前面的概念仓库顶层目录其实一目了然目录对应概念说明db/三个平面control-plane / runtime-plane / />动手体验5 分钟跑通一个 App最快的上手方式是按 SETUP.md 用 Docker Compose 自托管完整步骤见 docker-compose.local.yml克隆仓库git clone --recurse-submodules https://gitcode.com/gh_mirrors/bu/butterbase-ossnpm ci cp .env.example .envdocker compose -f docker-compose.local.yml up -d启动整栈执行npm run migrate:all应用三个平面的迁移用一条curl创建你的第一个 App本地默认关闭认证详见 SETUP.md启动后你可以直接访问控制面 APIhttp://localhost:4000创建 App、定义 schema、部署函数——这就是在真实环境中观察三平面协作的最佳方式。小结一张表带走本文概念一句话理解在哪看代码/文档App资源隔离的基本单位一整套后端introduction.md控制面管账户、App 注册、计费、审计db/control-plane/运行面管高频运行时状态与代码执行db/runtime-plane/数据面管每个 App 的业务数据 RLS 隔离db/data-plane/掌握这四个词你就读得懂 Butterbase 的目录结构、文档和路线图了。下一步建议先用模板克隆一个完整 Appbutterbase clone流程见 templates/README.md再回头看这三平面体会会深得多 【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考