Dify 本地部署保姆级教程：Docker、模型配置、知识库问答全流程
适合 AI 工具站、企业知识库、内部问答机器人、私有化 AI 应用搭建参考
| 项目 | 说明 |
| 文章类型 | AI 工具教程 / 本地部署 / 知识库问答 |
| 适合人群 | 站长、运营、企业信息化人员、AI 应用开发者、想搭建私有知识库的团队 |
| 核心收益 | 掌握 Docker 部署 Dify、配置模型、创建知识库、发布问答应用的完整链路 |
| 难度等级 | 中等：需要基础 Linux / Docker 命令，但不需要从零写代码 |
一、什么是 Dify？为什么适合本地部署
Dify 是一款开源 LLM 应用开发平台，可以把大模型、提示词、知识库、工作流、Agent、插件和 API 发布能力集中到一个可视化控制台里。对普通站长和企业团队来说，Dify 最大的价值不是“再做一个聊天框”，而是把内部资料、业务流程和模型能力连接起来，快速做出可复用的 AI 应用。
本地部署 Dify 的意义在于：数据、账号、应用配置、知识库文件和调用链路都可以放在自己的服务器或内网环境中管理。对于客服知识库、制度问答、产品手册、售后文档、项目资料等场景，本地部署比纯云端工具更容易做权限隔离、数据留存和长期维护。
1.1 Dify 的核心能力
- 可视化应用搭建：支持聊天助手、文本生成、工作流、Agent 等应用形态。
- 知识库问答：上传文档后进行切分、向量化、检索增强生成，让回答基于自己的资料。
- 多模型接入：可以接 OpenAI、Azure OpenAI、Anthropic、通义、智谱、Moonshot、DeepSeek、Ollama 等模型服务，具体以当前插件和模型供应商支持为准。
- API 发布：应用调试通过后，可以复制 API 地址或嵌入到网站、业务系统、客服入口中。
- 工作流编排：用节点方式串联输入、检索、条件判断、工具调用、输出格式化等环节。
1.2 本地部署更适合哪些人
如果你只是偶尔体验 AI 聊天，直接使用云端 Dify 或现成 AI 工具即可；如果你要长期维护一个网站、企业知识库、客户问答机器人，或者希望把多个模型统一接入一个后台，本地部署会更适合。
| 使用目标 | 是否建议本地部署 | 原因 |
| 个人临时体验 | 不一定 | 云端更省事，不需要维护服务器 |
| 网站知识库问答 | 建议 | 可把产品教程、FAQ、售后资料沉淀成可复用问答应用 |
| 企业内部制度问答 | 建议 | 便于管理账号权限、数据文件、模型调用和访问域名 |
| 开发者做 AI 应用原型 | 建议 | 可快速验证 RAG、工作流、Agent 与 API 集成 |
| 高并发生产系统 | 谨慎规划 | 需要额外考虑扩容、监控、日志、安全和备份 |
二、部署前准备：服务器、Docker 与网络环境
Dify 官方 Docker Compose 部署要求服务器至少具备 2 核 CPU、4GB 内存；macOS、Linux 和 Windows WSL2 场景都可部署，但正式生产建议使用 Linux 服务器，并给 Docker 分配足够内存。
2.1 推荐配置
| 场景 | CPU | 内存 | 磁盘 | 建议 |
| 本地测试 | 2 核 | 4GB 起 | 20GB+ | 仅用于体验，知识库和并发不宜过大 |
| 个人/小团队 | 2-4 核 | 8GB+ | 50GB+ | 适合搭建内部问答、教程库、轻量应用 |
| 企业试运行 | 4 核+ | 16GB+ | 100GB+ | 建议配置域名、HTTPS、备份和监控 |
| 生产高并发 | 按压测结果扩容 | 32GB+ | 独立数据库/对象存储 | 建议拆分数据库、向量库、日志与应用服务 |
2.2 需要准备的软件
- Linux 服务器：Ubuntu 22.04 LTS / Debian / CentOS Stream 等均可，本文以 Ubuntu 类命令为例。
- Docker Engine：建议使用官方源安装，避免发行版旧包导致 Compose 兼容问题。
- Docker Compose v2：官方文档要求 Docker Compose 2.24.0 或更高版本。
- Git：用于拉取 Dify 源码。
- 域名与 HTTPS：生产环境建议配置域名、反向代理和 SSL 证书。
| # Ubuntu 示例：安装常用工具 sudo apt update sudo apt install -y git curl ca-certificates gnupg # 检查 Docker / Compose 版本 docker –version docker compose version |
| 避坑提醒：Windows 用户建议把 Dify 源码和数据放在 WSL2 的 Linux 文件系统中，不要放在 Windows 盘符目录下，否则文件绑定、权限和性能可能出现问题。 |
三、Dify Docker 本地部署完整流程
3.1 获取 Dify 源码
建议直接按官方文档拉取最新 release 对应分支，这样可以避免 main 分支变动导致的兼容问题。服务器没有 jq 时，也可以直接到 GitHub Releases 页面查看最新版本后手动指定分支或标签。
| # 方式一：拉取最新 release（需安装 curl 和 jq） git clone –branch “$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)” https://github.com/langgenius/dify.git # 方式二：普通克隆 # git clone https://github.com/langgenius/dify.git cd dify/docker |
3.2 复制环境变量文件
Dify Docker 部署的核心配置在 docker/.env。第一次启动前需要从 .env.example 复制一份 .env。后续升级时，也要对比新的 .env.example，确认是否新增或变更了关键环境变量。
| cd dify/docker cp .env.example .env # 可用 nano / vim 编辑 nano .env |
3.3 重点检查 .env 里的哪些配置
| 配置方向 | 常见变量 / 位置 | 什么时候需要改 |
| 密钥 | SECRET_KEY | 正式部署必须使用高强度随机值，不建议沿用示例值 |
| 访问地址 | CONSOLE_WEB_URL、CONSOLE_API_URL、APP_WEB_URL、APP_API_URL、SERVICE_API_URL | 使用域名、OAuth、邮件通知、发布应用时建议明确配置 |
| 触发器地址 | TRIGGER_URL | 需要外部系统调用 Webhook 或插件触发器时设置为公网域名/IP |
| 模型供应商 | 模型插件或模型供应商后台配置 | 用于接入 OpenAI、Azure、国产模型或本地模型 |
| 向量数据库 | VECTOR_STORE 及 envs/vectorstores/ 下配置 | 默认可用 Weaviate；生产可按需求切换 Milvus、OpenSearch、pgvector 等 |
| 文件存储 | STORAGE_TYPE 等 | 数据量较大或多实例部署时考虑 S3 / OSS / MinIO 等对象存储 |
3.4 启动 Dify 服务
在 docker 目录执行 docker compose up -d 后，Dify 会启动 web、api、worker、plugin_daemon、PostgreSQL、Redis、Weaviate、Nginx、Sandbox、SSRF Proxy 等服务。第一次启动需要下载镜像，时间取决于服务器网络。
| cd dify/docker docker compose up -d # 查看容器状态 docker compose ps # 查看日志 docker compose logs -f –tail=100 |
3.5 访问并初始化管理员账号
默认情况下，可在浏览器访问服务器地址或本机 localhost，进入 /install 页面创建管理员账号。初始化完成后，进入控制台即可开始配置模型和创建应用。
| # 本地测试常见入口 http://localhost/install # 服务器部署常见入口 http://服务器IP/install https://你的域名/install |
| 生产建议：正式上线前请务必配置 HTTPS、关闭不必要的公网端口，并使用强密码。不要把数据库、Redis、向量库端口直接暴露到公网。 |
四、模型配置：OpenAI、国产模型与 Ollama 怎么接
Dify 能否正常问答，关键不只在聊天模型，还在 Embedding 模型、Rerank 模型和知识库检索配置。很多新手只配置了一个聊天模型，结果可以聊天但知识库不可用，原因通常是没有配置可用的向量化模型。
4.1 配置云端大模型
- 进入 Dify 控制台的“模型供应商 / Model Provider”区域。
- 选择对应供应商，例如 OpenAI、Azure OpenAI、Anthropic、通义、智谱、Moonshot、DeepSeek 等。
- 填写 API Key、API Base URL、模型名称等信息。
- 至少配置一个聊天模型；做知识库问答时，建议同时配置 Embedding 模型。
- 保存后用测试按钮确认模型能正常响应。
4.2 配置 OpenAI 兼容接口
许多国产模型和第三方中转平台提供 OpenAI Compatible 接口。配置时通常要关注三项：API Key、Base URL、模型名称。Base URL 一定要按照服务商文档填写，不要把网页控制台地址误填为 API 地址。
| 配置项 | 示例 | 说明 |
| API Key | sk-xxxx | 由模型平台后台生成 |
| API Base URL | https://api.example.com/v1 | 必须是接口地址，不是官网登录页 |
| Chat Model | deepseek-chat / qwen-plus / kimi-k2 等 | 以实际服务商支持为准 |
| Embedding Model | text-embedding-3-small / bge / qwen embedding 等 | 知识库向量化使用 |
| Rerank Model | 可选 | 用于提升检索片段排序质量 |
4.3 配置本地模型 Ollama
Ollama 适合在本机或内网服务器运行开源模型。如果 Dify 在 Docker 中运行，连接宿主机 Ollama 时需要注意地址不能简单写 localhost，因为容器里的 localhost 指向容器本身。Docker Desktop 常见写法是 host.docker.internal；Linux 服务器可能需要使用宿主机内网 IP 或额外网络配置。
| # 安装并拉取模型（示例） ollama pull qwen2.5:7b ollama pull bge-m3 # 检查 Ollama 服务 ollama list curl http://localhost:11434/api/tags |
| 模型选择建议：知识库问答至少要区分“回答模型”和“向量模型”。回答模型负责生成答案，向量模型负责把文档和问题转换为可检索的向量，两者不是同一件事。 |
五、创建知识库问答：从上传文档到发布应用
5.1 创建知识库
- 进入“知识库 / Knowledge”页面，点击创建知识库。
- 上传文档，例如 PDF、Word、TXT、Markdown、FAQ 文档等。
- 选择分段规则：新手可先使用自动分段，后续根据测试结果优化。
- 选择 Embedding 模型，把文档转换为向量并写入向量数据库。
- 等待处理完成后，用测试问题检查召回片段是否准确。
5.2 文档怎么整理更适合 RAG
| 资料类型 | 建议整理方式 | 不建议做法 |
| 产品说明书 | 按功能模块拆分，保留标题层级 | 整本扫描 PDF 直接上传且无 OCR |
| FAQ | 一问一答结构，每条问题尽量清晰 | 多个问题混在一个段落里 |
| 企业制度 | 按章节、适用范围、生效时间整理 | 上传过期版本且不标日期 |
| 售后工单 | 先脱敏，再按问题类型归类 | 直接上传含隐私的原始聊天记录 |
| 网页资料 | 保留正文和标题，去掉导航、广告、页脚 | 把无关页面内容全部混入知识库 |
5.3 创建问答应用
- 进入“应用 / Studio”，新建一个 Chatflow 或聊天助手。
- 在提示词中说明角色、回答边界、是否必须基于知识库回答。
- 关联刚创建的知识库，并设置召回数量、相似度阈值等参数。
- 用真实问题测试，例如“退款规则是什么”“某个功能如何配置”“失败报错怎么处理”。
- 检查答案是否引用到正确文档片段，必要时调整切分规则和检索参数。
- 测试通过后发布应用，复制 WebApp 地址或 API 调用地址。
5.4 推荐提示词模板
| 你是一个企业知识库问答助手。 回答规则： 1. 优先基于知识库内容回答，不要编造不存在的政策、价格、链接或流程。 2. 如果知识库没有相关信息，请明确说明“资料中没有找到依据”。 3. 回答时先给结论，再列步骤或注意事项。 4. 对涉及账号、付款、隐私、法律风险的问题，提醒用户联系人工确认。 5. 如果用户问题含糊，先追问必要信息。 |
六、上线前优化：安全、备份、性能与升级
6.1 安全配置
- 管理员账号使用强密码，避免多人共用一个管理员账号。
- 配置 HTTPS，避免 API Key、登录态和用户输入明文传输。
- 限制服务器安全组端口，只开放 80/443/SSH 等必要端口。
- 模型 API Key 不要写入前端页面，也不要放在公开仓库。
- 对外发布应用时，明确数据使用边界和用户隐私说明。
6.2 备份策略
Dify 本地部署后，最重要的资产包括数据库、向量库、上传文件、.env 配置和应用编排配置。升级、迁移或修改 docker-compose 前，建议先做完整备份。
| # 示例：备份 docker 目录下的 volumes 和 .env cd dify/docker mkdir -p ~/dify_backup_$(date +%F) cp .env ~/dify_backup_$(date +%F)/.env cp -r volumes ~/dify_backup_$(date +%F)/volumes # 查看容器状态与日志 docker compose ps docker compose logs –tail=200 |
6.3 常见故障排查
| 问题 | 可能原因 | 处理建议 |
| 页面打不开 | 容器未启动、端口冲突、防火墙拦截 | docker compose ps / logs 检查服务状态，确认 80/443 端口 |
| 模型测试失败 | API Key、Base URL、模型名称错误 | 对照模型平台文档重新填写并测试 |
| 知识库不可用 | 没有配置 Embedding 模型或向量库异常 | 先配置可用 Embedding，再查看 worker 和向量库日志 |
| 上传文档处理失败 | 文件过大、格式复杂、OCR 缺失 | 先用小文档测试，必要时转为 Markdown/TXT |
| 回答幻觉明显 | 召回片段不准、提示词没约束、知识库过杂 | 优化分段、相似度阈值、提示词和资料来源 |
| 升级后异常 | .env 变量未同步、镜像版本变化 | 备份后对比 .env.example，逐项迁移自定义配置 |
七、适合普通用户的落地场景
7.1 网站教程知识库
把网站中的教程、FAQ、会员说明、下载说明、工具介绍整理成知识库，用户可直接提问“某个工具怎么安装”“会员下载失败怎么办”“某篇教程适合谁”。对 AI Stack Nav 这类内容站来说，Dify 可以作为智能搜索和客服入口。
7.2 企业内部文档问答
把制度文件、入职手册、报销流程、产品手册、项目规范上传到知识库，员工可以用自然语言查询制度条款。上线前要注意权限控制和资料版本管理，避免不同部门看到不该看的资料。
7.3 售后与客服辅助
把常见问题、故障处理、产品参数、售后流程接入知识库，让客服先用 Dify 检索和生成回复草稿，再由人工确认。这样既能提升回复速度，又能减少新人客服培训成本。
7.4 内容生产辅助
把选题库、标题模板、文章结构、品牌表达规范放入知识库，再通过工作流生成文章大纲、FAQ、SEO 信息、推广文案。对于站长来说，这是把“写作经验”变成可复用流程的一种方式。
八、FAQ
Q1：Dify 本地部署一定要服务器吗？
不一定。个人测试可以在本机 Docker Desktop 或 WSL2 中部署；如果要长期对外访问，建议使用 Linux 云服务器并配置域名和 HTTPS。
Q2：Dify 是不是完全免费？
Dify 开源版本可以自部署使用，但服务器、模型 API、向量库、存储、运维和带宽都可能产生费用。
Q3：只配置聊天模型，能做知识库问答吗？
通常不够。知识库问答还需要 Embedding 模型把文档向量化，必要时还要配置 Rerank 模型提升检索排序。
Q4：Ollama 本地模型适合生产环境吗？
适合内网测试和部分轻量场景。生产环境要看模型效果、硬件性能、并发需求和响应速度，不建议未经压测直接上线。
Q5：Dify 知识库回答不准怎么办？
先检查召回片段是否正确，再优化文档清洗、分段长度、Embedding 模型、相似度阈值、提示词约束和知识库范围。
Q6：升级 Dify 前要做什么？
先备份 .env、volumes、数据库和向量库数据，再查看官方更新说明，对比新的 .env.example 与本地配置。
Q7：Dify 可以接入 WordPress 网站吗？
可以。常见做法是把 Dify 应用发布为 WebApp 链接、嵌入 iframe，或通过 API 接入 WordPress 自定义页面/插件。
九、总结
Dify 本地部署的核心不是“把服务跑起来”这么简单，而是完成一条从模型接入、知识库处理、检索测试、应用发布到安全运维的完整链路。新手建议先用默认 Docker Compose 跑通，再逐步配置域名、HTTPS、模型供应商、知识库和备份策略。
对于内容站、企业知识库和客服场景，Dify 的优势在于把 RAG、提示词、工作流和 API 发布集中管理。只要资料整理得好、模型配置正确、上线前测试充分，就能快速做出一个真正可用的私有问答系统。
参考资料
- Dify Docs：Deploy Dify with Docker Compose – https://docs.dify.ai/en/self-host/quick-start/docker-compose
- Dify Docs：Environment Variables – https://docs.dify.ai/en/self-host/configuration/environments
- Dify Docs：Knowledge – https://docs.dify.ai/en/use-dify/knowledge/readme
- Dify GitHub：docker/README.md – https://github.com/langgenius/dify/blob/main/docker/README.md
