n8n 中文文档

使用 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:

  1. 将 AI provider key 添加到 .env:

N8N_INSTANCE_AI_MODEL_API_KEY=sk-ant-xxx

  1. 重启 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。

  1. 将 Postgres 凭据与沙箱 secret 一起添加到 .env:

POSTGRES_USER=change-me-user POSTGRES_PASSWORD=change-me-password POSTGRES_DB=n8n

  1. 将 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 升级指南操作。

  1. 将以下内容添加到 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

  1. 重新启动一切:

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 证书后退出;其他服务都会等待它。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。