Budibase 贡献指南理解 Monorepo 架构、搭建本地开发环境并提交首个 PR【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibaseBudibase 是一个开源的 low-code Web 应用构建平台使用 Svelte 构建前端应用并以 Lerna 管理的 monorepo 形式组织全部代码。本文以仓库 docs/CONTRIBUTING.md 为主体完整讲解 Budibase 的贡献全流程从 Bug 反馈、Feature Request、外部 PR 的 Ticket 校验与 Vouch 机制到核心术语表、CLI 贡献规范、开发环境搭建Node 22 Python 3 Docker、yarn dev热重载调试、三种运行模式切换、测试与 CI 管线并结合仓库源码与配置文件给出可验证的细节。读完本文你将具备在本地完整搭建 Budibase 开发环境并提交高质量 PR 的能力。贡献远不止于提交 PRBudibase 的贡献文化强调贡献不只是一次 Pull Request。以下行为同样被认可且有价值反馈 Bug指出一个缺陷非常有价值尤其是附带良好的复现步骤reproduction steps维护者可以直接按步骤验证问题提出功能需求Feature Request帮助产品持续改进。即使最终未被采纳反馈本身仍然有帮助质量提升型quality of life的小需求更容易被接受并落地而大型功能需要产品团队更多输入可能与项目路线不一致落地难度更高。Bug 或功能需求可以通过官方 issue 模板提交仓库中对应模板见 .github/ISSUE_TEMPLATE/bug_report.md、.github/ISSUE_TEMPLATE/feature_request.md。贡献者准入机制Vouching 与外部 PR Ticket 校验VouchingBudibase 使用 Vouch 机制基于 mitchellh/vouch来防止被明确抵制的用户提交 PR在打开或合并 PR 之前你并不需要被 vouch担保来自被明确抵制denounced用户的 PR 会被自动关闭每位贡献者同一时间只能有一个打开的 PR所有 PR 仍然遵循常规的 review 与贡献要求。外部 PR Ticket 校验External PR Ticket Check分支来自仓库外部的 PR必须引用本仓库中一个已存在的 issue且该 issue 必须同时满足处于open打开状态被分配给 PR 作者本人已完成 triage分类且不带有needs-triage、wontfix、out-of-scope、closed-stale任一标签。关联方式在 PR 描述description的Addresses部分写入该 issue 的完整 URL 或#123形式的引用每个 PR 最多检查10 个不同的 issue 引用。合规性由 CI 强制执行。从 .github/workflows/README.md 中可以看到仓库存在专门的external-pr-ticket.yml流水线不符合条件的 PR 会被打上持久标签closed: missing-ticket、附加说明注释并自动关闭在补充有效 issue 之后可以重新打开。仓库内部同仓库分支的 PR 不受此检查约束。Monorepo 架构Lerna 与核心包一览Budibase 是一个由 Lerna 采用independent版本模式、npmClient: yarn、并发数 20并且 publish 时会忽略*.md、*.txt、test/**等变更说明文档与测试文件的改动不会触发版本发布。根 package.json 通过workspaces.packages: [packages/*]聚合所有子包。从源码结构看构成 Budibase 的核心包如下对应文档定义仓库路径均真实存在包路径职责packages/builderBudibase 构建器builder的客户端 Svelte 应用即低代码设计界面本体packages/client运行在浏览器中的模块负责读取应用 JSON 定义并渲染出可交互的 Web 应用packages/serverBudibase 服务器基于 Koa 的应用负责向 builder 与 Budibase 应用提供 JS并提供与数据库、文件系统交互的 APIpackages/worker基于 Koa 的全局 API 服务负责整个 Budibase 安装的管理认证、用户、邮件、组织Org与 Auth 配置均由 worker 提供此外仓库还包含 packages/backend-core后端共享核心数据库、对象存储、Redis、队列、事件等、packages/bbuiSvelte UI 组件库、packages/types共享类型定义、packages/shared-core、packages/string-templates、packages/cli命令行工具等支撑包共同构成完整的编译、发布与运行链路。核心术语表理解 Budibase API 的上层实体要理解 Budibase 的 API 与数据模型先掌握以下顶层实体全部来自原文档均可在仓库类型定义中进一步追溯Tenant租户租户是用户、配置与工作空间workspace的顶层隔离边界。自托管self-hosted开发通常使用默认租户云环境与多租户环境可以包含多个租户。相关实现可参考 packages/backend-core/src/tenancy 与 scripts/dev/multiTenancy.js多租户模式开关脚本。Workspace工作空间构建与发布解决方案的主要组织单元。一个 workspace 涵盖所有数据资源、自动化automations、UI 定义、主题设置、插件与部署元数据。Workspace App工作空间应用每个 workspace 应用管理自己的导航、路由与访问设置。单个 workspace 内可存在多个应用每个应用可独立启用、禁用或设为默认入口。Table表表定义 workspace 中的结构化数据。表可以是内部表由 Budibase CouchDB 存储支撑也可以是外部数据源表。表拥有 schema、行、视图以及主显示字段等元数据。Datasource数据源数据源代表已配置的外部数据来源如 SQL、REST、MongoDB、Google Sheets 等。数据源可以将实体暴露为表也可以包含用于自定义数据操作的查询query。仓库 packages/server/src/integrations 下存放着各数据源集成的实现。Query查询针对数据源的可复用操作。查询定义输入参数、请求细节、转换器transformer与响应 schema可被应用、自动化及其他 workspace 功能使用。View视图表数据的已保存表示。视图可应用过滤、排序、计算与 schema 元数据使数据能够在 builder、API 与应用屏幕中被一致地复用。Screen屏幕workspace 应用内的路由化 UI 界面。屏幕指向某个 layout带有路由与角色元数据并包含该路由的根组件树。Layout布局屏幕共享的 UI 结构通常定义导航、页面框架与共享组件结构。Component组件用于屏幕和布局的基础前端构件。组件保存其类型、设置、样式、子组件与条件行为。Component Library组件库组件库是组件的集合以及包含在components.json文件中的 props 定义。Automation自动化workspace 中的工作流。自动化包含触发器trigger、一个或多个动作步骤action steps、状态、元数据与执行日志。仓库中 packages/server/src/automations 存放自动化引擎实现。Budibase AgentBudibase 智能体在 workspace 中配置的 AI 助手。Agent 定义目标、操作、工具、知识源与聊天集成使用户能够以对话方式与 workspace 数据和流程交互。相关能力沉淀在 packages/pro/src/ai 与 packages/shared-core/src/agentTools.ts 等模块中。Contributor License AgreementCLA为了接受你的 PR必须提交一次 CLA只需做一次首次提交 PR 时直接提交即可CLA Bot 会在合并前给出签署指引所有贡献者必须签署个人 CLA.github/cla/individual-cla.md代表公司贡献时公司必须签署公司 CLA.github/cla/corporate-cla.md并联系communitybudibase.com如果你的首次贡献出现在其他贡献者创建的 PR 中可以在该 PR 下评论以下文本以示同意I have read the CLA Document and I hereby sign the CLA。通用贡献规范进入编码阶段前请遵守以下约定原文档明确要求保持现有代码风格commit 尽量小而聚焦编写测试若分支落后于上游使用 rebase 而非 merge让提交图更易读工作完成后向master分支发起 PR并在描述中说明变更内容与原因。仓库还配备了 husky见根 package.json 的postinstall: husky install以及 ESLint / Prettier 规范可通过yarn lint、yarn lint:fix校验eslint.config.mjs、.prettierrc。从零搭建开发环境1. 前置依赖依赖版本要求说明NodeJS22.x.x根 package.json 的engines明确为22.18.0 23.0.0Python3.x部分构建与脚本依赖Docker / Docker Compose最新后端基础服务Redis、CouchDB、MinIO、NGINX 等通过容器运行Yarn全局安装包管理器npm install -g yarn2. 版本管理器asdf推荐与 nvm/pyenv方式一asdf推荐。asdf 可同时管理多个语言运行时Mac 用户可直接运行仓库脚本scripts/install-contributor-dependencies.sh./scripts/install-contributor-dependencies.sh。从脚本内容看它会安装 Homebrew、asdf并注册 nodejs / python 插件后执行asdf install最后全局安装 yarn手动安装按 asdf 官方指引完成初始化后执行asdf plugin add nodejsasdf plugin add pythonasdf plugin add yarn方式二nvm pyenvNVM安装后执行nvm use读取仓库中的.nvmrcPyenv安装后执行pyenv install -v 3.7.2文档中给出的示例版本Yarnnpm install -g yarn。3. 克隆仓库git clone https://github.com/Budibase/budibase.git cd budibase注意若你有权限访问budibase/pro子模块请在运行下方安装命令前先完成 Pro 部分指引仓库根目录yarn setup会执行git submodule update拉取子模块。4. 安装与构建Windows 提示所有 yarn 命令必须在 bash shell例如 Git Bash中执行。开发 Budibase 平台还需要本机安装 Docker 与 Docker Compose。快速方式yarn setupyarn setup会检查所有必要组件是否就绪并初始化仓库。从根 package.json 可以看到其完整调用链setup: git config submodule.recurse true git submodule update node ./hosting/scripts/setup.js yarn yarn build yarn dev其中 hosting/scripts/setup.js 会检测docker与docker-compose命令是否可用若缺失Mac/Windows 会提示访问官方安装页Linux 会尝试自动执行get-docker.sh与get-docker-compose.sh安装脚本。手动方式假设已安装 Docker / Docker Composeyarn # 安装项目依赖 yarn build # 构建所有 Budibase 包yarn build内部为DISABLE_V8_COMPILE_CACHE1 NODE_OPTIONS--max-old-space-size1500 lerna run build --stream以流式并行方式构建全部包。若需更细粒度构建可使用yarn build:npm、yarn build:apps、yarn build:cli等脚本见根 package.json。5. 运行开发环境热重载以开发模式带实时重载运行 Budibase server 与 builder打开一个新的终端在根目录执行yarn dev浏览器访问http://localhost:10000/builder。yarn dev会先运行dev:init即 scripts/dev/manage.js负责检查并写入开发用.env环境变量随后清理可能占用端口的进程再并行触发 prebuild 与各包 dev 进程。该模式会为 builder 应用、server、client 库以及所有组件库启用 watch 模式。从 scripts/dev/manage.js 可以看到本地开发默认端口与密钥配置builder/代理端口10000、server 端口4001、worker 端口4002、MinIO 端口4004、CouchDB 端口4005、CouchDB SQS 端口4006、Redis 端口6379开发账号为localbudibase.com。6. 使用 VS Code 调试仓库已提供 VS Code launch 配置打开调试窗口选择Budibase Server或Budibase Worker分别调试对应组件选择Start Budibase可同时启动两者其余 Budibase 组件可通过yarn dev:noserver以开发模式运行该命令会拉起 docker 基础服务栈dev:stack:up并忽略 server/worker/backend-core 的运行。7. 环境清理如需删除开发中创建的所有应用并重置环境yarn nuke:docker # 清空所有 Budibase 服务 yarn dev # 重新启动所有服务nuke:docker实际调用lerna run --stream dev:stack:nuke由各包统一清理 Docker 开发栈。后端服务与数据存储在开发后端时Budibase 通过 Docker Compose 运行基础服务。当前仓库的 hosting/docker-compose.dev.yaml 定义了完整服务栈minio-service对象存储端口 9000/9001、proxy-serviceNGINX 反向代理将MAIN_PORT映射到容器 10000、couchdb-serviceBudibase 数据库镜像端口 5984 与 SQS 4984、redis-service会话/缓存端口 6379带--requirepass以及较新的litellm-service与litellm-db模型无关的 AI 网关与 PostgreSQL 元数据库服务于 Agent/AI 功能。后端 Node 服务server、worker则以 nodemon 在 Docker 外单独运行便于脱离容器调试。本地运行时数据通过 Docker volumes 落盘与各服务对应的数据如下注意当前仓库 compose 文件中 CouchDB 卷名为couchdb_data原文档写作couchdb3_data卷存放数据redis_data会话sessions、邮件令牌email tokenscouchdb_data全局数据库与应用数据库minio_data应用 manifest、Budibase client、静态资源开发模式环境变量与三种运行形态Budibase 通过环境变量组合控制运行模式。切换模式后需要清理浏览器 Cookie否则会因旧的认证状态产生异常。根 package.json 提供了对应 yarn 命令其底层由 scripts/dev 下的脚本selfhost.js、multiTenancy.js、account.js、localdomain.js写入/清除环境变量实现Self Hosted自托管默认单租户安装无使用限制。默认开发配置即SELF_HOSTED1、MULTI_TENANCY为空、DISABLE_ACCOUNT_PORTAL1见 scripts/dev/manage.js。启用命令yarn mode:selfCloud云模式开启多租户、关闭账户门户account portal。启用命令yarn mode:cloudCloud Account云 账户门户云模式且开启账户门户是 budibase.app 线上形态的复刻。启用命令yarn mode:account实现为yarn mode:cloud yarn env:account:enable。CI 管线一览CI 管线总览见 .github/workflows/README.md主要包含标准 CI 构建任务budibase_ci.ymlPR 或 push 到 master 时触发。流程为安装依赖 → 构建项目 → 运行单元测试 → 通过 codecov 生成覆盖率 → 运行集成测试 → 校验 pro 与 account portal 子模块指向最新 master外部 PR Ticket 校验external-pr-ticket.yml即上文所述的 Ticket 自动检查发布Releases发布工作流与操作说明由单独的部署仓库维护合并到master后按部署仓库指引执行发布。测试单元测试与集成测试Budibase 使用Jest运行测试各包均有 jest.config.ts根目录还有 globalSetup.ts 与 babel.config.json。在根目录执行yarn testyarn test实际为lerna run --concurrency 1 --stream test即串行并发数为 1依次运行所有包的测试套件避免资源竞争。仓库中每个包都配套了丰富的测试例如 packages/server/src/tests服务端测试、packages/builder/src/testbuilder 组件测试、packages/string-templates/test模板引擎规范测试等。新增功能时请在对应包下补齐单元测试这是合并 PR 的必要条件。故障排查与恢复如果开发环境异常常见原因是 Budibase 平台发生不兼容更新。标准恢复流程按上文Step 7环境清理执行yarn nuke:docker清空开发环境从Step 3安装与构建重新执行yarn setup或手动yarn yarn build获得一份全新的 Budibase 安装。其他有用信息贡献者名单记录在 .github/AUTHORS.md首次贡献后可自行添加Budibase 采用C4Collective Code Construction Contract流程进行贡献不熟悉该流程的贡献者建议先阅读其规范仓库还提供yarn lint/yarn lint:fixESLint Prettiereslint.config.mjs、yarn check:types类型检查与yarn security:audit依赖审计等质量门禁提交 PR 前建议全部通过。小结从反馈一个 Bug 到合并一个 PRBudibase 的贡献链路完整且自动化程度高Vouch 与外部 PR Ticket 校验保证了仓库秩序Lerna Yarn workspaces 的 monorepo 让数千个文件的多包工程可以一键构建Docker Compose 支撑起 Redis / CouchDB / MinIO / NGINX以及 AI 网关 LiteLLM的后端底座而yarn mode:*三套命令则让你在不同部署形态间平滑切换。只要遵循小提交、写测试、rebase、PR 到 master的规范你就能成为 Budibase 生态的贡献者。【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考