Dify 本地部署智能体平台完整教程（Docker Compose 一键启动 + 常见报错避坑）

一、Dify 介绍

Dify（Define + Modify）是一个开源的大语言模型（LLM）应用开发平台，由苏州语灵人工智能推出。它提供可视化界面，帮助开发者快速构建 AI 应用。

核心能力：

• 🤖 基于 Agent 架构构建智能体应用

• 📚 基于 RAG 构建私有知识库应用

• 🔄 基于 Workflow 构建智能工作流应用

• 🏠 支持本地化部署，保证数据安全

一句话概括：不懂后端、不懂前端，也能通过可视化界面把大模型能力做成真正能用的产品。

二、环境准备

在开始之前，请确认本机满足以下条件：

💡 如果 Docker 还没装或镜像拉取很慢，建议先看上一篇 Docker Desktop 安装 + 国内镜像源配置教程，把基础环境打牢。

验证 Docker 是否就绪：

docker –version
docker compose version

三、下载与安装

3.1 克隆 Dify 仓库

打开终端（Windows 可用 PowerShell / CMD），执行：

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

💡 GitHub 访问慢的话可以配置代理，或者使用 Gitee 上的镜像仓库。克隆完成后会得到一个 dify 目录。

3.2 启动 API 服务

# 进入 docker 目录
cd dify/docker/
准备环境变量配置文件
cp .env.example .env
启动所有服务
docker compose up -d

命令解释：

• cp .env.example .env：将示例环境变量文件复制为正式配置，Dify 启动时会读取 .env 中的参数（数据库密码、端口、密钥等），这一步千万别漏。

• docker compose up -d：后台启动 docker-compose.yaml 中定义的所有容器（API、Worker、Web 前端、PostgreSQL、Redis、Weaviate、Sandbox 等）。

3.3 查看容器启动状态

docker compose ps

正常情况下会看到一排 Up 或 running 状态的容器。首次启动需要拉取镜像，耗时取决于网络，耐心等待即可。

3.4 访问 Dify

全部容器启动完成后，打开浏览器访问：

http://localhost/

首次进入会引导你设置管理员账号，设置完成后即可登录进入 Dify 主界面，开始创建应用。

⚠️ 如果访问不到，先执行 docker compose ps 确认 docker-web、docker-api 容器是否已正常运行。

四、常见错误处理

国内网络环境下部署 Dify，最常见的坑就是镜像拉取失败。下面两个报错基本覆盖了 90% 的场景。

错误 1：镜像拉取超时 / HTTPS Proxy 报错

报错内容：

Error response from daemon: failed to resolve reference "cr.weaviate.io/semitechnologies/weaviate:1.39.2":
failed to do request: Head "https://registry-1.docker.io/v2/semitechnologies/weaviate/manifests/1.39.2":
dialing registry-1.docker.io:443 container via direct connection because Docker Desktop has no HTTPS proxy:
connecting to registry-1.docker.io:443: dial tcp [2a03:2880:f130:83:face:b00c0:25de]:443: connectex:
A connection attempt failed because the connected party did not properly respond after a period of time…

原因： semitechnologies/weaviate:1.39.2 这个镜像默认从国外仓库拉取，国内网络直连超时。

解决方案：改成华为云国内镜像地址。

第 1 步：修改 docker-compose.yaml（或对应 .env 中的镜像配置）

找到 weaviate 服务下的 image 字段，将原地址替换为国内镜像：

weaviate:
image: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/semitechnologies/weaviate:1.39.2
# 原地址：cr.weaviate.io/semitechnologies/weaviate:1.39.2

第 2 步：手动单独拉取该镜像（推荐，提前验证能否拉下来）

docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/semitechnologies/weaviate:1.39.2

拉取成功后再执行 docker compose up -d，即可跳过该镜像的下载环节。

💡 如果用的是其他版本的 weaviate，记得把镜像 tag 换成与 docker-compose.yaml 中一致的版本号，避免版本不匹配导致服务异常。

错误 2：镜像层文件损坏（magic number mismatch）

报错内容：

failed to copy: invalid input: magic number

原因： 在拉取 Dify 镜像时，由于网络中断、国内镜像源同步延迟或本地 Docker 缓存异常，导致下载的镜像层文件损坏或不完整。

解决方案：清理后重新拉取。

# 先停掉当前 compose 服务
docker compose down
清理所有未使用的镜像和构建缓存
docker system prune -a
重新启动
docker compose up -d

⚠️ 重要提醒： docker system prune -a 会清理所有未被容器使用的镜像和缓存，请确保没有其他正在运行的项目依赖这些镜像，否则会被一并删掉需要重新拉取。如果只想清理构建缓存，可以用 docker builder prune；只清理悬空镜像用 docker image prune。

五、Dify 常用运维命令

部署完成后，日常维护只需记住这几条命令：bash

# 查看所有容器状态
docker compose ps
查看某个服务日志（如 api、web、worker）
docker compose logs -f api
停止所有服务（保留数据）
docker compose down
启动所有服务
docker compose up -d
重启某个服务（如修改配置后）
docker compose restart api

💡 更新 Dify 版本： 进入仓库目录执行 git pull 拉取最新代码，然后 docker compose down + docker compose up -d 即可。数据库数据保存在 Docker 卷中，不会丢失，但升级前建议备份 .env 和数据库卷。

六、总结

整体流程其实非常顺畅，核心难点全在镜像拉取。国内环境下，只要把慢的/拉不下来的镜像替换成国内镜像源，或者在 Docker 里配置好 registry-mirrors，基本不会再有其他问题。