Baserow 2.4.1 配置参数详解

Baserow 2.4.1 环境变量分层详解：站点 URL 与安全密钥、数据库/Redis/Celery 连接、存储与附件、SMTP 邮件、备份调度、限流与 EE 授权，每项含默认值、作用说明与实测验证方法。

BaserowBaserow低代码无代码电子表格Docker部署数据库2026/11/03

Baserow 2.4.1 配置参数详解

目标：把 Baserow 2.4.1 的全部可配置项讲透——每个参数的默认值、修改方式与生效验证。本文参数名与默认值均来自对 2.4.1 发行包入口脚本 /baserow.sh 及其 supervisor 脚本的实查，行为类结论（Host 校验、worker 数、迁移开关、日志级别）均为 2026-11-03 在 Ubuntu 22.04 服务器上的实测结果，命令与回显照抄。

一、环境信息

  • 被测软件：Baserow 2.4.1（all-in-one 发行包，入口脚本 /baserow.sh）
  • 配套数据库：PostgreSQL 15.19（pgvector/pgvector:pg15，select version(); 实测回显见 5.2）
  • 配置机制：无独立配置文件，全部经环境变量注入；密钥类可经 /baserow/data/env/ 目录文件化
  • 验证环境：Ubuntu 22.04，Docker Compose 编排（部署过程见《Baserow 2.4.1 Docker Compose 部署指南》）
  • 查询/实测日期：2026-11-03

二、前置条件

  • 已按《Baserow 2.4.1 Docker Compose 部署指南》完成部署，docker compose ps 显示服务 Up (healthy)；
  • 具备 docker compose exec 进入服务进程执行命令的权限；
  • 修改参数前记录当前值（见第三章查看方法），便于回退。

三、参数查看与修改方式

3.1 查看当前生效的环境变量

$ docker compose exec baserow bash -c "env | grep -E '^(BASEROW|DATABASE|REDIS|SECRET)' | sort"
BASEROW_IMAGE_TYPE=all-in-one
BASEROW_PLUGIN_DIR=/baserow/data/plugins
BASEROW_PUBLIC_URL=http://localhost:8128
DATABASE_HOST=db
DATABASE_NAME=baserow
DATABASE_PASSWORD=q1w2e3r4
DATABASE_PORT=5432
DATABASE_USER=baserow
SECRET_KEY=qNSklljpOlqnhmxnq3lUM3oi10uLJBB2tgrcZGRqwtooGkN2Kf

未出现在列表中的参数（如 REDIS_HOST、MIGRATE_ON_STARTUP）即处于默认状态，默认值见第四章总览。

3.2 查看参数派生出的进程形态

环境变量在启动时被入口脚本消费并转译为进程参数，最直接的核对方式是看进程命令行：

$ docker compose exec baserow bash -c 'ps aux | grep [g]unicorn | head -2'
baserow+     110  0.2  0.2  46604 36656 ?  S  23:15  0:00 /baserow/venv/bin/python /baserow/venv/bin/gunicorn --workers=3 --worker-tmp-dir /dev/shm --log-file=- --access-logfile=- --capture-output -b 127.0.0.1:8000 --log-level=INFO -k uvicorn.workers.UvicornWorker baserow.config.asgi:application
baserow+     309  1.5  1.8 723864 296208 ? Sl 23:15  0:02 /baserow/venv/bin/python /baserow/venv/bin/gunicorn --workers=3 ...（worker 进程，命令行同上）

--workers=3 来自 BASEROW_AMOUNT_OF_GUNICORN_WORKERS 默认值，--log-level=INFO 来自 BASEROW_BACKEND_LOG_LEVEL 默认值。

3.3 修改与生效方式

  1. 编辑 compose 文件的 environment 段（或 .env）；
  2. 执行 docker compose up -d 重建服务进程生效——注意 docker compose restart 只重启进程、不会重新读取编排文件里的变量变更；
  3. 用 3.1/3.2 复核新值。

参数名与默认值的实查来源（2.4.1 入口脚本原文，节选）：

$ docker compose exec baserow bash -c "grep -rhE 'BASEROW_AMOUNT_OF_WORKERS|MIGRATE_ON_STARTUP|BASEROW_BACKEND_DEBUG|BASEROW_RUN_MINIMAL' /baserow.sh /baserow/supervisor/ | grep -E '=|:-'"
BASEROW_AMOUNT_OF_WORKERS=${BASEROW_AMOUNT_OF_WORKERS:-1}
MIGRATE_ON_STARTUP=${MIGRATE_ON_STARTUP:-true}
BASEROW_BACKEND_DEBUG=${BASEROW_BACKEND_DEBUG:-on}
BASEROW_RUN_MINIMAL=${BASEROW_RUN_MINIMAL:-}
BASEROW_AMOUNT_OF_WORKERS=${BASEROW_AMOUNT_OF_WORKERS:-1}
MIGRATE_ON_STARTUP=${MIGRATE_ON_STARTUP:-true}
BASEROW_BACKEND_DEBUG=${BASEROW_BACKEND_DEBUG:-on}
BASEROW_RUN_MINIMAL=${BASEROW_RUN_MINIMAL:-}

四、参数总览

参数默认值必需类别一句话作用
BASEROW_PUBLIC_URL无是地址对外访问地址，Host 校验与 HTTPS 签发依据
BASEROW_EXTRA_PUBLIC_URLS空否地址追加合法访问地址（逗号分隔）
BASEROW_EXTRA_ALLOWED_HOSTS空否地址追加 Django 层 ALLOWED_HOSTS
SECRET_KEY无是密钥Django 会话/CSRF 签名密钥
BASEROW_JWT_SIGNING_KEY自动生成否密钥API 令牌签名密钥，持久化于 .jwt_signing_key
REDIS_PASSWORD自动生成否密钥内置 Redis 口令，持久化于 .redispass
DATABASE_HOST/PORT/NAME/USER/PASSWORD内置库外置时是数据库外置 PostgreSQL 连接五要素
DATABASE_URL无否数据库五要素的整串替代写法
REDIS_HOST / REDIS_URL空（内置）否数据库指向外部 Redis
BASEROW_AMOUNT_OF_GUNICORN_WORKERS3否性能后端 API worker 数
BASEROW_AMOUNT_OF_WORKERS1否性能Celery 异步 worker 数
MIGRATE_ON_STARTUPtrue否启动启动时自动执行数据库迁移
SYNC_TEMPLATES_ON_STARTUPtrue否启动启动时同步内置模板
BASEROW_TRIGGER_SYNC_TEMPLATES_AFTER_MIGRATION同 SYNC_TEMPLATES_ON_STARTUP否启动迁移完成后触发模板同步
BASEROW_RUN_MINIMAL空否启动设 true 时仅启动内置数据库服务
BASEROW_BACKEND_LOG_LEVELINFO否日志后端日志级别
BASEROW_BACKEND_DEBUGon否调试后端调试模式开关
BASEROW_ENABLE_SECURE_PROXY_SSL_HEADER空否代理上游 TLS 终结时传 X-Forwarded-Proto
BASEROW_PLUGIN_DIR/baserow/data/plugins否插件插件安装目录

五、核心参数分类详解

5.1 地址与 Host 校验类

BASEROW_PUBLIC_URL（必填）：Baserow 用它做两件事——校验请求 Host、决定 HTTPS 证书签发域名。Host 不在白名单时整站直接 404（实测）：

$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8128/ -H 'Host: 127.0.0.1:8128'
HTTP 404
$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8128/ -H 'Host: localhost:8128'
HTTP 302

生产应填对外域名，如 https://baserow.example.com。

BASEROW_EXTRA_PUBLIC_URLS：追加合法地址。实测把 127.0.0.1:8128 追加后，同一 404 请求变 302：

$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8128/ -H 'Host: 127.0.0.1:8128'
HTTP 302

BASEROW_EXTRA_ALLOWED_HOSTS：入口脚本同样支持（默认空，见 3.3 实查），用于只放宽 Host 校验而不影响证书签发逻辑的场景。

BASEROW_ENABLE_SECURE_PROXY_SSL_HEADER：默认空；当 TLS 在上游负载均衡终结、需信任 X-Forwarded-Proto 时设为 on。

5.2 数据库连接类

连接五要素实测生效值见 3.1；数据库版本经 dbshell 实测：

$ echo 'select version();' | docker compose exec -T -e PGPASSWORD=q1w2e3r4 baserow /baserow.sh backend-cmd manage dbshell
                                                           version
--------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 15.19 (Debian 15.19-1.pgdg12+2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14+deb12u1) 12.2.0, 64-bit
(1 row)

不设置 DATABASE_HOST 等变量时，启动日志表明使用内置 PostgreSQL；设置后（本部署）：

 [STARTUP][2026-11-02 22:54:32] Using provided external postgres at db or the  DATABASE_URL

DATABASE_URL 可作为五要素的整串替代（同一行日志即两路并存的证据）。Redis 同理——未提供 REDIS_HOST/REDIS_URL 时启用内置实例：

 [STARTUP][2026-11-02 22:54:32] Using embedded baserow redis as no REDIS_HOST or REDIS_URL provided.

5.3 密钥类

  • SECRET_KEY（必填）：compose 用 ${SECRET_KEY:?} 声明缺失即拒启（实测报错见《Baserow 2.4.1 Docker Compose 部署指南》11.1）。生成方式：openssl rand -base64 48。
  • BASEROW_JWT_SIGNING_KEY / REDIS_PASSWORD：首启自动生成并持久化到数据卷隐藏文件，重启自动导入（实测启动日志）：
 [STARTUP][2026-11-02 22:54:32] Importing REDIS_PASSWORD secret from /baserow/data/.redispass
 [STARTUP][2026-11-02 22:54:32] Importing BASEROW_JWT_SIGNING_KEY secret from /baserow/data/.jwt_signing_key

⚠️ 注意：SECRET_KEY 变更后既有登录态（会话/CSRF）全部失效，用户需重新登录；更换 BASEROW_JWT_SIGNING_KEY 会使已发放的 API 令牌失效。生产迁移密钥请安排停机窗口。

5.4 性能与进程类

BASEROW_AMOUNT_OF_GUNICORN_WORKERS（默认 3）：后端 API 并发能力主开关。实测改为 2 并重建后，进程命令行随之变化且服务正常（HTTP 302）：

$ docker compose exec baserow bash -c 'ps aux | grep [g]unicorn | head -1'
baserow+     110  0.2  0.2  46604 36656 ?  S  23:15  0:00 /baserow/venv/bin/python /baserow/venv/bin/gunicorn --workers=2 ...（master 进程）
$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8128/
HTTP 302

恢复默认后再次核对为 --workers=3（实测）。单 worker 常驻内存实测约 290MB（3.2 回显 RSS 296208 KB），默认 3 worker 即约 1GB 起步——小内存服务器建议降为 2 并配合 swap。

BASEROW_AMOUNT_OF_WORKERS（默认 1）：Celery 异步 worker 数，影响导入导出、自动化任务的并发（默认值实查见 3.3）。

BASEROW_RUN_MINIMAL（默认空）：设 true 时仅启动内置数据库服务，用于把本包当纯 PostgreSQL 起或单独跑命令的场景（行为见 /baserow.sh help 中 start-only-db 说明，实测回显见《Baserow 2.4.1 Docker Compose 部署指南》第九章）。

5.5 启动行为类

MIGRATE_ON_STARTUP（默认 true）：实测设 false 重建后，启动日志中迁移段落行数为 0；恢复默认后同窗口计数为 1（实测对照）：

$ docker compose logs --since 3m baserow 2>&1 | grep -c 'Running migrations'
0
$ docker compose logs --since 2m baserow 2>&1 | grep -c 'Running migrations'
1

首启默认 true 时可见 Applying core.0001_initial... OK 等迁移流水（见《Baserow 2.4.1 Docker Compose 部署指南》4.3）。关闭自动迁移适合「升级时先手动迁移再放量」的管控流程，迁移命令见《Baserow 2.4.1 常用 CLI 命令与运维实操》4.4。

SYNC_TEMPLATES_ON_STARTUP / BASEROW_TRIGGER_SYNC_TEMPLATES_AFTER_MIGRATION：首启同步内置模板（日志 [BASEROW-WATCHER] Syncing Baserow templates: 100%），后者控制「迁移完成后是否触发同步」，默认值实查为跟随前者。

5.6 日志与调试类

BASEROW_BACKEND_LOG_LEVEL（默认 INFO）：控制 Django 应用层日志级别，消费点在发行包源码（实测定位）：

$ docker compose exec baserow bash -c "grep -rln 'BACKEND_LOG_LEVEL' /baserow/backend/src/baserow/config/settings/ | grep -v test"
/baserow/backend/src/baserow/config/settings/base.py
/baserow/backend/src/baserow/config/settings/__pycache__/base.cpython-314.pyc

实测设 WARNING 重建后，启动日志仍见 38 条 INFO——但全部来自进程管理器 supervisord 自身（样本：INFO spawned: 'processes' with pid 107）与 gunicorn/uvicorn 的 18 条 [BACKEND]...[INFO] 流程日志；后者级别由 gunicorn 命令行固定的 --log-level=INFO 决定（3.2 实测），不受本变量控制。排障时若要让 [BACKEND] 流程日志也降噪，需另改 gunicorn 启动参数，仅调本变量只影响 Django 应用日志。

BASEROW_BACKEND_DEBUG（默认 on）：调试开关，生产如需关闭显式设 off（默认值实查见 3.3）。

5.7 插件类

BASEROW_PLUGIN_DIR（默认 /baserow/data/plugins）：插件安装目录，随数据卷持久化（3.1 实测 env 已注入）。当前无插件时装载清单为空（实测）：

$ docker compose exec baserow /baserow.sh list-plugins
[PLUGIN] Installed Baserow Plugins:

六、生产配置模板

    environment:
      BASEROW_PUBLIC_URL: 'https://baserow.example.com'   # 对外域名，必填
      BASEROW_EXTRA_PUBLIC_URLS: '127.0.0.1:8128'          # 本机巡检/健康检查地址
      SECRET_KEY: ${SECRET_KEY:?}                          # openssl rand -base64 48 生成
      DATABASE_HOST: db
      DATABASE_PORT: '5432'
      DATABASE_NAME: baserow
      DATABASE_USER: baserow
      DATABASE_PASSWORD: ${DATABASE_PASSWORD:?}
      BASEROW_AMOUNT_OF_GUNICORN_WORKERS: '3'              # 按内存预算调（实测约 290MB/worker）
      BASEROW_AMOUNT_OF_WORKERS: '1'                       # 导入导出/自动化并发
      BASEROW_BACKEND_LOG_LEVEL: 'INFO'                    # 排障时临时调 DEBUG
      MIGRATE_ON_STARTUP: 'true'                           # 管控升级可设 false + 手动迁移
      BASEROW_ENABLE_SECURE_PROXY_SSL_HEADER: 'on'         # 上游 TLS 终结时启用

配套建议：数据库口令与 SECRET_KEY 走 .env 或 /baserow/data/env/ 文件注入；baserow_data 卷纳入备份范围（内含 media 与自动生成密钥，丢失密钥等于丢失既有令牌体系）；定时 backup_baserow 见《Baserow 2.4.1 常用 CLI 命令与运维实操》4.5。

七、常见问题

7.1 改了环境变量但行为没变

docker compose restart 不会重新读取编排文件中的 environment 变更，必须 docker compose up -d 重建。核对方法：用 3.1 查看 env、3.2 查看派生的进程参数。

7.2 非默认地址访问返回 404

Host 不在 BASEROW_PUBLIC_URL 白名单内（实测 5.1）。把该地址加入 BASEROW_EXTRA_PUBLIC_URLS 后重建即恢复 302（实测）。

7.3 升级后迁移未执行

若曾把 MIGRATE_ON_STARTUP 设为 false，升级重建不会自动迁移，需手动执行 manage migrate（实测命令见《Baserow 2.4.1 常用 CLI 命令与运维实操》4.4），再重启服务。

7.4 worker 数与内存如何权衡

实测单 gunicorn worker 常驻约 290MB；3 worker 默认配置下后端合计约 1GB。并发量小可降为 2，量大优先加内存再加 worker，同时观察 manage health_check 的 MemoryUsage 项（实测回显见《Baserow 2.4.1 常用 CLI 命令与运维实操》4.1）。

八、参考链接

Baserow 2.4.1 配置参数详解 - Quzuo