# 部署 n8n 并接入模型 API

n8n 可以串联触发器、HTTP 请求和数据处理节点。生产环境要同时保存工作流、凭据及加密密钥，避免容器重建后无法解密。

更新日期：2026-09-16

规范地址：https://stock.iftalking.com/guides/n8n/

## 1. 先决定部署普通工作流还是完整助手栈

n8n 可以编排定时任务、HTTP 请求和模型调用。普通工作流、Code 节点任务执行器与新版本 n8n Assistant 的沙箱是不同层次，资源和权限要求也不同。本文先完成一个受控的基础工作流实例，再接模型 API。

官方最新完整 Compose 教程包含助手沙箱与搜索组件，至少要求约 2 vCPU、4 GB 内存，并有特权容器。只做基础 API 工作流时不必一开始接入所有组件；正式高并发与长期任务应按官方生产部署方式使用 PostgreSQL、任务执行器和备份。

## 2. 创建持久化的基础 Compose 配置

先安装[Docker 与 Compose](https://stock.iftalking.com/guides/docker/)，建立独立目录。以下示例仅把编辑器映射到主机回环地址，数据存到命名卷，适合先通过 SSH 隧道或现有反向代理测试。

```yaml
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      TZ: Asia/Shanghai
      GENERIC_TIMEZONE: Asia/Shanghai
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
    volumes:
      - n8n_data:/home/node/.n8n
    restart: unless-stopped
volumes:
  n8n_data:
```

使用前在官方镜像页确认标签，正式运行固定到经过验证的版本或摘要。持久卷包含数据库和凭据加密所需信息，不能在更新时随意删除。多用户生产环境按官方 PostgreSQL 示例扩展，不直接把 SQLite 数据目录换成空数据库。

## 3. 启动后用本地连接完成初始化

```bash
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail 60 n8n
curl -f http://127.0.0.1:5678/healthz
```

在自己的电脑建立隧道，SSH 端口按实际替换：

```bash
ssh -N -L 5678:127.0.0.1:5678 -p 22 deploy@203.0.113.10
```

保持隧道运行，在本机打开 `http://localhost:5678`，完成所有者账户设置。正式外部访问配置 HTTPS 域名；不通过关闭安全 cookie 来解决错误的公网 HTTP 部署。

## 4. 先创建一个不会写外部系统的工作流

![n8n 工作流编辑器中的触发器、模型连接和条件分支](https://stock.iftalking.com/tutorial-media/n8n-workflow.png)

*图示说明：n8n 官方项目公开的工作流编辑器截图。它展示触发器、模型与分支的连接方式，属于官方示例；图中通知服务和节点并非本文要求接入的配置。*

图中连线表示数据从前一个节点传到下一个节点。先掌握单线流程，再添加图示中的条件分支与工具调用，不必照图一次接入所有外部服务。

新建工作流，添加 Manual Trigger，再添加 Edit Fields/Set 节点，输出一条固定文字，执行后检查每个节点的输入与输出。然后添加 HTTP Request，访问自己允许测试的公开接口，确认状态码和字段路径。

接入模型时，在 Credentials 中保存 API Key，配置当前模型名与官方 Base URL。使用原生支持的模型节点，或按官方接口格式发送请求；先用一条无敏感内容的问题测试，查看返回和费用，再接正式数据。

## 5. 上线定时任务与 Webhook 前检查地址

定时节点使用配置的时区，保存后按当前版本要求启用/发布工作流。测试 Webhook 地址与正式地址用途不同，不要把只在手动监听时有效的测试地址发给正式调用方。

反向代理下设置正确的 `WEBHOOK_URL`、编辑器公开地址和可信代理跳数，按官方当前部署文档核对。给 Webhook 加认证或签名检查，防止任何人触发昂贵模型调用。

## 6. 保留执行记录并测试恢复

设置失败分支、超时、有限重试和执行历史保留，避免重试重复发送消息或重复写单。导出工作流不一定包含可用凭据，备份还要覆盖数据库、持久目录和加密密钥。

升级前记录版本，备份后阅读迁移说明，再验证登录、定时任务、Webhook 和模型调用。助手沙箱、社区节点和命令执行工具按需要逐项启用，不给它们无关的宿主机目录与秘密。更多见[API 接入](https://stock.iftalking.com/guides/ai-api/)和[备份恢复](https://stock.iftalking.com/guides/backup-restore/)。


## 完成后检查

流程手动运行成功后，还要验证外部触发、时区和失败告警。

## 参考资料

- [n8n 官方文档](https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose)
- [github.com · 项目文档](https://github.com/n8n-io/n8n)