n8n 基础镜像 Docker 镜像使用指南

快速参考

维护方

由 n8nio 官方团队维护，作为 n8n 生态的基础依赖镜像。

帮助渠道

可通过 n8n 官方文档、GitHub 仓库 Issues 板块或社区论坛获取支持。

支持的标签及对应 Dockerfile 链接

稳定版本标签：latest（最新稳定版）、18（对应 Node.js 18 基础版本）等
Dockerfile 可通过 n8n 官方代码仓库查看

问题反馈地址

n8n GitHub Issues：https://github.com/n8n-io/n8n/issues

支持的架构

主要支持 amd64 架构，部分版本兼容 arm64（适配 ARM 架构服务器）。

镜像详情

包含元数据、传输大小等信息，可访问 Docker Hub 镜像页面查看。

镜像更新

随底层 Linux 发行版、Node.js 版本及核心依赖更新同步迭代，更新频率低于 n8n 功能镜像。

本文档来源

基于 n8n 生态镜像特性、基础镜像设计规范整理，实际以官方文档为准。

什么是 n8nio/base

n8nio/base 是 n8n 生态的底层基石，解决多组件的环境一致性问题：

核心构成：基于 Alpine Linux 或 Debian 构建，包含稳定版 Node.js 运行时（如 Node.js 18/20）、Yarn 包管理器、基础系统库（如 libstdc++）及安全优化配置
设计目标：提供轻量、安全、统一的基础环境，减少上层镜像的构建复杂度，确保 n8n 主服务、runners 等组件在不同部署环境下的行为一致性
生态定位：不直接用于生产部署，仅作为构建其他 n8n 相关镜像的基础层（如 n8nio/n8n 镜像即基于此镜像扩展）

如何使用本镜像

作为基础镜像构建自定义 n8n 组件

在 Dockerfile 中引用 n8nio/base 作为基础层，扩展自定义功能：

dockerfile
# 基于 n8nio/base 构建自定义 n8n 节点镜像
FROM docker.xuanyuan.run/n8nio/base:latest

# 安装额外依赖（如 Python 开发库）
RUN apk add --no-cache python3 py3-pip

# 复制自定义节点代码
COPY ./custom-nodes /home/node/custom-nodes

# 设置工作目录
WORKDIR /home/node

# 安装节点依赖
RUN yarn add /home/node/custom-nodes

本地验证基础环境

启动镜像验证 Node.js 与依赖可用性：

bash
# 启动基础镜像容器
docker run --rm -it docker.xuanyuan.run/n8nio/base:latest sh

# 验证 Node.js 版本
node -v  # 输出如 v18.20.3

# 验证 Yarn 版本
yarn -v  # 输出如 1.22.22

配置说明

该镜像为基础环境镜像，无额外配置项，核心特性通过构建时确定：

Node.js 版本：标签通常对应内置 Node.js 主版本（如 n8nio/base:18 对应 Node.js 18.x）
系统依赖：预装 curl、tar 等基础工具，以及 libstdc++ 等 Node.js 扩展所需的系统库
用户配置：默认创建 node 用户（UID 1000），工作目录为 /home/node，与 n8n 主镜像保持一致

数据持久化

作为基础镜像，无本地状态存储需求，无需配置数据卷。上层镜像需根据功能需求自行设计持久化方案（如 n8n 主镜像需持久化 /home/node/.n8n 目录）。

注意事项

镜像用途

仅作为基础层使用，不建议直接启动容器运行业务逻辑。

版本选择

需根据上层组件的 Node.js 版本需求选择对应标签的 base 镜像。

安全更新

定期拉取最新版本以获取底层系统与 Node.js 的安全补丁。

架构适配

ARM 架构服务器需选择支持 arm64 架构的标签（如 n8nio/base:latest-arm64）。

许可信息

镜像基于 n8n 的 Fair-Code Sustainable Use License 许可协议，作为基础组件供 n8n 生态镜像构建使用，详情参考 n8n 许可说明 https://n8n.io/license/

n8nio/base Docker Image