企业官网建设流程全解析

LLM 应用开发这件事，过去一年我最大的感受是：模型能力已经不是瓶颈了，真正卡住项目进度的是"把模型接进业务流程"这一段的工程量。写一个能跑的 Demo 可能只要一个下午，但要把它变成团队里其他人也能维护、能改提示词、能换模型、能看日志的东西，往往要再搭进去两三周。Dify 这个项目就是冲着这个断层来的——它把提示词编排、知识库检索、工具调用、流程分支、日志观测这些环节拆成可视化的"积木块"，让不写后端的人也能拼出一个可用的 LLM 应用。这篇不打算写成官方文档的复述，而是按我自己从零部署到跑通一条知识库流水线的实际路径，把每个环节的选择理由、踩过的坑和调优经验摊开讲。

1. 先搞清楚 Dify 到底替你省掉了哪部分工作

很多人第一次打开 Dify 的界面，第一反应是"这不就是个聊天机器人搭建器吗"。如果只停留在对话助手这一层，确实会低估它。要理解它的价值，得先看清楚一个 LLM 应用从想法到上线，中间到底有哪些活是重复劳动。

1.1 一个 LLM 应用的完整链路拆解

抛开具体业务，任何一个稍微正经的 LLM 应用，基本都包含这么几段：接收用户输入、做输入预处理（清洗、改写、意图识别）、检索外部知识、组装提示词、调用模型、解析模型输出、执行工具或函数、把结果返回给用户、记录整条链路的日志用于后续优化。这十来个环节里，真正跟你的业务强相关的可能只有两三个，剩下的全是通用工程。

传统做法是每个环节都自己写代码。输入预处理写一个函数，检索接一个向量库 SDK，提示词用字符串拼接，模型调用封装一层 HTTP 客户端，日志自己往数据库里塞。这套东西写一遍不累，写十遍就崩溃了，而且每次换模型、换向量库、改提示词都要动代码、重新发版。

Dify 的思路是把这些通用环节做成配置项。你在界面上拖一个"知识检索"节点，选好知识库和召回参数，它就替你把向量化、相似度计算、结果拼装全做了。你换一个模型，只需要在下拉框里换一下，不用改任何代码。这就是"搭积木"这个说法的实际含义——它省掉的不是模型调用本身，而是模型周边那一圈胶水代码。

1.2 Workflow 和 Chatflow 的分工边界

Dify 里有两个容易混淆的概念：Workflow 和 Chatflow。我一开始也没分清，后来用多了才总结出一句话：Chatflow 是给对话场景用的，Workflow 是给任务场景用的。

Chatflow 面向的是多轮对话，它天然带对话历史管理、带会话变量，适合做客服、助手、问答这类需要记住上下文的场景。Workflow 面向的是单次任务执行，输入一个东西、跑一条流水线、输出一个结果，适合做内容生成、数据加工、批量处理这类不需要记住上一轮说了什么的场景。

这个区分很重要，因为它直接决定你该选哪个入口。我见过有人拿 Workflow 硬做多轮对话，结果自己在外层维护会话状态，绕了一大圈。也见过拿 Chatflow 做批量文档处理，被对话历史拖慢速度。选错了不是不能跑，是会在后面不断给你添堵。

1.3 它和纯代码框架的本质差异

市面上做 LLM 编排的框架不少，有偏代码的，有偏配置的。Dify 明显偏配置。这个取向带来的取舍很明确：上手快、改起来快、非技术人员能参与；代价是遇到特别定制化的逻辑时，你得靠它提供的代码节点或者外部 API 来兜底，灵活性不如纯代码框架。

我的判断标准是这样的：如果你的需求 80% 以上能用"检索 + 提示词 + 模型 + 简单分支"覆盖，Dify 会让你省下大量时间；如果你的需求里充满了复杂的自定义算法、特殊的并发控制、非常规的数据结构变换，那纯代码框架可能更顺手。这不是谁好谁坏，是场景匹配问题。

2. 部署方式的选择：为什么我最后选了 Docker Compose

部署这一步看起来是纯体力活，但选错方式会在后面反复折磨你。我前后试过三种方式，最后稳定在 Docker Compose 上，这里把选择逻辑讲清楚。

2.1 三种部署路径的适用人群

云服务适合做原型验证，几分钟就能开一个空间，把想法跑通再说。但只要涉及内部数据、涉及合规要求，基本都得走自托管。源码部署我试过一次，光是 Python 依赖和前端构建就折腾了半天，除非你确定要改它的核心代码，否则没必要。

Docker Compose 是甜点区。官方仓库里直接给了 compose 文件，拉下来改几个环境变量就能起。它把 API 服务、Worker、前端、数据库、向量库、缓存这些组件都编排好了，你不需要逐个去理解它们怎么通信。

2.2 起容器之前必须确认的三件事

第一件是端口占用。Dify 默认会用到 80、5001 等端口，如果你的机器上已经跑了别的 Web 服务，起容器时会直接报端口冲突。我建议起之前先ss -tlnp看一眼哪些端口被占了，心里有数。

第二件是数据卷的持久化路径。compose 文件里默认把数据库和上传文件挂到相对目录，如果你在临时目录里起的容器，重启机器后数据可能就找不到了。我习惯把数据卷统一指到一个固定的绝对路径，比如/data/dify/，这样备份和迁移都清楚。

第三件是环境变量里的密钥。Dify 需要设置一个用于加密敏感信息的密钥，这个值一旦设定就不要随便改，改了之后已存的模型 API Key 会解不开。我第一次部署时随手填了个测试值，后来想换，发现得重新录入所有模型的凭证，白折腾一轮。

2.3 首次启动后别急着用，先做这三项检查

容器起来不代表就能用。我一般会按顺序确认三件事。

先看服务健康状态。用docker compose ps看各个容器是不是都处于运行状态，有没有反复重启的。Worker 容器如果一直重启，多半是数据库连接或者队列配置有问题。

再确认数据库迁移是否完成。Dify 首次启动会自动跑数据库迁移，这个过程需要一点时间。如果迁移没跑完你就去访问，可能会遇到表不存在的报错。看 API 容器的日志，等到出现迁移完成的提示再操作。

最后验证文件上传目录的写权限。知识库要上传文档，如果容器内的上传目录没有写权限，上传会静默失败或者报权限错误。这个坑我在一台权限管得比较严的机器上踩过，排查了半天才发现是目录属主不对。

提示：升级 Dify 版本时，务必先备份数据库和上传目录。跨版本升级有时会涉及数据库结构变更，回滚没有备份会很被动。

3. 模型接入：凭证校验失败是最高频的拦路虎

模型接入是 Dify 里第一个真正会卡住人的环节。界面看起来很简单，选个供应商、填个 API Key、点保存，但实际报错五花八门。我把常见的几类问题拆开讲。

3.1 凭证校验到底在校验什么

点"保存"时 Dify 会做一次凭证校验，它会拿你填的 Key 去实际调一次模型接口，确认这个 Key 有效、有权限、能正常返回。所以校验失败不一定是 Key 填错了，也可能是网络不通、模型名不对、账户余额不足、区域不匹配。

理解这一点很关键，因为报错信息往往只说"凭证校验失败"，不会告诉你具体哪一环出了问题。你得自己按顺序排查。

3.2 按顺序排查的四步法

我的排查顺序是这样的：

1. 确认 Key 本身有效。拿这个 Key 在供应商自己的控制台或者用命令行工具直接调一次，确认它本身能用。这一步能排除掉一大半问题。
2. 确认网络可达。Dify 的容器要能访问到模型供应商的接口地址。如果容器所在网络有出站限制，请求根本发不出去。可以在容器里用curl试一下目标地址。
3. 确认模型名拼写正确。有些供应商的模型名区分大小写，或者有版本后缀，填错一个字符就调不通。
4. 确认账户状态正常。余额不足、额度用尽、账户被限制，都会表现为校验失败。

这四步走下来，基本能定位到问题。我遇到最多的是第二步，容器网络和宿主机网络不是一回事，宿主机能访问不代表容器能访问。

3.3 多模型混用的配置策略

实际项目里很少只用一个模型。常见组合是：用一个能力强的模型做复杂推理，用一个便宜快速的模型做意图识别或者简单改写。Dify 支持配置多个模型供应商，在节点里按需选择。

这里有个经验：把不同用途的模型分开配置，不要图省事全用一个。意图识别这种任务用大模型是浪费，用一个小模型又快又省。而最终生成答案的那一步，该用大模型就用大模型，别在这省。我见过为了省钱全程用小模型，结果回答质量差到没法用，反而浪费了更多调试时间。

另外，配置多个供应商还能起到容灾作用。某个供应商临时抽风时，可以快速切到另一个，不至于整个应用停摆。

4. 知识库流水线：从文档到可检索片段的完整过程

知识库是 Dify 里最能体现"流水线"思维的部分。一份文档从上传到变成可被检索的片段，中间要经过解析、清洗、分块、向量化、入库好几个步骤，每一步都有参数可调，每一步调不好都会影响最终效果。

4.1 文档解析阶段容易忽略的格式问题

上传文档后，Dify 要先把它解析成纯文本。这一步对格式很敏感。PDF 里的表格、扫描件里的图片、Word 里的复杂排版，解析出来经常是乱的。

我的做法是：能提供结构化程度高的源文件，就别提供 PDF。同样一份内容，Markdown 或者纯文本解析出来的质量远高于 PDF。如果只有 PDF，尽量用带文字层的，扫描件需要先做 OCR，否则解析出来是空的。

还有一个细节是文档里的页眉页脚和页码。这些内容在解析后会被当成正文混进片段里，检索时可能被误召回。如果文档量大，建议在解析前先做一轮清洗，把这类噪声去掉。

4.2 分块策略：为什么不能一套参数走天下

分块是知识库效果的分水岭。块太大，检索出来的内容里混着一堆无关信息，模型容易被干扰；块太小，一个完整的语义被切碎，检索到了也拼不出完整答案。

Dify 提供了几种分块方式，我常用的判断逻辑是这样的：

• 通用文本用固定长度加重叠。长度我一般设在 500 到 800 字符之间，重叠设 50 到 100 字符，保证跨块边界的语义不被切断。
• 结构化文档（比如带明确章节的说明书）用自定义分隔符，按标题层级切，这样每个块天然是一个完整小节。
• 问答对形式的资料直接按问答切，一问一答作为一个块，检索命中率最高。

这里没有万能参数。我做过一个对比，同一份技术文档，用固定长度切和按标题切，检索准确率能差出两成。所以我的建议是：先拿一批真实问题去测，看召回的内容对不对，再反过来调分块参数，而不是拍脑袋定一个值。

4.3 向量化与检索参数的配合

分块之后要向量化入库。这一步涉及两个关键选择：用哪个嵌入模型、检索时用什么策略。

嵌入模型的选择上，中文场景要特别注意模型对中文的语义理解能力。有些模型在英文上表现很好，换到中文就明显下降。选之前最好拿自己的数据实测一下。

检索策略上，Dify 支持向量检索、全文检索和混合检索。我的经验是：混合检索在大多数场景下比单一策略稳。向量检索擅长语义相近但用词不同的情况，全文检索擅长精确匹配关键词，两者结合能覆盖更多情况。纯向量检索在遇到专有名词、型号、编号这类内容时容易漏，这时候全文检索能补上。

召回数量也不是越多越好。召回太多会把无关内容塞进提示词，既浪费 token 又干扰模型。我一般先设一个中等值，然后看实际召回的内容质量，再往上或往下调。

4.4 知识库更新后的重新索引问题

文档更新了，知识库不会自动重新索引。你得手动触发重新处理。这里有个坑：如果只是改了几个字，重新索引整个文档是浪费；但如果改了结构，不重新索引又会导致新旧内容混在一起。

我的做法是给文档做好版本管理，改动大的直接删掉旧文档重新上传，改动小的评估一下值不值得重新索引。另外，重新索引期间知识库可能处于不可用或者部分可用的状态，生产环境要避开高峰期操作。

5. 用 Workflow 编排一条真实可用的处理链路

前面都是准备工作，真正体现 Dify 价值的是把节点串成一条能跑的链路。我拿一个"文档问答 + 自动分类"的场景来演示编排思路。

5.1 从需求倒推节点设计

假设需求是：用户提交一个问题，系统先判断这个问题属于哪个类别，然后从对应类别的知识库里检索，最后生成回答。

倒推一下需要哪些节点：一个输入节点接收问题，一个分类节点判断类别，一个条件分支根据类别走不同的检索，两个知识检索节点分别对应不同知识库，一个模型节点生成回答，一个输出节点返回结果。

这个链路里，分类节点是关键。它决定了后面走哪条分支。分类可以用模型做，也可以用关键词规则做。如果类别边界清晰、关键词明显，用规则更快更稳；如果类别之间有语义重叠，用模型判断更准。

5.2 变量在节点之间怎么传递

Dify 的节点之间靠变量传递数据。每个节点的输出可以命名成一个变量，后面的节点引用这个变量。理解这一点，编排就通了一大半。

我踩过的坑是变量命名混乱。一开始随手起名，节点一多就分不清哪个变量是哪来的。后来养成习惯：变量名带上来源节点的含义，比如classify_result、retrieve_docs，一眼就知道是什么。

还有一个细节是变量的类型。有的是字符串，有的是数组，有的是对象。在引用时要注意类型匹配，比如把数组直接塞进需要字符串的地方会报错。遇到类型不对，可以用代码节点做一次转换。

5.3 条件分支的边界情况处理

条件分支看起来简单，实际最容易出问题的是边界情况。比如分类节点返回了一个你没预料到的类别，分支没有对应的处理路径，整个流程就断了。

我的处理方式是：永远给分支留一个默认路径。不管分类结果是什么，都能走到一个兜底的处理逻辑，哪怕只是返回一句"暂时无法处理这个问题"。这样至少不会让用户看到报错。

另外，条件判断的条件要写清楚。多个条件之间是"与"还是"或"，优先级如何，都要明确。我见过因为条件写得含糊，导致本该走 A 分支的走了 B 分支，排查起来很费劲。

5.4 调试单个节点而不是整条链路

链路长了之后，一次性跑通很难。Dify 支持单独测试某个节点，这个功能要善用。

我的调试习惯是：从输入节点开始，逐个往下测。每测一个节点，确认它的输出符合预期，再测下一个。这样出问题时，能立刻定位到是哪个节点的问题，而不是在整条链路里大海捞针。

调试时还要注意看每个节点的实际输入是什么。有时候问题不在节点本身，而在上游传过来的数据不对。比如检索节点召回为空，可能是上游的问题改写把关键词改没了。

6. 上线之后才开始的那些事：日志、评测与迭代

很多人把应用跑通就当成结束了，其实上线才是真正工作的开始。LLM 应用有个特点：它不像传统软件那样行为确定，同样的输入可能给出不同的输出，所以持续观测和迭代是必须的。

6.1 日志里到底该看什么

Dify 会记录每次运行的完整链路，包括每个节点的输入输出、耗时、token 消耗。这些日志的价值在于定位问题。

我关注几个点：检索节点召回了什么，这直接决定回答质量；模型节点的输入提示词是什么，有时候问题出在提示词组装得不对；每个节点的耗时，找出链路里的性能瓶颈；token 消耗，控制成本。

有一次线上反馈回答不准，我翻日志发现检索召回的内容是对的，但模型节点拿到的提示词里，检索结果被截断了，只传进去一部分。问题出在提示词模板的变量拼接上，不看日志根本发现不了。

6.2 用真实问题做回归测试

应用改一次提示词、换一次模型、调一次检索参数，都可能影响效果。如果没有回归测试，你根本不知道这次改动是变好了还是变差了。

我的做法是维护一个测试问题集，里面是真实用户问过的问题，覆盖各种类型。每次改动后，拿这个集合跑一遍，人工看回答质量。问题集不用很大，二三十个有代表性的就够，但要持续补充新遇到的边界情况。

这个习惯看起来笨，但特别有效。我靠它拦下过好几次"以为改好了实际改坏了"的情况。

6.3 提示词迭代的正确姿势

提示词不是一次写好的，是迭代出来的。我的迭代方法是：每次只改一个地方，改完立刻测。同时改好几处，出了问题不知道是哪处导致的。

改提示词时，我习惯把模型的输出格式要求写死，比如要求它按固定结构返回。这样解析起来稳定，也方便判断它有没有按要求做。如果输出格式飘忽不定，下游处理会很痛苦。

还有一点是给模型留例子。对于格式要求严格或者逻辑比较绕的任务，在提示词里放一两个输入输出的示例，效果比单纯描述规则好得多。

7. 二次开发与扩展：什么时候该动源码

用久了总会遇到 Dify 原生功能覆盖不到的需求。这时候要判断：是绕过去，还是改源码。

7.1 优先用外部能力而不是改源码

大部分定制需求，其实不需要改 Dify 的源码。它提供了几种扩展方式：自定义工具可以接外部 API，代码节点可以跑自定义逻辑，外部知识库可以对接自己的检索服务。

我的原则是：能用外部能力解决的，就不动源码。因为一旦改了源码，后续升级就要处理代码冲突，维护成本陡增。我见过团队为了一个小功能改了核心代码，结果每次官方发版都要手动合并，苦不堪言。

7.2 确实要改源码时的隔离策略

如果确实需要改源码，我的建议是把改动尽量集中、尽量小，并且做好记录。把每一处改动的原因、位置、影响范围都写清楚，升级时对照着看。

更好的做法是把定制逻辑做成插件或者独立服务，通过标准接口和 Dify 交互，而不是直接改它的内部实现。这样升级时你的东西不受影响。

7.3 多租户场景下的注意事项

社区版在多租户支持上相对简单。如果要做多租户，需要想清楚租户之间怎么隔离：数据隔离、模型凭证隔离、知识库隔离。这些在社区版里可能需要自己做一些工作。

我的经验是，多租户的复杂度主要不在技术，在权限模型的设计。先想清楚谁能看到谁的数据、谁能用谁的资源，再去考虑怎么实现。技术实现反而是后面的事。

8. 迁移与备份：别等出事才想起来

最后聊一个容易被忽视但很要命的话题：迁移和备份。

8.1 需要备份的到底是哪些东西

Dify 的数据分散在几个地方：数据库里存着应用配置、知识库元数据、日志；上传目录里存着原始文档；环境变量里存着加密密钥。这三样缺一不可。

只备份数据库不备份上传目录，恢复后知识库的文档就丢了。只备份数据不备份密钥，恢复后模型凭证解不开。我见过只备份数据库的，恢复时发现文档全没了，只能重新上传。

8.2 迁移到新机器的完整步骤

迁移时我的顺序是：先在新机器上把环境准备好，装好容器运行时；然后把旧机器的数据卷整体拷过去；再确认环境变量一致，尤其是加密密钥；最后起容器，验证数据是否完整。

这里的关键是环境变量必须一致。加密密钥不一致，所有加密过的数据都解不开。所以迁移前一定要把环境变量文件完整保存下来。

8.3 版本升级的风险控制

升级前先看官方的版本说明，确认有没有破坏性变更。然后在测试环境先升一遍，确认没问题再升生产。升级前做好完整备份，万一出问题能快速回滚。

升级过程中不要中断，让它跑完。中途中断可能导致数据库处于不一致状态。升级完成后，验证核心功能是否正常，尤其是知识库检索和模型调用这两块。

我在实际操作中的体会是，Dify 这类平台的价值不在于它某个功能多强，而在于它把一堆琐碎的工程环节收拢到了一起，让你能把精力放在真正跟业务相关的部分。但它也不是银弹，参数该调的还得调，日志该看的还得看，测试该做的还得做。把它当成一个帮你省掉胶水代码的工具，而不是一个能自动帮你把应用做好的魔法盒，心态就对了。