09.附录 Docker Desktop

1. Docker 核心概念与前置准备

  • Docker 的本质：将复杂的软件安装与环境配置过程打包成一个“可直接运行的盒子”。可类比为“游戏模拟器”，Docker 是模拟器，n8n、Ollama、Open WebUI 等 AI 工具是“游戏卡带”。用户无需研究底层代码，只需掌握“插入卡带（拉取镜像）”、“开机/关机（启动/停止容器）”即可。

  • 检查 CPU 虚拟化：

    • 快捷键 Ctrl + Shift + Esc​ 打开任务管理器 -> 性能​ -> CPU​ -> 查看 虚拟化 状态是否为“已启用”。
    • 若未启用，需重启电脑进入 BIOS 开启。方法因主板/品牌而异，可搜索 [电脑品牌/主板型号] 开启虚拟化教程。大多数现代电脑默认已开启。

2. Docker Desktop 下载与安装流程

  • 确认系统架构：快捷键 Win + X​ -> 系统​ -> 查看 系统类型。

    • ​基于 x64 的处理器​ -> 下载 AMD64 版本。
    • ​基于 ARM 的处理器​ -> 下载 ARM64 版本。
    • 绝大多数 Windows PC 选择 AMD64 即可。

  • 安装配置选项：

    • ​Use WSL 2 instead of Hyper-V​：必须勾选。WSL 2 性能更优，是现代 Windows 运行 Linux 容器的标准方案（Windows 家庭版默认即为此模式）。
    • ​Add shortcut to desktop：建议勾选，方便后续管理。
    • 保持默认的 Windows 模式运行。

  • 初始化设置：安装完成后重启电脑。首次启动需接受 EULA 协议。登录界面可直接点击 Skip（跳过），本地部署开源工具无需 Docker 账号。

3. WSL 2 环境配置与升级方案

若首次启动提示 WSL 版本过旧，需升级至最新版本：

  • 方法一：命令行自动更新

    1. ​Win + X​ -> 打开 终端 (管理员)​ 或 Windows PowerShell (管理员)。
    2. 输入命令 wsl --update 并回车，等待更新完成。
    3. 验证版本：输入 wsl -v，显示最新版本即成功。

  • 方法二：GitHub 手动安装（网络不佳时备用）

    1. 访问 GitHub microsoft/WSL​ 仓库 -> Releases​ -> 找到最新 Latest 版本。
    2. 下载对应架构的 .msi​ 安装包（x64​ 或 ARM64）。
    3. 双击安装即可。若无法访问 GitHub，可使用视频简介提供的网盘备用包。

  • 升级完成后，返回 Docker 报错界面点击 Restart 即可正常运行。

4. Docker Desktop 界面汉化指南

  1. 完全退出 Docker：关闭主窗口后，右键点击系统托盘右下角的 Docker 鲸鱼图标 -> Quit Docker Desktop，确保后台进程彻底关闭。

  2. 下载汉化补丁：

    • 访问汉化项目 GitHub Releases 页面。
    • 下载以 App-Windows​ 开头的文件。选择标准版（非 Beta），架构选 x64​（ARM 平板选 ARM64）。

  3. 替换语言文件：

    • 右键桌面 Docker 图标 -> 属性​ -> 打开文件所在的位置​ -> 返回上一级目录 -> 进入 resources 文件夹。
    • 找到 app.asar​（语言配置文件）。不要直接删除，将其重命名为 app.asar.bak 作为备份。
    • 将下载的汉化包重命名为 app.asar​，并粘贴至 resources 文件夹内。

  4. 重新启动 Docker Desktop，界面即显示为中文。

5. 核心架构解析：镜像、容器与数据持久化

  • 镜像 (Image) ：相当于软件的 .exe 安装包或游戏光盘，是静态的只读模板。

  • 容器 (Container) ：镜像运行后的实例，相当于正在运行的软件进程。可随时启动、暂停、删除。

  • 卷 (Volume) / 目录挂载 (Bind Mount) ：数据持久化的关键。用于保存 n8n 工作流、数据库等核心数据。若不配置，删除容器后所有数据将永久丢失。

    • ​Bind Mount：将容器内目录映射到本地指定文件夹。优点：文件可见易管理，跨设备迁移只需拷贝文件夹。
    • ​Volume：由 Docker 托管的独立存储区。优点：首次创建会自动同步容器内原有数据；缺点：数据默认存放在 WSL 内部文件系统，直接访问需借助工具或命令行，对新手稍显隐蔽。

6. 关键配置优化：存储路径迁移与镜像源加速

  • 迁移数据存储位置（节省 C 盘空间） ：

    1. 在 D 盘或其他大容量磁盘新建文件夹（如 D:\DockerData）。
    2. Docker 设置 -> Resources​ -> Disk image location​ -> Browse​ -> 选择新建文件夹 -> Apply & restart​ -> 弹窗选择 Move。后续所有镜像与容器数据将统一迁移至新路径。

  • 配置国内镜像源（解决下载慢/超时） ：

    1. Docker 设置 -> Docker Engine。

    2. 在 JSON 配置文件中添加或修改 registry-mirrors 字段。格式示例：

      1
      2
      3
      4
      "registry-mirrors": [
        "https://docker.1ms.run",
        "https://docker.xuanyuan.me/"
      ]

    3. 注意保持 JSON 语法正确（注意英文逗号分隔）。配置完成后点击 Apply & restart​。若未来镜像失效，可前往 GitHub 搜索 Docker registry mirror 获取最新可用地址。

7. 图形化界面 (GUI) 部署 n8n 全流程

  1. 搜索镜像：顶部搜索栏输入 n8n​ 回车。结果来自 Docker Hub，优先选择 Downloads​（下载量）和 Stars（星标数）最高的官方或高信誉镜像。

  2. 拉取与运行：点击 Pull​ 下载镜像，或直接点击 Run（若本地无镜像会自动拉取后运行）。

  3. 基础配置：

    • ​Container name​：自定义名称（如 n8n1），留空则默认生成。

    • ​Port mapping​：设置 Host Port​（如 8081​）映射到 Container Port​（n8n 默认为 5678​）。配置后通过浏览器访问 http://localhost:8081 即可打开。

    • ​Storage：选择数据持久化方式。

      • 若用 Bind Mount​：点击 Host path​ 右侧 ...​ 选择本地文件夹（建议命名如 n8n_data​）。Container path​ 需填写软件内部数据路径（n8n 通常为 /home/node/.n8n​，可在官方文档或镜像页 Volumes/Data 说明中查找）。
      • 若用 Volume：直接输入卷名或留空自动生成。

    • ​Environment variables：保持默认即可。

  4. 启动与验证：点击 Run​，容器状态变为绿色即运行成功。在浏览器输入 localhost:端口号 访问。GUI 界面提供直观的启停按钮（蓝色方块停止/绿色播放键启动）。

8. 命令行 (CLI) 部署与管理 n8n

官方文档或 AI 通常提供完整的 docker run 命令，适合批量部署或自动化：

  • 创建数据卷（可选） ：docker volume create n8n_data

  • 运行命令结构解析：docker run -d --name n8n2 -p 8082:5678 -v n8n_data:/home/node/.n8n n8nio/n8n

    • ​-d：后台运行 (Detached)。
    • ​--name：指定容器名称，避免冲突。
    • ​-p 主机端口:容器端口：端口映射。注意避免与已运行容器端口冲突。
    • ​-v 卷名或本地路径:容器内路径：数据挂载。
    • ​--rm​：注意此参数。若添加，容器停止后会自动删除。日常频繁使用的工具建议去掉此参数，以便保留容器状态。

  • 网络异常处理：若命令执行时报连接超时，通常是官方镜像源在国内不稳定。在配置好国内镜像源后，直接删除原命令中的镜像前缀或重新运行，Docker 会自动走镜像源加速拉取。

9. Docker 常用命令速查表

  • ​docker ps：查看当前正在运行的容器。
  • ​docker ps -a：查看所有容器（含已停止的）。
  • ​docker stop <容器名>：停止指定容器。
  • ​docker start <容器名>：启动已停止的容器。
  • ​docker rm <容器名>：删除容器（需先停止）。
  • ​docker rmi <镜像名>​：删除镜像（前提：必须先删除所有基于该镜像创建的容器，否则报错）。
  • 命令前缀统一为 docker，所有参数与容器名之间用空格分隔。

10. Docker 彻底卸载与清理步骤

若需完全移除 Docker 及所有残留数据，请按顺序执行：

  1. 清理容器：进入 Containers​ 标签 -> 停止所有运行中的容器 -> 点击垃圾桶图标逐一删除。

  2. 清理镜像：进入 Images​ 标签 -> 删除所有已下载的镜像。

  3. 清理卷：进入 Volumes​ 标签 -> 删除所有数据卷。

  4. 退出程序：右键系统托盘鲸鱼图标 -> Quit Docker Desktop。

  5. 系统卸载：通过 Windows 设置 -> 应用 -> 安装的应用​ 或 控制面板 -> 程序和功能 卸载 Docker Desktop。

  6. 清理残留文件：手动检查并删除以下路径的残留文件夹（若存在）：

    • ​%LOCALAPPDATA%\Docker
    • ​%PROGRAMDATA%\DockerDesktop
    • WSL 相关发行版（如 docker-desktop-data​）可通过 wsl --unregister docker-desktop-data 命令彻底清除。

‍