简介这份PDF教程面向希望快速上手开源大语言模型应用开发平台的开发者与AI应用爱好者围绕Dify的本地化部署展开帮助读者在自有环境中搭建一套可演示、可验证的生成式AI解决方案原型无需依赖复杂云服务。资源包共1个文件为711KB的PDF文档内容以命令行操作指导为主线涵盖环境准备、代码拉取、容器启动与后台初始化等关键环节。教程从Docker与Git的前置安装讲起逐步演示新建目录、克隆源码、复制环境变量配置、通过docker compose一键拉起服务并说明如何确认九个容器均处于健康运行状态最后引导访问本地地址完成管理员账号设置。文中还针对网络受限或拉取失败的情况给出替代方案并提醒妥善保存超级管理员凭证。目前已有1350人学习适合初学者与有经验的技术爱好者对照实操快速完成Dify平台的本地部署与初步验证。1. 从一台裸机到能跑工作流的 Dify这份部署教程到底解决了什么很多人第一次接触 Dify是在某个演示视频里看到拖拽几个节点就拼出一条知识库问答流水线然后兴冲冲去搜「dify本地部署教程」结果卡在第一步——环境没装、命令敲错、容器起不来。这份《Dify应用开发平台部署教程.pdf》针对的正是这个断层它不讲 Dify 能做什么花哨功能而是把「从零把平台跑起来」这条路径拆成了可照抄的命令序列。Dify 本身是开源的大语言模型应用开发平台融合了后端即服务与 LLMOps 的思路让开发者甚至非技术人员都能定义 AI 应用、运营数据。这份教程的价值在于它把 Docker、Git、docker compose 这些前置依赖和克隆、配置、启动、验证四步串成了一条线适合想在自己机器上验证 Dify 工作流、知识库流水线或者准备对接 deepseek 这类模型做本地部署的从业者。下面我按自己复现时的顺序把每一步的参数、边界和翻车点讲透。2. 部署前的环境底座Docker、Git 与目录规划2.1 为什么 Dify 的部署绕不开 Docker 和 GitDify 的社区版把后端 API、前端 Web、Worker、PostgreSQL、Redis、Weaviate 等组件全部容器化用一份 docker-compose.yaml 编排。这意味着你不需要逐个去装 Python 依赖、配数据库连接串只要 Docker 引擎能跑compose 就能把九个容器拉起来。Git 的作用则是拿到源码仓库因为 docker 目录下的 .env.example 和 compose 文件都在仓库里直接下载 zip 虽然也能用但后续更新、切换分支会麻烦。常见做法是Windows 用户装 Docker Desktop 并启用 WSL 2 后端Mac 用户装 Docker Desktop 即可Git 从官网装完在命令行能敲出git --version就算就绪。这里有个容易被忽略的点——Docker Desktop 默认给 WSL 2 分配的内存可能只有 2GB而 Dify 九个容器同时跑内存吃紧时 Worker 会反复重启建议在 Docker Desktop 的 Settings → Resources 里把内存调到 8GB 以上这是后面容器能不能全部 Started 的物理前提。2.2 新建目录与克隆仓库的实操教程里让先建一个 dify 文件夹再在导航栏输入 cmd 进命令提示符这个操作在 Windows 资源管理器里直接敲 cmd 回车就能在当前路径打开终端省去 cd 的路径拼接。克隆命令本身不复杂但网络环境决定了它是不是一次能成。# 在新建的 dify 文件夹路径下打开终端执行克隆 git clone https://github.com/langgenius/dify.git # 克隆完成后进入仓库确认 docker 目录存在 cd dify ls docker逻辑说明git clone会把整个仓库拉到当前目录下的 dify 子文件夹仓库里 docker 目录才是部署入口根目录的其他代码是给二次开发用的。参数上如果你只想拿部署文件可以加--depth 1做浅克隆减少下载量如果克隆中途断连先git config --global http.postBuffer 524288000把缓冲区调大再重试。教程里提到「安装不了也可以找我直接领取安装包」这对应的是网络受限时用离线包替代克隆拿到压缩包解压后同样要保证 docker 目录结构完整否则 compose 找不到构建上下文。2.3 环境变量文件与 compose 启动的先后关系进入 docker 目录后第一步不是直接 up而是复制环境配置文件。.env.example里定义了数据库密码、端口映射、镜像标签等直接 up 会用默认值但默认值里有些端口可能和你机器上已占用的服务冲突。# 进入 docker 目录 cd dify/docker # 复制环境变量模板生成实际生效的 .env cp .env.example .env # 后台启动所有容器 docker compose up -d逻辑说明cp .env.example .env这一步在 Windows 的 cmd 里如果报「系统找不到指定的文件」是因为 cmd 不认这个语法改用copy .env.example .env即可。docker compose up -d的-d是 detached 模式让容器在后台跑不加这个参数终端会被日志占住。首次执行会拉取九个镜像耗时取决于带宽教程里提醒「安装时间会要久一些」是实话我这边千兆带宽也等了六分多钟。启动完成后用docker compose ps检查正常应该看到九个容器状态列显示 running 或 healthy端口映射里 80 和 443 对应 Web 入口。3. 九个容器的健康检查与首次登录配置3.1 docker compose ps 输出怎么读docker compose ps列出的信息里Name 是容器名Command 是启动命令State 是运行状态Ports 是端口映射。九个容器分别是 api、worker、web、db、redis、weaviate、nginx、sandbox、ssrf_proxy其中 db 和 redis 是基础依赖weaviate 是向量库sandbox 负责代码执行隔离。判断部署成功的标准不是「有九个」而是这九个的 State 都是 running且 api 和 worker 没有在短时间内反复重启。如果你看到某个容器是 exited 状态先docker compose logs 容器名看最后几十行日志八成是端口冲突或内存不足。# 查看所有容器状态 docker compose ps # 如果某个容器异常查看它的日志 docker compose logs api --tail 50 # 查看资源占用确认没有容器被 OOM kill docker stats --no-stream逻辑说明--tail 50只输出最后 50 行避免日志刷屏docker stats --no-stream抓一次瞬时资源快照重点看 MEM USAGE 是否接近 LIMIT。参数上如果发现 db 容器起不来检查 .env 里的DB_PASSWORD是否被改成了含特殊字符的值compose 解析时可能出问题换纯字母数字组合最稳。3.2 访问 localhost/install 完成管理员初始化容器全部 running 后浏览器输入http://localhost/install会跳到初始化页面要求设置管理员邮箱和密码。这个账号是 Dify 的超级管理员后续所有工作空间、应用、知识库都挂在它下面教程里强调「需要记住」不是客套话——Dify 社区版没有找回密码的图形入口忘了只能进 db 容器改数据库。设置完成后点登录进入控制台此时平台才算真正可用。# 如果初始化页面打不开先确认 nginx 容器端口映射 docker compose port nginx 80 # 确认本机 80 端口没有被其他服务占用 netstat -ano | findstr :80逻辑说明docker compose port nginx 80会输出 nginx 容器 80 端口映射到宿主机的哪个端口默认是 80。如果本机 80 被 IIS 或其它 Web 服务占了要么停掉那个服务要么改 .env 里的EXPOSE_NGINX_PORT再重新 up。netstat在 Windows 上查端口占用Mac 用lsof -i :80。这一步的边界是改完 .env 后必须docker compose down再up -d只 restart 不会重新读环境变量。3.3 首次登录后该验证哪几个功能点进入控制台后别急着建应用先做三个验证一是「设置」里看模型供应商能不能正常加载二是建一个空白应用看编排页面能不能打开三是传一个小文本文件进知识库看切片和索引是否走通。这三步分别对应 api、web、worker 和 weaviate 四个容器的协同任何一个环节卡住都能定位到具体容器。常见做法是先在模型供应商里配一个 deepseek 的 API Key因为 deepseek 的接口兼容 OpenAI 格式在 Dify 里选 OpenAI 兼容模式填 base_url 和 key 就能用这也是热词里「deepseek部署」和「dify」经常一起出现的原因。4. 避坑与排查九个容器起不来时先看这几处4.1 现象docker compose up -d 卡在 pulling 或报 TLS 超时原因镜像仓库拉取受网络链路影响或者 Docker Desktop 的代理配置和宿主机不一致。解决先确认 Docker Desktop 的 Settings → Resources → Proxies 是否误开了代理关掉后重试如果还是超时在 .env 里把镜像源换成可访问的地址或者用docker pull单独拉取报错的那个镜像成功后再 up。注意不要同时开多个网络层工具容易让 Docker 的 DNS 解析混乱。4.2 现象db 容器反复重启日志显示 password authentication failed原因.env 里的DB_PASSWORD和 db 容器初始化时写入的密码不一致通常发生在你改了 .env 但 db 的数据卷还是旧的。解决docker compose down -v删掉数据卷再 up让 db 重新初始化。这个操作会清空已有数据仅在首次部署或确认不需要旧数据时用。血泪经验是改数据库相关配置前先备份docker/volumes目录。4.3 现象访问 localhost/install 显示 502 Bad Gateway原因nginx 容器起来了但 api 容器还没就绪或者 api 容器已经崩溃。解决docker compose logs api --tail 100看 api 的报错常见的是连不上 db 或 redis。如果 api 日志显示Connection refused到 db说明 db 还没 healthy等一两分钟再刷新如果 api 直接 exited检查 .env 里MIGRATION_ENABLED是否为 true首次启动需要它跑数据库迁移。4.4 现象初始化页面能打开但点登录后白屏原因浏览器缓存了旧版本的前端资源或者 web 容器和 api 容器的版本不匹配。解决强制刷新CtrlShiftR如果无效docker compose down后docker compose pull拉取最新镜像再 up。注意 Dify 社区版不同版本间的数据库 schema 可能有差异跨版本升级前先看 release note 里的迁移说明。4.5 现象知识库上传文件后一直显示「索引中」原因worker 容器没有正常消费队列或者 weaviate 容器连接异常。解决docker compose logs worker --tail 50看有没有报错常见的是 embedding 模型没配导致任务卡住。先在模型供应商里配好 embedding 模型再传文件否则 worker 会一直重试。这个坑在新装环境里特别常见因为默认没有可用的 embedding 供应商。5. 从能跑到好用升级、迁移与离线包替换的实操习惯部署完成只是起点真正在团队里用起来绕不开升级和迁移。Dify 社区版更新频率不低热词里「更新dify」「dify 在线升级 windows」说明很多人卡在升级这一步。我的习惯是升级前先docker compose down然后git pull拉最新代码对比 .env.example 和现有 .env 的差异把新增的变量补进去再docker compose pull拉新镜像最后up -d。这套流程在 Windows 和 Mac 上一致区别只是终端命令的写法。如果 git pull 因为本地改动冲突先git stash存一下再拉拉完git stash pop把改动合回来。迁移场景分两种同机换目录和跨机搬迁。同机换目录直接把整个 dify 文件夹复制走但要注意 .env 里的绝对路径配置跨机搬迁则要同时搬docker/volumes下的数据卷否则新机器上 db 是空的所有应用和知识库都没了。我一般会先用docker compose down停掉所有容器再打包整个 dify 目录到新机器上解压后up -d这样数据卷跟着目录一起走省去单独导出数据库的麻烦。离线包替换则是网络受限时的后悔药从能访问的机器上docker save出九个镜像拷到目标机器docker load再把 dify 源码目录一起带过去效果和在线克隆一致。验证升级是否成功不能只看容器 running要进控制台看版本号再跑一次知识库检索和一次工作流执行。我吃过一次亏容器全绿但 worker 的镜像标签没更新导致新功能在编排页面可见但执行时报方法不存在。从那以后我每次升级都强制走一遍「down → pull → 对比 .env → up → 跑一条工作流」的完整链路确认端到端通了才算完。希望这份拆解能帮你少走几个弯路把 Dify 真正跑成自己能用的平台。本文还有配套的精品资源点击获取