笔记更新
This commit is contained in:
287
knowledgebase/n8n Docker 更新指南.md
Normal file
287
knowledgebase/n8n Docker 更新指南.md
Normal file
@@ -0,0 +1,287 @@
|
||||
#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 或更新
|
||||
Reference in New Issue
Block a user