最稳妥的安装方式是直接用 docker run 启动，因其不依赖系统环境、不污染本地 Node/Python 版本，且规避了源码构建中常见的 lerna bootstrap 失败、node-gyp 编译报错、yarn install 卡死等问题。
直接用 docker run 启动是最稳妥的安装方式，不依赖系统环境、不污染本地 Node/Python 版本，也避开了源码构建中常见的 lerna bootstrap 失败、node-gyp 编译报错、yarn install 卡死等问题。
为什么别从源码 build Budibase
官方 repo 的 packages/server 和 packages/builder 依赖大量现代前端工具链（SvelteKit + Nx + Turborepo），在多数 Linux 发行版上直接 yarn build 容易失败：
-
yarn install可能因.yarnrc中的nodeLinker: node-modules与系统 Node 版本不兼容而挂起 -
lerna run build会触发多个子包并发构建，内存不足时process out of memory错误频发 -
builder包依赖svelte-preprocess和postcss插件，若系统缺少python3-dev或g++，node-gyp编译直接中断 - 即使构建成功，启动
npm start后端仍需手动配置BUDIBASE_DATABASE_URL等 7 个以上环境变量，且默认不启用 HTTPS 和反向代理支持
用 docker run 部署 Budibase（推荐）
这是生产可用、调试友好、升级简单的方案。注意三点：数据卷路径必须绝对、端口映射要显式、容器名建议固定：
- 运行命令（替换
/your/local/data为真实路径）：docker run -d \ --name budibase-prod \ -p 8080:80 \ -v /your/local/data:/data \ -e BUDIBASE_DISABLE_TELEMETRY=true \ --restart unless-stopped \ budibase/budibase:latest
-
/data是 Budibase 内部硬编码的数据根目录，不能改；挂载点必须是绝对路径，相对路径会导致容器启动后立即退出 - 首次启动耗时约 45 秒（初始化 SQLite 数据库 + 生成密钥），
docker logs -f budibase-prod看到Server running on http://0.0.0.0:80才算就绪 - 如果 80 端口被占，只改宿主机端口（如
-p 8080:80），不要改容器内端口——Budibase 不响应非 80/443 的内部监听
用 docker-compose.yml 管理多服务（比如加 PostgreSQL）
当需要对接外部数据库（而非内置 SQLite），docker-compose.yml 比单条 docker run 更可控。关键点在于网络互通和环境变量透传：
- PostgreSQL 必须与 Budibase 在同一自定义网络，且 Budibase 的
BUDIBASE_DATABASE_URL要用服务名（如postgres）而非localhost - 示例片段（保存为
docker-compose.yml）：version: '3.8' services: postgres: image: postgres:15 environment: POSTGRES_DB: budibase POSTGRES_USER: budibase POSTGRES_PASSWORD: changeme volumes: - ./pgdata:/var/lib/postgresql/data budibase: image: budibase/budibase:latest ports: - "8080:80" environment: BUDIBASE_DATABASE_URL: postgresql://budibase:changeme@postgres:5432/budibase BUDIBASE_DISABLE_TELEMETRY: "true" volumes: - ./budidata:/data depends_on: - postgres - 执行
docker-compose up -d后，先等postgres完全就绪（docker-compose logs postgres | tail -n 10出现database system is ready to accept connections），再检查 Budibase 日志 - 若连接失败，90% 是因为
BUDIBASE_DATABASE_URL写成localhost或端口填错（PostgreSQL 默认 5432，不是 5433）
配置反向代理（Nginx）和 HTTPS
Budibase 容器本身不处理 TLS，必须由前置 Nginx 或 Caddy 终止 HTTPS。重点在于 WebSocket 支持和 Header 透传：
- Nginx 配置中必须包含：
location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } - 漏掉
Upgrade和Connection两行，会导致 Budibase 编辑器实时协作、自动保存等功能静默失效 - 若用 Let's Encrypt，certbot 生成证书后，Nginx 需额外加
ssl_certificate和ssl_certificate_key，Budibase 容器无需任何改动 - 不要在 Budibase 容器里装 Nginx 或尝试用
nginx-proxy自动发现——它无法识别 Budibase 的 WebSocket 路径规则
真正麻烦的从来不是启动 Budibase，而是它启动后第一次访问时，浏览器卡在「Loading app...」超过 2 分钟——这几乎全是网络层问题：反向代理没透传 WebSocket、宿主机防火墙拦了 8080、或者 DNS 解析慢导致前端资源加载超时。先盯住浏览器开发者工具的 Network 面板，看哪些 .js 或 wss:// 请求失败，比反复重装镜像有用得多。
