Baserow 插件安装实战：Docker 镜像定制、运行时安装与环境变量自动安装的完整指南

Baserow 插件安装实战：Docker 镜像定制、运行时安装与环境变量自动安装的完整指南

【免费下载链接】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 官方插件安装文档（docs/plugins/installation.md）并结合仓库内deploy/plugins/下的真实安装脚本实现，系统讲解 Baserow 插件的三种安装方式（自定义 Dockerfile、现有容器内安装、启动时环境变量）、插件目录结构与安全校验机制、运行时安装的容器重建注意事项，以及插件卸载与查询的全部操作。读完后你将能够在自建（self-hosted）的 Baserow 环境中安全地安装、升级、卸载和审计任意社区或自研插件。

需要先明确一点：Baserow 插件目前仍处于early preview（早期预览）阶段，文档明确列出了以下安全前提，任何安装操作都应以此为准：

• 插件安装后对你的数据拥有完全访问权限，可以执行任意代码。Baserow 不对插件做沙箱隔离、也不做任何安全检查；
• Baserow 不验证、不担保任何插件的安全性，也不对因安装或使用插件导致的任何损坏或损失承担责任；
• 使用插件完全由你自行承担风险——务必信任插件来源，并在启用任何插件之前做好数据备份（备份方法参见 Docker 安装指南的备份章节）；
• 该功能只推荐给熟悉 Docker、volume、容器和命令行的高级用户；
• 部分能力目前缺失，例如没有用于查看已安装插件的 UI，所有管理操作都通过命令行完成。

理解这些限制后，下面的内容就聚焦于"具体怎么装、怎么卸、怎么查"，并用仓库源码解释每一步背后脚本到底做了什么。

方式一：构建自定义 all-in-one 镜像（最推荐）

官方文档指出，构建自己的 all-in-one 镜像是目前最简单、最快、最可靠的插件安装方式。完整流程如下：

1. 强烈建议先备份数据。插件拥有完全访问权限，备份是官方流程的第一步，详见 Docker 安装指南的备份章节。
2. 确保本机已安装并保持 Docker 为最新。
3. 创建一个名为Dockerfile的新文件，用它来构建一个预装所需插件的自定义 Baserow 镜像。
4. 将以下内容复制进Dockerfile：

FROM baserow/baserow:2.3.3 # You can install a plugin found in a git repo: RUN /baserow/plugins/install_plugin.sh \ --git https://github.com/example/example_baserow_plugin.git # Or you can download a tar.gz directly from an url RUN /baserow/plugins/install_plugin.sh \ --url https://example.com/plugin.tar.gz # Or you can install the plugin from a local folder by copying it into the image and \ # then installing using --folder COPY ./some_local_dir_containing_your_plugin/ /baserow/data/plugins/your_plugin/ RUN /baserow/plugins/install_plugin.sh \ --folder /baserow/data/plugins/your_plugin/ # The --hash flag below will make the install_plugin.sh script check that the # plugin exactly matches the provided hash. # # We recommend you provide this flag to make sure the downloaded plugin has not # been maliciously modified. # # To get the hash of a plugin simply run the docker build with a nonsense --hash # value. Then the build will fail and `install_plugin.sh` will print the hash of the # downloaded plugin. Then you can replace your nonsense --hash value with the printed # one and build again. RUN /baserow/plugins/install_plugin.sh \ --git https://github.com/example/example_baserow_plugin.git \ --hash hash_of_plugin_2

5. 从上面的RUN命令中只保留你要用的那一条，删除其余的，并把示例 URL 替换成你的插件地址。
6. 构建自定义镜像：

docker build -t my-customized-baserow:2.3.3 .

7. 像运行普通 Baserow 镜像一样运行新镜像：

docker run -p 80:80 -v baserow_data:/baserow/data my-customized-baserow:2.3.3

源码印证：install_plugin.sh到底做了什么

上述Dockerfile中调用的/baserow/plugins/install_plugin.sh在仓库中对应 deploy/plugins/install_plugin.sh，它在构建 all-in-one 镜像时会被复制到镜像内（见 deploy/all-in-one/Dockerfile 中的COPY deploy/plugins/*.sh /baserow/plugins/与BASEROW_PLUGIN_DIR=/baserow/data/plugins环境变量定义）。阅读该脚本可以确认几个实操中容易踩坑的细节：

• 三种来源互斥。脚本用getopt解析参数，--folder、--url、--git三个标志中必须且只能提供一个，提供 0 个或多个都会报错退出（exclusive_flag_count检查）。参数含义如下：
  • --folder <plugin folder>：插件所在文件夹路径；
  • --git <https git repo url>：包含插件的 https git 仓库地址；
  • --url <plugin url>：包含插件的.tar.gz文件下载地址；
  • --hash <plugin hash>：若提供，安装前会对插件内容做哈希校验，不匹配则安装失败（见下文）；
  • --dev：以开发模式安装（pip install -e可编辑安装前端yarn install而非构建）；
  • --runtime：触发运行时 setup 脚本；从 Dockerfile 调用时永远不应设置此参数；
  • --overwrite：覆盖同名已安装插件并强制重装/重建。
• git 仓库有结构要求：使用--git时，脚本git clone后要求仓库中的plugins/子目录下有且只有一个子目录，否则报错 "does not look like a Baserow plugin"。
• tar.gz 包同样有结构要求：使用--url时，脚本curl -Ls "$url" | tar xz解压后，要求归档内含有一个plugins/目录，且其中恰好只有一个插件子目录。
• 插件目录结构：每个插件是一个以插件名命名的文件夹，内含backend/（必须是合法的 Python 包）和/或web-frontend/（必须是合法的 node 包）子目录；若存在backend/build.sh或web-frontend/build.sh，会在安装时执行以完成额外安装任务。
• 哈希校验的具体算法：--hash校验的实现是对插件目录内所有文件先sha1sum，再对排序后的文件清单结果做一次sha1sum（find "$folder" -type f -print0 | sort -z | xargs -0 sha1sum | sha1sum）。这正是文档建议的"先填一个假 hash 值触发构建失败、从报错输出中读取真实 hash 再回填"操作可行的原因——校验失败时脚本会同时打印实际 hash 与期望 hash。由于插件"可以执行任意代码"，这一校验步骤对来自不可信来源的插件尤其重要，文档明确推荐使用--hash。
• 安装动作本身：backend 模块通过pip3 install装入/baserow/venv；web-frontend 模块通过yarn add引入并触发 Nuxt 构建。脚本还会创建/baserow/container_markers目录写入构建标记文件（如<plugin>.backend-built），用于避免重复安装——这也解释了文档"容器重建注意事项"一节的行为（见后文）。

方式二：安装到现有的 all-in-one 容器

这种方式直接把插件安装进一个已经存在的容器及其数据卷，适合不想重新构建镜像的场景。前提是容器已停止。

1. 同样，强烈建议先备份数据（参见 Docker 安装指南的备份章节）。
2. 对已停止的容器执行安装（替换示例 URL 与可选 hash 为你自己的插件）：

docker exec baserow \ ./baserow.sh install-plugin \ --git https://github.com/example/example_baserow_plugin.git \ --hash hash_of_plugin_1

3. 重启服务器以启用插件：

docker restart baserow

从 deploy/all-in-one/baserow.sh 可以看到，install-plugin子命令实际等价于在容器内执行/baserow/plugins/install_plugin.sh --runtime并透传其余参数——注意脚本自动附加了--runtime标志，与 Dockerfile 构建方式的关键区别就在于此：运行时安装会额外执行插件提供的runtime_setup.sh（如果存在）。这也说明文档中"必须先把容器停止再 exec"的原因：安装过程会改动容器文件系统内的依赖环境。

方式三：通过环境变量在启动时安装

使用官方 Baserow 镜像时，可以通过两个环境变量在容器启动阶段自动安装插件：

• BASEROW_PLUGIN_GIT_REPOS：逗号分隔的 https git 仓库 URL 列表，启动时逐个下载并安装；
• BASEROW_PLUGIN_URLS：逗号分隔的 URL 列表，启动时下载并安装其中的.tar.gz插件包。

示例——启动一个已预装两个插件的新容器：

docker run \ -v baserow_data:/baserow/data \ # ... 其他常规启动参数写在这里 -e BASEROW_PLUGIN_GIT_REPOS=https://example.com/example/plugin1.git,https://example.com/example/plugin2.git \ baserow:2.3.3

启动时的自动安装机制

从源码可以确认这两个环境变量并非魔法，而是由启动流程显式处理：

• all-in-one 容器的启动脚本 deploy/all-in-one/supervisor/start.sh 在拉起 supervisord 之前会source /baserow/plugins/utils.sh并调用startup_plugin_setup；
• deploy/plugins/utils.sh 中的startup_plugin_setup函数做了三件事：
  1. 遍历$BASEROW_PLUGIN_DIR（在 all-in-one 镜像中被设置为/baserow/data/plugins）下每个插件目录，对尚未在当前容器内安装完成的插件重新执行install_plugin.sh --runtime --folder ...；
  2. 将BASEROW_PLUGIN_URLS按逗号拆分，逐个执行install_plugin.sh --runtime --url ...；
  3. 将BASEROW_PLUGIN_GIT_REPOS按逗号拆分，逐个执行install_plugin.sh --runtime --git ...。
• 若设置了BASEROW_DISABLE_PLUGIN_INSTALL_ON_STARTUP，则跳过上述全部逻辑并打印提示日志。

这意味着两点实践结论：其一，这两个环境变量只在容器启动时触发一次安装，之后不会持续监听；其二，卸载一个用环境变量安装的插件不能只uninstall-plugin加重启，否则重启时环境变量会把它再装回来（文档在"环境变量方式卸载"一节对此有专门警告，见下文）。

容器重建注意事项（Caveats）

文档特别强调了一个容易误解的场景：如果删除了曾在其内运行时安装过插件的容器再重新创建，新容器是从不含任何插件的baserow/baserow:2.3.3基础镜像创建的。但只要数据卷没丢，插件不会消失，原因在源码中很清晰：

• 无论构建时还是运行时安装，插件本体都保存在数据卷挂载的/baserow/data/plugins目录下（而非镜像层）；
• 启动时startup_plugin_setup会扫描该目录，对"插件目录存在但当前容器内尚未安装"的插件自动重新执行安装；
• 是否"已安装"的判断依据是/baserow/container_markers中的标记文件（<plugin>.backend-built、<plugin>.web-frontend-built等），它们位于容器文件系统内而非数据卷——这正是为什么容器从零重建后会看到插件"重新安装一遍"的现象。

结论与文档一致：只要复用同一个数据卷，即使删除并重建容器也不会丢失任何插件数据；唯一影响是新建容器的首次启动日志中会看到插件自我重装的过程。

在 standalone 服务镜像中安装

除了 all-in-one 镜像，Baserow 还提供baserow/backend:2.3.3与baserow/web-frontend:2.3.3镜像，它们只分别运行 backend/celery 或 web-frontend 服务，面向多服务 docker-compose、k8s 等更高级的自托管部署。

这些镜像同样提供install-plugin/uninstall-plugin/list-pluginsCLI（配合docker run指定命令），以及上文提到的两个插件环境变量。例如：

docker run --rm baserow/backend:2.3.3 install-plugin ... docker run -e BASEROW_PLUGIN_GIT_REPOS=https://example.com/example/plugin1.git,https://example.com/example/plugin2.git --rm baserow/backend:2.3.3

用法与上文各节完全相同，既可以写进 Dockerfile 也可以在运行时执行。脚本会自动检测自己运行在 backend-only 还是 web-frontend-only 镜像中，并只安装对应那一侧的插件模块——从 install_plugin.sh 的实现可以看到，安装逻辑就是分别判断/baserow/backend与/baserow/web-frontend目录是否存在，只处理与插件实际包含的子模块匹配的那一侧。文档中提到插件样板工程（plugin boilerplate）提供了在backend.Dockerfile和web-frontend.Dockerfile中这样做的示例，可参见 docs/plugins/boilerplate.md（该文档注明样板工程适用于 Baserow 2.0.6 及更早版本，新版请参照其指向的 boilerplate 仓库）。

卸载插件

警告（原文强调）：卸载会把插件从 Baserow 安装中移除，并永久删除其全部关联数据。

卸载脚本 deploy/plugins/uninstall_plugin.sh 的行为是：执行插件自带的backend/uninstall.sh/web-frontend/uninstall.sh（如果存在），然后pip3 uninstall后端包、yarn remove前端包并触发 Nuxt 重新构建，最后删除插件目录与 container markers。由于卸载过程可能需要回滚数据库迁移，all-in-one 镜像的uninstall-plugin子命令会通过 baserow.sh 中的run_cmd_with_db先拉起嵌入式 PostgreSQL 再执行卸载——这与安装路径（安装时数据库变更可留待启动时以正常迁移完成）不同，是理解"卸载必须先停容器/需要数据库"的关键。

场景一：卸载通过自定义 Dockerfile 安装的插件

1. 强烈建议先备份数据（参见 Docker 安装指南的备份章节）。
2. 先停止 Baserow 服务器：docker stop baserow
3. 用官方镜像挂载同一数据卷执行卸载：

docker run --rm -v baserow_data:/baserow/data baserow:2.3.3 uninstall-plugin plugin_name

4. 插件已卸载自身、全部关联数据已删除。
5. 编辑自定义Dockerfile，删除对应的插件安装步骤。
6. 重新构建镜像：docker build -t my-customized-baserow:2.3.3 .
7. 删除基于旧镜像的容器：docker rm baserow
8. 用去掉插件的新镜像重新运行：

docker run -p 80:80 -v baserow_data:/baserow/data my-customized-baserow:2.3.3

9. 文档特别提醒：如果不完成第 5–8 步，由于插件文件夹仍留在数据卷的/baserow/data/plugins中（自定义镜像里也仍装着该插件），任何一次容器重建都会触发启动时自动重装，插件会"复活"。

场景二：卸载直接装入容器的插件

1. 强烈建议先备份数据。
2. 针对不用 Dockerfile、而是直接装入现有容器的插件，在容器运行中执行（假设容器名为baserow）：

docker exec baserow ./baserow.sh uninstall-plugin plugin_name

3. 插件卸载自身、关联数据被删除。
4. 重启服务器：docker restart baserow

场景三：卸载通过环境变量安装的插件

1. 强烈建议先备份数据。
2. 若插件是用BASEROW_PLUGIN_GIT_REPOS或BASEROW_PLUGIN_URLS安装的，必须删除并重建容器，且新容器的环境变量中不再包含该插件。如果只用uninstall-plugin+docker restart，由于环境变量仍含有旧插件地址，重启时startup_plugin_setup会把它再装回来。正确步骤：
   1. docker stop baserow
   2. docker run --rm -v baserow_data:/baserow/data baserow:2.3.3 uninstall-plugin plugin_name
   3. 插件及其数据已移除。
   4. 用与原启动命令相同的docker run重新创建容器，仅把该插件从对应环境变量中剔除。

查看已安装的插件

使用list-plugins子命令或镜像内置的/baserow/plugins/list_plugins.sh脚本查看当前已安装的插件：

docker run \ --rm \ -v baserow_data:/baserow/data \ baserow:2.3.3 list-plugins # 或在运行中的容器里 docker exec baserow /baserow/plugins/list_plugins.sh

需要指出一个原文档的笔误：其"运行中容器"示例写的是/baserow/plugins/list_plugin.sh（单数），而仓库中的实际脚本名是 list_plugins.sh（复数），baserow.sh 调用的也是复数形式，实际操作请以复数名为准。

从 list_plugins.sh 的实现看，它会遍历/baserow/data/plugins（BASEROW_PLUGIN_DIR）下的每个插件目录并打印名称；若插件携带baserow_plugin_info.json元数据文件，还会解析并显示其中的description字段——这是目前最接近"查看已安装插件"的 UI 替代品（文档已说明正式 UI 尚缺）。

小结与操作速查

以上所有流程均基于当前仓库deploy/plugins/下的脚本实现与docs/plugins/installation.md文档交叉验证；由于插件处于 early preview 阶段且官方不做任何安全隔离，请始终将"信任来源 + 先备份 +--hash校验"作为安装前的标准动作。

【免费下载链接】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