数据库环境变量#

基于文件的配置

您可以在单个变量后添加 _FILE 以在单独的文件中提供其配置。有关更多详细信息，请参阅在单独文件中保存敏感数据。

默认情况下，n8n 使用 SQLite。n8n 也支持 PostgreSQL。n8n 在 v1.0 中移除了对 MySQL 和 MariaDB 的支持。

本页概述了为您的自托管 n8n 实例配置所选数据库的环境变量。

变量	类型	默认值	描述
`DB_TYPE` /`_FILE`	枚举字符串： `sqlite`、`postgresdb`	`sqlite`	要使用的数据库。
`DB_TABLE_PREFIX`	*	-	用于表名的前缀。
`DB_PING_INTERVAL_SECONDS`	数字	`2`	n8n ping 数据库以检查连接是否仍然活跃的间隔（秒）。
`DB_PING_TIMEOUT_MS`	数字	`5000`	n8n 等待单次 ping 响应的时间（毫秒），超时后将其计为失败。如果设置了已弃用的 `N8N_DB_PING_TIMEOUT`，则回退使用该值。
`DB_PING_MAX_FAILURES_BEFORE_RECOVERY`	数字	`3`	连续多少次 ping 失败后，n8n 才将连接视为断开并开始恢复。
`DB_RECOVERY_BACKOFF_MIN_MS`	数字	`1000`	n8n 首次尝试恢复前等待的时间（毫秒）。后续每次重试的等待时间都会增加（指数退避）。
`DB_RECOVERY_BACKOFF_MAX_MS`	数字	`30000`	恢复尝试之间的最长等待时间（毫秒），用于限制退避时间。必须大于或等于 `DB_RECOVERY_BACKOFF_MIN_MS`。
`DB_CONNECTION_ACQUISITION_TIMEOUT_MS`	数字	`30000`	恢复期间，查询等待连接恢复的时间（毫秒）；超时后会立即报错。设为 `0` 表示无限等待。仅适用于 PostgreSQL。

PostgreSQL#

变量	类型	默认值	描述
`DB_POSTGRESDB_DATABASE` /`_FILE`	字符串	`n8n`	PostgreSQL 数据库的名称。
`DB_POSTGRESDB_HOST` /`_FILE`	字符串	`localhost`	PostgreSQL 主机。
`DB_POSTGRESDB_PORT` /`_FILE`	数字	`5432`	PostgreSQL 端口。
`DB_POSTGRESDB_USER` /`_FILE`	字符串	`postgres`	PostgreSQL 用户。
`DB_POSTGRESDB_PASSWORD` /`_FILE`	字符串	-	PostgreSQL 密码。
`DB_POSTGRESDB_POOL_SIZE` /`_FILE`	数字	`2`	控制 n8n 应并行打开多少个 Postgres 连接。增加连接数可能有助于提高资源利用率，但连接过多可能会降低性能。
`DB_POSTGRESDB_CONNECTION_TIMEOUT` /`_FILE`	数字	`20000`	Postgres 连接超时时间（毫秒）。
`DB_POSTGRESDB_IDLE_CONNECTION_TIMEOUT` /`_FILE`	数字	`30000`	空闲连接因持续空闲而可以被逐出的等待时间。
`DB_POSTGRESDB_MAX_CONNECTION_LIFETIME_MS` /`_FILE`	数字	`3600000`	n8n 回收连接池连接前保留该连接的时间（毫秒）。回收旧连接有助于避免数据库或网络已断开但 n8n 未发现的失效连接。默认为一小时。设为 `0` 可禁用回收。
`DB_POSTGRESDB_KEEP_ALIVE` /`_FILE`	布尔值	`true`	是否为连接启用 TCP keep-alive。keep-alive 让 n8n 无需先运行查询即可发现失效连接。
`DB_POSTGRESDB_KEEP_ALIVE_INITIAL_DELAY_MS` /`_FILE`	数字	`10000`	n8n 在连接上发送第一个 TCP keep-alive 探测前的等待时间（毫秒）。
`DB_POSTGRESDB_SCHEMA` /`_FILE`	字符串	`public`	PostgreSQL schema。
`DB_POSTGRESDB_SSL_ENABLED` /`_FILE`	布尔值	`false`	是否启用 SSL。如果定义了 `DB_POSTGRESDB_SSL_CA`、`DB_POSTGRESDB_SSL_CERT` 或 `DB_POSTGRESDB_SSL_KEY`，则自动启用。
`DB_POSTGRESDB_SSL_CA` /`_FILE`	字符串	-	PostgreSQL SSL 证书颁发机构。
`DB_POSTGRESDB_SSL_CERT` /`_FILE`	字符串	-	PostgreSQL SSL 证书。
`DB_POSTGRESDB_SSL_KEY` /`_FILE`	字符串	-	PostgreSQL SSL 密钥。
`DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED` /`_FILE`	布尔值	`true`	n8n 是否应拒绝未经授权的 SSL 连接。

SQLite#

变量	类型	默认值	描述
`DB_SQLITE_POOL_SIZE`	数字	`0`	控制以 WAL 模式还是回滚日志模式打开 SQLite 文件。设为零时使用回滚日志模式；大于零时使用 WAL 模式，该值决定要配置的并行 SQL 读取连接数。WAL 模式的性能和可靠性远高于回滚日志模式。
`DB_SQLITE_VACUUM_ON_STARTUP`	布尔值	`false`	启动时运行 VACUUM 操作以重建数据库，减小文件大小并优化索引。这是一项长时间运行的阻塞操作，会增加启动时间。

数据库连接恢复的工作原理#

n8n 会持续检查能否连接数据库。如果连接中断（例如数据库重启或网络短暂故障后），n8n 可以自行修复连接，而不必等到您重启 n8n。

本页变量控制的循环如下：

每隔 DB_PING_INTERVAL_SECONDS，n8n 发送一次 ping。每次 ping 必须在 DB_PING_TIMEOUT_MS 内响应。
连续失败的 ping 达到 DB_PING_MAX_FAILURES_BEFORE_RECOVERY 次后，n8n 会将连接视为已断开。
n8n 随后重建连接，并在重试之间逐渐增加等待时间；等待时间从 DB_RECOVERY_BACKOFF_MIN_MS 开始，且不会超过 DB_RECOVERY_BACKOFF_MAX_MS。
对于 PostgreSQL，恢复期间的任何新查询最多等待 DB_CONNECTION_ACQUISITION_TIMEOUT_MS 以恢复连接；超过该时间后会报错，而不是一直挂起。

适用于所有数据库

健康检查和恢复循环（DB_PING_* 与 DB_RECOVERY_BACKOFF_* 变量）适用于所有数据库类型。其余设置（DB_CONNECTION_ACQUISITION_TIMEOUT_MS、DB_POSTGRESDB_MAX_CONNECTION_LIFETIME_MS、DB_POSTGRESDB_KEEP_ALIVE 和 DB_POSTGRESDB_KEEP_ALIVE_INITIAL_DELAY_MS）仅适用于 PostgreSQL。默认值适合大多数部署，除非遇到连接问题，否则无需更改。