企业官网建设流程全解析

Baserow just 命令体系：用三层 Justfile 构建本地开发环境与测试流水线

【免费下载链接】baserowBuild databases, automations, apps & agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow

Baserow（一个可自托管的开源数据库/自动化/应用构建平台）选择 just 为骨架，逐节展开每类命令的用法，并结合仓库中 根 justfile、backend/justfile、web-frontend/justfile 的真实实现，说明每条命令背后实际做了什么，帮助你在本地快速拉起完整的 Baserow 开发环境（PostgreSQL + Redis + 后端 + Celery + 前端 + Storybook）并高效地跑测试。

三层 Justfile 的分工

Baserow 的命令被组织在三个 justfile 中（文档见 docs/development/justfile.md）：

根 justfile 通过alias与--justfile参数把后两者「挂」进来，因此绝大多数时候你只需要在仓库根目录敲命令：

# 在根目录执行（justfile 第 476-489 行） backend *args: @just --justfile backend/justfile --working-directory backend {{ args }} alias b := backend frontend *args: @just --justfile web-frontend/justfile --working-directory web-frontend {{ args }} alias f := frontend

也就是说just b test等价于进入backend/后执行just test，just f lint等价于进入web-frontend/后执行just lint。根 justfile 开头还启用了set unstable := true并import? 'local.just'（justfile#L4-L7）：前者解锁[group]/[doc]/[private]等注解以让just --list按分类展示，后者为个人 recipe 留了口子（见「个人 Recipe」一节）。

安装 just 与 uv

参考 docs/development/justfile.md 的官方安装方式：

# macOS brew install just uv # Linux curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin curl -LsSf https://astral.sh/uv/install.sh | sh

其中uv是后端 justfile 的前提——backend/justfile 中所有 Python 命令都以uv run --active为前缀（uv_run := "uv run --active"），venv 位置由UV_PROJECT_ENVIRONMENT控制，本地开发时默认落在仓库根目录的../.venv（相对于backend/）。

命令发现：先 --list，再 help

三个 justfile 都把just --list设为默认 recipe（不传参数直接敲just即可看到全部分组列表）。常用发现方式：

# 列出所有命令（按 [group(...)] 分类，按 [doc(...)] 显示说明） just --list # 查看快速入门指南（打印两种开发路线：本地进程 vs Docker） just help # 列出后端 / 前端命令 just b --list # 或 cd backend && just --list just f --list

just help的输出（justfile#L27-L58）直接给出了两条官方推荐路线：

• 路线 1：本地进程——需要本地 Python/Node，热重载更快：just init→just b code-runtime→just dev up；
• 路线 2：Docker 容器——一切容器化，环境搭建最简单：just dc-dev build --parallel→just dc-dev up -d。

首次环境初始化

just init # 安装后端 + 前端依赖，创建 .env.local just b code-runtime # 单独重建本地 Wasmtime + QuickJS 运行时产物 just pre-commit-install # 安装 Git pre-commit 钩子

从源码看，just init（justfile#L67-L69）依次执行just b init和just f install。其中b init（backend/justfile#L115-L128）依赖链为：

1. _setup-env：若根目录没有.env.local，从 .env.local-dev.example 复制一份并提示你去审阅修改；
2. _create-venv：用uv venv --python 3.14创建虚拟环境（python_version := "3.14"）；
3. code-runtime：执行docker build -f backend/Dockerfile --target code-runner-artifacts --output type=local,dest=.local/code-runtime，把 Wasmtime 二进制与 QuickJS wasm 产物导出到.local/code-runtime/（backend/justfile#L158-L181），并打印需要写入 env 文件的两个变量：

BASEROW_ENTERPRISE_CODE_RUNNER_WASMTIME_EXECUTABLE=.local/code-runtime/bin/wasmtime BASEROW_ENTERPRISE_CODE_RUNNER_QUICKJS_WASM_PATH=.local/code-runtime/lib/baserow/qjs.wasm

这正是 .env.local-dev.example 末尾注释掉的 code runner 配置段，开启本地代码执行字段时需要取消注释。 4. 最后uv lock && uv sync锁定并安装全部依赖（workspace 会一并包含premium/backend与enterprise/backend两个包）。

just f install则是简单的yarn install（web-frontend/justfile#L71-L72）。

值得注意的细节：backend 与 frontend 的 justfile 开头都有一句注释——「所有 recipe 必须在 Docker 内和本地开发中以同样方式工作，不得加入 docker 特有假设」，这也是b/f命令可以直接在容器里复用的原因。

本地进程开发：just dev

这是文档中「Local Development」一节的完整命令面：

just dev up # 启动全部（db、redis、backend、celery、frontend），并跟随日志 just dev up -d # 后台（detached）启动 just dev stop # 停止全部服务 just dev logs # 查看日志 just dev ps # 查看运行中的进程 + 容器（db、redis）

dev实际上是一个带 shell 脚本体的变参 recipe（dev *ARGS，justfile#L86-L234），子命令比文档列出的还多：up/up -d/stop/logs/ps之外，还支持wipe（删库后重启）和tmux（tmux 多窗格会话）。

_dev-start到底做了什么

just dev up内部调用私有 recipe_dev-start（justfile#L238-L357），完整启动序列为：

1. 若无.env.local则从.env.local-dev.example复制；随后set -a; source .env.local; set +a加载环境变量；
2. 用dc-dev up -d只拉起基础设施服务，并把应用服务 scale 为 0：--scale backend=0 --scale web-frontend=0 --scale celery=0 --scale celery-beat-worker=0 --scale celery-export-worker=0 --scale storybook=0，实际启动的是 db、redis、mailhog、otel-collector；
3. 用dc-dev exec -T db pg_isready -U baserow与redis-cli ping各做最多 30 秒的就绪探测；
4. 在backend/执行just migrate完成数据库迁移；
5. 以后台进程方式依次启动四个本地服务：backend（just run-dev-server）、celery 三件套（just run-dev-celery）、frontend（just run-dev-server）、Storybook（just storybook），并把 PID 写入${BASEROW_LOCAL_DEV_PREFIX}-<name>.pid、日志写入同名.log文件；
6. 打印服务地址与下一步命令。

日志与 PID 文件的位置由BASEROW_LOCAL_DEV_PREFIX控制，默认/tmp/baserow（justfile#L10-L16）。所以：

• just dev logs [-f] [backend|celery|frontend|storybook]会对这些文件执行tail，并用 sed 给 ERROR/WARNING/INFO/DEBUG 着色；不加服务名时默认看全部四个服务；
• just dev ps逐个检查 PID 文件是否存活，再调用dc-dev ps redis db mailhog otel-collector展示容器侧状态；
• 前台模式下dev up注册了trap ... INT，按 Ctrl+C 会先执行_dev-stop再退出——这正是文档所说「Ctrl+C stops everything」的实现；
• just dev wipe up会先dc-dev wipe（即docker compose down -v，删除数据卷）再按剩余参数继续，用于彻底重置开发数据。

后端开发服务器本身在 backend/justfile#L552-L563：baserow runserver（默认绑定BASEROW_RUNSERVER_BIND，缺省0.0.0.0:8000）；celery 三件套（worker 消费celery,automation_workflow队列、export worker 消费export队列、beat 使用 redbeat 调度器）带彩色前缀合并输出到单个日志文件，见 backend/justfile#L611-L666。默认 Nuxt 端口 3000、Storybook 端口 6006、MailHog Web UI 8025，均可在.env.local中覆盖——.env.local-dev.example 甚至内置了「实例 A / 实例 B」两套完整端口块（8010/3010、8020/3020），用于同一台机器同时跑多个原生开发实例。

Docker 开发：just dc-dev

文档「Docker Development」一节的命令：

just dc-dev up -d # 启动开发容器 just dcd logs -f # 跟随日志（dcd 是 dc-dev 的别名） just dcd exec backend bash # 进入容器 shell just dcd down # 停止并移除容器 just dcd ps # 查看运行中的容器

dcd就是 justfile#L610 的alias dcd := dc-dev。dc-dev是一个包装器（justfile#L553-L608），在透传参数给 docker compose 之前做了四件贴心事：

1. 首次运行自动cp .env.docker-dev.example .env.docker-dev；
2. 导出宿主机UID/GID，供 docker-compose.dev.yml 中user: "${UID}:${GID}"与 build args 使用，避免容器改坏 bind mount 目录的文件属主；
3. 确保web-frontend/node_modules目录存在（Docker bind mount 要求被挂载路径存在），必要时mkdir -p；
4. 实际执行docker compose --env-file .env.docker-dev -f docker-compose.yml -f docker-compose.dev.yml <ARGS>，特殊子命令wipe（down -v后透传剩余参数）、tmux、tabs被单独拦截处理。

开发镜像的服务清单可在 docker-compose.dev.yml 中核对：db（pgvector/pg14）、redis、caddy（dev 模式只做 media 文件服务器）、backend（baserow_backend:dev，挂载backend/、premium/backend/、enterprise/backend/源码目录并暴露 5678 调试端口）、web-frontend（nuxt-dev，端口 3000）、storybook（optionalprofile，端口 6006）、celery / celery-export-worker / celery-beat-worker（均用watch-py热重载）、celery-flower（optionalprofile）、mjml-email-compiler、mailhog（1025/8025）、otel-collector 等。optionalprofile 服务默认通过.env.docker-dev中的COMPOSE_PROFILES启用，置空即可关闭（见 justfile#L539-L541 的帮助文本）。

同组还有几个排障/辅助命令：

just dc-attach [filter] # 交互选择正在运行的容器并 exec bash 进入（别名：just a） just dc-cache-clear # docker builder prune -a -f，清除全部 BuildKit 缓存（别名：just prune） just dc-fix-network # 清理引用了失效网络的 Baserow 容器，修复 "network not found"

生产镜像与部署编排命令

dc-prod（别名dcp，justfile#L871-L890）用于在本地验证生产镜像：未设置BASEROW_VERSION时走docker-compose.build.yml本地构建，设置具体版本（如BASEROW_VERSION=1.29.0）时直接从镜像仓库拉取：

just dc-prod up -d # 本地构建并运行 latest BASEROW_VERSION=1.29.0 just dc-prod up -d # 拉取并运行指定版本

just build <target> [tag] [--multi]则统一了各部署目标的镜像构建（justfile#L892-L1032），支持的目标：backend、web-frontend、all-in-one、all-in-one-lite（不带 postgres/redis 的轻量单容器）、heroku、cloudron、render、apache、apache-no-caddy。--multi会创建/复用baserow-multiarchbuildx builder 并同时构建linux/amd64,linux/arm64（需要配合--push或--output）。

just dc-deploy <name> <cmd>把各部署方案的 compose 文件包装成统一入口（justfile#L1034-L1083），可选all-in-one、cloudron、heroku、traefik、nginx、apache、local-testing，例如just dc-deploy all-in-one up -d。

后端与前端的日常命令

文档「Running Commands」一节给出的命令及源码对应关系：

# 后端（根目录执行） just b test # 运行后端测试 just b lint # 后端 lint just b shell # Django shell just b migrate # 执行迁移 just b manage <cmd> # 任意 manage.py 命令 # 前端（根目录执行） just f test # 运行前端测试 just f lint # 前端 lint

• just b test最终执行uv run --active pytest -c pytest.ini，PYTHONPATH由 _pytest 变量 拼上tests:../premium/backend/tests:../enterprise/backend/tests，保证三个测试目录的 fixture 互相可见；支持透传-n=auto等 pytest 参数。
• just b lint/just f lint都是check的别名，且都支持按文件 lint：传入仓库根相对路径（如backend/src/foo.py），backend 侧只用 ruff 检查这些文件，frontend 侧按扩展名拆分到 eslint / stylelint / prettier（web-frontend/justfile#L92-L131），路径不在这几棵源码树内的会被静默跳过。
• just b manage、migrate、shell_plus等最终都走uv run baserow <args>（baserow是src/baserow/manage.py的 console 入口），常用别名有m（manage）、mg（migrate）、sp（shell_plus）、t（test）、dev/serve（run-dev-server），见 backend/justfile#L676-L716。
• Django settings 模块默认为baserow.config.settings.dev（可用DJANGO_SETTINGS_MODULE覆盖），.env.local-dev.example 中默认值一致，测试时可临时切换为baserow.config.settings.test。

另一个容易忽略的健壮性设计：backend 的 recipe 都依赖_check-dev（backend/justfile#L762-L768），它检测 venv 的bin/python与uv.lock是否存在，缺失时自动执行just init——因此 clone 仓库后不显式初始化也能直接just b test。

代码质量三连

just lint # 全量 lint（backend + frontend） just fix # 自动修复风格问题 just test # 运行全部测试

三者都在 justfile#L491-L510 中实现，就是依次委托b与f的同名 recipe。backend 侧使用 ruff（ruff check+ruff format --check，fix加--fix），frontend 侧使用yarn run lint/yarn run fix（eslint + stylelint + prettier 的组合）。

更快的测试：Ramdisk 数据库

文档「Testing with Ramdisk Database」给出的流程：

just test-db up # 启动 ramdisk 数据库 DATABASE_URL=postgres://baserow:baserow@localhost:<port>/baserow just b test -n=auto just test-db down # 停止 ramdisk 数据库 just test-db ps # 查看状态

源码实现（justfile#L1089-L1172）值得细看：test-db up会先删除旧容器再docker run一个新的pgvector/pgvector:pg14实例，容器名固定为baserow-test-db，关键点有二：

• tmpfs 内存盘：--tmpfs /var/lib/postgresql/data:size=8G，数据全部落在内存；
• 激进的写路径调优：fsync=off、synchronous_commit=off、full_page_writes=off、autovacuum=off、wal_level=minimal、max_wal_senders=0、关闭全部日志收集，外加shared_buffers=512MB、work_mem=256MB等。

注意：参考文档示例中标注的是 5433 端口，而当前 justfile 的默认端口为5431（test_db_port := env("TEST_DB_PORT", "5431")，可用环境变量TEST_DB_PORT覆盖）。以just test-db ps打印的实际端口为准来拼接DATABASE_URL即可。

just b test -n=auto中的-n=auto是 pytest-xdist 的自动并行参数，配合内存库可显著压缩后端全量测试时长。CI 侧的对应物是ci-test（backend/justfile#L394-L426），它按--splits/--group切分测试集并输出 JUnit 与 coverage 报告。

环境文件体系

文档中的环境文件表：

结合源码可以补充两点自动化逻辑与两个配套工具：

• 自动创建：_dev-start和b init的_setup-env都会检查并复制.env.local-dev.example→.env.local；dc-dev首次运行时复制.env.docker-dev.example→.env.docker-dev。三个 example 文件（.env.local-dev.example、.env.docker-dev.example、.env.example）都在仓库根目录，可直接阅读了解全部可配置项。
• 手动加载/卸载（根 justfile 的5 - utilities组）：

eval "$(just env-load)" # 在当前 shell 中 source .env.local eval "$(just env-clear)" # 打印 unset 语句，清除 .env.local 注入的变量

.env.local-dev.example 覆盖的典型配置块包括：Django settings 模块、SECRET_KEY、数据库连接（DATABASE_HOST/DATABASE_URL二选一，以及加速测试用的POSTGRES_DEV_EXTRA_ARGS单行调优参数）、Redis、公网/内网 URL（PUBLIC_BACKEND_URL、PUBLIC_WEB_FRONTEND_URL、PRIVATE_BACKEND_URL）、各服务端口、MailHog 邮箱拦截（EMAIL_HOST=localhost、EMAIL_PORT=1025，Web UI 在 8025）、以及 code runner 相关变量。

个人 Recipe：local.just

文档「Personal Recipes」一节：

cp local.just.example local.just

你的 recipe 会与标准 recipe 一起出现在just --list中。实现上是根 justfile 第 7 行的import? 'local.just'——?表示文件不存在时静默跳过，且local.just已被 gitignore，不会污染提交。仓库提供的模板 local.just.example 给出了五个典型示例，可以直接改造：

# 针对特定模块的快速测试 my-test: just b test tests/baserow/core/ # 只启动所需服务（基础设施容器 + 后端，不起前端） my-dev: #!/usr/bin/env bash just dc-dev up -d redis db mailhog just b run-dev-server # 自定义数据库重置 my-db-reset: just dc-dev exec db psql -U baserow -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;" just b migrate # 带 SQL 日志打印的 shell my-shell: just b manage shell_plus --print-sql

模板注释还说明：backend/与web-frontend/下也可以各自再放一个local.just，用于组件级别的个人 recipe（两个子 justfile 同样有import? 'local.just'）。

延伸：E2E 测试与 CI 命令

虽然文档主体是日常开发命令，但根 justfile 还内置了两个与 justfile.md 相邻主题的入口，值得一提：

• just e2e <build|up|down|test|logs|run|db-dump>委托给 e2e-tests/justfile：构建 CI 镜像、用预生成的数据库 dump（e2e-tests/fixtures/e2e-db.dump）快速拉起一整套 E2E 环境（独立端口 8070/3070，避免与开发栈冲突）、运行 Playwright 测试、生成/恢复数据库 dump；
• just ci <build|lint|test|run> [backend|frontend]在本地模拟 CI 流水线：构建baserow_backend:ci/baserow_frontend:ci镜像（justfile#L1240-L1379），为后端测试临时创建 Docker 网络并拉起 PostgreSQL + Redis，再进入容器执行 lint 或ci-test；run子命令则串行执行 lint + test 全流程。

小结与延伸阅读

回到 docs/development/justfile.md 的脉络：Baserow 的开发工作流可以浓缩为「just init一次 → 本地进程用just dev up、全容器用just dc-dev up -d→ 日常操作走just b …/just f …与just lint|fix|test→ 追求测试速度用just test-db」。每层的 recipe 都遵循「同一命令在容器内外行为一致」的约束，并保留local.just个人扩展点。

继续深入可阅读仓库中的配套文档（均为相对仓库根目录的路径）：

• Docker 方式运行开发环境
• 本地方式运行开发环境
• 运行测试
• E2E 测试
• 代码质量（lint 与格式化）
• 调试技巧

【免费下载链接】baserowBuild databases, automations, apps & agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow