Dify安装部署实战：Docker Compose环境准备到Ollama模型接入全指南-代码聚汇网

Dify安装部署实战：Docker Compose环境准备到Ollama模型接入全指南

楚雨馨·2026-09-06·阅读 22 GEO检测（免费）

DifyDocker ComposeOllama

|难度：普通|阅读约 30 分钟

1. 安装Dify前，先把这几个问题想清楚

动手装Dify之前，我建议你先别急着敲命令。Dify目前是全球使用量很大的开源LLM应用开发平台，把模型接入、知识库检索、工作流编排、Agent、API发布这些东西都整合在一个可视化的界面里。它的部署本质是一套Docker Compose编排的多容器应用，所以与其说是“安装Dify”，不如说是“在你自己的服务器或电脑上，把一套完整的大模型应用后端跑起来”。

我见过太多人卡在最开始的环境选择上，装了删、删了装，折腾几个小时最后还是起不来。核心原因就一个：Dify对机器配置和Docker环境有隐性的要求，文档里写得不痛不痒，但实际跑起来就差很多。

先说硬性配置。官方给的最低要求是2核4G，这个数字你听听就好——如果你不是在纯测试环境，而是真打算往里传文档、跑知识库、调工作流，8G内存是起步，16G才算舒服。我自己实测过，4G内存跑Dify 1.x版本，光PostgreSQL、Redis、Weaviate这三个基础组件就已经吃掉将近1.5G，再算上API服务和Worker进程，内存经常在90%以上顶着，系统会频繁触发OOM Killer，表现就是容器时不时崩一下，日志里出现Killed字样。

然后是操作系统。Dify官方最推荐的是Ubuntu 22.04这样的Linux服务器环境，原因很简单：Docker在Linux上的性能损耗最小，资源管理更透明，故障排查的思路也更干净。但如果你手里只有一台Windows电脑（尤其是不带WSL2的旧Windows 10），也不是不能装，只是要接受额外的网络层转发和文件系统I/O损耗。Windows本地部署Dify目前最靠谱的路径还是Docker Desktop配WSL2，装Hyper-V再加Linux镜像，整套下来比在Linux裸机上跑要多吃一截资源，启动速度也会慢一些。

最后是你对Docker的熟悉程度。Dify的安装本质上就是两个动作：拉镜像、起容器。但前提是你对Docker的基本概念有概念——镜像和容器的关系、端口映射是怎么回事、数据卷挂载到哪去了、日志去哪里看。如果你连docker ps和docker logs都还没用过，我建议你先花半小时把Docker的基础命令过一遍，再来动Dify。这不是装门槛，而是Dify一旦出问题，90%的排查动作都发生在这几个命令里。

另外一个很实际的问题：网络环境。Dify的镜像托管在Docker Hub和GitHub上，拉取镜像时如果速度极为缓慢，你会看到docker compose up进度条几乎不走。这不是Dify的问题，而是你的网络到境外节点的问题。解决办法有很多，区间从配置镜像加速器到改用代理都有，但具体怎么做我不展开——你只需要知道，如果首次启动花了超过半小时还在拉镜像，大概率是网络这块需要先处理，别傻等。

把上面这些都想清楚了，再往下走。安装本身不难，难的是在两个小时内别因为环境问题心态崩掉。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. Docker环境准备：最容易踩坑的环节往往在这里

Dify官方提供了两种安装方式：一种是Docker Compose一键部署，这是绝大多数场景下的首选；另一种是本地源码运行，适合要改代码、做二次开发的人。如果你是第一次接触Dify，或者只是想快速把平台用起来，老老实实走Docker Compose这一条路，不要想着源码跑，源码部署的坑比Docker部署多一个数量级。

在正式拉取Dify项目之前，先把Docker环境调到可用的状态。

2.1 Linux环境下的Docker安装核对清单

如果你用的是Ubuntu这类Linux发行版，先确认Docker和Docker Compose插件都装好了。用下面三组命令验证：

bash复制# 查看Docker版本与运行状态
docker --version
docker ps

# 查看Docker Compose版本（注意：新版Docker使用compose子命令）
docker compose version

docker ps能正常列出容器列表且不报权限错误，说明守护进程在跑。如果提示Cannot connect to the Docker daemon，先检查服务状态：

bash复制sudo systemctl status docker
sudo systemctl start docker
sudo systemctl enable docker

这里有一个新手高频失误：在Linux上直接跑docker ps遇到permission denied，就开始怀疑Docker装坏了。其实只是因为当前用户不在docker用户组里。解决办法是用sudo usermod -aG docker $USER把用户加进组，然后重新登录会话。

2.2 Windows用户的Docker Desktop注意事项

Windows下安装Dify，我实测最顺的路径是：安装Docker Desktop，然后在它的Settings里把WSL2作为后端。安装完Docker Desktop之后，有一件事必须单独确认——WSL2的内核更新包是否装好。很多Windows用户Docker Desktop能打开，但启动Linux容器时永远卡在Starting界面，十有八九就是这个内核包没装。

打开PowerShell执行wsl --status，能看到默认版本那一行。如果是V1，你需要执行wsl --set-default-version 2把它切到V2。

另一个Windows特有的问题：换行符。Git在Windows下默认会把克隆下来的文件里的LF换成CRLF，而这会破坏Dify的.env文件和docker-compose.yaml里某些配置的解析。为了避免这个坑，执行克隆命令前先设置一下：

bash复制git config --global core.autocrlf false

这行配置会让git保持仓库里原有的换行符不动，避免后面启动容器时出现莫名其妙的配置解析错误。别小看这个细节，我确实见过有人因为.env文件被Windows记事本改乱了，导致整个docker compose配置加载失败。

2.3 Docker镜像加速与拉取慢的问题

即使Docker装好了，拉镜像太慢依然会让你卡在第一步。Dify依赖的镜像包括langgenius/dify-api、langgenius/dify-web、postgres、redis、weaviate、nginx、sandbox等七八个，加起来体积在2-3GB左右。网络差的时候，docker compose up干拉镜像能拉一下午。

如果你遇到拉取速度问题，最直接的手段是配置镜像加速器。Docker Desktop可以直接在Settings -> Docker Engine里加registry-mirrors配置：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com"
  ]
}

Linux用户在/etc/docker/daemon.json里加同样内容，然后sudo systemctl restart docker。配好之后重新执行拉取，速度通常会有一个质的改善。但注意：镜像加速器不是永远可用，稳定性时常变化，如果某一天发现某家加速器失效了，换一个就行，多配几个也没什么坏处。

3. 用docker compose拉起Dify：完整安装步骤与参数说明

环境准备好之后，就是安装主流程了。用Docker Compose装Dify，一共就四步：下载项目代码、复制环境变量文件、改配置、启动。但每一步都有说头，我一个个拆开讲。

3.1 拉取Dify项目代码

bash复制git clone https://github.com/langgenius/dify.git

这个仓库是Dify的全量源码仓库，里面包含了api、web、docker等多个目录。我们真正用到的只有docker子目录，其他源码不用管。

bash复制cd dify/docker

如果你不想拉全量源码，也可以直接只拉docker目录里的编排文件，但那样需要手动创建目录结构，不如clone一把梭。执行完之后，docker目录下应该能看到docker-compose.yaml、.env.example、ssrf_proxy、nginx这些文件或目录。

3.2 生成.env环境变量文件

bash复制cp .env.example .env

docker compose读取的配置极多，Dify全部塞在.env里。默认值大部分能直接用，但有几个你必须根据自己的情况改：

配置项	默认值	说明
`EXPOSE_NGINX_PORT`	80	Dify Web界面的访问端口，80被占用时改这个
`EXPOSE_NGINX_SSL_PORT`	443	HTTPS监听端口，本地跑可以不动
`POSTGRES_PASSWORD`	difyai123456	数据库密码，建议改成强密码
`SECRET_KEY`	随机值	用于数据加密，生产环境必须改

如果你用的是macOS上基于Apple Silicon芯片的机器，Dify默认镜像里的sandbox容器可能起不来——这个问题在下文“启动失败排查”部分细说，但如果你提前知道，可以避免一次panic。Apple Silicon用户需要去.env里检查有没有相关的架构适配项，或者直接关注dify的release notes，不要自己手动改镜像架构，容易把整个编排搞坏。

3.3 启动所有容器

目录里执行：

bash复制docker compose up -d

-d参数是后台运行，意思是启动完不会霸占你的终端。首次执行会先拉镜像再起容器，取决于网络，这个过程可能从几分钟到几十分钟不等。执行完毕后再加一个参数验证容器状态：

bash复制docker compose ps

正常状态下，你会看到api、worker、web、db、redis、weaviate、sandbox、ssrf_proxy、nginx这九个容器全部处于running（或healthy）状态。

3.4 访问初始化页面

容器全部起来之后，打开浏览器访问：

code复制http://localhost/install

如果你是改过EXPOSE_NGINX_PORT，那就是：

code复制http://localhost:你改的端口/install

在初始化页面里设置管理员邮箱和密码，设置完成后会自动跳到登录页。到了这一步，Dify的核心安装其实已经结束了。后面要做的是把模型接进来，这个放到第五节详细说。

但我还是得提醒你一句：docker compose ps显示全部running，不代表Dify真的就能用了。容器起来了和整套系统健康运行之间，还需要跨过几个暗坑。

4. 启动日志里的门道：服务卡住的常见原因与处理记录

这一节我打算把启动失败和“假启动”的情况穿成一条线来讲。Dify是一个多容器的编排系统，启动失败的原因千奇百怪，但认真排查下来，大部分逃不出下面这几类。

4.1 web容器与nginx端口冲突

启动后访问页面发现压根打不开，或者是打开了但页面白屏报502，第一个要查的就是web容器和nginx容器的状态。Dify的架构是：nginx作为总入口，收到请求后转发给web前端容器（对应浏览器渲染的Vue应用）和api后端容器（对应接口服务）。

如果你的机器上80端口已经被其他应用占了（常见的是Apache、Nginx，或者微软的IIS），Dify的nginx容器就会因端口绑定失败而无限重启。排查命令：

bash复制docker compose logs nginx

如果日志里有bind: address already in use字样，那就是端口冲突。去.env里改EXPOSE_NGINX_PORT为一个空闲端口，然后重新执行：

bash复制docker compose up -d

注意改端口之后，之前那个容器需要重建而不是重启。如果你只是docker compose restart，新端口不会生效。需要执行：

bash复制docker compose down
docker compose up -d

4.2 api容器一直重启，问题多半在数据库迁移

如果docker compose ps显示api容器反复进出Restarting状态，大概率是数据库还没初始化完成。Dify的数据模型不是容器启动时自动建好的，而是通过一条迁移命令来完成。在合适的时机（通常是首次启动完成后），你需要在api容器内执行：

bash复制docker compose exec api flask db upgrade

注意：在容器刚初始化、PostgreSQL还没就绪的时候，执行这条命令可能会报connection refused。但首次正常启动流程下，db容器起来之后Dify会自动做迁移。如果你看到api容器日志里滚动刷relation "xxxxx" does not exist之类的报错，那就是迁移没有正常执行。手动补执行一次flask db upgrade基本都能解决。

4.3 Worker与API服务的角色差异

很多第一次接触Dify的人，看到docker compose ps里有一个叫worker的容器，会下意识以为它是多余的，或者干脆把它和api容器混为一谈。这是Dify架构里一个非常关键的设计：API容器负责接收用户的HTTP请求，实时处理对话、工作流运行这类同步操作；而Worker容器则专门跑异步任务——知识库的文档切分与向量化、批量任务的执行、Agent的长时间运行都挂在Worker上。

如果你用Dify只是简单聊聊天，Worker挂掉你可能暂时没感觉；但当你开始建知识库、传文档，会突然发现文档状态一直是“处理中”或者“待索引”，这时候不用问别人，先去查Worker容器：

bash复制docker compose logs worker -f

看到没有持续报错，再确认它内存占用是否异常。Worker处理大批量文档时非常吃内存，OOM杀进程是常见现象。

4.4 一个容易忽略的“假启动”：硬盘空间不够

Dify跑起来之后，PostgreSQL和Weaviate都会持续写入数据，尤其是使用知识库场景时，向量数据会快速增长。很多人的服务器硬盘只有40G，系统本身占掉20G，镜像占掉10G，再塞点文档，硬盘很快就满了。Dify的容器不会因为你硬盘满自动挂掉，但表现非常诡异——页面能打开、添加模型也没问题，但一传文档就报错，或者知识库索引永远在排队。

遇到这种症状，先检查磁盘：

bash复制df -h

如果使用率超过90%，先清理不需要的镜像和容器日志：

bash复制docker system prune -a

做完整清理后重启Dify，问题往往就消失了。这类问题之所以难排查，是因为它的表象千奇百怪，但根源就一个——没硬盘了。

4.5 排查故障的固定检查顺序

把这一节总结成一个排查路径，方便你以后遇到问题直接按顺序走：

docker compose ps确认所有容器状态，找出哪些是Restarting或Exited。
对异常容器使用docker compose logs <容器名>看最近日志，优先找error、fatal、panic关键字。
df -h和free -h分别确认磁盘和内存是否充足。
如果Web能打开但接口报错，检查Nginx转发配置与api容器存活状态。
如果某容器反复重启，用docker inspect <容器名>看退出码和重启策略。

这个顺序我用了很久，能解决Dify起步阶段绝大部分问题。关键是不要一上来就瞎改配置，先通过日志明确症状，再决定动哪里。

5. 启动完成之后：模型接入与基础配置

Dify跑起来只是第一步，没有可用的模型，它本质上就是个空壳。Dify支持的模型来源极多：OpenAI、Anthropic、Azure OpenAI、Google Gemini、Ollama、Xinference，以及各类国产模型平台。模型接入的逻辑是统一的：在“设置 -> 模型供应商”里找到对应的供应商，填入API Key或者自定义配置。

对没有付费API Key、又想完整体验Dify功能的用户，目前最友好的路径是接Ollama本地模型。这也是搜索热词里“dify ollama本地设置方法”这么高频的原因。这里完整演示一遍。

5.1 先在Ollama侧准备好模型

假设你已经装了Ollama，并且已经拉好了一个模型。以qwen2.5:7b为例：

bash复制ollama pull qwen2.5:7b

拉完之后确认模型在本地列表里：

bash复制ollama list

然后把Ollama的服务监听地址改一改。默认情况下Ollama只监听127.0.0.1:11434，这意味着只有本机能访问。但Dify的api容器运行在Docker网络里，它访问宿主机时走的是网关地址而不是localhost，所以你需要让Ollama监听所有网卡。在Linux（systemd环境下）编辑Ollama服务配置：

bash复制sudo systemctl edit ollama

写入：

code复制[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

Windows下则是在Ollama的环境变量里设置OLLAMA_HOST=0.0.0.0:11434，然后重启Ollama。

5.2 在Dify平台里配置Ollama

登录Dify后台，进入“设置 -> 模型供应商 -> Ollama”，填写三样东西：

模型名称：填qwen2.5:7b，和你ollama list里看到的名字完全一致，少个冒号或者多一个tag都不行。
API Base URL：这里是最容易出错的。一定不能用http://localhost:11434。因为Dify的api容器是一个独立的容器，它内部访问不到宿主机的localhost。正确写法是http://宿主机IP:11434，例如http://192.168.1.100:11434。
模型类型：视你的用途勾选，对话用选“LLM”，要接入Embedding就选“Text Embedding”。

填完之后点击“保存”，Dify会向Ollama发一条测试请求。如果返回结果正常，说明模型已经接入成功。这里再补一个我在实践中常见的问题：Dify设置里能保存成功，但对话时一直报Connection error。这种情况基本还是在Ollama地址上——请回到宿主机上手动测试：

bash复制curl http://127.0.0.1:11434/api/tags

能返回JSON数据，说明Ollama正常；再curl http://192.168.x.x:11434/api/tags（换成实际局域网IP）看是否也能通。如果第二条curl失败，那就回到Ollama的监听配置。

5.3 选择哪类模型配合Dify体验最佳

我个人的建议是：如果你只是学习Dify功能，对话模型选7B-14B参数量级别的量化版（q4_K_M或q5_K_M）即可；如果机器配置有限，3B小模型也能跑，响应速度快但智商上限比较低。中文场景下，Qwen2.5系列、GLM系列都是不错选择。

如果做知识库，则还需要在Ollama拉一个Embedding模型（比如nomic-embed-text等），然后到Dify的“知识库 -> 嵌入模型”里选Ollama作为嵌入供应商。知识库的向量化工作由Worker容器负责，所以前面提的Worker务必要保持健康。

5.4 初始化配置的取舍

Dify还有几处新手容易忽略的配置，我在实际部署中用的策略是：

安全设置：.env里的SECRET_KEY、数据库密码、FLASK_SECRET_KEY全部改掉。本地学习可以不改，但如果服务器暴露在公网，不改就等于裸奔。
HTTPS：本地测试完全不用管SSL证书，nginx会以HTTP模式工作。公网部署再折腾HTTPS，第一步只用http://IP:端口访问即可。
邮箱：Dify注册流程默认关闭。如果你不需要对外开放注册，保持默认就好，不用配置SMTP。
多租户：Dify社区版从1.10开始支持多租户，如果同一个人需要分别管理多个独立工作空间，可以在初始化设置或用户管理里创建新的工作空间。

启动完成后，我建议你至少做一轮冒烟测试：新建一个空白应用，选一个对话型应用类型，绑定刚接入的模型，发一条消息看是否正常回复。然后上传一份PDF到知识库里，看Worker能否顺利切分并完成向量化。这两步走通，说明从Web、API、Worker到模型链路全是通的，Dify算是真正被“启动”成功了。

最后分享一个我的个人经验：Dify安装这件事，最忌讳的就是一边看教程一边焦虑，装到一半遇到个小问题就想卸载重来。实际上绝大多数问题都是一次性的环境问题，只要配置正确、Docker环境正常，docker compose up -d这条命令本身是极其稳定的。把这一套流程完整走一遍之后，你会发现最耽误时间的部分不是启动，而是理解“这个平台到底该拿来做点什么”。而等你开始编排第一个工作流、把文档丢进知识库、让Agent跑起多轮工具调用的时候，你才会真正意识到前面花在安装上的时间，值了。