怎么从GitHub克隆Dify源码并用Docker本地部署

从 GitHub 克隆 Dify 官方源码并在本地通过 Docker Compose 启动容器集群，是搭建私有化大语言模型应用平台最严谨、也最便于后续定制二次开发的部署方案。整个操作路径可以概括为四个连贯环节：校验宿主机 Docker 与 Git 基础环境、克隆仓库并检出稳定 Release 版本、基于模板配置 .env 环境变量、拉起容器集群并完成控制台管理员初始化。掌握这套流程不仅能快速获得完整的本地 AI Agent 与知识库工作流环境，也能为日后的数据持久化备份和版本平滑升级打下清晰的基础。

一、部署前的环境准备与硬件基线

Dify 是一个全功能的大模型应用开发平台，其后台集成了前端交互界面、核心 API 引擎、Celery 异步任务队列、PostgreSQL 关系型数据库、Redis 缓存队列、Weaviate 向量检索引擎以及用于沙箱执行的代码运行器。由于协同运行的容器数量通常在 8 个以上，因此在执行代码克隆前，必须首先确保本地宿主机具备合规的软硬件环境。

在硬件资源方面，建议宿主机具备至少 2 核 CPU 以及 8GB 运行内存。如果本地需要同时运行嵌入模型（Embedding）或向量检索运算，4GB 内存极易导致 PostgreSQL 或向量数据库因系统内存溢出（OOM）而异常崩溃退出。此外，Docker 镜像拉取和各模块的基础数据存储需预留至少 15GB 的可用磁盘空间。

在软件方面，需要安装 Git 工具以及较新版本的 Docker。当前主流部署方式均推荐使用 Docker Compose V2 规范（即通过 docker compose 命令调用），不再推荐旧版的独立二进制工具 docker-compose。

# 检查 Git 版本
git --version

# 检查 Docker 引擎运行状态与版本（建议 20.10.x 以上）
docker --version

# 检查 Docker Compose 版本（建议 v2.10.x 以上）
docker compose version

执行上述命令后，如果均能正确输出对应工具的版本号，并且 Docker 守护进程处于正在运行状态（可通过运行 docker info 确认），即可进入下一步的代码克隆环节。

二、克隆 Dify 源码与检出版本

Dify 的开源代码托管在 GitHub 上。在执行克隆前，建议选择一个拥有足够读写权限且磁盘剩余空间充裕的工作目录。克隆命令可以直接指定官方仓库地址：

# 1. 克隆官方 Git 仓库至本地当前目录
git clone https://github.com/langgenius/dify.git

# 2. 进入克隆完成的代码根目录
cd dify

# 3. 列出最近发布的版本标签（按需查看）
git tag -l --sort=-v:refname | head -n 10

# 4. 推荐检出一个稳定的 Release 版本（以具体的稳定标签为例，请替换为最新 Tag）
git checkout 0.15.3

许多初次接触 Dify 的用户往往直接在默认的 main 主分支上启动 Docker。这种做法存在显著的稳定性隐患。main 分支是核心开发分支，其数据库迁移脚本、环境变量项与 Docker 镜像可能正处于快速迭代中，一旦本地拉取的镜像版本与本地代码中的配置模板产生轻微脱节，极易导致启动时报出数据表缺失或配置项无法解析的错误。因此，明确执行 git checkout <tag_name> 锁定一个已发布的稳定版本是保证本地部署一次成功的关键操作。

三、配置环境变量与启动服务

Dify 的全部 Docker 部署编排资源均存放在源码的 docker 子目录中。进入该目录后，可以看到 docker-compose.yaml 文件以及环境变量配置文件模板 .env.example。

# 1. 进入 docker 配置子目录
cd docker

# 2. 从模板复制出正式的 .env 配置文件
cp .env.example .env

# 3. 后台编排拉起所有容器服务
docker compose up -d

执行 cp .env.example .env 后，本地即生成了一份生效的配置。对于绝大部分单机本地测试环境，直接使用模板生成的默认参数即可正常跑通。但在一些特定网络环境下，有几项关键配置需要按需核对：

• EXPOSE_NGINX_PORT：这是 Dify Web 控制台在宿主机上暴露的端口，默认为 80。如果本地宿主机已经安装了 Apache、Nginx 或其他服务占用了 80 端口，可在此处修改为 8080 或 3000 等可用端口。
• CONSOLE_API_URL 与 CONSOLE_WEB_URL：前端访问后端 API 的公开基础地址。如果是本地回环访问，保持默认的相对路径或 http://localhost 即可；如果准备让局域网内其他电脑访问，需要配置为本机的实际局域网 IP。
• 持久化卷路径：在 docker-compose.yaml 中，PostgreSQL 数据库、Redis 缓存以及用户上传的文件均挂载在 docker/volumes 目录下。切勿随意删除该目录，否则会导致所有应用与知识库数据丢失。

四、初始化访问与运行验证

当执行 docker compose up -d 后，Docker 会自动连接镜像仓库下载依赖的镜像。初次拉取通常需要几分钟，耗时取决于网络带宽。拉取完成后，所有容器会陆续启动。

此时应当运行命令查看容器集群的实际运行状态：

# 查看当前目录下运行中的容器列表
docker compose ps

在输出的容器列表中，应该看到 docker-api-1、docker-web-1、docker-worker-1、docker-db-1、docker-redis-1、docker-nginx-1 以及向量存储容器的状态均标记为 Up 或 Up (healthy)。如果某个核心容器的状态显示为 Exit 1 或 Restarting，则说明存在端口冲突或资源超限。

五、常见问题排查与日常维护

在实际部署与后续运行中，用户最常遇到的异常主要集中在网络端口冲突、宿主机资源限制以及容器更新迁移三方面。

1. 端口占用报错（Bind for 0.0.0.0:80 failed）

如果在执行 docker compose up -d 时终端提示端口 80 已被占用，只需使用文本编辑器打开 docker/.env 文件，找到 EXPOSE_NGINX_PORT=80 这一行，将其更改为未占用的自定义端口（例如 EXPOSE_NGINX_PORT=8090），随后重新执行启动命令即可：

# 停止并重新按新配置启动
docker compose up -d

2. 内存不足导致的数据库异常崩溃

如果浏览器提示“502 Bad Gateway”或者 API 无法连接，通常是后端 api 容器或 db 容器未能正常维持运行。通过查看容器日志可以迅速定位问题原因：

# 查看特定容器的最近日志输出
docker compose logs -f api
docker compose logs -f db

若在日志中发现包含 Killed 或 Cannot allocate memory，说明宿主机分配给 Docker 的内存不足。请在 Docker Desktop 的设置面板中调大内存上限（至少保证 6GB 到 8GB）。

3. 日常维护、平滑升级与数据备份

由于 Dify 的所有持久化数据均通过相对路径映射在 dify/docker/volumes 目录下，因此日常升级并不会破坏已有数据。正确的更新流程是先拉取官方最新的 Git 标签，随后通过 Docker 拉取对应的新镜像并重新拉起服务：

# 1. 进入本地 dify 根目录并拉取最新 tag
cd dify
git fetch --tags

# 2. 检出目标稳定版本
git checkout <target-tag>

# 3. 进入 docker 目录，先拉取新镜像，再平滑启动
cd docker
docker compose pull
docker compose up -d

按照上述流程，容器在重启时会自动比对数据库版本并执行必要的平滑迁移，从而在不丢失历史提示词、知识库文档与应用流编排的前提下，完成系统的无缝升级。