使用 Docker Compose 安装
适用对象
本指南介绍如何手动构建 Docker Compose 设置,包括为 n8n Assistant 提供支持的沙箱堆栈。如果您希望完全控制配置,或需要将 n8n 集成到现有 Compose 项目中,请使用本指南。
此设置中的沙箱仅用于开发和测试,不适用于生产环境。有关生产环境的沙箱方案,请参阅设置 n8n Assistant。
如果您只想快速运行 n8n(和 n8n Assistant),不想自行编写文件,请使用一行设置。它会自动完成下述设置。
开始前的准备
- Docker Engine 和 Docker Compose v2。运行
docker compose version检查版本。 - 至少 4 GB RAM 和 2 个 vCPU。运行 AI 生成代码的沙箱(
sandbox-runner-1)使用 Docker-in-Docker,比典型容器需要更多资源。
警告
sandbox-runner-1 以 privileged: true 和 Docker-in-Docker 方式运行,隔离性较弱:逃逸出沙箱的代码会触及宿主机。请在没有运行其他任何服务的专用主机或虚拟机上运行此设置。
提示
Windows 用户: 使用 WSL,并在 Linux 发行版中安装 Docker Desktop(WSL2 后端)或 Docker Engine。将项目文件夹保存在 WSL 文件系统中(例如 ~/n8n),不要放在 /mnt/c/... 下。跨越该边界的绑定挂载速度很慢,还可能导致权限问题。
第 1 步:创建项目文件夹
mkdir n8n && cd n8n
第 2 步:创建 .env
此文件保存要运行的版本,以及沙箱服务相互通信所需的 secret。请创建名为 .env 的文件,用你自己的值替换占位符,并将该文件排除在版本控制之外。
# n8n version - get the version number of the latest stable release from https://github.com/n8n-io/n8n/releases
N8N_VERSION=change-me-version-number
# Sandbox service version - the API, runner, and sandbox images share one release.
# Get the number of the latest stable "service" release (not a staging prerelease) from https://github.com/n8n-io/n8n-sandbox-service/releases
N8N_SANDBOX_VERSION=change-me-sandbox-version-number
# n8n task runner authentication. Use a random secret you generate.
N8N_RUNNERS_AUTH_TOKEN=change-me-runner-auth-token
# Sandbox service secrets — pick your own values
SANDBOX_API_KEYS=change-me-api-key
SANDBOX_RUNNER_REGISTRATION_TOKEN=change-me-registration-token
SANDBOX_RUNNER_API_KEYS=change-me-runner-key
# Must match a value in SANDBOX_API_KEYS above — this is how n8n authenticates to the sandbox
N8N_SANDBOX_SERVICE_API_KEY=change-me-api-key
# Web search: secret for the bundled SearXNG instance — pick your own value
SEARXNG_SECRET=change-me-searxng-secret
N8N_INSTANCE_AI_SEARXNG_URL=http://searxng:8080
暂时不需要 AI provider key;所有服务运行后,请参阅下方的打开 n8n Assistant。
第 3 步:创建 searxng-settings.yml
SearXNG 默认镜像只提供 HTML;n8n 的网络搜索需要 JSON API,此文件会启用该 API。
use_default_settings: true
search:
formats:
- html
- json
第 4 步:创建 compose.yml
此文件定义要设置的所有服务:n8n 本身、让 n8n Assistant 安全运行代码的沙箱堆栈,以及用于网络搜索的 SearXNG。
# n8n stack definition for get-n8n.sh (https://get.n8n.io).
# Downloaded at install time; the copy in your install directory is yours to
# edit. On --upgrade the script only repoints the sandbox image tags below at
# N8N_SANDBOX_VERSION. To review changes between versions:
# https://github.com/n8n-io/n8n/commits/master/docker/get-n8n-compose.yml
# compose-version: 2
# The sandbox service API, runner and sandbox images ship as one release and
# are only supported together, so a single N8N_SANDBOX_VERSION (from .env)
# pins all three.
volumes:
n8n-data:
sandbox-tls:
services:
sandbox-certs:
image: ghcr.io/n8n-io/n8n-sandbox-service-api:${N8N_SANDBOX_VERSION}
user: '0:0'
entrypoint: ['sh', '-c']
command:
- >
bootstrap-mtls.sh --out-dir /tls --api-san sandbox-api
--control-san-prefix sandbox-runner --world-readable &&
chown -R sandbox-api:sandbox-api /tls/api && chmod -R a+rX /tls
environment:
NUM_RUNNERS: '1'
volumes:
- sandbox-tls:/tls
sandbox-api:
image: ghcr.io/n8n-io/n8n-sandbox-service-api:${N8N_SANDBOX_VERSION}
depends_on:
sandbox-certs:
condition: service_completed_successfully
env_file: .env
environment:
SANDBOX_API_GRPC_TLS_CERT_FILE: /tls/api/grpc-server.crt
SANDBOX_API_GRPC_TLS_KEY_FILE: /tls/api/grpc-server.key
SANDBOX_API_GRPC_TLS_CLIENT_CA_FILE: /tls/api/ca.crt
SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CA_FILE: /tls/api/ca.crt
SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CERT_FILE: /tls/api/control-grpc-api-client.crt
SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_KEY_FILE: /tls/api/control-grpc-api-client.key
SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_SERVER_NAME: sandbox-runner-1
volumes:
- sandbox-tls:/tls:ro
healthcheck:
test: ['CMD', 'wget', '-qO-', 'http://localhost:8080/healthz']
interval: 5s
timeout: 3s
retries: 5
start_period: 10s
# Never publish 8080/9090 to the host on an internet-facing server.
# n8n reaches this container by service name, over the default Compose network.
sandbox-runner-1:
image: ghcr.io/n8n-io/n8n-sandbox-service-runner-dind:${N8N_SANDBOX_VERSION}
privileged: true
depends_on:
sandbox-api:
condition: service_healthy
env_file: .env
environment:
SANDBOX_RUNNER_API_GRPC_ADDR: sandbox-api:9090
SANDBOX_RUNNER_HTTP_BASE_URL: https://sandbox-runner-1:8080
SANDBOX_RUNNER_CONTROL_GRPC_LISTEN_ADDR: ':9091'
SANDBOX_RUNNER_CONTROL_GRPC_ADVERTISE_ADDR: sandbox-runner-1:9091
SANDBOX_RUNNER_ID: runner-1
SANDBOX_RUNNER_DOCKER_SANDBOX_IMAGE: ghcr.io/n8n-io/n8n-sandbox-service-sandbox:${N8N_SANDBOX_VERSION}
SANDBOX_RUNNER_REGISTRATION_GRPC_CA_FILE: /tls/runner/ca.crt
SANDBOX_RUNNER_REGISTRATION_GRPC_CERT_FILE: /tls/runner/grpc-client.crt
SANDBOX_RUNNER_REGISTRATION_GRPC_KEY_FILE: /tls/runner/grpc-client.key
SANDBOX_RUNNER_REGISTRATION_GRPC_SERVER_NAME: sandbox-api
SANDBOX_RUNNER_CONTROL_GRPC_TLS_CERT_FILE: /tls/runner/control-grpc-server.crt
SANDBOX_RUNNER_CONTROL_GRPC_TLS_KEY_FILE: /tls/runner/control-grpc-server.key
SANDBOX_RUNNER_CONTROL_GRPC_TLS_CLIENT_CA_FILE: /tls/runner/ca.crt
volumes:
- sandbox-tls:/tls:ro
# Never expose this container's ports publicly — it runs privileged Docker-in-Docker.
n8n:
image: docker.io/n8nio/n8n:${N8N_VERSION}
depends_on:
sandbox-api:
condition: service_healthy
ports:
- '5678:5678' # the only port that should be internet-facing
env_file: .env
volumes:
- n8n-data:/home/node/.n8n
runners:
image: ghcr.io/n8n-io/runners:${N8N_VERSION}
depends_on:
- n8n
environment:
N8N_RUNNERS_AUTH_TOKEN: ${N8N_RUNNERS_AUTH_TOKEN}
N8N_RUNNERS_TASK_BROKER_URI: http://n8n:5679
# Idle runners exit and are relaunched on demand (per the task-runners docs)
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT: '15'
# Runs user code from Code nodes. Never publish this container's ports.
searxng:
image: ghcr.io/searxng/searxng:latest
environment:
SEARXNG_SECRET: ${SEARXNG_SECRET}
volumes:
- ./searxng-settings.yml:/etc/searxng/settings.yml:ro
# Internal-only: n8n reaches it by service name. Never publish its port.
刚刚设置的内容
| 组件 | 这是做什么用的 |
|---|---|
| n8n | 工作流编辑器本身,可通过 http://localhost:5678 访问。 |
| sandbox-certs | 运行一次,生成其他沙箱服务所需的 TLS 证书,然后退出。 |
| sandbox-api | n8n Assistant 需要运行代码时,n8n 与其通信的控制平面。 |
| sandbox-runner-1 | 执行实际工作;创建并运行沙箱的特权 Docker-in-Docker 容器。 |
| searxng | n8n Assistant 使用的捆绑式网络搜索后端。 |
此配置捆绑 n8n 自带的沙箱(n8n-sandbox),仅适用于开发和测试。它的 runner 是特权容器,因此隔离性较弱。对于生产实例,n8n 建议使用带 Sysbox runner 的 n8n 沙箱服务,最好运行在 Kubernetes 上。如果可以接受由第三方处理你的工作流数据,Daytona 是一个托管替代方案。请参阅设置 n8n Assistant 了解各方案的配置方法。
此处未定义数据库服务。n8n 会回退到内置 SQLite 数据库。get-n8n-compose.yml 中的 n8n-data 卷会存储数据库和 n8n 的加密密钥,因此重启或重新创建容器后数据仍然保留。生产实例请改用 Postgres。请参阅下方的使用 PostgreSQL 代替 SQLite。
第 5 步:启动所有服务
docker compose up -d
docker compose ps
等待 sandbox-api 显示 healthy;随后 sandbox-runner-1 和 n8n 会自动启动。
第 6 步:验证是否正常工作
# sandbox-api is reachable from n8n
docker compose exec n8n wget -qO- http://sandbox-api:8080/healthz
# the runner registered itself with the API
docker compose logs sandbox-api | grep -i runner
# n8n is up
curl -sf http://localhost:5678/healthz
在浏览器中打开 http://localhost:5678,启动 n8n 的设置流程。
可选:打开 n8n Assistant
上面的配置会运行完整沙箱堆栈,但 n8n Assistant 本身会保持关闭,直到指定要使用的模型。n8n 运行后,可以在 n8n UI 的实例 AI 设置中完成配置;如果希望首次登录前就配置,也可以编辑 .env:
- 将 AI provider key 添加到
.env:
N8N_INSTANCE_AI_MODEL_API_KEY=sk-ant-xxx
- 重启 n8n 使设置生效:
bash
docker compose up -d n8n
默认情况下,网络搜索通过捆绑的 SearXNG 服务运行。如果更愿意使用 Brave Search,可以在 UI 中设置,或将 Brave API key 添加到 .env;设置后 Brave 的优先级高于 SearXNG:
INSTANCE_AI_BRAVE_SEARCH_API_KEY=BSA-xxx
完整设置步骤(包括支持的 model provider)请参阅设置 n8n Assistant。
可选:使用 PostgreSQL 代替 SQLite
SQLite 适合试用;对于需要处理多用户或全天候运行工作流的生产实例,请使用 Postgres。
- 将 Postgres 凭据与沙箱 secret 一起添加到
.env:
POSTGRES_USER=change-me-user
POSTGRES_PASSWORD=change-me-password
POSTGRES_DB=n8n
- 将
postgres服务添加到compose.yml及其数据卷:
```yaml volumes: db-storage:
services: postgres: image: postgres:18 restart: always environment: POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: ${POSTGRES_DB} PGDATA: /var/lib/postgresql/data volumes: - db-storage:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -h localhost -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] interval: 5s timeout: 5s retries: 10 ```
警告
PostgreSQL 18 更改了默认的数据存储位置。设置
PGDATA可让数据继续存储在与旧版本相同的文件夹中,从而保持卷挂载不变。请勿删除这一行:否则 PostgreSQL 18 会将数据写入卷未覆盖的位置,数据库启动后将显示为空。警告
已经在运行旧版 PostgreSQL?直接迁移到 18 属于主版本升级,PostgreSQL 无法打开由旧主版本写入的数据目录。只更新现有设置的镜像标签会产生
database files are incompatible with server错误,但数据仍然完好。请先使用pg_dumpall备份,再按照官方 PostgreSQL 升级指南操作。
- 将以下内容添加到 n8n 服务的 environment 块,并让 n8n 等待 Postgres:
yaml
environment:
# ...your existing N8N_ENABLED_MODULES, N8N_INSTANCE_AI_* settings stay as they are
DB_TYPE: postgresdb
DB_POSTGRESDB_HOST: postgres
DB_POSTGRESDB_PORT: '5432'
DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
DB_POSTGRESDB_USER: ${POSTGRES_USER}
DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
depends_on:
sandbox-api:
condition: service_healthy
postgres:
condition: service_healthy
- 重新启动一切:
bash
docker compose up -d
n8n 启动时会迁移到新的 Postgres 数据库。现有 SQLite 数据不会自动迁移;此流程适用于新实例,而非就地迁移。
提示
如需更安全的设置(例如专用的非 root Postgres 用户和外部任务运行程序),请参阅 n8n 托管仓库中的
withPostgres示例。
故障排除
| 症状 | 可能的原因 |
|---|---|
sandbox-api 或 sandbox-runner-1 无法启动并出现证书错误 |
sandbox-certs 未完成。检查 docker compose logs sandbox-certs。 |
sandbox-api 始终不是 healthy |
检查日志,并确认镜像中确实有 wget。 |
sandbox-runner-1 启动时崩溃循环并出现 ... must be set 错误 |
缺少必需环境变量,最常见的是 SANDBOX_RUNNER_API_KEYS 或 SANDBOX_RUNNER_REGISTRATION_TOKEN。运行 strings /usr/local/bin/sandbox-runner \| grep -oE 'SANDBOX_[A-Z_]+ must be set' 获取完整列表。 |
| runner 从未在 API 上注册 | SANDBOX_RUNNER_REGISTRATION_TOKEN 不匹配,或 SANDBOX_RUNNER_API_GRPC_ADDR 错误。 |
| n8n 的沙箱调用失败 | .env 中的沙箱 URL/密钥与 sandbox-api 地址或 SANDBOX_API_KEYS 不匹配。 |
| Linux 上正常、WSL 上失败 | 通常是绑定挂载路径问题;将项目放在 WSL 文件系统中,而不是 /mnt/c/...。 |
安全检查表
sandbox-runner-1(privileged: true、Docker-in-Docker)绝不能暴露到公共互联网,应将其视为主机上的 root。- 与 Compose 堆栈相同的主机或虚拟机上不运行任何其他服务。如果代码逃逸出沙箱,就能触及该主机上的所有内容。
- 此设置不是你的生产沙箱。生产环境请使用带 Sysbox runner 的 n8n 沙箱服务,最好运行在 Kubernetes 上。如果可以接受由第三方处理你的工作流数据,Daytona 是一个托管替代方案。请参阅设置 n8n Assistant。
- 云防火墙只开放 n8n 端口。
SANDBOX_API_KEYS、注册令牌和 runner key 都是唯一值,不保留change-me-...占位符,并定期轮换。sandbox-api和sandbox-runner-1不使用env_file: .env。每个服务只在environment块中接收明确需要的变量。API key、Brave key、Postgres 密码和 n8n 加密密钥不会传入沙箱容器。sandbox-tls卷中的 mTLS key(包括 root CA key)权限锁定为0600,且仅由需要它们的服务持有(sandbox-api持有自身 key;root 持有 runner 和 CA key)。这些 key 均不可被其他用户读取。- 计划重新生成
sandbox-tls卷。sandbox-certs生成的证书不会自动续期。
服务架构
flowchart LR
subgraph compose["docker-compose.yml (one project)"]
n8n["n8n"]
certs["sandbox-certs<br/>(runs once, then exits)"]
api["sandbox-api"]
runner["sandbox-runner-1<br/>(privileged, DinD)"]
sandboxes["sandbox containers<br/>(per execution)"]
certs -.->|TLS certs| api
certs -.->|TLS certs| runner
n8n -->|HTTP :8080| api
api -->|control gRPC| runner
runner --> sandboxes
end
classDef oneshot fill:#eee,stroke:#999,stroke-dasharray: 3 3;
class certs oneshot
n8n 向 sandbox-api 发送代码执行请求;该服务将请求交给 sandbox-runner-1,后者创建并运行实际的沙箱容器。sandbox-runner-1 是特权组件,在生产环境设置中,由 Kubernetes 上的 Sysbox runner 取代它。sandbox-certs 在启动时运行一次,生成另外两个服务所需的 TLS 证书后退出;其他服务都会等待它。