#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 或更新