Dify实战指南：从本地部署到企业级AI应用搭建-编程实验室

各位读者朋友好。这篇文章想和你认真聊一聊 Dify。很长一段时间里，我对“低代码搭 AI 应用”这个说法是持保留态度的，总觉得这类平台要么限制太多，要么只能做玩具级 Demo。直到在一个政务类知识库项目中，团队需要把大量政策文件、办事指南快速变成一个可问答、可溯源、可管理权限的 AI 客服系统，传统开发方式从数据清洗到接口联调起码要按周计算，而用 Dify 把知识库、检索、模型调用串联起来后，整个 MVP 在几天内就跑通了，这让我对它的定位有了完全不同的认识。

这篇文章不是简单介绍 Dify 有哪些按钮，而是围绕一个完整的学习路径展开：先讲清楚 Dify 到底是什么、核心概念有哪些，再带你从零完成本地部署，然后通过多个实战项目把工作流、知识库、Agent、插件这些能力逐个练一遍。内容比较长，但每一步都可以照着操作。无论你是刚接触 AI 应用开发的新手，还是已经做过 RAG 项目、想找一个更高效编排方案的开发者，这篇文章都值得收藏备用。

1. Dify 是什么：为什么它被称为“AI 应用搭建平台”

1.1 从一次痛苦的 AI 应用开发说起

先看一个传统场景。假设你有几千份企业内部文档，想做一个能回答员工问题的机器人。传统做法大致是：

写代码做文档解析、分块（chunking）；
调用 Embedding 模型把文本转成向量；
把向量存储到向量数据库里，比如 Milvus、Qdrant、Weaviate；
搭建召回服务，把用户问题做向量检索；
设计 Prompt 模板，把检索结果拼进去；
调用大模型生成答案；
再写一个前端聊天窗口，处理流式输出；
最后还要考虑会话管理、权限、日志、评估。

这条路走下来，业务价值还没看到，基础设施已经写了一堆。更麻烦的是，模型换一个、向量库换一个，代码就要跟着改动，整个链路耦合非常严重。

Dify 解决的就是这个问题。它是一个开源的 LLM 应用开发平台，把大模型应用开发中的公共环节做成了可视化、可配置的能力：模型管理、Prompt 编排、知识库管理、检索增强生成（RAG）、工作流编排、Agent 行为编排、插件扩展、应用发布与 API 管理等。你不再需要从零拼接每一块积木，而是把精力集中在业务逻辑本身上。

1.2 Dify 的定位和常见应用类型

用更通俗的话解释：Dify 是介于“直接写代码调模型 API”和“使用别人做好的成品 AI 产品”之间的中间层。它给你一套完整的工具链，让你快速定制出属于自己业务的 AI 应用。

在 Dify 中，创建应用时有几种类型，这里提前梳理一下，后文会反复用到：

应用类型	适用场景	说明
聊天助手	客服、问答、私有知识库对话	支持多轮对话、会话记忆、提示词编排
文本生成	写摘要、翻译、文案、报告生成	单轮输入输出，更接近“调用一次模型”
Agent	需要调用工具完成复杂任务的场景	让模型自己决定调用哪些工具和参数
工作流	业务流程固定、需要多步骤串联的复杂场景	通过拖拽节点实现，如知识检索后经过代码处理再回复
Chatflow	聊天场景下的工作流	既支持多轮对话，又保留工作流节点的编排能力

这篇文章的重点会放在工作流、知识库、Agent 和 Chatflow 上，因为它们才是企业级项目中真正高频使用的部分。

1.3 你为什么要掌握 Dify

从我的经验看，Dify 至少给开发者和团队带来三个层面的价值：

第一，原型交付速度大幅提升。以前做一个带知识库的问答应用，后端接口、向量库、Prompt 调试、前端页面，一套流程下来几个工作日很正常。用 Dify 之后，绝大部分逻辑可以通过配置完成，最快几个小时就能跑通一个可演示的版本。

第二，降低模型切换成本。Dify 支持 OpenAI、Azure OpenAI、Anthropic、通义千问、DeepSeek、Ollama 等大量模型供应商。你可以在管理后台统一配置 Key，应用内部通过统一的接口调用，换模型就是后台切换的事。

第三，贴近真实项目落地。Dify 不只是可视化界面，它也提供完善的 API 接口，也就是说，你在 Dify 中编排好的应用可以嵌入到现有业务系统里。这解决了“Demo 很厉害，但无法集成”的尴尬问题。

2. 学习 Dify 前必须理解的五个核心概念

2.1 模型供应商与模型管理

模型供应商就是大模型和 Embedding 模型的提供方。Dify 中需要配置两类模型：

系统推理模型：负责对话和文本生成，比如 GPT、Claude、Qwen、DeepSeek。
Embedding 模型：负责把文本变成向量，用于知识库的索引和检索，比如 OpenAI 的 text-embedding-3-small、智源的 bge-m3。

在“设置 -> 模型供应商”页面中，你可以添加 API Key，也可以接入本地模型。对于本地私有化部署场景，最常用的组合是“Ollama 部署推理模型 + Ollama 部署 Embedding 模型”，后文第 4 节会专门演示。

2.2 工作流与节点

工作流是 Dify 最核心的编排能力。你可以把它理解成一个可视化编程环境。一个工作流由多个节点组成，每个节点完成一种确定的动作，常见节点包括：

节点类型	作用
开始	工作流的入口，定义用户输入参数
LLM	调用大模型生成回复
知识检索	从知识库中检索相关内容
代码执行	运行 Python/Node.js 代码
HTTP 请求	调用外部 API
条件分支	根据条件走不同分支
迭代	对列表数据逐条处理
变量聚合	把多个分支结果合并
参数提取	从文本中提取结构化参数
模板转换	把变量格式化为指定模板内容

工作流适合流程固定、逻辑确定的任务。例如客服场景中，用户问题进来后先查知识库，查不到就转接人工，查得到就生成回答并附带来源引用，这就可以用条件分支加知识检索节点实现。

2.3 知识库与 RAG

RAG 全称是 Retrieval-Augmented Generation，检索增强生成。它的基本思路是：在模型回答之前，先从你的业务知识库中检索相关内容，然后把检索结果和用户问题一起交给大模型，让模型基于给定的资料回答。

这样做有两个明显好处：

一是解决“大模型不知道你的私有数据”的问题。模型训练数据不可能包含你们公司内部制度、你的产品手册，但 RAG 可以把这些内容动态喂给模型。

二是缓解“幻觉”问题。因为模型是基于检索到的资料生成答案，而不是凭空想象，答案的可信度和溯源性都更强。

Dify 的知识库模块支持多种文档格式上传，包括 PDF、Word、Markdown、TXT 等。系统会自动完成分段、向量化，并提供检索测试功能。你可以调整检索模式、TopK、Score 阈值等参数。

更细说一下：文档导入后，Dify 会先把文档切分成若干分段（chunk），每个分段通过 Embedding 模型生成向量。用户提问时，系统把问题向量化，然后在向量库中找出与问题最相似的分段，这就是“召回”。召回结果再交给 LLM 生成答案。

2.4 Agent 与工具调用

Agent 是让大模型具备“行动能力”的方式。普通聊天助手只能“说”，Agent 可以“做”。例如，当你问“帮我查一下上海明天的天气”，Agent 会判断这需要调用天气工具，然后自动生成参数并调用对应 API，最后把 API 返回的结果整理成自然语言回复。

在 Dify 中，你可以为 Agent 配置工具，工具可以是内置的（比如计算器、网页搜索），也可以是自定义的 API 工具（通过 OpenAPI schema 导入）。Dify 的 Agent 默认支持 ReAct 等推理框架，让模型自己决定调用什么工具、工具参数是什么。

2.5 会话、应用发布与 API

Dify 中的每个应用都可以独立发布为 Web App 或者 API Service。Web App 可以直接得到一个可访问的聊天页面；API Service 则允许你把应用能力嵌入自己的前端或后端系统。

API 请求通过标准的 HTTP 调用完成，认证方式通常使用应用的 API 密钥（以 app- 开头）。这一点对企业集成特别重要：你完全可以把 Dify 当作一个后台服务，前端页面保持自己团队的技术栈。

3. 环境准备：Windows 本地部署 Dify 完整教程

3.1 部署方式选型

Dify 官方推荐使用 Docker Compose 部署。社区版目前可以用多种方式安装：

Docker Compose（推荐，升级方便）
宝塔面板（部分国内服务器用户更习惯）
源码本地运行（适合二次开发）
云平台一键部署

这篇文章以 Docker Compose 为例，因为它在 Windows、Linux、macOS 上行为一致，也是社区最常用的方式。建议你在自己的电脑或一台 4 核 8G 以上的 Linux 服务器上操作。

如果你使用的是 Windows，请先安装 Docker Desktop，并确保后端运行方式是 WSL 2，这是 Windows 下跑 Docker 最稳定的方案。安装完成后打开 Docker Desktop，等待右下角出现“Engine running”的提示。

3.2 下载项目与配置环境变量

打开命令行工具，按以下步骤操作。

# 1. 克隆 Dify 源码仓库 git clone https://github.com/langgenius/dify.git # 2. 进入 docker 目录 cd dify/docker # 3. 复制环境变量示例文件 cp .env.example .env

.env文件里包含大量配置项。对于初学者，大多数配置保持默认即可。但有两个地方建议先关注：

一是版本相关的镜像标签，默认会拉到当前最新稳定版本，生产环境建议固定版本号，避免后续镜像更新带来不可控变化。

二是如果你要修改端口，可以调整EXPOSE_NGINX_PORT，默认是 80。如果本地 80 端口被占用，可以先改成 8080：

# .env 示例 EXPOSE_NGINX_PORT=8080

3.3 启动并完成初始化

# 在 dify/docker 目录下执行 docker compose up -d

第一次启动需要拉取多个镜像，包括 API 服务、Web 前端、数据库、向量数据库、Redis、Nginx 等，时间取决于网络状况。启动完成后，用下面命令确认容器状态：

docker compose ps

如果所有服务都处于 Up 状态，就可以访问 Web 界面了。

假设你设置的端口是 8080，浏览器打开：

http://localhost:8080

首次访问会进入初始化页面，你需要设置管理员邮箱和密码。这一步完成后，就拥有了一个可以正常使用的 Dify 社区版实例。

补充一点，Dify 社区版升级时，进入 docker 目录后重新执行：

docker compose down docker compose pull docker compose up -d

但升级前请务必先备份数据库和 .env 文件。后文第 7 节会详细讲一个和升级相关的坑。

3.4 配置 Ollama 本地模型

在本地开发阶段，如果你想彻底不依赖外部 API，可以安装 Ollama 来运行开源模型。Ollama 是一个本地模型运行工具，支持 Llama、Qwen、DeepSeek、bge-m3 等模型。

先在 Ollama 官网下载安装包，完成后在终端执行：

# 拉取一个适合中文对话的模型 ollama pull qwen2.5:7b # 拉取一个 Embedding 模型用于知识库 ollama pull bge-m3

模型拉取完成后，确认 Ollama 服务正在运行。需要注意的是，当 Dify 运行在 Docker 容器中时，宿主机和容器之间的网络地址不能直接使用 localhost，而要用host.docker.internal这样的特殊域名来访问宿主机服务。

在 Dify 管理后台，“设置 -> 模型供应商”中找到 Ollama，填写：

配置项	填写值
模型名称	qwen2.5:7b
Base URL	http://host.docker.internal:11434
模型类型	LLM

保存后点击“模型添加”，同样方式添加 Embedding 模型：

配置项	填写值
模型名称	bge-m3
Base URL	http://host.docker.internal:11434
模型类型	Embedding

如果你在非 Docker 环境（比如源码部署）中运行 Dify，Base URL 可以直接写http://localhost:11434。这个细节很常见，很多初学者在 Docker 环境里填 localhost 导致连不上，特此说明。

4. 实战一：基于 bge-m3 本地模型搭建企业知识库问答助手

4.1 项目需求

假设你是一个企业的技术负责人，手里有一份《员工入职手册》PDF，内容包括考勤制度、报销流程、设备申请、休假政策等。你需要把它变成一个内部问答机器人，员工可以随时提问，比如“怎么申请年假？”“报销需要什么材料？”。这就是一个典型的企业知识库问答场景。

在这一个实战中，我会完整演示：创建知识库、上传文档、配置分段和检索、创建聊天助手、进行对话测试。

4.2 第一步：创建知识库

在 Dify 顶部导航栏进入“知识库”，点击“创建知识库”。

知识库名称：填写“员工入职手册”
数据源：选择“导入已有知识”

你可以在“导入已有知识”入口上传 PDF 文件。Dify 支持直接上传文件，也可以从 Notion、本地文件、Web 网页等同步文档。

点击“保存并处理”后，Dify 会开始处理文档，包括文本提取、分段、向量化等步骤。这一步会调用我们刚才配置的 bge-m3 Embedding 模型。处理完成后，进入“文档”页面可以看到文档的状态变为“可用”。

4.3 第二步：了解分段与检索设置

点击进入文档，可以看到 Dify 自动生成的分段列表。分段就是把长文本切割成若干块，每一块会被向量化。

Dify 提供“自动分段”和“自定义分段”两种模式：

自动分段：平台根据语义和长度自动切分，适合大部分场景。
自定义分段：你可以设置分段标识符、最大长度、重叠长度。

分段大小会影响检索效果。分段太大，一条里包含太多无关内容，召回精度下降；分段太小，上下文不完整，模型难以理解完整语义。一般来说，200 到 500 个 token 左右的长度，从实践看对多数企业内部文档表现不错。你可以把文档按章节拆开，不同章节独立导入，这样效果往往比让系统自动切更好。

4.4 第三步：创建聊天助手并关联知识库

在应用页面创建应用，选择“聊天助手”。

进入编排界面后，重点做三件事：

设置提示词（System Prompt）。例如：

你是一名企业内部的智能客服助手。你只能根据提供的知识库内容回答问题。 如果知识库中没有相关内容，请明确告知“当前知识库中暂无相关信息”，不要编造答案。 回答时请用中文，语言简洁清晰。

在“上下文”部分关联刚才创建的“员工入职手册”知识库。
在“模型”部分选择我们配置好的 Ollama 下的 qwen2.5:7b。

保存后，点击右上角“预览”按钮，可以直接在调试界面中输入问题测试。你可以试几个问题：

问：年假怎么申请？ 问：报销需要准备哪些材料？ 问：我们的办公地址在哪里？

观察回答是否基于知识库内容。你还可以在调试界面的“引用”区域查看模型回答时引用的是知识库的哪一段，这就是 RAG 应用的可溯源能力。

4.5 第四步：通过 API 集成到业务系统

Dify 应用编排完成后，对外提供标准 API。在应用页面的“访问 API”中，可以获取 API 密钥和调用地址。下面是一个最小化的 Python 调用示例：

import requests # 应用 API 密钥，在 Dify 应用“访问 API”页面获取 API_KEY = "app-你的密钥" BASE_URL = "http://localhost:8080/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } payload = { "inputs": {}, "query": "如何申请年假？", "response_mode": "blocking", "user": "employee-1001", "conversation_id": "" } resp = requests.post(f"{BASE_URL}/chat-messages", json=payload, headers=headers) print(resp.status_code) print(resp.json().get("answer"))

如果返回的状态码是 200，说明你已经成功把 Dify 中编排的 AI 应用，通过 API 集成到了自己的后端服务里。

5. 实战二：Dify 工作流搭建 —— 从一个客服连续对话场景说起

5.1 为什么需要工作流

聊天助手模式适合比较直接的问答，但企业里的真实业务往往没有这么简单。比如客服场景：

用户进来先要判断意图：是咨询问题，还是投诉，还是想转人工？
如果咨询问题，先查知识库；
如果知识库答不出来，是否可以转人工？
回答完要不要做满意度评价？

这类流程用普通的聊天助手很难表达，因为它没有明确的分支逻辑。Dify 的工作流就是专门解决这个问题的。在 Chatflow 或工作流中，你可以像画流程图一样，把业务逻辑编排出来。

5.2 搭建一个多分支客服工作流

下面我们创建一个 Chatflow 应用（聊天工作流），实现以下流程：

用户输入 -> 意图判断（LLM 节点） -> 如果是“咨询” -> 知识库检索 -> 生成回答 -> 如果是“转人工” -> 返回人工客服提示语 -> 如果是“投诉” -> 返回投诉处理提示语

创建一个 Chatflow 应用后，从左侧拖拽节点到画布：

第一步：添加开始节点

开始节点默认包含 sys.query 等系统变量，sys.query 就是用户的输入文本。

第二步：添加 LLM 节点做意图判断

在开始节点后面连接一个 LLM 节点，模型选择 Ollama qwen2.5:7b。在节点配置中，把输入变量设置成 sys.query，Prompt 可以写成：

请判断用户的意图，只输出以下三类之一，不要输出其他内容： - 咨询 - 转人工 - 投诉 用户输入： {{#sys.query#}}

注意：工作流节点的输入变量，在提示词里通过{{#节点路径.变量名#}}引用。这里的写法在不同版本中略有差异，请以你使用的版本编辑器提示为准。

第三步：添加条件分支节点

条件分支节点支持多条分支，每条分支设置判断条件。例如：

分支名称	条件
咨询分支	LLM 输出包含 “咨询”
转人工分支	LLM 输出包含 “转人工”
投诉分支	LLM 输出包含 “投诉”

第四步：为每个分支配置处理逻辑

在“咨询”分支下添加知识检索节点和 LLM 节点。知识检索节点选择上文创建的“员工入职手册”知识库，LLM 节点基于检索结果生成答案，Prompt 示例：

请基于以下知识库内容回答用户问题。 如果内容中没有相关信息，请告知用户“当前知识库中暂未收录该问题”。 知识库内容： {{#knowledgeRetrieval.result#}} 用户问题： {{#sys.query#}}

在“转人工”分支可以加一个模板转换节点，内容直接返回“正在为你转接人工客服，请稍等”。在“投诉”分支做类似处理。

最后把各分支汇聚到“结束”节点。

保存后，你可以进入预览界面测试不同输入，例如：

“我想问一下年假政策” -> 应该走咨询分支 “帮我转人工” -> 应该走转人工分支 “我要投诉” -> 应该走投诉分支

通过这个案例可以看出，工作流的核心价值是“把业务逻辑可视化”。每一个节点做什么、数据怎么流转、异常怎么处理，都一目了然。

5.3 客服连续对话的会话保持

很多读者搜索“dify 客服连续对话”时会发现一个问题：Chatflow 默认可能不保留多轮上下文。要实现连续对话，需要理解 Dify 的会话机制。

在对话型应用中，Dify 会把多轮消息组织成一个 conversation。前端调用 API 时，如果带上上一次返回的 conversation_id，模型就能记住之前聊了什么。在工作流中，如果需要显式把历史消息传给 LLM 节点，可以使用“对话历史变量”（Chat History 节点）或者直接把系统变量中的历史消息传入 LLM 的上下文。

在普通聊天助手应用中，只要不传新的 conversation_id，Dify 就会自动开启新会话；传入同一 conversation_id 则继续原会话。实际开发时，你应该在后端保存用户的 conversation_id，随请求传递，这是实现多轮对话最简单也最可靠的方式。

6. 30+ 企业级 Dify 实战项目的分类清单

标题里提到的“30+ 个实战项目”，我们不妨把它们按照类型划分成一张清单。这张清单的价值在于：你可以把它当作学习路线图，也可以把它当作企业落地时的需求池。

分类	项目方向
知识库类	企业制度问答、政务政策问答、产品手册助手、法律文书检索、科研文献问答、医疗知识问答、设备维修手册
客服类	电商售前咨询、售后工单分类、智能语音客服、投诉分级处理、多语言客服、客服质检
办公提效类	会议纪要生成、周报自动生成、合同审查助手、邮件分类回复、简历筛选助手、PPT 大纲生成
数据分析类	自然语言查询数据库、经营报表解读、Excel 数据摘要、异常指标告警分析、用户评论情感分析
流程自动化类	工单自动分派、内容审核流转、定时抓取汇总、多系统数据同步助手
教育内容类	知识点讲解助手、试卷自动生成、错题解析、外语口语陪练
企业知识沉淀类	新人入职培训助手、经验分享问答、项目复盘总结、风险库检索

这些项目并非全部需要复杂技术，很多是同一套能力的组合变体。例如“政务政策问答”和“企业制度问答”底层都是知识库加 RAG，只是数据源不同、提示词不同。当你做完一个完整的知识库问答项目后，其余知识库类项目基本都是换数据、调参数的重复训练。

6.1 政务 RAG 知识库项目的落地要点

在所有知识库类项目中，政务 RAG 是公认要求较高的场景，因为它对准确率和溯源性要求极高。Dify 在这个场景中的落地经验有几点值得借鉴：

一是数据治理先于平台配置。政务文档格式复杂，有红头文件、PDF 扫描件、表格、流程说明，必须做好 OCR、版式解析和清洗，否则后端的检索效果一定受影响。扫描版 PDF 如果没有做文字识别，导入知识库后检索出来也是一堆乱码。

二是分段策略要精细。政策文件经常出现“总则、适用范围、办理条件、办理流程”这样的结构化内容。建议按条、款拆分段，而不是让系统自动切块。Dify 的自定义分段和父子分段能力，可用在这一步。

三是回答策略要保守。政务场景中，模型不能自由发挥。提示词中必须强调“仅根据知识库内容回答”，检索不到就明确告知，必要时还可以配置“兜底回答”节点，把问题记录到人工处理列表。

四是权限和审计不能省。生产环境建议为不同部门建立独立知识库，应用访问通过 Dify API 密钥和业务系统的登录态双重控制。涉及敏感数据时，需要评估私有化部署方案。

6.2 用 Dify 搭建数据分析平台的实践思路

除了问答，Dify 还经常被用来做数据分析入口。项目方向是：用户输入一个自然语言问题，系统理解后转化为 SQL，查询数据库，再把结果以表格、图形或文字摘要的形式返回。

在 Dify 中，一般是这样实现的：

使用 Agent 应用，配置 Database 工具或自定义 HTTP 工具；
给 Agent 配置一个 Text2SQL 的 Prompt，说明数据库表结构，让模型生成 SQL；
通过代码执行节点或 HTTP 请求节点执行 SQL；
把查询结果交给 LLM 生成分析结论。

这种应用形态比较适合内部经营分析场景。但必须注意：生产环境连接数据库时，一定要使用只读账号，限制可查询的表和字段，避免模型生成的 SQL 造成误操作。建议设置查询超时、行数限制，并对执行的 SQL 记录日志。

6.3 离线安装插件与扩展

Dify 提供了插件机制，可以扩展工具、模型和 Agent 能力。在某些内网隔离环境中，无法直接从插件市场下载插件，这时需要使用离线安装方式：在有网环境中下载插件包，再通过 Dify 管理后台的“插件”页面上传安装。

离线安装的核心思路是准备好插件文件，而不是在线搜索安装。不同版本的插件安装界面可能不同，建议在测试环境先验证一遍再上生产。

7. 常见报错与排查思路

7.1 升级后无法保存知识库或修改知识库时报 internal server error

这是社区里反馈较多的问题之一。现象是在 Dify 升级之后，打开知识库编辑分段、保存文档时，页面报internal server error。

这类问题的常见原因和排查思路如下：

问题现象	常见原因	解决思路
知识库保存报 internal server error	升级时数据库迁移未正确执行	查看 API 容器日志，定位具体报错堆栈
知识库无法打开或文档丢失	向量数据库版本不兼容	检查 weaviate 或对应向量库容器是否正常
升级后页面功能异常	浏览器缓存了旧版静态资源	强制刷新或清除浏览器缓存
保存分段失败	版本升级后字段或 API 变化	备份数据后重新执行完整升级流程
服务启动不了	镜像版本和 .env 配置不匹配	对比升级文档中的配置项说明

排查内部错误的通用流程：

# 进入 docker 目录 cd dify/docker # 查看 api 服务日志 docker compose logs -f api

然后找到internal server error出现前后的日志堆栈。重点看有没有疑似数据库字段不存在、索引异常、模型调用失败等关键字。

解决办法通常有两类：

如果你是数据库结构老版本升级，先确认升级文档要求的迁移步骤是否全部执行。Dify 正常升级重启后，Web 容器启动时可能会自动或半自动触发迁移，如果迁移失败，后续接口就会异常。这时优先修复迁移，而不是反复重启。

如果你使用的是 Windows + Docker Desktop 环境，还要额外确认磁盘空间和文件共享配置。知识库分段向量化会频繁读写数据卷，磁盘空间不足也会表现为保存失败。

7.2 本地 Ollama 模型接入失败

问题现象	常见原因	解决思路
Dify 配置 Ollama 后测试失败	Base URL 写成了 localhost	Docker 环境改用 host.docker.internal
模型拉取后还是请求超时	Ollama 服务没有监听外部请求	配置 OLLAMA_HOST 环境变量并重启服务
知识库向量化一直等待	Embedding 模型未正确配置	确认添加了 Embedding 类型的模型
回答速度特别慢	本地模型参数量大，GPU 内存不够	换更小模型，或改用 API 模型

7.3 创建工作流后无法运行

工作流无法运行要分层排查：

先确认开始节点是否连接了后续节点，空节点会导致流程中断；
再看节点有没有报错，例如 LLM 节点模型未配置、知识检索节点未指定知识库；
观察“运行”面板的变量值，定位是哪一步数据不符合预期。

工作流调试和普通代码调试思路一样，从上游到下游逐个节点确认输入输出，往往很快就能定位问题。

7.4 网站无法访问

部署完成后如果浏览器访问不了，先按顺序检查：

# 1. 容器是否都在运行 docker compose ps # 2. 端口是否被占用 netstat -ano | findstr :8080 # 3. 防火墙是否放行端口 # Windows 需要检查防火墙入站规则

如果你是访问云服务器的公网 IP，还需要确认云安全组规则是否放行了对应端口。

8. 最佳实践与工程建议

8.1 知识库工程化：高质量数据是第一生产力

知识库质量决定 RAG 效果。文档在上传前，建议做一轮清洗：删除无关页眉页脚、修正 OCR 错字、统一表格格式。分段时不要一味追求小，而要结合文档结构，让每一段拥有相对完整的语义。对于政策文件，可以引入父子分段，子分段用于向量检索，父分段作为完整上下文输入给模型，检索命中后携带更完整的背景信息。

8.2 Prompt 管理的几个原则

第一，系统提示词要明确边界。告诉模型哪些不要回答、回答不了怎么回应。第二，变量引用要测试。工作流中{{#xxx#}}的引用路径写错是常见问题。第三，Prompt 版本建议沉淀到文档或 git 中，方便回滚和审计。

8.3 环境隔离与配置管理

本地开发、测试、生产环境建议使用独立的 Dify 实例，至少使用不同的.env配置。API 密钥不要写进前端代码，所有调用 Dify API 的请求统一走后端服务。生产环境的模型供应商 Key 可以使用环境变量注入，避免明文出现在配置文件中。

8.4 安全边界与权限控制

Dify 应用本身提供 API 密钥，但密钥一旦泄露，调用方就能无限制使用你的模型资源。建议在业务系统后端统一记录调用方身份，定期轮换密钥。对于敏感场景，优先考虑私有化部署，知识库数据不要发送到外部模型服务。

涉及外部服务调用时，所有 HTTP 请求节点都应设置超时和错误处理。工作流中涉及更新、删除等写操作时，必须明确告知用户该操作的后果，并需要二次确认。

8.5 数据备份与升级策略

生产环境升级 Dify 前，一定要先备份数据库和向量数据。至少备份.env、Postgres 数据和向量数据库数据。升级后先在测试环境验证核心功能，再对生产环境操作。遇到社区版大版本更新时，不急于第一时间升级，可以多观察社区反馈。

下面给出一个简单的备份思路：

# 使用 docker compose 执行数据库备份（示例） cd dify/docker docker exec -t dify-db pg_dump -U postgres dify > dify_backup.sql

不同版本数据库服务容器名称可能存在差异，请先通过docker compose ps确认实际容器名。备份文件要保存到独立位置，不要和容器数据卷放在同一块磁盘。

9. 总结与下一步学习建议

在这篇文章中，我们走通了一条完整的 Dify 学习路径。从平台概念说起，理清了工作流、知识库、RAG、Agent 等核心名词；然后完成了 Windows 环境下 Docker Compose 部署，并配置了 Ollama 本地模型；通过知识库问答助手和工作流客服两个实战，掌握了 RAG 应用和工作流编排的基本方法；最后整理了 30 个企业级项目的分类清单、常见报错排查方法以及工程落地建议。

如果你现在准备动手，建议按这样的顺序：先在本机部署一个 Dify 社区版，导入一份自己的文档，跑通第一个知识库问答；然后尝试创建一个带条件分支的 Chatflow，把流程控制感建立起来；再尝试接入不同模型供应商，观察同一套应用在不同模型下的效果差异；最后再看 Agent 和插件，理解模型如何自主调用外部工具。

在学习过程中遇到问题是很正常的，注意优先通过容器日志定位问题，其次再搜索报错关键字。推荐按“日志 -> 配置 -> 网络 -> 版本”的顺序排查，大部分问题都能在这个过程中找到原因。