Dify本地部署完整指南：源码与Docker启动-育师

Dify本地部署完整指南：源码与Docker启动

在AI应用开发日益普及的今天，如何快速搭建一个支持大模型编排、知识检索和Agent执行的可视化平台，成为许多开发者关注的问题。Dify 正是为此而生——它将复杂的 LLM 应用开发流程封装成直观的图形界面，让开发者无需深入底层也能高效构建智能客服、内容生成系统或企业级知识库问答引擎。

要真正掌握 Dify 的能力，最好的方式是从本地部署开始。无论是为了调试源码、定制功能，还是为后续生产环境做准备，亲手跑通整套服务都是不可或缺的第一步。本文将带你一步步完成 Dify 的全链路本地部署，涵盖从中间件配置到前后端启动的全过程，并提供源码与 Docker 两种主流方式的选择建议。

环境准备：打牢基础才能跑得更稳

Dify 并非单一服务，而是一个由多个组件协同工作的系统。它的核心依赖三个关键中间件：

PostgreSQL：存储用户信息、应用配置、会话记录等结构化数据；
Redis：作为缓存层和 Celery 异步任务队列的 Broker；
Weaviate：向量数据库，支撑 RAG（检索增强生成）能力，实现文档语义搜索。

这些服务如果手动逐个安装配置，不仅耗时还容易出错。幸运的是，Dify 提供了开箱即用的docker-compose配置文件，可以一键拉起整个中间件集群。

首先克隆项目源码：

git clone https://github.com/langgenius/dify.git cd dify

进入docker目录并复制环境变量模板：

cd docker cp middleware.env.example middleware.env

接下来启动中间件服务：

docker compose -f docker-compose.middleware.yaml up -d

这条命令会在后台运行以下容器：
-dify-postgres（PostgreSQL 13）
-dify-redis（Redis 7）
-dify-weaviate（Weaviate 1.19+）

⚠️ 注意：请确保本机未占用 5432（PostgreSQL）、6379（Redis）、8080（Weaviate HTTP）和 50051（gRPC）端口，否则可能导致服务无法绑定。

等待几秒钟后，可通过以下命令检查状态：

docker ps | grep dify-

当看到所有三个服务都处于Up状态时，说明中间件已准备就绪。

后端服务：API 层的核心逻辑

Dify 的后端基于 Flask 构建，结合 SQLAlchemy 实现 ORM 操作，使用 Celery 处理异步任务（如文档嵌入处理），并通过 RESTful 接口对外暴露能力。你可以选择通过源码运行或构建 Docker 镜像来启动 API 服务。

使用源码方式启动（推荐用于开发调试）

切换到api/目录：

cd ../api

复制环境配置文件：

cp .env.example .env

.env文件中包含多个重要参数，例如：

参数	默认值	说明
`DB_USERNAME`	`postgres`	数据库用户名
`DB_PASSWORD`	`postgres`	密码需与`middleware.env`中一致
`WEAVIATE_ENDPOINT`	`http://localhost:8080`	向量库访问地址
`REDIS_URL`	`redis://localhost:6379/1`	Redis 连接 URL

其中最敏感的是SECRET_KEY，建议使用 OpenSSL 自动生成高强度密钥：

awk -v key="$(openssl rand -base64 42)" '/^SECRET_KEY=/ {sub(/=.*/, "=" key)} 1' .env > temp_env && mv temp_env .env

Dify 使用 Poetry 管理 Python 依赖。如果你尚未安装 Poetry，可执行：

curl -sSL https://install.python-poetry.org | python3 -

然后创建虚拟环境并安装依赖：

poetry env use 3.10 poetry install

✅ 建议使用 Python 3.10，这是官方测试最稳定的版本。

首次部署需要初始化数据库表结构：

poetry shell flask db upgrade

该命令会根据migrations/目录中的脚本自动创建所有必要表，包括提示词模板、对话历史、知识库索引关系等。

一切就绪后，启动 API 服务：

flask run --host 0.0.0.0 --port=5001 --debug

此时服务已在http://localhost:5001可用，可通过健康检查接口验证：

curl http://localhost:5001/health

预期返回如下 JSON：

{ "status": "healthy", "version": "0.6.0" }

💡 小贴士：--debug模式支持代码热重载，适合开发阶段。但在生产环境中应改用 Gunicorn + Nginx 方案以提升性能和安全性。

使用 Docker 镜像方式启动（适用于快速部署）

对于希望避免环境冲突或进行标准化部署的用户，推荐使用 Docker 镜像方式。

在api/目录下构建镜像：

docker build -t dify-api .

随后运行容器：

docker run \ --name dify-api \ --network host \ -p 5001:5001 \ -d \ dify-api

🔁 若未使用host网络模式，请确保容器网络能正确访问宿主机上的 PostgreSQL、Redis 和 Weaviate 服务。可通过自定义 bridge 网络或添加--add-host参数解决通信问题。

你也可以挂载.env文件传入配置：

docker run \ --name dify-api \ -p 5001:5001 \ --env-file .env \ -d \ dify-api

查看日志确认运行状态：

docker logs -f dify-api

正常输出中应包含：

* Running on all addresses (0.0.0.0) * Running on http://127.0.0.1:5001

前端服务：交互入口的搭建

Dify 的前端采用 React + TypeScript 技术栈，基于 Vite 构建，UI 使用 Ant Design 组件库，提供了流畅的应用编排画布和 Prompt 调试面板。

源码方式启动（适合二次开发）

进入web/目录：

cd ../web

安装依赖：

npm install

✅ 推荐使用 npm 8+ 或 yarn。若遇到锁文件冲突，可用npm ci清除重建依赖树。

启动开发服务器：

npm run start

前端默认运行在http://localhost:3000，并通过vite.config.ts中的代理规则将/api请求转发至http://localhost:5001/api，有效规避跨域问题。

浏览器打开后将跳转至登录页。初始管理员账户可通过注册新用户创建，后续可在数据库中提权。

Docker 镜像方式启动（适合统一部署）

在web/目录下构建镜像：

docker build -t dify-web .

该镜像基于 Nginx，打包了编译后的静态资源。

运行容器：

docker run \ --name dify-web \ -p 3000:80 \ -d \ dify-web

⚙️ 如需将前端部署到非本地环境（如测试服务器），可在构建时动态注入 API 地址：

ARG VITE_API_BASE_URL=http://your-api-domain.com ENV VITE_API_BASE_URL=$VITE_API_BASE_URL

修改Dockerfile即可实现多环境适配。

访问http://localhost:3000即可进入 Dify 的可视化操作界面。

常见问题排查与实用建议

实际部署过程中难免遇到一些“小坑”，以下是几个高频问题及其解决方案：

❓ Weaviate 启动失败？

最常见的原因是内存不足。Weaviate 对资源要求较高，默认 Docker Desktop 分配的 2GB 内存可能不够用，建议调整为4GB 或以上。

如果只是临时测试且不依赖向量检索功能，可以在.env中关闭向量存储：

ENABLE_VECTOR_STORE=false

但注意这会导致知识库上传、RAG 查询等功能失效。

❓ 数据库迁移报错？

通常是因为 PostgreSQL 服务未启动或认证信息不匹配。重点检查：
-DB_PASSWORD是否与middleware.env中设置的一致；
- 容器是否正常运行（docker ps查看状态）；
- 是否有其他进程占用了 5432 端口。

可手动测试连接：

psql -h localhost -U postgres -p 5432 -c "SELECT version();"

输入密码postgres后应能成功返回版本号。

❓ 前端调用 API 失败？

常见原因包括：
- 后端监听的是127.0.0.1而非0.0.0.0，导致外部请求无法访问；
- 防火墙阻止了 5001 端口；
- 浏览器控制台出现 CORS 错误（不过在开发模式下已被代理解决，一般不会发生）。

建议始终使用--host 0.0.0.0启动 Flask 服务。

不同场景下的部署优化建议

场景	推荐方案
本地开发调试	源码部署 + 热更新，便于追踪日志和修改逻辑
团队协作测试	Docker Compose 统一编排，共享中间件配置
生产环境上线	使用独立 PostgreSQL/Redis/Weaviate 集群，配合 Nginx 反向代理和 HTTPS 加密
CI/CD 自动化	编写构建脚本，推送镜像至私有 registry，结合 Kubernetes 或 Nomad 编排

此外，若计划长期维护或参与社区贡献，建议开启 Git Hooks 并配置代码格式化工具（如 Prettier + Black），保持代码风格一致性。

整个部署流程走下来，你会发现 Dify 的架构设计非常清晰：前端负责交互体验，后端处理业务逻辑与模型调度，中间件各司其职，彼此解耦又紧密协作。这种模块化结构既方便调试，也利于未来扩展。

当你成功打开http://localhost:3000并看到 Dify 的主界面时，就意味着你已经拥有了一个完整的 LLM 应用开发沙箱。现在就可以尝试创建第一个 AI Agent、导入 PDF 知识库、设计多步骤 Prompt 工作流，真正体验“低代码+强能力”的 AI 开发新模式。