去年年底我帮一个做电商运营的朋友搭知识库问答，他自己折腾了一个礼拜，光 Python 环境就坏了好几次，最后找我远程一看，问题全出在依赖冲突和系统环境上。后来我直接给他换成了 Dify 社区版加 Docker Compose 的部署方式，从拉代码到上线第一个应用，前后不到半小时，他当场就愣住了。这篇文章就是要把这套流程完整拆开，让你也体验一把"30 分钟跑通 Dify"的感觉。
Dify 是个开源的大语言模型应用开发平台，简单说就是给你一个可视化的操作界面，不用从零写代码就能把模型对接、提示词编排、知识库管理、工作流设计这些活儿全都接住。而 Docker 则是把 Dify 以及它依赖的数据库、缓存、网关等组件打包成独立容器，一条命令就能全部启动，省去了手工装 Redis、装 PostgreSQL、配 Nginx 的漫长过程。无论你是刚接触 AI 应用开发的新手，还是想快速搭一套内部工具的团队，这篇实战记录都值得花半小时照着走一遍。
1. 部署之前，先想明白这套组合到底帮你省了什么
1.1 Dify 能做什么，为什么我从源码部署转投 Docker
先说个反直觉的事：Dify 本身并不产生模型能力，它做的是"模型和应用之间的胶水层"。你在它里面配好 OpenAI、DeepSeek、通义千问这类模型的 API Key，就能通过可视化界面创建聊天助手、文本生成应用、Agent 智能体，甚至把知识库文档丢进去做检索增强生成（RAG）。这就把"模型调用 + 应用逻辑 + 用户界面"串成了一个完整的闭环。
早期我用 Dify 都是在宿主机上直接跑源码，Python 虚拟环境、npm 构建、Redis 版本冲突、PostgreSQL 初始化脚本报错，每一关都可能折腾半天。后来切到 Docker 部署，我才意识到容器化最大的价值不是"快"，而是"可预期"——所有依赖都被锁在镜像里，同一套配置在任何机器上表现一致。你今天部署成功，三个月后重新部署，流程一模一样，不会因为系统更新导致莫名其妙的失败。
1.2 Docker 部署方式对比源码部署的取舍
如果你在网上搜 Dify 部署，会看到官方文档同时提供了源码部署和 Docker Compose 部署两条路线。我个人的建议非常明确：除非你要深度修改 Dify 后端源码并且对容器技术极度反感，否则一律选 Docker Compose。
| 对比维度 | Docker Compose 部署 | 源码部署 |
|---|---|---|
| 环境依赖 | 仅需 Docker 与 Compose 插件 | Python、Node.js、PostgreSQL、Redis、Nginx 全套 |
| 启动速度 | 拉取镜像后一条命令启动 | 需要逐项初始化、编译前端资源 |
| 升级方式 | 拉新镜像重启容器 | 手动更新代码、迁移数据库、重新构建 |
| 隔离性 | 容器隔离，互不干扰 | 与宿主机共享资源，依赖易冲突 |
| 排障成本 | 日志集中，容器状态清晰 | 需要逐进程排查 |
这不是说源码部署一无是处，而是对绝大多数场景来说，Docker 版本的开箱体验远胜于"从零手搓"。尤其是 Dify 依赖的组件有七八个，手工编排服务的启动顺序非常容易出错。
1.3 硬件和账号准备：30 分钟内能不能跑通，八成看这里
别一上来就复制部署命令，先检查三件事。
第一是 Docker 环境。Windows 用户安装 Docker Desktop 并开启 WSL2 后端，macOS 用户同样装 Docker Desktop，Linux 用户装 Docker Engine 即可。装完后务必确认 Docker Compose 插件版本在 v2 以上，因为 Dify 的部署脚本直接使用docker compose子命令而不是老旧的docker-compose。检查命令：
docker --version docker compose version第二是资源配额。Dify 全家桶包括 API 服务、Worker 异步任务、Nginx 网关、PostgreSQL 数据库、Redis 缓存、Sandbox 沙箱执行环境和 SSRF 代理，加起来内存占用在 2GB 到 4GB 之间。所以你的宿主机至少要有 4GB 可用内存，低于这个数会出现容器反复重启或者数据库初始化失败的情况。我刚部署那台 2GB 的测试机，就是卡在 PostgreSQL 启动上，换到 8GB 的机器后一次通过。
第三是模型 API Key。Dify 只是一个平台，最终回答问题的是大模型。你至少需要一个模型供应商的 API Key，比如 DeepSeek、OpenAI、通义千问、智谱等，也可以先不填，等应用建好后再补。这一步容易被忽略，但没 Key 就相当于买了车没加油，平台跑起来了应用却用不了。
2. 五步部署实操：从拉取仓库到服务全部就绪
2.1 第1步：拉取 Dify 官方仓库与目录结构
部署的第一步不是写配置文件，而是拿到官方的 Docker 编排文件。Dify 的源码托管在 GitHub 上，部署文件集中在docker目录下。你不需要克隆整个项目的完整历史记录，直接浅克隆即可，节省时间：
git clone --depth 1 https://github.com/langgenius/dify.git cd dify/docker克隆完成后，你会看到这个目录下有几个关键文件。.env.example是所有环境变量的模板，docker-compose.yaml定义了所有服务的编排关系，volumes目录挂载点会在启动时自动创建，用于持久化存储。如果你之前部署过旧版本，升级时务必用新的配置覆盖旧的，不要图省事混合使用。
2.2 第2步：配置 .env 环境文件，关键是密钥和端口
Dify 会将大多数配置项以环境变量的方式注入容器，因此你需要复制一份环境变量文件：
cp .env.example .env打开.env文件后，有几个必须确认的配置项。最重要的是SECRET_KEY，它用于加密会话和敏感数据，官方示例里是空值，你需要手动生成一串随机字符串。我一般用 OpenSSL 生成：
openssl rand -base64 42然后把输出填入SECRET_KEY。另外检查EXPOSE_NGINX_PORT和EXPOSE_NGINX_SSL_PORT，默认分别是 80 和 443，如果宿主机 80 端口已被占用，改为 8080 或者其他端口即可，后面访问地址也要跟着变。如果你使用外部已有的 PostgreSQL 或 Redis，可以在此处指向外部地址，但我不建议在首次部署时做这种优化，默认的内部实例最省心。
2.3 第3步：用 docker compose 一键启动全部依赖服务
环境文件配置好之后，到了整套流程中最关键的一步。在docker目录下执行：
docker compose up -d这条命令会自动检查本地是否已有需要的镜像，没有就拉取，然后按照依赖关系依次启动容器。Dify 默认会启动api、worker、web、db、redis、nginx、ssrf_proxy、sandbox这组服务。我第一次执行时看到屏幕上一行行 Pull complete 飘过，心里还挺没底的，担心某个镜像拉取失败导致全盘白搭。
启动完成后，用docker compose ps查看所有容器状态。正常情况下所有服务都应该是Up或者显示healthy。如果某个容器状态是Restarting，不要慌，用docker compose logs查日志定位原因，后面我会单独讲高频问题。
2.4 第4步：通过浏览器完成管理员账号初始化
等服务状态稳定后，打开浏览器访问http://localhost。如果你修改了EXPOSE_NGINX_PORT，就用http://localhost:对应端口。首次访问会跳转到初始化页面，这里要设置管理员邮箱和密码。
设置管理员账号是你部署成功后做的第一件正经事，密码强度建议至少 8 位并包含大小写字母和数字。提交后系统会自动初始化数据库表结构，这个过程通常几秒到十几秒。初始化完成后跳转到登录页，用刚才的账号登录，你就正式进入了 Dify 的控制台。
有个细节我踩过坑：如果你访问时页面一直转圈或者提示 502，先别怀疑初始化，先检查 Nginx 容器是否起来了。很多时候是镜像没拉完就打开页面，等一分钟刷新就好。
2.5 第5步：登录后的基础配置与版本确认
登录 Dify 控制台后，第一件事不是急着创建应用，而是确认系统跑在预期版本上。右上角点击头像查看"关于"，确认版本号。Dify 的社区版迭代很快，有时候你部署的是几个月前的版本，而界面早已改版，后续照着教程操作可能会对不上号。
接下来进入"设置"，找到"模型供应商"。在这里添加你的模型 API Key，比如 DeepSeek 的 API Key，填入后会显示"已授权"状态。这一步完成后，你的 Dify 环境才算真正具备了对话能力。到这里，整个部署流程已经走完，耗时通常取决于镜像拉取速度，一般 10 到 30 分钟。
3. 从空平台到首个 AI 应用的完整创建路线
3.1 建应用前先选对模型供应商
很多新手卡在"模型供应商"这一步：进了设置页看到几十个模型厂商，不知道选谁。我的建议是优先选你已经持有 API Key 的服务商。如果你手里一个 Key 都没有，可以先去注册 DeepSeek、通义千问或者智谱的开放平台，它们都有免费额度，用来学习和验证完全够用。
在模型供应商页面填入 API Key 后，Dify 会调用模型列表接口，把该供应商支持的所有模型同步进来。有一点需要注意：不同模型擅长的事差别很大。纯聊天问答，DeepSeek 这类通用对话模型就够；做知识库召回后的归纳总结，要选上下文窗口大、指令跟随能力强的模型。如果你是第一次创建应用，选默认的对话模型即可，等应用跑起来后再慢慢调。
3.2 创建聊天助手应用，关键配置拆解
进入应用页面，点击"创建应用"，选择"聊天助手"类型，输入应用名称后确认。Dify 会生成一个可视化的编排界面，左侧是提示词编辑区，右侧是预览对话区。此时即便你什么都不改，直接点击预览并输入"你好"，模型也能正常回复——前提是刚才的模型供应商已经配置好。
真正决定应用质量的，是提示词。我见过太多人把提示词写成一段简单的指令就完事，结果应用回答生硬、不贴场景。一个合格的聊天助手提示词至少要包含三部分：角色定位、任务说明、输出约束。举个例子，你要做一个"产品文案助手"，提示词可以这样写：
你是一名资深电商产品文案专家。请根据用户提供的产品名称和卖点，生成一段面向目标消费者的种草文案。要求语气亲切、突出卖点、包含行动号召，全文控制在120字以内。把这段提示词填进去，再对比一下没填提示词时的回答，你会直观感受到差距。Dify 左侧还能开启"对话开场白"功能，让应用主动引导用户输入。这些配置完成后，右侧预览区已经可以像微信聊天一样交互了。
3.3 发布与嵌入：让应用从调试环境走进真实世界
应用在编排界面里能用，只代表调试通过。要分享给别人使用，还需要点击右上角的"发布"按钮。Dify 提供了两种发布方式：发布为 Web App 或通过 API 调用。
Web App 模式会生成一个独立的访问链接，任何有链接的人都可以直接在浏览器里跟你的应用对话。这种方式最适合做产品原型演示或者内部工具，不需要任何开发成本。另一种方式是"访问 API"，Dify 会为你的应用生成专属的 API 密钥，并给出接口文档，你可以用标准的 HTTP 请求调用它，把应用嵌入到自己的网站、公众号或企业微信机器人里。
我在给朋友搭建客服问答时，就是先在 Dify 上调试好提示词和知识库，再通过 API 接口接到企业微信机器人上，整个过程完全不需要自己写大模型调用代码。
4. 实测中绕不开的四个高频问题与排查链路
4.1 Nginx 端口被占用导致服务起不来
新人在部署时最常遇到的错误是端口冲突。如果你本机已经跑了 Apache、Nginx 或者其他占用 80 端口的服务，docker compose up -d启动后 Nginx 容器会无限重启，日志里报Bind for 0.0.0.0:80 failed: port is already allocated。
解决方式很简单：修改.env文件里的EXPOSE_NGINX_PORT=8080，然后重新执行docker compose up -d。注意只是改.env不够，还要让 Compose 重新加载配置，我会顺手执行docker compose down && docker compose up -d，确保环境变量的变更生效。
4.2 Docker 镜像拉取慢导致部署超时
镜像拉取速度是部署流程里最不可控的因素。特别是初次部署需要拉取十几个镜像，如果网络状态不佳，一个镜像卡住几分钟，30 分钟的目标就泡汤了。这时候最有效的办法是为 Docker 配置镜像加速器。
国内用户可以在 Docker Desktop 的 Settings -> Docker Engine 里添加 registry-mirrors 配置，也可以用可信的公共镜像加速地址。添加后点击 Apply & Restart，再重新拉取镜像，速度会有明显提升。配置完以后我建议先执行docker compose pull把所有镜像一次性拉完，再执行docker compose up -d启动，这样能避免启动过程中卡在拉取环节。
4.3 应用创建后提示模型不可用或未授权
这种问题跟 Dify 本身没关系，90% 是模型供应商配置没生效。你在"设置"里填入了 API Key，显示授权成功，但创建应用时模型列表里却找不到对应模型，这通常是因为模型供应商页面下方需要勾选"可用模型"。
另一种情况是 API Key 余额不足或者触发了限流。这个排查起来最简单：把同样的 Key 拿到模型服务商的官网调试页面试试，如果官网也报错，就是 Key 或额度问题；如果官网正常但 Dify 报错，再检查 Dify 的api容器日志：
docker compose logs api --tail=100日志里会明确写出模型服务返回的 HTTP 状态码和错误信息，照着提示去改配置基本都能解决。
4.4 升级 Dify 时数据不丢失的几个操作习惯
Dify 社区版迭代非常勤快，有时候一个月就有好几个版本。每次升级我都是这么操作的：先备份docker目录下的volumes文件夹，再备份.env文件，然后拉取最新代码并覆盖docker-compose.yaml，最后执行docker compose down && docker compose pull && docker compose up -d。
有朋友问过能不能只跑docker compose pull && docker compose up -d完成升级。理论上可以，但如果在跨大版本升级时，数据库迁移逻辑有变化，旧的容器没清理干净容易出怪问题。所以多花十几秒执行一次down再重新up，更稳妥。升级后记得进 Web 界面确认知识库和应用的配置都还在，再继续使用。
5. 下一步：从"能跑"到"好用"的三条进阶路线
5.1 接入本地模型，实现数据不出内网
用云服务 API 虽然方便，但有些场景要求数据完全内网化，比如企业内部文档问答。这时候可以在同一台机器上部署 Ollama，然后下载开源模型，让 Dify 直接通过 Ollama 连接本地模型。
具体操作是先在宿主机安装 Ollama，拉取一个模型，比如 qwen2.5 或者 llama3，然后进入 Dify 模型供应商页面，找到 Ollama 供应商并填写服务地址。需要注意如果 Ollama 和 Dify 都在 Docker 里跑，填写的地址不能是localhost，而要用宿主机在 Docker 网络中的网关地址。这一步我第一次配置时也纠结了一阵，后来测试通了才发现就是这么个小细节。
5.2 用工作流把单模型升级为多节点协作
当你不再满足于"一问一答"时，就该研究 Dify 的工作流了。工作流允许你用拖拽节点的方式编排复杂的应用逻辑：比如先做意图识别，再根据识别结果调用不同的模型或工具，最后做结果格式化输出。我在做 RAG 知识库问答时，工作流里就是"知识检索"和"大模型"两个节点串联，前者负责从知识库中找出相关片段，后者负责组织回答语言。
学习工作流最好的方式是打开 Dify 内置的模板。创建应用时选择"工作流"类型，平台会提供多个官方模板，你可以直接基于模板改动，比从空白画布开始容易得多。
5.3 通过 API 把 Dify 应用嵌入自己的业务系统
Dify 的 API 接口遵循标准 RESTful 风格，对开发者非常友好。在应用的"访问 API"页面可以看到专属的 API 密钥和接口文档，核心接口是发送对话消息的POST /v1/chat-messages。参考示例：
curl --location --request POST 'http://localhost/v1/chat-messages' \ --header 'Authorization: Bearer app-你的API密钥' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": {}, "query": "你好，请介绍一下你自己", "response_mode": "blocking", "user": "test-user" }'请求成功后你会在终端里直接看到模型返回的文本。这种方式可以轻松把 Dify 应用接入到企业微信机器人、网站客服弹窗、自动化脚本等任何业务系统中，也是从零开始做 AI 应用开发最顺滑的通道。
最后分享一个我坚持到现在的小习惯：每次部署完成后，我都会新建一个"测试专用"应用，输入框直接问"你是什么模型？"，确认模型供应商的真实路径。这个动作看着简单，却能快速区分"平台问题"和"模型问题"，给后面排查省下大量时间。Dify 的入门曲线在同类产品里已经算很缓的了，只要你部署成功一次，后面无论是接知识库还是搭工作流，都会顺理成章。
