NocoBase 模板打印插件安装指南：商业插件激活、LibreOffice 与 Docker 环境配置-迪斯科星球

NocoBase 模板打印插件安装指南：商业插件激活、LibreOffice 与 Docker 环境配置

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

NocoBase 的模板打印插件支持使用 Word、Excel 和 PowerPoint 编辑模板文件（.docx、.xlsx、.pptx），通过占位符与逻辑结构动态生成业务文档，并可输出 PDF，广泛应用于报价单、发票、合同等场景。本文聚焦该插件的安装全流程：先说明商业插件激活与升级的通用方式，再重点讲解 PDF 生成所依赖的 LibreOffice 的安装方案，最后结合仓库中的 Docker 入口脚本与 Compose 配置，深入说明storage/scripts脚本机制、容器重启与安装校验等实战细节，帮助你在一套 Docker 部署的 NocoBase 上完整跑通模板打印能力。

一、安装插件（商业插件激活）

模板打印插件属于 NocoBase 的商业插件，安装与升级方式与普通开源插件不同，需要先完成商业许可的激活。官方提供了专门的激活指南（《商业插件激活指南》），其中覆盖了以下关键环节：

许可获取：商业插件需要购买许可证并获取对应的激活凭证；
激活操作：在应用后台或通过配置完成许可证的绑定与激活；
版本升级：商业插件随 NocoBase 主版本升级时，需要同步更新并重新激活。

完成激活后，插件便出现在应用的可启用插件列表中。启用后即可在详情区块与表格区块中看到“模板打印”操作按钮，具体启用方式可参考模板打印配置：在详情区块点击“配置操作”，选择“模板打印”即可激活功能；表格区块用法基本相同，区别在于支持勾选多条记录批量打印（最多 100 条），且由于数据结构不同（对象 vs 数组），表格区块与详情区块的模板互不通用。

提示：不同版本/渠道获取的商业插件包名可能带有template-print字样（如 action-template-print），安装后请以应用后台「插件管理」中实际显示的插件名为准。

二、安装 LibreOffice（生成 PDF 的必备依赖）

模板打印支持直接输出.docx、.xlsx、.pptx以及PDF文件。其中生成 PDF 必须依赖 LibreOffice 进行文档转换，因此这是「可选但按需必装」的环节——如果业务只需要 Word/Excel/PPT 文件，可以跳过；一旦需要 PDF 输出，就必须确保运行 NocoBase 的环境（服务器或容器）中安装了 LibreOffice。

2.1 非 Docker 环境

非 Docker（直接部署在服务器）的情况下，直接前往 LibreOffice 官网下载对应操作系统的安装包并完成安装即可。安装完成后，确保libreoffice命令在 PATH 中可用，NocoBase 服务在生成 PDF 时会调用该命令。

2.2 Docker 环境：利用`storage/scripts`自动执行脚本

在 Docker 部署中，不建议在构建镜像时写死 LibreOffice，更推荐的做法是利用 NocoBase 容器启动时自动执行的storage/scripts目录机制，在每次容器启动时检查并安装 LibreOffice。

先在宿主机上创建脚本文件：

mkdir ./storage/scripts cd ./storage/scripts vim install-libreoffice.sh

install-libreoffice.sh的完整内容如下（脚本会在容器启动时由 NocoBase 的入口脚本自动执行）：

#!/bin/bash # Define variables INSTALL_DIR="/opt/libreoffice24.8" DOWNLOAD_URL="https://downloadarchive.documentfoundation.org/libreoffice/old/24.8.5.2/deb/x86_64/LibreOffice_24.8.5.2_Linux_x86-64_deb.tar.gz" # Check if LibreOffice is already installed if [ -d "$INSTALL_DIR" ]; then echo "LibreOffice is already installed, skipping installation." exit 0 fi # Update APT sources tee /etc/apt/sources.list > /dev/null <<EOF deb http://mirrors.aliyun.com/debian/ bookworm main contrib non-free deb-src http://mirrors.aliyun.com/debian/ bookworm main contrib non-free deb http://mirrors.aliyun.com/debian-security/ bookworm-security main contrib non-free deb-src http://mirrors.aliyun.com/debian-security/ bookworm-security main contrib non-free deb http://mirrors.aliyun.com/debian/ bookworm-updates main contrib non-free deb-src http://mirrors.aliyun.com/debian/ bookworm-updates main contrib non-free deb http://mirrors.aliyun.com/debian/ bookworm-backports main contrib non-free deb-src http://mirrors.aliyun.com/debian/ bookworm-backports main contrib non-free EOF # Update APT and install dependencies apt-get update apt-get install -y \ libfreetype6 \ fontconfig \ libgssapi-krb5-2 \ libxml2 \ libnss3 \ libdbus-1-3 \ libcairo2 \ libxslt1.1 \ libglib2.0-0 \ libcups2 \ libx11-xcb1 \ fonts-liberation \ fonts-noto-cjk \ wget rm -rf /var/lib/apt/lists/* cd /app/nocobase/storage/scripts # Download and install LibreOffice if not already present if [ ! -d "./libreoffice" ]; then rm -rf libreoffice.tar.gz wget --no-check-certificate -O libreoffice.tar.gz $DOWNLOAD_URL if [ $? -ne 0 ]; then echo "Failed to download LibreOffice." exit 1 fi rm -rf libreoffice && mkdir libreoffice tar -zxvf libreoffice.tar.gz -C ./libreoffice --strip-components=1 if [ $? -ne 0 ]; then echo "Failed to extract LibreOffice." exit 1 fi fi # Install LibreOffice dpkg -i libreoffice/DEBS/*.deb ln -s /opt/libreoffice24.8/program/soffice.bin /usr/bin/libreoffice libreoffice --version if [ $? -ne 0 ]; then echo "Failed to install LibreOffice." exit 1 fi echo "LibreOffice installation completed successfully."

这段脚本有几个值得留意的设计点：

幂等性：通过检查/opt/libreoffice24.8目录是否存在来决定是否跳过安装，避免每次容器启动都重复下载；
下载与解压分离：先wget下载 tar 包，再解压到./libreoffice，每步都有失败退出校验，便于排查；
依赖预装：安装的libfreetype6、fontconfig、libcairo2、libnss3、libcups2等是 LibreOffice 在无图形界面（headless）环境下正常运行所必需的动态库；
中文字体支持：fonts-noto-cjk用于保证模板中的中文内容在转换为 PDF 时能够正确渲染，不会出现乱码或豆腐块；
软链暴露命令：ln -s /opt/libreoffice24.8/program/soffice.bin /usr/bin/libreoffice将 LibreOffice 的可执行文件链接为全局libreoffice命令，NocoBase 打印服务据此调用；
镜像源适配：脚本将 APT 源替换为阿里云镜像，这是为了在国内网络环境下加速依赖下载，如果你的网络环境不同，可以替换为可访问的 Debian 源。

2.3 脚本为何会被自动执行：容器入口机制

上述脚本能生效的关键在于 NocoBase 官方 Docker 镜像的入口脚本 docker-entrypoint.sh 中有一段「启动前自动执行 storage/scripts 下所有 shell 脚本」的逻辑（对应文件第 146-152 行）：

# run scripts in storage/scripts if [ -d "/app/nocobase/storage/scripts" ]; then for f in /app/nocobase/storage/scripts/*.sh; do [ -e "$f" ] || continue echo "Running $f" sh "$f" done fi

也就是说：只要把*.sh脚本放进容器的/app/nocobase/storage/scripts目录，容器每次启动时都会在正式拉起 NocoBase 应用（yarn start --quickstart）之前按文件名顺序执行这些脚本。这也是「重启 app 容器即可触发安装」的底层原因——重启时入口脚本会重新扫描该目录并运行install-libreoffice.sh。

而storage/scripts之所以能通过宿主机上的./storage/scripts直接访问，是因为 Docker 部署默认将宿主机./storage目录挂载到容器内的/app/nocobase/storage。例如仓库中的 docker/app-sqlite/docker-compose.yml 所示：

volumes: - ./storage:/app/nocobase/storage

因此你只需在宿主机（Compose 项目目录下）创建storage/scripts/install-libreoffice.sh并赋予可执行权限，无需重新构建镜像，重启容器后脚本即会在容器内生效。

三、重启容器并校验安装结果

3.1 重启 app 容器

脚本编写完成后，重启 app 容器使其在启动阶段执行安装脚本：

docker compose restart app # 查看日志 docker compose logs app

执行docker compose logs app时，可以在启动日志中看到入口脚本执行storage/scripts的痕迹，例如Running /app/nocobase/storage/scripts/install-libreoffice.sh，以及脚本末尾打印的LibreOffice installation completed successfully.。如果下载或安装失败，脚本会以非零状态退出并在日志中留下对应错误信息，便于定位是网络下载问题还是依赖缺失问题。

3.2 校验 LibreOffice 是否安装成功

进入容器直接检查libreoffice命令的版本：

$ docker compose exec app bash -c "libreoffice --version" LibreOffice 24.8.4.2 bb3cfa12c7b1bf994ecc5649a80400d06cd71002

只要能正常输出版本号，说明命令已可用、动态库依赖完整，模板打印的 PDF 转换链路即可正常工作。

四、安装完成后的验证路径

插件与 LibreOffice 都就绪后，建议按如下路径做一次端到端验证：

在详情区块通过「配置操作 → 模板打印」激活功能（参见模板打印配置）；
在「模板配置」中新建模板，填写模板名称、选择类型（Word/Excel/PowerPoint）、上传.docx/.xlsx/.pptx模板文件；
从字段列表复制占位符变量填入模板并保存；
回到详情页点击「模板打印」按钮，分别验证生成原始格式文件与 PDF 文件。

如果 PDF 生成报错，可优先排查：LibreOffice 是否安装（libreoffice --version）、中文字体是否缺失（fonts-noto-cjk）、容器内网络是否能访问下载地址。关于模板语法（占位符、循环、条件输出、格式化器）与渲染问题的详细说明，可继续阅读模板打印语法与模板打印常见问题。

五、小结

模板打印插件的安装可以拆成两个独立维度：

维度	是否必需	说明
商业插件激活	必需	通过商业许可激活指南完成插件安装与升级，启用后出现「模板打印」操作入口
LibreOffice	生成 PDF 时必需	非 Docker 环境直接官网安装；Docker 环境利用`storage/scripts`自动执行安装脚本，重启容器后校验`libreoffice --version`

借助 docker-entrypoint.sh 的 storage/scripts 机制与宿主机./storage卷挂载，你可以在不重新构建镜像的前提下，以「写脚本 + 重启容器」的方式为任何 Docker 部署的 NocoBase 实例补充 PDF 输出能力，这也是该方案在运维层面最实用的价值所在。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析