企业官网建设流程全解析

前段时间有个团队找我帮忙，说他们想在公司内网做一套AI助手，既要能基于内部文档回答员工问题，又不想把数据传到外部平台。我给他们搭的就是Dify——开源的大模型应用开发平台，可以完全私有化部署，自带知识库、智能体、工作流这些模块。这个方案在Windows环境下也能跑通，前提是先把Docker生态弄明白。

这篇文章我会把我在Windows上从零部署Dify、接模型、搭知识库、建智能体的完整过程写一遍，包括每个环节容易踩的坑。适合两类人：一类是想在本机快速体验Dify能力的产品经理、开发者；另一类是准备给团队或企业内部署一套私有知识库问答系统的技术同学。我尽可能少讲"点击这里点击那里"的废话描述，遇到关键步骤会把背后的原理也交代清楚，这样你排查问题的时候才不会两眼一抹黑。

1. 为什么要本地跑一套 Dify：隐私、可控和长期成本

1.1 本地部署与在线平台的本质区别

先说说Dify是什么。它不只是一个聊天机器人前端，而是一个完整的LLM应用开发平台。你可以在里面管理多种大模型API、搭建知识库、编排工作流、创建智能体，并且通过一个可视化的界面把所有这些能力组合成最终的应用。社区版是开源的，代码可以直接获取，部署到自己的服务器或者本地电脑都可以。

在线平台很多，优点是开箱即用，但缺点也很明显。第一是数据隐私——如果你要处理的文档包含客户信息、内部流程、财务数据，每次把文档传到第三方平台，等于把核心资产交给别人保管。第二是功能边界——在线平台能改的东西有限，很多高级配置、自定义插件都没有。第三是费用——按调用量和时间收费，团队一旦用起来，规模上去了费用也在涨。

本地部署之后，模型调用可以换成内网的推理服务，知识库的数据全部落在自己的磁盘上，页面没有广告，管理权限自己控制。虽然前期需要花一点时间搭环境，但一旦跑通，后面维护成本并不高。对大多数有数据合规要求的团队来说，这个取舍非常划算。

1.2 这套方案到底适合谁

我不建议所有人都上本地部署。如果你是个人用户，只是偶尔用AI写文案、改代码，在线平台更方便，没必要折腾。但如果你是以下情况之一，本地部署Dify很值得考虑：

• 企业或团队需要一个基于内部制度、产品文档、FAQ的知识库问答机器人。
• 业务数据不能出内网，需要在隔离环境里搭建AI服务。
• 你想把多家大模型（本地Ollama、云端API）统一管理到一个平台里。
• 你想深入研究智能体的工作原理，通过可视化的流程去调试每一步的调用。

文章的后面，我会以一个"企业内部产品知识库+客服智能体"作为主线场景，带大家完整走一遍从环境准备到最终上线的流程。这个场景足够典型，你换成任何垂直领域，比如农业知识库、法律条款问答、设备维修手册，方法完全一样。

2. 环境基建：Windows 上先把 Docker 这关过了

2.1 硬件与系统准备

Dify是典型的容器化部署，在Windows上依赖Docker Desktop。Docker Desktop的底层依赖WSL2或Hyper-V，所以系统建议用Windows 10 2004及以上版本，或者Windows 11。内存建议至少16GB——Dify本身的服务大约占到2-3GB，如果还要在本地跑Ollama模型，7B级别的量化模型加载后大概还要5-6GB，内存小了会很吃力。

CPU方面，6核8核都可以，如果是纯CPU推理，本地模型生成速度会慢，但做知识库索引和一般问答还是能用的。如果计算机上有独立显卡，NVIDIA显卡可以配合Ollama做GPU加速，生成速度会快很多。动手装之前，建议先打开任务管理器确认虚拟化是否开启。如果"性能"页里显示"虚拟化：已启用"，说明BIOS层面没问题。如果显示"已禁用"，需要重启进BIOS，找到Intel VT-x或AMD SVM的选项打开，不然后面WSL2和Docker都起不来。这是Windows部署容器化应用最常见的拦路虎之一。

2.2 Docker Desktop 安装全流程

下载Docker Desktop安装包直接安装即可。安装过程中会提示是否使用WSL2，默认勾选就行。需要注意，如果系统之前没装过WSL，安装完Docker Desktop后建议重启一次电脑，让它自动初始化WSL2内核。

这里有一个常见的翻车点：Docker Desktop提示需要WSL2 Update，但安装更新包时又报错"无法安装"。这种情况可以手动执行两条PowerShell命令（管理员权限）先启用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 --version，能看到版本号就说明WSL2正常了。

Docker Desktop装好后，第一次启动需要接受协议，然后它会自动创建一个默认的WSL发行版。你可以在Docker Desktop的Settings → Resources → WSL Integration里看到当前集成的发行版。这个页面还可以设置WSL的内存上限和CPU核数，如果机器配置比较紧张，可以给Docker限制到6GB内存、4核，避免容器把物理内存占满。

2.3 装完 Docker 后先做两件事

第一件事是确认Docker引擎能正常拉取镜像。打开PowerShell执行：

docker version docker run hello-world

如果hello-world能运行，说明Docker的核心功能没问题。如果运行过程中拉取比较慢或者经常超时，原因通常是当前网络环境访问Docker Hub不太稳定。可以在Docker Desktop的Settings → Docker Engine里，把registry-mirrors配置成可用的镜像加速地址，然后重启Docker。要注意，这类加速服务在不同时间段的稳定性差异比较大，如果某个地址失效，就清掉配置直接访问官方仓库，多数情况下也能拉取，就是慢一些。

第二件事是检查docker compose命令是否可用。Docker Desktop自带Compose插件，PowerShell里执行docker compose version，能输出版本号就行。很多旧教程会让你安装docker-compose（带横杠），那是独立的Python工具，现在新版本Docker里已经集成了，不用单独装。下面所有命令我都用docker compose这种新式写法。

另外，建议顺手把Git for Windows装好，用于拉取Dify源码。安装时保持默认选项即可，后期在PowerShell里可以用git命令。

3. Dify 服务启动：拉代码、改配置、看日志

3.1 获取 Dify 源码和镜像

Dify的部署文件都放在GitHub仓库里，先用git把代码拉下来：

git clone https://github.com/langgenius/dify.git cd dify/docker

刚拉下来的代码是主分支，迭代很快。想用稳定版本，建议先git tag看一下版本列表，然后切到一个固定版本再部署：

git tag git checkout 1.17.1

为什么要固定版本？因为主分支可能有一些未完全验证的改动，部署之后如果遇到问题，很难判断是配置问题还是代码问题。我自己习惯用发布版本，遇到问题可以直接到对应的Release页面查issue，社区里可能已经有人踩过同样的坑。

docker目录下已经写好了完整的部署编排文件。目录里有个.env.example，这是Dify后端所有的环境变量模板。部署前复制一份：

copy .env.example .env

Windows的PowerShell里，或者在资源管理器里直接复制文件都行。不改也能跑，但有几个变量建议按自己的环境调整，详见下一小节。

3.2 .env 里最值得动的几个参数

打开.env文件，重点关注这几个：

这里特别说下端口。Dify默认用80端口，如果你本机装了IIS、Nginx或者其他服务占用了80，启动后会发现访问不了。可以直接把DIFY_PORT改成8080，改完后访问地址是http://localhost:8080。这个环境变量在编排文件里会自动替换nginx的端口映射，比手动改docker-compose.yaml里的ports字段更省事，升级代码时不会冲突。

3.3 启动与自检：从浏览器到容器日志

在docker目录下执行：

docker compose up -d

首次启动会拉取一批镜像，包括PostgreSQL、Redis、Weaviate、Nginx、API服务、Worker、Web前端等，镜像总量几个GB，耗时取决于你的网络环境。中途如果某个服务启动失败，可以执行：

docker compose ps

看看哪个容器状态是 Exited 或者 Restarting。再查看它的日志：

docker compose logs api docker compose logs web

日志里能看到"Listening"或者"Server running"之类的信息，说明服务起来了。整个启动过程1-3分钟属于正常，第一次要等数据库初始化、迁移表结构，可能更久一些。

启动完成后，浏览器访问http://localhost:8080/install（如果端口改了就用你自己的端口）。第一次访问会进入初始化页面，需要设置管理员邮箱和密码。这个管理员账号不只是一个登录账号，Dify里的模型配置、知识库路由、应用管理都是在这个后台完成的。设置完后会跳转到登录页，说明数据库和Web服务已经通了。

如果你希望团队成员从其他电脑访问这台机器上部署的Dify，需要在Windows防火墙里放行对应端口，然后用http://这台电脑的局域网IP:8080访问。如果访问不通，优先检查防火墙和端口是否真的对外监听，用netstat -ano | findstr :8080可以快速确认。

4. 模型接入：Ollama 本地推理和云端 API 的取舍

4.1 Ollama 安装与模型拉取

Dify本身不带模型能力，它只是一个管理模型和应用的平台。所以第二步是把模型接进来。有两类选择，一类是接云端的API服务，一类是跑本地的开源模型。如果想完全离线使用，必然要选本地模型。我推荐用Ollama来管理本地模型，它在Windows上安装非常简单，下载对应安装包即可，装卸、拉模型都比较省心。

Ollama装好后，在PowerShell里先拉一个通用对话模型：

ollama pull qwen2.5:7b

qwen2.5:7b是目前性价比比较高的中文模型之一，量化后的文件大概4-5GB，普通CPU也能跑，独立显卡上更快。如果你硬件配置强，可以试qwen2.5:14b或llama3.1:8b，效果会好一些。下载完成后，在PowerShell里执行：

ollama run qwen2.5:7b

看到对话提示符说明模型已经能推理了。先输入一句"介绍你自己"测试一下，确认没问题再往下走。模型首次加载可能需要一小段时间，这是正常的。

如果你希望知识库获得更好的中文语义检索效果，建议同时拉一个嵌入模型：

ollama pull bge-m3

这个模型专门用来把文本转成向量，知识库的"高质量索引"模式会用到。

4.2 Dify 里挂接 Ollama 模型

Ollama默认监听本机的11434端口。这里有一个关键的网络细节：Dify是跑在Docker容器里的，容器访问宿主机的地址不能写localhost，在Windows上用Docker Desktop的话，可以用特殊域名host.docker.internal来指代宿主机。

所以在Dify后台操作时，进入"设置" → "模型供应商" → 找到"Ollama" → 点击"添加模型"：

• 模型类型：选择LLM（对话模型）
• 模型名称：填qwen2.5:7b，要和Ollama里的名字完全一致
• 基础 URL：填http://host.docker.internal:11434
• 模型上下文长度：填32768或8192，以Ollama模型实际上下文为准

保存后，Dify会向Ollama发一个测试请求。如果你没写对地址，这里会直接报错"Connection error"。最常见的原因就是把地址写成了http://localhost:11434。如果Docker网络环境特殊，host.docker.internal解析不了，可以在docker-compose.yaml的api容器和worker容器里加上extra_hosts配置，手动把host.docker.internal映射到宿主机网关，这个操作不太常用，但遇到网络不通时值得排查。

同样的方式，再添加一个Text Embedding类型的模型，名称填bge-m3，这样知识库才能使用"高质量"索引模式。

4.3 云端 API 接入（以 DeepSeek 为例）

本地模型胜在隐私和离线可用，但受限于硬件，复杂任务的生成质量通常不如大参数模型。如果硬件不够，又想保证回答质量，可以接云端API。Dify支持多家供应商，包括DeepSeek、通义千问、Moonshot、智谱等，也支持OpenAI兼容格式的接口。

以DeepSeek为例：去DeepSeek开放平台注册账号，创建一个API Key，然后回到Dify后台，设置 → 模型供应商 → DeepSeek → 添加模型。模型名称填deepseek-chat，API Key填你的密钥，保存即可。

如果你打算使用混合策略，可以这样设计：对话模型用云端API保证质量，嵌入模型用本地bge-m3。Dify允许不同模型供应商混用，这正是本地部署比单一平台灵活的地方。还有一点容易被忽略：对话模型和嵌入模型是分开配置的，不影响使用。知识库用云端嵌入模型、对话模型用本地Ollama，也没问题，按实际需求组合就行。

5. 知识库从零搭到能"用"：分段、索引与召回

5.1 文档准备与上传格式

Dify的知识库模块支持多种后端存储，在1.x版本里创建知识库时，可以看到数据集的类型选项，一般选择"通用"或"结构化"都可以。创建流程很简单：进入知识库页面 → 创建知识库 → 填名称、描述 → 上传文档。

支持的文档格式包括文本、Markdown、PDF、Word、Excel等，对日常使用来说已经很全面。但我要提醒一句：PDF如果是从扫描件生成的图片型PDF，Dify本身不会做OCR，文字提取不出来。如果你的文档是这样，先用工具转成文字再上传。

以"企业内部产品知识库"为例，常见的文档有三类，处理方式略有区别：

• 产品规格PDF：适合整体上传，让Dify自动分段。
• 制度/流程Word：篇幅较长，建议先按章节拆成多个小文件，方便分段管理。
• 问答FAQ：最适合做知识库，一行一问答，检索命中率高。

如果你的团队已经在用Obsidian或者其他笔记工具积累了大量Markdown笔记，其实可以直接把这些文件批量导出来喂给Dify。很多人想做"第二大脑"式的个人知识库，Dify本地部署之后正好可以接管这一层，让大模型基于你的笔记回答，而不是泛泛地聊。

5.2 分段规则的实操调优

上传文档后，Dify会进入分段设置页。很多新手直接点"自动分段"就完事了，结果实际问答效果很差——用户问的问题，系统找不到答案，或者答案上下文错乱。这是因为自动分段不一定适合你的文档结构。

Dify的分段规则支持几种方式：自动分段（默认按长度）、自定义分段（指定分隔符）、按Markdown标题分段。我的习惯是：

• 面向FAQ的纯文本：选自定义分段，分隔符设为换行符，最大分段长度设500左右，重叠50。
• 结构清晰、带标题的Markdown/Word：选按Markdown标题分段，语义完整。
• 代码示例多的文档：必须手动拆，否则一段里可能混着好几段代码，检索时很难定位。

分段的核心原则是"语义完整"：一个分段最好是一个独立的知识块，能被单独检索。分段太大会导致命中后上下文太多，模型容易抓不住重点；分段太小又导致语义割裂，检索精度下降。这是一个需要根据实际文档反复尝试的环节，没有万能参数。你可以在创建知识库后反复调整分段规则重新切分，多试几次，找到最适合你文档的模式。

5.3 索引与召回：向量检索的"召回率"问题

分段完成后，Dify会生成索引。这时候可以选择索引方式：高质量（向量索引）或者经济（关键词索引）。高质量模式需要配置嵌入模型，前面提到的bge-m3就能用。向量索引的优势是能理解语义，比如用户问"退货流程"，文档里写的是"退款处理步骤"，它也能匹配上。经济模式按关键词匹配，速度快但鲁棒性差。

创建知识库时选择"高质量"模式，并指定嵌入模型。第一次索引数据时，如果文档比较多，会花一些时间，可以在知识库列表看到索引进度。

创建完成后，在知识库页面右侧有一个"召回测试"入口，可以输入一句测试问题，查看从库里召回了哪些分段以及它们的分值。这一步非常重要——如果召回结果都不是用户问题的真正答案，后面的智能体再怎么调提示词都没用，因为源头就错了。召回率低时，修改分段规则重新切分，通常比改提示词更有效。

在应用里挂载知识库时，召回设置默认是"向量召回"（对应高质量模式）。如果需要更高准确率，可以开"混合召回"并配置Rerank重排模型，不过重排模型对本地部署来说是额外的资源消耗，初次尝试建议先用向量召回跑通全流程。

5.4 在应用里挂知识库并验证

知识库建好并完成索引后，需要把它挂到一个应用里才能真正对话。在Dify后台创建"聊天助手"应用，选择模型（用之前配好的Ollama或云端模型），然后在右侧的上下文中添加刚才的知识库。

验证环节我建议这样做：在调试对话窗口里问三个角度的测试问题。

• 第一，直接命中知识库中的原文内容——验证基本检索是否正常。
• 第二，用同义表达提问——验证向量语义是否生效。
• 第三，提问一个知识库中没有的问题——测试模型在找不到答案时的表现。

第三点很关键，因为它暴露了知识库问答最常见的缺陷：明明没有答案，模型却根据训练数据编了一个。解决方法是修改提示词，明确要求"当知识库没有相关内容时，必须说明未收录"。这一步从知识库问答的质量角度看，比所有参数调优都重要。

6. 智能体配置：让它学会调工具、查资料、给结论

6.1 创建智能体应用

知识库挂上去之后，这其实就是一个"带知识库的聊天机器人"，但还不是真正意义上的智能体。智能体和聊天助手的主要区别在于：智能体有工具调度能力，它可以决定在回答某个问题之前先去调用哪个工具，再根据返回结果组织回答；聊天助手则主要依赖固定的指令和附加上下文。

在Dify后台创建应用时，选择 "Agent（智能体）" 类型。创建后需要做三件事：选模型、写提示词、绑定工具和知识库。和聊天助手相比，智能体的模型建议选择工具调用能力比较强的模型，因为工具调度依赖模型对工具描述的理解。

如果你在Dify里配置的是Ollama本地模型，Dify会尝试使用它的工具调用能力。不同模型的Function Calling效果差别很大，如果频繁出现工具调用失败、不按预期执行的情况，一个简单方案是换一个在大模型工具调用方面更成熟的模型，比如接入云端接口，或者选本地支持Function Calling表现更好的模型。

6.2 完整提示词工程实例

下面举一个"客服智能体"的例子。这个智能体的知识库是我在上面的"企业内部产品知识库"基础上做的。提示词可以写成：

你是一个产品客服助手，面对用户时帮助解答关于产品功能、使用、退换货等问题。 工作流程： 1. 先判断用户问题的类型。如果是产品相关问题，优先从知识库检索答案。 2. 如果知识库中有相关信息，基于知识库内容组织回答，并保留原文中的关键数据。 3. 如果知识库没有相关信息，明确告知用户"该问题在知识库中未收录"，不要编造。 4. 如果用户问的是与产品无关的话题，礼貌地引导回产品话题。 注意事项： - 回答尽量简洁，不要超过500字。 - 如果问题涉及多种情况，分点列出。 - 不要泄露内部系统的技术细节。

这段提示词的关键是"如果知识库没有相关内容，不要编造"。实测下来，这句话对回答质量的影响最大。另外，把"工作流程"拆成编号步骤，比一大段描述性的指令更容易被模型遵循。

写完提示词后，在上下文中添加知识库，然后可以在调试窗口测试。Dify的智能体调试界面会展示模型每一步的判断，比如"是否需要调用工具""调用了哪个知识库""检索结果是什么"。你可以清楚地看到它是在"看文档"还是"自己编"。

6.3 调试中的几个高频坑

第一个坑：智能体完全不查知识库。模型认为自己的通用知识能回答所有问题，所以直接回答了。解决办法是在提示词里加强指令，把"优先从知识库检索"写清楚；另一招是把知识库的检索参数调整一下，比如降低阈值，让模型更依赖检索结果。

第二个坑：Function Calling调用失败。现象是用户问一个问题后，模型没有触发工具调用，或者触发了但报错。这种情况大多是因为所选模型不支持或对工具的指令理解弱。可以尝试用Dify内置的"查看日志"功能查看具体错误信息，并根据错误提示更换模型。

第三个坑：知识库检索结果太多，模型不知道选哪段。这通常是分段粒度的问题。把每个分段的长度缩小，特别长的文档重新切分，让每次检索返回的结果更聚焦。

第四个坑：加了多个工具之后，模型会先走工具再回答，导致响应变慢。如果只是知识库问答场景，没有必要给智能体配一堆无关工具。一个知识库工具加一个搜索工具通常就够用了。

我建议的做法是：先用一个最小可用的智能体跑通，确认答案质量达标后，再逐步添加工具和工作流。开始就堆砌太多功能，调试时会分不清问题出在哪一层。

7. 复盘：我踩过的坑和速度优化建议

7.1 部署阶段最容易翻车的几个问题

这一节把我在Windows上部署Dify时经常遇到的报错和解决办法整理成一张速查表，给后来的人少走弯路。

这些坑大部分都和环境变量、网络地址有关。遇到问题不要第一反应是"重装"，而是先看日志，日志里的一行报错比任何猜测都靠谱。

7.2 让本地部署更方便的小技巧

最后分享几个我实测有效的小技巧。

一是给模型留一定的预热时间。Ollama加载本地模型需要时间，如果隔了很久才第一次提问，会有明显的延迟。可以在正式使用前，通过ollama run让它先加载一次，或者在自己开发的脚本里设置 keep_alive 参数，让模型常驻内存。对日常测试这个影响不大，但如果要做演示、给团队用，这个细节一定要处理。

二是Windows关机前先停掉Docker服务。Docker Desktop默认会在Windows退出时停机，但偶尔出现异常，容器数据损坏的概率不是零。养成习惯：长时间不用时执行docker compose down停掉整套Dify，比直接关机更稳。

三是数据备份的核心。Dify的数据都在PostgreSQL里，知识库的文档索引在向量数据库里。在升级Dify版本之前，用docker compose down停止服务后，对docker卷做一个整体备份。Dify官方文档对升级有说明，但实际经验告诉我，备份卷永远不嫌多。

四是一次性占用太多内存时，可以调整WSL配置。编辑%UserProfile%\.wslconfig，在里面限制WSL的内存和CPU。比如给WSL分配8GB内存和4个核，让Windows本身不至于被拖垮。这个文件在启动前生效，改完需要wsl --shutdown重启WSL。

我认为最值得记住的一点是：Dify这套系统，关键难点不在Dify本身，而在它外部的运行环境——Docker、模型API、嵌入模型、网络端口。把这几层基础打好了，剩下的就是配置项的填空游戏。希望这篇血泪总结能帮你在Windows上顺利把整套系统跑起来，而不是在"装环境"这一步就放弃了。