287 lines
6.2 KiB
Markdown
287 lines
6.2 KiB
Markdown
#n8n #docker #update
|
||
## 概述
|
||
|
||
本笔记记录 n8n 容器化部署的版本管理和更新方法，基于自定义 Dockerfile 多阶段构建（Python 3.13 任务运行器 + n8n 基础镜像）的场景。
|
||
|
||
---
|
||
|
||
## 问题分析
|
||
|
||
### 当前 Dockerfile 的版本不匹配问题
|
||
|
||
在原有配置中存在以下问题：
|
||
|
||
```dockerfile
|
||
# 阶段 1：克隆特定版本的源码
|
||
RUN git clone --depth 1 --branch n8n@2.13.4 \
|
||
https://github.com/n8n-io/n8n.git /tmp/n8n-src
|
||
|
||
# 阶段 2：使用最新的基础镜像
|
||
FROM n8nio/n8n:latest # ← 潜在的版本不兼容
|
||
```
|
||
|
||
**风险：** 源码版本（2.13.4）与运行时基础镜像版本不一致，可能导致：
|
||
|
||
- Python 任务运行器与 n8n 核心不兼容
|
||
- 环境变量和 API 变化
|
||
- 功能异常或启动失败
|
||
|
||
### docker compose pull 的行为
|
||
|
||
```bash
|
||
$ docker compose pull
|
||
✔ postgres:16-alpine Pulled # ← 成功拉取（直接使用 image:）
|
||
✔ n8n Skipped # ← 跳过（使用 build: 需要重新构建）
|
||
```
|
||
|
||
**原因：** `docker compose pull` 仅处理 `image:` 字段的镜像，对于 `build:` 字段需要使用 `docker compose build`。
|
||
|
||
---
|
||
|
||
## 更新方法
|
||
|
||
### 方案 1：明确版本号（推荐）
|
||
|
||
**优点：**
|
||
|
||
- 版本控制清晰，可复现
|
||
- 避免 `latest` 标签的不确定性
|
||
- 便于回滚
|
||
|
||
**实施步骤：**
|
||
|
||
1. **查询最新版本**
|
||
|
||
```bash
|
||
# 访问 GitHub Releases 页面
|
||
# https://github.com/n8n-io/n8n/releases
|
||
# 或使用 git 查询
|
||
git ls-remote --tags https://github.com/n8n-io/n8n.git | grep -oP 'n8n@\K[\d.]+' | tail -10
|
||
```
|
||
|
||
2. **更新 Dockerfile**
|
||
|
||
```dockerfile
|
||
FROM python:3.13-alpine AS python-builder
|
||
ENV HTTP_PROXY=http://127.0.0.1:10808
|
||
ENV HTTPS_PROXY=http://127.0.0.1:10808
|
||
RUN apk add --no-cache git
|
||
|
||
# 更新版本号
|
||
RUN git clone --depth 1 --branch n8n@2.14.2 \
|
||
https://github.com/n8n-io/n8n.git /tmp/n8n-src
|
||
|
||
# ... 阶段 1 其余部分 ...
|
||
|
||
# 确保基础镜像版本匹配
|
||
FROM n8nio/n8n:2.14.2
|
||
USER root
|
||
# ... 阶段 2 其余部分 ...
|
||
```
|
||
|
||
3. **重新构建和启动**
|
||
|
||
```bash
|
||
# 清除缓存重建
|
||
proxychains docker compose build --no-cache n8n
|
||
|
||
# 停止旧容器
|
||
docker compose down
|
||
|
||
# 启动新容器
|
||
docker compose up -d
|
||
|
||
# 查看日志
|
||
docker compose logs -f n8n
|
||
```
|
||
|
||
|
||
### 方案 2：使用 latest 标签（快速更新，不推荐用于生产）
|
||
|
||
**优点：**
|
||
|
||
- 快速获取最新功能
|
||
- 简化维护
|
||
|
||
**缺点：**
|
||
|
||
- 版本不可控
|
||
- 可能的功能破坏性变化
|
||
- 难以追踪问题
|
||
|
||
**实施步骤：**
|
||
|
||
```dockerfile
|
||
FROM python:3.13-alpine AS python-builder
|
||
ENV HTTP_PROXY=http://127.0.0.1:10808
|
||
ENV HTTPS_PROXY=http://127.0.0.1:10808
|
||
RUN apk add --no-cache git
|
||
|
||
# 移除 --branch 参数，使用最新源码
|
||
RUN git clone --depth 1 https://github.com/n8n-io/n8n.git /tmp/n8n-src
|
||
|
||
# ... 阶段 1 其余部分 ...
|
||
|
||
FROM n8nio/n8n:latest # ← 保持 latest
|
||
USER root
|
||
# ... 阶段 2 其余部分 ...
|
||
```
|
||
|
||
然后执行：
|
||
|
||
```bash
|
||
proxychains docker compose build --no-cache n8n
|
||
docker compose down && docker compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 版本管理
|
||
|
||
|环境|建议|说明|
|
||
|---|---|---|
|
||
|生产|明确版本号|便于故障追踪和回滚|
|
||
|测试|测试多个版本|在升级前验证兼容性|
|
||
|开发|可使用 latest|快速迭代原型|
|
||
|
||
### 2. 构建优化
|
||
|
||
```dockerfile
|
||
# 代理配置一致性
|
||
# 阶段 1 和 docker-compose.yml 应保持一致
|
||
# Dockerfile 中：127.0.0.1:10808（本地）
|
||
# docker-compose.yml 中：host.docker.internal:10808（容器内）
|
||
|
||
# 原因：
|
||
# - Dockerfile 在本地构建时，127.0.0.1 指向本机
|
||
# - 容器运行时，host.docker.internal 指向宿主机
|
||
```
|
||
|
||
### 3. 版本检查
|
||
|
||
更新后验证版本：
|
||
|
||
```bash
|
||
# 进入容器
|
||
docker compose exec n8n sh
|
||
|
||
# 查看 n8n 版本
|
||
npm list n8n
|
||
|
||
# 查看 Python 版本
|
||
python3 --version
|
||
|
||
# 查看任务运行器状态
|
||
ls -la /usr/local/lib/node_modules/@n8n/task-runner-python/
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: docker compose pull 没有更新 n8n
|
||
|
||
**A:** 因为你使用了 `build:` 而不是 `image:`。需要用：
|
||
|
||
```bash
|
||
docker compose build --no-cache n8n
|
||
```
|
||
|
||
### Q2: 更新后 n8n 启动失败
|
||
|
||
**A:** 检查以下几点：
|
||
|
||
```bash
|
||
# 查看错误日志
|
||
docker compose logs n8n
|
||
|
||
# 常见原因：
|
||
# 1. 版本不兼配 → 确保 Dockerfile 两阶段版本一致
|
||
# 2. 环境变量过期 → 查阅新版本的 CHANGELOG
|
||
# 3. 数据库迁移失败 → 检查 PostgreSQL 连接和权限
|
||
```
|
||
|
||
### Q3: 如何回滚到前一个版本
|
||
|
||
**A:**
|
||
|
||
```bash
|
||
# 1. 修改 Dockerfile 版本号
|
||
# 2. 重新构建
|
||
docker compose build --no-cache n8n
|
||
|
||
# 3. 清理数据后重启（如需）
|
||
docker compose down
|
||
docker compose up -d
|
||
```
|
||
|
||
### Q4: 代理在构建时不生效
|
||
|
||
**A:** Docker 构建使用的是宿主机网络，`127.0.0.1` 应该指向代理服务。确保：
|
||
|
||
```bash
|
||
# 1. 代理服务运行中
|
||
# 2. 端口 10808 可访问
|
||
# 3. 检查防火墙规则
|
||
|
||
# 测试连接
|
||
curl -x http://127.0.0.1:10808 https://github.com -I
|
||
```
|
||
|
||
---
|
||
|
||
## 更新清单
|
||
|
||
更新前：
|
||
|
||
- [ ] 备份 `.env` 和 `docker-compose.yml`
|
||
- [ ] 记录当前 n8n 版本
|
||
- [ ] 查看新版本的 CHANGELOG（breaking changes）
|
||
- [ ] 确保代理正常工作
|
||
|
||
更新过程：
|
||
|
||
- [ ] 更新 Dockerfile 版本号（两处）
|
||
- [ ] 执行 `docker compose build --no-cache n8n`
|
||
- [ ] 停止旧容器：`docker compose down`
|
||
- [ ] 启动新容器：`docker compose up -d`
|
||
|
||
更新后：
|
||
|
||
- [ ] 查看 n8n 日志：`docker compose logs n8n`
|
||
- [ ] 检查 Web UI 是否可访问（https://n8n.ishenwei.online）
|
||
- [ ] 验证现有工作流是否正常运行
|
||
- [ ] 检查 Python 任务运行器功能
|
||
|
||
---
|
||
|
||
## 相关命令速查
|
||
|
||
```bash
|
||
# 查看构建日志（详细）
|
||
docker compose build --no-cache n8n --progress=plain
|
||
|
||
# 清理所有 n8n 相关镜像和容器
|
||
docker compose down -v
|
||
docker image rm n8n:*
|
||
|
||
# 重新完整部署
|
||
docker compose down -v && docker compose up -d --build
|
||
|
||
# 进入 n8n 容器交互式 shell
|
||
docker compose exec n8n sh
|
||
|
||
# 查看实时日志
|
||
docker compose logs -f n8n
|
||
|
||
# 仅查看最后 100 行日志
|
||
docker compose logs n8n -n 100
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新：** 2026-09-01
|
||
**当前配置版本：** n8n@2.13.4
|
||
**推荐升级版本：** n8n@2.14.x 或更新 |