企业官网建设流程全解析

简介：这份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 到 6GB；CPU 双核能启动但编排和知识库处理会慢，四核以上体感正常；磁盘留 20GB 以上，镜像和向量数据都会涨。Windows 用户要注意，Docker Desktop 默认走 WSL 2 后端，装之前确认 BIOS 里虚拟化是开的，否则 Docker 起不来，后面所有命令都是白搭。

2.2 装 Docker 和 Git 的具体动作

Docker 的安装按平台走官方安装包就行。Windows 去 Docker 官网下 Desktop 版，安装时勾选 WSL 2 backend；Mac 下对应芯片的 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 :80，Mac 上用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 看报错、建个对话应用发一句话」这三步，确认整条链路真的通，再开始正式用。希望帮到你。

本文还有配套的精品资源，点击获取