将 Grist 文档快照保存到带版本的对象存储

原作者／来源：Grist 官方帮助中心（原文无个人署名）。原文：Cloud Storage。本文为经授权的中文译稿；技术核验日期：2026-10-05。

云存储功能可以把 Grist 文档及其历史版本自动同步到兼容 S3 的存储系统，例如 RustFS，也可以同步到 AWS S3。Grist 完整版还原生支持 Azure 存储账户，以及通过 AWS 官方客户端访问 S3。

使用云存储时，建议启用 Redis，因为这是测试最充分的配置。启用快照会显著改变文档的存储方式，最好在创建文档之前完成；更改配置前，请先备份已有工作。

通过 MinIO 客户端连接 S3 兼容存储

设置以下环境变量即可启用：

旧版本把这组设置称为 GRIST_DOCS_MINIO_*，例如 GRIST_DOCS_MINIO_BUCKET；这些旧名称仍然有效。

如果使用 AWS S3，端点设为 s3.amazonaws.com，不需要指定端口或 SSL 标志。访问密钥和秘密密钥对应 AWS_ACCESS_KEY_ID 与 AWS_SECRET_ACCESS_KEY。务必提前创建启用版本控制的存储桶。

选择支持版本控制的 S3 兼容存储

Grist 把一份文档的历史保存为桶中同一个对象的不同版本。因此，存储桶必须开启版本控制，服务本身也必须支持这项能力。并不是所有 S3 兼容服务都支持；原文指出 Garage 和 Cloudflare R2 无法用于这里的 Grist 方案。Grist 启动时会检查桶的版本控制，未开启就报错并停止。

原文列出的已测试服务如下：

• AWS S3 本身。
• RustFS：开源 S3 服务器，Grist 的 Docker Compose 示例使用它。
• MinIO：其开源版本已不再维护。
• Silo：由社区维护的 MinIO 分支。原文说明，已有 MinIO 部署可以把镜像名 minio/minio 换为 pgsty/silo；它使用相同设置，并可直接读取现有 MinIO 数据。
• Versity Gateway：适合测试，把普通目录作为 S3 存储，因此每份文档的最新版本会以普通文件形式保存在磁盘上。启动时使用 --versioning-dir 才会同时保留旧版本；数据目录的文件系统必须支持扩展属性。原文撰写时它尚不支持生命周期规则，因此不能设置下文建议的旧版本清理规则。

无论选择哪种存储，都可以使用 AWS 命令行工具创建桶并启用版本控制。通过 AWS_ENDPOINT_URL 指向所选的 S3 兼容服务：

export AWS_ENDPOINT_URL=http://<host>:<port>
export AWS_ACCESS_KEY_ID=<access key>
export AWS_SECRET_ACCESS_KEY=<secret key>
export AWS_DEFAULT_REGION=us-east-1
aws s3api create-bucket --bucket grist-docs
aws s3api put-bucket-versioning --bucket grist-docs \
  --versioning-configuration Status=Enabled

Azure

1. 在 Azure 门户创建存储账户。
2. 为该账户的 Blob 服务启用版本控制。
3. 从 Access Keys 区域取得连接字符串，形式可能类似 DefaultEndpointsProtocol=https;AccountName=...。
4. 把连接字符串放入环境变量 AZURE_STORAGE_CONNECTION_STRING。
5. 在 GRIST_AZURE_CONTAINER 中设置存储容器名称，例如 my-grist-docs。
6. 在 GRIST_AZURE_PREFIX 中设置前缀，例如 v1/。

使用原生 AWS 客户端访问 S3

1. 把桶名设置到 GRIST_DOCS_S3_BUCKET，例如 my-grist-docs。
2. 通过 GRIST_DOCS_S3_PREFIX 设置前缀，例如 v1/。
3. 不要设置 GRIST_DOCS_S3_ENDPOINT；一旦设置，Grist 就会改用上文的 MinIO 客户端。
4. 通过 AWS 支持的凭据机制配置访问权限；最直接的方式之一是设置 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。

上述 Azure 和原生 AWS 客户端支持属于 Grist 完整版；S3 兼容客户端路径的选择不要与产品版本许可混淆。

配置后的验证与保留策略

完成外部存储配置后，按自托管 Grist 的正常方式启动。启动日志中应出现类似这一行：

info: == grist.externalStorage.[s3|azure|minio].active: true

所有文档都会从对应的 S3 桶或 Azure 容器读取，并保存回去。没有现有文档的全新 Grist 实例最容易配置。系统运行后，应在存储账户的生命周期管理中设定所需的历史版本保留期限。

原文建议每天清理前缀为 ${PREFIX}/assets/unversioned/ 的对象的非当前版本，例如 v1/assets/unversioned/。这条规则用于定期裁剪旧的快照元数据版本；不能不加区分地应用到整个桶。

文档快照的保留频度由以下环境变量控制：

• GRIST_SNAPSHOT_TIME_CAP：一个 JSON 字符串，指定每种时间单位要保留的窗口数。例如 {"hour": 24, "day": 30, "isoWeek": 52, "month": 24, "year": 5}，表示最近 24 小时中每小时保留该小时最新的一份、最近 30 天中每天保留该天最新的一份，其他周期依此类推。落在保留窗口外的旧备份，会在需要为新备份腾出空间时被删除。
• 未设置时，默认值为 {"hour": 25, "day": 32, "isoWeek": 12, "month": 96, "year": 1000}。

GRIST_SNAPSHOT_KEEP 则指定至少保留多少份最近的快照，不受 GRIST_SNAPSHOT_TIME_CAP 限制，默认是 5。

来源与权利说明：原页未明确列出本文独立的转载许可证；保留 Grist 官方来源，不从产品软件许可证推定文档许可。