在 AI 应用从 Demo 走向交付的过程中Dify 是绕不开的一类基础设施。它把模型调用、知识库检索、Agent 工具调用、工作流编排和日志观测组合成一个统一平台让开发者不用重复实现对话管理、向量检索和权限隔离这样的通用模块。很多团队用它来搭建智能体也会用它的可视化编辑器梳理 AI 工作流常见形态包括客服问答、企业内部知识库助手、运营文案生成以及需要多步骤调用工具的 Agent 应用。这篇文章要带读者做完的不是“把 Dify 跑起来看一眼”而是把整条链路打通先在服务器上用 Docker Compose 完成 Dify 社区版的安装与部署再接入云端或本地大模型创建一个智能体应用搭建一条带知识库检索的 RAG 工作流最后处理高频报错并给出上线前检查清单。全文面向有一定 Linux 和 Docker 基础的开发者如果只想在 Windows 笔记本上实验也可以使用 Docker Desktop 按相同步骤操作遇到网络和路径差异时会在正文里单独说明。1. 先搞清楚 Dify 到底帮你解决了什么问题1.1 为什么不是直接调模型 API还要使用 Dify很多开发者会先写一个 Python 脚本调用大模型 API 做技术验证确实几十行代码就能返回一段文本。但把脚本扩展成可用的智能体应用时问题马上会出现多轮对话的上下文怎么保存、用户上传的私有文档怎么检索、模型需要调用外部工具时谁来编排、后台如何统计用户提问和 token 消耗、不同部门的成员如何隔离权限。这些需求如果全部自己实现工作量会迅速超过 AI 功能本身。Dify 的核心思路是把“模型能力”和“应用工程能力”分开。模型只负责生成文本而“谁来调用模型、调用前要检索什么、调用后要执行什么动作、中间有哪些分支和判断、用户看到什么内容、后台留下什么日志”这些流程全部由 Dify 作为平台来承接。可以把它理解成 LLM 应用领域的低代码开发框架但它同时也保留了代码节点和 API 扩展能力并不只是一个拖拽画布。1.2 Dify 的核心模块Dify 社区版的主要模块可以整理成下面这张表模块作用典型使用场景应用管理创建聊天助手、Agent、文本生成应用客服机器人、内容生成助手工作流用可视化节点编排调用链先检索知识库再生成回答的多步流程知识库上传文档、分段、向量化、检索企业私有文档问答模型供应商接入云端 API 和本地推理服务DeepSeek、Ollama 等模型接入工具管理给 Agent 提供外部工具搜索、计算、HTTP 请求等观测与日志查看运行轨迹、token 消耗排查答非所问和节点异常这些模块不是独立功能而是一个最小闭环。一个典型的 RAG 问答应用本质上是“模型供应商 知识库 工作流 应用日志”组合出来的结果。这也是为什么官方安装完成后第一件事通常是配置模型供应商而不是直接去创建工作流。1.3 适用场景与部署形态选择Dify 社区版支持多种部署方式最常见的是基于 Docker Compose 的单机部署。它会按编排文件把 api、worker、web、数据库、Redis、模型服务沙箱等组件组合在一起适合学习、演示和中小规模内部工具。生产环境如果用户量变大就要拆分数据库、存储和推理服务或者使用 Kubernetes 部署这时需要重点考虑多副本、滚动升级、日志采集和密钥管理。部署阶段推荐方式需要关注的工程项本地学习Docker Desktop Docker Compose端口占用、镜像拉取时间团队测试云主机 Docker Compose数据库备份、访问地址、HTTPS生产环境容器编排 / K8s高可用、监控告警、数据持久化、多租户配额本文的主线是单机 Docker Compose 跑通全流程生产环境差异会在第 7 章集中说明。2. 部署前的环境和依赖准备2.1 硬件与系统要求部署 Dify 的机器在内存和磁盘上要留足余量。学习环境内存建议不低于 8GB磁盘预留 20GB 以上。如果还要在同一台机器上运行本地模型资源要求会更高此时建议把模型推理服务单独放在另一台机器或使用带 GPU 的实例避免模型加载和 Dify 主服务抢内存导致容器崩溃。操作系统方面Linux 服务器、macOS 和 Windows 都支持 Dify 的 Docker Compose 部署。Windows 下需要安装 Docker Desktop并保证虚拟化功能已开启。不同系统的差异主要体现在 Docker 安装方式、文件路径和容器访问宿主机网络的方式后面章节会分别提到。2.2 安装 Docker 与 Docker ComposeDify 社区版的官方推荐部署方式是 Docker Compose因此第一步是把 Docker 环境准备好。不同操作系统的安装方式差异明显Linux 可以使用发行版软件仓库安装 Docker Engine也可以参考 Docker 官方文档安装。macOS 和 Windows 使用 Docker Desktop 安装会同时带出 docker 和 docker compose 命令。安装完成后不要只看图标是否运行要用命令确认docker --version docker compose version这里要区分两个命令。较新的 Docker 版本使用插件形式的docker compose旧的独立脚本叫docker-compose。两者命令格式基本一致本文统一使用docker compose。如果机器上只有docker-compose把示例命令中的空格换成连字符即可。2.3 准备 Git 与模型 API KeyDify 部署需要先拉取代码仓库因此本机要安装 Git。在命令行执行git --version能输出版本号就说明 Git 可用。Dify 迭代很快部署时建议切换到稳定的版本标签而不是直接跟随 main 分支这一步会在第 3 章演示。模型 API Key 是部署后第一步配置内容。常见模型厂商包括 DeepSeek、Minimax、OpenAI 兼容服务等按各自控制台的说明创建 Key 即可。这里特别注意API Key 一旦泄露可能产生费用不要在代码仓库和聊天工具里明文传播。如果打算走本地模型路线也需要预先准备好 Ollama 或其他推理服务的安装环境但本地模型不是部署 Dify 的必要条件。2.4 部署前环境自检清单开始安装前建议按下面这张清单检查一遍检查项预期结果检查命令CPU 核数2 核及以上nproc内存8GB 及以上free -h磁盘剩余空间20GB 及以上df -hDocker 版本20.10 及以上docker --versionCompose 插件可用docker compose version端口占用80 / 443 未被占用ss -tlnp网络能访问镜像仓库docker pull busybox:latestAPI Key已准备就绪厂商控制台确认如果docker push或docker pull拉取镜像比较慢请优先排查部署机器的网络带宽和 DNS 配置不要直接在生产配置里堆叠不熟悉的镜像源参数。镜像下载慢通常只是第一次启动明显后续启动会使用本地缓存。3. 从 Docker Compose 启动 Dify 社区版3.1 下载项目代码与目录结构说明先拉取 Dify 社区版代码并进入 docker 目录git clone https://github.com/langgenius/dify.git cd dify git tag git checkout 稳定tag cd docker ls -la使用git tag列出版本标签然后选择一个稳定版本切换过去。直接使用 main 分支虽然能尝新但可能包含未充分验证的变更出现问题时不好定位。在 docker 目录下重点文件是docker-compose.yaml和.env.example。前者定义了整套服务后者是环境变量模板。Dify 启动后由多个容器组成常见的有 api、worker、web、db、redis、sandbox、ssrf_proxy 等。api 是后端主服务worker 处理异步任务web 是前端控制台db 和 redis 是它的基础设施sandbox 用于隔离模型或代码节点的执行环境。3.2 修改环境变量与应用配置第一次进入 docker 目录时需要把.env.example复制成自己的.env文件cp .env.example .env然后编辑.env至少修改以下内容SECRET_KEYplease_change_to_random_value DB_PASSWORDplease_change_db_password REDIS_PASSWORDplease_change_redis_passwordSECRET_KEY 用于服务端会话和加密相关逻辑正式环境必须改成足够长的随机字符串不能沿用模板里的默认值。数据库和 Redis 的密码是 Dify 内部组件之间通信的凭据也要避开弱密码。如果对.env里的其他变量不了解不要随手改动。Docker Compose 默认会把 web 服务映射到宿主机 80 端口如果 80 端口已被占用需要在docker-compose.yaml中调整 web 服务的 ports 映射例如改为8080:80。3.3 启动服务并确认容器状态在 docker 目录下执行docker compose up -d docker compose psup -d会在后台拉取镜像并启动所有服务。第一次启动时间较长因为要拉取多个镜像。执行完docker compose ps后需要看到各服务处于 running 状态数据库容器进入 healthy 状态才代表初始化完成。docker compose logs -f api如果 api 容器反复重启用上面这条命令看启动日志。最常见原因是数据库还没有完成初始化api 在启动时连接数据库失败。等 db 容器 healthy 之后再次观察 api 状态通常会自动恢复。不要一开始就删除容器或重装先看日志再决定操作。注意不要只看容器名存在要关注 STATUS 是否 healthy。web 页面能打开不代表数据库和 worker 已经正常后续创建智能体一旦涉及知识库和异步任务就可能出现索引失败或任务卡住。3.4 初始化管理员账号并登录系统服务启动成功后浏览器访问http://localhost如果部署在服务器上就访问http://服务器IP。首次打开会进入管理员初始化页面填写邮箱、用户名和管理员密码。完成初始化之后登录地址就是你自己的服务地址并不存在一个统一的“Dify 平台登录入口官网”。不同版本的登录路径可能略有差异通常会在前端跳转到/signin或/apps之类的地址以实际界面为准。学习环境到这里就算部署完成了。如果是团队测试或生产环境还需要配置域名反向代理、HTTPS 证书、数据库外置和日志持久化这些内容统一放到第 7 章。4. 配置大模型把模型能力接进 Dify4.1 模型供应商接入方式Dify 的模型配置入口在“设置 - 模型供应商”。它的设计目标是把各类模型厂商和自建推理服务统一成一套接口上层应用不关心模型来自哪里只关心“哪个模型可用”。接入方式主要有两种云端 API在模型厂商控制台创建 API Key填到 Dify 中即可。自定义推理服务自建 Ollama、DeepSeek 本地部署或其他 OpenAI 兼容服务填 Base URL 和模型名。学习环境优先用云端 API省去本地模型对显存和内存的要求。如果业务要求数据不出内网再考虑本地推理方案此时要额外负责模型服务的稳定性、容量和升级。4.2 云端 API 模型配置示例在“设置 - 模型供应商”中选择目标厂商并填入 API Key 的步骤基本一致打开模型供应商页面。选择厂商例如 DeepSeek、Minimax 或 OpenAI 兼容服务。粘贴 API Key。选择要使用的模型核对模型名。点击“点击测试”等待返回一段正常文本。配置项说明API Key唯一的调用凭证必须保密模型名必须与厂商实际提供的模型一致Base URLOpenAI 兼容服务需要填写接口地址云端厂商通常预填测试按钮通过模型调用确认配置是否可用测试是必须做的一步。能通过测试说明 Dify 后端到模型厂商的网络、密钥和模型名都是正确的后续创建应用时才能直接选用这个模型。4.3 本地模型接入示例Ollama / DeepSeek 本地部署场景本地模型接入的原理和云端 API 相同只是把请求从公网地址换成了内网推理服务地址常见场景是 Ollama。安装好 Ollama 后在宿主机拉取一个测试模型例如ollama pull qwen2.5:7b然后在 Dify 的模型供应商页面选择自定义模型或兼容 OpenAI 的模型类型填写Base URL: http://host.docker.internal:11434 Model Name: qwen2.5:7b API Key: 任意非空值这里最容易踩的坑是网络地址。Dify 的后端运行在容器里容器内访问localhost指向的是容器自己不是宿主机。因此要访问宿主机上的 Ollama需要Windows 和 macOS 的 Docker Desktop 可以直接使用host.docker.internal。Linux 上的 Docker 20.10 之后通常也支持host.docker.internal。如果解析失败可以改用宿主机局域网 IP例如http://192.168.1.20:11434。DeepSeek 本地部署或其他 OpenAI 兼容推理服务也是同样的思路。只要服务暴露了一个 Base URL且 Dify 后端容器能访问到这个地址就可以通过自定义模型接入。如果接口要求拼接/v1路径则 Base URL 需要写成类似http://host.docker.internal:11434/v1。不同版本对路径的拼接方式有差异以界面提示和模型服务文档为准。4.4 配置完成后的验证与报错配置完成后优先使用界面上的测试按钮。如果本地模型没有现成测试按钮也可以在宿主机用 curl 先确认模型服务本身可用curl http://host.docker.internal:11434/api/tags返回模型列表说明服务正常。之后回到 Dify 再做一次测试。报错现象常见原因处理方式401 UnauthorizedAPI Key 无效或未填写核对厂商控制台里的 Key429 Too Many Requests配额不足或触发限流等待一段时间或提升配额404 Not FoundBase URL 路径不对确认接口是否要求拼接/v1connection refused模型服务未启动或容器网络不通在宿主机 curl 测试检查端口和服务状态model not found模型名与推理服务不一致用服务端接口查询实际模型名5. 创建第一个智能体并用工作流把任务串起来5.1 创建应用从聊天助手到 Agent模型配置好之后进入工作区创建应用。Dify 支持聊天助手、Agent、工作流和文本生成等类型。如果目标是搭建一个能回答私有知识库问题的智能体常见选择是聊天助手或工作流。创建聊天助手时需要完成三件事选择一个已配置好的模型。填写人设和提示词例如“你是一个内部客服助手回答要简洁同时要给出依据”。按需开启 Agent 能力允许模型在需要时调用 Dify 内置工具或自定义工具。聊天助手和 Agent 的区别需要说清楚。聊天助手偏向直接问答Agent 则在模型层增加“决定是否调用工具”的循环。如果任务只是固定问答不需要开 Agent只有需要查外部数据、操作外部系统时才用 Agent。工具能力越强模型跑偏的可能性越大因此在链路不稳时不要急着开。5.2 搭建一个带知识库的 RAG 工作流工作流适合把多步骤任务固化下来。一个最小可用的 RAG 工作流包含四个节点开始 - 知识检索 - LLM - 直接回复节点作用关键配置开始接收用户输入定义问题变量知识检索从知识库中召回相关片段选择知识库、设置 TopK 和 Score 阈值LLM基于检索片段生成回答系统提示词中引用检索结果直接回复把结果输出给用户引用 LLM 节点的输出如果还没有创建知识库需要先回到第 6 章建一个知识库否则知识检索节点没有数据来源。工作流的价值在于模型不是直接凭记忆回答而是先检索私有文档再基于检索结果生成答案。这样在客服问答、内部资料查询等场景下回答约束在企业自己的知识范围内。5.3 设置变量、节点与结束条件工作流是 DAG每个节点通过变量引用上游输出。开始节点添加一个文本变量用来接收用户输入例如sys.query。知识检索节点选择目标知识库设置 TopK 为 3、Score 阈值按需调整输出字段记为类似knowledgeRetrieval.result。LLM 节点的系统提示词写成这样你是一名内部客服助手。请根据下面的知识库片段回答用户问题。 如果片段中没有可靠信息请直接说明不知道不要编造。 【检索片段】 {{#knowledgeRetrieval.result#}} 【用户问题】 {{#sys.query#}}结束节点输出{{#llm.text#}}。这里不同版本的变量命名规则可能不同实际使用时以工作流画布上节点输出字段为准。关键判断点是LLM 节点的提示词里一定要引用知识检索结果否则模型看不到知识库内容整个 RAG 链路就名存实亡。注意工作流节点通过变量引用上下游数据。出现答非所问时第一件事不是改 Prompt而是看知识检索节点到底有没有返回内容。5.4 在 WebApp 中测试并观察链路日志配置完成后点击工作流右上角的运行或发布进入调试页面输入测试问题。例如针对知识库内容问“这个平台的部署要求是什么”然后观察运行轨迹。Dify 会记录每个节点的输入和输出。排查时按这个顺序看开始节点是否收到了用户问题。知识检索节点是否返回了片段片段内容与问题是否相关。LLM 节点是否成功引用了检索片段。结束节点是否正常输出。只要中间某一步的输入输出为空或明显异常问题就定位到那一个节点不需要猜测。发布后用户可以在 WebApp 页面和 API 两种方式访问应用这部分能力在发布配置中打开。6. 知识库流水线与多租户场景的工程注意点6.1 知识库的导入、分段与召回参数知识库是 RAG 应用的底座。创建知识库后进行文档上传Dify 支持常见的文本、Markdown、PDF、Word 等格式。上传后需要选择分段规则和嵌入模型索引完成后才能被工作流检索。分段规则直接影响召回质量。常用参数包括参数作用调小的影响调大的影响分段长度一个检索单元的最大长度检索更精准但上下文可能碎片化上下文更完整但可能引入无关内容重叠长度分段之间的重复字符数信息可能被截断重复内容变多占用 tokenTopK召回片段数量返回更少可能漏掉答案返回更多噪音也可能增加Score 阈值过滤低相关片段召回结果更多但可能不相关更精准但可能召回为空嵌入模型的选择也很重要。没有嵌入模型就无法完成文档向量化知识库索引会失败。不同嵌入模型对中文等语义的区分能力有差异实际效果需要通过召回测试来判断而不是凭模型名猜测。6.2 知识库流水线的调试方法问答效果不符合预期时按下面顺序排查确认文档已经完成索引。如果文档状态仍是“处理中”先等待异步任务完成。确认嵌入模型配置正确索引过程没有报错。打开知识库的“召回测试”功能输入一个问题观察返回哪些片段。如果召回不到相关内容调低 Score 阈值、增大 TopK或者缩小分段长度。如果召回结果正确但回答错误检查 LLM 节点提示词是否引用了召回结果是否被 Prompt 里的其他规则覆盖。如果模型引用了不相关内容可以在提示词中要求模型严格基于片段回答无法判断时明确回答不知道。大部分“答非所问”不是模型不够聪明而是召回结果和提示词没有对齐。先用召回测试把知识链路调通再谈优化 Prompt。6.3 多租户场景需要关注的问题Dify 社区版在较新的版本中已经支持多租户能力但不同版本的能力边界差别较大部署前要先查看官方发布说明确认当前版本是否支持以及如何启用。多租户带来的核心变化是应用、知识库、成员和 API Key 需要按租户隔离。一个租户的知识库不能让另一个租户检索一个租户的应用也不能消耗另一个租户的模型配额。这些在平台层需要统一管理。工程层面还要关注三点租户变多后数据库和文件存储的数据量会快速增加备份和清理策略要提前设计。模型调用量需要按租户统计不能只依赖模型厂商的限额否则一个租户的突发流量可能拖垮整体服务。密钥管理要做到每个租户独立不能共用一个平台级 API Key否则无法审计费用来源。7. 常见问题排查、升级注意与上线清单7.1 几个高频故障现象与排查路径下面整理的是 Dify 部署和日常使用中比较高发的问题问题现象常见原因检查方式处理建议页面一直加载或返回 502部分容器没有正常启动docker compose ps等 db healthy查看 api 日志api 容器反复重启数据库未就绪或连接失败docker compose logs -f api等待 db 健康后重启 api机器重启后服务不恢复容器缺少自动重启策略docker compose ps查看状态在 compose 中配置 restart 策略模型测试报 401API Key 无效厂商控制台确认重新生成 Key本地模型连接不上容器无法访问宿主机服务宿主机 curl 测试接口使用 host.docker.internal 或局域网 IP知识库索引失败嵌入模型未配置或配额不足查看知识库索引日志更换嵌入模型或检查 KeyWindows 下访问不了Docker Desktop 未启动或端口冲突查看 Docker Desktop 状态、检查 80 端口启动 Docker Desktop 并释放冲突端口此外经常有人改了.env后不重启容器导致配置不生效。修改.env之后需要重新执行docker compose up -d让它重新读取环境变量并重建受影响容器。7.2 升级 Dify 时要注意什么Dify 版本迭代非常快升级不能只靠“拉最新代码”这个动作。推荐的升级顺序是先备份。Docker Compose 部署时数据库是其中最核心的数据。可以使用 pg_dump 导出例如docker compose exec db pg_dump -U postgres 数据库名 dify_backup_$(date %F).sql数据库名和用户名以.env中的实际配置为准。备份上传文件对应的存储目录。如果使用本地卷挂载需要连同挂载目录一起备份。拉取新版本代码切换到目标 taggit fetch origin git checkout 新版本tag查看目标版本的发布说明确认数据库迁移、docker-compose 文件变更等要求。重新执行docker compose up -d观察迁移是否正常执行。如果升级失败按第一步的备份恢复到原版本不要直接在 main 分支上修改代码来救数据。Windows 下使用 Docker Desktop 部署时没有单独的“在线升级按钮”。升级路径仍然是 Git 版本切换加 Docker Compose 重建。升级前确保 Docker 卷没有被误删否则数据会随容器清理而丢失。注意升级前没有备份数据出问题后几乎无法回滚。宁可多等几分钟备份也不要直接在生产环境执行强制重建。7.3 上生产前的检查清单部署 Dify 到生产环境前建议逐项确认下面的清单修改默认 SECRET_KEY、数据库密码和 Redis 密码。数据库和 Redis 使用独立实例数据目录落在持久化存储中。配置定时备份备份内容包括数据库、上传文件和知识库索引数据。使用反向代理启用 HTTPS关闭不必要的端口暴露。设置容器内存和 CPU 上限避免单个组件耗尽资源。配置健康检查、日志采集和告警策略。模型 API Key 使用独立子 Key 或按预算设置限额。知识库文档的更新和维护流程要责任到人。保留上一版本的部署文件和镜像作为回滚预案。生产环境的目标不是“功能能用”而是“挂了能恢复、变更能回滚、费用可审计”。Dify 本身解决的是 AI 应用编排问题但围绕它的备份、监控、权限和成本控制仍然需要按软件工程的常规标准来处理。最后给一点实际建议。部署 Dify 并不难难的是把模型、知识库和工作流组合成一个稳定可交付的应用。建议先用单机 Docker Compose 和一个高频 demo 打通全链路再逐步补充生产要素密钥、备份、日志、监控、多租户配额。新手不要一上来就追求复杂节点先让“知识库 - 召回 - LLM - 回复”这条链路稳定再添加 Agent 工具和条件分支否则出了问题很难定位是模型问题、检索问题还是编排问题。