Dify本地部署完整教程：Docker与Git配置指南

Dify本地部署完整教程：Docker与Git配置指南

在大模型应用开发日益普及的今天，如何快速搭建一个稳定、可扩展的AI工程化平台成为开发者关注的重点。Dify 作为一款开源的可视化 LLM 应用开发工具，集成了 Prompt 编排、RAG 检索增强生成、Agent 流程设计和数据集管理等核心能力，正逐渐成为企业与个人构建 AI Agent 的首选框架。

而要真正发挥 Dify 的潜力，第一步就是完成本地环境的部署。本文将带你从零开始，基于 Docker 和 Git 实现 Dify 的一键式本地部署，并深入解析每个环节的关键细节，帮助你避开常见“坑点”，顺利启动属于自己的 AI 开发平台。

环境准备：让容器跑起来

Dify 是典型的微服务架构系统，包含 Web 前端、API 后端、数据库、缓存、向量库等多个独立运行的服务模块。手动部署这些组件不仅繁琐，还容易出错。因此，它采用了 Docker + Docker Compose 的方式来统一管理所有服务——这也是我们首先要搞定的基础环境。

安装并优化 Docker Desktop

Docker 是现代云原生应用的事实标准。无论你在 Windows、macOS 还是 Linux 上工作，Docker 都能提供一致的容器运行时环境。

前往 Docker 官网 下载对应系统的安装包。以 Windows 为例：

首次启动时会提示登录 Docker Hub 账号。如果你没有账号或网络受限，可以直接点击 Continue without signing in 跳过。这不会影响本地镜像拉取和容器运行，仅限制推送镜像到远程仓库的功能。

📌 小贴士：国内用户访问 docker.io 经常遇到超时或拉取失败的问题。解决办法是配置镜像加速器。

进入 Settings → Docker Engine，替换默认 JSON 配置如下：

{
"builder": {
"gc": {
"defaultKeepStorage": "20GB",
"enabled": true
}
},
"experimental": false,
"features": {
"buildkit": true
},
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://docker.1panel.dev",
"https://docker.hlmirror.com",
"https://registry.docker-cn.com",
"http://hub-mirror.c.163.com"
]
}

保存后点击 Apply & Restart。其中 daocloud.io 和 1panel.dev 的源实测速度较快且稳定性高，优先推荐。

你可以通过命令行验证是否生效：

docker info | grep -i mirror

若能看到列出的镜像地址，则说明配置成功。

安装 Git：代码世界的通行证

Dify 的源码托管在 GitHub 上，我们需要通过 Git 来克隆项目。虽然也可以直接下载 ZIP 包，但后续更新、分支切换都会变得极其困难。

打开终端执行：

git –version

如果有输出版本号（如 git version 2.40.0.windows.1），说明已安装；否则需要前往 https://git-scm.com/downloads 下载安装。

安装过程中有几个关键选项需要注意：

• 安装路径：建议不要放在 C 盘根目录，避免权限问题
• PATH 环境变量：务必选择第二项 “Use Git from the Windows Command Prompt”，这样才能在 PowerShell 或 CMD 中调用 git 命令
• 行尾换行符转换：选择 Checkout Windows-style, commit Unix-style，保证跨平台兼容性
• 默认编辑器：如果安装了 VS Code，可以设为默认 Git 编辑器

安装完成后，在任意目录右键选择 “Git Bash Here” 打开终端，设置基本信息：

git config –global user.name "your-name"
git config –global user.email "your-email@example.com"

这一步虽小，却是良好开发习惯的起点。

部署流程：三步启动 Dify 平台

一切就绪后，就可以正式开始部署 Dify。

第一步：获取源码

确保 Docker 正在运行（状态栏图标为绿色），然后进入你的项目目录，例如：

cd D:\\Projects

执行克隆命令：

git clone https://github.com/langgenius/dify.git

这个过程可能需要几分钟，取决于网络状况。如果速度较慢，可尝试更换网络环境或使用代理。

克隆完成后，进入 Docker 配置目录：

cd dify/docker

这里存放着整个部署的核心文件：docker-compose.yml 定义了所有服务的依赖关系和启动参数，.env.example 则是环境变量模板。

第二步：配置运行参数

将模板复制为实际使用的 .env 文件：

# 在 Git Bash 中使用 cp
cp .env.example .env

⚠️ 注意：Windows CMD 使用 copy，而 Git Bash 必须用 cp，别搞混了。

此时 .env 文件中的默认配置已经足够用于本地开发。但为了安全起见，建议修改以下几项：

尤其是密码字段，切勿保留默认值上线使用。

第三步：启动容器集群

先确认 Docker Compose 版本：

docker compose version

如果返回 v2.x.x，说明使用的是新版 V2 语法；如果没有该命令，尝试：

docker-compose –version

V2 是当前主流，命令更简洁统一。

执行启动命令：

docker compose up -d

加上 -d 表示后台运行，避免占用终端。首次运行会自动拉取所有所需镜像，包括：

• nginx：反向代理，处理前端请求
• web：前端界面服务
• api：后端逻辑入口
• worker：异步任务处理器
• db：PostgreSQL 数据库存储结构化数据
• redis：缓存与消息队列
• vector-db：Weaviate/Qdrant 向量数据库，支撑 RAG 功能

整个过程大约耗时 5–10 分钟，具体看网络带宽。

可通过以下命令查看服务状态：

docker compose ps

正常情况下所有容器都应显示为 running：

NAME SERVICE STATUS PORTS
dify-nginx nginx running 0.0.0.0:80->80/tcp
dify-web web running
dify-api api running
dify-worker worker running
dify-db db running 5432/tcp
dify-redis redis running 6379/tcp
dify-vector-db vector-db running 6333/tcp

如果某些容器处于 restarting 或 exited 状态，不要慌，先查日志定位原因：

docker compose logs api
docker compose logs db

常见的问题有：

• 镜像拉取失败 → 检查镜像加速器是否生效
• 端口冲突 → 默认 NGINX 占用 80 端口，若 IIS 或其他服务已占用，可在 .env 中修改 NGINX_PORT=8080
• 内存不足 → 推荐至少 8GB 内存，WSL2 用户可在 .wslconfig 中设置内存上限

初始化平台：创建你的第一个管理员账户

当所有服务运行正常后，打开浏览器访问：

👉 http://localhost/install

你会看到 Dify 的初始化页面。

填写管理员信息：

• 邮箱：admin@dify.ai（仅为示例）
• 用户名：admin
• 密码：请设置强密码（含大小写字母、数字、特殊字符）

点击 Install 完成安装。

成功后将自动跳转至登录页：http://localhost

使用刚才的账号登录，即可进入 Dify 控制台主界面。

首页展示内容包括： – 已创建的应用列表 – 快捷创建按钮（支持文本生成、Agent、RAG 应用等） – 文档中心与社区链接入口

至此，本地部署已完成！🎉

Dify 能做什么？不只是个聊天界面

很多人第一次打开 Dify，以为它只是一个类似 ChatGPT 的前端封装。实际上，它的能力远不止于此。

可视化流程编排：拖拽式 AI Agent 构建

无需写一行代码，通过图形化界面就能组合多个节点，实现复杂的业务逻辑。

比如你可以构建一个智能客服 Agent： 1. 接收用户输入 2. 查询知识库（RAG） 3. 判断是否需要转人工 4. 自动生成工单并通知客服人员

整个流程通过“条件判断”、“HTTP 请求”、“LLM 调用”等节点串联而成，清晰直观。

RAG 支持：打造专属知识大脑

上传 PDF、TXT、Markdown 文件，Dify 会自动进行分段、清洗和向量化处理，存储到内置的 Weaviate 或 Qdrant 向量数据库中。

查询时，系统会根据语义相似度检索相关内容，并动态注入 prompt 上下文中，显著提升回答准确率。

支持多种 Embedding 模型切换，如 BGE、text-embedding-ada-002 等，适应不同场景需求。

Prompt 工程调试利器

内置强大的调试面板，支持： – 多模型切换（GPT-4、Claude、通义千问、百川等） – 变量插槽（{{input}}, {{context}}） – 输出格式约束（JSON Schema） – 温度、Top-p、最大 token 数等参数实时调节

还能保存不同版本的 Prompt 进行 A/B 测试，极大提升迭代效率。

数据集全生命周期管理

不仅仅是“上传文档”，Dify 提供完整的数据治理能力： – 数据清洗与去重 – 构建高质量问答对 – 用于模型微调或评估测试 – 支持版本控制与团队协作

特别适合需要持续优化模型表现的企业级场景。

丰富的应用模板

开箱即用的模板覆盖多个行业： – 智能客服机器人 – 自动生成营销文案 – 法律文书助手 – 教育答疑系统 – 内容摘要与翻译工具

每个模板都可以自由修改，快速适配你的业务需求。

常见问题排查指南

即使按照步骤操作，也可能遇到一些意外情况。以下是高频问题及解决方案：

❌ docker compose up -d 报错无法连接网络？

原因：国内网络环境下无法访问 docker.io，导致镜像拉取失败。

解决方法： 1. 回到 Docker 设置，确认 registry-mirrors 已正确配置 2. 推荐使用 https://docker.m.daocloud.io 和 https://docker.1panel.dev 3. 修改后重启 Docker Desktop

也可临时改用手机热点测试是否为网络策略限制。

❌ 访问 http://localhost 显示空白或 502 错误？

这是最常见的问题之一，通常由 Nginx 反向代理失败引起。

排查步骤：

docker compose logs nginx
docker compose logs api

重点查看是否有以下错误： – 数据库连接失败（检查 POSTGRES_PASSWORD 是否一致） – API 服务崩溃（可能是环境变量缺失或端口占用） – SSL 配置异常（本地部署一般不会触发）

如果是 502，大概率是 api 服务未启动成功。可以尝试重建：

docker compose down
docker compose up -d –force-recreate

🔁 如何升级 Dify 到最新版本？

随着项目不断迭代，保持版本更新非常重要。

步骤如下：

# 回到项目根目录
cd ../..
git pull origin main

# 进入 docker 目录重新部署
cd docker
docker compose down
docker compose up -d –build

⚠️ 注意：升级前务必备份 .env 文件，防止自定义配置被覆盖。

你也可以通过修改 .env 中的 TAG 字段指定特定版本，实现灰度升级。

🛡️ 能否用于生产环境？

当然可以，但需做进一步加固：

• 部署环境：建议使用独立服务器或云主机（如 AWS、阿里云 ECS）
• HTTPS 加密：配置 Nginx + Let’s Encrypt 实现自动证书签发
• 持久化存储：挂载外部卷，防止容器重建导致数据丢失
• 访问控制：设置防火墙规则、IP 白名单、JWT 认证等
• 监控告警：接入 Prometheus/Grafana 监控资源使用情况
• CI/CD 集成：结合 GitHub Actions 或 Jenkins 实现自动化部署

对于企业用户，还可以考虑使用 Kubernetes 替代 Docker Compose，实现更高可用性和弹性伸缩。

Dify 的出现，标志着 AI 应用开发正在从“实验阶段”迈向“工程化落地”。它降低了非专业开发者参与大模型应用构建的门槛，同时也为专业团队提供了标准化、可复用的技术栈。

通过 Docker 与 Git 的组合，我们实现了“一次配置，随处运行”的理想状态。无论是本地调试、团队协作还是生产发布，这套流程都能无缝衔接。

更重要的是，Dify 不是一个封闭系统，而是一个开放的生态平台。你可以自由接入私有模型、自建向量库、集成内部系统接口，真正实现 AI 与业务的深度融合。

📌 GitHub 项目地址：https://github.com/langgenius/dify 📘 官方文档：https://docs.dify.ai

现在就开始你的 AI 应用构建之旅吧！