n8n 中文文档

在 Hetzner 云 上托管 n8n

本托管指南介绍如何在 Hetzner Cloud 服务器上自托管 n8n。它使用:

  • Caddy{:target="_blank" .external-link}(反向代理)允许从互联网访问服务器。
  • Docker Compose{:target="_blank" .external-link} 创建和定义应用组件,以及它们如何协同工作。

n8n 启动并运行后,可选的最后一部分将介绍添加 n8n Assistant。

提示

Self-hosting knowledge prerequisites 自托管知识先决条件

自托管 n8n 需要技术知识,包括:

  • 设置和配置服务器和容器
  • 管理应用程序资源和扩展
  • 保护服务器和应用程序
  • 配置 n8n

n8n 建议专家用户使用自托管。错误可能会导致数据丢失、安全问题和停机。如果您没有管理服务器的经验,n8n 推荐 n8n Cloud。

提示

稳定版和测试版

n8n 每周都会发布新的次要版本。 stable 版本用于生产用途。 beta 是最新版本。 beta版本可能不稳定。要报告问题,请使用 论坛。

当前 stable:2.47.7 当前 beta:2.48.4

创建服务器

  1. 登录{:target=_blank .external-link} Hetzner Cloud 控制台。
  2. 选择要托管服务器的项目,或通过选择 + NEW PROJECT 创建新项目。
  3. 在要添加服务器的项目磁贴上选择 + CREATE SERVER。

您可以根据需要更改大多数设置。由于本指南使用 Docker 运行应用,请在 Image 部分的 APPS 选项卡中选择 Docker CE。

提示

Type 类型

创建服务器时,Hetzner 会要求您选择 plan。大多数使用场景选择 CPX11 即可。如果计划添加 n8n Assistant,请选择至少 4 GB RAM 和 2 个 vCPU 的 plan;添加沙箱后,CPX11 的资源余量不足。

提示

SSH keys SSH 密钥

Hetzner 允许您选择 SSH 或密码身份验证。SSH 更安全;本指南后续步骤假定您使用 SSH。

登录服务器

本指南的其余部分要求您使用支持 SSH 的终端登录服务器。有关更多信息,请参阅通过 SSH/rsync/BorgBackup 访问。您可以在项目的服务器列表中找到公网 IP 地址。

安装 Docker Compose

Hetzner Docker 应用镜像未安装 Docker Compose。请运行以下命令安装:

apt update && apt -y upgrade
apt install docker-compose-plugin

克隆配置存储库

Docker Compose、n8n 和 Caddy 需要一系列文件夹和配置文件。您可以从此存储库{:target=_blank .external-link}将这些文件克隆到服务器的 root 用户文件夹。以下步骤说明要更改哪些文件以及如何更改。

使用以下命令克隆存储库:

git clone https://github.com/n8n-io/n8n-docker-caddy.git

并切换到您克隆的存储库的根目录:

cd n8n-docker-caddy

默认文件夹和文件

主机操作系统(服务器)将您创建的两个文件夹挂载到 Docker 容器中,使其可供 Docker 使用。这两个文件夹是:

  • caddy_config:保存 Caddy 配置文件。
  • local_files:保存通过 n8n 上传或添加的文件。

创建 Docker 卷

为了在重启后保留 Caddy 缓存并缩短启动时间,请创建一个可供 Docker 重复使用的 Docker 卷{:target="_blank" .external-link}:

docker volume create caddy_data

为 n8n 数据创建 Docker 卷:

sudo docker volume create n8n_data

设置 DNS

n8n 通常在子域上运行。请通过 DNS 提供商为该子域创建 DNS 记录,并将其指向服务器的 IP 地址。具体步骤取决于 DNS 提供商,但通常需要为 n8n 子域创建一条新的 A 记录。DigitalOcean 提供了DNS 术语、组件和概念介绍{:target="_blank" .external-link}。

开放端口

n8n 作为 Web 应用运行,因此服务器需要允许端口 80 的非加密入站流量和端口 443 的加密入站流量。

通过运行以下两个命令在服务器的防火墙中打开以下端口:

sudo ufw allow 80
sudo ufw allow 443

提示

如果您稍后添加 n8n Assistant,其沙箱服务会保留在 Compose 网络内部。您无需为它们开放其他端口。

配置 n8n

n8n 需要将一些环境变量传递给 Docker 容器中运行的应用。示例 .env 文件包含占位符,您需要将其替换为自己的值。

使用以下命令打开文件:

nano .env

该文件包含内联注释,帮助您了解要更改的内容。

有关 n8n 环境变量的详细信息,请参阅环境变量。

Docker Compose 文件

Docker Compose 文件(docker-compose.yml)定义应用所需的服务,本例中为 Caddy 和 n8n。这里没有单独的数据库服务;n8n 默认使用内置 SQLite 数据库。

  • Caddy 服务定义其使用的端口和要挂载到容器的本地卷。
  • n8n 服务定义其使用的端口、运行 n8n 所需的环境变量(部分在 .env 文件中定义),以及要挂载到容器的卷。

Docker Compose 文件使用在 .env 文件中设置的环境变量,您不需要更改其内容,但要查看,请运行以下命令:

nano docker-compose.yml

配置 Caddy

Caddy 需要知道它应该提供哪些域,以及向外部世界公开哪个端口。编辑 caddy_config 文件夹中的 Caddyfile 文件。

nano caddy_config/Caddyfile

将占位符子域名改为您的子域名。如果按照步骤将子域命名为 n8n,则完整域名类似 n8n.example.com。reverse_proxy 设置中的 n8n 告诉 Caddy 使用 docker-compose.yml 中定义的服务:

n8n.<domain>.<suffix> {
    reverse_proxy n8n:5678 {
      flush_interval -1
    }
}

启动 Docker Compose

使用以下命令启动 n8n 和 Caddy:

docker compose up -d

这可能需要几分钟。

测试设置

在浏览器中,打开由之前定义的子域和域名组成的 URL。输入之前设置的用户名和密码,即可访问 n8n。

停止 n8n 和 Caddy

您可以使用以下命令停止 n8n 和 Caddy:

sudo docker compose stop

可选:添加 n8n Assistant

n8n Assistant 需要沙箱来运行代码。您可以将 Docker Compose 指南 中使用的同一沙箱堆栈添加到此设置中。开始前请注意:

  • 此沙箱仅适用于开发和测试。下面的堆栈使用 n8n 自带的沙箱(n8n-sandbox),其 runner 以 privileged: true 运行,隔离性较弱。带公共域名的 Hetzner 服务器通常用于实际部署,因此不要将此堆栈用于生产环境,也不要在该服务器上运行其他任何服务。如果你需要在单台 Linux 虚拟机上使用隔离性更强的沙箱,请在虚拟机上安装 Sysbox,并按照其步骤改用 Sysbox 而不是 privileged: true 来运行 runner。本指南中的 Compose 文件不包含这些更改。其他生产环境方案请参阅设置 n8n Assistant。
  • 根据需要调整规格。 sandbox runner 使用 Docker-in-Docker,比单独运行 n8n 需要更多资源。请至少配置 4 GB RAM 和 2 个 vCPU。
  • 无需更改网络。 Caddy 只代理 n8n 本身;沙箱服务保留在 Compose 网络内部,不需要更改 DNS、防火墙或 Caddyfile。
  1. 将沙箱 secret 与现有变量一起添加到 .env:

``` # Sandbox service secrets — pick your own values SANDBOX_API_KEYS=change-me-api-key SANDBOX_API_RUNNER_REGISTRATION_TOKEN=change-me-registration-token SANDBOX_API_RUNNER_API_KEY=change-me-runner-key

# Web search: secret for the bundled SearXNG instance — pick your own value SEARXNG_SECRET=change-me-searxng-secret ```

  1. 在其他配置文件旁创建 searxng-settings.yml(SearXNG 默认镜像只提供 HTML;此文件会启用 n8n 网络搜索所需的 JSON API):

yaml use_default_settings: true search: formats: - html - json

  1. 打开 docker-compose.yml 并在现有 caddy 和 n8n 服务旁边添加沙箱和搜索服务:

```yaml volumes: sandbox-tls:

services: sandbox-certs: image: ghcr.io/n8n-io/n8n-sandbox-service-api:latest user: '0:0' entrypoint: ['sh', '-c'] command: - > bootstrap-mtls.sh --out-dir /tls --api-san sandbox-api --control-san-prefix sandbox-runner && chown -R sandbox-api:sandbox-api /tls/api environment: NUM_RUNNERS: '1' volumes: - sandbox-tls:/tls

 sandbox-api:
   image: ghcr.io/n8n-io/n8n-sandbox-service-api:latest
   depends_on:
     sandbox-certs:
       condition: service_completed_successfully
   environment:
     SANDBOX_API_KEYS: ${SANDBOX_API_KEYS}
     SANDBOX_API_RUNNER_REGISTRATION_TOKEN: ${SANDBOX_API_RUNNER_REGISTRATION_TOKEN}
     SANDBOX_API_RUNNER_API_KEY: ${SANDBOX_API_RUNNER_API_KEY}
     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 — Caddy never routes to this service, and it shouldn't.

 sandbox-runner-1:
   image: ghcr.io/n8n-io/n8n-sandbox-service-runner-dind:latest
   privileged: true
   depends_on:
     sandbox-api:
       condition: service_healthy
   environment:
     SANDBOX_RUNNER_API_KEYS: ${SANDBOX_API_RUNNER_API_KEY}
     SANDBOX_RUNNER_REGISTRATION_TOKEN: ${SANDBOX_API_RUNNER_REGISTRATION_TOKEN}
     SANDBOX_RUNNER_API_GRPC_ADDR: sandbox-api:9090
     SANDBOX_RUNNER_HTTP_BASE_URL: http://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:latest
     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.

 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, and don't route Caddy to it.

```

  1. 将相应的沙箱变量添加到现有 n8n 服务的 environment 块:

yaml environment: # ...your existing N8N_HOST, N8N_PORT, etc. stay as they are - N8N_ENABLED_MODULES=instance-ai - N8N_INSTANCE_AI_SANDBOX_ENABLED=true - N8N_INSTANCE_AI_SANDBOX_PROVIDER=n8n-sandbox - N8N_SANDBOX_SERVICE_URL=http://sandbox-api:8080 - N8N_SANDBOX_SERVICE_API_KEY=${SANDBOX_API_KEYS} - N8N_INSTANCE_AI_SEARXNG_URL=http://searxng:8080 depends_on: sandbox-api: condition: service_healthy

  1. 重启所有服务,使更改生效:

bash sudo docker compose up -d

  1. 添加 model API key。完整参考(包括如何选择 model provider)请参阅设置 n8n Assistant。通过上面捆绑的 SearXNG 服务,网络搜索无需额外配置即可使用;如果更愿意使用 Brave Search,也可以添加 Brave Search key。

警告

将此服务器暴露到互联网前,请将 .env 中的 change-me-... 占位符替换为您自己的唯一 secret。sandbox-runner-1 以特权模式运行 Docker-in-Docker;切勿发布其端口,也不要让 Caddy 将流量路由到它。

更新

如果您使用 Docker Compose 文件运行 n8n,请按照以下步骤更新 n8n:

# Navigate to the directory containing your docker compose file <a href="#navigate-to-the-directory-containing-your-docker-compose-file" id="navigate-to-the-directory-containing-your-docker-compose-file"></a>
cd </path/to/your/compose/file/directory>

# Pull latest version <a href="#pull-latest-version" id="pull-latest-version"></a>
docker compose pull

# Stop and remove older version <a href="#stop-and-remove-older-version" id="stop-and-remove-older-version"></a>
docker compose down

# Start the container <a href="#start-the-container" id="start-the-container"></a>
docker compose up -d

后续步骤

相关资源

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