验收私有 n8n 部署：PostgreSQL 与外部任务运行器

执行状态：未执行。 本文说明如何在隔离测试实例上进行验收，没有实际运行输出、部署截图或某份配置已经可用的结论。只有完成对应检查后，才能记录实际结果。

1. 先明确测试边界

使用可丢弃的 Linux 主机，或已获授权主机上的隔离实验环境。准备受维护的 Docker Engine、Compose、现有安全管理通道、足够磁盘空间，以及重启失败后的恢复入口。

本轮只使用合成工作流数据。不要接入生产凭据、导入真实工作流、启用定时触发器，或向外部服务发送请求。

建议的基线包含三个服务：n8n、PostgreSQL 和外部任务运行器。数据库及任务代理仅通过私有容器网络通信，不发布宿主机端口。运行器只接入所需的任务代理网络，不挂载数据库存储、n8n 配置或 Docker socket。本基线不使用特权容器、Docker-in-Docker 或 host 网络。

编辑器使用已批准的私有访问方式。宿主机回环地址映射配合 SSH 隧道是一种可选设计。测试前写清实际访问路径，不要为了排查访问问题，把编辑器发布到宿主机全部接口。Hermes 指南中的 Docker/UFW 说明解释了为什么不能只凭 UFW 状态判断边界；其中的 Hermes 命令不是 n8n 配置。

2. 改用上游示例前，先审核配置

官方 withPostgres 示例可以作为审核起点。本页核对的版本包含外部运行器、PostgreSQL 18、数据库与 n8n 持久卷，以及数据库启动健康检查。不过，它仍以 5678:5678 发布编辑器端口，不符合本文的私有访问边界。启动前必须审核并明确调整这部分暴露方式。该示例还让服务共用默认网络；分离数据库与任务代理网络是额外的设计步骤，并非示例已有的属性。参见本次核对的 Compose 文件。

选择受维护的 n8n 版本及匹配的运行器版本，记录两者的镜像摘要。使用 external 模式，并通过私有配置提供共享认证令牌。运行器应访问容器网络中的任务代理地址；运行器内的 localhost 指向运行器自身。按照所选版本核对配置，不要直接沿用旧教程的开关。参见任务运行器配置。

数据库密码、运行器令牌和加密密钥应通过已批准的私有配置方式提供，不要放进命令参数、Git、截图或导出的证据。不要公开包含实际密钥的完整 Compose 展开结果。

记录 PostgreSQL 镜像、数据目录、卷标识和应用数据库角色。数据库跨大版本升级需要独立迁移方案，不要把现有生产数据目录直接挂到另一个 PostgreSQL 大版本上试运行。上游 README 说明了该示例的存储约定。

3. 建立基线记录

启动前记录：

• 日期、宿主机系统、Docker 与 Compose 版本
• n8n、运行器和 PostgreSQL 的准确镜像标识
• 不含密钥的配置版本，以及预期网络边界
• 数据库与 n8n 卷标识、加密密钥保存方式
• 适合本实验的启动等待上限和恢复等待上限
• 需要单独批准的操作，尤其是服务中断和宿主机重启

启动后检查服务状态、重启次数、相关日志、端口映射和网络。只保留脱敏证据。容器处于运行状态，还不足以通过验收。

从另一台已获授权的机器测试：编辑器、数据库和任务代理不能通过非预期的宿主机接口访问。主机分配了公网 IPv4、IPv6 时，应分别检查，并记录探测来源。在宿主机内部发起请求，不能证明外部隔离。若没有同时确认主机在线及预期私有通道可用，单次超时也不足以下结论。

4. 分别检查可达性与数据库就绪状态

n8n 官方文档区分两项检查：

• /healthz 返回 HTTP 200，表示实例可达，不代表数据库健康。
• /healthz/readiness 返回 HTTP 200，表示数据库已连接且迁移完成。

如果修改了默认路径，请使用实际配置的端点。参见 n8n 监控文档。

通过已批准的私有通道探测，设置有限的连接超时和总超时，记录时间、HTTP 状态或连接失败，以及耗时。只等待到预先写明的启动时限。

就绪检查和下一节的工作流执行都需要通过。这两个健康端点本身不能证明 Code 节点能够使用外部运行器。

5. 执行合成手动工作流

新建名为 DeployManual n8n acceptance 的工作流。使用 Manual Trigger，连接一个 JavaScript Code 节点，并选择 Run Once for All Items 模式。让 Code 节点返回一个条目，包含标记 deploymanual-n8n-lab，以及由 2 + 3 计算得到的数值 total。无需凭据、模块导入、文件操作、网络请求或其他节点。参见 Manual Trigger 和 Code 节点文档。

保存工作流，取消所有固定测试数据，再手动执行。

预期验收条件，以下并非实测输出：

• 整个工作流成功完成
• 输出包含指定标记，以及数值 5
• 脱敏后的运行证据能够支持此次 Code 任务由已配置的外部运行器执行
• 重新加载编辑器后，仍能从预期数据库读取已保存的工作流

记录工作流标识、可用时的执行标识、时间和实际结果。编辑器截图或以前保存的输出不足以证明本次执行成功。

本轮只验证一条简单 JavaScript 路径。Python、Webhook、定时执行、队列工作进程、第三方集成和负载能力仍未测试。

6. 分别演练运行器与数据库中断

只有在隔离实验环境中，并获得服务中断授权后，才执行这些检查。记录停止和恢复时间，不删除存储。

运行器中断

仅停止运行器服务，再执行合成工作流。在配置的任务等待时限内观察 Code 步骤等待或失败的实际表现；没有运行器时不应报告 Code 成功结果。超过观察时限仍未结束的等待不能算作验收完成。编辑器与数据库就绪检查可能仍然正常。恢复运行器，等待重新连接，再发起一次新的手动执行。成功后再继续。

数据库中断

确认没有重要执行正在进行，仅停止 PostgreSQL。中断期间持续检查两个健康端点。就绪检查必须在约定观察窗口内停止报告“已就绪”。根据进程实际行为，可能出现非 200 响应，也可能无法建立连接。不要预设唯一错误码，也不要要求 /healthz 一直可用。

使用相同服务和相同数据卷恢复数据库。要求就绪状态恢复、已保存工作流仍然存在，并且新的合成执行成功。同时检查是否存在无法解释的反复重启或迁移失败。

如果需要人工干预，应如实记录，不能写成自动恢复。一次新的执行成功，也不能证明中断中的执行已经安全续跑。

7. 将持久化与宿主机重启分开验收

先通过已审核的 Compose 配置重建应用容器，保留全部卷及原加密密钥。确认原工作流仍然存在，并能够重新成功执行。若实例看起来变空，先核对挂载的存储标识。

使用 PostgreSQL 后，仍需要保存 n8n 自身的状态目录和加密密钥。参见 n8n 持久化说明。不要把删除卷当作重启捷径。

随后，在获得单独批准且准备好带外恢复入口后，重启实际宿主机。检查 Docker 是否启动、各服务能否脱离交互终端恢复、私有网络边界是否保持、数据库是否就绪、原工作流是否保留，以及新的合成执行能否成功。

容器重启和容器重建不能证明宿主机重启恢复。如果环境不能重启，该项应标记为未测试。

8. 排错与完成标准

• 实例可达但未就绪： 检查数据库连接、角色权限、迁移日志、磁盘容量和挂载卷。
• 已就绪但 Code 执行失败： 检查运行器连接、版本匹配、令牌配置和任务超时，不要把任务代理开放到公网。
• 状态似乎丢失： 停止写入，核对 Compose 项目标识、数据库目标、数据目录和实际挂载卷，不要通过重新初始化或删除存储掩盖问题。
• 只有手动重启后才恢复： 记录依赖启动顺序和人工操作，恢复验收仍未完成。
• 发现非预期外部访问： 先停止实验服务，修正边界后再继续。

每项保留一个状态：未测试、通过、失败或受阻，并附日期、环境、证据位置和人工干预记录。本参考指南中的所有验收项目前均为未测试：

通过本实验，只能支持已经记录的配置与检查范围。备份还原、还原后的凭据解密、生产入口、升级、容量和灾难恢复，都需要在生产使用前取得独立证据。