你折腾过AI Agent吗？注册云服务、绑信用卡、等审批，半天过去了，Token跑完还得续费。现在用这个 Dify 本地部署 教程 Windows，20 分钟，装个 Docker 拉几条命令，你的 Windows 笔记本就能跑起完整的 AI 应用平台——0 成本，全私有，还能让 DeepSeek 或任何模型当你的 Agent 后盾。

为什么选择在Windows上本地部署Dify

在 Windows 上跑 Dify，最直接的好处是 零云成本。Dify 官方 Docker 镜像大约 780MB，加上 PostgreSQL、Redis、Weaviate 等依赖容器，全部跑在本地，不产生任何 API 调用费——你只需要为模型本身的 Token 付费。如果用本地模型（比如 Ollama 加载的 DeepSeek-Coder-V2），连模型费用都省了。

数据完全私有是第二个关键理由。所有用户对话、知识库文档、Agent 日志都存在你本机的 PostgreSQL 数据库里，不会经过第三方服务器。企业内部想试用 AI Agent 又怕数据泄漏？本地部署是唯一合规路径。Dify 0.10.1 之后的版本支持 LDAP 和邮箱邀请成员（[1]），即使在内网也能管理多用户，数据不出门。

Windows 用户尤其需要这个 Dify 本地部署 教程 Windows，因为 Dify 官方文档主要面向 Linux/macOS。Windows 上要处理 Hyper‑V、WSL2、端口冲突这些坑。你在知乎或 GitHub Issues 里会看到大量“Windows 部署踩坑”帖，例如 Docker Desktop 默认占用 443 端口导致 Dify Nginx 启动失败，或文件路径转义问题让 docker-compose up 报错。一份针对 Windows 的教程能省下你至少半小时的排查时间。

硬件门槛极低。Dify 控制台本身几乎不消耗 CPU/GPU，2 核 4GB 内存的 Windows 笔记本就能流畅运行。真吃资源的是模型推理：如果你本地跑 7B 模型，建议 16GB 内存以上；如果接云端 API（比如 DeepSeek 官方的 deepseek-chat），8GB 内存足矣。Dify 官方给的 Docker Compose 模板开箱即用，但默认配置里 PostgreSQL 密码是弱密码 difyai123456，生产环境务必改掉。

提示：Dify 目前最新稳定版是 0.10.2（2025年5月），支持模型供应商 30+ 种，包括 OpenAI、Claude、DeepSeek、智谱 GLM，以及通过 One‑API 代理的任意模型。

灵活性远超 SaaS。云上的 Dify Cloud 限制每用户最多 5 个应用，数据存储 100MB；本地部署无上限。你自己接手后可以随意调 Docker Compose 里的变量，比如把 VECTOR_STORE=weaviate 改成 milvus 来加速 100 万级知识库检索。Windows 上还能直接挂载本地文件夹作为知识库源，不用走 S3 上传。

在Windows上安装Docker并开启Hyper-V的完整步骤

第一步：开启 Hyper‑V 和 WSL2

打开 控制面板 → 程序 → 启用或关闭 Windows 功能，勾选这三项：Hyper-V、Windows 虚拟机监控程序平台、适用于 Linux 的 Windows 子系统。

如果你用的是 Windows 11 家庭版，Hyper‑V 默认不可见——在 PowerShell（管理员）里直接跑 dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart 也能强行打开，并非必须 Pro 版。

确认无误后重启电脑，BIOS 里必须开启虚拟化技术（Intel VT-x 或 AMD SVM）。在华硕主板上进 BIOS 按 F7 切到 Advanced 模式，在 CPU Configuration 里找到 Intel Virtualization Technology 设为 Enabled；联想笔记本按 F2 进 BIOS，在 Security → Virtualization 里开启。如果这一步没做，Docker Desktop 安装后会直接报“Hardware assisted virtualization and data execution protection must be enabled in the BIOS”。

第二步：安装 Docker Desktop

去 Docker Desktop 4.30 Windows 安装包大约 680MB。双击运行，安装向导里务必取消勾选“Use WSL 2 instead of Hyper-V”（这个选项在旧版才有，新版默认走 WSL2）。
安装完成后，打开 Docker Desktop，进入 Settings → General，确认 Use the WSL 2 based engine 已勾选。然后在 Settings → Resources → WSL Integration 里，把 Ubuntu（或你默认的 WSL 发行版）的开关打开。这一步经常被遗漏，导致后期 docker-compose up 找不到 WSL 后端。

打开 PowerShell，跑 wsl --set-default-version 2 强制 WSL2 为默认，然后 wsl --list --verbose 确认发行版 Version 列是 2。如果显示 Version 1，执行 wsl --set-version <发行版名称> 2 手动升级。

第三步：验证环境

在命令行依次跑三条命令，每一条都返回版本号才算通过：

docker --version              # 应返回 Docker version 26.1.x
docker compose version        # 应返回 Docker Compose version v2.27.x
wsl -l -v                     # 确认所有发行版 Version 列为 2

常见故障：docker compose 提示命令不存在，原因是 Docker Desktop 老版本用空格分隔的 docker-compose，新版改为 docker compose（中间一个空格）。如果报错，改用 docker-compose --version 试试，并在后续 Dify 启动命令中保持一致。

现在 Docker 环境已经就绪，下一节会拉取 difyai/dify-web:0.10.2 镜像并启动 PostgreSQL + Redis + Weaviate 三件套，这是 Dify 本地部署 教程 Windows 里最容易踩端口冲突的部分。

通过Docker Compose一键部署Dify容器服务

Docker Desktop 跑通后，拉取 Dify 的 Docker Compose 文件只需要一句 git clone。打开 PowerShell，进入一个你打算存放项目的目录（例如 C:\dify），执行：

git clone https://github.com/langgenius/dify.git  # 获取最新稳定版 0.10.2
cd dify\docker

Dify 仓库里自带了 docker-compose.yml 和 .env.example。复制 .env.example 并重命名为 .env，这是所有环境变量的来源。用记事本打开 .env，至少改这三项：

  • POSTGRES_PASSWORD=你的强密码（默认是 difyai123456，生产环境必须换）
  • SECRET_KEY=<32位随机字符串>（用 openssl rand -hex 16 或在线生成器生成）
  • DIFY_PORT=8080（默认 80，Windows 上 80 端口常被其他软件占用，改成 8080 省得冲突）

SECRET_KEY 在 .env 里默认是空值，不填的话 Dify 会在启动时自动生成并写入 data/ 目录下的某个文件里，但建议手动设置，避免容器重建后密钥变导致会话失效。

确认 .env 配置无误后，在 dify\docker 目录下执行：

docker compose up -d

首次拉取镜像约需 2-5 分钟（取决于网速），包含 4 个核心容器：

  • dify-web（主应用，基于 Python 3.11，约 780MB）
  • postgres（PostgreSQL 15，数据持久化）
  • redis（缓存和 Celery 队列）
  • weaviate（向量数据库，用于知识库检索）

启动完成后，用 docker compose ps 检查所有容器状态，理想情况下每个容器的 STATUS 都是 Up 或 Up (healthy)。如果看到某个容器反复重启，用 docker compose logs <服务名> 看日志，大部分问题出在端口占用或 .env 里密码格式错误。

一切就绪后，浏览器访问 http://localhost:8080（如果你改了端口就用对应的）。首次页面会引导你创建管理员账号——这一步不需要邮件验证，直接设邮箱和密码即可。登录后看到的后台就是 Dify 的控制台，此时你已经有了一套完整的私有 AI 应用平台。接下来需要让 Dify 连上模型（比如 DeepSeek 或 Ollama），才可以在工作流里调用 Agent。

初始化Dify后台：设置管理员账号与邮箱邀请

浏览器访问 http://localhost:8080 后，页面会直接显示管理员注册表单。这一步骤不需要邮件验证——你只需输入邮箱、密码和确认密码，点击“创建管理员”即可完成。密码建议 16 位以上，包含大小写字母和数字，Dify 0.10.2 后端使用 Werkzeug 密码哈希，弱密码容易被彩虹表破解。创建成功后自动跳转到控制台首页，到此你已经有了一个完全私有的 Dify 实例。

注意：管理员账号的邮箱可以是任意格式（如 admin@local.dev），不会发出验证邮件。但如果你后续想用邮箱邀请其他成员，则需要真实的 SMTP 配置。

进入后台后，第一件事不是配置模型，而是设置成员管理。点击左下角头像 → 设置 → 成员管理，点“添加成员”并选择“通过邮箱邀请”。输入目标用户的邮箱，系统会生成一个一次性邀请链接，不会真的发邮件（除非你配置了 SMTP）。你需要复制该链接，通过微信、邮件或其他方式手动发送给对方。对方打开链接后，输入自己的邮箱和密码即可注册为成员。

如果你的团队有真实邮箱服务器，可以在 .env 中配置 SMTP 参数：

  • MAIL_TYPE=smtp
  • MAIL_DEFAULT_SENDER=your@domain.com
  • MAIL_SMTP_HOST=smtp.example.com
  • MAIL_SMTP_PORT=587
  • MAIL_SMTP_USER=your@domain.com
  • MAIL_SMTP_PASSWORD=你的密码

配置后重启容器：docker compose restart worker。之后邀请成员时，Dify 会自动发送邮件，接收方点击邮件中的链接即可自行注册。本地部署不依赖任何云身份服务，数据流全程受控。

这是 Dify 本地部署 教程 Windows 中容易忽略的一步：很多人以为必须配 SMTP 才能邀请成员，实则离线邀请链接触手可得。如果你在内网且没有邮件服务器，直接复制链接发给同事即可——对方用浏览器就能完成注册。

管理员账号建好后，下一步就是把 DeepSeek 或 Ollama 的 API Key 填入系统，让 Dify 有能力调用模型。模型配置在“设置 → 模型供应商”页面，下一节会具体操作。

接入模型供应商：配置DeepSeek等自付费API Key

登录 Dify 后台后，点击左下角头像 → 设置 → 模型供应商。页面列出所有支持的模型平台——DeepSeek、OpenAI、智谱 GLM、Anthropic Claude 等共 30 余种。找到 DeepSeek，点击 “添加模型”。

填三个字段即可：

  • 模型名称：随意起，比如 deepseek-chat（实际对应 DeepSeek 的聊天模型）
  • API Key：从 DeepSeek 开发者平台 申请，格式 sk- 开头，32 位十六进制字符串。注册后免费送 500 万 tokens（2025年5月活动），超出部分按 0.5 元/百万输入 tokens、2 元/百万输出 tokens 计费。
  • Base URL：默认 https://api.deepseek.com，如果用 One‑API 代理则改为你的代理地址。

点击保存。Dify 0.10.2 会自动验证 Key 的有效性——如果返回 401，检查 Key 是否前后带空格，或是否启用了 IP 白名单。同样方式可添加其他供应商：智谱 GLM 需填入 glm-4 模型名和 API Key（从智谱开放平台获取）；Ollama 则需要自定义 Base URL 为 http://host.docker.internal:11434（Windows 上通过 Docker 容器访问宿主机 Ollama 的固定地址）。

重要：不要将 API Key 写死在代码或 .env 文件里。Dify 会加密存储到 PostgreSQL 数据库，仅在调用模型时通过后端传递。如果你用容器重启后 Key 丢失，说明 .env 中 SECRET_KEY 未配置——手动设置后重建容器即可。

配置完成后，创建一个测试应用：点击 工作室 → 创建应用 → 对话型应用，选择刚添加的 DeepSeek 模型，输入“Hello”点发送。如果返回正常，说明 Dify 本地部署 教程 Windows 中的模型连接已经打通。接着你可以配置多个供应商，让不同应用按需切换——例如客服用便宜的 DeepSeek，复杂推理用推理更强的 Claude 3.5 Sonnet，各自独立计费，互不干扰。

在Dify平台上搭建并发布你的第一个AI Agent

登录 Dify 后台后，点击顶部导航的 工作室 → 创建应用，选择 Agent 类型。应用名称随意起，比如“我的第一个Agent”。创建后进入编排界面，左侧是提示词框和工具库，右侧是预览调试区。

先在模型选择器里选定 DeepSeek（上一节已配好 Key），点击模型名称旁的齿轮图标，确认 “温度”设为 0.1——Agent 任务需要确定性，别让模型自由发挥。然后在底部 “上下文” 区域，点击 “添加知识库”，选择你之前上传的本地文件（比如公司制度 PDF）。如果还没建知识库，暂时跳过，后续再从右上角“知识库”菜单导入 CSV 或 Markdown 文件。

接下来配置工具。Dify 内置了 7 个标准工具：网页爬虫、代码执行、搜索引擎、图片生成等。点击 工具库 → 开启 “Bing 搜索”（需要你自己申请 Bing Search API Key，免费 1000 次/月）或 “DALL·E 3 绘画”。不过最简单的测试场景是让 Agent 只回答知识库内容，不联网——这样你只需要一个空提示词，因为 Agent 会自动根据用户 Query 检索知识库。

注意：如果提示词里写了“你是一个什么什么助理”，建议限制在 200 字符以内。过长提示词会让 Agent 在推理时忽略工具调用，直接硬答。

输入测试消息：“请总结公司差旅报销流程”。点 “测试” 按钮，右侧对话框会实时显示 Agent 的思考过程：先调用 knowledge_retrieval 工具，再从返回片段里提取答案。如果返回空或无关结果，请检查知识库文件是否已索引（状态显示“可用”）。发布前务必多做几轮测试——比如问“没有相关文档”的问题，看 Agent 是否会礼貌拒绝而非瞎编。

确认无误后，点击右上角 “发布” 按钮。Dify 会弹出两个选项：“发布为新版本”（保留历史版本）或 “保存并发布”。选择后者，系统生成一个可访问的 Web 应用链接，形如 http://localhost:8080/workspace/your-app-id。你也可以在 “访问令牌” 页面生成 API Key，供外部程序调用这个 Agent。

至此，你已在 Windows 本地完成 Dify 本地部署 教程 Windows 的核心闭环：从安装到发布，全程未联网云服务。后续可以修改提示词模板、添加更多工具（比如计算器、天气查询），甚至用工作流编排多步 Agent 协作。

本地部署常见问题：端口冲突、模型报错与内存限制

端口冲突：80和443被占用的排查方法

Docker Desktop 默认会占用 443 端口（用于 Web UI 的 HTTPS 代理），而 Dify 默认监听 80 端口——这两个端口在 Windows 上经常被 IIS、Skype、VMware 或其他开发工具抢占。如果你执行 docker compose up -d 后看到 dify‑web 容器反复重启，或访问 http://localhost 返回“无法访问此站点”，很可能就是端口冲突。

打开 PowerShell（管理员），跑这条命令查看谁占了 80 端口：

netstat -ano | findstr :80

输出第三列显示 0.0.0.0:80 的那一行，最后一列是 PID。记下 PID，然后用 tasklist /fi "PID eq 你的PID" 查具体进程名——如果是 System（PID 4），那是 Windows 的 HTTP 服务，去 控制面板 → 程序和功能 → 启用或关闭 Windows 功能 里关掉“Internet Information Services”。如果是 vmware-hostd.exe，在 VMware 的设置里把共享虚拟机端口改掉。

最稳妥的解法：直接改 Dify 端口。编辑 dify\docker\.env，将 DIFY_PORT=80 改为 DIFY_PORT=8080，然后 docker compose up -d 重建容器。8080 在 Windows 上极少被占用，从此告别端口冲突。

改了端口后，记得用 docker compose ps 验证每个容器的 PORTS 列是否映射正确。如果 dify-web 仍然重启，再用 docker compose logs dify-web 看日志——常见错误还有 address already in use 的 Redis 端口（6379）或 PostgreSQL 端口（5432），同样在 .env 中改映射端口即可：

  • REDIS_PORT=6380（若宿主机 6379 已被占用）
  • POSTGRES_PORT=5433（若宿主机 5432 已被占用）

模型报错：API Key 无效与连接超时

配置完模型供应商后，测试时如果返回 401 Unauthorized 或 Connection refused，按顺序排查：

  1. API Key 前后有无空格？ 复制时容易多一个换行符，在 Dify 后台重新粘贴，手动检查首尾。
  2. Base URL 是否正确？ DeepSeek 官方地址是 https://api.deepseek.com（不带 /v1）。如果使用 Ollama，URL 必须是 http://host.docker.internal:11434——Docker 容器通过 host.docker.internal 访问宿主机，不能用 localhost。
  3. 模型名称是否精确匹配？ DeepSeek 的模型名是 deepseek-chat，智谱 GLM 是 glm-4，大小写敏感。在供应商页面下拉列表里选，不要手打。
  4. 网络代理是否干扰？ Windows 上如果开了 Clash 或 V2Ray，Docker 容器可能走代理导致请求失败。在 Docker Desktop 的 Settings → Resources → Proxies 里清空 HTTP/HTTPS 代理，或把 API 地址加入代理白名单。

docker compose logs worker 可以看到模型调用的详细错误堆栈。如果看到 HTTPSConnectionPool 超时，说明容器无法访问外网——检查 Docker Desktop 的 DNS 设置，改为 8.8.8.8 或你的内网 DNS。

内存限制：WSL2 默认吃满 50% 物理内存

Dify 本身只占约 500MB 内存，但 WSL2 虚拟机会默认分配宿主机 50% 的内存。如果你的 Windows 只有 8GB RAM，WSL2 一启动就占 4GB，加上 Docker 容器和模型推理，很快触发 OOM（Out Of Memory），表现为容器突然停止或 docker compose 命令卡死。

解决方法：限制 WSL2 的内存上限。在 %UserProfile% 目录下创建 .wslconfig 文件（无扩展名），写入：

[wsl2]
memory=4GB
processors=2
swap=2GB

然后打开 PowerShell 执行 wsl --shutdown，再重启 Docker Desktop。之后 wsl --list --verbose 确认内存限制生效——通过任务管理器查看 Vmmem 进程的内存占用，不应超过 4GB。

如果你同时跑 7B 模型（如 DeepSeek‑Coder‑V2），建议 物理内存至少 16GB，并将 .wslconfig 的 memory 设为 8GB。模型推理时，Ollama 会额外占用 4‑6GB，总内存不够时可以在 docker-compose.yml 的 ollama 服务下加 mem_limit: 8g 来硬性限制容器内存。

这是 Dify 本地部署 教程 Windows 里最容易被低估的瓶颈。很多人模型报错“OutOfMemoryError”或容器反复重启，其实不是配置问题，而是 WSL2 悄悄吃光了内存。跑 free -h（在 WSL 终端里）确认剩余内存，如果 Swap 用了超过 1GB，就该升级内存或降低模型参数量了。

排查完这三类问题，你的 Dify 实例应该能稳定运行。接下来可以调整工作流中的模型参数——比如把 DeepSeek 的 温度降到 0.1，让 Agent 输出更可控。

进阶优化：为Dify添加自定义工具与知识库

Dify 默认提供的 7 个内置工具（如网页爬虫、计算器）能覆盖基础场景，但如果你需要对接内部 API（比如公司考勤系统、私有数据库），就需要编写自定义工具。进入工作室 → 选择你的 Agent → 点击“工具库”面板右下角的 “创建自定义工具”。Dify 支持两种方式：直接粘贴 OpenAPI 规范（Swagger） JSON，或手动填写端点信息。

以调用一个简单的天气查询 API 为例。假设你有一个私有天气服务，地址是 http://192.168.1.100:5000/weather?city=xxx，返回 JSON {"temp": 22, "humidity": 0.6}。在自定义工具界面，按以下步骤配置：

  • 工具名称：写 private_weather，尽量用英文下划线。
  • 描述：根据城市名查询实时天气，返回温度和湿度。 描述决定 Agent 何时调用该工具，务必清晰。
  • API 格式：选 HTTP，方法 GET，URL 填入 http://host.docker.internal:5000/weather（注意：容器访问宿主机必须用 host.docker.internal，同上一节的 Ollama 配置）。
  • 参数：添加 city，类型 string，必填。Agent 会自动从用户提问中提取城市名填入。
  • 认证方式：如果 API 需要 Token，在 Headers 中添加 Authorization: Bearer <你的 Token>。

保存后，在 Agent 的工具库中开启这个自定义工具。测试时输入“北京今天天气如何”，右侧日志会显示 调用 tool: private_weather 和返回的原始数据。Agent 会根据响应内容组织自然语言回复。

注意：自定义工具不支持动态请求头或 OAuth2 流程。如果你的 API 需要签名算法（如阿里云 API 网关），建议先在宿主机写一个轻量级中间件去除签名，再让 Dify 调用。

知识库检索调优：分段策略与混合搜索

上传文档后，知识库只做基本的分段和向量化。对于非标文件（如扫描版 PDF、代码仓库），默认参数效果很差。在知识库 → 点击目标知识库 → 设置 → 分段设置，这里有三个核心参数：

  • 分段标识符：默认按 \n\n 拆分段落。如果你的文档是 Markdown 标题结构，改为 ## （二级标题），让每个 H2 区块 成为一个段落，避免标题与正文脱离。
  • 分段长度：默认 500 tokens。对代码文档建议降至 200 tokens，防止 Agent 忽略中间细节；对长报告可增至 1000 tokens，减少碎片化。
  • 搜索模式：Dify 支持 向量搜索（语义匹配）和 关键词搜索（词频 TF-IDF）。混合模式通常效果最好——把 召回策略 设为 “混合搜索”，权重向量 0.7 关键词 0.3。测试几次后根据准确率调整。

如果知识库包含大量相似内容（如不同版本的产品说明书），务必定时手动重建索引：在知识库列表点击“重新处理”。否则 Agent 可能返回过时片段。这是 Dify 本地部署 教程 Windows 中容易被忽略的一步——因为你可能每天都在更新本地文件，但索引不会自动刷新。

完成自定义工具和知识库调优后，你的 Agent 就能处理私有业务数据了。下一步可以根据工作流复杂度，研究 Dify 的对话变量和条件分支，实现多轮状态下工具调用的结果缓存。

总结

部署完成后，先别急着投入生产——用 docker compose logs --tail=50 dify-web 检查启动日志，确认没有 CRITICAL 或 ERROR 级别的报错。接着访问 http://localhost:8080/health（Dify 0.10.2 内置的健康检查端点），返回 {"status":"ok"} 才算绿色通过。这个步骤能帮你提前发现数据库连接失败或密钥未初始化的问题。

生产环境必须做的三件事：

  1. 改密码与密钥——在 .env 中把 POSTGRES_PASSWORD 和 SECRET_KEY 都换成高强度随机值。SECRET_KEY 用 python -c "import secrets; print(secrets.token_hex(16))" 生成。
  2. 启用 HTTPS——Dify 默认未开启 TLS。用 Nginx 或 Caddy 反代 localhost:8080，配置 Let’s Encrypt 证书。否则 Agent 的 API Key 在传输过程中可能被窃听。
  3. 定期备份数据——PostgreSQL 数据在 dify/docker/volumes/postgres 目录，用 pg_dump -h localhost -U dify -d dify > backup.sql 定时备份。Weaviate 的向量数据建议每天全量导出。

如果你计划让其他设备（如手机、同事电脑）访问此 Dify 实例，务必在 Docker Desktop 的 Settings → Network 中启用 “Expose daemon on tcp://localhost:2375 without TLS”（仅限内网），并将防火墙 8080 端口放开。暴露到公网则需要更强的安全策略。

维护成本极低。Dify 小版本升级只需重新 git pull 新镜像，然后 docker compose pull && docker compose up -d 重建。数据库迁移由 Dify 自动处理，你不需要执行任何 SQL 语句。本地部署的唯一开销是每月几元电费（Dify 容器组待机时约 15W）。

最后再次强调：本 Dify 本地部署 教程 Windows 中涉及的所有配置（端口、密码、API Key）都应当记录在团队内部文档中，避免容器重建后手忙脚乱。Windows 上的 Docker 环境相比 Linux 更有测试性质，如果计划长期运行，建议逐步迁移到稳定的 Linux 服务器上。但现在，你已经拥有了一个完全可控、可扩展的私有 AI Agent 平台——从零到一，只花了不到一小时。