Dify 应用交付全流程：从一台服务器到客户能用的应用

📖 摘要：先说成色：这是一次完整交付演练的复盘，不是已经跨场景验证过的方法论——文中所有数字都是单案实测值，不是普适结论。在这个前提下，它回答一个具体问题：Dify 类 AI 应用，怎么做才交得出去。文章用我们自己的一次完整交付演练做主线（一份 22 段的产品手册 + 一份常见问题，自有测试实例），把 需求收集 → 需求分析 → 方案与边界 → 环境落地 → 语料工程 → 应用上线 → 验收 → 交付 → 巡检维护 九段逐段走一遍：每段发生了什么、我们固定怎么做（判据与产出物）、留下了什么，并给出九段判据总表。全程带真实实测数字（一次串联 14 个阶段 150.5 秒、验收用例 15/15、备份抽样恢复出 143 张表）。哪些是实测、哪些是项目经验、哪些还没验证，文中分开标注。

客户第一次开口，通常是一句话：

「我们有本产品手册，还有一份常见问题，客服每天要回几十遍同样的问题，能不能做个能问的机器人？」

这句话听上去是技术需求，其实只是开场白。真正决定这个项目能不能做完、做完能不能用的，是客户后来才问出口的三个问题：

• 装上了吗？（能打开不等于能用）
• 你怎么证明它是对的？（答错了谁负责）
• 以后谁来维护？（资料更新了怎么办）

我们做 Dify 应用交付，整套做法就是围绕这三个问题建的。一句话概括：交付物不是文档，是一条有门禁、有证据、可复算的流水线。

下面的主线是我们自己做的一次完整交付演练：一份自己造的产品手册（一款智能手表，22 段）和一份常见问题（清洗后 43 段），在自有测试实例上从需求走到维护，每一步都留了痕。手册是我们造的，数字全部来自实测记录。

文中三类信息分开标注，读的时候可以先看这个：

• （实测）——本次演练的真实运行结果，有留痕可查
• （经验）——我们在真实项目里反复用到的做法，不带数字
• （待验证）——样本不足或属于推断，文末专门讲，含验证计划

先看这条链

链上每个环节都挂两样东西：判据（什么算过）和产出物（留下什么）。没有判据的环节等于没做，没有产出物的环节等于说不清。

把九个环节的判据摊平，就是下面这张表——它也是全文最该被对照使用的一张表：

一、需求收集：在客户的三句话里，找五个答案

客户带资料来的时候，脑子里通常只有「我要个能问的机器人」。我们要的是另外五个答案：业务目标（省客服人力，还是让客户自助）、谁在用（内部员工还是外部客户）、资料从哪来（谁写的、多久更新）、谁算验收人（谁能拍板说「可以了」）、答错了会怎么样（内部查一下就好，还是会影响对外服务）。

中间两个最容易被跳过，也最要命。演练里我们问「以后谁负责更新这份手册」，对面停了几秒——这个问题之前没人想过。而资料没人维护的问答系统，上线那天就是它开始过期的第一天。

所以我们固定的动作是：访谈问题清单五问 + 一次资料盘点（多少份、什么格式、谁维护、是不是最新）。五问答不上来，不进入下一步（经验）。留下的是一份访谈结论与资料清单，含更新责任人——它后面会变成边界卡和验收口径的输入。

二、需求分析：先判能不能做，再谈怎么做

拿到资料，我们先做就绪度判断，四个问题：答案在不在资料里（还是需要实时数据）、问题分布什么样（多少能答、多少答不了）、是检索还是要推理（检索能答的别硬上推理）、边界在哪（哪些必须明确拒绝）。

演练里这一步的产出很关键：我们发现有一类问题——比如「这个型号什么时候停产」——手册里根本没有答案。这不是「做得不好」，是资料里就不存在。于是提前说清：能答的答准，不能答的明确说「资料里没有」，超出范围的拒绝回答。

这句话后来变成了验收口径，也就是三类问题：库内问题答对、库外问题明说未找到、越界问题拒绝。验收标准不是交付时定的，是这时候定的（经验）。

产出是三类问题口径 + 每类 3 条样例，客户确认「这就是我要的」。判断结果是「需要补资料」或「这类需求做不了」，我们直接说，不往下走。

三、方案与边界：开工前把「什么算做完」写死

这一段的产物是一页纸：边界卡。内容不复杂，但每条都要双方认下——这次做什么、这次不做什么、验收口径是什么、环境与模型 key 谁提供、资料更新谁负责、分几期做。

演练里我们写下的是：做产品手册与常见问题的问答（含引用出处）、不做表格与图片解析、不做多语言、不承诺跨大版本行为一致；环境用自有实例，模型 key 自备；资料更新先由我们跑一遍流程，之后交给客户。

「不做什么」和「做什么」一样重要。多数交付纠纷不是做不出来，而是我以为做完了，你没说要（经验）。边界与验收口径双方确认后才动第一刀。

四、环境落地：先让地基合格

环境有两种：客户给一台服务器让我们部署，或者客户已经有 Dify 让我们接管。不管哪种，第一件事都是部署后自检——十项关键项：容器在不在跑、端点通不通、磁盘与内存余量、数据库能不能查、备份在不在、管理入口有没有暴露到公网。

演练里这一步当场报出了问题（实测）：自有实例的备份目录是空的（跑了很久，一次备份都没做过）、有个组件在反复重启（7 次）。另一次对外部实例做外部视角审计时，报出控制台登录页对公网返回 200、一个非必要端口对外开着、证书只剩 61 天。

这三类问题有个共同点：它们都不影响「页面能不能打开」，所以只要不做这一步，就永远发现不了。判据是严重项清零才往下走；暴露面问题按「限制来源 / 加访问控制 / 收紧端口」逐条处置。

五、语料工程：把资料变成能检索的东西

资料进库不是「传上去就完了」。这一段要走五步：清洗、分段选型、建库、检索配置、体检。

演练里最值钱的一次发现来自体检（实测）：常见问题那份语料有 51 个段，其中 8 个是「续航与充电」这种纯分类标题段（占 15.7%）。它们没有答案内容，却因为主题词密度高在检索里排得很靠前——客户问「续航多少天」时，正是这些标题段把真正的答案段挤出了前五名。删掉这类孤立标题行后：51 段变 43 段，短段率从 15.7% 降到 0，同一个问题再问一次，答案段回到第一位。

**但真实的交付不会只给你一次干净的机会。**同一次演练里还有一次很难看的失败（实测）：手册改了一个参数（电池容量），我们更新了手册那一份，却漏了常见问题里同样写着这个参数的条目——残留检查直接判 FAIL，因为它的做法是「按事实扫，不按文件扫」。补上那份之后才是 2/2 通过。同一次里，语料更新后的守门员问题集回归还失败过一条：一个口语化的短问法没能召回正确段，把前五的位置让给了别的段落；查下来根因不在参数，而在问法覆盖与语料表达。

两条经验就落在这里（经验）：分段不是越细越好——纯标题段会被检索当成高相关内容；更新不是文件级动作——同一个事实往往写在多处，改完必须按事实回扫。判据是短段率低于 10%、破碎段为零、目标问题能召回。

六、应用上线：一份 DSL 进，一个能用的应用出

配置好应用（节点编排、提示词、检索设置），接下来五步：导入、依赖检查、发布、建 Service Key、冒烟对话。

依赖检查这一步是门禁，不是走过场：它检查应用用到的模型、插件、工具在目标环境里有没有——缺一个，导入到客户环境里就是打不开。演练里这个项目是干净的（实测），但这条门禁在实际项目里拦过人（经验）：环境装的东西和开发环境不一样，是交付里最常见的意外。

冒烟对话只问三类问题（第二步定下的口径）。演练里三问都有应答（实测）：库内答出具体参数，库外明确说资料里没有，越界问题直接拒绝。同时发现一个细节：回答里没有给出处引用，因为配置里引用开关是关着的——想要「答案 + 出处」，这个开关必须打开。

七、验收：这一步决定「你怎么证明」

验收分两层：静态检查（DSL 本身有没有结构性问题，112 条规则，零第三方依赖，可直接进流水线）和用例执行（真的问、真的答、按事先定好的期望判定）。

演练里静态检查报出一条「严重」：某个节点的变量名像凭据。翻代码核实——那个变量是拿检索结果去重用的键，不是密钥，属误报。这里有个岔路：改代码骗过规则，还是让它留在报告里？

我们的选择是第三条：写豁免 + 理由，并在报告里单列一节「已豁免」。工具要在客户手里被信任，靠的不是「从不报错」，而是「报了错能被解释清楚」。

豁免不是万能通行证。它的成立条件我们卡了三条（经验）：证据可复核（能指到具体代码行）、理由具体到能被人反驳、客户知情（报告里单列一节，不是藏起来）。反过来，涉及安全、数据出域、合规这三类的告警不允许豁免——那类问题只能修，不能解释。第一次跑这套机制时，那条「严重」看着很像真的，我们花了时间翻代码才敢认它是误报；如果当时翻不出来，结论就应该是「先修，不豁免」。

随后 15 条用例跑下来 15/15 通过（实测）。但有个容易混淆的点值得记住：静态检查抓的是「兜底缺失」（知识库没命中时该走什么分支），用例执行证的是「当前这条路径没出事」——一个防未来，一个证现在。两层一起给，才叫证据。

最后把结果基线化：这份基线之后每次变更都要拿来对账，回答一个问题——这次改动有没有把原来好的弄坏。

八、交付：不是交完就走

交付这一步，我们用一份可勾选的清单逐条过：应用与知识库可用、验收证据齐、环境自检过、巡检基线有、凭据已单独移交、客户侧有人能自己跑一遍。

演练里，我把前面所有环节串成一条链跑了完整一遍：14 个阶段、150.5 秒（实测）。这里要说清这个数字是什么——它是单次串联记录：自有实例、环境处于热态、只统计机器执行时间，不含需求访谈、口径确认、语料准备这些人工环节；换成冷启动或网络受限的服务器，时间会明显变长。所以它给的是量级（不到三分钟），不是承诺。

凭据有一条硬规矩：Service Key 单独渠道移交，不进报告、不进交付包。报告里只有数量、体积、状态，没有内容、没有凭据。

「客户侧有人能自己跑一遍」这句不是客套。演练里交付的是三样东西：能用的应用、能复跑的工具与判据、一份逐阶段的交付报告。客户拿到的不只是结果，还有自己维持下去的能力（经验）。

九、巡检维护：交付之后那一段

多数交付在这里就结束了。但客户的问题从这一刻才开始：资料会更新、模型会变、机器会满、证书会到期。

定期巡检：五组二十二项——服务（容器与重启、日志错误量）、资源（磁盘、内存）、数据（库体积、备份新鲜度）、应用（应用与知识库规模、索引状态、运行失败率）、暴露面（端口、控制台可达性、证书）。演练里巡检报出那个反复重启的组件（实测，7 次）——这类问题不影响使用，但它是事故的前兆。

备份有效性验证：备份不是「脚本跑成功、文件在」就算数——没验证过恢复的备份等于没有备份。做法是起一个临时容器，把最新备份真导进去一遍：演练里 142.3 MB 的备份恢复出 143 张表、关键表 120 行（实测）；验证完临时容器立即删除，生产库全程不动。

资料更新：手册改了参数，走更新流程——演练里文档 ID 不变、约 5 秒完成重索引（实测）；更新的同时跑守门员问题集（更新前 3/4 → 更新后 4/5）与残留检查（2/2 通过），确认「旧说法没有漏在别处」。

变更后回归：任何改动（换模型、改提示词、更新资料）之后，拿验收阶段的基线和当前结果对比，看清哪些变好、哪些退化。

这里有一条边界我们守得很死：巡检只读。脚本不改任何环境配置，发现问题只出清单与修复建议——改不改、什么时候改，由人决定。客户环境里的自动改动，是事故的常见来源。

回到开头的三个问题，答案在这一段收口（实测 + 经验）：

• 装上了吗——靠环境自检十项与冒烟三问回答：不是「页面能打开」，而是容器、端点、依赖、库、索引、备份、暴露面都有实测值
• 怎么证明是对的——靠可复算的证据链回答：静态检查、用例执行、验收报告、回归基线，客户拿同一套工具复跑应当得到同样结论
• 以后谁维护——靠巡检、备份恢复演练、资料更新流程与变更回归回答：交付时把工具与判据一并给客户，他们自己就能跑

我们交付时固定的七条做法

九段讲的是「一次交付怎么走」，这七条是走法背后的原则——每条都指回它在哪一段被验证过。

一、交付物是能跑的东西。（落在第四、八、九段）交付的不是说明书，是能执行的东西与能复跑的证据：每条交付物回答「装什么、怎么起、跑起来什么样、边界在哪」。

二、门禁驱动：过不了就不往下走。（落在第四、五、六、七、九段）判据不达标就停在那一段。停下来不是失败，是不让问题走到客户手里。

三、验收口径前置。（落在第二、三段）验收标准在开工前定。问答类项目落到三类问题：库内答对、库外明说、越界拒绝——这三条定死了，「好不好用」就不再是各说各话。

四、证据可复算。（落在第七、九段）检查、用例、报告、基线全部落在文件里；同一份 DSL 用同一套工具复跑，应当得到同样结论。可复算是证据和截图的区别。

五、环境层也纳入交付。（落在第四、九段）不只看应用能不能用，还要看环境本身有没有基线。环境没基线，后面所有问题都查不清楚。

六、语料工程有质量门禁。（落在第五段）清洗有判据、分段有选型依据、更新后按事实回扫。语料质量不上门禁，检索效果就只能靠运气。

七、能力转移，变更可回归。（落在第八、九段）交付时把工具与判据一并给客户；每次变更后拿基线对账。交付的终点不是「我帮你做好了」，是你能自己维持下去。

给技术读者：实现细节怎么落地

上面讲的是判断，这一段讲东西长什么样，方便想复跑的读者核对。

静态检查：规则库从真实交付踩过的坑里沉淀，按「严重 / 一般 / 提示」三级；实现只有标准库依赖，所以能直接挂进流水线（本次 112 条规则，实测）。每条结论都带规则编号与代码位置，报告可逐条核对。

误报豁免：豁免表是一个 JSON 文件，每条必须写「规则编号 + 命中位置 + 理由」，理由为空则这条豁免不生效；报告里单列「已豁免」一节，客户能看到我们豁免了什么、为什么。安全、数据出域、合规三类问题不开放豁免。

用例执行：用例表的期望值来自对目标应用的实际探测，不是抄来的——换了语料就要重新探测期望值，否则跑出来一片红但不说明任何问题。判定按事先写好的口径（关键词命中 / 明确拒答 / 明说未找到）。

回归基线：把静态缺陷集合与用例结果落成基线文件；变更后做 diff，输出三类结论——新增问题、已修复、回归（原来通过现在不通过）。

巡检：五组 22 项，全部通过只读命令采集（命令级白名单 + 破坏性动作拦截），不改环境；报告给出异常分级、修复建议，并与上次结果对比。

备份恢复验证：起临时容器导入备份，验证表数与关键表行数，验证完删除容器；生产库与生产卷全程不挂载、不写入。

这套做法还没验证到什么程度

这部分是本文最该被认真读的一段。三个条件我们目前只有单点经验，没有跨场景对照数据——每个条件我都写上现在的推断和打算怎么验证。

**一、资料规模差一个数量级。**演练里是 22 段手册 + 43 段常见问题；放到几千页手册、几十万段的规模，分段策略、检索配置、巡检节奏要不要改，我们只能推断。（待验证） 推断：分段与检索配置要按资料结构重做，巡检频率要提高；备份与恢复的时间成本会变成主要矛盾。 验证方式：拿一份体量差一个数量级的真实资料跑同一条链，对照段数分布、目标问题召回情况与体检指标。 验到哪算过：三项指标不劣化，且总耗时仍在可接受范围（按项目的维护窗口定）。

**二、客户中途改边界。**演练里的边界卡一次定成。真实项目里「不做什么」被推翻、范围临时扩大是常态，这套流程的重定基线成本有多高，我们只有零散经验。（待验证） 推断：成本主要落在验收口径的重新确认与基线重建，而不是脚本本身。 验证方式：记录一个中途改过边界的项目里，重定边界前后的返工量（返工工时、基线重建次数、用例改动条数）。 验到哪算过：返工量可估、可接受，且不影响交付节奏。

**三、语料质量本身就烂。**演练用的是自己造的手册，结构清楚。面对扫描件、多版本并存、关键信息互相矛盾的资料，清洗与体检的判据需要重新校准。（待验证） 推断：需要把门禁从「格式质量」（短段率、破碎段）扩到「事实一致性」——同一事实的多个版本要能检出冲突并给出待人工确认清单。 验证方式：拿一批真实脏资料跑清洗链，统计冲突检出率与误报率。 验到哪算过：主要冲突能自动检出、误报在人工可接受的量级，这层门禁才算有效。

再往下一层：一次完整演练的样本量，只能支持「流程走得通」这个结论，支持不了「这套做法在多数项目里都成立」。这也是我把标题里那个「全流程」当流程图理解、而不当承诺的原因——流程是完整的，验证还在路上。

后续最有价值的事不是再润色这篇文章，而是再跑几次真实交付，把上面三个条件各自的失效边界打出来。到那时，「门禁驱动」才真的不只是听起来稳。

这套流程适合什么项目，不适合什么项目

适合：资料相对稳定（有明确维护人）、有明确使用者、能接受「答不出要明说」而不是要求「什么都能答」、愿意把验收标准在开工前定下来的项目。

不适合：要求三天出个能演示的壳（门禁环节省不掉，能做到什么程度、哪些门禁可以裁见 FAQ 第一条）、要求承诺「回答 100% 准确」（大模型做不到，能做的是口径与兜底）、资料散落且没人能确认哪份最新（语料质量不可控，效果必然扯皮）的项目。

常见问题

这套门禁要花多少时间？时间紧的项目要不要做全链？

先分两类时间。机器时间可以忽略：整条链一次串联跑通是 150.5 秒（单次记录）。真正花时间的是人工环节：需求访谈与验收口径确认、语料清洗与分段选型、豁免核实、异常处置——这些按项目规模算，压不掉，但门禁可以裁剪。

裁剪的取舍是这样的：自检、冒烟、用例这三件不能省，省了等于没验证就交付；巡检与备份恢复验证在首次交付时至少各做一次，否则你回答不了「坏了能不能恢复」；静态检查与回归基线是给后续变更用的，如果这个应用确定不再改，可以先不做。反过来——如果客户后面还要改（换模型、更新资料），没有基线的话，每次改动都只能靠感觉判断有没有改坏。

怎么判断一个知识库类 AI 项目能不能做？

先看四个问题：答案在不在资料里、问题分布能不能覆盖、是检索还是需要推理、哪些必须明确拒绝。判断的关键不是「技术上能不能实现」，而是资料里有没有答案——资料里没有的，模型只能编，这类问题要在需求阶段就挑明。做法是出三类问题样例（库内 / 库外 / 越界）各三条，项目能不能做，看这三类样例答得怎么样。

知识库分段到底怎么选？为什么短段率是个指标？

分段不是越细越好。分段过细会把「续航与充电」这类纯分类标题切成独立段——它们没有答案内容，却因为主题词密度高在检索里排前，把真正的答案段挤出候选。我们的做法是先按资料结构选分段方式，建完库看两个数：短段率（低于 10%）和破碎段（为零）。演练里清掉孤立标题行之后，段数从 51 降到 43，短段率从 15.7% 归零，同一个问题的答案段回到了第一位。

检索效果不好，先调参数还是先调语料？

先看根因在哪一层，别急着动参数。我们在演练里试过一轮：把候选池从 3 调到 5 有效；再往上加、调相似度阈值、加 rerank 都没有明显增益——因为问题不在参数层，而在问法覆盖与语料表达：一个口语化的短问法压根没把正确段召回到候选里，参数再调也救不回来。做法是分层判读：先看候选池里有没有正确段（没有 = 检索 / 语料问题），再看它在池里的排序（有但排后 = 排序 / 问法问题），最后才动参数。

静态检查和用例执行，为什么两个都要做？

两者证明的不是一回事。静态检查看的是结构性问题与兜底缺失——比如知识库没命中时该走什么分支、提示词里有没有防注入的隔离约定；用例执行证明的是当前这条路径没出事。一个防未来，一个证现在。只跑用例，等于只证明了你测过的那几条路是通的；只跑静态，等于只有防范没有实测。

语料更新后为什么还要跑「残留检查」？

因为「更新」不是文件级动作，是事实级动作。演练里我们改了一个参数，更新了手册那一份，却漏了常见问题里同样写着这个参数的地方——残留检查（按事实扫，不按文件扫）当场判 FAIL。同一个事实往往写在多处：手册、FAQ、工单模板、对外文档。改完不回扫，客户就会在另一处读到旧说法。

误报豁免什么时候成立，什么时候不成立？

成立要同时满足三条：证据可复核（能指到具体代码行）、理由具体到能被人反驳、客户知情（报告单列一节）。反过来，涉及安全、数据出域、合规的告警不允许豁免——那类问题只能修，不能解释。还有一条经验：如果你花时间翻代码仍然解释不清，结论就该是「先修，不豁免」。

为什么不能承诺「回答 100% 准确」，能保证的是什么？

因为大模型的输出是概率性的，而资料本身也可能有缺口、有多版本矛盾——这两件事都不是靠调参能消除的。能承诺的是三件具体的事：能答的答准（有资料有出处）、答不了要明确说没找到（不许编）、超出范围的拒绝（越界问题不硬答）。把这三条做成可验收的口径，比承诺一个做不到的准确率有用。

多语言支持什么时候该做？

先问一句：谁在用这门语言。如果使用者都是中文，多语言只会增加语料与检索的噪声（同一份资料的不同语言版本会互相竞争召回）。我们的做法是先做单语言闭环，把分段、检索、验收口径跑顺；真有多语言需求时，按语言分库而不是往一个库塞多语言语料——分库之后，每门语言各自有一套可复算的验收基线。

备份为什么要做抽样恢复，而不是只看备份文件在不在？

因为「脚本跑成功、文件也在」和「这份备份真能恢复」是两件事。备份可能被截断、可能写在只剩几兆的分区上、可能权限不对——这些在「文件存在」这个检查里全都看不出来。抽样恢复的做法是起一个临时容器，把最新备份导进去一遍，看能恢复出多少张表、关键表有多少行；验证完容器立即删除，生产库全程不动。演练里 142.3 MB 的备份恢复出 143 张表、关键表 120 行——这才叫「有备份」。

巡检为什么只读，不做自动修复？

因为客户环境里的自动改动是事故来源：磁盘满了自动删日志，可能把需要排查的证据一起删掉；容器异常自动重建，可能把数据弄丢。巡检该做的是三件事：报出异常、给出修复建议、留下基线。改不改、什么时间改、要不要停服，这些需要业务判断和变更窗口，是人的决定。工具把判断权留着，是对客户环境负责。

相关文章：AI 项目交付全流程：一张表从启动跑到沉淀（方法层总览：九步流程与门禁）｜独立验收（二）：上线前怎么验（验收方法论）｜AI 项目烂尾的七个征兆（维护那一段的反面）

本文基于真实交付实践与自有测试实例实测撰写（2026-09）。文中数据均来自实测记录；标注为「待验证」的部分属推断，已在文中说明。AI 参与创作。