Budibase 本地开发环境搭建与运行指南从全新克隆到 dev 栈启动的完整实践【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase导读本文以 Budibase 官方开发者技能文档.agents/skills/budibase-setup-run/SKILL.md为核心骨架系统讲解在全新环境本地开发机或自动化 VM中完成 Budibase 单体仓库monorepo的克隆、环境准备、依赖安装、构建、启动与排障的全过程。你将掌握yarn setup、yarn dev与yarn dev:agent三条核心命令的差异与适用场景理解本地开发栈中 Nginx、Server、Worker、Builder、CouchDB、MinIO、Redis、LiteLLM 等服务的端口划分与角色分工并能根据源码定位到.env的生成逻辑、Docker 编排文件与健康检查入口独立完成本地登录与包级测试。一、Core Path全新克隆的标准流程对于一个全新的 Budibase 本地检出fresh local checkout官方推荐的完整流程如下# 1. 克隆并进入仓库 git clone https://github.com/Budibase/budibase.git cd budibase # 2. 使用仓库锁定的 Node 版本 nvm install nvm use node -v # 3. 安装 Yarn若尚未安装 npm install -g yarn yarn -v # 4. 确认 Docker 与 Compose 可用 docker --version docker compose version docker info # 5. 引导并启动项目普通本地开发 yarn setupBudibase 要求 Node 版本为22.0.0 23.0.0。仓库根目录的 .nvmrc 将版本锁定为v22.22.2同时根 package.json 的engines字段声明为node: 22.18.0 23.0.0因此推荐直接通过nvm install nvm use对齐仓库锁定版本避免出现由 Node 大版本差异引起的原生模块编译或语法兼容问题。yarn setup是一条聚合命令其真实定义位于根 package.json 的scripts.setupsetup: git config submodule.recurse true git submodule update node ./hosting/scripts/setup.js yarn yarn build yarn dev它依次完成四件事配置并拉取子模块git config submodule.recurse true git submodule update保证构建所依赖的子模块内容完整检查 Docker 前置条件执行 hosting/scripts/setup.js该脚本会通过command -v/where检测docker与docker-compose是否存在在 Linux 上缺失时会自动触发./hosting/scripts/linux/get-docker.sh与./hosting/scripts/linux/get-docker-compose.sh进行自动化安装安装完成后需要重新运行 setup 脚本安装依赖yarn工作区安装在根 package.json 的workspaces.packages中声明为packages/*构建并启动yarn build yarn dev最终拉起完整开发环境。对于依赖与构建产物可以被缓存的自动化 VM 环境官方建议使用 agent 路径yarn yarn build yarn dev:agentyarn dev:agent相比yarn dev有两处关键差异定义同样在根 package.jsondev:agent: yarn dev:init BUDIBASE_DEV_STACKcore LITELLM_MASTER_KEY lerna run --stream dev跳过根目录 clean/prebuild它不执行kill-all与包级 prebuild从而保留已有构建产物适合在成功构建之后或恢复一个已包含有效dist输出的 VM 镜像时使用只启动核心 Docker 服务并禁用 LiteLLM 就绪检查通过环境变量BUDIBASE_DEV_STACKcore只拉起核心服务并将LITELLM_MASTER_KEY置空以跳过 LiteLLM 的 readiness 检查让资源受限的 VM 环境启动更轻量。二、Manual Setup手动分步安装路径当yarn setup在中途失败或用户希望分步执行时可以使用手动路径yarn yarn build yarn dev首次搭建时yarn build是 dev 循环前的强制前置步骤因为运行中的 TS 编译与 dev server 依赖各包的dist产物。此后若修改了共享包如budibase/shared-core、budibase/backend-core或types需要再次执行yarn build使改动生效。从根 package.json 可以看到build的完整形态build: DISABLE_V8_COMPILE_CACHE1 NODE_OPTIONS--max-old-space-size1500 lerna run build --stream它通过 Lerna配置见 lerna.jsonnpmClient: yarn、独立版本模式流式并发构建所有 workspace 包并通过NODE_OPTIONS限制构建期堆内存以适配 CI/VM 环境。仓库还提供了范围化构建脚本如yarn build:npm只构建可发布的 npm 包与yarn build:apps只构建budibase/server与budibase/worker适合只想验证后端改动的场景。三、Running Locally本地开发环境启动在仓库根目录执行yarn dev该命令在根 package.json 中的定义是dev: yarn dev:init yarn run kill-all lerna run --parallel prebuild lerna run --stream dev它依次完成创建或更新.envyarn dev:init实际执行 scripts/dev/manage.js该脚本基于 hosting/docker-compose.dev.yaml 与运行时配置把SELF_HOSTED1、APPS_PORT4001、WORKER_PORT4002、CLUSTER_PORT10000、COUCH_DB_URLhttp://budibase:budibaselocalhost:4005、MINIO_URLhttp://localhost:4004、REDIS_URLlocalhost:6379、BB_ADMIN_USER_EMAILlocalbudibase.com、BB_ADMIN_USER_PASSWORDcheekychuckles等默认项写入仓库根目录.env已有配置会保留合并释放端口yarn kill-all内部为kill-port 3000与kill-port 4001 4002清理可能残留的 Builder/Server/Worker 进程并行执行包级 prebuild通过lerna run --parallel prebuild完成各包的构建前置清理启动完整开发栈lerna run --stream dev并行拉起 server、worker、builder 与 Docker 支撑服务。开发环境启动后通过 Nginx 代理访问主代理入口http://localhost:10000Builder可视化搭建界面http://localhost:10000/builder默认本地登录凭据邮箱localbudibase.com密码cheekychuckles这两项默认值由 scripts/dev/manage.js 中的BB_ADMIN_USER_EMAIL/BB_ADMIN_USER_PASSWORD写入.env并在本地账号初始化时生效。若你修改了.env中的这两项登录时请使用新值。对于构建成功后的自动化 VM 运行使用yarn dev:agent它保持普通开发工作流不变同时通过BUDIBASE_DEV_STACKcore减少启动的服务数量、降低缓存环境中的启动工作量与内存占用。四、Services And Ports本地服务与端口全景官方文档给出了完整的本地服务端口对照表服务端口说明Nginx 代理10000主入口统一转发各上游Builder3000Vite/Svelte 开发服务器Server4001Koa API处理应用数据接口Worker4002后台任务与平台 APIMinIO4004S3 兼容对象存储CouchDB4005主数据库CouchDB SQS4006队列相关的 CouchDB 服务Redis6379缓存、会话、队列LiteLLM4000可选 AI 代理token 为budibase这些端口在 hosting/docker-compose.dev.yaml 中均有对应的端口映射proxy-service将10000映射到容器内 Nginx 的10000监听端口couchdb-service同时暴露5984主库与4984SQS 队列库两个端口minio-service暴露9000API与9001控制台redis-service暴露6379litellm-service暴露4000。BUDIBASE_DEV_STACKcore模式下packages/server/scripts/dev/manage.js 只会启动minio-service、proxy-service、couchdb-service、redis-service这 4 个核心服务而跳过litellm-service与litellm-db。Nginx 代理的转发规则定义在 hosting/nginx.dev.conf/与/app、/app_、/api/走app-serviceServer4001/api/(system|admin|global)/走worker-serviceWorker4002/builder与/vite/走 Builder3000/db/直接透传 CouchDB其余路径默认指向 MinIO。注意 Worker 与 Server 的upstream使用${PROXY_ADDRESS}:端口开发环境通过host.docker.internal指向宿主机。健康检查命令curl http://localhost:4001/health curl http://localhost:4002/health对应 Nginx 配置中location /health反代到app-service/health的路由。你也可以通过http://localhost:10000/health从主入口验证整条代理链路。五、Common Commands常用开发命令速查目的命令构建全部包yarn build类型检查yarn check:types代码检查ESLint Prettieryarn lint包内运行测试cd packages/server yarn test path/to/test-file.test.ts只运行 Server 与 Workeryarn dev:server自动化环境优化启动yarn dev:agent其中yarn check:types在根 package.json 中定义为lerna run check:types会为所有包执行各自的tsc --noEmit检查例如 server 与 worker 的check:types脚本yarn dev:server的定义为yarn dev:init yarn run kill-server lerna run --stream dev --scope budibase/worker --scope budibase/server只拉起 worker 与 server 两个后端进程适合后端调试单包测试通过该包自身的scripts/test.sh见 packages/server/package.json 与 packages/worker/package.json驱动 Jest 执行。六、Troubleshooting常见问题排查Docker 命令失败确保 Docker Desktop 或 Docker daemon 已启动后再重新运行 setup。Linux 缺失时 hosting/scripts/setup.js 会尝试自动安装 Docker 与 Compose。端口残留导致启动异常执行yarn kill-all清理 3000/4001/4002 端口上的残留进程后再启动。依赖或构建产物损坏执行yarn restore定义为yarn run clean yarn yarn run build。它只清理并重建 node_modules 与构建产物不会删除 Docker 容器与卷数据因此数据库与对象存储内容得以保留。云 VM 中的嵌套 Dockeryarn dev前可能需要手动启动 Dockersudo dockerd注意不要将/var/run/docker.sock改为全局可写。若遇到 Docker 权限错误应使用环境认可的 Docker 用户组、rootless Docker 或 VM 预置方案而不是放宽 socket 权限。浏览器中看不到本地改动清除浏览器中针对localhost的 Budibase cookies本地开发模式缓存了部分状态清 Cookie 后重新登录即可。七、Contributor Notes包结构与测试基础设施Budibase 是典型的 Yarn workspace 单体仓库包之间统一使用budibase/前缀的 scoped import主要包划分如下后端packages/serverKoa API 服务、packages/worker后台任务/平台 API、packages/backend-core共享后端核心前端packages/builder可视化搭建器、packages/frontend-core、packages/bbuiSvelte 组件库共享packages/shared-core前后端共享的类型与工具从 packages/builder/package.json 可看到 Builder 依赖budibase/bbui、budibase/frontend-core、budibase/shared-core等前端包其开发脚本为routify -c dev:viteVite 7 Svelte而从 packages/server/package.json 可以看到 Server 依赖budibase/backend-core、budibase/pro、budibase/string-templates等并以 Koa、Bull队列、isolated-vmJS Runner为核心技术栈。编写测试时官方推荐Server API 测试优先使用packages/server/src/tests/TestConfiguration.ts提供的TestConfiguration工具类来搭建测试上下文自动化Automation测试使用packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts中的createAutomationBuilder构建自动化测试。这两个测试工具与packages/server/scripts/dev/manage.js中的dev:stack:up/dev:stack:down/dev:stack:nuke命令配合可在本地拉起或清理测试所需的 Docker 依赖CouchDB、MinIO、Redis 等从而支持在包内直接运行集成级测试。结语从git clone到yarn dev完整跑通 Budibase 本地开发环境关键在于理解三层结构环境准备层Node 版本、Yarn、Docker/Compose 检查与自动安装、构建层Lerna 驱动的 workspace 构建与dist产物与运行层yarn dev/yarn dev:agent背后的.env生成、端口释放、包 prebuild 与 Docker 编排。日常开发中按需选择yarn dev完整交互式开发或yarn dev:agent缓存/VM 环境轻量启动遇到问题依次检查 Docker 状态、端口占用与.env配置即可快速恢复可用的开发环境。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 0:01:32 · 阅读 1.2k Budibase 本地开发环境搭建与运行指南：从全新克隆到 dev 栈启动的完整实践
Budibase 本地开发环境搭建与运行指南从全新克隆到 dev 栈启动的完整实践【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase导读本文以 Budibase 官方开发者技能文档.agents/skills/budibase-setup-run/SKILL.md为核心骨架系统讲解在全新环境本地开发机或自动化 VM中完成 Budibase 单体仓库monorepo的克隆、环境准备、依赖安装、构建、启动与排障的全过程。你将掌握yarn setup、yarn dev与yarn dev:agent三条核心命令的差异与适用场景理解本地开发栈中 Nginx、Server、Worker、Builder、CouchDB、MinIO、Redis、LiteLLM 等服务的端口划分与角色分工并能根据源码定位到.env的生成逻辑、Docker 编排文件与健康检查入口独立完成本地登录与包级测试。一、Core Path全新克隆的标准流程对于一个全新的 Budibase 本地检出fresh local checkout官方推荐的完整流程如下# 1. 克隆并进入仓库 git clone https://github.com/Budibase/budibase.git cd budibase # 2. 使用仓库锁定的 Node 版本 nvm install nvm use node -v # 3. 安装 Yarn若尚未安装 npm install -g yarn yarn -v # 4. 确认 Docker 与 Compose 可用 docker --version docker compose version docker info # 5. 引导并启动项目普通本地开发 yarn setupBudibase 要求 Node 版本为22.0.0 23.0.0。仓库根目录的 .nvmrc 将版本锁定为v22.22.2同时根 package.json 的engines字段声明为node: 22.18.0 23.0.0因此推荐直接通过nvm install nvm use对齐仓库锁定版本避免出现由 Node 大版本差异引起的原生模块编译或语法兼容问题。yarn setup是一条聚合命令其真实定义位于根 package.json 的scripts.setupsetup: git config submodule.recurse true git submodule update node ./hosting/scripts/setup.js yarn yarn build yarn dev它依次完成四件事配置并拉取子模块git config submodule.recurse true git submodule update保证构建所依赖的子模块内容完整检查 Docker 前置条件执行 hosting/scripts/setup.js该脚本会通过command -v/where检测docker与docker-compose是否存在在 Linux 上缺失时会自动触发./hosting/scripts/linux/get-docker.sh与./hosting/scripts/linux/get-docker-compose.sh进行自动化安装安装完成后需要重新运行 setup 脚本安装依赖yarn工作区安装在根 package.json 的workspaces.packages中声明为packages/*构建并启动yarn build yarn dev最终拉起完整开发环境。对于依赖与构建产物可以被缓存的自动化 VM 环境官方建议使用 agent 路径yarn yarn build yarn dev:agentyarn dev:agent相比yarn dev有两处关键差异定义同样在根 package.jsondev:agent: yarn dev:init BUDIBASE_DEV_STACKcore LITELLM_MASTER_KEY lerna run --stream dev跳过根目录 clean/prebuild它不执行kill-all与包级 prebuild从而保留已有构建产物适合在成功构建之后或恢复一个已包含有效dist输出的 VM 镜像时使用只启动核心 Docker 服务并禁用 LiteLLM 就绪检查通过环境变量BUDIBASE_DEV_STACKcore只拉起核心服务并将LITELLM_MASTER_KEY置空以跳过 LiteLLM 的 readiness 检查让资源受限的 VM 环境启动更轻量。二、Manual Setup手动分步安装路径当yarn setup在中途失败或用户希望分步执行时可以使用手动路径yarn yarn build yarn dev首次搭建时yarn build是 dev 循环前的强制前置步骤因为运行中的 TS 编译与 dev server 依赖各包的dist产物。此后若修改了共享包如budibase/shared-core、budibase/backend-core或types需要再次执行yarn build使改动生效。从根 package.json 可以看到build的完整形态build: DISABLE_V8_COMPILE_CACHE1 NODE_OPTIONS--max-old-space-size1500 lerna run build --stream它通过 Lerna配置见 lerna.jsonnpmClient: yarn、独立版本模式流式并发构建所有 workspace 包并通过NODE_OPTIONS限制构建期堆内存以适配 CI/VM 环境。仓库还提供了范围化构建脚本如yarn build:npm只构建可发布的 npm 包与yarn build:apps只构建budibase/server与budibase/worker适合只想验证后端改动的场景。三、Running Locally本地开发环境启动在仓库根目录执行yarn dev该命令在根 package.json 中的定义是dev: yarn dev:init yarn run kill-all lerna run --parallel prebuild lerna run --stream dev它依次完成创建或更新.envyarn dev:init实际执行 scripts/dev/manage.js该脚本基于 hosting/docker-compose.dev.yaml 与运行时配置把SELF_HOSTED1、APPS_PORT4001、WORKER_PORT4002、CLUSTER_PORT10000、COUCH_DB_URLhttp://budibase:budibaselocalhost:4005、MINIO_URLhttp://localhost:4004、REDIS_URLlocalhost:6379、BB_ADMIN_USER_EMAILlocalbudibase.com、BB_ADMIN_USER_PASSWORDcheekychuckles等默认项写入仓库根目录.env已有配置会保留合并释放端口yarn kill-all内部为kill-port 3000与kill-port 4001 4002清理可能残留的 Builder/Server/Worker 进程并行执行包级 prebuild通过lerna run --parallel prebuild完成各包的构建前置清理启动完整开发栈lerna run --stream dev并行拉起 server、worker、builder 与 Docker 支撑服务。开发环境启动后通过 Nginx 代理访问主代理入口http://localhost:10000Builder可视化搭建界面http://localhost:10000/builder默认本地登录凭据邮箱localbudibase.com密码cheekychuckles这两项默认值由 scripts/dev/manage.js 中的BB_ADMIN_USER_EMAIL/BB_ADMIN_USER_PASSWORD写入.env并在本地账号初始化时生效。若你修改了.env中的这两项登录时请使用新值。对于构建成功后的自动化 VM 运行使用yarn dev:agent它保持普通开发工作流不变同时通过BUDIBASE_DEV_STACKcore减少启动的服务数量、降低缓存环境中的启动工作量与内存占用。四、Services And Ports本地服务与端口全景官方文档给出了完整的本地服务端口对照表服务端口说明Nginx 代理10000主入口统一转发各上游Builder3000Vite/Svelte 开发服务器Server4001Koa API处理应用数据接口Worker4002后台任务与平台 APIMinIO4004S3 兼容对象存储CouchDB4005主数据库CouchDB SQS4006队列相关的 CouchDB 服务Redis6379缓存、会话、队列LiteLLM4000可选 AI 代理token 为budibase这些端口在 hosting/docker-compose.dev.yaml 中均有对应的端口映射proxy-service将10000映射到容器内 Nginx 的10000监听端口couchdb-service同时暴露5984主库与4984SQS 队列库两个端口minio-service暴露9000API与9001控制台redis-service暴露6379litellm-service暴露4000。BUDIBASE_DEV_STACKcore模式下packages/server/scripts/dev/manage.js 只会启动minio-service、proxy-service、couchdb-service、redis-service这 4 个核心服务而跳过litellm-service与litellm-db。Nginx 代理的转发规则定义在 hosting/nginx.dev.conf/与/app、/app_、/api/走app-serviceServer4001/api/(system|admin|global)/走worker-serviceWorker4002/builder与/vite/走 Builder3000/db/直接透传 CouchDB其余路径默认指向 MinIO。注意 Worker 与 Server 的upstream使用${PROXY_ADDRESS}:端口开发环境通过host.docker.internal指向宿主机。健康检查命令curl http://localhost:4001/health curl http://localhost:4002/health对应 Nginx 配置中location /health反代到app-service/health的路由。你也可以通过http://localhost:10000/health从主入口验证整条代理链路。五、Common Commands常用开发命令速查目的命令构建全部包yarn build类型检查yarn check:types代码检查ESLint Prettieryarn lint包内运行测试cd packages/server yarn test path/to/test-file.test.ts只运行 Server 与 Workeryarn dev:server自动化环境优化启动yarn dev:agent其中yarn check:types在根 package.json 中定义为lerna run check:types会为所有包执行各自的tsc --noEmit检查例如 server 与 worker 的check:types脚本yarn dev:server的定义为yarn dev:init yarn run kill-server lerna run --stream dev --scope budibase/worker --scope budibase/server只拉起 worker 与 server 两个后端进程适合后端调试单包测试通过该包自身的scripts/test.sh见 packages/server/package.json 与 packages/worker/package.json驱动 Jest 执行。六、Troubleshooting常见问题排查Docker 命令失败确保 Docker Desktop 或 Docker daemon 已启动后再重新运行 setup。Linux 缺失时 hosting/scripts/setup.js 会尝试自动安装 Docker 与 Compose。端口残留导致启动异常执行yarn kill-all清理 3000/4001/4002 端口上的残留进程后再启动。依赖或构建产物损坏执行yarn restore定义为yarn run clean yarn yarn run build。它只清理并重建 node_modules 与构建产物不会删除 Docker 容器与卷数据因此数据库与对象存储内容得以保留。云 VM 中的嵌套 Dockeryarn dev前可能需要手动启动 Dockersudo dockerd注意不要将/var/run/docker.sock改为全局可写。若遇到 Docker 权限错误应使用环境认可的 Docker 用户组、rootless Docker 或 VM 预置方案而不是放宽 socket 权限。浏览器中看不到本地改动清除浏览器中针对localhost的 Budibase cookies本地开发模式缓存了部分状态清 Cookie 后重新登录即可。七、Contributor Notes包结构与测试基础设施Budibase 是典型的 Yarn workspace 单体仓库包之间统一使用budibase/前缀的 scoped import主要包划分如下后端packages/serverKoa API 服务、packages/worker后台任务/平台 API、packages/backend-core共享后端核心前端packages/builder可视化搭建器、packages/frontend-core、packages/bbuiSvelte 组件库共享packages/shared-core前后端共享的类型与工具从 packages/builder/package.json 可看到 Builder 依赖budibase/bbui、budibase/frontend-core、budibase/shared-core等前端包其开发脚本为routify -c dev:viteVite 7 Svelte而从 packages/server/package.json 可以看到 Server 依赖budibase/backend-core、budibase/pro、budibase/string-templates等并以 Koa、Bull队列、isolated-vmJS Runner为核心技术栈。编写测试时官方推荐Server API 测试优先使用packages/server/src/tests/TestConfiguration.ts提供的TestConfiguration工具类来搭建测试上下文自动化Automation测试使用packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts中的createAutomationBuilder构建自动化测试。这两个测试工具与packages/server/scripts/dev/manage.js中的dev:stack:up/dev:stack:down/dev:stack:nuke命令配合可在本地拉起或清理测试所需的 Docker 依赖CouchDB、MinIO、Redis 等从而支持在包内直接运行集成级测试。结语从git clone到yarn dev完整跑通 Budibase 本地开发环境关键在于理解三层结构环境准备层Node 版本、Yarn、Docker/Compose 检查与自动安装、构建层Lerna 驱动的 workspace 构建与dist产物与运行层yarn dev/yarn dev:agent背后的.env生成、端口释放、包 prebuild 与 Docker 编排。日常开发中按需选择yarn dev完整交互式开发或yarn dev:agent缓存/VM 环境轻量启动遇到问题依次检查 Docker 状态、端口占用与.env配置即可快速恢复可用的开发环境。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考