Dify从入门到精通(一)——Docker Compose一键部署实战

1. 为什么选择Docker Compose部署Dify如果你对AI应用开发感兴趣但又觉得从零开始搭建大模型环境、处理各种依赖和配置太麻烦那Dify的出现简直就是福音。我自己刚开始接触LLM应用时光是环境配置就折腾了好几天各种Python包冲突、服务启动失败让人头大。直到用了Dify特别是它的Docker Compose部署方式我才真正体会到什么叫“一键部署开箱即用”。简单来说Dify是一个帮你快速搭建AI应用的操作系统。你想做一个智能客服、一个文档问答机器人或者一个创意写作助手不需要从零写代码去调用大模型的API也不需要自己搭建前后端和数据库。在Dify的可视化界面上拖拖拽拽配置一下提示词Prompt连接上你的数据一个可用的AI应用就诞生了。而Docker Compose则是把运行Dify所需的所有“零件”——比如网站界面、后端逻辑处理、数据库、缓存服务——打包成一个“乐高套装”的说明书。你只需要一条命令它就能自动把这些零件下载、组装、启动起来完全不用关心底层复杂的安装过程。我推荐Docker Compose方式尤其是对于新手和想要快速验证想法的人原因有三点。第一是隔离性。Dify服务跑在独立的Docker容器里和你系统里原有的其他服务比如MySQL、Redis互不干扰。部署失败了直接删掉容器重来不会把你的系统环境搞乱。第二是一致性。我在自己Mac笔记本上测试通过把同样的docker-compose.yml文件拿到公司的Linux服务器上也能一模一样地跑起来彻底告别“在我机器上是好的”这种魔咒。第三是可维护性。所有服务配置都写在一个YAML文件里版本升级、服务重启、查看日志都有统一简单的命令管理起来非常清晰。所以无论你是想在自己的电脑上快速体验还是要在云服务器上搭建一个给团队使用的正式环境通过Docker Compose来部署Dify都是最稳、最快的那条路。接下来我们就从零开始一步步把它跑起来。2. 部署前的准备工作打好地基老话说得好磨刀不误砍柴工。在运行那条神奇的docker-compose up -d命令之前我们需要确保“地基”是牢固的。这里主要就是三样东西操作系统、Docker引擎和Docker Compose插件。别担心步骤都很简单。2.1 系统与环境检查首先你的机器需要满足一些基本条件。Dify的Docker镜像支持主流的操作系统Linux这是最推荐的生产环境选择比如Ubuntu 20.04/22.04 LTS或者CentOS 7/8。云服务器绝大多数也是Linux系统。macOS苹果电脑无论是Intel芯片还是Apple SiliconM1/M2/M3都完美支持。Windows需要开启WSL 2Windows Subsystem for Linux然后在WSL 2的Linux子系统比如Ubuntu中进行操作。不建议直接在原生Windows上操作。硬件方面建议给Dify分配至少4GB的内存如果后面要跑一些较大的本地模型8GB或以上会更流畅。磁盘空间准备个20GB以上用来存放Docker镜像和产生的数据。打开你的终端Linux/macOS的Terminal或Windows上的WSL终端我们依次检查核心依赖是否就位。# 1. 检查Git。我们需要用它来拉取Dify的代码仓库。 git --version # 如果看到类似 git version 2.xx.x 的输出说明Git已安装。 # 2. 检查Docker引擎。它是运行所有容器的基础。 docker --version # 期望看到 Docker version 20.10.x 或更高版本。 # 3. 检查Docker Compose插件。这是关键它负责编排多个容器。 docker compose version # 注意命令是 docker compose中间没有横杠。期望看到 Docker Compose version v2.x.x。如果你运行上面的命令提示“command not found”那就说明对应的工具还没安装。别急安装过程非常简单。2.2 一键安装缺失的依赖以Ubuntu为例假设你用的是一台全新的Ubuntu 22.04服务器我们可以用下面这一串命令搞定所有安装。如果你用的是其他系统原理也类似只是包管理命令不同比如CentOS用yum。# 更新系统软件包列表 sudo apt update # 安装Git sudo apt install -y git # 安装Docker的依赖工具 sudo apt install -y ca-certificates curl gnupg # 添加Docker的官方GPG密钥和软件源 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 再次更新并安装Docker引擎和Compose插件 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 启动Docker服务并设置开机自启 sudo systemctl start docker sudo systemctl enable docker # 可选但推荐将当前用户加入docker组这样以后就不用每次都加sudo了 sudo usermod -aG docker $USER # 执行完这条命令后你需要**退出当前终端重新登录**这个改动才会生效。重新登录后再运行docker --version和docker compose version应该就能看到正确的版本信息了。至此我们的地基就打得非常牢固了。3. 获取Dify的“蓝图”与“零件清单”环境准备好了接下来我们要拿到搭建Dify的“图纸”和“零件清单”也就是源代码和配置文件。Dify的所有代码都开源在GitHub上我们通过Git命令把它克隆到本地。3.1 克隆官方代码仓库我习惯在用户目录下创建一个专门的项目文件夹这样比较整洁。你跟着我做就行。# 创建一个名为dify的目录并进入它 mkdir -p ~/dify cd ~/dify # 从GitHub克隆Dify官方仓库的代码 git clone https://github.com/langgenius/dify.git # 克隆完成后进入dify目录 cd dify这个过程很快因为代码本身不大。完成后你的~/dify目录下就会有一个dify文件夹里面就是全部源码。3.2 理解目录结构关键文件在哪进到dify目录后用ls命令看看你会发现不少文件夹。对于部署来说我们只需要关注最核心的几个dify/ ├── docker/ # 【核心】Docker部署相关的所有配置文件都在这里 ├── api/ # 后端API服务的源代码 ├── web/ # 前端网页的源代码 ├── worker/ # 异步任务处理服务的源代码 └── docker-compose.yml - docker/docker-compose.yml # 【最关键】一键部署的入口文件一个软链接看到那个docker-compose.yml了吗它其实是一个软链接指向docker/docker-compose.yml。这个YAML文件就是我们的“总装说明书”里面定义了要启动哪些服务、用什么镜像、端口怎么映射、数据存哪里等等。我们后续的所有自定义调整几乎都是围绕这个文件进行的。提示如果你网络访问GitHub比较慢可以考虑使用国内镜像源来加速克隆比如在git clone命令的URL前加上https://ghproxy.com/代理。但通常直接克隆问题也不大。3.3 可选但建议切换到稳定版本默认情况下git clone拉取的是最新的开发版main分支。开发版功能最新但可能偶尔会有一些小问题。对于生产环境或者追求稳定的用户我强烈建议切换到最新的稳定版本Tag。# 进入dify代码目录如果还没在的话 cd ~/dify/dify # 查看所有可用的版本标签 git tag # 假设最新的稳定版是 v0.6.10我们就切换到它 git checkout v0.6.10切换后你的docker-compose.yml文件内容就会固定在这个版本部署时拉取的Docker镜像也是对应版本的这样能最大程度保证稳定性。你可以在Dify的GitHub Release页面查看最新的稳定版号。4. 核心实战解读与配置docker-compose.yml现在我们来到了最核心的环节。很多人看到YAML文件里一大堆配置就发怵其实我们只需要弄懂几个关键点就能轻松驾驭它。让我们进入docker目录看看这个“总装说明书”。cd ~/dify/dify/docker cat docker-compose.yml文件内容看起来不少但结构很清晰。它主要定义了5个服务servicesdify-api后端、dify-web前端、dify-worker后台任务、dify-postgres数据库、dify-redis缓存。此外还有volumes数据卷和networks网络的配置。我们不需要逐行理解只需知道如何修改几个最常碰到的配置项。4.1 修改服务端口解决端口冲突这是最可能遇到的问题。默认配置中前端Web服务将容器内的80端口映射到了宿主机的80端口后端API服务将容器内的8000端口映射到了宿主机的8000端口。如果你的服务器上80端口已经被Nginx、Apache占用或者8000端口被其他应用用了就会导致Dify启动失败。修改方法很简单用你喜欢的文本编辑器如vim或nano打开docker-compose.yml文件。vim docker-compose.yml找到services下面的web和api部分services: web: image: langgenius/dify-web:latest ports: - 80:80 # 格式是 “宿主机端口:容器内端口” ... api: image: langgenius/dify-api:latest ports: - 8000:8000 ...假设你想把前端访问端口改成8080后端API端口改成8081就这样改ports: - 8080:80 # 现在访问 http://你的IP:8080ports: - 8081:8000 # 现在后端API地址是 http://你的IP:8081改完保存即可。这样Dify服务就会使用新的端口避免和你机器上现有的服务“打架”。4.2 配置镜像加速解决拉取镜像慢Docker镜像默认从Docker Hub拉取在国内网络环境下可能会非常慢甚至超时。我们可以为每个服务配置国内镜像源来加速。国内常用的有阿里云镜像、网易云镜像等。你需要为services下的每一个用到外部镜像的服务主要是api,web,worker,postgres,redis添加image字段指向国内的镜像地址。这里以阿里云镜像为例你需要先有一个阿里云账号在容器镜像服务里开通并设置密码获取专属加速器地址格式通常是你的ID.mirror.aliyuncs.com。但更通用的方法是直接修改Docker守护进程的配置设置全局镜像加速器这样所有镜像拉取都会加速。这里给出两种方法。方法一修改Docker守护进程配置推荐一劳永逸# 创建或修改Docker的配置文件 sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [https://你的ID.mirror.aliyuncs.com] } EOF # 重新加载配置并重启Docker服务 sudo systemctl daemon-reload sudo systemctl restart docker重启后再拉取任何Docker镜像都会走阿里云的加速器了。方法二在docker-compose.yml中为每个服务单独指定镜像灵活但麻烦如果你不想动全局配置或者只想对Dify的镜像加速可以这样改以api服务为例api: # 将原来的 image: langgenius/dify-api:latest 替换为 image: 你的ID.mirror.aliyuncs.com/langgenius/dify-api:latest ...你需要对web、worker、postgres、redis服务都做同样的替换。显然方法一更省事。4.3 配置数据持久化防止数据丢失Docker容器本身是无状态的一旦删除里面的数据就没了。Dify的数据用户信息、应用配置、对话记录等都存储在PostgreSQL数据库里。在docker-compose.yml中默认已经通过volumes配置了数据卷挂载确保数据保存在宿主机上即使容器重建也不会丢失。默认配置如下volumes: pg_data: # 定义了一个名为 pg_data 的数据卷用于存放PostgreSQL数据 redis_data: # 定义了一个名为 redis_data 的数据卷用于存放Redis数据在dify-postgres服务中你会看到挂载配置- pg_data:/var/lib/postgresql/data。这意味着数据库文件实际存储在Docker管理的pg_data卷中。你可以通过docker volume inspect dify_pg_data查看它具体在宿主机的哪个路径。如果你想自定义数据存储路径比如一定要存到/home/data/dify目录下可以修改volumes部分volumes: pg_data: driver: local driver_opts: type: none device: /home/data/dify/postgres # 宿主机上的绝对路径 o: bind redis_data: driver: local driver_opts: type: none device: /home/data/dify/redis o: bind这样数据就会直接存储在你指定的目录下备份和管理起来更直观。记得要先创建好这些目录sudo mkdir -p /home/data/dify/postgres /home/data/dify/redis并确保Docker进程有读写权限。5. 一键启动与验证见证Dify运行配置调整完毕最激动人心的时刻到了——启动服务整个过程非常简单就一条命令。5.1 启动所有服务确保你的终端当前位于包含docker-compose.yml文件的目录即~/dify/dify/docker然后执行docker compose up -d这个命令中的-d参数代表“detached”意思是让服务在后台运行。执行后你会看到终端开始刷刷地输出日志Docker会依次拉取如果本地没有并启动postgres、redis、api、worker、web这五个容器。首次执行可能会花费5到15分钟主要时间花在拉取几个G的镜像文件上取决于你的网速。看到最后出现“done”或者类似提示并且没有明显的红色错误信息就说明启动命令执行完成了。5.2 检查服务状态启动命令完成不代表所有服务都健康运行了。我们需要检查一下各个容器的状态。docker compose ps这个命令会列出当前目录下docker-compose.yml定义的所有服务。你期望看到的输出应该是这样的NAME IMAGE COMMAND SERVICE STATUS PORTS dify-api langgenius/dify-api:latest /bin/bash /entrypo… api Up 2 minutes 0.0.0.0:8000-8000/tcp dify-web langgenius/dify-web:latest /docker-entrypoint.… web Up 2 minutes 0.0.0.0:80-80/tcp dify-worker langgenius/dify-worker:latest /bin/bash /entrypo… worker Up 2 minutes 8000/tcp dify-postgres postgres:15-alpine docker-entrypoint.s… postgres Up 2 minutes 5432/tcp dify-redis redis:7-alpine docker-entrypoint.s… redis Up 2 minutes 6379/tcp最关键的是STATUS这一列必须全部是Up状态后面可能跟一个时间如Up 2 minutes。如果某个服务是Exit或者不断重启那就说明有问题。5.3 验证部署结果服务状态都显示Up了我们通过实际访问来验证。访问前端页面打开你的浏览器在地址栏输入如果你在本地电脑部署http://localhost如果没改端口如果你改了Web端口为8080http://localhost:8080如果你在远程服务器部署http://你的服务器IP地址或http://你的服务器IP地址:端口如果一切顺利你应该能看到Dify的登录/注册界面。这说明前端服务Nginx和后端服务API之间的通信是正常的。初始化管理员账号在登录界面点击“注册”填写邮箱和密码。第一个成功注册的账号会自动成为系统管理员拥有所有管理权限。务必记住这个账号验证后端健康状态在浏览器或终端里访问后端健康检查接口。如果没改API端口http://localhost:8000/health如果改了API端口为8081http://localhost:8081/health你应该会看到一个简单的JSON响应{status: healthy}。这证明后端API服务运行良好。当你完成了以上三步恭喜你一个完整的Dify平台已经成功在你的机器上运行起来了。你可以用刚才注册的管理员账号登录开始探索Dify的世界了。6. 运维与排错让服务稳定运行部署成功只是第一步日常运维和遇到问题时如何排查同样重要。这里分享几个我最常用的命令和技巧。6.1 日常运维命令这些命令都需要在docker-compose.yml所在的目录~/dify/dify/docker下执行。# 查看所有服务的实时日志类似 tail -f docker compose logs -f # 只看某个服务的日志比如api docker compose logs -f api # 停止所有服务但保留数据卷 docker compose down # 停止所有服务并且**删除数据卷**危险这会清空所有数据包括数据库 docker compose down -v # 重启所有服务 docker compose restart # 重启单个服务比如worker docker compose restart worker # 更新服务比如修改了docker-compose.yml配置后 docker compose up -d --force-recreate6.2 常见问题与排查思路即使按照教程你也可能会遇到一些小问题。别慌按照以下思路排查基本都能解决。问题一端口冲突服务启动失败现象docker compose ps看到某个服务状态不是Updocker compose logs web看到类似bind: address already in use的错误。解决这就是我们前面讲过的修改docker-compose.yml中冲突服务的ports映射换一个宿主机上未被占用的端口。用sudo lsof -i:端口号或sudo netstat -tlnp | grep 端口号命令可以查看端口被谁占用。问题二镜像拉取失败或极慢现象docker compose up -d卡在Pulling阶段很久最后超时。解决确保已按照4.2节配置了Docker国内镜像加速器。配置后可以尝试先单独拉取最大的镜像docker pull langgenius/dify-api:latest。也可以使用docker compose pull命令预先拉取所有镜像。问题三服务启动后很快退出Exited现象docker compose ps显示服务状态为Exited (1)或不断重启。解决这是最需要查看日志的情况。使用docker compose logs 服务名例如docker compose logs api查看该服务的详细错误输出。常见原因有依赖的服务如PostgreSQL没启动好、环境变量配置错误、磁盘空间不足、内存不足等。根据日志中的错误信息去搜索通常能找到解决方案。问题四能访问登录页但注册或登录失败现象前端页面能打开但提交表单后报错或者一直转圈。解决首先检查后端API服务是否真的健康访问/health接口。然后查看api和worker服务的日志看是否有数据库连接错误、Redis连接错误或者第三方API调用错误。确保postgres和redis两个服务都是Up状态。6.3 后续步骤建议成功登录Dify后我建议你先做这几件事配置模型点击左下角“设置” - “模型供应商”添加你的大模型API密钥比如OpenAI的GPT、Anthropic的Claude或者国内的通义千问、文心一言等。这是让Dify“活”起来的关键一步。探索模板在“应用”页面Dify提供了一些现成的应用模板比如“翻译助手”、“小红书风格文案生成器”你可以直接复制一个来玩玩感受一下低代码开发的效率。数据备份虽然Docker卷已经做了持久化但定期备份pg_data卷的数据是个好习惯。你可以使用docker exec命令执行pg_dump来导出数据库或者直接备份整个数据卷目录。踩过几次坑之后我发现Docker Compose部署Dify最吸引人的地方就在于它的可复现性。一旦你的docker-compose.yml文件调校好了整个部署环境就可以像代码一样被版本管理。下次换机器或者团队新成员需要环境直接把这个文件给他一条docker compose up -d就能得到一个和你一模一样的环境这种体验对于开发和协作效率的提升是巨大的。好了现在你的Dify playground已经搭建完毕接下来就可以尽情地去创造你的第一个AI应用了。