外部存储
提示
功能可用性
外部存储适用于:
- Self-hosted: Business、Enterprise
n8n Cloud 不支持此功能。
n8n 可以在外部存储工作流执行产生的二进制数据和执行数据。此功能有助于避免依赖数据库或文件系统来存储大量数据。
在 S3 中存储 n8n 的二进制数据
n8n 支持 AWS S3{:target=_blank .external-link} 作为工作流执行产生的二进制数据的外部存储。您可以使用其他 S3 兼容服务,如 Cloudflare R2 和 Backblaze B2,但 n8n 不正式支持这些。
提示
功能可用性
S3 二进制数据存储适用于:
- Self-hosted: Business、Enterprise
n8n Cloud 不支持此功能。
启用外部存储前,请激活您的许可证密钥。没有有效许可证时,n8n 无法在 s3 二进制数据模式下启动:请将 N8N_DEFAULT_BINARY_DATA_MODE 设置为其他模式,或升级计划。
设置
按照 AWS 文档{:target=_blank .external-link}创建和配置存储桶。您可以使用以下策略,将 <bucket-name> 替换为您创建的存储桶名称:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": ["arn:aws:s3:::<bucket-name>", "arn:aws:s3:::<bucket-name>/*"]
}
]
}
设置存储桶级生命周期配置,以便 S3 自动删除旧的二进制数据。n8n 将二进制数据的清理委托给 S3,因此除非您想无限期保留二进制数据,否则需要设置生命周期配置。
如果该存储桶也保存执行数据,请在添加规则前阅读二进制数据与执行数据共享存储时的生命周期规则。
完成创建存储桶后,您将拥有主机、存储桶名称和区域,以及访问密钥 ID 和秘密访问密钥。您需要在 n8n 的环境中设置它们:
export N8N_EXTERNAL_STORAGE_S3_HOST=... # example: s3.us-east-1.amazonaws.com
export N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME=...
export N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION=...
export N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY=...
export N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET=...
提示
无区域
如果您的提供商不需要区域,您可以将 N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION 设置为 'auto'。
验证并更新 S3 存储桶区域格式(从 n8n 2.6.4 起)
从 n8n 2.6.4 起,环境变量 N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION 的值必须满足以下条件:
- 只能包含字母数字字符(
a-z、A-Z、0-9)和连字符(-)。 - 不能包含下划线(
_)或其他特殊字符。
如果不满足这些条件,即使存储端点可访问且之前在较旧版本中可以正常工作,n8n 也会因连接错误而启动失败。
如果将 n8n 升级到 2.6.4 后 S3 连接失败,请验证区域值是否符合这些条件,然后重新部署 n8n。
告诉 n8n 在 S3 中存储二进制数据:
export N8N_AVAILABLE_BINARY_DATA_MODES=filesystem,s3
export N8N_DEFAULT_BINARY_DATA_MODE=s3
提示
Auth autodetection 身份验证自动检测
要自动检测凭据以验证您的 S3 呼叫,请将 N8N_EXTERNAL_STORAGE_S3_AUTH_AUTO_DETECT 设置为 true。这将使用默认的凭据提供程序链。
重启服务器以加载新配置。
用法
启用 S3 后,n8n 将任何新的二进制数据写入和读取到 S3 存储桶。n8n 以此格式将二进制数据写入您的 S3 存储桶:
workflows/<workflow-id>/executions/<execution-id>/binary_data/<binary-file-id>
如果 filesystem 仍在 N8N_AVAILABLE_BINARY_DATA_MODES 中列为选项,n8n 继续从文件系统读取存储在文件系统中的较旧二进制数据。
如果您在 S3 中存储二进制数据,然后切换到文件系统模式,只要 s3 仍在 N8N_AVAILABLE_BINARY_DATA_MODES 中列出且您的 S3 凭据仍然有效,实例就会继续读取存储在 S3 中的任何数据。
提示
Binary data pruning 二进制数据修剪
二进制数据修剪在活动二进制数据模式下进行。例如,如果您的实例将数据存储在 S3 中,并且您后来切换到文件系统模式,则 n8n 仅修剪文件系统中的二进制数据。这将来可能会改变。
S3 存储升级最佳实践
使用 S3 或 S3 兼容存储时:
- 同时将所有 n8n 组件(main、worker、runner)升级到相同版本,以避免协议不兼容。
- 对于通过 HTTP 访问的本地部署或 S3 兼容存储,请设置
N8N_EXTERNAL_STORAGE_S3_PROTOCOL=http,并在 host 配置中包含协议。 - 仅使用受支持的环境变量名称:对于访问密钥,请使用
N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY。
较新的 n8n 版本具有更严格的验证和协议处理。升级后旧配置可能需要更新。
在 Azure Blob Storage 中存储 n8n 的二进制数据
n8n 支持 Azure Blob Storage 作为工作流执行产生的二进制数据的外部存储。它使用与外部执行数据存储相同的 Azure Blob 配置,因此一个容器可以同时存储二进制数据和执行数据。
提示
功能可用性
Azure Blob Storage 二进制数据存储适用于:
- Self-hosted: Business、Enterprise
n8n Cloud 不支持此功能。
启用外部存储前,请激活您的许可证密钥。没有有效许可证时,n8n 无法在 azure 二进制数据模式下启动:请将 N8N_DEFAULT_BINARY_DATA_MODE 设置为其他模式,或升级计划。
Azure 设置
按照 Azure 文档在 Azure 存储帐户中创建 blob 容器。
在 n8n 环境中设置容器名称。N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME 始终是必需的:
export N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME=...
对于身份验证,n8n 支持连接字符串、帐户名称和密钥,或托管身份(DefaultAzureCredential)。有关身份验证变量的完整列表以及 n8n 检查它们的顺序,请参阅外部数据存储环境变量 | Azure Blob Storage。
n8n 将二进制数据的清理委托给 Azure,因此请设置生命周期管理策略,以自动删除旧的二进制数据。除非您想无限期保留二进制数据,否则必须设置生命周期策略。该策略设置在存储账户上。没有 prefixMatch 的规则会应用于账户中的所有 blob,因此请为每条规则设置以容器名称开头的 prefixMatch,将其范围限定在您的容器内。
如果该容器也保存执行数据,请在添加策略前阅读二进制数据与执行数据共享存储时的生命周期规则。
告诉 n8n 将二进制数据存储在 Azure Blob Storage 中:
export N8N_AVAILABLE_BINARY_DATA_MODES=filesystem,azure
export N8N_DEFAULT_BINARY_DATA_MODE=azure
重启服务器以加载新配置。
Azure 用法
启用 Azure Blob Storage 后,n8n 会将新的二进制数据写入容器并从容器读取。n8n 以以下格式将二进制数据写入容器:
workflows/<workflow-id>/executions/<execution-id>/binary_data/<binary-file-id>
如果 filesystem 仍列在 N8N_AVAILABLE_BINARY_DATA_MODES 中,n8n 会继续从文件系统读取存储在其中的旧二进制数据。
如果您将二进制数据存储在 Azure Blob Storage 中,之后切换到文件系统模式,只要 azure 仍列在 N8N_AVAILABLE_BINARY_DATA_MODES 中且 Azure 凭据仍然有效,实例就会继续读取存储在 Azure 中的数据。
在 S3 中存储 n8n 的执行数据
n8n 也可以将执行数据存储在 S3 中。
按照二进制数据设置部分中的说明配置 S3 存储桶和凭据,然后告诉 n8n 将执行数据存储在 S3 中:
export N8N_EXECUTION_DATA_STORAGE_MODE=s3
在队列模式下,请在所有实例(包括 worker)上设置 N8N_EXECUTION_DATA_STORAGE_MODE 和 N8N_EXTERNAL_STORAGE_S3_* 变量。
警告
启动需要许可证
S3 执行数据存储需要 Business 或 Enterprise 计划及有效的许可证密钥。如果设置 N8N_EXECUTION_DATA_STORAGE_MODE=s3 时没有有效许可证,n8n 将无法启动。要重新启动 n8n,请将模式切换回 database 或 filesystem,或恢复有效许可证。
启用 S3 执行数据存储后,n8n 会将每次新执行的数据以以下格式写入 S3 存储桶:
workflows/<workflow-id>/executions/<execution-id>/execution_data/bundle.json
n8n 会记录每次执行数据的存储位置,因此切换模式不会破坏数据。旧执行仍可从数据库或文件系统读取;如果之后切换回其他模式,只要存储桶仍配置正确,存储在 S3 中的执行仍可读取。
n8n 会自行清理 S3 中的执行数据,使用标准的执行清理设置(EXECUTIONS_DATA_* 变量)。与二进制数据不同,执行数据不依赖 S3 生命周期规则。请勿为执行数据添加生命周期规则,否则可能会删除 n8n 仍在引用的数据。
如果使用 terraform-aws-n8n 模块在 AWS 上部署 n8n,请参阅在 AWS 上配置 Enterprise 功能。
要让同时保存执行数据的存储桶中的二进制数据过期,请阅读二进制数据与执行数据共享存储时的生命周期规则。
二进制数据与执行数据共享存储时的生命周期规则
当您将二进制数据和执行数据存储在同一个提供商中时,它们会共享同一个 S3 存储桶(N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME)或 Azure 容器(N8N_EXTERNAL_STORAGE_AZURE_CONTAINER_NAME)。对于每次执行,这两类数据位于同一前缀下:
workflows/<workflow-id>/executions/<execution-id>/binary_data/<binary-file-id>
workflows/<workflow-id>/executions/<execution-id>/execution_data/bundle.json
S3 键前缀过滤器和 Azure prefixMatch 过滤器都从对象名称的开头进行匹配。在 Azure 上,前缀还要以容器名称开头。没有任何一个前缀能覆盖所有二进制数据而不同时覆盖执行数据,而且 n8n 不会按数据类型为对象打标签。因此,作用于整个存储桶或容器的生命周期规则可能会让两类数据都过期。
执行数据保留在数据库或文件系统中时让二进制数据过期
如果执行数据保留在数据库或文件系统中,n8n 不会向存储桶或容器写入新的执行数据。此时,范围限定为 workflows/ 前缀的生命周期规则可以让来自执行的二进制数据过期:
- S3: 将规则的前缀过滤器设置为
workflows/。 - Azure: 将
prefixMatch设置为<container-name>/workflows/。如果没有prefixMatch,规则会应用于存储账户中的所有 blob,而不仅仅是该容器。
这种方法有以下限制:
- 存储桶或容器中仍可能保存着之前配置留下的执行数据。切换
N8N_EXECUTION_DATA_STORAGE_MODE不会迁移现有的执行数据。生命周期规则可能会删除 n8n 仍在引用的数据,因此添加规则前请检查是否存在execution_data/对象。 - 生命周期规则使用对象时间戳,而不是执行完成时间。n8n 从执行结束时开始计算执行的存留时间,而二进制数据可能更早写入。将过期时间设置为与
EXECUTIONS_DATA_MAX_AGE一致,并不能保证 n8n 保留的每次执行的二进制数据都可用。更短的过期时间可能会删除 n8n 仍保留的执行的二进制数据。 - 执行清理会跳过带注释的执行,以及状态为
new、running或waiting的执行。这些执行在 n8n 中保留的时间可能超过任何过期时间,并会在规则使其过期时丢失二进制数据。 - 并非所有二进制数据都来自执行。n8n 会将 Chat Hub 和 agent 的附件存储在同一个存储桶或容器中,分别位于
chat-hub/和agents/前缀下。这些文件与执行的存留时间无关,并且 n8n 仍在引用它们。作用于整个存储桶或容器的规则也会让它们过期,因此请将规则范围限定为workflows/。
执行数据也存储在对象存储中时让二进制数据过期
如果您将 N8N_EXECUTION_DATA_STORAGE_MODE 设置为 s3 或 azure,并且将二进制数据存储在同一个提供商中,n8n 不提供只让二进制数据过期的生命周期配置。不要添加让存储桶或容器中当前对象过期的生命周期规则,因为它也会让 n8n 仍在引用的执行数据过期。
将执行数据保留在数据库中,可以避免执行数据包与二进制数据存放在一起。
对象版本控制与生命周期规则
启用版本控制后,过期的对象或 n8n 删除的对象会作为旧版本保留下来,您需要继续为其存储付费。清理旧版本与让当前对象过期是两件独立的事:
- S3: n8n 删除对象时不带版本 ID,这会在启用版本控制的存储桶中添加删除标记。请添加
NoncurrentVersionExpiration规则来移除旧版本。请参阅 S3 生命周期配置元素。 - Azure: blob 版本控制是存储账户级别的设置,生命周期策略会应用于整个存储账户。请为以前的版本添加操作,并使用以容器名称加斜杠开头的
prefixMatch(例如<container-name>/)限定规则范围。请参阅 Azure 生命周期策略结构。