Windows 11/10 系统基于 Docker Desktop 部署 Dify AI 应用平台实战指南

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在 Windows 环境下尝试部署 AI 应用时你是否也遇到过环境配置复杂、依赖冲突、端口占用等一系列“水土不服”的问题特别是对于像 Dify 这样功能强大的 AI 应用开发平台其官方文档通常以 Linux 环境为主让许多 Windows 开发者望而却步。本文将为你提供一套在 Windows 11/10 系统上基于 Docker Desktop 完整部署 Dify 的实战指南。从 Docker 环境准备、镜像拉取、容器编排到最终访问验证每一步都配有详细的命令、配置说明和避坑要点。无论你是想快速体验 Dify 的核心功能还是计划在本地搭建一个稳定的 AI 应用开发测试环境这篇教程都能让你绕过弯路一次部署成功。1. Dify 与 Docker 部署核心概念在开始动手之前我们先厘清几个核心概念这有助于你理解整个部署流程的设计思路并在遇到问题时能快速定位。1.1 Dify 是什么为什么选择它Dify 是一个开源的 LLM大语言模型应用开发平台。你可以把它理解为一个“可视化、低代码”的 AI 应用工厂。它最大的价值在于开发者无需深入掌握复杂的 Prompt 工程和模型微调技术就能通过图形化界面像搭积木一样快速构建出基于大语言模型的 AI 应用例如智能客服、内容生成、数据分析助手等。对于个人开发者或小团队而言在本地部署 Dify 有三大优势数据隐私与安全所有数据包括你的提示词、知识库文档、对话记录都运行在你自己的机器上无需担心敏感信息上传到第三方云端。成本可控除了电费和硬件成本没有额外的 SaaS 服务订阅费用。你可以自由对接 OpenAI、Azure OpenAI 或本地部署的开源模型如 Ollama。深度定制与学习本地部署让你可以深入探索 Dify 的架构、工作流设计甚至可以根据需要进行二次开发是学习 AI 应用架构的绝佳实践。1.2 为什么在 Windows 上用 Docker 部署传统在 Windows 上部署 Python 应用需要手动安装 Python 解释器、各种依赖包如 Redis、PostgreSQL配置环境变量处理版本冲突过程繁琐且容易出错。Docker 容器化部署完美解决了这些问题环境隔离Dify 及其所有依赖Python, Redis, PostgreSQL被打包在一个独立的“容器”中与你的主机系统完全隔离不会污染本地环境。一致性“一次构建处处运行”。你在本地测试好的 Docker 镜像可以几乎无修改地部署到服务器上保证了开发、测试、生产环境的一致性。简化部署通过docker-compose.yml文件你可以用几条命令定义并启动整个多服务应用Web 前端、后端 API、数据库、缓存无需手动安装和配置每个组件。易于维护与清理不需要时直接删除容器和镜像即可系统保持干净。对于 Windows 用户Docker Desktop 提供了近乎原生的容器运行体验使得在 Windows 上运行 Linux 应用变得简单可行。1.3 部署架构预览本次部署将使用 Docker Compose 启动以下四个核心服务dify-api(后端服务)提供核心的 RESTful API处理业务逻辑。dify-web(前端服务)提供用户操作的图形化界面。postgres(数据库)使用 PostgreSQL 存储应用数据、用户信息、知识库元数据等。redis(缓存服务)用作消息队列、会话缓存和临时数据存储。它们通过 Docker 内部的网络进行通信你只需要在主机上暴露 Web 服务的端口通常是 80即可访问。2. 环境准备与前置检查工欲善其事必先利其器。在开始部署前请确保你的 Windows 系统满足以下要求。2.1 系统与硬件要求操作系统Windows 10 64位版本 2004 及更高或 Build 19041 及更高或 Windows 11。必须启用 WSL 2 (Windows Subsystem for Linux 2)或 Hyper-V。内存建议至少8GB。运行 Dify 及其数据库、缓存服务会占用一定内存4GB 可能较为吃力。磁盘空间确保系统盘有至少 10GB 的可用空间用于存放 Docker 镜像和容器数据。虚拟化需在 BIOS/UEFI 中开启 CPU 的虚拟化支持Intel VT-x / AMD-V。2.2 安装与配置 Docker Desktop这是最关键的一步。请严格按照以下步骤操作下载安装包 访问 Docker 官网的 Docker Desktop for Windows 下载页面获取最新稳定版的安装程序。安装与初始配置运行安装程序安装过程中会提示启用 WSL 2 或 Hyper-V请务必勾选同意。安装完成后启动 Docker Desktop。首次启动时间可能较长它会完成初始化。启动后在系统托盘区找到 Docker 鲸鱼图标右键选择 “Settings”设置。关键配置非常重要General通用确保 “Start Docker Desktop when you log in” 已勾选方便后续使用。Resources资源在 “WSL Integration” 或 “Advanced” 中为 Docker 分配足够的资源。建议 CPU 不少于 4 核内存不少于 4GB交换空间 1GB。Docker Engine为了加速镜像拉取建议配置国内镜像源。在配置窗口中找到或添加以下配置注意 JSON 格式{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }点击 “Apply Restart” 应用并重启 Docker Daemon。验证安装 打开 PowerShell管理员身份或 Windows Terminal运行以下命令docker --version docker-compose --version # 或 docker compose version (Docker Compose V2)如果都能正确输出版本号Docker Compose 需 2.24.0说明安装成功。2.3 获取部署文件Dify 官方提供了标准的 Docker Compose 部署文件。我们直接在本地创建一个工作目录来存放它。在任意位置例如D:\Projects创建一个新文件夹命名为dify。在该文件夹内新建一个文本文件命名为docker-compose.yml。将以下完整的docker-compose.yml配置内容复制到该文件中。这是部署的核心文件请仔细核对。version: 3.8 services: postgres: image: postgres:16-alpine container_name: dify-postgres environment: POSTGRES_DB: dify POSTGRES_USER: postgres POSTGRES_PASSWORD: dify2024 PGDATA: /var/lib/postgresql/data/pgdata volumes: - postgres_data:/var/lib/postgresql/data networks: - dify-network restart: unless-stopped healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: dify-redis command: redis-server --requirepass dify2024 volumes: - redis_data:/data networks: - dify-network restart: unless-stopped healthcheck: test: [CMD, redis-cli, --raw, incr, ping] interval: 10s timeout: 5s retries: 5 dify-api: image: langgenius/dify-api:latest container_name: dify-api environment: # 数据库配置指向上面定义的 postgres 服务 DB_HOST: postgres DB_PORT: 5432 DB_NAME: dify DB_USERNAME: postgres DB_PASSWORD: dify2024 # Redis 配置指向上面定义的 redis 服务 REDIS_HOST: redis REDIS_PORT: 6379 REDIS_PASSWORD: dify2024 # 外部访问地址用于前端回调等。请替换为你的实际IP或域名。 CONSOLE_API_URL: http://localhost:3001 CONSOLE_WEB_URL: http://localhost:3000 # 服务绑定地址和端口 SERVICE_API_URL: http://localhost:5001 # 加密密钥首次启动会自动生成生产环境请务必修改 SECRET_KEY: your-secret-key-please-change volumes: # 挂载本地目录用于持久化上传的文件、日志等 - ./storage:/app/api/storage - ./logs:/app/api/logs ports: - 5001:5001 depends_on: postgres: condition: service_healthy redis: condition: service_healthy networks: - dify-network restart: unless-stopped dify-web: image: langgenius/dify-web:latest container_name: dify-web environment: # 指向后端 API 服务 CONSOLE_API_URL: http://localhost:3001 # 前端服务自身地址 CONSOLE_WEB_URL: http://localhost:3000 ports: - 3000:3000 depends_on: - dify-api networks: - dify-network restart: unless-stopped networks: dify-network: driver: bridge volumes: postgres_data: driver: local redis_data: driver: local配置文件关键点解析版本version: 3.8声明了 Compose 文件格式版本。服务定义了四个服务postgres,redis,dify-api,dify-web。镜像使用了官方镜像langgenius/dify-api:latest和langgenius/dify-web:latest以及标准的数据库和缓存镜像。环境变量这是服务间通信的桥梁。特别注意DB_HOST、REDIS_HOST直接使用了 Docker Compose 的服务名postgres,redis这是 Docker 内部 DNS 的特性。卷Volumespostgres_data和redis_data是命名卷用于持久化数据库和缓存数据即使容器删除数据也不会丢失。./storage和./logs是绑定挂载将容器内的目录映射到宿主机的当前目录下方便查看日志和上传的文件。端口映射ports将容器端口映射到宿主机端口。dify-web:3000映射到主机3000端口dify-api:5001映射到主机5001端口。网络所有服务加入自定义的dify-network它们可以在该网络内通过服务名互相访问。健康检查healthcheck确保数据库和 Redis 完全启动后后端服务才启动避免连接失败。依赖depends_on结合condition: service_healthy定义了服务的启动顺序。3. 启动与部署 Dify环境与文件准备就绪后现在可以开始启动服务了。3.1 启动 Docker Compose 服务打开 PowerShell 或终端使用cd命令切换到存放docker-compose.yml文件的目录例如cd D:\Projects\dify。执行以下命令启动所有服务docker-compose up -dup创建并启动容器。-d在后台运行守护进程模式。首次执行时Docker 会从 Docker Hub 拉取所需的镜像PostgreSQL, Redis, Dify API, Dify Web这需要一些时间取决于你的网速。请耐心等待。查看服务状态docker-compose ps这个命令会列出所有服务的状态。当所有服务的State都显示为Up时表示启动成功。启动过程可能需要1-2分钟因为后端服务需要初始化数据库。3.2 监控日志与初始化过程在启动过程中或遇到问题时查看日志是排查的关键。查看所有服务的综合日志docker-compose logs -f-f参数可以实时跟踪日志输出。观察日志重点关注dify-api服务你会看到它执行数据库迁移、创建初始表等操作。直到看到类似Application startup complete.或Uvicorn running on http://0.0.0.0:5001的日志说明后端已就绪。查看特定服务的日志例如只查看后端docker-compose logs -f dify-api如果启动失败常见原因是端口占用。确保你本地的3000和5001端口没有被其他程序如其他开发服务器占用。如果需要修改端口可以在docker-compose.yml文件中修改ports映射例如将3000:3000改为8080:3000那么访问地址就变成了http://localhost:8080。3.3 访问与初始化 Dify 平台访问前端界面在浏览器中打开http://localhost:3000。首次初始化首次访问会跳转到初始化页面你需要设置管理员账号邮箱和密码。填写信息并提交。这个过程会在后端数据库中创建管理员用户。登录系统初始化完成后使用刚才设置的邮箱和密码登录。配置模型供应商登录后进入 “设置” - “模型供应商”。在这里你需要添加至少一个 LLM 供应商Dify 才能正常工作。OpenAI如果你有 OpenAI API Key选择 OpenAI填入你的 API Key 和 Base URL如果使用第三方代理。Azure OpenAI填入 Azure 提供的端点、API Key 和部署名称。Ollama本地模型如果你在本地运行了 Ollama可以添加 “自定义模型”API 地址填写http://host.docker.internal:11434。host.docker.internal是 Docker 提供的一个特殊域名指向宿主机的本地回环地址这样容器内的服务就能访问宿主机上运行的 Ollama 了。创建你的第一个应用点击 “创建应用”选择 “对话型应用” 或 “文本生成型应用”即可开始通过可视化工作流构建你的 AI 应用。至此Dify 平台已经在你的 Windows 本地成功部署并可以正常使用了。4. 日常管理与维护命令部署完成后你需要掌握一些基本的 Docker Compose 命令来管理你的 Dify 服务。4.1 常用运维命令停止所有服务保留容器和数据docker-compose stop启动已停止的服务docker-compose start重启所有服务常用于更新配置后docker-compose restart停止并删除所有容器、网络不会删除数据卷和镜像docker-compose down这个命令在你修改了docker-compose.yml文件后经常使用它会清理旧的容器下次up时会根据新配置创建。停止并删除所有容器、网络、数据卷警告这会清除所有数据库数据docker-compose down -v除非你想彻底重置 Dify否则不要轻易使用-v参数。查看服务资源占用docker-compose top4.2 数据备份与迁移你的数据应用、知识库、对话记录存储在 PostgreSQL 数据库中而上传的文件如知识库文档存储在./storage目录。备份这两者即可。备份数据库# 进入 postgres 容器执行备份命令 docker-compose exec postgres pg_dump -U postgres dify dify_backup_$(date %Y%m%d).sql这会在当前目录生成一个 SQL 备份文件。备份存储文件直接复制整个./storage目录即可。迁移到新环境在新环境准备好相同的docker-compose.yml。先启动服务docker-compose up -d完成初始化。停止服务docker-compose stop。将备份的 SQL 文件复制到新环境并恢复数据库# 将备份文件复制到 postgres 容器内 docker cp dify_backup_20240515.sql dify-postgres:/tmp/backup.sql # 进入容器执行恢复 docker-compose exec postgres psql -U postgres -d dify -f /tmp/backup.sql用备份的storage目录覆盖新环境的./storage。重启所有服务docker-compose restart。4.3 更新 Dify 版本Dify 项目迭代较快定期更新可以获取新功能和修复。更新步骤很简单拉取最新镜像docker-compose pull这个命令会从 Docker Hub 拉取dify-api和dify-web服务的最新latest标签镜像。重新创建并启动容器docker-compose up -dDocker Compose 会检测到镜像已更新并使用新镜像重新创建容器。数据库卷保持不变因此你的数据是安全的。验证更新查看日志或访问 Web 界面确认服务正常运行。注意更新前建议先执行数据库备份。虽然官方镜像通常会处理好数据库迁移但备份是一个好习惯。5. 常见问题与故障排查在部署和使用过程中你可能会遇到一些问题。以下是常见问题的排查思路。5.1 容器启动失败问题现象可能原因排查与解决思路dify-api启动失败日志显示数据库连接错误1. PostgreSQL 容器未完全启动。2. 环境变量配置错误密码、数据库名。3. 网络问题dify-api无法通过服务名postgres访问数据库。1. 运行docker-compose logs postgres查看数据库日志确认健康检查通过。2. 检查docker-compose.yml中DB_PASSWORD等环境变量是否与postgres服务定义的一致。3. 进入dify-api容器内部测试连通性docker-compose exec dify-api ping postgres。dify-web无法访问或页面白屏/报错1. 前端容器未启动。2. 前端配置的CONSOLE_API_URL指向的后端地址不可达。3. 浏览器缓存。1.docker-compose ps确认dify-web状态为Up。2. 检查dify-web环境变量中的CONSOLE_API_URL是否与dify-api服务的SERVICE_API_URL或CONSOLE_API_URL对应。在容器内应使用服务名和容器端口如http://dify-api:5001但我们配置的是主机网络映射所以用localhost。确保一致。3. 打开浏览器开发者工具F12查看 Console 和 Network 标签页的具体错误信息。端口被占用导致容器启动失败本地已有程序占用了 3000 或 5001 端口。1. 在 PowerShell 中运行 netstat -ano5.2 平台使用问题问题现象可能原因排查与解决思路添加 OpenAI 模型供应商后测试连接失败1. API Key 错误或过期。2. 网络问题无法访问api.openai.com。3. 账号余额不足。1. 在 OpenAI 官网检查 API Key 的有效性。2. 在宿主机上使用curl或浏览器测试是否能访问 OpenAI API。3. 如果使用代理需要在 Dify 的模型供应商配置中正确填写Base URL。知识库文件上传失败或处理异常1. 文件格式不支持。2. 文件过大。3../storage目录权限问题在 Windows 上较少见。1. 确认文件类型在支持列表中txt, pdf, docx, pptx, excel, markdown等。2. 查看dify-api日志获取具体的错误信息。3. 尝试上传一个小型文本文件测试。应用对话无响应或报错1. 模型供应商配置有误或额度用尽。2. Prompt 设计有问题导致模型无法理解。3. 网络超时。1. 在 “模型供应商” 页面测试连接。2. 检查应用的 “提示词编排” 部分确保逻辑通顺。3. 查看dify-api日志看是否有来自模型 API 的错误返回。5.3 Docker 环境问题问题现象可能原因排查与解决思路docker-compose命令未找到Docker Desktop 安装时未正确集成 Docker Compose或使用的是旧版本。1. Docker Desktop 新版本已内置 Compose V2命令是docker compose没有横杠。可以尝试docker compose version。2. 如果必须使用docker-compose可能需要单独安装。但在 Windows Docker Desktop 环境下推荐使用内置的docker compose。镜像拉取速度极慢Docker Hub 在国内访问速度不稳定。按照本文2.2 节配置 Docker Daemon 的国内镜像加速器。WSL 2 启动失败或报错Windows 功能未启用或 WSL 2 内核未更新。1. 以管理员身份打开 PowerShell运行wsl --install安装 WSL 2。2. 运行wsl --set-default-version 2设置默认版本。3. 在 “控制面板 - 程序和功能 - 启用或关闭 Windows 功能” 中确保 “适用于 Linux 的 Windows 子系统” 和 “虚拟机平台” 已勾选。6. 生产环境部署建议与安全加固本文演示的是本地开发测试环境。如果你计划将部署在公网或团队内网中使用必须考虑安全和性能问题。6.1 安全配置清单修改默认密码和密钥数据库密码将docker-compose.yml中postgres服务的POSTGRES_PASSWORD和dify-api服务中的DB_PASSWORD改为强密码。Redis 密码将redis服务的requirepass参数和dify-api中的REDIS_PASSWORD改为强密码。Dify 密钥将dify-api服务中的SECRET_KEY改为一个长且复杂的随机字符串。切勿使用示例中的your-secret-key-please-change。使用非latest标签镜像latest标签总是指向最新版本可能包含不稳定的变更。在生产环境中应使用具体的版本标签例如langgenius/dify-api:0.6.0。这可以确保部署的版本是已知且稳定的。配置 HTTPS 公网访问必须使用 HTTPS。你有两种主要方式在 Dify 前端配置这需要修改 Nginx 或 Traefik 等反向代理配置为dify-web服务配置 SSL 证书。更推荐使用外部反向代理在 Docker Compose 之外使用独立的 Nginx 或 Caddy 服务器作为反向代理统一管理域名和 SSL 证书。这样更安全也便于管理多个服务。限制网络访问修改docker-compose.yml中的端口映射不要将数据库 (5432) 和 Redis (6379) 的端口暴露给宿主机即删除或注释掉它们的ports配置因为它们只需要被dify-api内部访问。如果宿主机有防火墙确保只开放必要的端口如 Web 的3000或80/443。定期备份 建立自动化备份机制定期备份数据库 (pg_dump) 和storage目录并将备份文件传输到异地存储。6.2 性能与可用性优化资源限制在docker-compose.yml中为每个服务设置资源限制防止某个容器耗尽所有主机资源。services: dify-api: # ... 其他配置 ... deploy: resources: limits: cpus: 2 memory: 2G reservations: cpus: 0.5 memory: 512M注意deploy部分通常在 Swarm 模式下使用单机 Docker Compose 可以使用resources顶级字段但语法可能不同请查阅最新文档。日志管理默认日志会输出到容器控制台长期运行可能占用磁盘。可以配置 Docker 的日志驱动如json-file并设置大小和数量限制或者将日志集中收集到 ELK、Loki 等系统中。监控使用docker stats命令或 Portainer、cAdvisor 等工具监控容器资源使用情况。对于应用层监控可以关注 Dify 自身的运行日志和接口性能。6.3 使用环境变量文件管理敏感信息将密码、密钥等敏感信息直接写在docker-compose.yml中不安全。最佳实践是使用环境变量文件。在docker-compose.yml同目录下创建.env文件# .env 文件 POSTGRES_PASSWORDYourStrongDbPassword123! REDIS_PASSWORDYourStrongRedisPassword456! DIFY_SECRET_KEYYourVeryLongAndRandomSecretKeyGeneratedHere!修改docker-compose.yml引用这些环境变量environment: POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} DB_PASSWORD: ${POSTGRES_PASSWORD} # 使用同一个变量 REDIS_PASSWORD: ${REDIS_PASSWORD} SECRET_KEY: ${DIFY_SECRET_KEY}确保.env文件被添加到.gitignore中避免提交到代码仓库。通过以上步骤你不仅能在 Windows 上成功部署 Dify还能掌握其日常运维、故障排查方法并了解将其推向更正式环境所需的安全与优化考量。Dify 的强大之处在于其开箱即用的可视化能力让你能快速将 AI 想法转化为实际应用。现在你可以开始探索它的工作流、知识库和 Agent 功能构建属于你自己的智能助手了。如果在实践中遇到本文未覆盖的特定问题查阅 Dify 官方文档和 GitHub Issues 通常是找到解决方案的最佳途径。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度