在全新 Linux 服务器上通过 SSH 用 Docker…

当用户想在自己的 VPS/服务器上自托管、安装、部署或维护 n8n（单机或队列模式）时，按此流程端到端完成部署。

适用场景

解决思路

1. 先问用户选哪种模式，不要猜：单机/常规模式（一个 n8n 进程、SQLite、无额外服务、适合 1 用户轻中度负载）还是队列模式（main + N 个 worker、Redis 队列 + Postgres 数据库、worker 并行执行、适合高负载与横向扩展）。不确定就选单机；若用户预期真实高流量则直接上队列模式（后期切换需换 compose 文件并把 SQLite 迁移到 Postgres）。
2. 收集输入：SSH 目标（user@host 及认证方式，root 或 sudo 用户）、域名（完整主机名，如 n8n.example.com → SUBDOMAIN=n8n、DOMAIN_NAME=example.com，用户须能控制其 DNS）、Let's Encrypt 用的 TLS 邮箱（SSL_EMAIL）、时区（IANA 名称如 Europe/Warsaw，否则 Etc/UTC）、模式（队列模式需确认内存约 4 GB 起步，每个 worker 约 1–2 GB）。
3. 询问可选模块：某些功能（当前为 Agents）是# 后端模块，只有列入 N8N_ENABLED_MODULES 才启用；若用户提到，先读 QUEUE_MODE.md 的模块章节，因为队列模式下它必须同时下发到 worker。
4. 询问“工作流是否会使用 Python Code 节点，或除你之外是否还有人编辑工作流？”任一为是即需外部模式任务运行器：加一个 n8nio/runners sidecar（队列模式下每个 worker 一个）。官方 n8nio/n8n 镜像不含 Python 3，默认内部模式下所有 Python Code 节点会报 Python runner unavailable: Python 3 is missing from this system；第 3 步前先读 TASK_RUNNERS.md。
5. 预检（最便宜的失败在这里拦住）：SSH 登录，用 . /etc/os-release 确认是 Debian/Ubuntu 系；确认 DNS 已指向该机器——比较机器公网 IP（curl -s ifconfig.me）与 dig +short <fqdn>（在机器上跑，最好也在本机跑），不一致就停下，让用户建 A 记录并等传播；确认 80 和 443 端口从公网可达，检查主机防火墙以及云安全组/网络防火墙（Hetzner Cloud、AWS SG 等，这些在机器之外，是常见隐形阻塞点）。
6. 安装 Docker（若缺失）：检查 docker --version 和 docker compose version，缺失则安装 Docker Engine + Compose 插件（Ubuntu/Debian 上用官方 get.docker.com 脚本即可），继续前重新确认 docker compose version。
7. 铺设项目：选一个绝对路径的 DATA_FOLDER（如 /opt/n8n），.env 里的 DATA_FOLDER 必须等于该确切目录（compose 挂载 ${DATA_FOLDER}/caddy_config/Caddyfile，init-data.sh 通过相对 ./ 路径挂载），因此始终在此目录运行 docker compose；创建它以及其中的 caddy_config/ 和 local_files/。
8. 把模板文件传到机器上（它们在技能 assets/ 里，不在服务器上）：用 scp 上传，或无需本地副本直接通过 SSH 写入，例如 ssh <target> 'cat > <DATA_FOLDER>/docker-compose.yml' < assets/docker-compose.single.yml；按确切文件名落位：所选 compose → <DATA_FOLDER>/docker-compose.yml（重命名为该名）、Caddyfile → <DATA_FOLDER>/caddy_config/Caddyfile、仅队列模式：init-data.sh → <DATA_FOLDER>/init-data.sh 并 chmod +x、对应的 .env.*.example → <DATA_FOLDER>/.env。
9. 外部任务运行器（Python）：现在就把 runner 环境变量和 task-runners sidecar 加进 compose（TASK_RUNNERS.md 有各模式的片段），并在第 4 步与其他密钥一起生成 N8N_RUNNERS_AUTH_TOKEN。
10. 填写 .env 并生成密钥：设置 DATA_FOLDER、DOMAIN_NAME、SUBDOMAIN、SSL_EMAIL、GENERIC_TIMEZONE；在机器上用 openssl 生成每个密钥（命令见 SECURITY.md）并写入 .env，替换对应的 REPLACE_WITH_… 占位符：N8N_ENCRYPTION_KEY；队列模式还要 POSTGRES_PASSWORD 和 POSTGRES_NON_ROOT_PASSWORD。
11. 启动前确认没有未设置的占位符：grep REPLACE_WITH_ .env 必须无输出——残留占位符会变成字面密码，导致 Postgres/n8n 连不上；然后 chmod 600 .env，并记录加密密钥以便用户离线备份。
12. 配置防火墙：ufw 放行 OpenSSH + 80 + 443 后启用；不要开放 5678/5432/6379。
13. 启动：cd <DATA_FOLDER> && docker compose up -d；队列模式会拉起 Redis + Postgres + main + worker（worker 通过 replicas），扩容用 docker compose up -d --scale n8n-worker=N。
14. 验证（不做就不算成功）：docker compose ps 每个服务 Up/healthy（队列模式先等 postgres 和 redis healthy）；n8n 内部可用：docker compose exec n8n wget -qO- http://localhost:5678/healthz 返回 {"status":"ok"}，以此区分“n8n 在跑”与“TLS 还没就绪”；证书已签发：docker compose logs caddy | grep -i 'certificate obtained'（首次 ACME 可能需一两分钟，期间公网 https 请求 TLS 失败说明证书还在申请，不是 n8n 挂了）；公网可达（带重试）：curl -fsS --retry 5 --retry-delay 10 https://<fqdn>/healthz 返回 {"status":"ok"}（/healthz 只证明进程可达，/healthz/readiness 还确认数据库已连接并迁移，排查启动循环时用它）。
15. 队列模式验证 main 与 worker 一致：diff <(docker compose exec -T n8n env | sort) <(docker compose exec -T --index 1 n8n-worker env | sort)，只应有 public-URL/proxy 变量不同；其他差异意味着某个行为设置只到了 main 没到 worker，而执行工作流的是 worker，会在运行时某个节点失败而非启动时失败（规则见 QUEUE_MODE.md）。
16. 外部任务运行器验证：docker compose logs n8n | grep 'Registered runner' 必须同时出现 launcher-javascript 和 launcher-python（队列模式检查每个 worker），然后按 TASK_RUNNERS.md 的 Verify 冒烟测试一个 Python Code 节点。
17. 打开 https://<fqdn> 应看到 owner setup 界面；谁先完成注册表单谁就占有该实例，暴露的未认领实例是竞态，所以立即创建 owner 账号再分享 URL，并启用 2FA（自动化部署可用环境变量预置 owner，见 SECURITY.md 的 owner 行）。
18. 交付：给用户 URL、项目所在位置、需妥善保存的加密密钥，以及 DAY2.md 里的 Day-2 基础操作（更新/备份/恢复）。
19. 不要跳过 DNS/端口预检（A 记录错误或云防火墙关闭是 Caddy 拿不到证书、n8n 看似“坏了”的头号原因）；不要把 5678/5432/6379 发布到主机（Caddy 通过私有网络访问 n8n）；不要复用其他实例的加密密钥或 .env（每台机器全新密钥）；不要在队列模式用 SQLite（队列必须 Postgres，模板已接好）；不要把密钥放进 docker-compose.yml 或 Caddyfile（只放 .env）；队列模式下不要把行为类环境变量只加到 main（模块、DB、队列、二进制数据和加密设置应放在共享的 x-n8n-env anchor 里让 worker 也拿到，只有 public-URL/proxy 变量是 main 独有，见 QUEUE_MODE.md）；不要盲目用 :latest（固定 N8N_IMAGE_TAG，按 DAY2.md 有意识地更新）；不要承诺官方镜像内部模式下能用 Python Code 节点（需要 n8nio/runners sidecar、版本与 n8n 完全一致、并在 launcher 配置里把 import 加入允许列表，默认连 import json 都会被拒，见 TASK_RUNNERS.md）；一旦 runner 外部化就不要 --scale 队列 worker（一个 sidecar 只服务一个 worker，应成对添加 worker + runner，见 TASK_RUNNERS.md）。

适用边界 · 注意事项

• 不适用于 n8n Cloud，也不适用于构建工作流本身。
• 不适用于非 Debian/Ubuntu 系或无法通过 SSH 以 root/sudo 访问的机器。
• 不适用于用户无法控制域名 DNS 或无法开放 80/443 端口的场景。