Budibase 源码仓库开发全指南Lerna Monorepo 架构、测试规范与本地开发环境搭建【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase本篇技术指南以 Budibase 仓库根目录的CLAUDE.mdBudibase Agent Guide为骨架系统讲解这个 AI 驱动的低代码平台AI agents、automations and apps that run your operations源码仓库的开发全貌从 Lerna monorepo 的包划分与budibase/依赖约定到构建、测试、类型检查的完整命令矩阵再到代码风格、server 包测试基建、Git/PR 协作流程最后落地到一套可复现的本地开发环境Nginx 10000 / Server 4001 / Worker 4002 / CouchDB 4005 / Redis 6379 / MinIO 4004 / LiteLLM 4000。读完你将掌握如何在 Budibase monorepo 中写符合规范的代码、如何用datasourceDescribe等基建编写数据源/自动化测试、如何一键拉起并调试完整的本地开发栈。一、架构总览Lerna Monorepo 与包划分Budibase 是一个以 Lerna 管理的工作区workspacemonorepo全部包位于根目录packages/下。根 package.json 中通过workspaces.packages [packages/*]声明工作区lerna.json 采用version: independent各包独立版本并以yarn作为 npmClient、默认并发数 20。1.1 主包清单与运行环境CLAUDE.md明确划分了各主包的职责与运行环境包运行环境定位packages/serverNodeJS应用后端 APIKoa承载应用/数据源/自动化逻辑packages/workerNodeJS后台任务与账户/租户管理 Workerpackages/backend-coreNodeJS后端共享核心DB、认证、事件、对象存储等packages/frontend-core浏览器前端共享核心组件、fetch、API 封装packages/client浏览器应用运行时客户端渲染库packages/builder浏览器可视化构建器Vite/Sveltepackages/shared-coreNodeJS 与浏览器前后端共用核心自动化、过滤、主题、翻译等packages/bbui浏览器基础 UI 组件库Svelte除此之外仓库还包含packages/types跨包共享 TypeScript 类型、packages/string-templates模板渲染/表达式、packages/cli、packages/pro企业版与packages/sdk等包。1.2 包间依赖约定包间依赖统一使用budibase/前缀的 scoped import例如import { Datasource } from budibase/types根 package.json 的resolutions中对budibase/backend-core、budibase/shared-core、budibase/string-templates、budibase/types统一解析为*保证工作区内始终链接到本地源码版本。1.3 Node 版本约束根目录 .nvmrc 固定为v22.22.2同时根 package.json 的engines声明node: 22.18.0 23.0.0。编写或 review 代码时应以该版本为目标避免使用版本不兼容的 API。二、构建 / 测试 / 类型检查命令矩阵CLAUDE.md给出了四类核心命令以下是结合根 package.json 脚本的完整解读。2.1 构建yarn build根build脚本实际执行DISABLE_V8_COMPILE_CACHE1 NODE_OPTIONS--max-old-space-size1500 lerna run build --stream即递归触发所有包的build。仓库还提供细分构建yarn build:npm只构建可发布的库包backend-core、bbui、cli、frontend-core、pro、sdk、shared-core、string-templates、typesyarn build:apps只构建应用包server、workeryarn build:devprebuild后进入lerna watch监听模式源码变更自动增量构建。2.2 代码检查Lintyarn lint # 检查 yarn lint:fix # 自动修复根lint由两部分组成lint:eslinteslint packages与lint:prettierprettier --check packages/**/*.{js,ts,svelte}。lint:fix默认只对本次变更的文件执行node ./scripts/lintChanged.js fix避免全库格式化造成噪音如需全局修复可使用yarn lint:fix:alleslint prettier 全量。2.3 测试# 需在某个 packages/* 目录内执行 yarn test filename根test脚本为lerna run --concurrency 1 --stream test串行跑所有包。包内测试底层均为 Jestpackages/server与packages/backend-core通过各自的scripts/test.sh包装shared-core、string-templates等直接由 jest 驱动。packages/server/scripts/test.sh对 CI 与本地做了差异化处理CI 环境NODE_OPTIONS--max-old-space-size4096、--maxWorkers4 --bail追求速度与失败即停本地环境则--coverage --maxWorkers2生成覆盖率报告。2.4 类型检查yarn check:types根check:types为lerna run check:types逐包执行。由于类型依赖跨包precheck:types会先构建budibase/types、budibase/backend-core、budibase/shared-core、budibase/pro保证类型检查基于最新产物。2.5 数据源测试的环境变量DATASOURCEpackages/server中凡是使用datasourceDescribe的测试都支持通过环境变量收窄到单个数据库DATASOURCEpostgres yarn test some-datasource-test可选值定义在 packages/server/src/integrations/tests/utils/index.ts 的DatabaseName枚举中枚举值对应数据库postgres/postgres_legacyPostgreSQL新旧两套连接配置mongodbMongoDBmysqlMySQLmssqlSQL ServermariadbMariaDBoracleOraclesqs内部CouchDB SQS数据源elasticsearchElasticsearchdynamodbDynamoDB当DATASOURCE未设置时datasourceDescribe默认跑全部数据源设为none或过滤后为空时会注入一个占位空测试createDummyTest避免 Jest 因测试文件无用例报错——这正是 index.ts 注释中说明的 CI 场景。三、代码风格规范CLAUDE.md对代码风格有非常明确的要求且与仓库工具链一一对应。3.1 格式化基调Prettier.prettierrc.json中的配置是无分号、双引号、2 空格缩进的直接来源{ tabWidth: 2, semi: false, singleQuote: false, trailingComma: es5, arrowParens: avoid, bracketSameLine: false, plugins: [prettier-plugin-svelte] }同时trailingComma: es5、arrowParens: avoid也属于既定风格新代码默认遵守。3.2 TypeScript 规范启用 strict 模式并启用consistent-type-imports类型导入统一使用import type形式类型定义对象用interface联合类型/原始类型用type禁止 cast 到any或unknown优先直接导入已命名的领域类型而不是通过索引访问推导。例如使用RestTemplateId而不是TemplateSelectionContext[restTemplateId]禁止使用// ts-nocheck来绕过类型错误修复除非任务明确要求不要添加向后兼容路径或覆盖所有场景的过度防御逻辑。3.3 JavaScript / 通用规范变量使用 camelCase未使用参数以_前缀标记函数优先使用箭头函数异步逻辑用async/await而非 Promise 链错误处理统一try/catch导入分组外部依赖在前budibase/*内部包在后避免嵌套三元表达式多输入参数的函数必须使用对象参数仅当保持既有外部 API 时才保留位置参数注释只在确实需要解释不直观行为时添加。3.4 日志与前端环境差异测试代码禁用console.log因为测试输出不会出现在 STDOUT只断言最终结果不检查中间状态应用代码使用console.log而非直接调 pino——Budibase 已做重定向应用内的console.log会自动进入 pino 日志框架Builder 代码运行在浏览器环境不要用typeof window undefined守卫浏览器全局对象Svelte优先采用 Svelte 5 写法而非 Svelte 4URL 测试涉及 URL 的测试统一使用example.com域名。四、packages/server 测试基建深度解读CLAUDE.md单独辟出 Test style - packages/server 一节明确 server 包测试必须使用的三件套基建。4.1 自动化测试createAutomationBuilder构建自动化测试用例时统一使用createAutomationBuilder工厂函数位于 packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts。它以链式/声明式方式组装自动化的触发条件与执行步骤避免手写复杂的自动化文档结构。4.2 资源构造basicTable等 structures 函数创建表、数据源、查询等 Budibase 资源时应优先使用 packages/server/src/tests/utilities/structures.ts 中预置的工厂函数如basicTable。这些函数内置合理的默认配置需要定制时通过extra属性覆盖扩展const table await config.api.table.save(basicTable(orders, { extra: { ... } }))4.3 API 测试入口TestConfiguration每一个 API 测试用例都应基于 packages/server/src/tests/utilities/TestConfiguration.ts 提供的TestConfiguration类通过new TestConfiguration().api访问封装好的测试 API。全部可用函数与请求/响应类型定义在packages/server/src/tests/utilities/api目录下写测试前先查阅该目录避免重复造轮子。4.4 测试数据源统一描述datasourceDescribe对外部数据库的集成测试通过 index.ts 的datasourceDescribe(opts)统一描述。它支持两种模式{ only: [DatabaseName.POSTGRES, ...] }仅跑指定数据库{ plus: true, exclude?: [...] }跑全部datasource_plus数据库postgres、postgres_legacy、mysql、mssql、mariadb、oracle、sqs可用exclude剔除。函数内部通过testContainerUtils.startContainer启动数据库容器Testcontainers为每个数据库返回dbName、config、dsProvider以及isSql、isPostgres、isMongodb等判定标记方便在用例内按数据库类型分支断言。五、Git 与 Pull Request 协作流程5.1 Git 操作守则CLAUDE.md对 Agent 的 Git 行为约束非常明确核心是每次变更都需要人工许可禁止自动 commit除非显式要求每次提交都要单独征求许可禁止自动 push同样需要每次许可禁止自动 stage/add开发者希望先 review LLM 的改动也不要 unstage已暂存内容例如一次git add, commit, push命令执行后任何后续改动都要再次获得许可。5.2 Pull Request 规范严格遵循根目录 pull_request_template.md 的格式某些 section 如不适用可跳过但不要新增 section打开的 PR 一律先以draft状态提交等待人工 review开 PR 前确保分支已与master同步修 bug 时PR 名称以方括号内的 bug ID 开头例如[BUDI-1234]bug 链接放入模板的 Addresses 部分。5.3 分支同步创建或切换分支时务必先与 GitHub 远程同步不要在过期代码上工作。六、本地开发环境服务端口、启动步骤与健康检查CLAUDE.md的 Cursor Cloud specific instructions 一节给出了最贴近实操的本地开发手册以下表格与步骤均来自该文档并经过仓库脚本核实。6.1 服务端口总览服务端口说明Nginx 代理主入口10000路由到 builder、server、worker、CouchDB、MinIOBuilderVite/Svelte3000前端开发服务器ServerKoa4001应用后端 APIWorker4002后台任务注意.env中WORKER_PORT4002而非 4003CouchDB4005主数据库CouchDB SQS4006CouchDB 的 SQS 兼容层Redis6379缓存、会话、队列MinIO4004S3 兼容对象存储LiteLLM可选4000AI 代理认证 token 见下节6.2 启动开发环境先启动 Dockeryarn dev之前 Docker 必须正在运行。开发栈CouchDB、Redis、MinIO、Nginx可选 LiteLLM由yarn dev通过 packages/server/scripts/dev/manage.js 自动拉起该脚本封装 docker-compose以hosting/docker-compose.dev.yaml为配置核心服务为 minio-service、proxy-service、couchdb-service、redis-serviceLiteLLM 相关为可选服务。执行yarn dev根 package.json 中dev脚本为yarn dev:init yarn run kill-all lerna run --parallel prebuild lerna run --stream dev。即依次执行dev:init运行node scripts/dev/manage.js生成.envkill-all释放 3000 / 4001 / 4002 / 3001 / 4003 端口prebuild各包预构建通过lerna run --stream dev启动 server worker builder。健康检查Workercurl http://localhost:4002/healthWORKER_PORT在.env中设置为 4002Servercurl http://localhost:4001/health。访问完整应用经 Nginx 代理访问http://localhost:10000。6.3 本地默认登录与产品形态本地开发默认登录账号为localbudibase.com密码cheekychuckles。Budibase 产品按应用app划分因此要查找数据源、自动化等内容必须先选中一个 app 再进入相应模块。6.4 LiteLLMAI 代理本地开发时 LiteLLM API 位于localhost:4000认证 token 为budibase。它是可选的 AI 代理服务用于接入模型无关的 LLM 能力对应项目定位 Model agnostic。6.5 运行包级测试cd packages/pkg yarn test filenamepackages/server与packages/backend-core的测试通过scripts/test.sh包装 Jest含 CI/本地差异参数见上文shared-core与string-templates直接以 jest 运行。七、Docker 环境与常见坑Gotchas7.1 云 VM / 嵌套容器中的 Docker在嵌套容器环境中Docker 已安装并配置了fuse-overlayfs存储驱动与iptables-legacy。注意事项Docker daemon 需先用sudo dockerd启动通过chmod 666 /var/run/docker.sock设置 socket 权限后docker命令无需sudo即可使用。7.2 高频踩坑点lerna 是 devDependency 而非全局安装yarn dev之所以能工作是因为 yarn 会解析本地 bin直接运行lerna时应使用npx lerna或yarn lernapostinstall 钩子会执行husky install安装 git hooks其中 pre-push 钩子依赖git-lfs未安装会失败首次运行yarn dev前必须yarn build之后 server/worker 由 nodemon 热重载但对 shared 包types、shared-core、backend-core的改动可能需要重新 build 才能生效。八、给 Agent / LLM 的补充协作约定CLAUDE.md本质上是一份面向 AI Agent 的协作契约除上述技术规范外还包含产品浏览如需在浏览器中操作 Budibase 产品可查阅官方在线文档本地开发服务器地址为http://localhost:10000只读仓库原则仓库为只读参考本指南仅用于查看、运行与配置不应在生成流程中修改仓库内容需求聚焦不要引入向后兼容路径或过度防御逻辑除非任务显式要求——这与以指定文档为骨架、源码为佐证的写作原则一致确保改动最小化、可 review。综上Budibase 的CLAUDE.md是一份密度极高的仓库宪法它以 Lerna monorepo 架构为根基用命令矩阵、代码风格、server 测试基建datasourceDescribe/TestConfiguration/AutomationTestBuilder、Git 许可制 PR 流程以及一套端口明确、可一键启动的本地开发栈把人类开发者 AI Agent的协作方式固化成了可执行规范。无论是为 Budibase 贡献代码、编写集成测试还是搭建本地调试环境本文给出的命令与源码路径均可直接落地验证。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考