这次我们来看一个在 Windows 系统上基于 Docker 容器技术本地部署 Dify 开源 AI 应用开发平台的项目。对于想私有化部署 AI 能力、构建知识库或智能工作流的开发者和团队来说Dify 提供了一个可视化的低代码界面。而通过 Docker 部署可以极大简化环境配置的复杂度实现相对“一键化”的安装和启动。本文将带你完成从零开始在 Windows 10/11 系统上使用 Docker Desktop 部署 Dify 的全过程。核心内容包括Docker 环境的准备与验证、Dify 镜像的拉取与容器启动、服务访问与初始化配置以及部署后的基本功能验证和常见问题排查。整个过程重点关注实操步骤、端口占用、服务稳定性和数据持久化确保你能在本地成功运行一个功能完整的 Dify 服务。1. 核心能力速览在开始动手之前我们先快速了解通过 Docker 在 Windows 本地部署 Dify 的核心信息。能力项说明项目类型开源 AI 应用开发平台 (LLM Ops)核心功能可视化编排 AI 工作流、构建 AI 智能体 (Agent)、创建与管理知识库、集成多种大模型 API。部署方式Docker 容器化部署 (推荐)硬件门槛主要依赖网络和存储。CPU 推理对算力要求不高但若本地运行大模型则需要相应 GPU 资源。Dify 本身作为调度平台资源消耗不大。内存要求建议分配至少 4GB 内存给 Docker确保 Dify 相关容器App、API、Worker运行流畅。存储要求需要预留约 2-3GB 空间用于 Docker 镜像和初始数据。知识库文件上传会额外占用空间。支持平台Windows 10/11 (64位) 专业版、企业版或教育版。家庭版需安装 WSL 2 后端。启动方式通过docker-compose命令一键启动所有服务。是否支持 API是。Dify 提供完整的 OpenAPI可用于集成到其他系统。是否支持批量任务是。支持通过工作流批量处理文档知识库支持批量文件上传与处理。适合场景个人学习与测试、企业内部 AI 工具开发、需要数据隐私的 AI 应用原型搭建。2. 适用场景与使用边界Dify 作为一个平台其价值在于连接和调度。理解它能做什么、不能做什么有助于你判断是否值得投入时间部署。它非常适合以下场景快速原型开发无需编写大量代码通过拖拽即可构建基于大模型的对话应用、文本处理流水线。企业知识库问答将内部文档Word、PDF、PPT、TXT上传构建知识库创建专属的智能问答助手。多模型统一管理在同一个界面中管理 OpenAI、Azure、 Anthropic、国内主流大模型等多种 API 密钥和端点方便切换测试。工作流自动化将大模型调用与条件判断、代码执行、网络搜索等节点结合实现复杂的自动化任务。需要注意的使用边界非本地模型运行时Dify 默认是一个“调度器”它调用外部大模型 API如 OpenAI。如果你需要完全离线、本地运行大模型需要在 Dify 中配置本地模型 API 服务如通过 Ollama、LocalAI 等部署的本地模型这需要额外的部署步骤和显卡资源。性能依赖外部服务应用的响应速度和稳定性很大程度上取决于你所连接的大模型 API 服务的质量与网络状况。数据合规性当你使用第三方大模型 API 时提示词、上下文和生成的内容可能会经过服务提供商的服务器。如需绝对的数据隐私务必使用可本地部署的模型或确保 API 服务商符合你的数据安全要求。资源消耗虽然 Dify 本身不重但处理大量知识库文档尤其是 OCR 图片或运行复杂工作流时会对 CPU 和内存有一定压力。3. 环境准备与前置条件在 Windows 上通过 Docker 部署任何服务第一步永远是准备好 Docker 环境。以下是详细的检查清单。3.1 系统要求确认操作系统Windows 10 版本 2004 及更高内部版本 19041 及更高或 Windows 11。虚拟化支持必须在 BIOS/UEFI 中启用虚拟化技术如 Intel VT-x 或 AMD-V。可以在任务管理器 - “性能” - “CPU” 中查看“虚拟化”是否已启用。WSL 2Docker Desktop for Windows 依赖于 WSL 2适用于 Linux 的 Windows 子系统作为后端。这是必须的。3.2 安装 WSL 2如果你的系统是 Windows 家庭版或从未安装过 WSL需要手动安装。以管理员身份打开 PowerShell。运行以下命令启用 WSL 和虚拟机平台功能wsl --install这个命令会默认安装 Ubuntu 发行版。如果需要其他发行版可以先运行wsl --install -d 发行版名称。安装完成后重启计算机。重启后WSL 2 会自动完成初始化。你可以运行wsl -l -v来验证安装输出应显示一个发行版且VERSION为2。3.3 安装 Docker Desktop for Windows访问 Docker 官网下载 Docker Desktop for Windows 安装包。运行安装程序安装过程中确保勾选“使用 WSL 2 而不是 Hyper-V”如果出现此选项。安装完成后启动 Docker Desktop。首次启动可能需要几分钟进行初始化。启动成功后在任务栏托盘区可以看到 Docker 图标。右键图标选择“Settings”。在“General”设置中确保“Use the WSL 2 based engine”选项被勾选。在“Resources” - “WSL Integration”中启用与你安装的 WSL 发行版如 Ubuntu的集成。打开 PowerShell 或命令提示符运行以下命令验证安装docker --version docker-compose --version两者都应返回版本号无报错。4. 安装部署与启动方式Dify 官方提供了 Docker Compose 部署文件可以一键启动所有必需的组件包括 Web 前端、后端 API、后台 Worker 以及数据库PostgreSQL和缓存Redis。4.1 获取部署配置文件在你希望安装 Dify 的目录例如D:\Dify下打开 PowerShell。下载官方提供的docker-compose.yaml文件curl -o docker-compose.yaml https://github.com/langgenius/dify/blob/main/docker/docker-compose.yaml如果系统没有curl你也可以直接访问上述 GitHub 链接复制文件内容在本地新建一个docker-compose.yaml文件并粘贴。同时下载环境变量配置文件示例curl -o .env.example https://github.com/langgenius/dify/blob/main/.env.example将其重命名为.envcp .env.example .env # 或者在Windows资源管理器中直接重命名4.2 关键配置说明打开.env文件你需要关注并可能修改以下几个关键配置SECRET_KEY用于加密的密钥首次启动会自动生成建议保留。POSTGRES_PASSWORDPostgreSQL 数据库密码请修改为一个强密码。REDIS_PASSWORDRedis 缓存密码请修改为一个强密码。DB_PASSWORD应与POSTGRES_PASSWORD一致。CONSOLE_API_URL和APP_API_URL默认是http://localhost:5001和http://localhost:5001/v1。如果后续访问有问题可能需要根据实际情况调整例如改为服务器IP。CONSOLE_WEB_URL默认是http://localhost:3000这是 Web 管理界面的访问地址。对于最简单的本地测试你可以暂时不修改.env文件直接使用默认值。4.3 启动 Dify 服务在包含docker-compose.yaml和.env文件的目录下打开 PowerShell执行以下命令docker-compose up -d这个命令会执行以下操作从 Docker Hub 拉取 Dify 相关镜像包括 api、worker、web 等。创建并启动定义的所有容器app、api、worker、postgres、redis。-d参数表示在后台运行。首次执行会下载镜像耗时取决于你的网速。完成后可以使用以下命令查看容器状态docker-compose ps如果所有服务状态都是Up则表示启动成功。5. 功能测试与效果验证服务启动后我们通过 Web 界面进行基本的功能验证。5.1 访问 Web 管理界面打开浏览器访问http://localhost:3000。首次访问会进入初始化页面需要你设置管理员账号邮箱和密码。设置完成后使用刚设置的账号密码登录进入 Dify 控制台。5.2 基础功能验证配置模型供应商Dify 本身不提供模型需要你先配置一个可用的模型 API。在控制台点击左侧菜单栏的“模型供应商”。点击“添加模型供应商”选择你拥有的 API 服务例如“OpenAI”。填写对应的 API Key 和 Base URL如果使用官方接口Base URL 可留空。如果你暂时没有可以跳过此步但后续的对话和应用测试将无法进行。点击“保存”状态显示为“正常”即表示配置成功。5.3 核心功能测试一创建对话型应用点击左侧“应用”然后点击“创建新应用”。选择“对话型应用”输入应用名称点击“创建”。进入应用编排页面。在“提示词编排”区域你可以编写系统提示词。在右侧的“模型”区域选择你刚刚配置好的模型供应商和具体模型如 gpt-3.5-turbo。点击右上角的“发布”按钮将应用发布。发布后点击“访问应用”会打开一个独立的对话窗口。在输入框中发送一条测试消息如“你好请介绍下你自己”。如果配置正确你应该能收到 AI 的回复。这是验证 Dify 与大模型连接是否成功的最直接方法。5.4 核心功能测试二创建知识库并问答返回控制台点击左侧“知识库”点击“创建知识库”。填写知识库名称点击“创建”。进入知识库详情页点击“上传文件”选择一个本地的文本文件或 PDF 文件进行上传。上传后文件会进入“处理中”状态。Dify 会对其进行分段、向量化处理。处理完成后状态变为“已索引”。再次创建一个新的“对话型应用”或编辑一个已有应用。在应用编排页面找到并添加“知识库检索”节点。将其连接到对话流程中并选择你刚创建的知识库。发布并访问该应用。现在你的提问将优先从上传的文档中寻找答案。例如如果你的文档是关于某个产品的说明书你可以问“这个产品的主要功能是什么”。如果知识库检索配置正确AI 的回答应基于文档内容。6. 接口 API 与批量任务Dify 不仅提供 Web 界面更强大的能力在于其 API允许你将 AI 能力集成到自己的系统中。6.1 API 访问基础获取 API Key在 Dify 控制台点击右上角个人头像 - “API 密钥”可以创建新的密钥。请妥善保管此密钥。API 端点默认的 API 基础地址是http://localhost:5001/v1。你可以在.env文件的APP_API_URL中配置。认证方式在请求头中携带Authorization: Bearer your-api-key。6.2 调用对话应用 API以下是一个使用 Pythonrequests库调用已发布对话应用的示例import requests import json api_key your-dify-app-api-key # 替换为你的应用API密钥 app_id your-app-id # 替换为你的应用ID url fhttp://localhost:5001/v1/chat-messages headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { inputs: {}, query: 你好今天天气怎么样, response_mode: blocking, # 同步模式 conversation_id: , # 首次可为空后续使用返回的id以保持多轮对话 user: test-user-001 # 标识用户 } response requests.post(url, jsonpayload, headersheaders, timeout60) if response.status_code 200: result response.json() print(fAI回复{result.get(answer)}) print(f本次对话ID{result.get(conversation_id)}) else: print(f请求失败状态码{response.status_code}, 响应{response.text})注意应用 API 密钥需要在应用发布后在应用的“访问 API”设置中获取与控制台的 API 密钥不同。6.3 批量任务处理Dify 本身没有提供直接的“批量任务”API但你可以通过以下方式实现批量处理知识库批量上传通过 Dify 提供的“文档处理”API可以编程式地上传和处理大量文件到知识库。工作流批量触发如果你构建了一个工作流应用例如输入一篇新闻输出摘要和关键词你可以写一个简单的脚本循环读取一个文件夹下的所有文件依次调用该工作流应用的 API实现批量处理。使用异步模式上述 API 示例中response_mode设置为blocking同步。对于耗时的任务可以设置为streaming流式并在客户端处理或者通过conversation_id管理多轮对话的上下文实现连续的批量问答。7. 资源占用与性能观察部署完成后了解如何监控服务状态和资源消耗很重要。7.1 观察容器状态与日志查看所有容器状态docker-compose ps查看特定容器日志如 api 服务docker-compose logs api或docker-compose logs -f api-f表示跟随输出类似 tail -f。查看容器资源占用docker stats。这个命令会实时显示所有运行中容器的 CPU、内存、网络 I/O 使用情况。重点关注dify-api和dify-worker容器。7.2 性能影响因素知识库处理首次上传大量文档或高分辨率图片进行 OCR 时worker容器的 CPU 和内存使用率会显著上升。处理完成后会下降。模型 API 调用延迟Dify 应用的响应速度主要受限于你所连接的外部大模型 API 的响应时间。你可以在 Dify 的“日志与审计”中查看每次调用的耗时。向量数据库性能Dify 使用 PostgreSQL 的pgvector扩展存储向量。知识库文档数量巨大时检索速度可能会变慢。对于生产环境可以考虑使用更专业的向量数据库如 Qdrant、Weaviate但这需要修改部署配置更为复杂。网络带宽如果模型 API 在远端网络延迟和带宽会影响体验。7.3 端口占用情况默认情况下Dify 会占用以下端口3000Web 前端控制台 (dify-web)5001后端 API 服务 (dify-api)5432PostgreSQL 数据库 (dify-db)6379Redis 缓存 (dify-redis) 如果这些端口被其他程序占用会导致服务启动失败。你需要修改docker-compose.yaml文件中对应服务的端口映射如”3000:3000″改为”3001:3000″。8. 常见问题与排查方法部署过程中难免会遇到问题这里列出一些典型情况及解决方法。问题现象可能原因排查方式解决方案docker-compose up -d失败1. 端口被占用。2. 镜像拉取失败。3. WSL 2 未运行或 Docker Desktop 未启动。1. 运行docker-compose logs查看具体错误。2. 检查端口占用netstat -ano | findstr :3000。3. 确认 Docker Desktop 托盘图标为绿色。1. 修改docker-compose.yaml中的主机端口。2. 检查网络尝试手动拉取镜像docker pull langgenius/dify-api。3. 重启 Docker Desktop 和 WSL。访问localhost:3000无法连接1. 服务未成功启动。2. 防火墙阻止。3. 容器内部服务启动出错。1.docker-compose ps查看容器状态。2.docker-compose logs web查看前端容器日志。1. 根据日志修复错误后重启服务docker-compose restart。2. 暂时关闭防火墙或添加入站规则。能打开页面但登录或操作时报错1. 后端 API 服务 (dify-api) 异常。2. 数据库连接失败。3. 环境变量配置错误。1.docker-compose logs api查看后端日志。2.docker-compose logs db查看数据库日志。3. 检查.env文件中的DB_PASSWORD等是否与docker-compose.yaml匹配。1. 检查.env配置特别是数据库密码和连接 URL。2. 确保POSTGRES_PASSWORD和DB_PASSWORD一致。3. 重启所有服务docker-compose down docker-compose up -d。知识库文件一直“处理中”1.dify-worker容器未运行或崩溃。2. 缺少 OCR 依赖对于图片文件。3. 文件格式不支持或损坏。1.docker-compose ps检查 worker 状态。2.docker-compose logs worker查看详细错误。1. 重启 worker 容器docker-compose restart worker。2. 确保上传的是支持的格式txt, md, pdf, docx, pptx等。3. 对于复杂 PDF尝试转换为纯文本再上传。调用 API 返回 404 或连接拒绝1. API 服务地址或端口错误。2. 应用未发布。3. API Key 不正确或未传递。1. 确认APP_API_URL配置和实际访问地址。2. 在 Dify 控制台确认应用已“发布”。3. 检查请求头中的Authorization字段。1. 使用http://localhost:5001/v1作为基础 URL 进行测试。2. 使用应用发布后生成的 API 密钥而非控制台密钥。Docker Desktop 启动失败提示 WSL 相关错误1. WSL 2 内核未更新或损坏。2. 虚拟化未启用。1. 在 PowerShell 运行wsl --update。2. 在任务管理器中检查虚拟化是否启用。1. 根据 Docker Desktop 的错误提示下载并安装最新的 WSL 2 内核更新包。2. 进入 BIOS/UEFI 启用虚拟化技术。9. 最佳实践与使用建议为了让你的 Dify 本地部署更稳定、数据更安全这里有一些建议。数据持久化备份Docker Compose 配置中已经将 PostgreSQL 数据库的数据卷映射到了本地./storage/db目录。定期备份这个目录就备份了你的所有应用配置、知识库元数据和对话记录。./storage目录下的其他子目录也存放了上传的文件和临时数据同样重要。升级与更新更新 Dify 版本时建议的步骤是备份./storage目录和.env文件。拉取最新的docker-compose.yaml文件。停止旧服务docker-compose down。拉取新镜像docker-compose pull。启动新服务docker-compose up -d。观察日志确保服务正常启动。安全配置修改默认密码务必修改.env文件中的POSTGRES_PASSWORD和REDIS_PASSWORD不要使用默认值或弱密码。限制访问本地测试时使用localhost无妨。如果需要在局域网内访问考虑使用 Nginx 配置反向代理并添加 HTTPS 和基础认证不要将:3000和:5001端口直接暴露在公网。API 密钥管理像保管密码一样保管你的 Dify API 密钥和应用密钥不要在代码或版本库中明文硬编码。资源监控对于长期运行的服务可以简单配置一个计划任务定期运行docker stats --no-stream docker_stats.log来记录资源使用情况以便在出现内存泄漏等问题时追溯。模型供应商备用方案在生产用途的应用中为关键模型配置备用供应商或备用 API Key避免因单一服务商故障导致业务中断。10. 总结与下一步通过 Docker 在 Windows 上部署 Dify你获得了一个功能强大、可私有化部署的 AI 应用开发平台。整个过程的核心在于 Docker 环境的准备和 Compose 文件的正确配置。一旦服务成功跑起来剩下的就是通过 Web 界面探索其丰富的功能——从简单的对话应用到结合知识库的复杂工作流。最先应该验证的功能无疑是连接一个可用的大模型 API 并成功进行对话。这是所有功能的基础。最容易踩的坑通常是端口冲突、数据库密码配置不一致以及模型 API 网络连接问题。按照本文的排查清单大部分问题都能快速定位。部署完成只是第一步。接下来你可以深入探索工作流尝试使用 Dify 的视觉化工作流编辑器将条件判断、HTTP 请求、代码执行等节点与大模型结合构建自动化流程。集成本地模型研究如何部署 Ollama 或 LocalAI并将本地运行的模型如 Llama 3、Qwen作为供应商添加到 Dify 中实现完全离线的 AI 应用。进行 API 集成开发将 Dify 发布的 AI 应用 API 集成到你自己的业务系统、微信公众号、小程序或聊天机器人中。优化知识库检索尝试不同的文本分段策略、向量化模型以提升知识库问答的准确性和相关性。这个部署方案为你提供了一个安全、可控的沙盒环境非常适合进行 AI 应用的原型设计和内部工具开发。建议收藏本文的部署与排查步骤在需要重建环境或帮助他人部署时能快速参考。
Windows系统Docker部署Dify：私有化AI应用开发平台实战指南
发布时间：2026/7/27 23:05:50
这次我们来看一个在 Windows 系统上基于 Docker 容器技术本地部署 Dify 开源 AI 应用开发平台的项目。对于想私有化部署 AI 能力、构建知识库或智能工作流的开发者和团队来说Dify 提供了一个可视化的低代码界面。而通过 Docker 部署可以极大简化环境配置的复杂度实现相对“一键化”的安装和启动。本文将带你完成从零开始在 Windows 10/11 系统上使用 Docker Desktop 部署 Dify 的全过程。核心内容包括Docker 环境的准备与验证、Dify 镜像的拉取与容器启动、服务访问与初始化配置以及部署后的基本功能验证和常见问题排查。整个过程重点关注实操步骤、端口占用、服务稳定性和数据持久化确保你能在本地成功运行一个功能完整的 Dify 服务。1. 核心能力速览在开始动手之前我们先快速了解通过 Docker 在 Windows 本地部署 Dify 的核心信息。能力项说明项目类型开源 AI 应用开发平台 (LLM Ops)核心功能可视化编排 AI 工作流、构建 AI 智能体 (Agent)、创建与管理知识库、集成多种大模型 API。部署方式Docker 容器化部署 (推荐)硬件门槛主要依赖网络和存储。CPU 推理对算力要求不高但若本地运行大模型则需要相应 GPU 资源。Dify 本身作为调度平台资源消耗不大。内存要求建议分配至少 4GB 内存给 Docker确保 Dify 相关容器App、API、Worker运行流畅。存储要求需要预留约 2-3GB 空间用于 Docker 镜像和初始数据。知识库文件上传会额外占用空间。支持平台Windows 10/11 (64位) 专业版、企业版或教育版。家庭版需安装 WSL 2 后端。启动方式通过docker-compose命令一键启动所有服务。是否支持 API是。Dify 提供完整的 OpenAPI可用于集成到其他系统。是否支持批量任务是。支持通过工作流批量处理文档知识库支持批量文件上传与处理。适合场景个人学习与测试、企业内部 AI 工具开发、需要数据隐私的 AI 应用原型搭建。2. 适用场景与使用边界Dify 作为一个平台其价值在于连接和调度。理解它能做什么、不能做什么有助于你判断是否值得投入时间部署。它非常适合以下场景快速原型开发无需编写大量代码通过拖拽即可构建基于大模型的对话应用、文本处理流水线。企业知识库问答将内部文档Word、PDF、PPT、TXT上传构建知识库创建专属的智能问答助手。多模型统一管理在同一个界面中管理 OpenAI、Azure、 Anthropic、国内主流大模型等多种 API 密钥和端点方便切换测试。工作流自动化将大模型调用与条件判断、代码执行、网络搜索等节点结合实现复杂的自动化任务。需要注意的使用边界非本地模型运行时Dify 默认是一个“调度器”它调用外部大模型 API如 OpenAI。如果你需要完全离线、本地运行大模型需要在 Dify 中配置本地模型 API 服务如通过 Ollama、LocalAI 等部署的本地模型这需要额外的部署步骤和显卡资源。性能依赖外部服务应用的响应速度和稳定性很大程度上取决于你所连接的大模型 API 服务的质量与网络状况。数据合规性当你使用第三方大模型 API 时提示词、上下文和生成的内容可能会经过服务提供商的服务器。如需绝对的数据隐私务必使用可本地部署的模型或确保 API 服务商符合你的数据安全要求。资源消耗虽然 Dify 本身不重但处理大量知识库文档尤其是 OCR 图片或运行复杂工作流时会对 CPU 和内存有一定压力。3. 环境准备与前置条件在 Windows 上通过 Docker 部署任何服务第一步永远是准备好 Docker 环境。以下是详细的检查清单。3.1 系统要求确认操作系统Windows 10 版本 2004 及更高内部版本 19041 及更高或 Windows 11。虚拟化支持必须在 BIOS/UEFI 中启用虚拟化技术如 Intel VT-x 或 AMD-V。可以在任务管理器 - “性能” - “CPU” 中查看“虚拟化”是否已启用。WSL 2Docker Desktop for Windows 依赖于 WSL 2适用于 Linux 的 Windows 子系统作为后端。这是必须的。3.2 安装 WSL 2如果你的系统是 Windows 家庭版或从未安装过 WSL需要手动安装。以管理员身份打开 PowerShell。运行以下命令启用 WSL 和虚拟机平台功能wsl --install这个命令会默认安装 Ubuntu 发行版。如果需要其他发行版可以先运行wsl --install -d 发行版名称。安装完成后重启计算机。重启后WSL 2 会自动完成初始化。你可以运行wsl -l -v来验证安装输出应显示一个发行版且VERSION为2。3.3 安装 Docker Desktop for Windows访问 Docker 官网下载 Docker Desktop for Windows 安装包。运行安装程序安装过程中确保勾选“使用 WSL 2 而不是 Hyper-V”如果出现此选项。安装完成后启动 Docker Desktop。首次启动可能需要几分钟进行初始化。启动成功后在任务栏托盘区可以看到 Docker 图标。右键图标选择“Settings”。在“General”设置中确保“Use the WSL 2 based engine”选项被勾选。在“Resources” - “WSL Integration”中启用与你安装的 WSL 发行版如 Ubuntu的集成。打开 PowerShell 或命令提示符运行以下命令验证安装docker --version docker-compose --version两者都应返回版本号无报错。4. 安装部署与启动方式Dify 官方提供了 Docker Compose 部署文件可以一键启动所有必需的组件包括 Web 前端、后端 API、后台 Worker 以及数据库PostgreSQL和缓存Redis。4.1 获取部署配置文件在你希望安装 Dify 的目录例如D:\Dify下打开 PowerShell。下载官方提供的docker-compose.yaml文件curl -o docker-compose.yaml https://github.com/langgenius/dify/blob/main/docker/docker-compose.yaml如果系统没有curl你也可以直接访问上述 GitHub 链接复制文件内容在本地新建一个docker-compose.yaml文件并粘贴。同时下载环境变量配置文件示例curl -o .env.example https://github.com/langgenius/dify/blob/main/.env.example将其重命名为.envcp .env.example .env # 或者在Windows资源管理器中直接重命名4.2 关键配置说明打开.env文件你需要关注并可能修改以下几个关键配置SECRET_KEY用于加密的密钥首次启动会自动生成建议保留。POSTGRES_PASSWORDPostgreSQL 数据库密码请修改为一个强密码。REDIS_PASSWORDRedis 缓存密码请修改为一个强密码。DB_PASSWORD应与POSTGRES_PASSWORD一致。CONSOLE_API_URL和APP_API_URL默认是http://localhost:5001和http://localhost:5001/v1。如果后续访问有问题可能需要根据实际情况调整例如改为服务器IP。CONSOLE_WEB_URL默认是http://localhost:3000这是 Web 管理界面的访问地址。对于最简单的本地测试你可以暂时不修改.env文件直接使用默认值。4.3 启动 Dify 服务在包含docker-compose.yaml和.env文件的目录下打开 PowerShell执行以下命令docker-compose up -d这个命令会执行以下操作从 Docker Hub 拉取 Dify 相关镜像包括 api、worker、web 等。创建并启动定义的所有容器app、api、worker、postgres、redis。-d参数表示在后台运行。首次执行会下载镜像耗时取决于你的网速。完成后可以使用以下命令查看容器状态docker-compose ps如果所有服务状态都是Up则表示启动成功。5. 功能测试与效果验证服务启动后我们通过 Web 界面进行基本的功能验证。5.1 访问 Web 管理界面打开浏览器访问http://localhost:3000。首次访问会进入初始化页面需要你设置管理员账号邮箱和密码。设置完成后使用刚设置的账号密码登录进入 Dify 控制台。5.2 基础功能验证配置模型供应商Dify 本身不提供模型需要你先配置一个可用的模型 API。在控制台点击左侧菜单栏的“模型供应商”。点击“添加模型供应商”选择你拥有的 API 服务例如“OpenAI”。填写对应的 API Key 和 Base URL如果使用官方接口Base URL 可留空。如果你暂时没有可以跳过此步但后续的对话和应用测试将无法进行。点击“保存”状态显示为“正常”即表示配置成功。5.3 核心功能测试一创建对话型应用点击左侧“应用”然后点击“创建新应用”。选择“对话型应用”输入应用名称点击“创建”。进入应用编排页面。在“提示词编排”区域你可以编写系统提示词。在右侧的“模型”区域选择你刚刚配置好的模型供应商和具体模型如 gpt-3.5-turbo。点击右上角的“发布”按钮将应用发布。发布后点击“访问应用”会打开一个独立的对话窗口。在输入框中发送一条测试消息如“你好请介绍下你自己”。如果配置正确你应该能收到 AI 的回复。这是验证 Dify 与大模型连接是否成功的最直接方法。5.4 核心功能测试二创建知识库并问答返回控制台点击左侧“知识库”点击“创建知识库”。填写知识库名称点击“创建”。进入知识库详情页点击“上传文件”选择一个本地的文本文件或 PDF 文件进行上传。上传后文件会进入“处理中”状态。Dify 会对其进行分段、向量化处理。处理完成后状态变为“已索引”。再次创建一个新的“对话型应用”或编辑一个已有应用。在应用编排页面找到并添加“知识库检索”节点。将其连接到对话流程中并选择你刚创建的知识库。发布并访问该应用。现在你的提问将优先从上传的文档中寻找答案。例如如果你的文档是关于某个产品的说明书你可以问“这个产品的主要功能是什么”。如果知识库检索配置正确AI 的回答应基于文档内容。6. 接口 API 与批量任务Dify 不仅提供 Web 界面更强大的能力在于其 API允许你将 AI 能力集成到自己的系统中。6.1 API 访问基础获取 API Key在 Dify 控制台点击右上角个人头像 - “API 密钥”可以创建新的密钥。请妥善保管此密钥。API 端点默认的 API 基础地址是http://localhost:5001/v1。你可以在.env文件的APP_API_URL中配置。认证方式在请求头中携带Authorization: Bearer your-api-key。6.2 调用对话应用 API以下是一个使用 Pythonrequests库调用已发布对话应用的示例import requests import json api_key your-dify-app-api-key # 替换为你的应用API密钥 app_id your-app-id # 替换为你的应用ID url fhttp://localhost:5001/v1/chat-messages headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { inputs: {}, query: 你好今天天气怎么样, response_mode: blocking, # 同步模式 conversation_id: , # 首次可为空后续使用返回的id以保持多轮对话 user: test-user-001 # 标识用户 } response requests.post(url, jsonpayload, headersheaders, timeout60) if response.status_code 200: result response.json() print(fAI回复{result.get(answer)}) print(f本次对话ID{result.get(conversation_id)}) else: print(f请求失败状态码{response.status_code}, 响应{response.text})注意应用 API 密钥需要在应用发布后在应用的“访问 API”设置中获取与控制台的 API 密钥不同。6.3 批量任务处理Dify 本身没有提供直接的“批量任务”API但你可以通过以下方式实现批量处理知识库批量上传通过 Dify 提供的“文档处理”API可以编程式地上传和处理大量文件到知识库。工作流批量触发如果你构建了一个工作流应用例如输入一篇新闻输出摘要和关键词你可以写一个简单的脚本循环读取一个文件夹下的所有文件依次调用该工作流应用的 API实现批量处理。使用异步模式上述 API 示例中response_mode设置为blocking同步。对于耗时的任务可以设置为streaming流式并在客户端处理或者通过conversation_id管理多轮对话的上下文实现连续的批量问答。7. 资源占用与性能观察部署完成后了解如何监控服务状态和资源消耗很重要。7.1 观察容器状态与日志查看所有容器状态docker-compose ps查看特定容器日志如 api 服务docker-compose logs api或docker-compose logs -f api-f表示跟随输出类似 tail -f。查看容器资源占用docker stats。这个命令会实时显示所有运行中容器的 CPU、内存、网络 I/O 使用情况。重点关注dify-api和dify-worker容器。7.2 性能影响因素知识库处理首次上传大量文档或高分辨率图片进行 OCR 时worker容器的 CPU 和内存使用率会显著上升。处理完成后会下降。模型 API 调用延迟Dify 应用的响应速度主要受限于你所连接的外部大模型 API 的响应时间。你可以在 Dify 的“日志与审计”中查看每次调用的耗时。向量数据库性能Dify 使用 PostgreSQL 的pgvector扩展存储向量。知识库文档数量巨大时检索速度可能会变慢。对于生产环境可以考虑使用更专业的向量数据库如 Qdrant、Weaviate但这需要修改部署配置更为复杂。网络带宽如果模型 API 在远端网络延迟和带宽会影响体验。7.3 端口占用情况默认情况下Dify 会占用以下端口3000Web 前端控制台 (dify-web)5001后端 API 服务 (dify-api)5432PostgreSQL 数据库 (dify-db)6379Redis 缓存 (dify-redis) 如果这些端口被其他程序占用会导致服务启动失败。你需要修改docker-compose.yaml文件中对应服务的端口映射如”3000:3000″改为”3001:3000″。8. 常见问题与排查方法部署过程中难免会遇到问题这里列出一些典型情况及解决方法。问题现象可能原因排查方式解决方案docker-compose up -d失败1. 端口被占用。2. 镜像拉取失败。3. WSL 2 未运行或 Docker Desktop 未启动。1. 运行docker-compose logs查看具体错误。2. 检查端口占用netstat -ano | findstr :3000。3. 确认 Docker Desktop 托盘图标为绿色。1. 修改docker-compose.yaml中的主机端口。2. 检查网络尝试手动拉取镜像docker pull langgenius/dify-api。3. 重启 Docker Desktop 和 WSL。访问localhost:3000无法连接1. 服务未成功启动。2. 防火墙阻止。3. 容器内部服务启动出错。1.docker-compose ps查看容器状态。2.docker-compose logs web查看前端容器日志。1. 根据日志修复错误后重启服务docker-compose restart。2. 暂时关闭防火墙或添加入站规则。能打开页面但登录或操作时报错1. 后端 API 服务 (dify-api) 异常。2. 数据库连接失败。3. 环境变量配置错误。1.docker-compose logs api查看后端日志。2.docker-compose logs db查看数据库日志。3. 检查.env文件中的DB_PASSWORD等是否与docker-compose.yaml匹配。1. 检查.env配置特别是数据库密码和连接 URL。2. 确保POSTGRES_PASSWORD和DB_PASSWORD一致。3. 重启所有服务docker-compose down docker-compose up -d。知识库文件一直“处理中”1.dify-worker容器未运行或崩溃。2. 缺少 OCR 依赖对于图片文件。3. 文件格式不支持或损坏。1.docker-compose ps检查 worker 状态。2.docker-compose logs worker查看详细错误。1. 重启 worker 容器docker-compose restart worker。2. 确保上传的是支持的格式txt, md, pdf, docx, pptx等。3. 对于复杂 PDF尝试转换为纯文本再上传。调用 API 返回 404 或连接拒绝1. API 服务地址或端口错误。2. 应用未发布。3. API Key 不正确或未传递。1. 确认APP_API_URL配置和实际访问地址。2. 在 Dify 控制台确认应用已“发布”。3. 检查请求头中的Authorization字段。1. 使用http://localhost:5001/v1作为基础 URL 进行测试。2. 使用应用发布后生成的 API 密钥而非控制台密钥。Docker Desktop 启动失败提示 WSL 相关错误1. WSL 2 内核未更新或损坏。2. 虚拟化未启用。1. 在 PowerShell 运行wsl --update。2. 在任务管理器中检查虚拟化是否启用。1. 根据 Docker Desktop 的错误提示下载并安装最新的 WSL 2 内核更新包。2. 进入 BIOS/UEFI 启用虚拟化技术。9. 最佳实践与使用建议为了让你的 Dify 本地部署更稳定、数据更安全这里有一些建议。数据持久化备份Docker Compose 配置中已经将 PostgreSQL 数据库的数据卷映射到了本地./storage/db目录。定期备份这个目录就备份了你的所有应用配置、知识库元数据和对话记录。./storage目录下的其他子目录也存放了上传的文件和临时数据同样重要。升级与更新更新 Dify 版本时建议的步骤是备份./storage目录和.env文件。拉取最新的docker-compose.yaml文件。停止旧服务docker-compose down。拉取新镜像docker-compose pull。启动新服务docker-compose up -d。观察日志确保服务正常启动。安全配置修改默认密码务必修改.env文件中的POSTGRES_PASSWORD和REDIS_PASSWORD不要使用默认值或弱密码。限制访问本地测试时使用localhost无妨。如果需要在局域网内访问考虑使用 Nginx 配置反向代理并添加 HTTPS 和基础认证不要将:3000和:5001端口直接暴露在公网。API 密钥管理像保管密码一样保管你的 Dify API 密钥和应用密钥不要在代码或版本库中明文硬编码。资源监控对于长期运行的服务可以简单配置一个计划任务定期运行docker stats --no-stream docker_stats.log来记录资源使用情况以便在出现内存泄漏等问题时追溯。模型供应商备用方案在生产用途的应用中为关键模型配置备用供应商或备用 API Key避免因单一服务商故障导致业务中断。10. 总结与下一步通过 Docker 在 Windows 上部署 Dify你获得了一个功能强大、可私有化部署的 AI 应用开发平台。整个过程的核心在于 Docker 环境的准备和 Compose 文件的正确配置。一旦服务成功跑起来剩下的就是通过 Web 界面探索其丰富的功能——从简单的对话应用到结合知识库的复杂工作流。最先应该验证的功能无疑是连接一个可用的大模型 API 并成功进行对话。这是所有功能的基础。最容易踩的坑通常是端口冲突、数据库密码配置不一致以及模型 API 网络连接问题。按照本文的排查清单大部分问题都能快速定位。部署完成只是第一步。接下来你可以深入探索工作流尝试使用 Dify 的视觉化工作流编辑器将条件判断、HTTP 请求、代码执行等节点与大模型结合构建自动化流程。集成本地模型研究如何部署 Ollama 或 LocalAI并将本地运行的模型如 Llama 3、Qwen作为供应商添加到 Dify 中实现完全离线的 AI 应用。进行 API 集成开发将 Dify 发布的 AI 应用 API 集成到你自己的业务系统、微信公众号、小程序或聊天机器人中。优化知识库检索尝试不同的文本分段策略、向量化模型以提升知识库问答的准确性和相关性。这个部署方案为你提供了一个安全、可控的沙盒环境非常适合进行 AI 应用的原型设计和内部工具开发。建议收藏本文的部署与排查步骤在需要重建环境或帮助他人部署时能快速参考。
