上个月帮一位朋友搭 AI 应用演示环境他模型接口早就申请好了结果折腾了整整两天愣是没让一个聊天机器人跑起来。不是不会调 API而是卡在“应用怎么落地”这一步——前端要写、后端要接、会话要管、文档要切全得自己搭。后来我直接把 Dify 搬出来用 Docker 一键部署半小时不到一个能对话、能传文档、能跑知识库的 AI 应用就上线了。这篇就把整个流程拆开揉碎讲清楚从 Docker 环境准备到 Dify 跑起来再到发布第一个 AI 应用五步走完全程附命令、附截图说明、附我踩过的坑。1. 为什么是 Dify Docker我的选型逻辑先说结论如果你要的不是“从零写一个大模型应用框架”而是“快速把大模型能力变成可用的产品”Dify 是当前少有的、把开发者和业务方需求同时照顾到的开源平台。我在选型之前也对比过几类方案这里把当时的思考过程写出来省得你再走一遍弯路。1.1 Dify 到底解决了什么问题Dify 本质上是一个 LLMOps 平台也就是大模型应用的低代码开发与运营平台。它把大模型应用开发里最重复、最琐碎的部分——模型接入、Prompt 编排、上下文管理、RAG 知识库、会话记忆、应用发布——全都做成了可视化操作。你不需要自己写后端接口来管理对话状态不需要自己拼向量数据库来做文件问答更不需要从零开发一个管理后台。我那位朋友之前卡住的点正是 Dify 擅长的部分他把 OpenAI 的 API 接通之后发现要做成“用户能打开网页直接对话”的产品还得考虑会话历史、流式输出、系统 Prompt、多轮上下文截断。这些如果自己写没个一两周打磨不好。Dify 把这些能力全部内置网页端、API 端、分享链接三种发布方式都是开箱即用的。还有一个很现实的因素团队协作。Dify 天然带多租户能力在 1.x 版本里社区版也支持了多租户模式。也就是说团队里不同角色可以在同一个实例上各玩各的开发人员调工作流、运营人员配知识库、产品经理看日志互不干扰。这一点在后面做企业级应用时非常重要。1.2 为什么必须用 Docker 部署Dify 的部署方式不止一种官方文档里提供了 Docker Compose、本地源码运行、Kubernetes 等方案。但对于绝大多数场景——个人学习、团队内部使用、中小型产品 MVP 验证——Docker Compose 是唯一值得推荐的。原因很简单Dify 不是单体应用它由 api、worker、web、db、redis、sandbox、ssrf_proxy 等多个服务组成。如果不用容器编排光是装依赖、配环境变量、启动顺序就够你喝一壶的。我实测下来全新的一台 Ubuntu 22.04 服务器从安装 Docker 到 Dify 界面出现大概 15 到 20 分钟。如果用源码方式跑光装 Python 虚拟环境和 Node 依赖就不止这个时间。而且 Docker 方式最大的优势是“干净”——所有组件都打在容器里升级时只需要拉新镜像重启即可不会把宿主机环境搞得一团糟。所以下面所有步骤都围绕 Docker Compose 展开。这不是唯一方案却是让我愿意反复推荐的方案。2. 动手前的环境检查清单真正省时间的准备很多人部署失败不是后面步骤操作错了而是第一步环境没准备好。这里列一份我在多次部署中总结的检查清单照着核对一遍能避免大部分翻车。2.1 硬件要求与操作系统建议先说最低配置。官方的建议是 2 核 4G 内存但实际上跑起来之后Dify 全家桶要吃 2GB 左右的内存。如果你还要在同一个实例上做模型推理比如部署本地嵌入模型 bge-m3那 8G 内存才稳妥。磁盘方面系统盘至少留 20G 剩余空间Docker 镜像和容器日志都会占空间太紧的话容易出现容器写了半截就退出的问题。操作系统我踩过两个版本Ubuntu 22.04 和 Debian 12都跑得很顺。如果你手头是 CentOS 7也不是不行但要确认内核版本不低于 3.10且 Docker 要装较新版本否则有些 Compose 特性用不了。Windows 用户建议直接用 Docker DesktopWSL2 后端macOS 用户同样用 Docker Desktop。说实话Windows 上部署 Dify 可行但如果你有云服务器我更推荐在 Linux 上跑后面升级维护都省心。2.2 安装 Docker 与 Docker Compose如果你的机器还没装 Docker这一步是必须做的。Ubuntu 22.04 上我通常会这样装# 移除可能存在的旧版本 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加软件源 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin装完之后务必确认 Docker Compose 插件版本Dify 的 compose 文件对版本有要求docker --version docker compose version我当前环境是 Docker 27.x Compose 2.x跑 Dify 1.x 没问题。Compose 版本低于 2.0 的建议先升级否则后面执行docker compose up时会报语法不支持的错。2.3 镜像拉取慢的解决方案这一步几乎是国内服务器部署绕不开的坎。Dify 的镜像包含 postgres、redis、nginx、python、node 等基础镜像以及 langgenius 自己的镜像总下载量接近 2GB。如果你直接拉大概率会卡在等待层数据的阶段动辄半小时起步。我的做法是在 Docker 的 daemon 配置里加上镜像加速地址。修改/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://mirror.baidubce.com ] }注意加速地址不要只填一个国内镜像源偶尔会失效填两三个做兜底。修改后重启 Docker 服务再继续。sudo systemctl daemon-reload sudo systemctl restart docker配置好之后拉镜像的速度从几 KB/s 到几 MB/s完全两种体验。这一步如果不做后面docker compose up会非常痛苦不是命令错就是网络慢到怀疑人生。3. 五步部署实操从空服务器到 Dify 界面环境就绪后真正干活的时间到了。我把整个过程压缩成五个大步骤每一步都是可以直接复制执行的。全程不需要写一行业务代码只需要敲命令和点鼠标。3.1 获取 Dify 源码与 Docker Compose 编排文件Dify 的部署不是直接写一份 compose 文件而是官方仓库里已经准备好了完整的编排文件和环境变量模板。你要做的第一件事就是把仓库拉下来git clone https://github.com/langgenius/dify.git这里有个小建议不要直接 clone 主分支的最新代码而是去 Release 页面看当前正式版的版本号然后 checkout 到对应 tag。我一般这样做cd dify # 查看当前 release 版本假设是 1.10.0 git checkout 1.10.0为什么建议用 release tag因为主分支可能包含一些未完全测试的新特性部署上去之后如果遇到问题社区里不一定有对应的解决方案。而 release 版本经过了完整测试坑基本都被踩平了。我早期图新鲜用过一次主分支结果某个中间版本里 worker 容器一直重启查了半天才发现是已知 bug切回正式版就好了。进入部署目录cd dify/docker cp .env.example .env.env文件是 Dify 所有环境变量的总开关里面有端口配置、数据库配置、密钥配置、模型供应商默认开关等。3.2 环境变量的必要检查打开.env文件后有几个关键项我强烈建议现在就检查而不是等容器启动后再回头改EXPOSE_NGINX_PORT默认 80。如果你服务器上已经有 Nginx 或其他服务占用 80 端口这里改成 8080 或任意空闲端口。这个改动只在.env里改就行compose 文件会自动读取。SECRET_KEY默认是dify-ai这是用来加密会话数据的密钥。生产环境务必改成随机字符串比如用openssl rand -base64 42生成一个。POSTGRES_PASSWORD、REDIS_PASSWORD安全起见也建议改成强密码。如果你只是本地学习不改问题不大如果是公网部署不改等于把数据库裸奔在外面。另外如果你计划跑本地嵌入模型比如 bge-m3来构建知识库需要在.env里检查一条SANDBOX_API_KEY之类的配置是否存在。Dify 1.x 版本对沙箱有内置的随机密钥逻辑默认值一般够用但升级时注意看迁移文档。检查完毕后保存文件接下来就是见证奇迹的时刻。3.3 启动所有服务docker compose up 的完整姿势启动命令非常简单但这简单背后有一个顺序问题。Dify 的依赖关系是数据库和 Redis 先起来 → api 和 worker 起来 → web 前端起来 → nginx 做入口反向代理。不过 Docker Compose 会根据depends_on自动处理启动顺序你不需要手动分步启动。在dify/docker目录下执行docker compose up -d-d表示后台运行。第一次执行时会开始拉取所有镜像这个阶段我想再强调一句如果前面配置了镜像加速这里会顺很多。拉取完成后观察容器启动状态docker compose ps正常情况下你会看到大约 9 到 10 个容器分别是容器名作用健康状态docker-api-1Dify 后端 API 服务healthydocker-worker-1异步任务处理服务healthydocker-web-1前端页面服务healthydocker-db-1PostgreSQL 数据库healthydocker-redis-1缓存与队列healthydocker-sandbox-1代码执行沙箱healthydocker-ssrf_proxy-1SSRF 防护代理healthydocker-nginx-1统一入口反向代理healthydocker-weaviate-1向量数据库部分版本内置healthy如果你的版本里有 weaviate 或 qdrant 容器这是正常的知识库功能会用到向量数据库。看到所有容器都是 healthy 之后部署就完成了 90%。3.4 初始化管理员账号进入系统的第一道门容器健康不代表你立刻能登录。首次访问 Dify 时系统会要求你配置管理员账号。在浏览器里访问http://你的服务器IP:端口/install如果你改过EXPOSE_NGINX_PORT不要忘了带上端口号。页面上会要求设置管理员邮箱和密码。我一般会设置一个专门的邮箱来接收系统通知密码用足够强度的组合。这一步没有任何难度但有一点要注意这个页面只在首次安装时出现如果你跳过了系统不会自动弹出来那就得去数据库里手动初始化非常麻烦。所以遇到/install页面一次填完别关。设置完管理员账号Dify 会跳到登录页。用刚创建的账号密码登录你就正式进入了 Dify 的工作台。3.5 登录后的三个必要设置登录之后先别急着创建应用我强烈建议你按下面三步把基础设置做完否则后续用起来会别扭检查模型供应商页签在右上角头像进入“设置”找到“模型供应商”。这里能看到支持的各类模型列表。你要用的模型比如 OpenAI 的 gpt-4o、Anthropic 的 claude、国内的智谱 GLM、阿里通义等都需要在这里填 API Key。填完之后Dify 会自动验证 Key 是否可用。添加模型即可有些模型供应商需要单独在“模型类型”里选择对话、文本生成、Embedding 等类别。Embedding 模型格外重要做知识库时要用建议提前把 bge-m3 或 text-embedding-3-small 之类的模型配上。设置工作空间信息工作空间名称会展示在应用管理的界面上改成你自己项目的名字后面多项目时就不会搞混。到这里Dify 平台本身已经跑通。剩下的问题只有一个怎么让一个 AI 应用上线我下面用最小化的路径演示一遍。4. 五步上线的核心创建并发布一个可对话的 AI 应用部署好 Dify 只是平台就绪真正让业务方看见价值的是“应用”本身。这里我不讲复杂的工作流编排而是用最简单的“聊天助手”类型走完从创建到发布的完整流程让你先有一个跑得通的闭环再谈进阶。4.1 选择合适的应用类型在 Dify 工作台首页点击“创建应用”你会看到几种类型聊天助手、Agent、文本生成、工作流等。第一个应用我建议创建“聊天助手”因为它的交互方式最直观而且能直接看到模型对话效果。创建对话框里会让你填应用名称和描述这些会展示在最终用户面前。名称我用过“内部知识助手”这种业务向的名字也用过“测试机器人”这种开发向的名字看你自己场景。创建完成后进入的是应用编排页面。4.2 编排页面的关键配置模型、Prompt、对话开场白编排页面是 Dify 的核心工作区左侧是应用的基本信息中间是系统 Prompt 编辑区和模型选择右侧是调试预览区。模型选择放在右上角。点击选择模型会列出你在设置里配好的模型列表。第一个应用我建议直接选一个能力强的模型比如 gpt-4o 或 claude-3.5-sonnet因为你要先验证链路是否通而不是优化成本。系统 Prompt 是给模型的总纲。我在这里踩过一个小坑最开始什么都不填直接调试模型也能回复但语气和风格完全是随机的。建议至少写清楚角色、目标、限制三件事比如你是一个智能客服助手负责回答用户关于产品使用的问题。 回答要简洁直接如果不知道答案就如实说不知道不要编造。填完 Prompt 后右侧会出现调试对话框可以直接发消息测试。这一步能立刻看到模型是否正常响应也能调整 Prompt 的效果。别忘了左下角有个“对话开场白”设置这是用户点开聊天气泡时看到的第一句话类似于“你好我是XX助手有什么可以帮你”。做完这个设置客服体验会专业很多。4.3 发布应用三种方式任选调试满意后点击右上角的“发布”按钮。Dify 会弹出一个发布方式选择通常有“发布为 Web App”和“访问 API”两种。这两个都是生产方式不是测试方式。对于第一个应用我建议选择“发布为 Web App”。发布完成后你会得到一个链接把链接发给任何人对方不需要登录 Dify就能直接打开网页和你的 AI 应用对话。这一点在演示场景中非常加分——我那位朋友最后就是用这个链接给领导演示的整个过程只花了一个晚上。4.4 从 Web App 到 API 集成如果你的应用最终要嵌入到现有产品里Dify 的 API 能力才是重点。在“访问 API”页面你可以创建 API 密钥然后通过标准的 REST API 调用应用。官网给了 Python、curl 等示例核心逻辑是curl -X POST http://你的服务器IP/端口/v1/chat-messages \ -H Authorization: Bearer app-你的API密钥 \ -H Content-Type: application/json \ -d { inputs: {}, query: 你好, user: test-user, response_mode: blocking }返回的 JSON 里answer字段就是模型生成的回复。这种方式适合把 AI 能力嵌入到已有的业务系统里公司内部工具、客服工作台、后台管理界面都可以这样接通。我这里多提醒一句API 密钥是敏感信息只放到后端代码里前端页面不要暴露。我在一些开源项目里见过把app-开头的密钥直接写在前端 JS 里的别人拿到密钥就能无限调用你的 AI 应用账单会非常难看。5. 实测中踩过的坑与高频问题排查跑通是一回事跑得稳是另一回事。下面这些问题是过去几个月里反复出现在社区和我个人部署经历里的高频问题我把排查链路写出来遇到问题时照着走会快很多。5.1 多个容器状态异常定位根因的通用套路第一次启动后不是所有人都会一次全绿。常见情况是docker compose ps看到某个容器状态为 restating 或 unhealthy。这时候不要慌也不要挨个容器重启正确做法是先看日志docker compose logs api # 看后端 API 日志 docker compose logs worker # 看任务队列日志日志会明确告诉你失败原因。我遇到最多的几个原因数据库还没准备好api 容器就尝试连接导致启动失败。处理方式是等几秒再docker compose restart api或者直接把启动命令里的健康检查依赖调严格一点。.env里的SECRET_KEY格式不对导致加解密报错。检查是否包含特殊字符导致解析异常。镜像版本不一致比如 compose 文件里的版本号被改成不存在的 tag。这种情况把镜像 tag 恢复到官方默认即可。日志排查法适用于绝大多数容器异常实在没头绪就去 Dify 官方 GitHub Issues 里搜报错关键词基本都能找到答案。5.2 80 端口被占用导致 Web 无法访问如果你服务器上已经装了 Nginx 或宝塔面板80 端口冲突是大概率事件。症状是容器都 healthy但浏览器访问 IP 就是打不开页面。这时候不要先怀疑 Dify先看本机端口监听sudo netstat -tlnp | grep :80如果是其他服务占用最简单的方案是把EXPOSE_NGINX_PORT改成 8080然后重新执行docker compose up -d修改.env后光重启容器不够因为 nginx 容器启动时读取的是当时的环境变量。你需要先停掉再启动docker compose down docker compose up -d5.3 升级后知识库报 Internal Server Error这个坑在 Dify 社区里出现频率很高尤其是在线升级版本之后。我自己的经历是1.6 升到 1.10 时知识库里旧的文档索引和新的向量数据库逻辑对不上导致打开知识库页面或修改文档时直接 500。排查方式是先看 api 容器日志基本会看到和数据库 migration 相关的错误。处理方案通常是把数据库迁移补跑一遍docker compose exec api flask db upgrade注意不同版本的迁移命令可能不同升级前务必看官方 Release Notes 里的升级指南。如果已经报错先备份dify/docker目录下的.env和volumes文件夹再尝试迁移命令。实在不行回滚到旧版本镜像也是一种保命手段。5.4 镜像加速失效后的应急方案即使配置了镜像加速也可能遇到某些特定镜像拉取特别慢的问题。我遇到过langgenius/dify-api这个镜像因为体积大偶尔拉取超时的情况。应急方案有两个一是重新执行docker compose pull多试几次一般能续上二是找到该镜像的具体名称和 tag单独执行docker pull成功后 compose 会自动使用本地缓存镜像。不要反复docker compose up -d中间中断会留下很多悬空层反而拖慢后续操作。5.5 离线环境的插件与模型部署如果你的部署环境是内网隔离的无法访问外网拉取模型和插件那就要提前做好离线准备。Dify 1.x 支持离线安装插件你需要先在一台联网机器上把插件打包下载再拷贝到内网机器上通过命令导入。这个过程比较繁琐但可行。我建议这类用户优先在测试环境把整个镜像目录docker save导出来再在目标机器docker load导入比逐层解决网络问题省事得多。6. 从“跑通”到“好用”部署完成后的扩展方向应用上线不是终点甚至只是开始。Dify 真正厉害的地方在于跑通基础链路之后你可以像搭积木一样给它加能力。最后这部分讲讲我最常推荐的三个扩展方向。6.1 接入知识库做 RAG 问答第一个应用只是一个裸模型只能靠训练数据回答问题。如果你的业务需要基于内部文档问答那就得给应用接上“外挂知识库”。在 Dify 里这个过程不需要写向量数据库代码只需要在“知识库”模块上传文档PDF、Markdown、TXT 等Dify 会自动完成切片、向量化、索引。然后回到应用编排页面在“上下文”里关联这个知识库模型就会优先从文档中找答案。如果做知识库本地部署嵌入模型比如 bge-m3会很有必要这样可以避免把文档内容发到外部模型 API数据安全上更可控。部署 bge-m3 到本地后在模型供应商里配置为 Embedding 模型创建知识库时选择它即可。6.2 用工作流编排复杂业务逻辑如果单纯对话无法满足你的场景Dify 的工作流是你下一个要玩的东西。工作流可以把大模型能力、逻辑判断、HTTP 请求、代码执行等节点串联起来实现类似“用户输入订单号 → 查询数据库 → 调用大模型总结 → 返回结果”这样的复杂流程。这个能力对团队内部工具非常有用相当于把 AI 应用从“聊天”升级到了“自动化处理”。我第一次用工作流做的是一个组内日报自动生成器从项目管理工具拉数据丢给大模型总结最后通过 Webhook 发到群机器人。整个流程在 Dify 界面里拖拽完成没写一行代码。6.3 多租户与团队协作Dify 1.10 开始社区版的多租户能力进一步完善。在团队场景下管理员可以创建多个成员账号不同成员可以在同一个实例上各自管理自己的应用和知识库互相看不到对方的数据但共享同一个模型配置。这对希望控制成本、集中管理模型 API Key 的团队来说非常友好。我现在的用法是个人一套 Dify 实例做实验公司一套独立实例做正式业务。正式业务里给开发、产品、运营分别建账号开发调工作流产品配知识库运营看数据各司其职。版本升级前先在个人实例验证没问题再动正式环境这个习惯帮我避开了好几次升级导致的故障。6.4 最后分享一个小技巧关于日常维护我强烈建议你养成定期备份的习惯。Dify 的数据在 PostgreSQL 里你不需要备份整个服务器只需要备份数据库和.env文件docker compose exec db pg_dump -U postgres -d dify dify_backup_$(date %Y%m%d).sql备份的 SQL 文件拉回本地存好真出问题时在新机器上部署好 Dify 后用同样的命令恢复几分钟就能满血复活。这个习惯救过我不止一次重要的事情值得再次强调。