简介这份PDF教程面向希望快速上手开源大语言模型应用开发平台的开发者与AI应用爱好者围绕Dify的本地化部署展开帮助读者在自有环境中搭建一套可运行的生成式AI应用原型系统摆脱对云服务的依赖。资源包内仅含1个PDF文件大小约711KB内容以图文结合的命令行操作指导为主覆盖从环境准备到容器启动的完整流程。教程从Docker与Git的前置安装讲起逐步演示新建目录、克隆源码、复制环境变量配置、使用docker compose一键拉起服务并说明如何通过容器状态确认九个服务是否健康运行最后引导访问本地地址完成管理员账号初始化。对于网络条件受限或克隆失败的情况文中也提供了替代获取方式与排错提示。目前已有1350人学习下载适合初学者对照操作也便于有经验的技术人员在此基础上进行定制与功能拓展。1. 从零把 Dify 跑起来为什么我建议你先在本地用 Docker 装一遍很多人第一次接触 Dify是在某个演示视频里看到别人拖几个节点就搭出一个能查知识库、能调工具的 AI 应用然后兴冲冲去注册云端账号结果卡在额度、网络或者数据合规上。我自己的习惯是凡是这种开源 LLM 应用开发平台先在本地用 Docker 完整跑一遍把它的容器结构、端口映射、环境变量摸清楚再决定要不要上生产。Dify 这个项目把后端即服务和 LLMOps 揉在一起前端做编排、后端管模型接入和知识库流水线整套东西拆成了九个左右的容器用一份 docker-compose 就能拉起来。这篇笔记就按我实际部署的顺序走一遍从装 Docker 和 Git到克隆源码、改环境变量、启动容器、验证九个服务是否健康最后进初始化页面建管理员账号。适合手里有一台能跑 Docker 的机器、想本地验证 Dify 工作流和知识库能力的开发者也适合想拿它接 deepseek 这类模型做原型验证的团队。2. 部署前的环境准备Docker、Git 和机器底子怎么算够用2.1 为什么 Dify 非要 Docker 和 Git 不可Dify 的官方部署路径是围绕 docker-compose 设计的这不是随便选的。它一套跑起来要同时起 API 服务、Worker 异步任务、Web 前端、PostgreSQL、Redis、Weaviate 或其它向量库、Nginx 反代、Sandbox 沙箱等组件手工一个个装依赖、配版本光是 Python 和 Node 的版本冲突就够折腾半天。Docker 把这些组件的运行时和依赖全部封在镜像里你只需要保证宿主机有 Docker Engine 和 compose 插件剩下的版本对齐交给镜像标签。Git 的作用是把源码仓库完整拉下来因为 docker 目录里的 compose 文件、.env.example 模板、nginx 配置都在仓库里不是单独一个镜像能替代的。常见做法是直接用 git clone 拿仓库而不是去下某个压缩包这样后续更新、切分支、看 compose 变更都方便。机器底子这块我给一个实际能跑起来的参考线内存至少 8GB推荐 16GB因为光 PostgreSQL、Redis、向量库加上几个 Python 服务空闲状态就能吃掉 4 到 6GBCPU 双核能启动但编排和知识库处理会慢四核以上体感正常磁盘留 20GB 以上镜像和向量数据都会涨。Windows 用户要注意Docker Desktop 默认走 WSL 2 后端装之前确认 BIOS 里虚拟化是开的否则 Docker 起不来后面所有命令都是白搭。2.2 装 Docker 和 Git 的具体动作Docker 的安装按平台走官方安装包就行。Windows 去 Docker 官网下 Desktop 版安装时勾选 WSL 2 backendMac 下对应芯片的 dmg拖进应用目录。装完打开终端敲版本命令验证docker --version docker compose version第一行确认 Docker Engine 在第二行确认 compose 插件在。注意新版 Docker 用的是docker compose中间空格不是老的docker-compose连字符这两个命令在脚本里不通用后面启动容器时用错会直接报 command not found。Git 去 git-scm.com 下对应平台安装包一路默认即可。装完验证git --version能打印出版本号就说明 PATH 配好了。如果 Windows 上敲 git 提示不是内部命令多半是安装时没选「Git from the command line」重装一遍勾上就行。这两步做完环境准备就算齐了接下来才是 Dify 本体。3. 克隆源码到启动容器一条命令链把九个服务拉起来3.1 新建目录并克隆 Dify 仓库先在你打算放项目的盘里建一个空文件夹比如叫dify。这个文件夹是后面所有操作的根别建在中文路径或者带空格的目录下Docker 挂载卷时遇到空格偶尔会出玄学问题。建好后在文件夹地址栏输入cmd回车直接在当前目录打开命令提示符省得手动 cd。然后执行克隆git clone https://github.com/langgenius/dify.git这条命令会把 Dify 主仓库拉到当前目录下的 dify 子文件夹里。克隆完成后你会看到一堆源码目录其中docker这个目录才是部署要用的。如果克隆中途断流或者速度极慢常见做法是换一个网络时段重试或者直接用别人打包好的源码包解压效果一样只要目录结构完整。克隆完先别急着启动进去确认一下 docker 目录里有没有docker-compose.yaml和.env.example这两个文件它们是下一步的核心。3.2 进 docker 目录、复制环境变量、启动容器进入 docker 目录同样在地址栏敲 cmd 打开命令行cd dify/docker cp .env.example .env第一行切到 compose 文件所在目录第二行把环境变量模板复制成实际生效的.env。这一步不能省Docker Compose 默认读.env文件来填充 compose 里的变量占位符没有这个文件容器启动时会因为变量为空而报错。.env里控制的东西不少常见需要关注的几个EXPOSE_NGINX_PORT决定你最终访问的端口默认 80数据库密码、Redis 密码这些首次启动会自动生成或使用默认值向量库类型默认是 weaviate想换别的得改配置。第一次部署建议先不动用默认值跑通再说。接着启动docker compose up -d-d是后台运行不加的话日志会刷满你的终端关掉窗口容器就停了。这条命令会先拉取所有镜像再按依赖顺序创建并启动容器。第一次执行时间会比较长镜像加起来好几个 GB耐心等。看到一堆Started或者Running的输出说明容器都起来了。这里有个血泪经验如果卡在某个镜像拉取不动多半是网络问题可以配置镜像加速或者分几次重试别反复up又down容易把已经拉好的层搞乱。3.3 验证九个容器是否真的健康启动完不代表就好了得确认每个容器都在正常运行docker compose ps这条命令列出当前 compose 项目下所有容器的状态、端口映射和健康检查结果。正常情况你应该看到九个左右的服务包括 api、worker、web、db、redis、weaviate、nginx、sandbox、ssrf_proxy 这些状态列显示Up或者running。如果某个容器显示Exit或者Restarting说明它启动失败或者反复重启这时候要看它的日志docker compose logs 服务名比如docker compose logs api看后端服务的报错。常见失败原因是端口被占用比如 80 端口已经被别的 web 服务占了、内存不够导致容器被 OOM kill、或者.env里某个变量格式不对。把日志里的报错关键词拿去搜基本都能定位。九个容器全部 Up 之后部署这步就算过了。4. 初始化管理员账号与首次登录别把密码弄丢4.1 访问安装页并设置管理员容器都健康后打开浏览器访问http://localhost/install如果你改了EXPOSE_NGINX_PORT就把 80 换成你设的端口。这个地址会跳到 Dify 的初始化设置页让你填管理员邮箱和密码。这个账号是超级管理员后面所有工作空间、应用、知识库的管理权限都挂在它下面密码务必记牢。我见过有人随手设了个密码过两天想进后台发现进不去只能去数据库里重置非常麻烦。填完邮箱密码点设置就会进入登录页用刚设的账号登录就能看到 Dify 的主界面了。到这一步一个本地可用的 Dify 应用开发平台就算完整跑起来了接下来你可以接模型、建知识库、搭工作流。4.2 首次登录后先确认这几件事登录进去别急着建应用先花两分钟确认基础状态。第一看设置里的模型供应商能不能正常配置如果你要接 deepseek 或者其它模型需要在这里填 API Key 和 Base URL填完点测试能通说明后端到模型的链路没问题。第二看知识库功能是否可用随便传一个小文本文件试试索引能不能跑通这一步会验证向量库和 worker 是否正常工作。第三看系统状态或者容器日志里有没有反复出现的报错尤其是数据库连接和 Redis 连接相关的。这三件事确认完你后面搭工作流、做知识库流水线才不会莫名其妙翻车。5. 避坑与排查部署 Dify 最容易翻车的五个地方5.1 容器起来了但网页打不开现象docker compose ps显示容器都是 Up但浏览器访问 localhost 一直转圈或者连接被拒。 原因最常见的是 Nginx 容器端口没映射对或者宿主机 80 端口被其它程序占用Nginx 起不来但 compose 没报错。 解决先docker compose ps看 nginx 那行的端口映射是不是0.0.0.0:80-80如果不是检查.env里的EXPOSE_NGINX_PORT。再看宿主机 80 是不是被占Windows 上用netstat -ano | findstr :80Mac 上用lsof -i :80占用了就改端口或者停掉占用程序。5.2 克隆仓库卡住或者失败现象git clone执行后长时间无响应或者报连接超时、early EOF。 原因仓库体积不小网络抖动或者链路质量差时容易中断。 解决先确认能正常访问代码托管站点然后重试如果反复失败用浅克隆git clone --depth 1只拉最新一次提交体积小很多再不行就用打包好的源码包解压后目录结构一致不影响后续部署。5.3 启动时提示变量为空或配置错误现象docker compose up -d报错提示某个环境变量没有值或者容器启动后立刻退出。 原因忘了执行cp .env.example .env或者.env文件被编辑器改坏了格式比如多了空格、引号不匹配。 解决确认 docker 目录下存在.env文件用cat .env看关键变量有没有值。如果改过恢复成从.env.example重新复制一份再改需要的项。注意.env里不要用中文引号不要有多余空行里的空格。5.4 内存不够导致容器反复重启现象部分容器状态是 Restarting日志里出现 killed 或者 OOM 字样。 原因宿主机内存不足Docker 在资源紧张时会杀掉占用高的容器PostgreSQL 和向量库首当其冲。 解决给 Docker 分配更多内存Docker Desktop 在设置里调或者关掉其它吃内存的程序。如果机器本身只有 8GB建议把不必要的容器停掉或者只跑核心服务做验证。生产环境直接上 16GB 以上。5.5 管理员密码忘了进不去现象初始化时设的密码记不起来登录页反复提示错误甚至触发 too many incorrect password attempts。 原因密码没记录或者多人共用环境被人改过。 解决最直接的是进数据库重置用docker compose exec db psql -U postgres连进 PostgreSQL找到对应用户表更新密码字段密码是哈希存储不能直接填明文。更省事的办法是如果数据不重要把容器和数据卷一起清掉重新初始化但这样会丢已有应用和知识库操作前想清楚。6. 进阶把本地 Dify 用顺手的几个参数与验证习惯跑通只是起点真正用起来还得会调。第一个要会的是端口和访问方式。默认 80 端口在很多机器上会被占我一般会在.env里把EXPOSE_NGINX_PORT改成 8080 或者别的空闲端口改完docker compose down再up -d生效。改完记得访问地址也要跟着换别还用 localhost 硬试。第二个是模型接入的验证。Dify 本身不带模型你得在设置里配供应商。接 deepseek 这类兼容 OpenAI 接口的模型时Base URL 和模型名要填对填完一定点测试按钮看到成功再保存。我习惯在正式建应用前先建一个最简单的对话应用发一句话确认模型能回再去做复杂的工作流这样出问题能快速判断是模型链路还是编排逻辑的锅。第三个是数据持久化。Dify 的数据库和向量数据都存在 Docker 卷里docker compose down默认不会删卷但如果你加了-v参数卷会被一起清掉所有应用和知识库就没了。所以任何时候执行带-v的命令前先确认数据是不是可以丢。想备份的话定期把数据库导出来或者直接备份对应的卷目录。第四个是升级。Dify 更新比较频繁升级时先git pull拉最新代码再看docker-compose.yaml和.env.example有没有新增变量有的话同步到自己的.env然后docker compose pull拉新镜像再up -d。别跳过看变更直接 up有时候新版本加了必填变量直接起会失败。最后说个验证习惯。我每次部署完除了看docker compose ps还会挨个看关键服务的日志前几十行确认没有反复出现的 error。尤其是 api 和 worker它们报错往往不会让容器退出但功能会悄悄坏掉比如知识库索引一直排队不处理。从那以后我每次部署完 Dify都强制走一遍「ps 看状态、logs 看报错、建个对话应用发一句话」这三步确认整条链路真的通再开始正式用。希望帮到你。本文还有配套的精品资源点击获取