Skip to content

Commit c1e7d37

Browse files
mudsskymudssky
committed
feat(self-hosted): 增加 n8n 自托管配置
1 parent 643a819 commit c1e7d37

7 files changed

Lines changed: 386 additions & 2 deletions

File tree

‎.agents/skills/repo-ops/SKILL.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: repo-ops
3-
description: 管理 powershellScripts 仓库运维任务时使用，包括 LiteLLM 网关、LobeHub 与 Forgejo 自托管、项目依赖安装、Docker Compose 服务生命周期、日志状态排查、环境变量示例文件，以及维护本地 repo-ops skill。
3+
description: 管理 powershellScripts 仓库运维任务时使用，包括 LiteLLM 网关、LobeHub、Forgejo 与 n8n 自托管、项目依赖安装、Docker Compose 服务生命周期、日志状态排查、环境变量示例文件，以及维护本地 repo-ops skill。
44
---
55

66
# Repo Ops
@@ -12,6 +12,7 @@ description: 管理 powershellScripts 仓库运维任务时使用，包括 LiteL
1212
- LiteLLM 网关：模型路由、fallback、配置同步、启动、重启、日志、运行时 smoke test。
1313
- LobeHub 自托管：external/internal 模式、服务启动、状态、日志、RustFS bucket 初始化和常见排查。
1414
- Forgejo 自托管：服务启动、状态、日志、SSH 端口、数据盘、PostgreSQL 复用、Pull Mirror 同步和常见排查。
15+
- n8n 自托管：服务启动、状态、日志、Webhook URL、secure cookie、数据盘、PostgreSQL 复用和常见排查。
1516
- 项目依赖安装：根目录初始化、PowerShell 模块、Node/Bash 工具构建、pnpm QA。
1617
- 本 skill 维护：新增运维域、更新 reference、刷新 `agents/openai.yaml`、校验 skill 结构。
1718

@@ -28,6 +29,7 @@ description: 管理 powershellScripts 仓库运维任务时使用，包括 LiteL
2829
- LiteLLM 网关任务：读取 `references/litellm.md`。
2930
- LobeHub 自托管任务：读取 `references/lobehub.md`。
3031
- Forgejo 自托管任务：读取 `references/forgejo.md`。
32+
- n8n 自托管任务：读取 `references/n8n.md`。
3133
- 项目安装、依赖、QA：读取 `references/project-install.md`。
3234
- 修改本 skill 或新增运维域：读取 `references/skill-maintenance.md`。
3335

@@ -38,3 +40,4 @@ description: 管理 powershellScripts 仓库运维任务时使用，包括 LiteL
3840
- 不把 LiteLLM 的 OpenAI 兼容 `claw-` 路由和 Claude Code Anthropic messages 兜底路由混用。
3941
- 不把 LobeHub external 模式误认为项目会启动 PostgreSQL、Redis、RustFS；默认 external 依赖宿主机共享服务。
4042
- 不把 Forgejo 本机 `.env`、数据盘 `app.ini`、SSH host key、JWT key、数据库密码或访问 token 写入 skill、提交信息或最终答复。
43+
- 不把 n8n 本机 `.env`、`N8N_ENCRYPTION_KEY`、数据库密码、用户凭据或 workflow secret 写入 skill、提交信息或最终答复。

‎.agents/skills/repo-ops/agents/openai.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
interface:
22
display_name: "Repo Ops"
3-
short_description: "管理本仓库 LiteLLM、LobeHub、Forgejo 与依赖安装"
3+
short_description: "管理本仓库 LiteLLM、LobeHub、Forgejo、n8n 与依赖安装"
44
default_prompt: "使用 $repo-ops 处理本仓库的运维任务。"

‎.agents/skills/repo-ops/references/n8n.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# n8n 自托管运维
2+
3+
## 关键路径
4+
5+
- 目录：`self-hosted/n8n/`
6+
- 说明文档：`self-hosted/n8n/README.md`
7+
- Compose 模板：`self-hosted/n8n/compose.yaml`
8+
- 环境示例：`self-hosted/n8n/.env.example`
9+
- 私有环境：`self-hosted/n8n/.env`
10+
- 本机数据盘：通常为 `/Volumes/Data/docker_data/n8n`
11+
12+
不要输出 `.env` 中的 `N8N_ENCRYPTION_KEY`、数据库密码、用户凭据、API key、OAuth secret、workflow 内部 secret 或其他私密值。
13+
14+
## 服务边界
15+
16+
- n8n compose 只管理 n8n 应用容器，不启动 PostgreSQL。
17+
- PostgreSQL 复用宿主机共享服务，容器内默认通过 `host.docker.internal:5432` 访问。
18+
- Linux Docker Engine 依赖 compose 中的 `host.docker.internal:host-gateway`。
19+
- macmini 本机长期数据不放仓库目录，使用 `N8N_DATA_PATH=/Volumes/Data/docker_data/n8n`。
20+
- 当前默认访问入口：
21+
- Web：`http://macmini:5678/`
22+
- 本机回环：`http://localhost:5678/`
23+
24+
## 常用命令
25+
26+
从仓库根目录执行：
27+
28+
```bash
29+
docker compose \
30+
--env-file self-hosted/n8n/.env \
31+
-f self-hosted/n8n/compose.yaml \
32+
--project-directory self-hosted/n8n \
33+
ps
34+
35+
docker compose \
36+
--env-file self-hosted/n8n/.env \
37+
-f self-hosted/n8n/compose.yaml \
38+
--project-directory self-hosted/n8n \
39+
logs -f --tail=200 n8n
40+
41+
docker compose \
42+
--env-file self-hosted/n8n/.env \
43+
-f self-hosted/n8n/compose.yaml \
44+
--project-directory self-hosted/n8n \
45+
up -d --force-recreate n8n
46+
```
47+
48+
模板检查使用 `.env.example`，避免依赖本机私有配置：
49+
50+
```bash
51+
docker compose \
52+
--env-file self-hosted/n8n/.env.example \
53+
-f self-hosted/n8n/compose.yaml \
54+
--project-directory self-hosted/n8n \
55+
config
56+
```
57+
58+
## 数据目录和配置修改
59+
60+
- 修改 `self-hosted/n8n/.env` 前，按项目规则创建同目录时间戳 `.bak`。
61+
- n8n 数据目录挂载到容器内 `/home/node/.n8n`，本机长期部署默认使用 `/Volumes/Data/docker_data/n8n`。
62+
- 数据迁移到新路径时：
63+
1. 停止 n8n 容器。
64+
2. 使用 `rsync -a` 复制旧数据，保留权限和时间戳。
65+
3. 更新 `N8N_DATA_PATH`。
66+
4. 重建容器。
67+
5. 用 `docker inspect n8n` 验证 `/home/node/.n8n` 的 mount source。
68+
- 不删除旧 `data/`、volume、数据库或数据盘目录，除非用户明确要求。
69+
70+
## PostgreSQL
71+
72+
- Compose 不创建数据库；首次启动前需要在共享 PostgreSQL 中准备 `N8N_DB_NAME`，默认是 `n8n`。
73+
- 默认变量：
74+
- `N8N_DB_HOST=host.docker.internal`
75+
- `N8N_DB_PORT=5432`
76+
- `N8N_DB_NAME=n8n`
77+
- `N8N_DB_USER=postgres`
78+
- `N8N_DB_SCHEMA=public`
79+
- 不要把 `N8N_DB_PASSWORD` 的真实值写入日志、文档、提交信息或最终答复。
80+
- 本机非 SSL PostgreSQL 不需要向 n8n 传 `DB_POSTGRESDB_SSL_*` 变量；如果误传，可能触发 `The server does not support SSL connections`。
81+
82+
## Webhook 与 Cookie
83+
84+
- `N8N_HOST`、`N8N_PROTOCOL` 和 `N8N_WEBHOOK_URL` 会影响页面和 webhook URL。
85+
- 本机 HTTP 访问时保持 `N8N_SECURE_COOKIE=false`，否则浏览器可能提示 secure cookie 与非安全 URL 不匹配。
86+
- 改成 HTTPS 反向代理入口时，同步更新：
87+
- `N8N_HOST`
88+
- `N8N_PROTOCOL`
89+
- `N8N_WEBHOOK_URL`
90+
- `N8N_SECURE_COOKIE`
91+
- `N8N_ENCRYPTION_KEY` 必须长期固定并备份；服务使用后不要随意更换，否则历史凭据可能无法解密。
92+
93+
## 常见排查
94+
95+
- Web 提示 secure cookie 错误：本机 HTTP 场景检查 `N8N_SECURE_COOKIE=false`，重建容器后再访问。
96+
- 数据库连接失败：确认宿主机 PostgreSQL 监听 `5432`，并检查 `.env` 中数据库主机、库名、用户变量。
97+
- 日志出现 `The server does not support SSL connections`：检查 compose 展开结果中是否仍存在 `DB_POSTGRESDB_SSL_*` 变量。
98+
- webhook 地址不对：检查 `N8N_WEBHOOK_URL` 是否是浏览器或外部服务可访问的最终入口。
99+
- 页面无法访问但容器运行中：先 `curl --noproxy '*' -I http://localhost:5678/`，再检查本机代理、端口占用和容器日志。
100+
101+
## 验证清单
102+
103+
```bash
104+
docker compose \
105+
--env-file self-hosted/n8n/.env.example \
106+
-f self-hosted/n8n/compose.yaml \
107+
--project-directory self-hosted/n8n \
108+
config
109+
110+
docker inspect n8n --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
111+
112+
curl --noproxy '*' -sS -I --max-time 10 http://localhost:5678/
113+
```
114+
115+
模板或文档变更后运行：
116+
117+
```bash
118+
pnpm qa
119+
```

‎self-hosted/n8n/.env.example‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# n8n self-hosted 模板环境变量示例
2+
# 使用前建议复制为 `.env` 后按本机实际情况调整：
3+
# cp self-hosted/n8n/.env.example self-hosted/n8n/.env
4+
5+
# =====================
6+
# ===== 容器基础 =====
7+
# =====================
8+
9+
# n8n 官方 Docker 镜像。长期使用建议替换 latest 为明确版本号。
10+
N8N_IMAGE=docker.n8n.io/n8nio/n8n:latest
11+
12+
# 容器重启策略。
13+
N8N_RESTART_POLICY=unless-stopped
14+
15+
# n8n 数据目录。macOS 长期部署建议使用：
16+
# /Volumes/Data/docker_data/n8n
17+
N8N_DATA_PATH=./data/n8n
18+
19+
# n8n 工作流和定时任务使用的时区。
20+
N8N_TIMEZONE=Asia/Shanghai
21+
22+
# 启用 task runner，匹配 n8n 官方 Docker 启动建议。
23+
N8N_RUNNERS_ENABLED=true
24+
25+
# 固定凭据加密密钥。正式使用前必须替换为长随机字符串，并妥善备份。
26+
N8N_ENCRYPTION_KEY=change-me-to-a-long-random-string
27+
28+
# =====================
29+
# ===== 访问入口 =====
30+
# =====================
31+
32+
# HTTP 对外端口。
33+
N8N_HTTP_PORT=5678
34+
35+
# 浏览器访问 n8n 的主机名、协议与 webhook 根地址。
36+
N8N_HOST=localhost
37+
N8N_PROTOCOL=http
38+
N8N_SECURE_COOKIE=false
39+
N8N_WEBHOOK_URL=http://localhost:5678/
40+
41+
# =======================
42+
# ===== 外部 PostgreSQL =====
43+
# =======================
44+
45+
# 复用宿主机共享 PostgreSQL，和 Forgejo 使用同一个 PostgreSQL 实例。
46+
N8N_DB_HOST=host.docker.internal
47+
N8N_DB_PORT=5432
48+
N8N_DB_NAME=n8n
49+
N8N_DB_USER=postgres
50+
N8N_DB_PASSWORD=12345678
51+
N8N_DB_SCHEMA=public

‎self-hosted/n8n/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.env
2+
.env.local
3+
.env.*.bak
4+
data/

‎self-hosted/n8n/README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# n8n Compose
2+
3+
这个目录提供 n8n 的 Docker Compose 部署模板。它只启动 n8n 应用容器，数据库复用系统已有 PostgreSQL，模式与 `self-hosted/forgejo` 一致。
4+
5+
## 文件说明
6+
7+
- `compose.yaml`：n8n 应用服务模板。
8+
- `.env.example`：可复制的环境变量示例。
9+
- `.gitignore`：忽略本地 `.env` 与运行数据目录。
10+
11+
## 默认约定
12+
13+
- HTTP：宿主机 `5678` -> 容器 `5678`
14+
- PostgreSQL：`host.docker.internal:5432`
15+
- 数据库名：`n8n`
16+
- 数据库用户：`postgres`
17+
- 数据库密码：`12345678`
18+
- 应用数据目录：默认 `self-hosted/n8n/data/n8n`，macOS 长期部署建议放在 `/Volumes/Data/docker_data/n8n`
19+
20+
## 准备环境变量
21+
22+
```bash
23+
cp self-hosted/n8n/.env.example self-hosted/n8n/.env
24+
```
25+
26+
长期使用前，至少检查：
27+
28+
- `N8N_HOST`
29+
- `N8N_PROTOCOL`
30+
- `N8N_SECURE_COOKIE`
31+
- `N8N_WEBHOOK_URL`
32+
- `N8N_ENCRYPTION_KEY`
33+
- `N8N_DB_HOST`
34+
- `N8N_DB_NAME`
35+
- `N8N_DB_USER`
36+
- `N8N_DB_PASSWORD`
37+
- `N8N_DATA_PATH`
38+
39+
`N8N_ENCRYPTION_KEY` 用于加密 n8n 凭据。首次正式启动前必须替换为长随机字符串，并妥善备份；服务已经使用后不要随意更换，否则历史凭据可能无法解密。
40+
41+
本机通过 HTTP 访问时，`N8N_SECURE_COOKIE` 需要保持为 `false`，否则登录页会提示 secure cookie 与非安全 URL 不匹配。后续如果改成 HTTPS 反向代理入口，再把它改回 `true`。
42+
43+
## 准备 PostgreSQL 数据库
44+
45+
Compose 不会启动 PostgreSQL，也不会自动创建数据库。首次启动前需要在共享 PostgreSQL 中准备 `n8n` 数据库。
46+
47+
如果宿主机已经有 `createdb`：
48+
49+
```bash
50+
PGPASSWORD=12345678 createdb -h localhost -p 5432 -U postgres n8n
51+
```
52+
53+
如果使用仓库共享 PostgreSQL 容器：
54+
55+
```bash
56+
docker exec -it postgre createdb -U postgres n8n
57+
```
58+
59+
如果数据库已经存在，可以跳过这一步。
60+
61+
## 准备数据目录
62+
63+
n8n 官方镜像会把运行数据写入 `/home/node/.n8n`。首次启动前建议显式创建目录，避免 Docker 自动创建 root-owned 目录带来后续维护困扰。
64+
65+
默认仓库内路径：
66+
67+
```bash
68+
mkdir -p self-hosted/n8n/data/n8n
69+
```
70+
71+
macOS 上如果使用 `start-container.ps1` 同款数据盘，可以在 `.env` 中配置：
72+
73+
```bash
74+
N8N_DATA_PATH=/Volumes/Data/docker_data/n8n
75+
```
76+
77+
并准备目录：
78+
79+
```bash
80+
mkdir -p /Volumes/Data/docker_data/n8n
81+
```
82+
83+
## 启动
84+
85+
```bash
86+
docker compose \
87+
--env-file self-hosted/n8n/.env \
88+
-f self-hosted/n8n/compose.yaml \
89+
--project-directory self-hosted/n8n \
90+
up -d
91+
```
92+
93+
启动后访问：
94+
95+
```text
96+
http://localhost:5678/
97+
```
98+
99+
## 查看状态和日志
100+
101+
```bash
102+
docker compose \
103+
--env-file self-hosted/n8n/.env \
104+
-f self-hosted/n8n/compose.yaml \
105+
--project-directory self-hosted/n8n \
106+
ps
107+
108+
docker compose \
109+
--env-file self-hosted/n8n/.env \
110+
-f self-hosted/n8n/compose.yaml \
111+
--project-directory self-hosted/n8n \
112+
logs -f --tail=200 n8n
113+
```
114+
115+
## 停止
116+
117+
```bash
118+
docker compose \
119+
--env-file self-hosted/n8n/.env \
120+
-f self-hosted/n8n/compose.yaml \
121+
--project-directory self-hosted/n8n \
122+
down
123+
```
124+
125+
`down` 不会删除 `data/n8n`，应用数据会保留在本目录下。
126+
127+
## 升级
128+
129+
如果使用 `latest` 镜像，可以按下面方式拉取并重建：
130+
131+
```bash
132+
docker compose \
133+
--env-file self-hosted/n8n/.env \
134+
-f self-hosted/n8n/compose.yaml \
135+
--project-directory self-hosted/n8n \
136+
pull
137+
138+
docker compose \
139+
--env-file self-hosted/n8n/.env \
140+
-f self-hosted/n8n/compose.yaml \
141+
--project-directory self-hosted/n8n \
142+
up -d
143+
```
144+
145+
长期使用建议把 `N8N_IMAGE` 固定到明确版本，升级前先备份 PostgreSQL 数据库和 `N8N_DATA_PATH`。
146+
147+
## 配置检查
148+
149+
修改 `.env` 后可以先展开配置：
150+
151+
```bash
152+
docker compose \
153+
--env-file self-hosted/n8n/.env \
154+
-f self-hosted/n8n/compose.yaml \
155+
--project-directory self-hosted/n8n \
156+
config
157+
```
158+
159+
如果只想验证模板默认值，也可以直接用 `.env.example`：
160+
161+
```bash
162+
docker compose \
163+
--env-file self-hosted/n8n/.env.example \
164+
-f self-hosted/n8n/compose.yaml \
165+
--project-directory self-hosted/n8n \
166+
config
167+
```

0 commit comments

Comments
 (0)