企业官网建设流程全解析

从零到一：本地部署 Dify 的完整记录

我折腾本地部署 Dify 已经有一阵子了。当时想法很简单：数据不想出服务器，又想把 DeepSeek、Qwen 这类开源模型用起来，还想自己控制知识库的处理流程。翻了一圈方案后发现 Dify 是最合适的载体，于是从拉代码、改配置、接 Ollama 一路走到知识库跑通。这篇就把整个过程中的思路、操作、踩过的坑一次说清，内容按“为什么这么弄—硬件怎么选—实际怎么部署—报错怎么修—资源不够怎么办”来讲，能帮你少走不少弯路。

读这篇之前，你最好对 Docker 有一点基础概念，不需要精通，能看懂docker compose up -d这类命令就行。如果你连 Docker 都没装过，问题也不大，我会把每一步写清楚。目标是让你在一台干净的 Linux 机器上，把 Dify 跑起来，并且接上一个本地或远程的大模型，做成一个能对话、有知识库、能跑简单工作流的私人 AI 平台。

1. 本地部署 Dify 之前，先想清楚这三个问题

1.1 Dify 到底解决什么问题

Dify 是一个开源的大语言模型应用开发平台，核心价值是帮你把“模型调用、知识库检索、工作流编排、Agent 工具调用”这些事封装成可视化界面。你不需要自己写大量的调用代码，就可以做出一个带聊天界面、能检索知识库、能调用外部工具的 AI 应用。

你可以把它理解为“给大模型套了一层工程骨架”。大模型本身只会做输入输出转换，但真实的业务场景需要提示词管理、上下文拼接、文档切分、向量检索、多轮对话记忆、外部 API 调用等一堆周边功能。Dify 把这些能力都做成了插件式的模块，让开发重心从“实现功能”变成“配置任务”。

我做本地部署的核心原因很简单：知识库里的内容不方便传到公共平台，同时希望模型跑在自己的显卡或服务器上，调用链路上少一层不确定性。Dify 社区版把后端所有组件都开源了，数据存在自己的 PostgreSQL 和向量库里，理论上数据圈完全闭合。

1.2 为什么选本地部署，而不是直接用云版本

如果你只是想快速验证一下产品概念，直接用云版更快，注册账号、拿个 API Key、选好模型就能开始。但如果你遇到下面几个场景，本地部署就很有必要：

• 企业或团队内部文档涉及敏感数据，不能放到外部服务处理
• 需要长期跑一些自动化任务，按 API 调用量计费成本太高
• 想深度定制流程、改造源码、接入私有模型
• 服务器环境本身就在内网，外网访问受限，只能本地部署

还有一个容易忽略的点：本地部署之后，你的应用创建、知识库更新、模型调用都不依赖外部平台的规则变化。哪天云平台调整了模型配额或者下线某个功能，你不会被波及。当然，前提是你把底层模型也接在自己的服务上，或者至少是 API 收费方。

我也见过不少人是先做云端 PoC，验证完再迁回本地的。这样做的问题在于迁移成本：云端创建的应用、知识库、工作流导出后，本地也要对得上版本。我的建议是，如果你确定数据敏感，不如一开始就直接本地部署，Dify 社区版从 1.x 开始，迁移和备份机制已经比较成熟了，没必要中间折腾两遍。

1.3 和 LangChain、FastGPT、CrewAI 对比，怎么选

聊到本地部署，很多人会问：Dify 和 LangChain、CrewAI、FastGPT 比到底哪个好？我的结论是：工具属性不一样，完全看你的使用场景。

LangChain 是一个开发框架，给的是一堆代码组件，适合写代码、要精细控制复杂逻辑的开发者。它没有自带界面，更没有什么可视化知识库，所有的编排都用代码表达。如果你喜欢写 Python、需要深度定制，LangChain 是主线。

CrewAI 主打多智能体协作，核心是让多个“角色”分工协作完成任务，也偏代码和底层控制。

FastGPT 和 Dify 很像，都提供可视化编排、知识库、工具调用。FastGPT 的界面在某些国产模型和知识库场景下很顺手，但 Dify 胜在工作流能力更丰富、模型供应商接入范围更广、社区更活跃。

我在实际选择时的判断标准很简单：

Dify 的优势不是单点功能最极致，而是整体闭环最完整，从模型管理、提示词编排、知识库处理、工作流到对外 API，全都给齐了。这也是它在社区里热度高、相关搜索词多的核心原因。

2. 部署方案和硬件评估：先把底子打好

2.1 Docker Compose 方案是首选，但不是唯一

Dify 官方提供了 Docker Compose 部署、本地源码启动、Kubernetes 部署三种方式。本地部署我只推荐前面两种，其中 Docker Compose 是绝大多数人的最佳选择。

Docker Compose 方式的核心是用一套编排文件，把 Dify 依赖的所有中间件一次性拉起来。这些中间件包括：

• API 服务（后端接口）
• Worker（异步任务队列）
• Web（前端页面）
• PostgreSQL（业务数据与用户数据）
• Redis（缓存与消息队列）
• 向量数据库（默认 Weaviate，也可以切换 Qdrant 或 Milvus）
• Nginx（反向代理和静态文件服务）
• 可选：SSRF 防护模块、Sandbox、Plugin daemon 等

用 Compose 最大的好处是环境隔离，不会把依赖装满整个服务器，而且升级时只需要替换镜像版本再重新拉起。

如果你要做二次开发，那就需要源码方式启动 API 和 Web，同时自己准备 PostgreSQL、Redis、向量库。源码方式对调试友好，代码改动能即时生效，但环境配置复杂得多，不建议新手第一轮就选。我的习惯是先用 Docker 跑通，再做二次开发时一套 Docker 部署保持业务稳定，另起一套源码环境用来改代码。

2.2 硬件要求：官方最低配置只是参考

Dify 官方文档给的最低配置是 2 核 CPU、4GB 内存、10GB 磁盘，但我想实话实说：这个配置跑通 Demo 可以，跑稳定业务非常勉强。本地部署的目的如果是长期使用，配置至少要翻倍。

我实地测试的真实体感是：

如果你计划用 Ollama 拉取 7B 级别的模型进行推理，最好有一块 16GB 显存以上的卡。显存不够时模型会自动退到 CPU 推理，速度会慢到让人怀疑人生，尤其在做知识库 QA 时，体验很难接受。没有 GPU 也没关系，可以接 API 方式调用模型，硬件压力就主要集中在 Dify 自身的服务上。

关于磁盘我还有一句提醒：不要只算镜像和代码的空间。Dify 跑起来之后会产生日志文件、上传的文件、向量数据库的数据文件，这些都随时间膨胀。我自己吃过亏，磁盘只剩 5% 时数据库写入直接报错，排查了很久才发现是空间不够。

2.3 模型选择：先定模型，再定部署架构

很多人部署 Dify 时纠结“模型商配置到底该填什么”，其实顺序反了，你应该先决定模型从哪来。模型来源基本就三种：

第一，接 OpenAI 兼容 API。DeepSeek、Moonshot、通义等国内厂商的 API 大多兼容 OpenAI 接口格式，在 Dify 里可以直接用 OpenAI 或相应厂商的模板配置。这种方式部署简单，适合没有显卡、不想管推理资源的场景。

第二，用 Ollama 跑本地开源模型。先在服务器上装 Ollama，拉取模型权重，然后把 Dify 的模型供应商选成 Ollama，填写本机地址和模型名。这种方式数据完全不出服务器，适合隐私要求高或推理次数多、长期算下来更省钱的场景。

第三，既接云端 API 也接本地模型。Dify 支持同时配置多个模型供应商，系统设置里可以按应用切换。你可以在日常聊天用便宜快速的 API，处理敏感文档走本地模型，形成混合策略。

我一开始的架构是纯 API，跑通后换成了 Ollama 加 API 双通道。这样做的好处是：当 Ollama 拉取新模型或重启时，线上应用不至于完全不可用，还能有一个降级通道。

3. 实操部署：从空白服务器到跑通第一个应用

3.1 拉代码、改环境变量、启动容器

第一件事是安装 Docker。对于 Ubuntu 和 Debian 系统，最稳妥的方式是配好官方镜像源后安装docker-ce和docker-compose-plugin。这里有一个细节：不要只安装 Docker 而忘了 Compose 插件，否则后面执行docker compose命令会提示找不到。

装好后验证一下：

docker --version docker compose version

然后进入部署目录。官方仓库把代码放在langgenius/dify，我们只需要拿到docker目录里的编排文件。我的做法是完整克隆仓库，因为后续升级和改配置都要用到：

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

接下来是关键：打开.env文件，至少确认几个必填项。SECRET_KEY是应用密钥，原文件里有一个随机值，建议生成一个长字符串替换掉；POSTGRES_PASSWORD和REDIS_PASSWORD的初始值虽然能用，但部署在公网暴露风险很大，建议改掉；VECTOR_STORE默认是weaviate，对大多数场景够用。

改完环境变量后直接启动：

docker compose up -d

第一次启动会拉取很多镜像，时间取决于网络状况。启动完成后用下面的命令看所有容器状态：

docker compose ps

正常状态是每个服务都显示Up，且healthy状态在陆续出现。如果某个容器一直starting或直接退出，不要急着重复启动，先看日志，第 4 章会专门讲排障思路。

等待所有依赖服务都变成 healthy 之后，浏览器访问服务器的 80 端口，就能看到 Dify 的初始化页面了。

3.2 初始化后台：创建管理员账号与第一个应用

第一次打开页面会进入管理员初始化流程。设置完邮箱、用户名、密码后，系统会跳转到后台首页。这一步没有太多技术含量，但是有个很实际的问题：初始安装时邮件服务通常没配好，所以验证码或密码找回这类功能暂时不可用，不用慌，可以在后台系统设置里后续再补邮件参数。

进入后台后的第一件事，我建议先进入“模型供应商”页面，把所有要用的模型配置好，再创建应用。因为 Dify 里没有模型，应用创建后也没法完成对话。

创建应用的路径是“创建空白应用”，类型选“聊天助手”。创建完成后进入提示词编排界面，右侧模型选择器里就能看到你配置好的模型。输入一条测试消息，如果模型返回正常，说明部署链路基本通了。

这里注意一个细节：Dify 的应用有“草稿”与“已发布”状态。编辑后必须点击“发布”按钮，前端聊天窗口才会使用新配置。我改了几次提示词后才发现窗口里一直没生效，就是这个原因。

3.3 接入 Ollama 本地模型的关键配置

这是很多人最容易卡住的一步。如果你打算用 Ollama 拉本地模型，需要先把 Ollama 装到服务器上。装好之后，拉模型：

ollama pull deepseek-r1:7b ollama pull qwen2.5:7b

拉取模型后，为了让 Dify 容器能访问到 Ollama 服务，需要把 Ollama 默认监听的localhost改成可以被其他容器访问的地址。修改 systemd 服务配置或启动参数，让 Ollama 监听0.0.0.0:11434。具体命令可以参考 Ollama 官方 Linux 安装文档，核心就是把OLLAMA_HOST环境变量设成0.0.0.0。

然后回到 Dify 系统设置，在模型供应商里选“Ollama”。需要填几个参数：

• 模型名称：必须和ollama list里显示的名称完全一致，比如deepseek-r1:7b，注意带不带 tag 都很关键
• Base URL：填http://host.docker.internal:11434或http://<宿主机IP>:11434
• 模型类型：选“LLM”
• 上下文长度：按模型实际情况填，比如 7B 的模型常见是 4096 或 8192

填完点保存，系统会做一次凭证校验。这一步如果报错，最常见的原因就是容器访问不到宿主机。Dify 容器里默认没有配置host.docker.internal，最稳妥的做法是直接用服务器的内网 IP，并且确认防火墙允许 11434 端口被访问。

配置成功之后，你在提示词编排界面的模型列表里选择 Ollama 下对应的模型，就能用本地模型对话了。注意：当前 Conversation 的“系统提示词”内容和模型支持的最大上下文长度要匹配，7B 模型本身上下文有限，别把整个知识库内容都拼进去。

3.4 知识库流水线配置与文档分块

Dify 的核心亮点之一是知识库。所谓知识库流水线，简单说就是“文档上传 → 文本提取 → 分块 → 向量化 → 存入向量数据库 → 检索时召回”。

在后台选择“知识库”，创建一个新的知识库，然后上传文档。支持 pdf、txt、md、docx 等格式。上传后，Dify 会先解析文本内容，这部分由 API 服务里的文档处理逻辑完成，如果文档是扫描版 PDF，还会尝试 OCR，但效果取决于模型和部署环境，扫描件场景建议提前转成文本。

接着是设置分块策略。选“分块”之后会出现两个关键参数：

• 分块长度：我用默认的约 500 字符就可以，专业文档可以调到 800 到 1000
• 重叠长度：默认约 50 字符，目的是避免检索时切断语义片段

向量化时要选一个 Embedding 模型。如果你本地没有部署 Embedding 模型，可以先用 API 方式调用一个远程 Embedding 模型；如果要求全本地，可以用 Ollama 拉一个嵌入模型，比如bge-m3，然后在 Dify 里选 Ollama 类型、模型类型选“Text Embedding”。

知识库创建完成后，在聊天助手的提示词编排界面点击“添加功能”，选择“知识库检索”，关联刚创建的知识库。之后让应用再跑一次测试，它就会根据用户提问去向量库检索相关片段，再汇总给大模型生成回答。

这里需要补充一个提醒：本地部署时，如果 Embedding 模型和对话模型都跑在 Ollama 上，知识库入库和检索时的速度会明显变慢，特别是同时处理多个请求时。我建议入库操作选在业务低峰期执行，或者在硬件有限的情况下用 API 嵌入，避免队列越积越长。

4. 常见问题与排障实录

4.1 credentials validation 报错：模型商凭证校验失败

很多人在配置模型供应商时遇到 "An error occurred during credentials validation"。这个报错表面上是“凭证验证出错”，实际原因却五花八门，我梳理一下最常见的三种。

第一种是网络不通，尤其配置 Ollama 时，Dify 容器访问不到宿主机。检查思路是先进入 Dify 的 API 容器里，用curl访问填写的 Base URL，看能不能通。如果容器内没装 curl，可以临时用wget或者直接用docker exec进入容器再装工具。

第二种是参数填错。模型名称多了一个空格、Base URL 末尾多加了斜杠、模型类型选成了 Chat 而不是 LLM，这些都很常见。注意 Ollama 填模型名时，必须在“模型名称”字段里写完整名称，而在“模型类型”里选 Chat 时，Dify 会自动拼出模型端点的路径，大小写敏感。

第三种是凭证格式不对。API 类模型商的加密 Key 必须完整填写，有时候复制时把前后空格也带进去了，肉眼看不出来。我的排查顺序是：先清空空格，再检查 URL 是否可访问，再看日志，最后换内置测试模型来确认是否是模型商本身的问题。

4.2 SSL 错误：证书问题排查

启动成功后，如果页面报 SSL 相关错误，通常是反向代理层面的问题。Dify 自带的 Nginx 默认监听 80 端口，如果你在服务器前面套了一个 HTTPS 网关，那么根源往往在网关配置，而不是 Dify 本身。

最典型的状况是：你配置了 Nginx 反代把域名 443 端口转发到 Dify 的 80 端口，但忘了把 WebSocket 的 Upgrade 头转发过去。Dify 的对话功能依赖 WebSocket，缺了 Upgrade 头时前端会时不时断连，或者发消息没响应。

排查时重点看 Nginx 配置中是否有：

proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;

如果你没有套反代、直接 HTTP 访问，却报证书错误，那要检查浏览器是否缓存了旧证书，换无痕窗口测一次。另有少部分情况是容器网络重启后自签证书被覆盖，这时直接重新拉取或重建对应容器即可。

4.3 知识库一直排队中：Worker 没跑起来

知识库上传文档后长时间停在“排队中”或“处理中”，十有八九是 Worker 容器没干活。Dify 里文档解析、文本清洗、向量化这些异步任务都交给 Worker 处理，当 Worker 挂掉或无法连接 Redis 时，任务就一直队列堆积，界面却不报错。

排查手段很直接：看 Worker 容器日志。

docker compose logs worker

每个问题不同，最常见的两种：一是数据库连接配置变了导致 Worker 初始化失败；二是容器启动顺序不对，Redis 先挂了，Worker 重试了几次没成功就退出。第一种需要修正.env后重启，第二种直接docker compose restart worker，观察日志确认它重新订阅队列。

另一个容易被忽略的情况是：上传文档后 Dify 前端提示上传成功，但没有任何任务被创建。此时要看 API 容器日志，是否插入任务失败，常见原因是 PostgreSQL 里表结构不对或磁盘空间写满。磁盘写满这个问题我前面提过，空间不足时数据库会静默拒绝写入，排查这类问题一定要先看磁盘。

4.4 工作流上下文超长怎么办

Dify 工作流在编排复杂任务时，经常出现提示词或上下文拼接后超过模型上下文限制。很多人把这个锅甩给模型，但实际上是你把检索结果和中间变量一股脑塞给了最终节点。

我的建议是涉及超长时，先梳理节点输出：检查“知识检索”节点的召回数量，Dify 默认可能召回好几条分段，每条分段几百字，叠加起来就很可观。把召回条数从默认值调成 3 到 5 条，并开启“启用重排序”或靠打分筛选，能有效控制最终上下文长度。

还有一个技巧：在使用 LLM 节点时，可以参考变量选择器，只把需要的关键字段传给模型，而不是直接把整个工作流节点对象传进去。比如只需传入 question 变量，就应该选择question而不是sys.query。这样既减小上下文，也避免给模型塞大量不相关信息。

真正要装大型上下文时，本地 7B 模型基本撑不住高频长文，建议改接云端上下文窗口更大的模型，或者换 70B 级别模型加多点显存，这不是优化能解决的硬约束。

4.5 版本升级、数据迁移和二次开发

Dify 社区版更新很快，但你没必要每次都追新。我的习惯是等一个小版本稳定后再升，升级前一定备份。

Docker 部署方式的升级逻辑是拉取最新镜像、重建容器：

cd /opt/dify/docker docker compose pull docker compose up -d

不要直接删目录重建，否则所有数据都没了。正确做法是先备份数据库和向量库。PostgreSQL 备份用pg_dump，向量库备份更麻烦，但你可以通过 Dify 自带的 API 导出知识库配置。实践下来，最稳妥的备份其实是数据目录快照，比如用tar打包整个 docker volume 目录，遇到问题能整体回滚。

数据迁移也是热点问题。迁移场景一般是换服务器，思路是：停服后把docker/volumes目录整体拷到新机器，或者单独备份 PostgreSQL 和 Redis 数据文件。迁移后要保证.env里的密钥保持一致，否则密码和密钥不匹配会导致鉴权失败。关于迁移，我想强调千万别只迁移容器而忽略卷目录，容器本身没有持久数据，真正的内容全在 volumes 里。

二次开发方面，Dify 官方仓库分了很多模块，常见改造点是 API 逻辑、前端界面和插件机制。改动源码后需要构建镜像替换，工作量不小。如果你只改前端样式，可以直接修改 Web 容器里的静态文件，但升级时会被覆盖。要做长期二次开发，最好维护一个 fork 仓库，每次官方更新后合并变更，再构建自己的镜像。

5. 资源受限时的降级方案与实用技巧

5.1 内存不足时如何砍组件

如果你服务器内存只有 8GB 或 16GB，又想跑 Dify，也不是不能，但要舍得砍功能。

最有效的降级方式是换用更轻量的向量库。Weaviate 本身内存占用不高，但 Dify 默认还包含了 Sandbox、SSRF 防护等辅助服务。如果确认你的环境没有恶意文件执行风险，可以在.env里关闭部分组件，比如注释掉 sandbox 服务相关配置。这样能省出 1GB 到 2GB 内存。

另外，Web 前端容器对内存要求不高，但 API 容器和 Worker 容器是吃内存大户，尤其是文档入库时，Python 进程内存会飙升。可以把 Docker 的内存限制加上，避免瞬时峰值压垮整个宿主机。限制方式是在 Compose 文件中为容器设置mem_limit，但要注意内存限制太小会导致任务直接 OOM，得结合日志测试出合适的阈值。

5.2 管理 Ollama 的显存占用

在一张显卡上同时跑 Embedding 模型和对话模型是件很讲究的事。ollama serve默认按需加载模型，但如果两个模型切换频繁，每次卸载重载都会拖慢速度。你可以用ollama ps查看当前显存中加载的模型。

我常用的两个技巧：一是设置OLLAMA_MAX_LOADED_MODELS环境变量，控制同时加载的模型数量，比如设成 1，保证对话模型的显存优先；二是固定使用同一个 Embedding 模型，避免不同知识库切换不同的嵌入模型导致频繁换载。

还有一点很重要：Ollama 如果和 Dify 跑在同一台机器上，要预留出 Dify 中间件本身的内存和 CPU 余量。不要为了模型推理把整机资源吃满，否则文档解析和向量化任务会卡成“排队中”。

5.3 顺手补充的本地服务扩展

本地部署 Dify 后，周边可以扩展的东西就丰富起来了。热词里经常提到 Supir 本地部署、MinERU 本地部署、Whisper 本地服务，这些在 Dify 社区里也都能串起来用。

借助 Dify 的“工具”能力，你可以在工作流里调用外部 HTTP 服务。比如你在本地部署了 Whisper 语音识别服务，就可以在工作流里加一个 HTTP 请求节点，把音频传给它做转写，转写结果再交给大模型处理。又比如文档预处理用 MinERU 做高精度版面解析，分析结果再灌进知识库，会比 Dify 自带解析强一些。这些扩展的本质，是 Dify 帮你做好了编排衔接，外部服务只要暴露 HTTP API，就能被工作流调用。

我建议初学者不要急着在第一天就把所有服务都接进来，先跑通“Dify + Ollama + 一个知识库”的最小闭环，稳定运行一周后，再按需加语音、加解析、加浏览器自动化工具。

最后一点体会

本地部署 Dify 不算难，难的是部署之后怎么让它稳定地服务业务。我个人折腾下来的体会是：先不看教程数量的多少，先把模型、硬件、数据存储三个决策想清楚，再动手会让整体过程顺畅很多。配置容易出现问题的点往往不是 Dify 本身，而是外部依赖的连通性和资源规划。

关于网络连通性，还有最后一个非常实用的小技巧：Dify 容器之间互相访问用服务名，但 Dify 容器访问宿主机、或者宿主机访问 Dify 容器，最省心的方式是记住用宿主机局域网 IP，而不是 localhost。把所有服务的监听地址都显式地写成 0.0.0.0，并对防火墙放行必要的端口，你在排障时会节省大量时间。本地部署这件事一旦跑顺，后续加模型、加知识库、加自动化工具都只是填配置的事情，收益会越来越明显。