NocoBase 备份管理器如何对数据库与上传文件做定时备份和还原-育师

NocoBase 备份管理器如何对数据库与上传文件做定时备份和还原

【免费下载链接】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 时，一个常见的运维需求是：让系统按固定时间自动对主数据库和用户上传的文件做全量备份，并在需要时把数据还原到备份时的状态。NocoBase 的备份管理器插件（@nocobase/plugin-backups）提供数据库及用户上传文件的全量备份、定时备份、备份的下载、删除与还原。本文基于备份管理文档给出从确认环境、配置定时备份到执行还原的完整操作路径。

适用前提：备份管理器依赖与主数据库版本匹配的数据库客户端（如mysqldump/pg_dump），使用前必须先确认当前运行环境中已有对应客户端。

前置条件：确认数据库客户端可用

备份管理器依赖对应主数据的数据库客户端。先确认当前运行环境中已有与数据库版本匹配的客户端，否则备份无法执行。

使用 Docker 安装 NocoBase 时，推荐直接使用对应版本的full镜像，例如latest-full、beta-full、alpha-full。这类镜像已内置常用数据库客户端，通常无需手动安装。

如果当前环境缺少数据库客户端，有两个途径：

前往官网下载与所使用的数据库版本匹配的客户端（MySQL 与 PostgreSQL 各自的官方下载页）。
在 Docker 环境中，可以直接在./storage/scripts目录下编写一段安装脚本install-database-client.sh，由容器在启动时安装：

mkdir ./storage/scripts cd ./storage/scripts vim install-database-client.sh

文档为两种数据库分别提供了脚本内容。脚本会修改容器的 apt 源配置（/etc/apt/sources.list）并安装系统包，属于会改变容器环境的操作，仅建议在 NocoBase 专用容器中使用。

PostgreSQL 版本：

#!/bin/bash # Check if pg_dump is installed if [ ! -f /usr/bin/pg_dump ]; then echo "pg_dump is not installed, starting PostgreSQL client installation..." # Configure Aliyun mirrors 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 # Install necessary tools and clean cache rm -rf /etc/apt/sources.list.d/debian.sources && apt-get update && apt-get install -y --no-install-recommends wget gnupg \ && rm -rf /var/lib/apt/lists/* # Configure PostgreSQL source echo "deb [signed-by=/usr/share/keyrings/pgdg.asc] http://mirrors.aliyun.com/postgresql/repos/apt bookworm-pgdg main" > /etc/apt/sources.list.d/pgdg.list wget --quiet -O /usr/share/keyrings/pgdg.asc http://mirrors.aliyun.com/postgresql/repos/apt/ACCC4CF8.asc # Install PostgreSQL client apt-get update && apt-get install -y --no-install-recommends postgresql-client-16 \ && rm -rf /var/lib/apt/lists/* echo "PostgreSQL client installation completed." else echo "pg_dump is already installed, skipping PostgreSQL client installation." fi

MySQL/MariaDB 版本（脚本会下载mysql-community-client-core的 deb 包并解压出mysqldump与mysql可执行文件到/usr/bin/）：

#!/bin/bash if [ ! -f /usr/bin/mysql ]; then echo "MySQL client is not installed, starting MySQL client installation..." 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 echo "Updating package list and installing necessary tools..." rm -rf /etc/apt/sources.list.d/debian.sources && apt-get update && apt-get install -y --no-install-recommends wget gnupg \ && rm -rf /var/lib/apt/lists/* wget --no-check-certificate https://downloads.mysql.com/archives/get/p/23/file/mysql-community-client-core_8.0.39-1debian12_amd64.deb && \ dpkg -x mysql-community-client-core_8.0.39-1debian12_amd64.deb /tmp/mysql-client && \ cp /tmp/mysql-client/usr/bin/mysqldump /usr/bin/ && \ cp /tmp/mysql-client/usr/bin/mysql /usr/bin/ echo "MySQL client installation completed." else echo "MySQL client is already installed, skipping installation." fi

脚本写好后重启 app 容器，并查看日志确认没有报错：

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

最后验证客户端版本号，必须与数据库服务端的版本号一致：

PostgreSQL：

docker compose exec app bash -c "pg_dump -V"

MySQL/MariaDB：

docker compose exec app bash -c "mysql -V"

配置定时备份

进入备份管理器的设置标签页，修改备份设置，点击保存即可生效。文档给出的设置项如下：

自动备份：开启根据 Cron 运行自动备份后，可设置按指定时间自动备份。
最大备份数：设置备份文件本地最大保存数量，超出数量后将自动删除本地最早的备份文件。
同步备份文件至云存储：设置备份文件备份成功后自动上传的云存储（可选分支，需要已配置可用的云存储）。
备份本地存储文件：是否把用户上传到服务器本地存储中的文件（storage/uploads）包含在备份中。标题场景要求“数据库 + 上传文件”都纳入备份，这一项需要开启。
还原密码：如果设置了还原密码，恢复备份时需要输入该密码。

注意：还原密码请妥善保管，遗忘密码将无法还原备份文件。

关于 cron 表达式，文档说明通过根据 Cron 运行自动备份按指定时间自动备份，未给出具体示例；从插件源码 plugin.ts 可见设置项中内置的默认 cron 值为0 0 * * *（每日 0 点触发一次），设置保存后应用会自动按新的 cron 重新计算下一次执行时间。

手动新建备份

除了定时自动备份，也可以随时手动触发一次备份：点击新建备份按钮，即可根据备份配置新建备份，并在备份列表中显示备份状态。备份完成后，点击备份项的下载按钮可下载备份文件，点击删除按钮可删除该备份文件。

还原备份

备份列表中的每一项都支持还原操作；此外也支持从本地备份文件还原。两种方式路径如下：

从备份列表中还原：点击备份列表中备份项的还原按钮，在弹出窗口中输入备份文件加密密码，点击确认还原备份。未加密备份文件无需输入密码。

上传本地备份文件还原：点击从本地备份还原按钮，在弹出窗口中选择本地备份文件，输入备份文件加密密码，点击确认还原备份。未加密备份文件无需输入密码。

执行还原前需要关注以下条件：

还原前先做一份当前数据库的备份。备份还原均为数据库全量操作，文档明确推荐在备份还原前先备份一份当前数据库。
以下场景不允许执行还原操作：
- 当前 NocoBase 版本低于备份文件中的 NocoBase 版本时；
- 当前 NocoBase 数据库与备份文件中的以下配置不一致时：dialect（数据库类型）、underscored（字段配置）、table prefix（表前缀）、schema（表结构）。
未开启容错模式且创建备份时数据库版本高于当前应用数据库版本时，不允许还原。若需要将备份文件还原至低版本数据库，需要开启容错模式。

验证与限制

备份是否成功：在备份列表查看备份项及其状态（新建备份与自动备份都会在备份列表中显示备份状态），必要时用下载按钮取回备份文件核对。
客户端版本是否匹配：通过上文pg_dump -V/mysql -V确认客户端版本与数据库服务端版本一致，这是备份能正常执行的前提。
还原的硬限制：还原密码遗忘后无法还原备份文件；版本或dialect、underscored、table prefix、schema不一致时不允许还原，需要按上文条件逐项核对后再执行。
自动备份的触发机制：定时备份依赖自动备份设置中的 Cron 配置，修改设置并保存后生效；备份超出最大备份数时本地最早的文件会被自动删除，重要备份应通过下载或同步备份文件至云存储另行保存。