Dify + Docker Compose 30分钟部署大模型应用平台实战

先交代一下背景这个系列的第01篇我讲了 Dify 是什么、能用来做什么说到底就是一句话——它是一个把大模型应用开发的门槛从训练模型拉低到拖拉拽配置的开源智能体平台。这一篇直接进入实战目标只有一个从一台空机器开始30分钟内用 Docker 把 Dify 跑起来然后完成第一个能对话的 AI 应用。我为什么强调30分钟因为我踩过不少折腾环境的坑也帮不少人排查过部署问题凡是卡住的绝大多数不是 Dify 本身的问题而是 Docker 环境、镜像拉取、配置项这三个环节没捋顺。这篇文章会把这三块完整地过一遍把事前准备、部署过程、应用配置、问题排查全部摊开讲按步骤走你能在半小时左右看到自己的 AI 应用在线运行。这个操作适合谁两类人。一类是刚开始接触 Dify、想本地跑起来看看效果的开发者另一类是公司要私有化部署、想在内网搭一套 AI 应用平台的运维或全栈工程师。两类人都建议先把这篇跑通再去做工作流编排或者多租户改造这些进阶操作。1. 部署前必读Dify 到底解决什么问题这次部署要准备什么在敲命令之前我想先花点时间把为什么选择 Dify Docker这件事讲清楚因为你一旦理解了部署结构后面不管遇到什么报错都能自己判断问题出在哪一层。很多人部署失败恰恰是因为没搞清楚自己在部署什么。1.1 为什么用 Dify 而不是从零写调用链路想象一下如果你要从零做一个 AI 问答应用需要做什么先要有大模型 API 或本地模型服务然后你要写后端接口去调用模型、处理上下文、管理会话再做前端聊天界面还要考虑用户权限、日志、成本统计……这一套下来光接口对接就能写两周。更难搞的是需求变化很快——今天要用 DeepSeek明天想换通义千问后天用户说要上传文档让 AI 基于文档回答你又要去接向量数据库、做切片、做检索。Dify 把这些东西全部做成了开箱即用的模块。模型供应商对接、Prompt 编排、知识库、工作流、API 发布全都可视化操作底层代码不需要你写。本质上它就是一个大模型应用的操作系统。我用它搭过一个企业内部的知识问答机器人从配置到上线不到一天这在以前是不可想象的。这个平台是开源项目社区版功能已经完全够用部署方式最推荐的就是 Docker Compose。官方提供了编排好的容器组合一条命令把后端 API、Worker、Web 前端、PostgreSQL、Redis、向量数据库全部拉起来省去手动装依赖的各种麻烦。1.2 部署方式选型Docker Compose 为什么是最优选Dify 的部署方式目前有几种Docker Compose、HelmKubernetes、以及源码直接运行。源码直接运行要先配 Python 环境、Node.js 环境、装 PostgreSQL、Redis、Weaviate 等一堆依赖对新手极不友好我基本不推荐。Helm 部署是生产环境大规模集群才需要门槛更高。所以单机部署、体验试用、小型团队私有化Docker Compose 是绝对主流也是官方文档默认推荐的方式。Docker Compose 的核心价值在于环境一致性。它把每个组件封装成独立的镜像容器互相之间通过网络通信你不需要在自己机器上装 PostgreSQL、Redis 之类的软件所有依赖都隔离在容器里。换机器迁移时只需要把 docker-compose.yaml 和 .env 配置带上docker compose up -d一条命令就能恢复一套一模一样的环境。还有一点很重要Dify 官方维护了一个docker/docker-compose.yaml文件里面预置了所有中间件PostgreSQL、Redis、Weaviate、Sandbox 等和 Dify 本体服务api、worker、web并对版本号做了固定。这意味你拉到的是一套经过官方验证的全家桶各组件之间的兼容性已经测试过了不需要你自己去研究版本搭配。1.3 软硬件要求与前置环境清单部署 Dify 之前先检查一下你的机器是不是满足基本条件。根据官方文档和我的实测最低配置是 2 核 CPU、4GB 内存、50GB 磁盘空间。但说实话4GB 内存跑起来会很紧张因为 PostgreSQL、Redis、Weaviate 本身就吃内存再加上 API 服务和 Web 服务建议真实环境至少 8GB 内存。如果你同时还跑 Ollama 本地模型那 16GB 才算比较舒服。操作系统方面Windows、macOS、主流 Linux 发行版都可以依赖 Docker。需要强调的是Docker 版本不要太老尽量使用 Docker Engine 20.10 以上版本Compose V2 插件要装好。我用过的环境里Ubuntu 22.04 Docker Engine 24.x 最稳Windows 上用 Docker Desktop 也完全没问题就是内存占用偏高。还有一个很多人忽略的点Dify 默认会暴露 80 端口如果你的机器上已经有 Nginx、Apache 或其他服务占用了 80 端口部署前最好想清楚怎么处理。我自己的做法是直接把 Dify 的端口映射改掉用80:80改成8080:80这样避免冲突后面我会讲具体怎么改。2. Docker 环境准备先把最容易被卡住的关卡打通Dify 部署最大的门槛其实不在 Dify 本身而在 Docker 环境。我帮人排查过很多次十次里有七八次都是 Docker 没装好或者镜像拉不下来。所以这一章把 Docker 的安装、镜像加速、验证方法完整走一遍这个基础打好了后面就顺了。2.1 不同操作系统下的 Docker 安装要点Linux以 Ubuntu 为例不要用apt install docker.io装那种老版本建议用官方源装 Docker CE。装完之后把当前用户加入 docker 组避免每条命令都要 sudo。具体命令大概是先curl -fsSL https://get.docker.com | sh然后sudo usermod -aG docker $USER重新登录后执行docker version验证。Windows推荐安装 Docker Desktop安装时确保勾选 WSL 2 后端就是安装向导里的Use WSL 2 instead of Hyper-V选项。装完之后在 Settings → Resources → WSL Integration 里把你要用的发行版开关打开。Windows 上踩坑最多的是 Docker Desktop 启动失败常见原因是 WSL 2 没启用或者 BIOS 虚拟化没开可以先用wsl --status检查 WSL 内核状态。macOS同样是装 Docker Desktop。Intel 芯片和 Apple Silicon 芯片的安装包不同Apple Silicon 上跑 Dify 性能不错但注意有些镜像可能没有 arm64 版本Compose 时会自动用模拟运行或者报错Dify 全家桶对 ARM 支持目前还算可以实测 M 系列芯片跑得挺顺。2.2 镜像加速配置解决拉取慢的核心手段这一步我必须多说几句。Dify 全家桶要拉不少镜像PostgreSQL、Redis、Weaviate、Sandbox、API、Web 等加起来有好几个 GB。如果你直接使用 Docker Hub 官方源在国内拉取大概率会慢到让你怀疑人生甚至直接超时中断。这不是 Dify 的问题是网络链路的问题。解决办法是配置镜像加速器。国内主流云厂商都提供免费的容器镜像加速服务比如阿里云容器镜像服务、腾讯云加速器、中科大镜像等。以阿里云为例登录容器镜像服务控制台在镜像加速器页面能看到一个专属加速地址把 Docker 的 daemon.json 配好sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [https://你的专属加速地址.mirror.aliyuncs.com] } EOF sudo systemctl daemon-reload sudo systemctl restart dockerWindows 和 macOS 用户在 Docker Desktop 的 Settings → Docker Engine 里把 JSON 配置里的registry-mirrors加上Apply Restart 即可。配置完可以用docker info看看 Registry Mirrors 是否生效。这里有个细节有些加速器只加速 Docker Hub 官方镜像Dify 的镜像也在 Docker Hub 上所以加速器对 Dify 部署是有效的。2.3 验证 Docker 环境是否就绪装完 Docker不要急着部署 Dify先用两个简单命令确认环境没问题。第一个是docker version确认 Client 和 Server 都有输出Server 有输出说明守护进程跑起来了。第二个是docker compose version确认 Compose V2 安装了。如果提示 Command Not Found说明你只有 docker 命令没有 compose 插件需要单独安装。提示如果你用的是 CentOS 或某些精简系统装完 Docker 之后记得把 Docker 服务设置成开机自启sudo systemctl enable docker。不然机器重启后 Docker 没起来Dify 容器也全挂了。我第一次部署 Dify 时就是卡在 Docker 版本太旧Compose 文件里的某些语法不识别反复报错。换到新版本后一切顺利所以别省这一步。3. 30 分钟跑通 Dify完整部署实操环境搞定了现在进入正题。整个部署过程我会按时间线拆开每一步都有命令、有解释、有预期结果。你跟着敲就行不需要理解每一个参数的含义但我会告诉你每个命令是在干什么这样出问题的时候你知道去哪里查。3.1 获取 Dify 源码与配置文件准备Dify 的一键部署脚本在 GitHub 仓库里。你不需要 clone 整个项目只需要下载docker目录下的文件即可。用 Git 拉取指定目录比较麻烦最直接的方式是 clone 整个仓库但只使用其中的 docker 子目录git clone https://github.com/langgenius/dify.git cd dify/docker如果你网速不好也可以直接在 GitHub 网页上进入docker目录手动下载docker-compose.yaml、.env.example、volumes这些文件和文件夹。但手动下载容易漏文件我建议直接 clone 然后用完删除更省心。进入dify/docker目录后先把环境变量示例文件复制成真正的.envcp .env.example .env这个.env文件是 Dify 配置的核心所有端口、密钥、数据库连接都在这里。默认配置对单机部署完全够用不需要修改就能启动。3.2 关键配置项解读部署之前先看懂 .env虽然默认配置可以直接启动但有几个配置我建议你在第一次启动前就改好省得后面再重建容器。第一个是EXPOSE_NGINX_PORT默认值是 80也就是 Dify 的 Web 界面访问端口。如果你的机器 80 端口被占用改成EXPOSE_NGINX_PORT8080这样访问地址就是http://服务器IP:8080。第二个是SECRET_KEY这是用于加密会话和敏感信息的密钥。.env.example里给的是一个默认开发密钥生产环境一定要换成一个随机字符串。可以用openssl rand -hex 32生成一个然后填进去。第三个是POSTGRES_PASSWORD、REDIS_PASSWORD这类中间件密码。单机部署用默认的开发密码问题不大但如果你的机器有公网 IP建议改成强密码不然数据库裸奔在公网上风险很高。其他配置如向量数据库默认 Weaviate、存储类型默认本地存储在单机体验阶段都可以不动。改完.env后用docker compose config检查一下语法这个命令会把最终的组合配置打印出来如果有配置错误会直接报错。3.3 docker compose 启动与过程监控配置做好了启动就一条命令docker compose up -d-d参数是后台运行不加的话会前台输出日志你关掉终端容器就停了严格说不会马上停但会失去守护。第一次执行这个命令Docker 会开始拉取所有镜像这一步最耗时取决于你的网速和镜像加速配置一般在 5 到 15 分钟之间。拉取完成后docker compose 会自动创建网络、数据卷、启动容器。启动过程中可以查看运行状态docker compose ps正常状态应该是所有服务都是runningSTATUS 列显示Up或Up (healthy)。其中healthy表示健康检查通过。如果某个服务一直显示starting或restarting多半是配置有问题或者某个依赖没起来。可以查看指定服务的日志来确认docker compose logs -f api-f是跟踪日志输出api是 Dify 后端服务名。日志里出现Running on http://0.0.0.0:5001或者类似Application startup complete的提示说明后端起来了。等待所有服务健康之后访问http://你的服务器IP:端口默认 80如果你改过端口就用改过的。浏览器里应该能看到 Dify 的初始化页面一个大大的 Dify Logo 加一个创建管理员账号的表单。3.4 初始化安装与管理员账号配置这一步相当于 Dify 的安装向导它不像普通应用那样装完就完事而是引导你配置第一个管理员账户这个账户是平台的超级管理员。填写邮箱、用户名、密码点击创建即可。密码建议 8 位以上包含大小写字母和数字这个账号以后登录后台、管理成员、配置模型都要用。创建成功后系统会跳转到登录页用刚才设置的账号登录就正式进入 Dify 的工作台了。到这一步部署已经完成。从docker compose up -d到看到工作台顺利的话 20 分钟内搞定剩下的时间就是我们接下来要做的上线第一个 AI 应用。注意有一种情况是浏览器打开后显示空白页或者 502 Bad Gateway。通常这是因为 Web 容器还没完全就绪尤其是首次启动时前端构建需要时间。等一两分钟刷新就好不要急着重启容器。4. 5 步上线首个 AI 应用从空白到能对话Dify 平台部署好之后很多人反而会愣住——功能太多了不知道从哪下手。别慌我拆解出一个最小可行的路径只需要 5 步你就能上线一个真正可以对话的 AI 应用。这 5 步是创建应用、接入模型、编排提示词、调试预览、发布使用。4.1 第一步创建应用并选定类型登录 Dify 工作台后在应用页面点右上角的创建空白应用。这时候会有几个应用类型让你选聊天助手、Agent、文本生成、工作流等。第一次体验我建议选聊天助手。聊天助手是 Dify 里最基础的对话应用适合做客服问答、知识问答、角色扮演等场景。它的特点是用户发消息AI 回消息上下文由平台自动管理你不需要自己处理会话历史的逻辑。创建时填一个应用名称比如第一个 AI 应用然后进入应用编排界面。你可以放心选因为 Dify 的应用类型随时可以改后面熟悉了再尝试 Agent 或工作流。4.2 第二步接入大模型供应商DeepSeek / Ollama / 在线 API这一步是整个配置里最关键的。Dify 本身不带模型它需要接入大模型的 API 才能提供对话能力。你可以在设置 → 模型供应商里配置。目前 Dify 支持的供应商非常多包括 OpenAI、Anthropic、国内的通义千问、DeepSeek、智谱 GLM 等还支持 Ollama 这类本地模型工具。我的建议是分两类选择在线 API 方式配置简单效果稳定以 DeepSeek 为例去 DeepSeek 开放平台注册账号创建一个 API Key。然后在 Dify 的模型供应商页面找到 DeepSeek填上 API Key系统会自动获取模型列表。选中一个模型比如deepseek-chat测试连接成功后保存即可。本地模型方式数据不出内网零 API 费用如果你有 GPU 机器可以装 Ollama 并拉取一个开源模型比如 Qwen2.5 或者 Llama 3。然后到 Dify 的模型供应商里选择Ollama填上 Ollama 服务的地址比如http://宿主机IP:11434和模型名称。要注意的是如果 Dify 和 Ollama 不在同一台机器需要配置 Ollama 允许局域网访问OLLAMA_HOST0.0.0.0。配置完成后回到应用编排界面在右上角的模型下拉框里选择你刚接入的模型。实测下来DeepSeek 的deepseek-chat在 Dify 里响应速度很理想性价比也高本地模型受限于机器性能冷启动会慢一点但没有外部依赖。4.3 第三步编排提示词与人设模型接入后应用编排界面的左侧是提示词编排区域这里是你唯一需要写代码的地方——但放心你写的不是代码而是自然语言的指令。Dify 里叫 SYSTEM 提示词系统指令它决定了 AI 的角色定位、回答风格和行为边界。举个例子我想做一个产品知识问答助手提示词可以这么写你是一个专业的产品知识问答助手负责回答用户关于产品功能、价格、使用方法的提问。 回答要求 1. 简洁准确优先给出结论再补充说明。 2. 如果你不知道答案明确告诉用户这个问题需要转人工不要编造。 3. 回答使用中文语气专业友好。这个提示词虽然简单但真实场景下它的质量直接决定应用效果。我见过很多人部署完 Dify 不写提示词直接扔给用户用结果 AI 回答得又空又散。花几分钟认真设计提示词回报是肉眼可见的。Dify 还允许你在提示词里插入变量。比如你想让 AI 在回答时带上用户的名字可以在提示词里写用户名字{{name}}前端对话时 Dify 会弹窗收集这个变量这就是 Dify 的对话开场白和变量机制做个性化体验非常有用。4.4 第四步搭建知识库可选但非常推荐如果你做的应用需要基于特定文档回答问题比如企业规章制度、产品手册、课程资料那就需要用到知识库。Dify 的知识库本质上是一个 RAG检索增强生成系统你上传文档平台把文档切片成小块用嵌入模型Embedding转成向量存储用户提问时先检索最相关的片段再把片段和问题一起丢给大模型生成答案。在 Dify 顶部导航点知识库→创建知识库输入名称后上传文档。Dify 支持 PDF、Word、Markdown、TXT 等常见格式。上传后需要选择嵌入模型一般选你配置过的供应商提供的 Embedding 模型。如果没配置过嵌入模型系统会提示你先去模型供应商页面配置。这里有一个我踩过的坑切片大小严重影响回答质量。Dify 默认切片长度是 500 个 token这个值对一般文档够用但如果你上传的是技术手册句子之间逻辑关联性强切片太小会把上下文切断导致 AI 回答不准确。建议在数据集的分段设置里把分段长度调大一些比如 800 到 1000同时在分段重叠Overlap设置为 50 左右这样能保留上下文衔接。知识库创建好后回到应用编排界面在右上角的上下文区域关联你刚建的知识库这样对话时 AI 就会自动检索并基于文档内容回答。这一步做完你的应用就从通用聊天升级成专业问答了。4.5 第五步发布、调试与嵌入这一步是整个流程里最有成就感的一步。在应用编排界面点右上角的发布按钮你的应用就正式上线了。发布后可以在同一页面点运行或预览进行测试直接在右下角的对话框里问几个问题看看回复是否符合预期。测试没问题后Dify 给你提供了多种使用方式Web AppDify 会生成一个独立的聊天页面链接分享给别人就能用。嵌入网站复制一段 iframe 代码把 AI 助手嵌入到你自己的官网或后台系统。API 调用在访问 API页面为应用创建 API KeyDify 会生成标准的 RESTful API 文档你可以用任何编程语言调用这个应用的对话接口。我通常是先发布生成 Web App把链接发到团队群里让大家试用收集反馈之后再迭代提示词和知识库。Dify 的迭代不需要重新部署改完配置重新发布即可这一点对产品快速验证特别友好。5. 常见问题与排查技巧实录部署 Dify 过程中你会遇到各种奇奇怪怪的问题。这一章我把实践中最常遇到的坑整理出来配上排查思路和解决方案直接对照处理。如果你想跳过也要把 5.1 和 5.3 看完这两个问题命中率最高。5.1 镜像拉取慢或中断这是国内部署 Dify 遇到的最普遍的问题。现象是docker compose up -d执行后镜像下载进度条卡住不动或者过一会儿报错net/http: TLS handshake timeout或EOF。解决方案检查一下 2.2 节里的镜像加速器是否配置正确。配置了加速器还慢可以尝试更换加速器地址各家加速器在不同网络环境下速度差异很大。如果你是在云服务器上部署建议选择与服务器同地域的加速器。另外还可以给 Docker 配置 HTTP 代理如果你的网络环境用到了代理具体做法是在~/.docker/config.json里配置proxies。避坑提示不要反复按下 CtrlC 中断拉取Docker 会缓存已经拉取完成的镜像层中断后重新拉取会从断点继续但频繁中断可能产生脏缓存。实在拉不完优先检查网络而不是无限重试。5.2 容器启动后一直重启现象是docker compose ps里某个服务显示restarting最常出现在api、worker或weaviate这几个服务上。第一步先看日志docker compose logs 服务名。几个常见原因api 或 worker 报数据库连接错误说明 PostgreSQL 还没就绪Dify 的服务就尝试连接了。这种情况通常等一会儿会自动恢复因为 Compose 里有依赖检查和健康检查。如果持续报错检查.env里 POSTGRES 相关的配置。weaviate 报磁盘或权限错误通常是数据卷目录权限不对。可以执行docker compose down后删除volumes/weaviate目录再重新启动。注意删数据卷会导致已有向量数据丢失对刚部署的环境没影响。端口冲突导致容器无法绑定报错Address already in use说明宿主机端口被别的进程占用。改.env里的EXPOSE_NGINX_PORT或者其他端口映射解决。5.3 服务都起来了但浏览器打不开页面docker compose ps显示所有服务都 running但访问 IP 时浏览器转圈或者报错。这种情况我遇到过好几次最典型的两个原因原因一Web 容器仍在初始化。Web 前端是 Nginx 托管的静态页面首次启动时 API 地址要注入到前端配置里这个过程需要几秒到几十秒。等两分钟再刷新。原因二防火墙或安全组拦截。如果你的机器是云服务器即使 Docker 映射了 80 端口安全组没放行该端口外部也访问不了。去云控制台检查安全组规则把对应端口放行。如果是本地虚拟机检查宿主机防火墙Linux 的 ufw / firewalldWindows 的防火墙入站规则。还有一个容易被忽略的点如果你改了EXPOSE_NGINX_PORT浏览器访问时要带上新端口别只记得 IP忘了端口。5.4 应用能对话但回答质量差或报模型错误平台部署没问题应用也发布了但对话时模型报错或者回答很怪。分两类看报错类最常见的是Invalid API key或者Rate limit reached。检查你填入 Dify 的模型供应商 API Key 是否正确、余额是否充足、模型是否对你开放。DeepSeek、通义千问这类平台都需要实名认证后才能调用某些模型。质量类AI 答非所问、编造内容。多数是提示词设计不到位或者知识库没生效。检查三件事第一模型是否选了正确的那个第二知识库是否关联到了应用第三提问的内容在知识库里是否真的能找到。如果知识库检索效果不好试试调整 4.4 节里说的切片长度。5.5 升级到新版本与数据备份的经验Dify 社区迭代速度很快我基本每个月都会更新一次。更新操作其实很简单但千万做好备份。# 进入部署目录 cd dify/docker # 备份环境变量 cp .env .env.bak # 拉取最新代码 git pull origin main # 重新构建并启动 docker compose down docker compose pull docker compose up -d数据都存在 Docker 数据卷里volumes目录所以升级前最好把整个dify/docker/volumes目录复制一份出来万一升级出问题可以回滚。我自己的习惯是升级前执行docker compose down再执行git pull然后docker compose pull拉取新镜像最后docker compose up -d启动。升级后如果发现某些表结构变更导致 api 服务报错可以查看官方 Release Notes通常会说明是否需要执行数据迁移命令。提示升级前千万别嫌麻烦跳过docker compose down。我试过在容器运行状态下直接docker compose up -d虽然大部分情况下能自动重建但偶尔会出现容器网络残留导致服务状态异常。规范操作永远是先 down 再 up。最后分享一点我的个人体会这套流程我前前后后部署了不下十次从最开始的折腾半天到现在基本无脑执行。Dify 的部署难度真的不高大部分时间花在网络环境上而不是配置本身。如果你第一次部署就遇到镜像拉不动、端口冲突、页面打不开这些情况别怀疑自己先对着第 5 章逐个排查90% 的问题都能解决。跑通之后我建议你做的第一件事不是急着搭复杂应用而是先建一个知识库、写一个简单的提示词、发布一个聊天助手完整走一遍这个闭环。只有亲手完成过一遍你才对 Dify 的能力边界有真实的感知也才知道后续该往哪个方向深入——是做客服机器人、私有知识助手还是用工作流编排自动化的业务逻辑。这一篇到此动手试试吧。