一、前言

Dify 是一款开源的 AI 应用开发平台，支持快速搭建聊天机器人、知识库问答、智能工具等各类大模型应用，兼容主流大模型厂商接口，同时支持在线调用与本地私有化部署两种模式。本文基于 Docker Compose 实现 Dify 本地从零部署，并完成通义千问大模型对接、聊天机器人创建与发布全流程，全程图文 + 命令行实操，新手也可顺利完成部署。

官方文档地址：https://docs.dify.ai/zh-hans/getting-started/install-self-hosted/dockercompose

二、部署前置条件

2.1 硬件最低要求

部署前请确保服务器 / 个人电脑满足以下配置，配置过低会出现镜像拉取缓慢、容器启动失败、服务卡顿等问题：

• CPU：≥ 2 核
• 内存（RAM）：≥ 4GiB
• 磁盘：预留至少 20GB 空间（用于存放镜像、容器数据）

2.2 软件依赖

本次部署基于容器化方案，必须提前安装 Docker 与 Docker Compose，主流系统（Windows、Linux、macOS）均可适配：

1. 安装 Docker（Docker Desktop 推荐新手使用，集成 Compose 组件）
   • Windows/macOS：前往 Docker 官网下载 Docker Desktop 并完成默认安装
   • Linux（CentOS/Ubuntu）：使用系统命令安装 Docker 及 Docker Compose
2. 网络要求：访问 GitHub 及模型插件仓库网络通畅，安装插件阶段建议开启代理，避免插件安装超时失败。

三、分步部署 Dify 核心服务

3.1 拉取 Dify 官方源码

打开终端（Windows 使用 PowerShell / CMD，Linux/macOS 使用系统终端），执行 git 命令克隆 Dify 开源仓库：

# 克隆 Dify 源码
git clone https://github.com/langgenius/dify.git

# 进入 docker 部署目录（核心部署目录）
cd dify/docker

补充说明：若服务器未安装 Git，可直接访问 GitHub 手动下载源码压缩包，解压后进入 docker 目录。

3.2 生成环境配置文件

Dify 依赖 .env 环境变量文件管理数据库、端口、服务地址等配置，官方提供示例配置文件，直接复制使用即可：

# 复制示例环境配置为正式配置文件
cp .env.example .env

基础部署无需修改 .env 文件默认配置，如需修改端口、数据库密码、域名等，可使用文本编辑器打开该文件自定义。

3.3 启动 Docker 容器集群

在 docker 目录下执行启动命令，后台运行所有 Dify 相关容器：

# 后台启动所有容器（首次执行会自动拉取官方镜像，耗时较长）
docker compose up -d

关键说明：

1. 首次启动会自动拉取数十个镜像，根据网络环境不同，耗时 5~20 分钟，请耐心等待，不要强制中断命令。
2. 常用 Docker Compose 运维命令（后续维护必备）：

   # 查看容器运行状态
   docker compose ps
   # 实时查看容器日志（排查启动失败问题）
   docker compose logs -f
   # 停止所有容器
   docker compose down
   # 重启服务
   docker compose restart
   

3. 容器全部启动成功后，状态会显示 Running，代表核心服务部署完成。

3.4 访问 Dify 后台并初始化管理员账号

1. 打开本地浏览器，输入默认访问地址：http://localhost
2. 首次进入系统会跳转至管理员账号设置页面，自定义用户名、密码完成初始化。
3. 使用刚设置的管理员账号登录 Dify 工作台，至此 Dify 基础部署完成。

四、集成大模型（通义千问）

Dify 本身不内置大模型，需手动安装模型插件并配置 API Key，本文以通义千问为例演示在线大模型对接流程。

4.1 安装通义千问插件

1. 登录 Dify 后，点击页面右上角头像，在下拉菜单中选择 设置。
2. 在左侧导航栏找到 模型供应商 模块，进入插件市场。
3. 在搜索框搜索 通义千问，点击插件右侧 安装。

   重要提示：插件安装阶段网络要求较高，建议开启代理，否则大概率出现安装超时、失败问题。

4. 查看插件安装状态（两种校验方式）：
   • 方式一（日志校验，推荐）：终端执行 docker compose logs -f，观察日志，出现 Running 状态、/plugin/xxx 接口请求日志，代表插件服务启动正常。
   • 方式二（页面校验）：返回「模型供应商」页面，通义千问插件状态变为待配置，即安装成功。

4.2 配置通义千问 API Key

1. 点击通义千问插件下方 设置 按钮，进入配置页面。
2. 填入你在阿里云获取的 通义千问 API Key，填写完成后点击 测试。
3. 页面提示「测试成功」，代表大模型接口对接正常，最后点击 保存。
4. 回到「模型列表」，确认通义千问模型已正常加载，系统提示消失。

五、创建并发布 AI 聊天助手应用

大模型配置完成后，我们基于 Dify 快速创建一个基础聊天机器人，完成全流程验证。

5.1 创建空白聊天应用

1. 返回 Dify 工作台首页，点击 创建空白应用。
2. 应用类型选择 聊天助手，自定义应用名称（如：本地测试机器人），点击 创建。

5.2 调试聊天机器人

1. 进入应用编辑页面，右侧为调试与预览窗口，即为机器人对话界面。
2. 在输入框中输入测试问题，例如：你是谁。
3. 正常情况下，机器人会通过通义千问大模型返回对应回答，证明模型调用、对话功能全部正常。

5.3 发布应用

测试无误后，点击页面右上角 发布 按钮，即可对外发布该聊天助手。发布后可通过 Dify 提供的链接、API 等方式对接前端页面或第三方系统。

六、常见问题与解决方案

结合部署实操经验，整理新手高频报错及对应解决办法：

问题 1：执行 docker compose up -d 拉取镜像超时 / 失败

• 原因：国内网络访问 Docker Hub、GitHub 不稳定
• 解决方案：
  1. 配置 Docker 国内镜像源（阿里云、网易云镜像）；
  2. 临时开启网络代理，完成镜像拉取后关闭。

问题 2：通义千问插件安装一直转圈、安装失败

• 原因：插件仓库境外网络访问受限
• 解决方案：安装插件期间保持代理开启，等待插件日志显示 Running 再关闭代理。

问题 3：浏览器访问 http://localhost 无法打开页面

• 原因：容器未完全启动、80 端口被占用
• 解决方案：
  1. 执行 docker compose ps 检查容器状态，确保所有容器为 Running；
  2. 若 80 端口冲突，修改 .env 文件中的服务端口，重启容器。

问题 4：对话提示模型未配置 / 调用模型失败

• 原因：API Key 填写错误、Key 权限不足、模型未启用
• 解决方案：重新进入模型供应商配置页，核对 API Key，再次点击「测试」验证连通性。

七、总结

1. 本次部署基于 Docker Compose，全程容器化，无需复杂环境配置，支持 Windows、Linux、macOS 全平台。
2. 核心流程概括：环境准备 → 克隆源码 → 配置环境文件 → 启动容器 → 初始化管理员账号 → 安装大模型插件 → 配置 API Key → 创建并发布 AI 应用。
3. Dify 除聊天助手外，还支持知识库、工作流、插件扩展等功能，完成基础部署后可进一步探索高阶玩法。
4. 私有化部署优势：数据本地流转，隐私性更强，可自由搭配各类开源 / 商用大模型。

八、参考资料

1. Dify 官方自托管文档：https://docs.dify.ai/zh-hans/getting-started/install-self-hosted/dockercompose
2. Docker 官方文档：https://docs.docker.com/
3. 通义千问 API 官方文档：阿里云通义千问开发者平台

---

补充拓展

如需后续升级 Dify 版本、配置 HTTPS、对接本地大模型（Ollama 等），可基于本文基础配置延伸操作，核心容器启动逻辑保持不变。

Note: 对AI 技术感兴趣的小伙伴，可以关注我下方，私信我发送"AI资料"，可获取AI相关资料和源码。