企业官网建设流程全解析

在 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 社区版的主要模块可以整理成下面这张表：

这些模块不是独立功能，而是一个最小闭环。一个典型的 RAG 问答应用，本质上是“模型供应商 + 知识库 + 工作流 + 应用日志”组合出来的结果。这也是为什么官方安装完成后，第一件事通常是配置模型供应商，而不是直接去创建工作流。

1.3 适用场景与部署形态选择

Dify 社区版支持多种部署方式，最常见的是基于 Docker Compose 的单机部署。它会按编排文件把 api、worker、web、数据库、Redis、模型服务沙箱等组件组合在一起，适合学习、演示和中小规模内部工具。生产环境如果用户量变大，就要拆分数据库、存储和推理服务，或者使用 Kubernetes 部署，这时需要重点考虑多副本、滚动升级、日志采集和密钥管理。

本文的主线是单机 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 Compose

Dify 社区版的官方推荐部署方式是 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 Key

Dify 部署需要先拉取代码仓库，因此本机要安装 Git。在命令行执行：

git --version

能输出版本号就说明 Git 可用。Dify 迭代很快，部署时建议切换到稳定的版本标签，而不是直接跟随 main 分支，这一步会在第 3 章演示。

模型 API Key 是部署后第一步配置内容。常见模型厂商包括 DeepSeek、Minimax、OpenAI 兼容服务等，按各自控制台的说明创建 Key 即可。这里特别注意：API Key 一旦泄露可能产生费用，不要在代码仓库和聊天工具里明文传播。如果打算走本地模型路线，也需要预先准备好 Ollama 或其他推理服务的安装环境，但本地模型不是部署 Dify 的必要条件。

2.4 部署前环境自检清单

开始安装前，建议按下面这张清单检查一遍：

如果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_KEY=please_change_to_random_value DB_PASSWORD=please_change_db_password REDIS_PASSWORD=please_change_redis_password

SECRET_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 ps

up -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. 配置大模型：把模型能力接进 Dify

4.1 模型供应商接入方式

Dify 的模型配置入口在“设置 -> 模型供应商”。它的设计目标是把各类模型厂商和自建推理服务统一成一套接口，上层应用不关心模型来自哪里，只关心“哪个模型可用”。

接入方式主要有两种：

1. 云端 API：在模型厂商控制台创建 API Key，填到 Dify 中即可。
2. 自定义推理服务：自建 Ollama、DeepSeek 本地部署或其他 OpenAI 兼容服务，填 Base URL 和模型名。

学习环境优先用云端 API，省去本地模型对显存和内存的要求。如果业务要求数据不出内网，再考虑本地推理方案，此时要额外负责模型服务的稳定性、容量和升级。

4.2 云端 API 模型配置示例

在“设置 -> 模型供应商”中，选择目标厂商并填入 API Key 的步骤基本一致：

1. 打开模型供应商页面。
2. 选择厂商，例如 DeepSeek、Minimax 或 OpenAI 兼容服务。
3. 粘贴 API Key。
4. 选择要使用的模型，核对模型名。
5. 点击“点击测试”，等待返回一段正常文本。

测试是必须做的一步。能通过测试，说明 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 再做一次测试。

5. 创建第一个智能体，并用工作流把任务串起来

5.1 创建应用：从聊天助手到 Agent

模型配置好之后，进入工作区创建应用。Dify 支持聊天助手、Agent、工作流和文本生成等类型。如果目标是搭建一个能回答私有知识库问题的智能体，常见选择是聊天助手或工作流。

创建聊天助手时，需要完成三件事：

1. 选择一个已配置好的模型。
2. 填写人设和提示词，例如“你是一个内部客服助手，回答要简洁，同时要给出依据”。
3. 按需开启 Agent 能力，允许模型在需要时调用 Dify 内置工具或自定义工具。

聊天助手和 Agent 的区别需要说清楚。聊天助手偏向直接问答，Agent 则在模型层增加“决定是否调用工具”的循环。如果任务只是固定问答，不需要开 Agent；只有需要查外部数据、操作外部系统时，才用 Agent。工具能力越强，模型跑偏的可能性越大，因此在链路不稳时不要急着开。

5.2 搭建一个带知识库的 RAG 工作流

工作流适合把多步骤任务固化下来。一个最小可用的 RAG 工作流包含四个节点：

开始 -> 知识检索 -> 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 会记录每个节点的输入和输出。排查时按这个顺序看：

1. 开始节点是否收到了用户问题。
2. 知识检索节点是否返回了片段，片段内容与问题是否相关。
3. LLM 节点是否成功引用了检索片段。
4. 结束节点是否正常输出。

只要中间某一步的输入输出为空或明显异常，问题就定位到那一个节点，不需要猜测。发布后，用户可以在 WebApp 页面和 API 两种方式访问应用，这部分能力在发布配置中打开。

6. 知识库流水线与多租户场景的工程注意点

6.1 知识库的导入、分段与召回参数

知识库是 RAG 应用的底座。创建知识库后进行文档上传，Dify 支持常见的文本、Markdown、PDF、Word 等格式。上传后需要选择分段规则和嵌入模型，索引完成后才能被工作流检索。

分段规则直接影响召回质量。常用参数包括：

嵌入模型的选择也很重要。没有嵌入模型就无法完成文档向量化，知识库索引会失败。不同嵌入模型对中文等语义的区分能力有差异，实际效果需要通过召回测试来判断，而不是凭模型名猜测。

6.2 知识库流水线的调试方法

问答效果不符合预期时，按下面顺序排查：

1. 确认文档已经完成索引。如果文档状态仍是“处理中”，先等待异步任务完成。
2. 确认嵌入模型配置正确，索引过程没有报错。
3. 打开知识库的“召回测试”功能，输入一个问题，观察返回哪些片段。
4. 如果召回不到相关内容，调低 Score 阈值、增大 TopK，或者缩小分段长度。
5. 如果召回结果正确但回答错误，检查 LLM 节点提示词是否引用了召回结果，是否被 Prompt 里的其他规则覆盖。
6. 如果模型引用了不相关内容，可以在提示词中要求模型严格基于片段回答，无法判断时明确回答不知道。

大部分“答非所问”不是模型不够聪明，而是召回结果和提示词没有对齐。先用召回测试把知识链路调通，再谈优化 Prompt。

6.3 多租户场景需要关注的问题

Dify 社区版在较新的版本中已经支持多租户能力，但不同版本的能力边界差别较大，部署前要先查看官方发布说明，确认当前版本是否支持以及如何启用。

多租户带来的核心变化是应用、知识库、成员和 API Key 需要按租户隔离。一个租户的知识库不能让另一个租户检索，一个租户的应用也不能消耗另一个租户的模型配额。这些在平台层需要统一管理。

工程层面还要关注三点：

1. 租户变多后，数据库和文件存储的数据量会快速增加，备份和清理策略要提前设计。
2. 模型调用量需要按租户统计，不能只依赖模型厂商的限额，否则一个租户的突发流量可能拖垮整体服务。
3. 密钥管理要做到每个租户独立，不能共用一个平台级 API Key，否则无法审计费用来源。

7. 常见问题排查、升级注意与上线清单

7.1 几个高频故障现象与排查路径

下面整理的是 Dify 部署和日常使用中比较高发的问题：

此外，经常有人改了.env后不重启容器，导致配置不生效。修改.env之后需要重新执行：

docker compose up -d

让它重新读取环境变量并重建受影响容器。

7.2 升级 Dify 时要注意什么

Dify 版本迭代非常快，升级不能只靠“拉最新代码”这个动作。推荐的升级顺序是：

1. 先备份。Docker Compose 部署时，数据库是其中最核心的数据。可以使用 pg_dump 导出，例如：

   docker compose exec db pg_dump -U postgres <数据库名> > dify_backup_$(date +%F).sql

   数据库名和用户名以.env中的实际配置为准。
2. 备份上传文件对应的存储目录。如果使用本地卷挂载，需要连同挂载目录一起备份。
3. 拉取新版本代码，切换到目标 tag：

   git fetch origin git checkout <新版本tag>

4. 查看目标版本的发布说明，确认数据库迁移、docker-compose 文件变更等要求。
5. 重新执行docker compose up -d，观察迁移是否正常执行。
6. 如果升级失败，按第一步的备份恢复到原版本，不要直接在 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 工具和条件分支，否则出了问题很难定位是模型问题、检索问题还是编排问题。