Dify 这个项目，第一次听说的时候我还是持观望态度的。后来在社区里看到有人用它的工作流搭了一个知识库问答机器人，从提问到检索文档再到生成回答，全程没写多少代码，才意识到这东西的定位有多讨喜。它全名叫 Dify.AI，开源的大模型应用开发平台，适合我这种想把大模型落地到具体应用、又不想从头撸 Prompt 工程和 RAG 管道的普通人。1.17 版本虽然不算最新，但胜在稳定，工作流编辑、模型管理、知识库这些核心模块都到了一个比较完备的状态，做新手的起点非常合适。
这篇东西就是一篇实战记录，目标很明确：帮你用最小的成本把 Dify 1.17 跑起来，并把你大概率会踩的坑提前拆开。文章会覆盖环境准备、精简部署、模型接入（本地 Ollama 和云端 API 两种主流方案）、知识库与工作流的基础配置，以及一套可以直接照着操作的排查方法。不管你是第一次碰 Docker，还是已经折腾过几天，按这个顺序走下来，至少在部署这个环节不会再对着满屏错误日志发呆。
1. 部署前的准备功夫
1.1 先搞清楚 Dify 解决什么问题
Dify 能做什么，用一句话概括：把大模型从“能聊天”变成“能干活”。它把模型调用、Prompt 编排、知识库检索、Agent 工具调用、日志与运营分析这些组件全部收拢到一个可视化的管理界面里。你在界面上创建的应用，可以直接通过 API 暴露给外部系统，也可以嵌入网页当成一个小产品来用。
对新手来说，Dify 最大的价值是省掉了大量的工程化工作。如果你自己从零搭一个 RAG 服务，你得处理向量库选型、文档分段、Embedding 模型调用、检索排序、上下文组装、流式输出……这一套下来少说一两个星期。而 Dify 把这些全部封装成了开箱即用的功能，你只需要关注业务问题本身。
版本选择这块，我坚持推荐 1.17 而不是盲目追新，原因有三：第一，1.17 的工作流编辑器已经支持节点复制、单节点调试、分支逻辑，功能上完全够用；第二，这个版本的模型供应商适配非常全，主流的 OpenAI、DeepSeek、Ollama、MiniMax 都内置了；第三，社区里关于 1.17 的踩坑记录已经很多，遇到问题大概率搜得到答案。选一个被大家验证过的稳定版本开始，比追随最新版要理性得多。
1.2 硬件和软件环境，给个能直接抄的答案
先说我实测的配置。我自己用的是一台 4 核 8G 内存的云服务器，Ubuntu 22.04，跑 Dify 1.17 加上一个 7B 的量化模型，日常知识库问答体验尚可，但内存已经比较吃紧。如果你打算在本地用 Ollama 跑模型，建议内存至少 16G；如果只是接云端 API，8G 内存跑 Dify 本体是够的。磁盘方面，Dify 本身的镜像加起来大约占用 8G 到 10G，再加上文档数据、日志和向量索引，预留 20G 比较稳妥。
软件环境只需要两个核心组件：Docker Engine 和 Docker Compose 插件。Dify 1.17 的 compose 文件依赖 Docker Compose v2 语法，如果你服务器上还是老版的docker-compose，建议统一升级。另外提一句，Windows 用户部署 Dify 也不是不行，用 Docker Desktop 就能跑，我后面会用到一个关键配置差异（容器访问宿主机的地址），到时候再细说。
1.3 安装 Docker 环境，一条命令起步
如果你面对的是一台干净的 Ubuntu 服务器，安装 Docker 最省事的方式是：
curl -fsSL https://get.docker.com | bash -s docker这条命令会把 Docker Engine、CLI 和 Compose 插件一次装好。装完验证一下：
docker --version docker compose version两个命令都有输出，环境就绪。Windows 用户安装 Docker Desktop 后，记得在设置里确认使用的是 WSL2 后端；macOS 用户直接装 Docker Desktop 就行。
这里有一个新手经常忽略的细节：docker compose up和docker-compose up是两套不同版本的命令，前者是 Compose v2（推荐），后者是独立的 Python 工具。Dify 1.17 的部署文档默认使用前者。如果你在输入命令时报“compose 命令不存在”，大概率是没装插件，而不是 Dify 的问题。
2. 精简部署全流程实操
2.1 下载 Dify 1.17，拿到 docker 目录就够了
下载 Dify 1.17 的源码包，你不需要关心整个仓库的源码，只需要关注解压后的docker目录。这个目录里躺着三个关键东西：docker-compose.yaml（所有服务怎么编排）、.env.example（配置模板）、nginx子目录（反向代理和 HTTPS 配置）。如果你用 Git 拉取，可以指定版本分支：
git clone --branch 1.17.0 https://github.com/langgenius/dify.git cd dify/docker在 Windows 上下载源码包之后，解压到某个目录，进入dify-main/docker，在文件夹空白处按住 Shift 键点右键，选择“在终端中打开”，就能得到命令窗口。这里要注意路径不要带有中文或空格，否则后面部分工具处理起来容易出些莫名其妙的幺蛾子。
2.2 复制 .env 模板，修改关键参数
进入 docker 目录后，无论如何先执行这一条：
cp .env.example .env复制模板到.env之后，你可以用文本编辑器打开它看一下都配置了些什么。核心参数有下面几个：
EXPOSE_NGINX_PORT=80：Dify 的 Web 入口端口。服务器上 80 端口被占的话，改成8080或别的可用端口。EXPOSE_NGINX_SSL_PORT=443：HTTPS 入口端口，本地部署一般用不到，但端口冲突时也要留意。SECRET_KEY：默认是一个固定的开发用值。部署到服务器后，用openssl rand -base64 42生成一个新的替换它。DB_USERNAME/DB_PASSWORD：PostgreSQL 的连接账号密码。默认值其实也可以跑，但生产环境建议改掉。VECTOR_STORE=weaviate：向量数据库默认用 Weaviate，新手不用动。
我想特别强调一点，新手最容易犯的错误是打开.env看到一堆配置项就忍不住到处改。其实 Dify 官方默认配置是针对标准部署调好的，你只需要改那些明显和你的环境冲突的参数（比如端口），其他的一律别动。改得越多，排查问题的时候变量越多，自找麻烦。
2.3 启动服务，完成首次登录
配置好.env后，回到docker目录，执行：
docker compose up -d首次执行会拉取全部镜像。这个过程我建议耐心等，中间不要 Ctrl+C，也不要急着开另一个容器操作。拉完之后，运行：
docker compose ps你会看到一堆Up状态的容器，包括nginx、api、worker、web、db、redis、sandbox、ssrf_proxy、weaviate等。刚启动的前几十秒，api容器可能还在做数据库迁移，页面先打不开是正常的。等个十几秒，浏览器访问http://<服务器IP>:<EXPOSE_NGINX_PORT>，看到管理员创建页面就成功了。第一次登录后，记得把邮箱、密码这些信息记好，重置密码的流程虽然存在但没必要走一遍。
如果想看启动日志，用docker compose logs -f api跟踪 API 服务的输出，会出现Database migration之类的字样，等它跑完再刷新页面即可。
3. 把模型和知识库都接进来：从能跑到能用
3.1 本地模型接入：Ollama 的 Base URL 千万别写 localhost
部署完成只是第一步，接不上模型就等于白跑。对个人用户来说，最灵活的方式是接本地模型，Ollama 是这里面最省心的选择。先在宿主机安装 Ollama，拉一个你想要的模型：
ollama pull qwen2.5:7b然后进入 Dify 后台，路径是“设置”→“模型供应商”→“Ollama”。这里需要填写两个关键信息：
- Model Name：例如
qwen2.5:7b，要和ollama list输出完全一致。 - Base URL：这里 90% 的新手都踩过坑。如果你在 Dify 的 Docker 容器里填
http://localhost:11434，它访问的是容器自己的 11434 端口，而 Ollama 跑在宿主机上，必然连不上。正确写法是：Docker Desktop 用户填http://host.docker.internal:11434，Linux 服务器用户填http://172.17.0.1:11434或宿主机的局域网 IP。
提示：在 Dify 容器里访问宿主机服务时，
localhost指向的是容器自身，不是宿主机。这是模型连接失败最常见的根源。
填完点击“测试”，如果模型列表正常加载，说明连通了。还有一个前置条件：Ollama 默认只监听本机请求，跨容器或跨机器访问时需要设置环境变量OLLAMA_HOST=0.0.0.0，然后重启 Ollama，否则即使 Base URL 填对了也会被拒绝。
3.2 云端 API 接入：以 DeepSeek 为例的通用做法
接入云端模型的思路更简单。以 DeepSeek 为例，先在对应平台注册并申请 API Key，然后在 Dify 的“模型供应商”页面找到 DeepSeek，填入 Key，完成。Dify 对 OpenAI 兼容接口的适配做得已经很成熟，所以很多国产模型的接入本质是在做“填 Key、填 Base URL”两件事。如果你的模型供应商在 Dify 列表里没有直接出现，可以试试用“OpenAI-API-compatible”这类通用入口，手动填 Base URL，一样能接起来。
这里分享一个适配细节：不同模型的上下文长度差异很大。Dify 在模型设置里允许你配置上下文长度和最大 Token 数，如果你用的是长上下文模型，却保留了默认的短上下文参数，Dify 会在上下文组装时主动截断，导致回答丢失前面的关键信息。接完模型后，花一分钟检查这两个参数，能帮你省掉后面一大半“模型回答不完整”的困惑。
3.3 创建第一个应用、工作流和知识库
模型接通后，快速验证链路的方式是创建一个“聊天助手”类型的应用，选好模型，发一条消息试试。如果回复正常，恭喜，Dify 的核心链路已经通了。
接下来值得体验的是工作流。创建应用时选择“Chatflow”类型，会进入一个可视化画布。最简单的工作流就是三个节点：开始 → LLM → 结束。把 LLM 节点的模型选成刚才接好的模型，输入变量从开始节点传递过去，点击“运行”测试，观察节点输出。这里我特别想强调的是，Dify 的每个节点都支持单独调试，你在某个节点右上角就能看到输入输出的完整记录，这个能力对排查问题太重要了——不用猜，直接看数据。
知识库的接入同样门槛很低。创建一个数据集，上传文档，Dify 会自动完成分段和向量化。分段参数是后面影响检索效果的关键：段落太长，召回时会把不相关内容一起带回来；段落太短，上下文碎片化，模型像在看一段段无头无尾的文字。我处理中文技术文档时习惯把分段大小设在 500 到 800 个字符，重叠区域 50 到 100 字符，实际按文档类型微调。
4. 问题排查与避坑实录
4.1 容器反复重启：先看日志，再动配置
新手部署 Dify，遇到最多的就是“某个容器一直在重启”。遇到这种情况，我建议按下面的顺序排查：
docker compose ps docker compose logs api docker compose logs db先看哪个容器是Restarting状态，再去看它的日志。api容器日志里如果出现数据库连接错误，多半是db容器还没就绪或者数据库密码不匹配；解决方法是把全部容器停掉再重新起来，让依赖关系正常走一遍：
docker compose down docker compose up -d如果db容器自己也是Restarting，就要看它的日志。比较常见的是数据卷权限问题，和宿主机目录权限设置有关；如果排除了权限，可以备份数据后删除对应的卷重新初始化。注意，删除卷意味着清空已有数据，操作前想清楚是否接受这个代价。
4.2 端口冲突与页面访问异常
页面访问不了的另一个典型原因是端口冲突。Dify 的 Nginx 容器默认监听 80 和 443，如果你在服务器上已经跑着 Nginx 或其他 Web 服务，新容器怎么都起不来。用下面的命令查一下端口占用情况：
sudo lsof -i:80确认被占用后，去.env把EXPOSE_NGINX_PORT改成 8080，执行：
docker compose up -dCompose 检测到配置变化会重建容器。这里有个经验：改端口后如果页面还是访问不了，检查一下防火墙和云服务商的安全组规则，很多云服务器的 8080 端口默认是不放行的，需要在控制台里把端口加进白名单。
4.3 镜像拉取超时与升级时的坑
第一次拉镜像超时，基本是所有国内用户都会遇到的问题。常规解法是给 Docker 配置镜像加速器。修改/etc/docker/daemon.json，加入 registry-mirrors 配置项，然后重启 Docker 服务。如果某个镜像反复失败，可以单独拉取这个镜像，再重新启动 compose。
关于升级，我补充几个细节。Dify 升级的核心命令是：
docker compose down # 更新源码（git pull 或重新解压） cp .env.example .env docker compose pull docker compose up -d但这里有一个很容易踩的坑：直接覆盖.env会丢掉你之前改过的所有参数。正确操作是先备份旧.env，然后用新版模板和旧文件做对比，把新增的参数补进去，保留你已经自定义过的旧参数。升级数据库结构也需要时间，启动后建议观察api容器的日志，等迁移完成再访问页面。
4.4 常见错误速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 容器反复重启 | 端口冲突、依赖服务未就绪 | 查看日志，改端口或清理数据卷 |
| 页面无法访问 | Nginx 未启动、端口映射错误 | 确认EXPOSE_NGINX_PORT和防火墙规则 |
| API 日志提示数据库连接错误 | PostgreSQL 未就绪或密码不正确 | 检查 db 容器状态，核对.env配置 |
| Ollama 模型连接失败 | Base URL 写错、Ollama 未监听外部请求 | 容器内使用宿主机地址，设置OLLAMA_HOST=0.0.0.0 |
| 模型调用超时 | 模型加载慢、上下文过长 | 调整上下文长度，提升硬件配置 |
| 知识库检索为空 | 分段参数不当、向量化失败 | 调整分段大小，重新执行索引 |
| 登录后部分页面白屏 | Web 容器和 API 容器版本不一致 | 确保所有镜像版本一致，重建容器 |
5. 部署后的调优、备份与下一步
5.1 给容器加资源限制，防止一台机器被拖垮
Dify 默认的 compose 文件没有给容器设置资源上限，这在低配机器上是个隐患。几个容器同时跑起来，内存很容易被吃满，然后整个系统进入卡顿甚至 OOM 状态。建议在/etc/docker/daemon.json中设置 Docker 的总资源限制，或者在 compose 文件的对应服务下面加deploy.resources.limits配置。一个可以照抄的片段：
services: api: deploy: resources: limits: memory: 2G cpus: "1.5"给 API、Worker、Web 这三个服务都加上合理限制，其余服务按类似思路配置。这样即使某个容器出现内存泄漏，也不会把整台机器拖死。
5.2 数据备份与后续可以玩的方向
部署完成之后，千万别忘了备份的重要性。Dify 的数据主要存在 PostgreSQL、Redis、Weaviate（向量索引）这几个容器里，最简单粗暴的备份方式是定时docker compose down后打包整个 docker 目录。如果不想停机，可以用docker run挂载卷的方式直接复制数据目录。无论采用哪种方式，备份频率取决于你写入数据的频度，至少一周一次起步。
后续可玩的方向非常多，但是别想着一步到位。我现在用 Dify 的习惯是先把一个很小的应用场景跑通，比如让工作流里加一个知识库检索节点，再逐步加工具、加分支。踩过几次坑之后你会发现，部署只是第一步，把数据和业务逻辑梳理清楚才是工作中最花时间的部分。先把这版 1.17 跑稳，后面再考虑升级或者扩展，不迟。
