n8n-guard

n8n-guard

一个用于访问 n8n Public API 底层 运维层的 MCP 服务。

注册表中的大多数 n8n MCP 服务都封装了相同的公共端点：列出工作流、列出执行记录、创建、激活、删除。这对构建工作流很有用。但对维持可自托管实例正常运行几乎毫无帮助，因为真正会导致实例宕机的问题根本不在该 API 中。

n8n-guard 解答了 API 无法回答的四个问题：

1. 数据存储有多大，何时会成为问题？ Public API 没有用于查询数据库大小的端点。n8n-guard 会读取 SQLite 文件或 直接查询 Postgres，按表拆分统计大小，计算增长率，并告诉你还剩多少天的余量。
2. 哪些执行卡住了？ 按状态列出执行记录并不等于检测。某次运行停留在 running 状态时，看起来与正常的长时间任务没有区别，除非将其与该工作流通常所需的时间进行比较。n8n-guard 会根据已完成的运行记录计算每个工作流的中位数，并标记异常值。
3. 保留策略的代价是什么？ 存储了多少条执行记录、这些记录最早可追溯到何时，以及指定的保留期限能释放多少空间。
4. 实例是否已偏离 git？ 现有服务会比较两个 API 对象。n8n-guard 会将运行中的实例与代码库中的 JSON 导出文件进行比较：在线但从未导出的工作流、已导出但已删除的工作流，以及悄然发生偏差的内容。

它严格只读。n8n-guard 从不写入你的实例、从不删除执行记录，也从不激活或编辑工作流。它负责报告；由你来决定。

安装

npx -y n8n-guard

需要 Node.js 22 或更高版本（使用内置的 node:sqlite）。如需永久安装，请使用 npm install -g n8n-guard。

Claude Desktop / 任意 MCP 客户端

{
  "mcpServers": {
    "n8n-guard": {
      "command": "n8n-guard",
      "env": {
        "N8N_URL": "https://n8n.example.com",
        "N8N_API_KEY": "n8n_api_...",
        "N8N_SQLITE_PATH": "/var/lib/n8n/.n8n/database.sqlite",
        "N8N_GIT_REPO_PATH": "/srv/workflow-exports"
      }
    }
  }
}

配置

所有配置均通过环境变量完成。没有硬编码的主机、路径、容器名称或账户，因此该服务可连接到任意可自托管实例。

变量	必填	默认值	用途
N8N_URL	否	http://localhost:5678	实例的基础 URL
N8N_API_KEY	执行和工作流检查时必填	无	Public API 密钥（Settings，n8n API）
N8N_SQLITE_PATH	使用 SQLite 进行数据存储检查时必填	无	database.sqlite 的路径
N8N_POSTGRES_URL	使用 Postgres 进行数据存储检查时必填	无	连接字符串，优先于 SQLite
N8N_GIT_REPO_PATH	进行偏差检查时必填	无	存放已导出工作流 JSON 的检出目录
N8N_GUARD_STUCK_MINUTES	否	15	运行处于 running 状态多久后视为卡住，单位为分钟
N8N_GUARD_DB_WARN_BYTES	否	1073741824（1 GB）	数据存储警告阈值
N8N_GUARD_DB_CRITICAL_BYTES	否	4294967296（4 GB）	数据存储严重阈值
N8N_GUARD_TIMEOUT_MS	否	15000	每个 API 请求的超时时间

部分配置是受支持的模式，并非错误。只配置 N8N_URL 和 N8N_SQLITE_PATH 仍可获取磁盘和保留策略相关信息；基于 API 的检查会报告未配置，并继续执行其余检查。

工具

工具	功能
instance_info	可达性、已配置的数据存储、工作流清单。显示哪些检查可用。
db_health	数据存储大小、各表明细、增长率，以及距离临界阈值的预计天数。
stuck_executions	卡在 running 状态的执行，依据绝对阈值和各工作流自身的中位数进行判断。
retention_report	执行数量、时间跨度，以及将保留期设为指定窗口后可释放的空间。
git_drift	对比实时工作流与仓库导出文件：缺失、已删除、存在差异、重复。
guard_run	以一次稳健的全面检查运行上述所有检查。建议安排运行此项。

调用示例

将服务指向一个实例，然后让客户端调用工具。每个工具都会先返回易读的摘要，再返回完整的结构化载荷：

## Retention report
- 200 execution records spanning 8.3 days (24.1/day)
- nothing older than 30 days, retention is already tight
- n8n-guard never deletes. To act on this, set EXECUTIONS_DATA_PRUNE=true and
  EXECUTIONS_DATA_MAX_AGE=720 (hours) on the n8n instance, then restart it.

随后是摘要所依据的结构化载荷：

{
  "executionCount": 200,
  "oldestExecutionAt": "2026-08-28T23:43:28.651Z",
  "spanDays": 8.29,
  "executionsPerDay": 24.12,
  "buckets": [
    { "olderThanDays": 7, "rows": 32, "share": 0.16, "estimatedBytes": 3277 },
    { "olderThanDays": 30, "rows": 0, "share": 0, "estimatedBytes": 0 }
  ]
}

guard_run 会执行全部六项检查。只配置数据存储时，它会报告缺少的部分，而不是中止：

## Guard run (degraded)
- stuck_executions failed after 3 attempt(s): N8N_API_KEY is not set, so the n8n Public API cannot be queried
- git_drift failed after 2 attempt(s): N8N_GIT_REPO_PATH is not set, so there is nothing to diff the instance against
- 4 of 6 checks completed despite the failures above

故障恢复：guard_run 可在部分服务中断时继续运行

如果监控运行在遇到第一个无法访问的依赖项时就中止，那它恰恰会在最需要的时候失去价值。API 宕机本身就是事故，但这并不意味着应该停止检查磁盘。

guard_run 会隔离每个步骤。失败的步骤会以退避方式重试；如果仍然失败，就会作为一项发现记录下来，同时其余检查会继续运行直至完成。依赖失败步骤的检查会附上原因并跳过，而不会因缺少输入而崩溃。报告会明确说明：

## Guard run (degraded)
- stuck_executions failed after 3 attempt(s): cannot reach http://n8n.internal:5678: fetch failed
- git_drift skipped: depends on instance, which failed
- 4 of 6 checks completed despite the failures above

此行为由 test/unit/runner.test.ts 和 test/unit/serviceRecovery.test.ts 中的测试覆盖。后者使用一个真实的 SQLite 数据存储，并连接到一个特意设为不可用的 API 端点。

渲染工作流

同一轮全面检查也可以作为 Render 工作流运行：每项检查对应一个 Render 任务，任务定义中声明执行顺序、重试和退避策略，并由 Render 而非进程内运行器执行。 部署步骤、任务表以及如何触发运行（包括一个展示重试流程的故意失败示例）请参阅 docs/render-workflow.md。

在临时实例上试用

该 compose 文件会启动一个全新的 n8n 实例，你可以放心地将服务指向它。数据目录以绑定挂载的方式挂载，这正是 n8n-guard 读取真实部署数据的方式。

git clone https://github.com/flow-84/n8n-guard && cd n8n-guard
npm install && npm run build

docker compose up -d
./scripts/demo-setup.sh     # owner, API key, workflows, and a drifted export folder

该脚本会生成所有者密码，将其保存在被 git 忽略的 .n8n-demo-credentials 中，并连同运行服务所需的环境变量块一起打印出来。脚本会预置四个工作流：一个与其导出文件匹配的工作流、一个从未导出的工作流、一个指向 sink 容器且可能导致运行挂起的工作流，以及一个对应工作流不存在的导出文件，这样 git_drift 和 stuck_executions 就有真实目标可供检测。

export N8N_URL=http://localhost:5679
export N8N_API_KEY=...            # printed by the script
export N8N_SQLITE_PATH=$PWD/.n8n-demo/database.sqlite
export N8N_GIT_REPO_PATH=$PWD/.n8n-demo-exports
npm start

该实例发布在 5679 端口，而非 n8n 默认的 5678 端口，因此不会与需要保留的实例冲突。设置 N8N_DEMO_PORT 可更改端口，并在 demo-setup.sh、集成测试和 N8N_URL 中传入相同的值。

测试

npm test              # unit tests, no instance required
npm run test:integration   # against the compose instance above

如果未设置 N8N_API_KEY，集成测试套件会跳过依赖 API 的测试用例，因此在纯净环境中运行 docker compose up 后仍可执行。

许可证

MIT