很多常年在 Windows 10 上做开发的朋友第一次看到 Dify 这个 LLM 应用开发平台时第一反应基本是“我想试试”第二步就开始头疼怎么部署。Dify 不是单机程序它背后要拉起 API 服务、Worker、Web 前端、Postgres、Redis、向量数据库、Sandbox 等一整组容器原生在 Windows 上逐个安装这些组件基本是给自己找不痛快。用 Docker 部署是公认最顺的方式。这篇文章就是我的完整安装步骤记录也是给同样在 Windows 10 上折腾 Docker 和 Dify 的同学一份可照做的路径图从开启 WSL2、装 Docker Desktop到拉取 Dify 源码、配置环境变量、用 Docker Compose 启动整套服务再到初始化账号、接入模型、创建聊天应用最后讲运维备份和常见故障排查。内容面向新手到进阶用户只要你照着步骤走大概半小时内就能看到一个能对话的 Dify 应用跑起来。1. 项目全貌与思路拆解1.1 为什么要用 Docker 在 Windows 上运行 Dify先说清楚一件事Dify 不是单一可执行文件它是一个完整的平台。从功能上看你用它可视化地编排大模型应用、搭 RAG 知识库、做 Agent 工作流但底层至少有这样几类组件在协作Web 前端你登录后在浏览器里拖拽、配置、调试的界面API 服务接收前端请求把对话、知识库检索、工作流执行等逻辑转发给对应组件Worker处理异步任务比如知识库文档切分、索引构建、定时任务Postgres存应用、用户、对话记录、配置信息Redis做缓存和消息队列向量数据库Dify 默认用 Weaviate也可以换 Qdrant 或 Milvus知识库的向量检索靠它Sandbox运行用户自定义代码的安全沙箱Nginx统一入口做反向代理如果你不用 Docker就得在 Windows 上手动装 Postgres、Redis、Weaviate再配置 Python 环境、Node 环境还要处理版本兼容问题。光是安装和调通中间件就能耗掉一整天。Docker Compose 解决的就是这个问题所有组件打包成镜像用一个编排文件统一拉起端口、网络、环境变量都提前定义好你在宿主机上只需要装一个 Docker Desktop剩余的都交给容器。我在实际使用中最深的体会是Docker 方案不只是省了安装过程还带来一个隐性好处升级和回滚非常可控。Dify 迭代很快每次我拉新版本先把旧镜像停掉再用新镜像启动不满意还可以切回旧版本整个过程不污染 Windows 本身的 Python、Node、数据库环境。1.2 安装方案选型WSL2 还是 Hyper-V在 Windows 10 上装 Docker Desktop安装向导会让你选择后端有两个选项WSL2 和 Hyper-V。这个选择直接决定后续性能表现和运维复杂度。Hyper-V 是 Windows 自带的虚拟化平台Docker Desktop 会创建一个专用的 Linux 虚拟机来跑容器。它的问题在于资源固定你需要在 Docker Desktop 设置里手动分配 CPU 和内存分配多了占资源分配少了系统卡顿。而且 Hyper-V 虚拟机和 VMware、VirtualBox 这类第三方虚拟机软件有冲突如果电脑里既有 Hyper-V 又在用 VMware启动时经常报错。WSL2 则是基于 Windows 的“虚拟机平台”功能实现的轻量级 Linux 子系统它和 Docker Desktop 配合得更紧密。Docker Desktop 在 WSL2 后端下创建的 Linux 环境会动态使用宿主机内存不需要预先分配一大块固定内存用完还能释放这对开发机来说太重要了。我的笔记本是 16GB 内存跑完整套 Dify 后用 Docker Desktop 自带的监控看整套容器加 WSL2 大约吃掉 6GB 左右如果切到 Hyper-V 后端内存会多吃很多。所以我推荐选择 WSL2。下面的步骤全部基于 WSL2 后端来写。2. 环境准备Windows 10 与 WSL2 前置条件2.1 系统版本、硬件与 BIOS 检查清单配置环境前先花五分钟把基础条件确认一遍别稀里糊涂装了半天最后发现系统不支持。检查项要求说明Windows 版本Windows 10 2004 及以上Build 19041老版本系统自带的功能组件不同装 WSL2 内核更新包容易失败CPU支持虚拟化并在 BIOS 中开启 VT-xIntel或 SVMAMD在任务管理器-性能-CPU 页面可以看到“虚拟化已启用”内存至少 8GB推荐 16GB 以上Dify 全家桶跑起来后容器会占用不少内存8GB 会很吃力磁盘至少预留 20GB 可用空间镜像加数据卷加起来不小WSL2 的文件系统还会随使用增长操作系统架构64 位 x86/ARM6432 位系统带不动这套东西最容易踩坑的是虚拟化没开启。有些人电脑在 BIOS 里默认关掉了 VT-x装完 WSL2 或 Docker Desktop 会提示“需要启用虚拟机平台”或者“无法启动 WSL2”排查到最后才发现是 BIOS 的问题。如果任务管理器显示虚拟化未启用进 BIOS 找到 Intel Virtualization Technology / SVM Mode 改成 Enabled保存重启后再继续。内存这块我多说一句。官方文档说最低 2GB 就能跑但那是理想条件。我实测在 8GB 内存的机器上跑启动完成后内存基本被吃满滚动日志都卡更别说再开浏览器去调试对话应用。如果你只有 8GB建议安装前先关掉其他大型软件或者单独给 Docker Desktop 限制资源否则体验会很糟糕。2.2 启用 WSL2 的具体操作确认前置条件没问题后开始启用 WSL2。整个操作都在管理员权限的 PowerShell 或 CMD 里执行。第一步启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个 Windows 功能dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart第一条命令启用 WSL第二条启用虚拟机平台这是 WSL2 的核心依赖。执行完会提示“是否立即重启”先不用急如果多条命令都执行完了再统一重启。第二步重启电脑。第三步重启后依然用管理员 PowerShell把 WSL 默认版本设置为 2wsl --set-default-version 2如果提示“需要更新 WSL 内核”说明当前系统的 WSL 内核版本太老需要去微软官网下载 WSL2 Linux 内核更新包下载后双击安装然后重新执行上面的命令。第四步验证 WSL 状态wsl --status wsl --list --verbosewsl --status会显示默认版本是否为 2wsl --list --verbose会列出已安装的 Linux 发行版如果没有发行版也没关系Docker Desktop 会自动创建一套专用的后端环境不依赖你手动安装 Ubuntu。装到这里有个细节如果之前电脑上安装过 WSL1 的发行版想把它从版本 1 转换到版本 2可以这样wsl --set-version 发行版名称 2不过对 Docker 来说这个转换动作可以交给 Docker Desktop 自动完成大多数情况下你不需要手动干预。2.3 安装与配置 Docker DesktopWSL2 就绪后接着装 Docker Desktop。安装包从 Docker 官网下载 Windows 版本安装过程中保持默认选项即可重点注意一点安装向导中会出现“Use WSL 2 instead of Hyper-V”的选项务必勾选它。装完后第一次启动会提示配置 WSL2 后端直接接受。装完后打开 Docker Desktop会自动启动 Windows 上的 Docker Engine。右上角的鲸鱼图标如果稳定不动说明服务正常。如果一直处于 “Docker Desktop is starting...” 状态常见原因是虚拟机平台功能没启用成功或者内核更新包没装回到上一步排查。接下来做一些必要的设置都是为了后面拉镜像更顺利打开 Docker Desktop 的 Settings进入 Resources 标签页。在 Advanced 里可以调整 CPU 和内存。默认分配的 WSL 内存是宿主机的一半左右如果你的物理内存是 32GB容器其实用不到那么多可以把内存调到 8GB 或 12GB把多出来的留给 Windows 本身。在 Resources 的 WSL Integration 标签页里确认 WSL integration 已开启。在 Docker Engine 标签页里可以配置镜像加速地址。加上你自己网络环境下能稳定访问的镜像加速器拉到镜像的速度会有明显改善。配置完点击 Apply Restart 让 Docker Desktop 重启。完成后再验证环境是否正常在 CMD 或 PowerShell 里执行docker version docker compose versiondocker version应该同时显示 Client 和 Server 的信息注意 Server 部分不要报错。docker compose version会输出 Compose 插件的版本号Docker Desktop 自带新版 Compose V2旧版docker-compose命令不一定可用所以后面我们都用docker compose中间有空格。再跑一个最小的容器做测试docker run hello-world如果能看到 “Hello from Docker!” 的输出说明整个 Docker 环境已经能正常拉取和运行容器前置条件全部完成可以进入 Dify 安装阶段了。3. 获取 Dify 源码与环境变量配置3.1 下载 Dify 源码包Dify 的官方仓库在代码托管平台上安装需要的所有编排文件都在里面。有两种方式获取源码任选一种。方式一用 git 拉取。打开 CMD 或 PowerShell切换到你希望存放项目的目录执行git clone https://github.com/langgenius/dify.git如果你不习惯命令行看 log也可以直接在仓库页面下载 ZIP 包解压后效果一样。我习惯用 git因为后续升级时git pull一条命令就能拉新版本比重新下载替换更不容易出错。进入项目目录cd dify里面会有多个目录和 Docker 部署相关的主要是docker目录。你可以在文件管理器里打开docker目录也可以直接用命令行进入cd docker确认目录下存在三个核心文件.env.example环境变量模板docker-compose.yaml所有容器的编排定义.env实际生效的环境变量文件这个文件初始不存在需要你从模板复制生成3.2 按需编辑 .env 配置在docker目录下先把模板复制成真正的环境变量文件cp .env.example .env然后打开.env文件重点检查几个关键配置项。Windows 下我推荐用 VS Code 或 NotePad 编辑记事本也可以但要注意文件编码不要改成带 BOM 的 UTF-8否则后续解析环境变量可能出问题。第一个必须改的是SECRET_KEY。这是 Dify 的加密密钥用来给会话、密码、Token 做签名。默认值是模板里的占位符直接使用有安全隐患而且如果多个实例共用默认值会存在会话伪造风险。你可以用命令生成一串随机字符串openssl rand -base64 42把输出的内容复制填到.env里SECRET_KEY这里填你生成的随机字符串如果没有 openssl也可以去在线随机字符串生成工具生成一个足够长的强随机字符串关键是长度要到 32 字节以上。第二个建议修改的是POSTGRES_PASSWORD。这是数据库的密码默认也是模板值。同样的原因部署到正式环境前要改掉。要注意一点密码字符串最好只包含大小写字母和数字不要包含$、#、、空格这类特殊字符否则在.env解析和 Docker 环境变量传递时容易出现转义问题。我当初设置密码时用了结果数据库容器起来后一直报密码错误排查了半天后来把特殊字符去掉就好了。第三个需要确认的是端口。.env里有两个端口相关项EXPOSE_NGINX_PORT80 EXPOSE_POSTGRES_PORT5432EXPOSE_NGINX_PORT是 Dify 对外访问的端口默认 80。如果你机器上已经有 IIS、Apache 或者其他程序占用了 80 端口这里就要改成别的端口比如EXPOSE_NGINX_PORT8080注意改掉之后后续访问地址就不是http://localhost而是http://localhost:8080初始化安装路径也要跟着变成http://localhost:8080/install。EXPOSE_POSTGRES_PORT默认 5432如果本机已经装了 Postgres 数据库端口就会冲突可以改成 5433。这个端口不直接暴露给外部访问内部容器之间是通过网络别名连接的所以只改宿主机映射端口不影响 Dify 内部逻辑。改完.env后先保存不用急着做其他操作。如果你对某些配置不确定保持默认比乱改安全只要把上面说的几项确认好就行。4. 拉取镜像并启动容器4.1 Dify 容器拓扑初识不看懂容器拓扑后面出问题排查会非常迷茫。Dify 的docker-compose.yaml定义了大约 8 个主要服务它们的名称和职责如下表。容器服务职责依赖nginx对外统一入口反向代理到 Web 和 APIweb、apiweb前端界面负责页面渲染和用户交互apiapi核心后端服务处理业务逻辑、对话请求、工作流db、redisworker异步任务执行者文档解析、向量索引、定时任务db、redisdbPostgres 数据库存储业务数据无redis缓存和消息队列协调 API 与 Worker 的异步通信无weaviate默认向量数据库存储知识库文档向量无sandbox代码执行沙箱安全运行用户自定义代码api它们的协作关系可以这样理解浏览器请求先打到 nginxnginx 把静态资源请求转发给 web把 API 请求转发给 api。api 收到请求后如果是普通对话直接查数据库里的配置再调用大模型如果涉及知识库api 会把文档切片后发给 worker 异步处理worker 写进向量数据库最终结果由 api 整理后返回给前端。启动容器前记住一点“容器全部是 Up”不代表 Dify 已经可用还需要等数据库迁移完成。这个状态我后面专门说。4.2 docker compose 启动全流程确认.env配置无误后在docker目录下执行启动命令docker compose up -d-d参数表示后台运行不占用当前终端。第一次执行时Docker 会自动拉取docker-compose.yaml里定义的所有镜像。整个过程取决于你的网络环境通常需要几分钟到十几分钟不等。如果某个镜像拉取失败Compose 会重试几次最终如果还是失败整个启动流程会被中断。启动完成后用下面的命令查看容器状态docker compose ps正常情况下所有服务的STATUS都是Upruntime 几秒。如果有容器显示Exit 1或不断重启Restarting说明某个容器启动异常先别急着循环重启看日志定位问题。查看某一个容器的日志docker compose logs -f api-f表示持续跟随输出日志会一直滚动。这条命令是排查问题的核心工具后面会反复用到。也可以一次性查看所有容器的日志输出但比较杂我通常只针对具体容器看。启动阶段最容易出问题的是api和db因为后端服务启动前要先连数据库如果数据库还没就绪api 会一直报连接错误并反复重启。遇到这种情况不用慌等一小会儿让 db 完成初始化api 会自动恢复。4.3 镜像拉取慢的应对建议Dify 的镜像整体体积比较大主要有langgenius/dify-api、langgenius/dify-web、langgenius/dify-sandbox再加上weaviate、postgres、redis、nginx加起来接近 3GB。如果网络环境不太好拉取时间会很长还容易超时失败。我的经验是从几个方面入手能显著降低失败概率第一配置镜像加速器。上一章已经提过在 Docker Desktop 的 Settings 里打开 Docker Engine 配置页把镜像加速器地址加到registry-mirrors数组里。保存并重启 Docker Desktop。注意不同网络环境下能稳定访问的加速器地址不一样你需要选择自己网络能够稳定连接的不要照抄别人的配置。第二手动预拉取。启动 Compose 之前先单独执行docker compose pull这条命令会把所有镜像提前拉取一遍拉取过程中每个镜像的状态都会显示出来。哪个镜像失败就单独重试哪个避免docker compose up启动到一半才因为某个镜像失败而回滚。如果某一次 pull 超时多执行几次大部分时候第二次、第三次就能成功。第三给 Docker Desktop 增大资源限制。镜像解压需要临时空间磁盘余量不足也会导致拉取后无法解压报 “no space left on device”。确保 Windows 上系统盘至少有 15GB 以上可用空间WSL2 虚拟磁盘所在的目录空间也要足够。镜像全部拉取成功后再执行docker compose up -d就会快很多。5. 在线初始化、账号创建与模型接入5.1 等待后端服务和数据库就绪容器全部启动后第一次访问 Dify 页面大概率会看到 502 Bad Gateway。这是正常现象Dify 的 api 容器首次启动时要对 Postgres 执行数据库建表和初始化脚本这个过程可能持续一两分钟。你可以通过日志判断初始化进度。打开一个终端进入docker目录执行docker compose logs -f api如果日志里出现Database is ready. Running database migration...说明正在迁移数据库。迁移完成后日志会继续滚动直到 api 完全启动。另一个判断方法是直接检查数据库表是否创建成功。执行docker compose exec db psql -U postgres -l如果能看到 Dify 相关的数据库名称以及一系列public.*的表说明初始化基本完成。如果你不熟悉 psql也可以简单等上几分钟再去浏览器刷新页面。当 api 日志稳定下来不再有报错再访问http://localhost/install如果你改了EXPOSE_NGINX_PORT就把端口带上。此时如果页面正常显示设置管理员账号的表单说明整个初始化流程已经走通了。5.2 浏览器安装向导与管理员账号浏览器打开安装向导后页面上会要求设置管理员账号包括邮箱、密码和姓名。密码建议用强密码因为后续所有应用的管理权限都在这个账号下。填完提交系统会完成最后的初始化然后自动跳转到登录页。用刚才设置的邮箱和密码登录就能看到 Dify 的主界面了。主界面默认有一个“概览”页展示当前实例的基本信息左下角是“设置”右上角是“新建应用”入口。这里有一个常见疑问如果之前已经初始化过一次再次访问/install会提示“系统已初始化”不会再让你重复设置管理员。如果你想重置整个系统重新初始化需要删除数据库卷再重启这是个比较重的操作后面卸载章节会讲到非必要不建议做。登录后还会看到提示要求你设置模型供应商。别急着跳过因为 Dify 本身不是一个完整的大模型服务它需要接入外部的模型 API 才能真正运行对话应用。这一步我放下一节讲。5.3 接入大模型供应商并跑通对话在 Dify 里模型是通过“模型供应商”接入的。各家模型服务商都支持 OpenAI 兼容的 API 协议所以 Dify 的接入方式很统一填写 Base URL、API Key、模型名称。进入“设置”页面选择“模型供应商”点击添加模型供应商选择一个你有的服务商。通常需要填这几个字段API Key你在模型服务商后台申请的密钥Base URL模型服务的接口地址一般用服务商文档里给的默认值模型名称你实际要使用的模型标识比如某些服务的gpt-xxx、qwen-xxx对应关系需要以服务商文档为准填写完成后Dify 会调用一次接口做连通性验证验证通过后该模型会出现在模型列表中。你可以在同一页面对模型进行“可用性测试”输入一句话看能不能正常回复。如果你手头还没有任何模型服务的 API KeyDify 也支持接入本地开源模型可以通过 Ollama 这类工具跑起来后在本地提供 OpenAI 兼容接口再把接口地址填进模型供应商里。这样整条链路就完全本地化了不依赖外部网络。模型接入成功后先做一个最简单的验证在 Dify 主界面点击右上角“新建应用”选“聊天助手”。创建后进入对话调试页面右侧选择模型左侧输入一句话点击发送能收到模型回复就说明端到端链路已经打通。到这一步Dify 的核心安装就算全部完成。6. 快速验证创建一个聊天应用6.1 新建聊天助手应用安装完成后大多数人想做的第一件事就是看看 Dify 到底能不能像宣传中那样低代码搭应用。我来演示一个从零创建聊天助手的完整过程。在 Dify 主界面点击“新建应用”选择“聊天助手”模板给应用起个名字比如“旅游攻略助手”。创建后会进入应用编排界面左侧是对话调试区中间是机器人设置区右侧是发布信息区。关键操作是编排区的“提示词”和“模型”设置。先选择你刚才接入的模型然后在提示词框里写清楚这个机器人的角色和任务。比如你是一名资深旅游规划师。用户会告诉我目的地、天数和偏好请输出一份包含每日行程、推荐餐厅、注意事项的旅行攻略内容要具体可行。写完点“发布”应用就上线了。之后回到左侧调试区输入一句“我想去云南玩 5 天喜欢自然风景和文化特色”点击发送模型会按你设定的角色返回一份旅行攻略。Dify 的一个特色是调试区左侧可以实时查看对话的完整链路信息包括模型调用参数、消耗的 Token、提示词模板处理结果。这比直接调 API 直观得多也是我用它做原型验证最顺手的地方。6.2 通过 WebApp 和 API 联调发布应用后Dify 会生成一个 WebApp 访问地址在编排页面右侧的“访问”发布信息区域可以看到。这个地址可以直接发到浏览器打开是一个独立的聊天界面不用登录 Dify 后台就能使用。我常把这个地址发给同事做快速体验比自己截图传话高效多了。如果你的应用需要嵌入到其他系统还可以走 API 模式。在 Dify 顶部菜单栏进入“API 访问”页面里面能查到这个应用专属的 API Key。调用方式非常简单Dify 的 API 遵循 OpenAI 兼容风格。比如发送一条对话消息curl --location --request POST http://localhost/v1/chat-messages \ --header Authorization: Bearer app-你的API密钥 \ --header Content-Type: application/json \ --data-raw { inputs: {}, query: 你好帮我规划一次杭州两日游, response_mode: blocking, user: test-user }如果改了 Nginx 端口把 URL 里的localhost后面加上对应端口。返回结果里会包含模型回复文本、消息 ID、Token 使用量等内容。到这里一个可以对话的 Dify 应用已经跑通。接下来我重点聊运维和故障排查因为这部分内容在我最初折腾时踩了最多的坑写出来能帮大家省不少时间。7. 常见问题排查实录7.1 端口冲突的处理端口冲突是 Windows 部署 Dify 时最常遇到的问题之一。症状是启动后访问http://localhost显示的却不是 Dify 页面或者docker compose up -d直接报错提示port is already allocated。先找到是谁占用了端口。在管理员 CMD 里执行netstat -ano | findstr :80最后一列是进程 PID。再用tasklist | findstr PID号就能看到占用 80 端口的程序。如果是系统自带的 IIS 或者某个本机服务占用了 80 端口解决方案就是在.env里修改EXPOSE_NGINX_PORT改成 8080 或其他空闲端口。改完执行docker compose up -dCompose 会自动重建端口映射的容器不需要删除所有容器。注意如果你只修改了.env而没有重启Docker 不会自动重新读取环境变量必须重新执行docker compose up -d触发容器重建才会生效。7.2 镜像或容器启动失败容器启动失败时最直接的排查方式是查看日志docker compose logs -f 容器服务名几种常见的启动失败情况第一db容器反复重启。多半是POSTGRES_PASSWORD和.env不一致或者数据库数据目录被之前失败初始化写坏了。如果是密码原因改完密码后要清掉旧的数据卷才能生效因为 Postgres 只在首次初始化时使用密码。第二api容器启动失败日志里报connect ECONNREFUSED db:5432。这是 api 启动早于 db数据库还没监听端口。解决方式是等一会儿或者执行docker compose restart api让它重连。如果长期如此检查 db 容器是否正常。第三镜像运行起来后提示架构不兼容。Windows 的 ARM64 机器和 x86 的 Docker 镜像不能混用你需要在 Docker Desktop 设置里开启“使用 Rosetta 模拟 x86_64”否则某些不支持 ARM 的镜像会报 exec format error。第四sandbox 容器启动失败。Dify 的沙箱组件对内核要求较高WSL2 内核太旧时会启动失败。尽量保持 WSL2 内核更新到最新版更新方法是执行wsl --update7.3 数据库迁移与页面 502我见过最多的问题是容器全部 Up但浏览器打不开 Dify 页面提示 502 Bad Gateway。原因逻辑其实很简单请求从 nginx 进来nginx 反代到 apiapi 如果还没就绪nginx 就只能返回 502。而 api 没就绪的常见原因就是数据库迁移还没有完成。查看 api 日志docker compose logs -f api如果日志停在Running database migration...或者反复出现连接数据库失败说明迁移没有正常结束。此时先确认 db 容器健康docker compose psdb 应该是 Up。再执行docker compose exec db psql -U postgres -c select 1;如果这个命令返回1说明数据库本身没问题问题多半出在 api 和 db 之间的网络或者 api 的启动逻辑。可以先重启 apidocker compose restart api然后重新观察日志。另一种情况是迁移卡在某一步比如日志停在Create index...不动可能是数据库中已有重复数据或索引可以清理掉旧卷重新初始化或者查阅对应版本升级脚本这里如果复杂可以直接在 Dify 社区搜版本相关迁移问题。遇到 502 千万不要反复docker compose up -d多次因为这不解决问题还可能把正在执行的迁移过程打断。耐心看日志比盲目重启有效得多。7.4 宿主机重启后的恢复Windows 重启后Docker Desktop 默认会自启但容器不会自动恢复。你打开浏览器访问 Dify大概率会连接失败。正确的恢复姿势是先确认 Docker Desktop 已经启动托盘图标稳定然后打开 CMD 进入docker目录执行docker compose start或者直接用之前的方式再把整套拉起来docker compose up -d两个命令效果接近。如果你想做到重启后完全不用手动操作可以把 Docker Desktop 设为开机自启并且在 WSL 里配置自动启动 Docker 服务。具体做法是在 WSL 发行版中编辑/etc/wsl.conf加入[boot] systemdtrue并把 Docker Desktop 的服务设置为 systemd 管理。这样 WSL 启动时会自动拉起 Docker Engine。不过这个配置在 Docker Desktop 的 WSL Integration 已经开启的情况下一般不需要折腾我手动执行docker compose start也就一分钟的事。7.5 常见问题速查表问题可能原因处理方法80 端口被占用本机其他程序占用了端口修改 .env 的 EXPOSE_NGINX_PORT再 docker compose up -d镜像拉取失败网络不稳或镜像源问题配置镜像加速器docker compose pull 多次重试db 容器退出密码不正确或数据目录损坏检查 POSTGRES_PASSWORD必要时清理数据卷重建api 连接数据库失败db 还没就绪等待或 docker compose restart api页面 502数据库迁移未完成查看 api 日志等迁移结束必要时重启 api容器启动报 exec format errorARM 机器跑 x86 镜像开启 Docker Desktop 的 Rosetta 模拟或换用 ARM 镜像重启后无法访问容器未自动启动进入 docker 目录执行 docker compose start宿主机内存不足容器占资源太多或机器内存小在 Docker Desktop 里限制 CPU/内存减少并行任务8. 日常运维备份、升级与卸载8.1 数据备份与恢复Dify 里最需要备份的是 Postgres 数据库它是所有用户、应用、对话记录、配置信息在磁盘上的存在形式。备份命令可以这样执行cd dify/docker docker compose exec db pg_dump -U postgres postgres backup_20241115.sql这样会把整个 Dify 数据库导出成一个 SQL 文件。恢复时执行docker compose exec -T db psql -U postgres postgres backup_20241115.sql注意 Windows CMD 和 PowerShell 对重定向的处理略有不同PowerShell 里路径解析更严格建议备份和恢复都在 CMD 下操作。除了数据库还需要备份两个东西一个是docker/dify/docker目录下的.env文件环境变量丢失会造成新容器无法正确连接另一个是volumes目录里面存放着上传的文件、知识库的原始文档、向量数据库数据等。如果你用了 Weaviate 存知识库也要把它对应的 volume 一并备份。最好的备份时间点是版本升级前和定期维护时。有了备份升级失败也能快速回滚这是运维的最底线。8.2 版本升级流程Dify 版本更新非常频繁升级流程不算复杂但顺序不能乱。第一步备份。用上一节的方法备份数据库和.env这是必须做的。在我经验里没见过升级不触发数据库迁移的情况迁移失败时如果没有备份恢复的成本会很高。第二步拉取新版本代码。如果你当初用的是 git clonegit pull origin main如果你想升级到指定 release tag可以先看官方仓库的 release 页面然后用git checkout 目标版本号第三步进入docker目录先停止旧容器docker compose down注意这里不是down -v-v会删除数据卷不能用在这。第四步拉取新镜像并启动docker compose pull docker compose up -d启动后数据库会自动执行迁移等待 api 日志稳定后访问 Dify 页面验证核心功能是否正常。假如升级后发现问题想回滚到旧版本更稳妥的做法是先docker compose down然后用备份的数据库恢复再切回旧代码版本重新docker compose up -d。整个过程都依赖第一步的备份。8.3 彻底卸载与清理如果哪天不想要这套系统了彻底卸载也有讲究。先备份需要的数据。然后停止并删除容器和网络docker compose down如果确定不需要保留任何数据可以连数据卷一起删除docker compose down -v-v参数会删掉所有由 Compose 创建的数据卷数据库内容、上传文件、向量库全部清空。这是一条不可逆的命令执行前想清楚。接下来退出 Docker Desktop然后在 Windows 的“应用和功能”里卸载 Docker Desktop。如果 WSL2 里安装过相关发行版可以执行wsl --unregister 发行版名称最后手动删除之前 clone 下来的dify目录即可。谈到彻底卸载我顺便说一个使用习惯上的建议Dify 的数据和代码最好放在同一个固定目录下不要频繁移动。因为 WSL2 的文件系统访问方式和 Windows 文件系统不同如果把项目放在/mnt/c/这种挂载目录文件 I/O 性能会比放在 WSL 原生文件系统里差很多特别是在知识库文档解析这种磁盘密集型任务里差异很明显。我自己后来把项目放到了 WSL2 的原生目录里docker compose 构建和日志输出都流畅了不少。结尾个人实操体会在 Windows 10 上把 Dify 完整跑通之后我最深的三个感受是第一Docker Compose 这种一键拉起整套依赖的方式对本地开发环境来说几乎是唯一正确的解。你不需要关心 Postgres 在哪装、Redis 配置改哪里只需要维护一份.env容器的可复制性和可恢复性都远超手工部署。第二资源规划比想象中重要。Dify 不是那种轻量的单容器应用它在 Windows WSL2 下跑起来后内存和磁盘占用都要提前留好余量建议至少 16GB 内存起步。第三日志真的是排障最好的朋友。每次遇到容器起不来或者页面打不开我不急着反复重启而是先看docker compose logs大部分问题都能从日志里找到原因这比盲目试命令高效得多。最后再分享一个小技巧用完 Dify 后可以不关闭 Docker Desktop但建议定期执行docker system prune清理悬空镜像和缓存避免 WSL2 虚拟磁盘越撑越大。希望这份记录能帮大家把 Dify 顺利跑起来真正把精力放在应用编排本身而不是在环境安装上反复折腾。
