企业官网建设流程全解析

如果你第一次接触 Dify，大概率是带着这样一个问题来的：我想做一个能回答自己文档问题的 AI 机器人，但总不能每次从零写一遍 RAG 代码吧。Dify 就是回答这个需求的开源 LLMOps 平台。这篇文章不打算复述官方文档，而是把本地部署、模型接入、知识库、工作流整条链路完整讲一遍，包括实际部署中踩过的坑和排查思路。不管你是打算在 CentOS7 上装、在 Windows 上跑，还是在飞牛 NAS 上做私有化，看完都能有一条清晰的执行路线。如果你已经在用扣子、FastGPT 或者 n8n，也可以借这篇文章做一次横向参考，搞清楚各自的能力边界。

1. Dify 的定位：一个开源 LLMOps 平台到底解决什么问题

1.1 从“文档问答机器人”这个经典需求说起

我先从一个最常见的需求切入：公司内网有一堆产品文档、FAQ、操作手册，想做一个机器人，员工问“这个功能在哪个模块”“报销流程怎么走”，它能直接给答案。

如果不用平台，自己从零写一套，需要做的事大概包括：加载文档、切分文本、调 embedding 接口向量化、把向量写入数据库、查询时做相似度检索、把召回结果拼进 prompt、再调大模型生成回答；如果还要支持多轮对话，就得自己管理会话记忆；如果要接企业微信、网页、App，还得再写一层接口。这个工作量放到一个小团队身上，少说一两周，还不算后续调优和修 bug 的时间。

Dify 的做法是把上面整条链路做成可视化配置：上传文档、设置分段规则、选一个 embedding 模型、保存知识库，然后在应用编排里拖一个“知识库检索”节点，连上大模型节点，一个文档问答机器人就成了。整个过程以小时计，而不是以周计。

1.2 Dify 在整个 AI 应用链路中的位置

如果打个比方，传统应用开发里数据库是所有应用的存储底座，那 Dify 这类平台做的就是大模型应用的应用底座，核心是四件事：

• 模型接入：把 OpenAI、Anthropic、Azure、Ollama、vLLM 等各种模型供应商统一配置，应用里按需切换。
• 应用编排：通过聊天助手、Agent、工作流（Chatflow / Workflow）把模型、知识库、工具节点组合成可对外服务的应用。
• 知识库管理：文档上传、解析、分段、向量化、召回测试，内置完整的 RAG pipeline。
• 发布与运维：每个应用发布后自动生成 API，自带日志、会话审计、标注、监控，方便持续迭代。

用大白话说，Dify 把“只会调 API”和“能上线一个完整的 AI 应用”之间的这段路缩短了。你仍然需要理解 prompt 怎么设计、知识库怎么分段、模型怎么选，但不需要再去写一堆胶水代码处理工程细节。

1.3 扣子、FastGPT、n8n 与 Dify 的选择边界

很多人第一次接触这个领域，会同时看到扣子、FastGPT、n8n 这几个名字，然后陷入选择困难。我给一个比较务实的区分方式。

我的建议是：如果你要私有化、要一个平台把模型和知识库都管起来，优先 Dify；如果你只是想把一个 FAQ 机器人快速跑起来，FastGPT 也够用；如果你已经有丰富的外部系统，需要的是把 AI 能力和 Zapier 这类自动化串起来，那 n8n 更合适；如果只是临时体验，扣子可以随便玩。

2. 装之前先想清楚：环境选型、硬件需求和版本取舍

2.1 三种部署方式：为什么官方推荐 Docker Compose

Dify 官方提供的主要部署方式有三种。

第一是 Docker Compose 部署，也是官方最推荐、社区里用得最多的方式。一条命令可以拉起后端 API、前端、数据库、向量库、文档解析、代理等一组容器，升级和迁移相对一致。

第二是源码运行或者二次开发部署。适合要改前端逻辑、改后端代码的团队。这种方式灵活，但需要自己维护 Node、Python 环境，构建成本高，日常升级麻烦。

第三是直接用云端的商业版本。不用自己维护服务器，但数据在云上，私有化场景一般不选。

所以结论很明确：个人使用、企业内部私有化、小团队自用，都优先选 Docker Compose。我在后面讲的所有安装细节也基于这条路。

2.2 硬件要求与基础环境

Dify 不是一个轻量工具，它默认的 compose 项目里包含了不少容器：nginx、api、worker、web、postgres、redis、向量数据库、sandbox、plugin_daemon、ssrf_proxy、unstructured 等。实际占用取决于组件版本和文档解析任务。

从实操经验看，最低 2 核 4G 内存可以跑起来，但知识库文档一多、并发一上来，API 容器和 worker 会明显吃力。想用得舒服，建议 4 核 8G 起步，磁盘预留 30GB 以上。镜像和依赖数据都不小，没有足够磁盘空间很容易在 pull 镜像或者向量库写入时出问题。

操作系统方面，Linux 是最顺的；Windows 通过 Docker Desktop 也能跑，但要处理好 WSL2 和路径问题；macOS 同样可以。Docker 版本建议新一些，至少支持 Docker Compose v2 命令，因为很多新版本文档里的示例都直接用docker compose。

如果你的服务器在国内，拉取 Docker Hub 镜像可能会特别慢，建议先给 Docker 配置国内云厂商提供的镜像加速器，再执行后面的安装步骤，不然很容易卡在 pull 镜像这一步。

2.3 不同宿主环境的差异化准备：CentOS7 / Windows / 飞牛 NAS

CentOS7属于比较容易出幺蛾子的环境。CentOS7 的内核版本和系统库都比较老，太新的 Docker 版本在上面可能有兼容问题。我建议装 Docker CE 20.10 或 23.0 这个区间的版本，同时确认docker compose插件存在；如果没有，就单独安装 docker-compose 的二进制文件。另外 CentOS7 的软件仓库源有些已经迁移，安装 Docker 时如果碰到源 404，可以手动改用可用的镜像地址。

Windows环境的重点在 Docker Desktop。后端推荐用 WSL2，跑起来更稳。项目目录千万别放在中文路径或者带空格的目录下，Docker Desktop 对这类路径的兼容性不好，容易莫名其妙挂载失败。Windows 上 80 端口很容易被 IIS、SQL Server Report 服务或其他程序占用，所以如果你发现 nginx 容器一直起不来，第一反应应该是检查端口，而不是重新拉镜像。

飞牛 NAS本质上是 Linux 环境，用 SSH 进到后台操作和装在其他 Linux 上没有本质区别。一个关键点是项目文件要放在存储池对应的挂载目录里，不要放在系统分区，否则容器数据量一大，系统盘会被写满。飞牛的 Docker 管理界面支持 compose 项目管理，可以把项目目录拷进去后直接导入运行，也可以整段命令在 SSH 里执行。

2.4 版本选择：社区版 1.10、多租户与后续升级路径

Dify 有社区版（开源免费）和云端/企业版。社区版在 1.10 之后的版本里已经加强了多人使用支持，可以在部署里创建多个账号，用空间或者团队的方式隔离应用和知识库。但要注意，这种隔离更多是逻辑层面的，适合小团队共用一套部署；如果你需要的是完善的多租户能力，比如组织级隔离、细粒度权限、配额管理这些，那属于企业版的能力范围，社区版不涉及。

升级路径也是一个需要提前想清楚的问题。社区版的升级大体上是cd dify/docker && git pull && docker compose up -d这套流程，但每次升级前一定要看版本的变更说明，以及先备份数据库。Dify 升级过程中可能有数据库迁移动作，跳过版本直接大跨度升级，很容易出现数据表对不上。

3. 完整安装实录：Docker Compose 部署的每一步与启动避坑

3.1 拉取代码与初始化配置

安装第一步是把官方代码仓库拉下来，我们只需要里面的 docker 目录。

git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env

为什么不直接给一堆容器命令手动拉起？因为 Dify 的组件之间有明确的依赖关系，官方提供的 compose 文件已经把网络、卷、环境变量都编排好了。复制.env.example为.env这一步是必须的，后续很多配置都从这里读取。

镜像拉取可以提前手动执行一次：

docker compose pull

这一步会拉取所有需要的镜像。镜像体积不算小，特别是带 unstructured 文档解析服务的镜像。如果你在国内，没配置镜像加速的话，这步会很痛苦。

3.2 .env 和 docker-compose.yaml 的关键参数

.env文件里有一个SECRET_KEY字段，官方注释也提示了要自己生成一个随机值。如果你不设置，系统启动时可能会自动生成，但迁移或者升级时如果这个值变了，会导致签名和会话校验出问题。

openssl rand -base64 42

把生成结果填到.env的SECRET_KEY=后面。

另一个需要留意的是端口。compose 里 nginx 默认映射到宿主机 80 端口。80 端口在服务器上经常被其他东西占用，最常见的情况是你机器上已经有一个 Nginx 或者别的 Web 服务。这时需要修改docker-compose.yaml中 nginx 服务的 ports 映射，把80:80改成8080:80，保存后访问地址就变成http://服务器IP:8080。

.env里的POSTGRES_PASSWORD和POSTGRES_USER这类数据库信息也建议改掉默认值，虽然这只是内网访问，但毕竟是基础安全习惯。

3.3 启动、初始化与验证

配置完成后执行：

docker compose up -d

首次启动会创建并运行全部容器。启动完成后，用下面两条命令检查状态：

docker compose ps docker compose logs -f api

看到 api 和 worker 容器处于 Up 状态且日志没有报错，基本就成功了一半。前端容器和 API 容器刚启动时，因为要等待数据库初始化，页面打开可能会一直转圈，等几十秒再刷新很正常。

首次访问http://服务器IP/install会进入管理员初始化页面，设置管理员邮箱和密码。这一步完成后，就可以用管理员账号登录了。也有一些版本会根据环境变量预置默认管理员，但统一走/install页面初始化是最稳妥的。

3.4 启动阶段的高频报错与排查

我整理一下启动阶段最容易碰到的几类问题，每类都给你排查路径。

端口占用导致 nginx 起不来。特征是docker compose ps里 nginx 反复重启或者直接 Exited。先看端口ss -lntp | grep 80，再改 ports 映射重启。这个问题在 Windows 和 CentOS 上出现频率极高。

内存不足导致容器循环重启。4G 内存的机器跑全组件确实紧张，症状是数据库或者向量库容器 OOM 被杀，日志里能看到 killed 相关字样。解决办法是增加内存，或者适当精简不需要的组件，但精简会牺牲功能，不建议新手做。

数据库无法连接。一般是 postgres 容器还没就绪，而 api 容器已经在尝试连库。看日志会有 FATAL 或 connection refused。等 postgres 完全起来后，手动重启 api 容器docker compose restart api通常能解决。

登录时提示 too many incorrect password attempts。这个提示的意思是失败次数过多，账号或者 IP 被临时限制了登录。最常见场景是部署好之后忘了密码，或者有人在用错误密码反复试。如果是临时锁，等一段时间会自动解除；如果是彻底忘了管理员密码，最省事的方案是恢复部署前的数据库备份，或者用数据库操作把这个管理员用户清掉重新初始化。生产环境不建议随意删用户，动手前先备份数据。

4. 登录之后第一件事：模型供应商配置与四大常见报错

4.1 模型供应商配置的核心逻辑

装好 Dify 只是搭好了一个空壳，要让应用真正跑起来，首先要做的是配置模型供应商。

入口在“设置”里的“模型供应商”页面。Dify 支持几乎所有主流供应商，包括 OpenAI、Anthropic、Azure OpenAI、Gemini、Ollama、vLLM 等。配置的核心字段其实就几个：API Key、Base URL、模型名称。对于本地部署的模型服务，只要它兼容 OpenAI 的接口格式，填入 Base URL 和模型名就能接入。

这里首先要理解一个设计：模型供应商的凭据是全局配置，应用里并不直接填 API Key。你在应用里选择模型节点时，只是引用“已经配置好的某个供应商下面的某个模型”。这样做的好处是换模型不用逐个应用去改，权限控制也更集中。

4.2 credentials validation 错误的完整排查链路

配置模型供应商时最常见的报错，文案是：An error occurred during credentials validation。这个报错的意思是 Dify 在保存配置前，会先调用一次模型接口做连通性校验，校验不过就不让你保存。

我遇到过的原因大致有这么几类：

• API Key 错误或额度不足。这个最直接，检查云厂商控制台里 Key 的状态，确认没有欠费。
• Base URL 填错。这是最隐蔽的坑。很多 OpenAI 兼容接口的地址必须以/v1结尾，比如http://192.168.1.10:8000/v1。你如果只填到端口，Dify 拼接出来的请求路径就会不对，校验直接失败。
• 网络不通。服务器访问不到模型 API，比如模型服务部署在一台内网机器上，但 Dify 部署在另一台机器，中间有防火墙隔离。
• SSL 证书问题。如果模型 API 走 HTTPS 但证书是自签的，Dify 在发起校验请求时会因为证书不受信任而失败。

排查顺序建议是：先在外面用 curl 直接调一次模型接口，确认 Key、地址、网络都没问题，再到 Dify 里保存配置。我后来养成一个习惯，凡是自建的模型服务，先在浏览器或者命令行里能调通，再去做图形界面配置，能省掉很多来回试错的时间。

4.3 API Key 管理与多应用复用

模型供应商配置完成后，尽量避免把 Key 复制到各种地方。不同应用用到不同模型时，直接在应用编排里切换模型就行，不用重新配 Key。知识库的 embedding 模型通常也会全局配置一次，供所有数据集使用。

另外，Dify 也有环境变量可以在docker-compose.yaml层面限制某些模型供应商，但对于单个实例的私有化部署，图形界面管理已经完全够用。

4.4 HTTPS/SSL 访问问题是怎么来的

默认部署是纯 HTTP 访问。所谓“Dify SSL 错误”，一般分两种情况。

一种是你希望用 HTTPS 访问 Dify，比较稳妥的做法是在外层加反向代理，比如 Nginx 或者 Caddy，由反向代理终结 TLS 证书，再转发到 Dify 的 nginx 容器端口。注意要处理好 WebSocket 长连接的转发参数，以及请求超时时间，不然工作流跑太久或对话流式输出时前端会断。

另一种是模型接口本身是 HTTPS 自签名证书，导致 Dify 调用模型时报 SSL 相关错误。这种情况下要么把自签名证书加到 Dify 容器的信任链里，要么干脆改成内网 HTTP 调用，省去证书问题。

5. 配置完模型之后，Dify 真正能做什么

5.1 知识库流水线：从上传文档到召回测试

模型配好之后，第一个值得深入的功能是知识库。Dify 的知识库模块本质是一条完整的 RAG pipeline，每一步都有可视化设置。

文档上传之后，第一步是解析。pdf、docx 这类格式会交给文档解析服务处理，Dify 里默认集成的是 unstructured。第二步是分段，你可以按标题层级、段落、自定义分隔符来切分，也可以设置父子分块，先切大块再细化小块，目的是兼顾上下文和召回精度。第三步是清洗，去掉超链接、乱码、无意义字符。

分段完成后，Dify 会调用你配置好的 embedding 模型做向量化，写入向量数据库。之后你可以进入“召回测试”界面，输入一句测试问法，直观看到从知识库里召回了哪些片段，以及每个片段的相似度分数。

召回这里我建议混合检索。Dify 支持向量检索、全文检索、混合检索三种模式。向量检索擅长语义匹配，全文检索擅长精确匹配关键词，混合检索两者结合。如果追求更高精度，可以在召回后接一个 Rerank 模型，对候选片段重新排序。代价是多一次模型调用，但对回答质量有明显提升。

5.2 工作流编排：一个售后工单自动分流案例

知识库是基础能力，真正让 Dify 有别于一般 Chatbot 工具的，是工作流编排。在 Dify 里，应用分为聊天助手、文本生成、Agent、工作流、Chatflow 几类。工作流适合比较确定性的流程，Chatflow 则更适合对话场景。

我拿一个实际案例来说明：产品售后工单自动分流。

需求是这样的：用户发来一段文字描述问题，系统需要判断是“能通过知识库自助解决”还是“必须转人工”，并且把工单内容推送到公司群。

流程设计如下：

开始 -> LLM 意图分类（判断工单类型） -> 知识库检索（检索售后 FAQ） -> 条件分支（判断召回分数是否足够高） -> 是：LLM 生成回复 -> 结束 -> 否：HTTP 请求（推送到群机器人） -> 结束

这里有个很关键的工程细节：为什么第一步要用 LLM 做意图分类，而不是简单的关键词匹配？因为用户描述问题的方式千奇百怪，关键词规则很难覆盖，LLM 分类的泛化能力更好。而知识库检索结果则负责提供事实依据，条件分支用召回分数作为阈值来分流。

“转人工”节点用 HTTP 请求实现，目标地址可以填企业微信机器人或者钉钉群机器人的 Webhook。这样一个流程跑通后，售后团队每天能自动消化掉相当一部分重复问题，真正需要人工介入的才被推送出来。

整个流程在 Dify 里都是拖拽完成，改一个节点、调一个 prompt 都是即时生效，不需要重新部署。

5.3 Agent 应用与对外 API：Dify 作为 AI 应用底座

把范围再放大一点，Dify 也支持创建 Agent 类型的应用。Agent 的核心能力是让模型自主决定调用哪些工具，比如 HTTP 请求工具、代码执行工具、搜索工具，也可以把知识库当作工具挂在 Agent 上。这适合流程不那么固定、模型需要自主推理的场景。

任何一个应用发布之后，在“访问 API”页面都能生成属于该应用的 Service API Key。拿到这个 Key 之后，外部系统就可以调用标准的 chat-messages 接口或者工作流运行接口。这意味着你完全可以把 Dify 当成一个 AI 应用后端，自己写一个简单的前端页面，或者接入到已有的业务系统里。

这对团队的意义很大：业务系统只需要对接一个 API，而 AI 相关的模型切换、知识库更新、工作流调整都在 Dify 平台里完成，后端代码一行都不用动。

6. 跑通之后：升级迁移、二次开发与周边生态接入

6.1 升级与迁移：长期维护的关键动作

Dify 升级整体比较简单，但有几个细节必须注意。

升级步骤是进到dify/docker目录，先git pull拉最新代码，再看.env是否有新增的配置项，最后执行docker compose up -d。因为镜像 tag 可能已经变化，up 的时候会自动拉取新镜像并重建容器。

升级前一定要做两件事：第一，看官方发布说明，确认有没有破坏性的数据库变更；第二，备份数据库。备份数据库不要用docker compose down -v，这个命令会把数据卷一起清掉，数据直接没。

迁移到新机器是另一个常见需求，本质要迁移三样东西：.env文件、Postgres 数据库数据、其他持久化数据。一个可靠的做法是在旧机器上停掉服务后用pg_dump导出数据库，把导出文件和.env一起拷到新机器，新机器先全新安装 Dify，再用psql导入数据。这么做的原因是容器卷直接拷贝容易因为版本差异、路径差异出问题，SQL 导入反而更可控。

6.2 unstructured 文档解析报错的定位与解决

如果你在知识库里上传 doc、docx 格式文件时，遇到类似 unstructured api url is not configured for doc file processing 的报错，原因基本可以锁定在文档解析服务没有正常工作。

Dify 默认的 docker compose 里包含一个 unstructured 容器，专门负责把 Office 文档解析成文本。如果你用的是精简过的 compose 文件，或者部署时间比较早，这个容器可能没有被正确启动，Dify 就不知道去哪里调用文档解析服务。

解决方式分两步：确认 unstructured 容器在运行：docker compose ps | grep unstructured。如果没起来，看这个容器的日志，多半是镜像拉取失败或者内存不足；接着检查.env里UNSTRUCTURED_API_URL相关配置，确保它指向正确的容器地址。

上传 PDF 一般不受影响，但 docx 这类格式强依赖这个服务。如果实在不想启用 unstructured，可以把文档先转成纯文本再上传，算是绕开问题的一条路。

6.3 二次开发路线：源码改造到自定义镜像

如果你需要改 Dify 本身的行为，那就进入二次开发模式。Dify 的源码目录里，web是前端，基于 Next.js；api是后端，基于 Python Flask。大致流程是：fork 源码、改前端或后端、构建自定义镜像、替换 compose 文件里的 image 镜像、重新docker compose up -d。

这套流程有几个现实问题：构建镜像需要完整的 Node 和 Python 构建环境，耗时较长；每次上游更新，你需要把上游代码合入自己的分支，合并冲突的工作量不小；Dify 迭代速度很快，维护一个深度改写的分支压力很大。

所以我的建议是：能通过平台本身功能解决的，尽量不碰源码。比如你想要一个自定义节点，优先看看有没有现成的插件，Dify 已经有了插件化机制；如果确实要改源码，至少保证构建流程能在一个干净的 CI 环境里复现，不要只在某一个人的电脑上能构建。

6.4 周边生态：Cursor 的 MCP 接入与多租户扩展

Dify 的 API 是开放的，周边生态也越来越热闹。一个比较流行的玩法是让 Cursor 这类 AI 编辑器通过 MCP 协议连接 Dify 的知识库。思路不复杂：Dify 提供标准的 dial 对话 API，我们只需要写一个很薄的 MCP Server，把 Dify 的 chat-messages 接口包装成 MCP 工具，然后在 Cursor 的配置文件里声明这个 server。

一个最小实现大致长这样，在 mcp.json 里声明：

{ "mcpServers": { "dify-bridge": { "command": "python", "args": ["mcp_dify_server.py"] } } }

对应的一段 Python 示意代码：

import json import urllib.request from mcp.server.fastmcp import FastMCP mcp = FastMCP("dify-bridge") API_KEY = "app-xxxxx" # Dify 应用访问 API 里生成 API_URL = "http://your-dify-host/v1/chat-messages" @mcp.tool() def ask_dify(query: str) -> str: payload = json.dumps({ "inputs": {}, "query": query, "response_mode": "blocking", "user": "cursor" }).encode() req = urllib.request.Request(API_URL, data=payload, headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", }) with urllib.request.urlopen(req) as resp: return json.loads(resp.read())["answer"] if __name__ == "__main__": mcp.run()

这段代码只是一个示意，具体写法取决于你用的 MCP SDK 版本，但整体思路就是：包装 API、注册为工具、在 Cursor 里启用。这样你在写代码的时候，可以直接通过 Dify 的知识库获取项目相关的历史文档和规范。

多租户方面，社区版 1.10 之后已经能在同一个部署里支持多个用户、多个空间，小团队共用一套部署做应用和知识库隔离是够用的；如果业务上需要严格的组织隔离和配额控制，那还是找商业版要能力。

我个人在跑通这套部署之后最大的感受是：Dify 这类平台真正的价值不在于把代码变成拖拽，而在于把 AI 应用的生命周期管理收拢到一个可观察、可配置、可迭代的地方。从文档上传、切片参数调整，到模型切换、工作流节点修改，再到对外 API 的发布，全在同一个界面上闭环。对一个想要在私有环境里快速落地 AI 应用的团队来说，这可能是当前性价比最高的起点。