企业官网建设流程全解析

如果你最近在关注AI应用开发，Dify这个名字大概率已经在各类技术社区刷屏。定位上，Dify是一个开源的LLM应用开发平台，简单说就是帮你把大模型、知识库、工作流、Agent这些能力封装成可视化可编排的产品，让开发者不需要从零写一堆胶水代码，就能把一个有业务逻辑的AI应用跑起来。这篇是“Dify从入门到精通”系列的第一篇，目标非常明确：把Dify是什么讲透，同时带你把环境跑起来，做出第一个能对话的智能应用。适合刚接触Dify、想本地部署试一试、或者已经在用但想系统梳理一遍的朋友。

我最早接触Dify是在1.0版本刚开源的时候，当时团队要做企业内部的知识库问答系统，选型对比过LangChain全家桶、Flowise、FastGPT，最后留在了Dify上。原因很简单：Dify把模型管理、RAG流程、Agent编排、应用发布这些高频需求全部做成了开箱即用的模块，既保留灵活性，又不像LangChain那样要自己组装太多零件。接下来我会按自己的实操经历，从部署、接入模型到发布应用一步步讲，争取这篇看完你就能把Dify跑起来。

1. Dify是个什么东西：它到底解决了我什么痛点

1.1 为什么现在做AI应用这么难

做AI应用和做传统后端应用有一个本质区别：传统应用里，逻辑是你写的，数据流是你控制的，出问题你知道去哪里查。但到了大模型时代，核心逻辑变成了“模型的输入输出”，你要考虑上下文管理、提示词策略、知识库切片与召回、Token成本、模型切换、流式响应，还有用户会话多轮管理。这些东西单独拆开都还好，组合在一起就是一团乱麻。

我见过很多团队做AI功能，初期找人写一个调用OpenAI接口的脚本，测试时很爽，等到要接知识库、做多轮对话、按权限控制访问、上生产环境，脚本直接变成面条代码，改一行崩三处。Dify做的最重要的事，就是把“模型调用”和“应用逻辑”解耦。你只需要在界面上把节点拖进来、连上线、填参数，一份可维护、可观测的AI应用就完成了。它不替代你的后端，但把你后端的AI部分几乎全部接管了。

1.2 Dify做了哪些事，以及它能替代什么

Dify在LLM应用开发生态里的位置，大致相当于“WordPress之于建站”。你不需要手写HTML、CSS、JS去实现一个博客系统，而是在一个后台里选模板、填内容、发布上线。Dify也是一样，它把开发AI应用最常见的几块能力全部做成了模块：

• 模型接入层：OpenAI、Anthropic、Azure OpenAI、Google Gemini，以及所有兼容OpenAI协议的模型服务，当然也包括本地部署的Ollama、Xinference等。一套界面统一管理，切换模型不用改代码。
• RAG能力：文档上传、自动切片、向量化、检索召回，还支持Rerank二次排序，这块是知识库问答的核心。
• 工作流编排：支持类Coze的拖拽式工作流，把LLM、代码执行、条件判断、HTTP请求等节点串起来，做自动化任务。
• Agent能力：给模型配置工具，比如网页搜索、内部API、数据库查询，让它自动决定调用哪个工具完成复杂任务。
• 应用发布与管理：内部使用可以发布成WebApp，外部接入可以走API，还自带用户管理和访问凭证控制。

这套组合拳下来，Dify能替代你原本用LangChain + FastAPI + 向量数据库 + 前端页面这堆技术栈组合起来的全套后端逻辑。你省下来的时间，可以全部投入到业务本身，比如优化知识库内容、打磨提示词、调工作流逻辑，这比每天跟Embedding维度、向量库连接池参数死磕有价值得多。

2. 上手前的准备工作：从选型到本地部署

2.1 二选一：用云端版本还是自己部署

Dify官方提供了两个使用途径：一个是注册并使用Dify Cloud云端服务，另一个是社区版自托管部署。我没有贬低云端版的意思，但作为开发者和技术团队，我强烈建议至少从本地部署开始接触。原因有三点：

第一，社区版功能完全够用，核心能力与云端版基本一致，而且没有API调用配额限制。第二，本地部署意味着数据完全掌控在自己手里，企业内部文档接入知识库没有隐私顾虑。第三，部署过程本身就是一次环境预检，你能直观理解Dify的架构依赖哪些基础设施，后面出问题排错会快很多。

如果只是纯粹想快速看一眼Dify长什么样，那直接去官网注册云端版体验也可以。但如果你要认真用起来、做二次开发或者接入企业内部系统，请跟我走一遍本地Docker部署。

2.2 在Windows上本地部署Dify的完整步骤

先说环境前提：Dify本质是一组Docker容器编排，所以你需要本机装有Docker Desktop，并且把资源配额调高。Dify全家桶包含API服务、Worker、Web前端、PostgreSQL、Redis、Weaviate或Qdrant等多个容器，内存建议至少8GB，磁盘预留20GB以上比较稳妥。

我以Windows系统为例，实际步骤记录如下：

1. 去Dify官方GitHub仓库的Releases页面下载最新版压缩包，dify-main.zip这种格式。注意是docker目录所在的那个完整包，不要只下载源码片段。
2. 将压缩包解压到本地，比如D:\dify，然后进入dify-main\docker目录。
3. 在docker目录下打开命令提示符，可以先执行dir确认文件都在。首次启动前需要创建环境变量文件，直接复制模板：

   cp .env.example .env

4. 启动全部容器：

   docker compose up -d

   这里补充一下，新版本Dify已经使用docker compose插件，旧版如果是docker-compose，请更新。启动过程会拉取镜像，时间取决于网络状况。
5. 等待所有容器状态变成healthy，用下面命令查看：

   docker compose ps

6. 浏览器访问http://localhost或http://localhost/apps，首次打开会进入管理员账号初始化页面，设置邮箱和密码后即可登录。

整个过程看起来不难，但实际部署时最大的坑基本都集中在镜像拉取失败和容器启动顺序上。下面专门讲一下镜像拉取的问题，这几乎是每个本地部署Dify的人都会遇到的第一道坎。

2.3 镜像拉取失败的处理思路

我见过太多人在这一步卡死，日志里反复出现failed to pull image、dial tcp: lookup ... no such host、EOF这类错误。这不一定是你操作有问题，而是国内网络环境访问Docker Hub的常规障碍。

解决方法有几个层面，按顺序尝试：

• 给Docker Desktop配置镜像加速器。打开Docker Desktop，进入Settings -> Docker Engine，在配置JSON中添加registry-mirrors，填一个你所在地区延迟较低的加速地址。改完点击Apply & Restart。这个方法对多数人有效。
• 如果加速器效果不理想，可以考虑使用代理环境。但如果你不方便用代理，还有一个更实用的办法：找一台能正常拉取镜像的机器，用docker pull手动拉取后通过docker save导出镜像包，再拷贝到目标机器docker load。这套离线镜像迁移流程在部分企业内网环境是标准操作。
• 还有一种情况是你改了.env里的镜像版本，但本地没有对应tag的缓存，这时候可以先把旧的Dify容器彻底清理掉，再重新执行docker compose up -d，避免Tag混乱导致拉取长时间无响应。

注意：部署完成后如果修改了.env文件里的配置（比如更换向量数据库、调整端口），一定要执行docker compose down然后重新docker compose up -d，而不是只重启部分容器，否则配置不会全量生效。

3. 接入大模型：让Dify跑起来的临门一脚

3.1 模型供应商的整体概念

Dify部署完成之后，登录进去第一眼会看到欢迎页，但真正要开始用，你得先接一个大模型。Dify把模型接入抽象成了“模型供应商”的概念。供应商可以是OpenAI这种云端服务商，也可以是你本地跑的Ollama、LM Studio、Xinference等开源推理服务。

在Dify的“设置 -> 模型供应商”页面，会看到一张已经支持的供应商列表。点击任意一个提供商，填入对应的API Key和Base URL，就能激活该服务。多人协作场景下，管理员配置好模型后，团队成员直接用就行，不用每个人都去申请API Key。

这里有个很容易被忽略的点：Dify的模型分为几类，第一大类型是“系统推理模型”，也就是聊天对话、文本生成使用的底层大模型，比如GPT-4o、Claude 3.5 Sonnet，或者本地Llama系列。第二大类是“Embedding模型”，用于知识库文档向量化。第三类是“Rerank模型”，用于知识库检索后的精排。新手经常只配了推理模型，然后发现知识库上传文档后问答效果很差，一查日志才发现Embedding没配或者没配对。

3.2 接入本地Ollama模型：零成本跑通对话

如果你暂时不想花钱申请云端API，我推荐先用Ollama把本地模型跑起来，再接进Dify。Ollama是一个极简的本地大模型管理工具，一条命令就能下载并启动模型。我在没有GPU的笔记本上用Ollama跑过qwen2.5:7b，速度虽然一般，但验证流程完全够用。

Ollama安装后默认监听在http://localhost:11434，但要被Dify容器访问，这里的地址有讲究。你在Dify的模型供应商里选Ollama，填的Base URL不能是http://localhost:11434，因为Dify容器内部访问不到你宿主机的localhost。在Windows和Mac上，Docker Desktop提供了一条宿主机特殊域名host.docker.internal，所以应该填：

http://host.docker.internal:11434

在Linux宿主机上则要直接用宿主机局域网IP，如果没有额外配置host网络模式的话。这个细节，我见过不少人在社区里问“为什么本地模型连不上”，十有八九都是Base URL填错了。

填好模型名称后，点击保存，系统会做一次连通性检测。如果提示连接失败，按下面顺序排查：

1. 确认Ollama服务正在运行，浏览器访问http://localhost:11434能出现Ollama is running。
2. 确认在Dify里填的Base URL是host.docker.internal而不是localhost。
3. 确认Ollama里已经拉取了你填写的那个模型名，比如ollama pull qwen2.5:7b。
4. 在Dify容器内部临时执行wget http://host.docker.internal:11434测试连通性，能通就说明网络层没问题。

3.3 Embedding与Rerank模型：知识库效果的隐形决定者

很多人第一次用Dify做知识库问答，传了文档进去却发现回答质量惨不忍睹，不是答非所问就是漏掉关键信息。这里我先给一个经验总结：如果只配了推理模型，知识库问答的效果大概率不会好。原因在于知识库涉及两条链路，入库时要把文档切片编码成向量，这叫Embedding；检索时要对召回的候选段落做相关性精排，这叫Rerank。两者分别需要专门的模型。

Embedding方面，Dify内置支持多种模型。国内使用比较稳定的是BAAI/bge-m3系列，它可以在Ollama里直接跑。你也可以用OpenAI的text-embedding-3-small，效果不错但会产生费用。我的实践经验是，中文场景如果不追求极致效果，bge-m3已经够用；如果做专业领域（比如法律、医疗术语多），建议测试多个Embedding模型的效果差异再定。

Rerank方面，Dify推荐配置一个Rerank模型，比如Cohere的Rerank接口，或者开源的BGE Reranker。配置Rerank后，知识库检索流程会变成：先用Embedding召回Top-20候选，再用Rerank模型精排取Top-3。这一步对准确率提升非常明显，尤其是在文档数量多、内容相似度高的场景。我现在做新项目，Rerank几乎是必选项，没有Rerank的RAG系统总觉得少了灵魂。

提示：在“设置 -> 模型供应商”里，不同的模型类型要分别配置。推理模型、Embedding模型、Rerank模型是三个独立配置项，别混在一个入口里找。

4. 快速上手：从创建应用到发布第一个智能助手

4.1 应用类型的选择：聊天助手还是文本生成

模型配好之后，就可以创建第一个应用了。Dify创建应用时有几个类型选项，最常见的是“聊天助手”和“文本生成”，另外还有“Agent”和“工作流”。

• 聊天助手：适合多轮对话场景，自带会话记忆能力，用户问一句答一句，上下文自动关联。用于客服、知识库问答等。
• 文本生成：适合一次输入、一次输出的场景，比如写摘要、生成文案、翻译。它不做多轮会话管理，逻辑更简单。
• Agent：聊天助手的增强版，可以配置工具，模型在对话中会自己判断是否调用工具以及调用哪个工具。适合查数据、查天气、调API等动作型应用。
• 工作流：多节点编排模式，适合有明确流程的任务，比如先检索知识库、再让LLM总结、再做敏感词过滤、再输出。

对第一个应用来说，我建议从“聊天助手”起步。它最简单、最容易看到即时效果，而且聊天助手里也能挂知识库，足以体验Dify最核心的能力。命名可以随意，比如“第一个智能助手”，模型选择你刚接入的那个。

4.2 提示词编排界面：不需要会编程的“系统提示词”

创建完应用，会进入Dify最有名的“提示词编排”界面。左边是提示词输入区，右上角是模型参数配置，右下角可以直接跟应用对话调试，整个布局非常适合新手。

提示词编排的本质是给模型设定角色和规则。你可以把系统提示词理解为“给一个刚入职的新人写工作说明书”，它决定了模型以什么身份、什么语气、什么边界来回答。一个最简单的系统提示词可以是这样：

你是一个专业的IT技术支持助手。请用简洁、准确的中文回答用户的问题。如果用户的问题与IT无关，请礼貌说明你无法回答，并建议用户咨询相关专业人员。

界面里还可以做变量引用，比如加一个{{input}}占位符，运行时Dify会把用户输入自动替换进去。右上角的“模型参数”可以调整温度（temperature）、Top P、最大Token等。新手阶段建议温度保持在0.5以下，尤其是做知识库问答时，温度太高模型容易“编造”内容。

调试框就在右下角，直接输入“你好”测试，如果模型有响应，恭喜，你的第一个Dify应用已经活了。这里我会额外建议：先不要急着调复杂功能，把系统提示词反复打磨几次，试试不同表达对回答风格的影响，这比一开始就冲进去做工作流更有手感。

4.3 发布与调用：WebApp和API两种方式

调试满意之后，点击界面上方的“发布”按钮，应用才正式对外生效。发布后Dify提供两种使用方式：

第一，发布为WebApp。在“概览”页会生成一个访问链接，别人打开就能用，不需要登录后台。这个适合快速做Demo给业务方看效果。

第二，通过API调用。在“API访问”菜单里，Dify会生成应用的API密钥（类似app-xxx的字符串）。同时Dify提供了完整的RESTful API接口，后端服务可以用HTTP方式调用这个应用。这样Dify应用就变成了你业务系统里一个AI能力微服务，前端页面、企业微信机器人、钉钉机器人都可以通过API对接。

我第一次生产接入时，就是先把Dify应用调好，然后从自己的后端发HTTP请求到Dify的API，传用户问题、收AI回答，整体非常顺。这里提醒一下，API密钥不要暴露在前端代码里，一定要由后端代理调用，否则别人拿到密钥就能白嫖你的Token额度。密钥权限管理在“访问控制”里还可以配置允许的IP列表，建议开起来。

5. Dify核心功能地图：先看清你面前有哪些武器

5.1 工作流：把AI从一个“对话框”变成一条“流水线”

很多人第一次接触Dify，把它当成一个高级ChatGPT套壳，这就太低估它了。Dify真正的威力在于工作流，英文叫Workflow。它让你像画流程图一样，把LLM节点、知识库检索节点、代码执行节点、条件判断节点、HTTP请求节点串联起来，实现一个复杂的自动化任务。

举个例子，接一个“根据语意生成SQL”的内部工具。传统做法是你写一套NL2SQL的代码，定义意图识别、表结构映射、SQL校验、结果解释这些模块。在Dify工作流里，可以这样搭：开始节点拿到用户问题，知识库节点召回相关表结构和历史SQL样例，LLM节点基于这些上下文生成SQL，代码节点做语法校验，最后HTTP请求节点执行查询，再把结果通过LLM节点转成自然语言回复。整个过程可视化，每一步的输入输出都看得到，排错比看日志直观得多。

第一篇我先不展开工作流的细节，但你要建立这个意识：Dify不止是做聊天，它是一个应用编排平台。后面的系列文章会专门用整篇篇幅讲工作流节点的选择、参数传递、循环和分支逻辑怎么写。

5.2 知识库：Dify里最实用的企业级能力

知识库是Dify日常使用频率最高的功能，没有之一。你可以把PDF、Word、Markdown、TXT、甚至网页内容上传进去，Dify会做文档解析、分段、向量化，之后在聊天助手里开启“知识库”功能，问答时自动检索相关内容作为上下文给模型参考。

假设你有一套内部产品手册，几百页PDF，员工问“XX功能的限额是多少”，传统方式是翻文档，用了Dify知识库后，几秒钟就能得到准确答案。但前提是你得知道：文档切片粒度直接影响检索效果。切太大，检索召回准确率降低；切太小，上下文碎片化，模型缺少完整逻辑。Dify默认提供自动分段模式，但针对多级标题结构明显的文档，我建议在分段设置里开启“自定义分段标识符”，用Markdown标题作为分隔。这个方法能让段落结构更符合原文档逻辑，检索效果明显好于无脑按字数切。

5.3 Agent与多智能体：更复杂的AI应用形态

我注意到最近社区里关于Dify多智能体的讨论越来越多，比如和AgentScope、Java后端结合做多智能体协作。Dify的Agent能力目前主要是“单Agent + 多工具”模式，模型根据任务目标自主决定调用哪些工具、按什么顺序调用。Dify本身就支持在Agent里接入多个自定义工具和插件，可以实现“帮我查天气，再根据天气推荐穿搭”这种需要两步动作的任务。

如果你要做多个AI角色协同决策的“多智能体系统”，Dify的Agent可以直接作为一个节点嵌入到工作流中，外部再通过API统一编排。坦白说，多智能体本身还比较前沿，生产环境落地要关注的不只是技术，还有业务规则怎么拆、错误怎么兜底。新手阶段先把单Agent的工具调用玩明白，后续我会专门写一篇如何基于Dify构建多智能体协作应用。

6. 高频问题与避坑记录：我在实际部署和日常使用中踩过的坑

6.1 端口占用与容器启动失败

Dify默认使用80端口提供Web服务，如果本机80端口被占用，容器启动会报端口冲突。解决办法是在.env文件里改EXPOSE_NGINX_PORT=8080，然后访问http://localhost:8080。改完保存后执行docker compose down再docker compose up -d。

另外，Dify依赖的PostgreSQL和Redis如果端口被本机已有的服务占用，也会启动失败。一般改宿主机的映射端口即可，方法同上，在.env里找到对应配置项修改。启动后观察日志：

docker compose logs -f api

看到类似Starting server at port 5001的日志，基本可以确认后端已经起来了。

6.2 不同版本的差异：1.17.1和1.15.0到底差在哪

很多人在社区问Dify 1.17.1和1.15.0的区别。我在升级到1.17.1后感受明显的几个变化：一是工作流节点类型和调试体验有优化，变量赋值器的操作更顺手；二是构建Agent时的工具调优界面更清晰；三是修复了一些知识库检索的边界问题。不过1.15.0作为稳定版本，在旧项目里跑得也很好。

我的建议是：新项目直接用最新稳定版，老项目如果工作正常没必要频繁升级。升级Dify的方法是先在GitHub Releases里下载新版压缩包，备份.env和docker目录里的数据卷，然后替换代码目录，再执行docker compose down和docker compose up -d。数据卷（特别是PostgreSQL和向量数据库的持久化目录）一定不要删除，否则所有知识库和应用配置都会消失。有条件的话升级前先对整个 docker 数据目录做一次快照或者压缩备份。

6.3 几个我实际遇到过的操作细节

先说一个最不起眼但影响很大的：上传文档的大小限制。Dify默认上传文件大小限制有上限，如果你要传几百MB的PDF，可能会直接失败。这个限制可以在.env里调整UPLOAD_FILE_SIZE_LIMIT，单位是根据文档说明来的，通常用MB。我在做制造业设备手册入库时就遇到过这个问题，改成较大值后重启服务就正常了。

再说变量赋值器。Dify工作流里有一个节点叫“变量赋值器”，作用是把前面节点的输出重新组织成后面节点需要的变量格式。我印象最深的场景是：LLM节点输出的是一段带Markdown格式的文本，但下游HTTP请求节点要求JSON格式，这时候就靠变量赋值器做转换和取值。新手经常忘记看节点输出的数据类型，直接连线，导致下游解析报错。记住一个原则：连线之前先点开上游节点的输出预览，确认字段结构，再决定要不要加一个变量赋值器或代码节点做转换。

最后是第三方登录授权问题。Dify社区版支持通过飞书等平台创建应用并用于内部用户登录，但首次使用飞书云文档的授权凭证时，很多人找不到app_id和app_secret在哪。这里强调一点：飞书的凭证不是填在Dify的“设置”里，而是在创建飞书自建应用后，从飞书开放平台的“凭证与基础信息”页面复制，然后再到Dify对应渠道配置里填入。如果授权失败，优先检查回调地址是否已经配置到飞书应用的“重定向URL”里。

我自己在写这篇系列文章时，把之前折腾Dify的过程重新复盘了一遍。从最开始拉镜像失败、模型连不上，到后来用工作流做自动化报告、给业务方搭知识库问答机器人，Dify确实把我从大量重复的模型对接代码里解放了出来。第一篇的内容先到这，后面的文章我会逐步深入工作流编排、知识库进阶调优、Agent工具开发这些方向。如果你按这篇文章部署成功了，可以动手试着自己搭一个简单问答应用，遇到问题随时回来对照第6节的排查思路。