用途:该技能用于排查 n8n v1.x 中的连接类故障,采用“症状→原因→修复”的确定性诊断表格,避免误判问题来源。
主要能力:
- API 连接失败:覆盖 ECONNREFUSED、ENOTFOUND(DNS)、ETIMEDOUT、HTTP 500/502/503、ECONNRESET 及代理错误,并给出检查服务状态、URL、DNS、防火墙与重试的处理方向。
- 凭据错误:覆盖 401、403、凭据未找到、OAuth2 令牌过期、凭据类型不匹配,以及 N8N_ENCRYPTION_KEY 不一致等问题。
- 超时配置:说明节点级(Retry On Fail、Max Tries、Wait Between Tries)、工作流级与实例级(EXECUTIONS_TIMEOUT、EXECUTIONS_TIMEOUT_MAX、N8N_AI_TIMEOUT_MAX)三层超时。
- SSL/TLS 错误:覆盖 UNABLE_TO_VERIFY_LEAF_SIGNATURE、CERT_HAS_EXPIRED、DEPTH_ZERO_SELF_SIGNED_CERT、ERR_TLS_CERT_ALTNAME_INVALID 与 PostgreSQL SSL 相关配置,并强调生产环境不得关闭证书校验。
- Webhook URL 问题:区分测试 URL(/webhook-test/)与生产 URL(/webhook/),说明工作流需激活、WEBHOOK_URL 需设置为公网地址,以及负载大小上限 N8N_PAYLOAD_SIZE_MAX。
- 速率限制:针对 HTTP 429,建议启用 Retry On Fail、调整等待时间、使用 Split In Batches 与 Wait 节点。
- 队列模式(Redis)连接:覆盖 Redis 连接被拒绝、AUTH 失败、超时、worker 不领取任务与执行卡在 waiting,并列出启用队列模式的前置检查项。
- 数据库连接:覆盖 PostgreSQL 连接被拒绝、密码认证失败、数据库不存在、连接池耗尽、连接超时,以及 SQLite 的 SQLITE_BUSY、SQLITE_CORRUPT 等问题。
使用方式:按诊断流程图先判断错误类型(HTTP 状态码、Node.js 错误码、数据库错误、队列/Redis 错误),再进入对应表格按“症状→原因→修复”处理;参考文件包括 references/methods.md(错误类型、重试与超时配置)、references/examples.md(分步修复场景)、references/anti-patterns.md(应避免的连接处理错误)。
适用场景:n8n 工作流出现连接失败、凭据报错、超时、证书错误、Webhook 不触发、触发限流或队列/数据库连接异常时的排查。
限制:资料仅针对 n8n v1.x 的连接问题,其他版本或非连接类故障暂未提供;具体命令、环境变量取值与部署细节需以资料所列内容为准,资料未涉及的场景暂未提供。