Docker Compose 部署 Dify 完整实战教程（2026避坑版）
一、前言与部署概述
Dify 是一款开源的大模型应用开发平台，支持可视化Prompt编排、RAG知识库搭建、智能体配置、插件扩展等核心功能，可快速私有化部署企业级AI应用，无需复杂开发即可搭建对话机器人、文档问答、AI助手等场景。
本文采用Docker Compose一键部署方案，基于CentOS 7/8系统实操，全程命令可直接复制，针对部署过程中常见的Docker版本兼容、网络异常、命令报错、启动卡住等问题做专项避坑，测试环境与轻量生产环境通用，部署后数据持久化，重启不丢失配置。
1.1 部署环境要求
- 操作系统：CentOS 7.x / 8.x（x86_64架构）
- 硬件配置：最低2核4G，推荐4核8G；磁盘可用空间≥20G（测试环境10G+即可，本文实测33G磁盘完全够用）
- 网络要求：服务器可访问外网，放行80端口（或自定义端口），关闭防火墙或放行对应端口
- 依赖软件：Docker Engine ≥20.10、Docker Compose V2（必须，V1版本不兼容高版本配置）
1.2 部署架构说明
本次部署包含Dify全套核心组件，通过Docker Compose统一编排，自动部署以下服务：
- Dify Web前端、API服务、Worker任务队列
- PostgreSQL（数据库，存储配置、用户、对话数据）
- Redis（缓存服务，提升接口响应速度）
- Weaviate（向量数据库，支撑RAG知识库检索）
- SSRF Proxy、Sandbox（安全沙箱与代理服务）
- Nginx（反向代理，统一入口）
所有服务容器化部署，数据挂载至本地卷，保障数据持久化，后续升级、迁移更便捷。
二、环境准备：Docker与Docker Compose安装
Dify最新版本仅支持Docker Compose V2，旧版V1（docker-compose带短横）会出现语法兼容报错，需先安装/升级正确版本。
2.1 卸载旧版本Docker（避免冲突）
若服务器已安装老旧版本Docker，先卸载清理，防止版本冲突：
yum remove -y docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine rm -rf /var/lib/docker rm -rf /etc/docker
2.2 安装Docker Engine稳定版
- 安装依赖工具
yum install -y yum-utils device-mapper-persistent-data lvm2
- 添加Docker官方YUM源
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
- 安装最新版Docker
yum install -y docker-ce docker-ce-cli containerd.io
- 启动Docker并设置开机自启
systemctl start docker systemctl enable docker
- 验证Docker安装
docker --version
出现版本号（如Docker version 26.x.x）即安装成功。
2.3 安装Docker Compose V2（核心避坑）
直接安装官方插件版，无需手动配置，彻底解决旧版本兼容问题：
yum install -y docker-compose-plugin
验证Compose版本：
docker compose version
需显示v2.20.0及以上版本，低于此版本会出现“Additional property required is not allowed”报错。
2.4 配置Docker国内镜像加速（解决拉取镜像慢）
默认Docker Hub拉取镜像速度慢，配置国内镜像源，提升部署效率：
cat > /etc/docker/daemon.json <<EOF { "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ] } EOF
重启Docker生效：
systemctl daemon-reload systemctl restart docker
三、Dify项目下载与配置
3.1 下载Dify官方源码
建议将项目存放至/opt目录，统一管理服务：
cd /opt # 克隆官方源码 git clone https://github.com/langgenius/dify.git # 进入docker部署目录 cd dify/docker3.2 生成环境配置文件
复制官方示例配置文件，无需修改即可直接部署测试，生产环境可按需调整端口、密钥等参数：
cp .env.example .env
可选配置：若80端口被占用，编辑.env文件，修改EXPOSE_NGINX_PORT为自定义端口（如8080），同时防火墙放行该端口即可。
3.3 预清理Docker异常网络（避坑核心）
针对部署常见的“Container cannot be connected to network endpoints”网络报错，提前清理残留异常网络与无用资源：
# 停止残留容器 docker compose down # 清理无用网络 docker network prune -f # 清理无用镜像、缓存 docker system prune -f
四、Dify启动部署与验证
4.1 一键启动Dify服务
进入dify/docker目录后，执行以下命令后台启动所有容器（命令格式核心避坑）：
# 正确命令：docker + compose + up -d，无短横，空格分隔 docker compose up -d
如果还是不行直接 docker-compose up -d 试试吧
命令报错避坑：若提示“unknown shorthand flag: 'd' in -d”，是命令格式错误，必须严格按照docker compose up -d执行，compose与up之间有空格，-d紧跟up后，不可拆分、不可少空格。
首次启动会自动拉取所有依赖镜像，耗时3-10分钟（取决于服务器网络），若中途卡住，直接Ctrl+C中断，重新执行该命令即可，Docker Compose具备幂等性，不会重复创建容器、不损坏数据。拉取镜像如下图：
4.2 验证容器运行状态
启动完成后，查看所有服务状态，确保全部为Up状态：
docker compose ps
正常结果：所有服务（web、api、worker、postgres、redis、weaviate等）状态均为Up，无退出、无异常。
4.3 查看启动日志（故障排查）
若容器启动异常，实时查看日志定位问题：
# 查看全部服务日志 docker compose logs -f # 单独查看某服务日志（如web服务） docker compose logs -f web
日志无报错、出现“服务启动成功”字样，即部署完成。
五、Dify访问与初始配置
5.1 访问Dify后台
浏览器输入服务器IP地址，直接访问（默认80端口，自定义端口则加端口号），一般直接用IP就可以访问了
5.2 初始管理员账号
- 开始运行会跳出管理员注册页面，直接添加自己的邮箱密码就行。
5.3 基础配置
- 修改管理员密码与个人信息
- 创建知识库、配置对话应用
整理日常运维必备命令，方便后续管理、重启、升级服务。最后附上安装成功的dify，利用本地ollama运行的qwen2:1.5b模型
七、常见故障与解决方案（全文避坑总结）
原因：使用了旧版Docker Compose V1（docker-compose带短横），不支持高版本配置语法
7.2 报错：Container cannot be connected to network endpoints
解决：执行docker compose down && docker network prune -f，重新启动服务
原因：命令格式错误，空格缺失或参数位置错误
7.4 启动卡住、镜像拉取失败
解决：配置Docker国内镜像加速，中断后重新执行启动命令
原因：防火墙未放行80端口、容器未正常启动
八、部署总结
核心避坑要点：必须使用Docker Compose V2、提前清理异常网络、严格遵循命令格式，遇到启动卡住可直接重复执行启动命令，无需担心数据损坏。部署完成后即可快速搭建各类AI应用，实现私有化大模型应用落地。
