Baserow 2.4.1 常用 CLI 命令与运维实操

Baserow 2.4.1 管理面实操手册：/baserow.sh 命令树与 manage 子命令（health_check/dbshell/createsuperuser/migrate/backup_baserow/restore_baserow/插件）及 REST API 分页排序过滤，含备份还原闭环演练与真实回显。

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

Baserow 2.4.1 常用 CLI 命令与运维实操

一、环境信息

本文所有命令与输出均为真实环境实测回显，逐行照抄。

项目值
操作系统Ubuntu 22.04.4 LTS (x86_64)
软件版本Baserow 2.4.1（镜像 baserow/baserow:2.4.1，入口脚本 /baserow.sh）
PostgreSQLpgvector/pgvector:pg15（实测服务端 PostgreSQL 15.19 on x86_64-pc-linux-gnu）
部署形态Docker Compose（编排文件见《Baserow 2.4.1 Docker Compose 部署指南》），本文命令均在该部署形态下执行
访问地址http://<服务器IP>:8128（实测本机 localhost:8128）
命令入口docker compose exec [-T] baserow /baserow.sh <子命令> ...（exec 默认进 root；backend-cmd 内部降权到 baserow_docker_user 执行）
备份目录卷 baserow_data:/baserow/data/backups
凭据数据库用户 baserow；CLI 备份/还原需 -h/-d/-U 显式参数 + libpq 口令（PGPASSWORD 环境变量或 .pgpass）

二、工具概览

Baserow 无独立二进制 CLI，管理面分三层：

  1. /baserow.sh 入口脚本（镜像内置）：start / start-only-db / backend-cmd / backend-cmd-with-db / frontend-cmd / celery-worker-cmd / celery-beat-cmd / logs / restart / ps / install-plugin / uninstall-plugin / list-plugins，子命令全集见《Baserow 2.4.1 Docker Compose 部署指南》第九章；
  2. Django manage 子命令：/baserow.sh backend-cmd manage <命令>，承载账号、迁移、健康检查、备份还原、插件等全部运维动作；
  3. REST API（/api/ 前缀）：JWT 鉴权后的数据面与部分管理面操作，适合脚本化批量运维（见本章 4.8）。

manage help 实测列出的 Baserow 自有命令共 38 个，运维常用子集：

manage 子命令用途本文位置
health_check组件健康检查（DB/Redis/存储）4.1
dbshell进入 PostgreSQL 交互终端4.2
createsuperuser创建管理员账号4.3
migrate应用待执行数据库迁移4.4
backup_baserow整库备份为 tar.gz4.5
restore_baserow从备份 tar.gz 还原4.6
list-plugins / install-plugin / uninstall-pluginEE 插件管理4.7
sync_templates同步官方模板库4.7
audit_retention_period_clean / cleanup_..._jobs / delete_expired_...EE 审计与任务清理4.7（列出）

三、前置条件

  • 已完成《Baserow 2.4.1 Docker Compose 部署指南》部署，docker compose ps 两服务 healthy；
  • 交互式命令直接 docker compose exec baserow ...；需要管道/重定向（如 manage shell < 脚本）加 -T 禁用伪终端；
  • backup_baserow / restore_baserow 底层调用 pg_dump / pg_restore，不接受口令参数，帮助原文要求 "You must also have a valid .pgpass file in the home directory of the user running this command or set the PGPASSFILE environment variable"——实测在 exec 命令上注入 -e PGPASSWORD=<密码> 等效可用；
  • 备份/还原命令的工作目录必须对运行用户（baserow_docker_user，uid=1001）可写：docker compose exec 默认 cwd 为 /（root 所有），直接跑会 PermissionError: [Errno 13] Permission denied: 'baserow_backup_...'（实测），需加 -w /baserow/data/backups。

四、各工具详解

4.1 health_check：组件健康检查

命令格式：

docker compose exec -T baserow /baserow.sh backend-cmd manage health_check

实测输出：

$ docker compose exec -T baserow /baserow.sh backend-cmd manage health_check
MemoryUsage: 8.16% (12.43 GiB available)
DatabaseConnection: OK
DatabaseQuery: OK, took 0 ms
Redis: OK
Cache: OK
Storage: OK
Migrations: OK
Celery: OK
DeployedApps: 1
ErrorLogMonitor: OK, 0 errors seen in last 5 minutes, 0 errors seen in past 24 hours
TaskScheduler: OK

关键输出解读：

检查项含义异常时
DatabaseConnection / DatabaseQuery后端到 PostgreSQL 连通与查询能力ERROR: connection to ... failed 查 DATABASE_* 变量与 db 服务状态
Redis / CacheRedis 与 Django 缓存层查 REDIS_URL 与 redis 服务
Migrations是否存在未应用迁移报 UNAPPLIED 时执行 manage migrate（4.4）
Storage媒体文件存储可写性查 MEDIA_ROOT 卷挂载与属主
ErrorLogMonitor近 5 分钟/24 小时错误计数非 0 时 docker compose logs 定位
DeployedApps当前部署应用数与预期服务拓扑核对

外部探针 GET /api/_health/ 返回纯文本 OK（实测），适合挂监控与 compose healthcheck。

4.2 dbshell：数据库交互终端

命令格式：

docker compose exec baserow /baserow.sh backend-cmd manage dbshell -c "SELECT version();"

实测输出：

$ docker compose exec baserow /baserow.sh backend-cmd manage dbshell -c "SELECT version();"
PostgreSQL 15.19 on x86_64-pc-linux-gnu, compiled by gcc (Debian 15.2.0) 15.2.0, 64-bit
(1 row)

不带 -c 则进入交互式 psql。数据行级核查（如备份还原后验证）也可直接走 db 服务：

docker compose exec db psql -U baserow -d baserow -tAc "select count(*) from database_table_1;"

4.3 createsuperuser：管理员账号与 UserProfile 坑

命令格式：

docker compose exec -T -e DJANGO_SUPERUSER_PASSWORD='<密码>' \
  baserow /baserow.sh backend-cmd manage createsuperuser \
  --username admin@example.com --email admin@example.com --noinput

实测输出：

$ docker compose exec -T -e DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 baserow /baserow.sh backend-cmd manage createsuperuser --username admin@example.com --email admin@example.com --noinput
Superuser created successfully.

关键坑（实测复现）：若 --username 与 --email 不一致（如 username=admin），Web 登录正常但 API 登录 500——createsuperuser 不创建 UserProfile 行，而 token-auth 序列化器访问 user.profile 抛 RelatedObjectDoesNotExist。实测后端日志：

django.core.exceptions.RelatedObjectDoesNotExist: User has no profile.

补建 UserProfile 后恢复。写成脚本经 manage shell 执行（-T 走 stdin）：

cat > /tmp/prof.py <<'EOF'
from django.contrib.auth import get_user_model
from baserow.core.models import UserProfile
U = get_user_model()
u = U.objects.get(email="admin@example.com")
up, created = UserProfile.objects.get_or_create(user=u)
print("PROFILE created={} id={}".format(created, up.id))
EOF
docker compose cp /tmp/prof.py baserow:/tmp/prof.py
docker compose exec -T baserow /baserow.sh backend-cmd manage shell < /tmp/prof.py

实测输出：

PROFILE created=True id=1

补建后 API 登录成功（完整响应，token 截断）：

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzk2MzQ4MjU2LCJpYXQiOjE3OTM2NzAxNTUsImp0aSI6IjQ1YjU2Y2MxZTg3YzRkYzRhMDhmZDkxNGI4Y2QwNTU2IiwidXNlcl9pZCI6MX0....",
    "token_type": "Bearer",
    "user": {
        "id": 1,
        "username": "admin@example.com",
        "first_name": "",
        "last_name": "",
        "email": "admin@example.com",
        "is_staff": true,
        "is_active": true,
        "profile": {
            "user": 1,
            "contact_info": { "phone_number": "" },
            "color": null,
            "page_size": 100,
            ...
        }
    }
}

（page_size 默认 100——与《Baserow 2.4.1 配置参数详解》7.3 的 API 分页默认值互相印证。）

4.4 migrate：数据库迁移

升级镜像版本后、或 health_check 报 Migrations: UNAPPLIED 时执行：

命令格式：

docker compose exec -T baserow /baserow.sh backend-cmd manage migrate

实测输出（版本对齐时）：

$ docker compose exec -T baserow /baserow.sh backend-cmd manage migrate
Apply all migrations: auth, authtoken, baserow, baserow_agent, baserow_audit_log, baserow_calendar, baserow_canary, baserow_canvas_page, baserow_collab, baserow_core, baserow_enterprise, baserow_form, baserow_gallery, baserow_integrations, baserow_invitations, baserow_map, baserow_migrations_report, baserow_premium_banners, baserow_reports, baserow_row_batch_editing, baserow_synced_table, ...
Running migrations:
  No migrations to apply.

注意 MIGRATE_ON_STARTUP=true（默认）时应用启动已自动迁移，手动执行主要用于排障确认与 false 场景下的升级流程（见《Baserow 2.4.1 配置参数详解》5.5 升级顺序）。

4.5 backup_baserow：整库备份

参数签名（manage backup_baserow --help 实测）：

backup_baserow [-h] -f FILE -h HOST -d DATABASE -U USERNAME [-p PORT] [-j JOBS] [--batch-size BATCH_SIZE]

文件、主机、库、用户全部是命名参数——把备份路径当位置参数传会报 pg_dump: option requires an argument -- 'f' + too many command-line arguments（实测），漏传 -h/-d/-U 报 the following arguments are required: -h/--host, -d/--database, -U/--username（实测）。

命令格式（实测可用形态）：

docker compose exec -T -e PGPASSWORD='<数据库密码>' -w /baserow/data/backups \
  baserow /baserow.sh backend-cmd manage backup_baserow \
  -f /baserow/data/backups/backup-$(date +%Y%m%d).tar.gz -h db -d baserow -U baserow

实测输出（关键行）：

$ docker compose exec -T -e PGPASSWORD=q1w2e3r4 -w /baserow/data/backups baserow /baserow.sh backend-cmd manage backup_baserow -f /baserow/data/backups/backup-d1test.tar.gz -h db -d baserow -U baserow
[BACKEND] ... INFO Created backup file /baserow/data/backups/backup-d1test.tar.gz
[BACKEND] ... INFO Successfully backed up Baserow to /baserow/data/backups/backup-d1test.tar.gz which can be restored using the ./baserow restore_baserow command.

过程日志可见备份机制：先备份用户表以外的全部表，再按批次导出用户数据表（实测 pg_dump ... --exclude-table=... 列表 + user_tables_batch_0），最终打包为单个 tar.gz（实测产物 177K）：

$ docker compose exec -T baserow ls -lh /baserow/data/backups/
total 180K
-rw-r--r-- 1 baserow_docker_user baserow_docker_user 177K Nov  3 02:08 backup-d1test.tar.gz

备份产物结构：tar.gz 内含 dumpfile.backup（pg_dump 自定义格式）与 backup.properties（版本与校验信息），跨版本还原前先核对 properties 中的版本号。

异机留存：备份文件在命名卷内，建议拷贝到宿主或对象存储：

docker compose cp baserow:/baserow/data/backups/backup-d1test.tar.gz ./backup_d1test.tar.gz

实测输出：

$ docker compose cp baserow:/baserow/data/backups/backup-d1test.tar.gz /opt/baserow/backup_d1test.tar.gz
$ ls -lh /opt/baserow/backup_d1test.tar.gz
-rw-r--r-- 1 root root 177K Nov  3 02:08 /opt/baserow/backup_d1test.tar.gz

定时备份（官方 cron 形态，宿主机 crontab 每日 03:00）：

0 3 * * * cd /opt/baserow/deploy && docker compose exec -T -e PGPASSWORD='<密码>' -w /baserow/data/backups baserow /baserow.sh backend-cmd manage backup_baserow -f /baserow/data/backups/backup-$(date +\%Y\%m\%d).tar.gz -h db -d baserow -U baserow >> /var/log/baserow_backup.log 2>&1

（crontab 中 % 需转义为 \%；备份目录所在卷空间需纳入监控，保留策略靠定期清理旧文件。）

4.6 restore_baserow：整库还原

参数签名（manage restore_baserow --help 实测）：

restore_baserow [-h] -f FILE -h HOST -d DATABASE -U USERNAME [-p PORT] [-j JOBS] [additional_arguments ...]

帮助原文两条硬约束（实测均验证）："Only restoring into existing blank databases is supported"——目标库必须已存在且为空；"Restoring into a running Baserow instance is unsafe"——还原生产库前必须先停应用。

失败案例一：目标库不存在（实测）：

$ docker compose exec -T -e PGPASSWORD=q1w2e3r4 -w /baserow/data/backups baserow /baserow.sh backend-cmd manage restore_baserow -f /baserow/data/backups/backup-d1test.tar.gz -h db -d baserow_ghost -U baserow
pg_restore: error: connection to server at "db" (10.89.56.2), port 5432 failed: FATAL:  database "baserow_ghost" does not exist
[BACKEND] ... ERROR CommandError: An error ocurred when trying to restore the backup:

失败案例二：目标库非空（重复还原）（实测）：

pg_restore: error: could not execute query (exit code 1) ... ERROR: function already exists with same argument types
[BACKEND] ... ERROR CommandError: An error ocurred when trying to restore the backup:

成功路径：建空库 → 还原（实测）：

docker compose exec db psql -U baserow -d postgres -tAc "CREATE DATABASE baserow_restore OWNER baserow;"
docker compose exec -T -e PGPASSWORD=q1w2e3r4 -w /baserow/data/backups \
  baserow /baserow.sh backend-cmd manage restore_baserow \
  -f /baserow/data/backups/backup-d1test.tar.gz -h db -d baserow_restore -U baserow

实测输出（关键行）：

[BACKEND] ... INFO Successfully restored Baserow to the database called: baserow_restore

生产库整库还原演练（停应用 → drop/create → 一次性容器还原 → 起服务，实测全流程）：

cd /opt/baserow/deploy
docker compose stop baserow
docker compose exec db psql -U baserow -d postgres -tAc "DROP DATABASE baserow;"
docker compose exec db psql -U baserow -d postgres -tAc "CREATE DATABASE baserow OWNER baserow;"
docker compose run --rm --no-deps -e PGPASSWORD=q1w2e3r4 -w /baserow/data/backups \
  baserow backend-cmd manage restore_baserow -f /baserow/data/backups/backup-d1test.tar.gz -h db -d baserow -U baserow
docker compose up -d baserow

实测输出：

DROP DATABASE
CREATE DATABASE
[BACKEND] ... INFO Successfully restored Baserow to the database called: baserow
 ✔ Container baserow-2.4.1-server  Started
$ curl -s http://localhost:8128/api/_health/
OK

（docker compose run 传参形态：backend-cmd manage ... 不带 /baserow.sh 前缀——镜像入口即 /baserow.sh，run 的参数是入口脚本的参数，实测 docker compose run --rm --no-deps baserow help 直接打印 /baserow.sh 用法。）

还原后数据验证（API 登录 + 行数核对，实测）：

login token_len=231
rows count: 3
['', '', '备份闭环验证行']

（备份前写入的验证行完整找回；两行空行是 API 新建表自带的初始空行，实测建表响应行 id 即为 3。）

4.7 插件与辅助命令

  • 列插件：docker compose exec -T baserow /baserow.sh backend-cmd manage list-plugins——实测输出空（社区版无已装插件）；
  • 装/卸插件：/baserow.sh install-plugin <pypi包名> / uninstall-plugin <插件ID>（入口脚本级，见部署指南第九章），需企业版授权，社区版装了不生效；
  • 模板同步：manage sync_templates——SYNC_TEMPLATES=true（默认）时启动已自动执行，手动用于模板库修复；
  • EE 清理类：audit_retention_period_clean、cleanup_stuck_database_export_jobs、delete_expired_trash_items 等，企业版运维范畴，本文环境未启用审计故不展开。

4.8 REST API 运维面

数据面批量操作（导入导出、脚本化建表、巡检）走 API。基础约定：POST /api/user/token-auth/ 换 JWT（见 4.3），请求头 Authorization: JWT <access_token>；路径参数数字一律为对象 ID。

建链实测（工作空间→数据库应用→表→行，全新实例 ID 从 1 起）：

B=http://localhost:8128
T=<access_token>
WS=$(curl -s -X POST $B/api/workspaces/ -H "Authorization: JWT $T" \
     -H 'Content-Type: application/json' -d '{"name":"默认空间"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])')
APP=$(curl -s -X POST $B/api/applications/workspace/$WS/ -H "Authorization: JWT $T" \
     -H 'Content-Type: application/json' -d '{"name":"项目任务","type":"database"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])')
TB=$(curl -s -X POST $B/api/database/tables/database/$APP/ -H "Authorization: JWT $T" \
     -H 'Content-Type: application/json' -d '{"name":"任务清单"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])')

实测输出：WS=1 APP=1 TB=1；取主字段 ID FID=1（GET /api/database/fields/table/1/ 中 primary=true 项）；建行 POST /api/database/rows/table/1/ -d '{"field_1":"备份闭环验证行"}' 返回行 id=3。

分页（实测，参数是 size + page，上限 200）：

$ curl -s "$B/api/database/rows/table/1/?size=2" -H "Authorization: JWT $T" | python3 -c 'import json,sys;d=json.load(sys.stdin);print("count:",d["count"],"ids:",[r["id"] for r in d["results"]]);print("next:",d.get("next"))'
count: 5 ids: [1, 2]
next: http://localhost:8128/api/database/rows/table/1/?page=2&size=2
$ curl -s "$B/api/database/rows/table/1/?size=2&page=2" -H "Authorization: JWT $T" | python3 -c 'import json,sys;d=json.load(sys.stdin);print("page2 ids:",[r["id"] for r in d["results"]])'
page2 ids: [3, 4]

超限请求（size=300）实测返回：

{"error": "ERROR_PAGE_SIZE_LIMIT", "message": "The page size is limited to 200.", "status": 400}

排序（order_by，降序加 - 前缀，字段名用 field_<ID>）：

$ curl -s "$B/api/database/rows/table/1/?order_by=-field_1" -H "Authorization: JWT $T" | python3 -c 'import json,sys;print([r.get("field_1") for r in json.load(sys.stdin)["results"]])'
['备份闭环验证行', '分页验证行B', '分页验证行A', '', '']

用行 ID 排序（order_by=-id）实测报 {"error":"ERROR_ORDER_BY_FIELD_NOT_FOUND","detail":"The field -id was not found in the table."}——排序键必须是字段。

过滤（表级端点用 search 全文匹配，实测）：

$ curl -s -G "$B/api/database/rows/table/1/" -H "Authorization: JWT $T" --data-urlencode 'search=分页' | python3 -c 'import json,sys;d=json.load(sys.stdin);print("count:",d["count"],[r.get("field_1") for r in d["results"]])'
count: 2 ['分页验证行A', '分页验证行B']

结构化条件过滤（field_filters=[{"fieldId":1,"type":"equal","value":"..."}]）是视图级参数：实测在表级端点（不带视图上下文）传入被静默忽略返回全量，需结合视图 filter 配置使用。

五、注意事项

  1. 备份/还原参数形态：文件路径必须 -f 命名参数，位置参数写法直接报错（实测）；口令走 PGPASSWORD/.pgpass，命令行无 -W 类参数。
  2. 工作目录可写性：exec 默认 cwd / 不可写，backup_baserow 会在 cwd 生成临时 tar 而 PermissionError——务必 -w /baserow/data/backups（实测）。
  3. 还原目标必须是空库：官方帮助明示 "Only restoring into existing blank databases is supported"；非空库重复还原报 function already exists（实测）。生产库还原先 DROP DATABASE + CREATE DATABASE。
  4. 还原时应用必须停止：docker compose stop baserow 后用 docker compose run --rm --no-deps 起一次性容器执行还原（实测流程），切勿在应用运行时动生产库。
  5. createsuperuser 不建 UserProfile：username≠email 时 API 登录 500（实测），按 4.3 补建；最省事的办法是 username 直接用邮箱。
  6. 备份一致性：官方帮助警告运行中备份可能不一致（"it is recommended that you shut down the Baserow server before making a backup"）；低峰期执行 + 异机留存，重要变更前先备份。
  7. backend-cmd 与 backend-cmd-with-db：外部 PostgreSQL 形态用 backend-cmd 即可；backend-cmd-with-db 面向内嵌库场景，实测在外部库环境执行时会尝试拉起内嵌 redis 并报 Failed listening on port 6379（端口已被占用）的无害噪音，命令本身仍正常完成。
  8. compose exec 与 run 的参数差异：exec 要写全 /baserow.sh backend-cmd ...，run 只写 backend-cmd ...（入口脚本即 /baserow.sh，实测）。

六、常见问题 FAQ

Q1：backup 报 pg_dump: option requires an argument -- 'f'？ 把备份路径写成了位置参数。正确形态：manage backup_baserow -f <路径> -h <db主机> -d <库> -U <用户>（实测）。

Q2：backup 报 PermissionError: [Errno 13] ... 'baserow_backup_...'？ exec 默认工作目录 / 对降权后的 baserow_docker_user 不可写，临时备份文件生成在 cwd。加 -w /baserow/data/backups（实测）。

Q3：还原报 database "xxx" does not exist？ restore_baserow 不建库。先 psql -tAc "CREATE DATABASE xxx OWNER baserow;" 再还原（实测成功）。

Q4：还原报 function already exists with same argument types？ 目标库非空。drop/create 重建空库后再还原（实测）。

Q5：API 登录 500，日志 User has no profile？ CLI 建的超管缺 UserProfile 行，按 4.3 用 manage shell 补建（实测 PROFILE created=True，登录恢复）。

Q6：health_check 报 Migrations: UNAPPLIED？ 执行 manage migrate（4.4）；升级场景按「备份→换镜像→migrate→起服务」顺序（见《Baserow 2.4.1 配置参数详解》5.5）。

Q7：size=300 报 ERROR_PAGE_SIZE_LIMIT？ 表级行接口单页上限 200（实测），翻页用 page 参数逐页取。

七、参考链接

Baserow 2.4.1 常用 CLI 命令与运维实操 - Quzuo