企业官网建设流程全解析

NocoDB SQLite 模式如何用 Litestream 将元数据库备份到 S3 并恢复？

【免费下载链接】nocodb🔥 🔥 🔥 A Free & Self-hostable Airtable Alternative项目地址: https://gitcode.com/GitHub_Trending/no/nocodb

NocoDB 在 SQLite 模式下把元数据（工作区、Base、表结构、权限等 meta 信息）存放在本地单个noco.db文件中，容器重建或数据卷丢失时这部分数据会随之丢失。NocoDB 镜像在 packages/nocodb/docker 目录下内置了 Litestream 的启动脚本与配置模板：容器启动时先从 S3 副本恢复noco.db，再在后台运行litestream replicate持续同步，从而实现“元数据库持续备份到 S3 + 重启时自动从 S3 恢复”。本文的操作路径均来自 start-litestream.sh 与 litestream.yml 两个文件的实际内容。

模式启用条件：纯 SQLite 元数据库 + 三个必需变量

脚本通过use_litestream检查决定是否走 Litestream 流程，条件必须同时满足：

• 未设置NC_DB、NC_DB_JSON、NC_DB_JSON_FILE、DATABASE_URL、DATABASE_URL_FILE、NC_MINIMAL_DBS中的任何一个（即没有外接数据库，使用内置 SQLite 元数据库）；
• 已设置LITESTREAM_S3_BUCKET、LITESTREAM_S3_ACCESS_KEY_ID、LITESTREAM_S3_SECRET_ACCESS_KEY。

任一外接数据库变量非空时，脚本跳过整个 Litestream 流程，直接执行node docker/main.js启动 NocoDB，此时不会发生任何 S3 备份。

脚本还保留了旧变量名的向后兼容映射（仅在对应LITESTREAM_*变量为空时生效）：

• AWS_ACCESS_KEY_ID→LITESTREAM_S3_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY→LITESTREAM_S3_SECRET_ACCESS_KEY
• AWS_BUCKET_PATH→LITESTREAM_S3_PATH
• AWS_BUCKET→LITESTREAM_S3_BUCKET

配置模板 litestream.yml

litestream.yml 是 Litestream 的配置模板，文件头部注释指向 Litestream 官方配置参考，${...}占位符在运行期由容器环境变量填充：

dbs: - path: ${NC_TOOL_DIR}noco.db replicas: - type: s3 endpoint: ${LITESTREAM_S3_ENDPOINT} region: ${LITESTREAM_S3_REGION} skip-verify: ${LITESTREAM_S3_SKIP_VERIFY} bucket: ${LITESTREAM_S3_BUCKET} path: ${LITESTREAM_S3_PATH} access-key-id: ${LITESTREAM_S3_ACCESS_KEY_ID} secret-access-key: ${LITESTREAM_S3_SECRET_ACCESS_KEY} retention: ${LITESTREAM_RETENTION} retention-check-interval: ${LITESTREAM_RETENTION_CHECK_INTERVAL} snapshot-interval: ${LITESTREAM_SNAPSHOT_INTERVAL} sync-interval: ${LITESTREAM_SYNC_INTERVAL}

模板中只声明了一个库：${NC_TOOL_DIR}noco.db，即元数据库。NC_TOOL_DIR是元数据库所在目录，脚本开头会自动mkdir -p创建它。与 Litestream 配置同名的其余项（retention、snapshot-interval、sync-interval等）分别由LITESTREAM_RETENTION、LITESTREAM_SNAPSHOT_INTERVAL、LITESTREAM_SYNC_INTERVAL、LITESTREAM_RETENTION_CHECK_INTERVAL控制，含义以 Litestream 配置文档为准。

脚本中唯一有默认值的是LITESTREAM_S3_PATH：未提供时会被设为nocodb。

启动容器并传入备份变量

README 给出的 SQLite 模式启动命令是：

docker run -d \ --name noco \ -v "$(pwd)"/nocodb:/usr/app/data/ \ -p 8080:8080 \ nocodb/nocodb:latest

要启用 Litestream，需要把脚本读取的环境变量传入容器。下面的命令由 README 示例加上脚本中出现的变量名组合而成，尖括号内的值替换为你自己的 S3 端点、桶名与密钥（LITESTREAM_S3_PATH可选，省略时默认为nocodb）：

docker run -d \ --name noco \ -v "$(pwd)"/nocodb:/usr/app/data/ \ -p 8080:8080 \ -e LITESTREAM_S3_ENDPOINT="<S3 服务端点>" \ -e LITESTREAM_S3_BUCKET="<桶名>" \ -e LITESTREAM_S3_ACCESS_KEY_ID="<Access Key>" \ -e LITESTREAM_S3_SECRET_ACCESS_KEY="<Secret Key>" \ -e LITESTREAM_S3_PATH="nocodb" \ nocodb/nocodb:latest

启动后的实际流程：先恢复，再持续备份

条件满足后，start-litestream.sh 按以下顺序执行：

1. 不存在${NC_TOOL_DIR}时创建该目录；
2. 执行旧AWS_*变量到LITESTREAM_*变量的兼容映射；
3. 删除本地可能残留的noco.db、noco.db-shm、noco.db-wal。注意这是脚本明确声明的行为（注释原文为 "remove any possible local DB leftovers"）：进入 Litestream 模式后，本地元数据库文件在每次启动时先被清除，S3 副本是唯一的恢复来源；
4. 执行litestream restore "${NC_TOOL_DIR}noco.db"，从 S3 副本恢复本地元数据库；
5. 如果恢复后${NC_TOOL_DIR}noco.db仍不存在（说明 S3 上还没有副本，例如首次使用），则touch一个空库文件；
6. 后台启动litestream replicate &开始持续同步；
7. 执行node docker/main.js启动 NocoDB 主进程。

也就是说，“备份”由第 6 步的replicate进程在运行期间持续完成，“恢复”由第 4 步在每次启动时自动完成，两者都由同一次容器启动串起来，不需要额外操作。

如何判断恢复结果

脚本本身给出了两种分支结果，可作为启动后的判断依据：

• S3 上已有副本：第 4 步恢复后${NC_TOOL_DIR}noco.db由副本还原得到，元数据回到副本中保留的状态（可保留到哪个时间点由retention、snapshot-interval、sync-interval等配置项决定，以 Litestream 的行为为准）；
• S3 上尚无副本：本地得到的是一个新建的空noco.db，litestream replicate从此开始向 S3 写入副本——这对应全新实例的首次运行。

无论哪个分支，NocoDB 主进程都是在 restore 步骤之后才启动的。

可选分支：age 加密副本

如果同时设置LITESTREAM_AGE_PUBLIC_KEY与LITESTREAM_AGE_SECRET_KEY，脚本会先用dasel检查/etc/litestream.yml中第一个 replica 是否已有age配置；没有时写入：

dasel put --file "${LITESTREAM_CONFIG_PATH}" \ --read yaml \ --type json \ --value '{ "identities": [ "${LITESTREAM_AGE_SECRET_KEY}" ], "recipients": [ "${LITESTREAM_AGE_PUBLIC_KEY}" ] }' \ --selector 'dbs.first().replicas.first().age'

litestream.yml 中也保留了同结构的注释块供对照。不开启该分支时，副本按明文的 S3 对象存储。

边界与限制

• 本流程只在纯 SQLite 元数据库模式下生效：设置了NC_DB、NC_DB_JSON、NC_DB_JSON_FILE、DATABASE_URL、DATABASE_URL_FILE、NC_MINIMAL_DBS中任何一个，脚本都不会执行 Litestream 相关步骤。
• 配置模板只备份${NC_TOOL_DIR}noco.db这一个元数据库文件。
• 每次启动都会删除本地noco.db、noco.db-shm、noco.db-wal后再恢复，因此不要在该目录放置依赖本地保留的其他数据。
• LITESTREAM_*变量必须在容器启动时以环境变量形式提供，脚本本身不从其他文件读取这些配置。

【免费下载链接】nocodb🔥 🔥 🔥 A Free & Self-hostable Airtable Alternative项目地址: https://gitcode.com/GitHub_Trending/no/nocodb