企业官网建设流程全解析

简介：面向希望快速搭建AI应用开发环境的开发者、运维人员及对大模型落地感兴趣的进阶学习者，Dify教程PDF以Dify为主线，系统讲解本地部署全流程。内容覆盖Docker命令行安装与DockerDesktop两种方式，包含镜像加速配置、docker-compose启动、Windows环境下的访问初始化等具体操作，并说明安装完成后的管理员设置与登录步骤；同时介绍借助Ollama在本地部署deepseek-r1:1.5b等大模型方法，详细演示如何通过修改.env文件、添加模型供应商与系统模型设置，让Dify成功关联Ollama，最终创建智能聊天机器人并搭建本地知识库，从环境准备到知识库落地的完整链路均有涉及。资源为单个PDF文档，约5.28MB，内容结构完整，含界面操作说明与配置参数提示，便于对照练习。已有791人学习下载，适合具备一定命令行基础、希望在自己电脑上完整跑通Dify加本地大模型链路的读者使用。

1. 从 Dify 教程 PDF 到真正跑起来：先给这套平台一个坐标

翻了半天 Dify 教程 PDF，不如先回答一个问题：Dify 到底替你省掉了什么。做 LLM 应用时，Prompt 拼接、模型 Key 管理、知识库分段与召回、Agent 工具调用，每一样都能写成一套独立代码；Dify 社区版把这套链路做成可视化平台，用工作流把节点串起来，用知识库流水线承接文档数据。这篇 Dify 教程不按界面截图走，而是从选型逻辑、容器拓扑讲到镜像拉取失败与检索调参。适合正在做内部知识库问答、想把工作流交给非开发人员维护的团队，也适合评估要不要在自己环境里搭一套 Dify 平台。

2. Dify 的架构定位：工作流、知识库与模型网关怎么粘在一起

2.1 先回答「Dify 到底是什么」：一个带界面的 LLM 应用编排系统

企业里做 AI 应用，最大的浪费是每个项目都把模型调用、Prompt 拼接、向量库、日志和权限重做一遍。Dify 社区版把这条链路固化成平台能力：模型网关统一管理多个供应商的 Key；工作流可视化编排推理逻辑；知识库流水线负责文档接入、分段、向量化和检索；Agent 节点能按需调用工具，搭一个多步决策的智能体应用也只需要拖拽几条边。第一次登录控制台时，你面对的是「创建应用」而不是「初始化项目」，这是它和 LangChain 这类开发框架最明显的差别。

先理清应用类型。Dify 里的应用分成聊天助手、Agent、文本生成、工作流四大类。聊天助手按编排好的节点顺序执行，适合客服问答、知识库问答这类结果稳定的场景；Agent 则多了「推理-行动」循环，每一轮可以决定调哪个工具、搜什么资料，适合需要多步决策的任务；文本生成是面向单次生成的简化形态；工作流是前面三者的底层底座，新建任意应用后都能切到编排页签看到一张节点图。

这里要纠正一个容易走偏的点：不是所有场景都要用 Agent。内部知识库问答、工单分类、报表生成这类流程固定的任务，用聊天助手或工作流就够了。Agent 的推理开销和不确定性都更高，上线前还要处理工具调用失败的重试，团队初期尽量少引入。等流程跑通、确实需要模型自主决策时，再逐步把 Agent 节点加进工作流。

2.2 容器拓扑：api、worker、web 与中间件各管一段

Dify 不是单体服务，docker compose 拉起的是一个分布式拓扑。api 容器负责接收 HTTP 请求、业务逻辑和鉴权；worker 通过 Celery 消费异步任务，知识库文档处理、Embedding 生成这些耗时操作都在 worker 里跑；web 是前端静态资源；nginx 做反向代理。数据层有三个角色：PostgreSQL 存业务数据，Redis 存缓存和任务队列，向量数据库（默认 Weaviate）存文档向量。

理解这个拓扑，排错才能有的放矢。上传 PDF 后知识库里迟迟没有内容，看 api 日志通常查不到问题，要去看 worker 日志，因为分段和向量化在队列里消费。反之，页面能打开但接口报 401，问题多半在模型 Key 或登录态，和容器没关系。先判断故障层，再动手翻日志。

# 查看编排里所有服务的运行状态，重点看 STATUS 是否 healthy docker compose ps

这条命令在部署和排错时都会反复用到。STATUS 列出现 restarting 时，用 docker compose logs <服务名> 跟进；出现 unhealthy 则优先检查依赖它的中间件是否就绪，比如 api 起不来常常是数据库还没初始化完。

2.3 选择 Dify 而不是自己拼的边界在哪里

用 Dify 之前先确认边界。它替你做掉的是通用链路，但要清楚两件事：一是复杂业务系统集成要靠 API 或自定义工具节点，别把所有业务逻辑塞进工作流图里；二是高频、低延迟、强一致性的交易场景，更适合把编排结果沉淀为独立服务，Dify 做原型验证和运营后台更合适。

给团队选型时可以按这几个维度过一遍：

这个表格给决策用。自研路线最亏的不是编码时间，而是为知识库分段、召回调优、Key 管理这些通用问题反复造轮子。LangFlow 更贴近「流程图式原型」，生产级能力不如 Dify 完整。所以实际部署中，Dify 通常被当作企业内部的 LLM 应用底座，上面接多个业务线，下面统一管模型和知识库。

3. Dify 本地部署实战：用 Docker Compose 跑通最小安装

3.1 最小可用的部署步骤与启动前检查

拿到社区版发布包或者代码仓库后，进 docker 编排目录，其余工作交给 Compose。生产环境建议固定到具体版本 tag，而不是用 latest，避免中间件升级带来行为变化。到这一步的代码很少，关键在配置理解。

# 进入 compose 编排目录（发布包或仓库已存在于本机） cd dify/docker # 从示例文件生成环境变量，后续端口和存储都靠它 cp .env.example .env # 拉起全部服务，首次会把 api、worker、web、db、redis、weaviate 都拉下来 docker compose up -d # 查看服务状态，等所有容器处于 running/healthy 后再初始化 docker compose ps

逻辑说明：cp .env.example .env 是部署里最关键的一步，端口映射、存储路径、中间件连接串都集中在这个文件。docker compose up -d 会按依赖关系启动全部容器；ps 用于确认状态，看到 unhealthy 就继续看日志。初始化完成后，浏览器访问 http://<服务器IP>:<端口>/install 设置管理员邮箱和密码。登录不进去时，先查宿主机防火墙和 nginx 容器端口映射，而不是怀疑 Dify 本身。

参数说明：.env 里最常改的是 EXPOSE_NGINX_PORT，默认 80；本机已有 Nginx 或 IIS 时改成 18080 这类空闲端口。POSTGRES 和 REDIS 连接串保持默认即可，容器间通过 Docker 网络互访，手动改成 127.0.0.1 反而会让 api 连不上库。SANDBOX 相关变量控制代码执行沙箱，不需要代码解释器时保持默认。

3.2 Docker Desktop 环境的两个注意点

在 Windows 或 macOS 上通过 Docker Desktop 跑 Dify 很常见，但最容易栽在资源上。这套拓扑有八九个容器，默认 2 核 4G 内存跑不动，api 和 worker 会频繁 OOM。建议先在 Docker Desktop 的 Resources 里把内存调到 8GB 以上，CPU 至少 4 核，WSL2 后端还要给磁盘留出 10GB 以上余量，镜像、日志、向量数据加起来并不小。

第二个注意点是端口冲突。Windows 上 80 端口常被 IIS 或其它进程占用，改法是修改 .env 中的 EXPOSE_NGINX_PORT，然后重新执行 docker compose up -d，nginx 会按新映射启动。不要在 Docker Desktop 界面里手动改容器端口，容器重建后改动会丢失。遇到端口改了还是被占用，用 netstat -ano | findstr :<端口> 看进程号再处理。

3.3 镜像拉取失败的常见原因与处理顺序

首次 docker compose up -d 卡在拉取阶段很常见，原因通常分四类：tag 不存在、网络波动或仓库限流、磁盘空间不足、compose 文件语法问题。处理顺序固定一下，不要上来就改配置。

# 先针对具体服务拉镜像，减少干扰因素 docker compose pull api # 确认拉取目标后，单独验证这条链路是否能走通 docker compose config > /dev/null && echo "compose ok"

第一条命令把 api 服务的镜像单独拉到本地，如果还是失败，看错误类型。manifest unknown 表示镜像 tag 对不上，去 release 页面核对 compose 文件里的镜像 tag 与版本；timeout 或 429 表示网络层问题，先重试几次，再考虑给 Docker 配置 registry mirror 或换仓库源；no space left on device 则是磁盘写满，清理旧镜像和构建缓存。compose config 用来校验编排文件语法，语法错误时 docker compose up 会在启动前就报错，和镜像无关，先排除这条路径。

社区版发布节奏较快，1.10 到 1.17 这一代版本之间，compose 文件结构有过调整。升级时如果 git pull 后直接 up -d 报 manifest unknown，多半是本地 .env 里的变量和新的 compose 文件不兼容。这时先备份 .env，再基于新的 .env.example 重新生成，再逐项迁移自定义项。

3.4 .env 里值得先确认的 5 个参数

提示：改动 .env 后，docker compose up -d 不会自动重建所有容器。稳妥做法是 docker compose down 后再 up -d，确保 api 和 worker 都用新配置启动。

4. Dify 知识库流水线与工作流案例：把 PDF 里的内容变成能问答的资产

4.1 从文档到可检索知识的四段式接入

一上来导入一堆 PDF，然后被「知识库检索效果差」反复折磨，是新手最常见的路径。Dify 的知识库是一条完整流水线：上传文档、分段、清洗、向量化入库。界面里的「创建知识库」只是入口，真正决定检索质量的是分段和 Embedding 配置。

分段设置上，Dify 支持自动分段和自定义分段。自动分段按语义边界切分，适合排版规整的 PDF；Markdown、HTML 这类本身有章节结构的文档，自定义分隔符更可控。最关键的参数是最大分段长度，它决定每个 chunk 的 token 上限。工程经验是 200-500 token：太小召回碎片多，答案容易被切断；太大容易把无关信息带进上下文，稀释注意力。向量化之前，清洗规则里可以去掉页眉页脚、处理无效换行，这些操作在界面的清洗环节完成，不需要写脚本。

4.2 知识库检索效果差的诊断清单

检索效果差，先别急着换 Embedding 模型。Dify 的检索参数集中在知识库的「检索设置」里，逐项排查才是高效路径。

逐项调优的验证方式很简单：在知识库的「召回测试」里输入问题，看返回的 hit 是不是你期望的段落。这一步能定位故障层——hit 不相关，问题在分段和检索模式，不在阈值；hit 相关但 LLM 答错，问题在提示词，回去改 Prompt 模板。混合检索对含人名、型号、缩写等专有术语的知识库尤其重要：向量检索按语义找，全文检索按字面找，两者结合能覆盖语义接近但字面完全不同的坑。

4.3 最小可运行的工作流案例：知识库问答

在 Dify 工作流里搭一个知识库问答，最少需要四个节点：开始、知识检索、LLM、直接回复。常见做法是新建「工作流」应用，把开始节点的用户问题作为知识检索的查询输入；知识检索节点选中目标知识库；LLM 节点在提示词里引用检索结果；直接回复节点把答案返回。

关键在变量引用。知识检索节点输出的上下文变量一般叫 context，LLM 节点提示词这样写：

请基于以下资料回答问题，不要使用资料外的知识： {{#context#}} 问题：{{#sys.query#}}

逻辑说明：{{#context#}} 是知识检索节点传给 LLM 的结构化上下文，一般按得分降序拼接 Top K 个命中的分段；sys.query 是开始节点接收到的用户原问题。这样设计的好处是把「检索」和「生成」解耦：上下文由知识库节点决定，模型只负责在前置资料里组织答案。业务上要加「无答案兜底」时，在知识检索后加条件分支，判断 context 是否为空，再走不同回复路径，这是 Dify 工作流案例里最常见的扩展形态。

4.4 外部结构化数据如何导入知识库

知识库不只能上传 PDF 和 Word，还支持通过 API 导入外部结构化数据。常见做法是调用知识库的文档创建接口，用 form-data 上传 CSV 或 JSON，指定分段策略，接口返回文档 ID 后先查文档状态，等 worker 异步完成向量化再用于检索。

# 用知识库ID和API Key创建文档，file 指向本地 CSV 文件 curl -X POST \ -H "Authorization: Bearer ${DIFY_API_KEY}" \ -F "data=${DATASET_ID}" \ -F "file=@/tmp/issues.csv" \ http://<你的Dify域名>/v1/datasets/{dataset_id}/document/create

逻辑说明：Authorization 请求头里的 Bearer Token 在控制台的「API 访问」菜单生成，权限按应用隔离；data 参数是知识库 ID，文件和知识库的对应关系在提交时确定。接口返回的是文档状态而不是向量结果，因为分段和向量化发生在 worker 队列里。轮询文档状态接口，状态变为 completed 后再做召回测试，能确认数据真正进了向量库。

参数说明：file 支持 CSV、Markdown、PDF 等格式，上传后默认沿用知识库的分段设置；生产环境建议用脚本把业务表导出为 CSV 再批量调用，导入频率高时注意控制并发，避免压垮 worker。具体接口路径以你部署版本的 API 文档为准，不同小版本对数据集接口有兼容性调整。

5. Dify 上线前的最后一课：多租户隔离、升级备份与一条验证命令

5.1 社区版多租户：先理解工作区边界

社区版从 1.10 开始强调多租户能力，但多租户不必理解成复杂的 SaaS 隔离体系。Dify 里天然的隔离单元是工作区：管理员后台创建多个工作区，每个工作区拥有独立的成员、知识库、应用和 API Key。业务线之间默认互不可见，这比自己在应用层拼权限来得省事。

多租户的配置入口在系统管理后台的成员与工作区管理里。常见做法是给每个业务线建一个独立工作区，把对应成员拉进去，知识库和应用各自维护；模型配置仍在统一设置里管理，Key 不随工作区下发。这样团队统一管账，各业务线不互相污染数据。

5.2 升级流程：备份、拉新、重建和回滚

Windows 上做 Dify 在线升级，思路和 Linux 一致：先停服务，再备份 volumes，最后拉新镜像重建。备份是唯一的后悔药，建议升级前手动做一次。

# 停服前先整体备份数据目录，确认 volumes 目录存在再打包 docker compose down tar czf /backup/dify-volumes-$(date +%Y%m%d).tar.gz ./volumes # 拉取新镜像并重建容器 docker compose pull docker compose up -d

逻辑说明：down 会停止并移除容器，但 volumes 目录里的数据不会丢；tar 把整个目录打包，回滚时解压还原再重启即可。pull 只更新镜像不碰数据，数据库结构变更会在容器启动时自动迁移。备份后第一件事是拉新镜像，镜像 index 拿到后再重建，能避免一边启动一边拉镜像导致的中断。

5.3 一条验证命令走完部署检查

部署完成后直接用对话功能验证不够快，建议先做三层链路检查：模型可访问、知识库可召回、api 无报错。

# 校验后端健康检查接口，返回 200 说明 api 与中间件链路正常 curl -s -o /dev/null -w "%{http_code}" http://localhost/health

再配合容器日志确认运行时状态：

docker compose logs --tail=50 api

日志里出现模型鉴权错误（401、403）时去控制台检查模型 Key 和模型名是否匹配；知识库检索结果为空时回知识库做召回测试，确认 worker 完成了向量化；容器反复重启时先看退出码，内存不足和 .env 变量不一致是最常见原因。升级后先新建一个聊天助手，输入任意问题验证模型通道，再打开知识库问答做端到端验证，全通了再对外开放。

本文还有配套的精品资源，点击获取