Dify 本地源码部署指南

本指南将帮助您从零开始在本地部署 Dify，包括所有必要的软件安装、中间件和模块的详细介绍，以及常见问题处理。

参考资料：

dify本地源码启动文档

docs.dify.ai/zh-hans/get...

1. Dify 架构概述

Dify 是一个 LLM 应用开发平台，其架构由以下几个主要部分组成：

前端 (Web) ：基于 Next.js 构建的用户界面，提供应用管理、对话界面等功能
后端 (API) ：基于 Flask 构建的 API 服务，处理业务逻辑和数据管理
Worker：基于 Celery 的异步任务处理服务，负责处理耗时操作
中间件：包括数据库、缓存、向量数据库等支持服务

2. 环境准备

2.1 安装 Docker

Docker 是运行 Dify 中间件服务（数据库、Redis 等）的必要工具。

MacOS 安装步骤：

perl 复制代码

# 使用 Homebrew 安装 Docker
brew install --cask docker

# 启动 Docker Desktop
open /Applications/Docker.app

常见问题：

问题：安装时提示 Error: It seems there is already a Binary at '/usr/local/bin/docker'
解决方案 ：使用 --force 选项强制安装
css 复制代码
```
brew install --cask --force docker
```
问题：安装后 docker 命令找不到
解决方案：确保 Docker Desktop 应用已启动，或重启终端

2.2 安装 Python 环境

Dify 后端需要 Python 3.12 和 Poetry 包管理工具。

bash 复制代码

# 安装 Python 3.12（如果尚未安装）
brew install [email protected]

# 安装 Poetry
curl -sSL https://install.python-poetry.org | python3 -

# 将 Poetry 添加到 PATH
echo 'export PATH="/Users/$USER/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
poetry --version

2.3 安装 Node.js 环境

Dify 前端需要 Node.js v18+ 和 pnpm。

perl 复制代码

# 安装 Node.js
brew install node@18

# 安装 pnpm
npm install -g pnpm

# 验证安装
node --version
pnpm --version

2.4 安装其他依赖

bash 复制代码

# 安装 libmagic（用于文件类型检测）
brew install libmagic

3. 获取 Dify 源码

bash 复制代码

# 克隆 Dify 仓库
git clone https://github.com/langgenius/dify.git
cd dify

4. 中间件服务详解

Dify 依赖多个中间件服务，每个服务都有特定的功能：

4.1 PostgreSQL

作用：主数据库，存储用户、应用、对话等核心数据。

配置：默认运行在端口 5432 上，用户名 postgres，密码在 middleware.env 中配置。

4.2 Redis

作用：

缓存服务，提高系统响应速度
消息队列代理，支持 Celery 异步任务
存储临时数据，如用户会话

配置：默认运行在端口 6379 上，无密码（如果设置了密码，需要在 .env 文件中配置）。

4.3 Weaviate

作用：向量数据库，用于存储和检索向量嵌入，支持知识库的语义搜索功能。

配置：默认运行在端口 8080 上。

4.4 Plugin Daemon

作用：插件守护进程，负责管理和执行 Dify 的插件。

配置：默认运行在端口 5002-5003 上。

4.5 Sandbox

作用：提供安全的代码执行环境，用于运行用户定义的代码。

4.6 SSRF Proxy

作用：防止服务器端请求伪造（SSRF）攻击的代理服务。

配置：默认运行在端口 3128 和 8194 上。

5. 启动中间件服务

注意：启动前先检查端口号是否被占用

bash 复制代码

# 进入 docker 目录
cd docker

# 创建中间件环境配置文件
cp middleware.env.example middleware.env

# 启动中间件服务
docker compose -f docker-compose.middleware.yaml --env-file middleware.env up -d

常见问题：

问题：Redis 连接错误 AUTH <password> called without any password configured

解决方案 ：修改 API 的 .env 文件，移除 Redis 密码

bash 复制代码

# 将 Redis 密码设置为空
sed -i '' 's/CELERY_BROKER_URL=redis://:difyai123456@localhost:6379/1/CELERY_BROKER_URL=redis://localhost:6379/1/' .env
sed -i '' 's/REDIS_PASSWORD=difyai123456/REDIS_PASSWORD=/' .env

6. Dify API 服务详解

API 服务是 Dify 的核心后端，负责处理所有业务逻辑和数据操作。

6.1 主要模块

app：应用主模块，包含 Flask 应用实例和配置
controllers：控制器，处理 HTTP 请求和响应
models：数据模型，定义数据库结构
services：业务服务，实现核心功能
extensions：扩展模块，如数据库、缓存等
tasks：异步任务定义
libs：通用库和工具函数

6.2 配置并启动 API 服务

bash 复制代码

# 进入 api 目录
cd ../api

# 创建 Python 虚拟环境
poetry env use 3.12
poetry install

# 创建环境配置文件
cp .env.example .env

# 激活虚拟环境
source .venv/bin/activate

# 初始化数据库
flask db upgrade

# 启动 API 服务
flask run --host 0.0.0.0 --port=5001 --debug

常见问题：

问题：端口 5001 被占用
解决方案 ：使用不同的端口，例如 --port=5002，并相应更新 Web 服务的配置
问题：poetry: command not found
解决方案 ：确保已将 Poetry 添加到 PATH，或使用完整路径 /Users/$USER/.local/bin/poetry

7. Worker 服务详解

Worker 服务基于 Celery 构建，用于处理异步任务，避免阻塞主 API 服务。

7.1 主要任务类型

dataset：知识库相关任务，如文档导入、索引创建
generation：生成内容相关任务，如长文本生成
mail：邮件发送任务
ops_trace：操作跟踪和监控任务

7.2 启动 Worker 服务

bash 复制代码

# 在新的终端窗口中，进入 api 目录
cd api

# 激活虚拟环境
source .venv/bin/activate

# 启动 Worker 服务
celery -A app.celery worker -P gevent -c 1 -Q dataset,generation,mail,ops_trace --loglevel INFO

常见问题：

问题：source: no such file or directory: .venv/bin/activate
解决方案 ：确保当前目录是 api 目录，而不是项目根目录
问题：Redis 连接错误
解决方案：确保 Redis 配置正确，密码设置与 Docker 中的 Redis 实例一致

8. Web 服务详解

Web 服务是 Dify 的前端界面，基于 Next.js 构建，提供用户交互界面。

8.1 主要模块

app：Next.js 应用主目录，包含页面和路由
components：UI 组件
context：React 上下文，管理全局状态
hooks：自定义 React Hooks
models：数据模型和类型定义
service：API 服务调用
utils：工具函数

8.2 配置并启动 Web 服务

shell 复制代码

# 进入 web 目录
cd ../web

# 安装依赖
pnpm install

# 创建环境配置文件
cp .env.example .env.local

# 修改环境配置，确保 API 端点指向正确的端口
# 编辑 .env.local 文件，设置以下内容：
# NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
# NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api

# 启动 Web 服务
pnpm run dev

常见问题：

问题：API 端点配置错误，导致前端无法连接后端
解决方案 ：确保 .env.local 中的 API 端点与实际运行的 API 服务端口一致

9. Dify 功能模块详解

9.1 应用管理

功能：创建和管理不同类型的 AI 应用，如聊天助手、文本生成等。

相关模块：

API: controllers/console/app
Web: app/apps

9.2 知识库

功能：创建和管理知识库，支持文档导入、分段和检索。

相关模块：

API: controllers/console/datasets
Web: app/datasets

9.3 对话管理

功能：管理用户与 AI 的对话历史。

相关模块：

API: controllers/console/conversation
Web: app/conversations

9.4 提示词管理

功能：创建和管理提示词模板。

相关模块：

API: controllers/console/prompt
Web: app/prompts

9.5 工作流

功能：创建复杂的 AI 工作流，组合多个步骤和条件。

相关模块：

API: controllers/console/workflow
Web: app/workflows

9.6 AI 提供商管理

功能：配置和管理 AI 模型提供商，如 OpenAI、Anthropic 等。

相关模块：

API: controllers/console/providers
Web: app/providers

10. 访问 Dify

现在，您可以通过浏览器访问 Dify：

打开浏览器，访问 http://localhost:3000
首次访问时，您需要注册一个管理员账户
注册完成后，您将自动登录到 Dify 控制台

11. 配置 AI 提供商

要使用 Dify 的功能，您需要配置至少一个 AI 提供商：

登录后，点击左侧菜单中的"设置"
选择"AI 提供商"选项卡
点击"添加"按钮，选择您想要添加的 AI 提供商（如 OpenAI、Anthropic 等）
输入相应的 API 密钥和其他必要信息
点击"保存"按钮

12. 完整启动命令汇总

每次启动 Dify，您需要按顺序执行以下命令：

bash 复制代码

# 1. 确保 Docker 已启动并且中间件服务正在运行
cd docker
docker compose -f docker-compose.middleware.yaml --env-file middleware.env up -d

# 2. 启动 API 服务
cd ../api
source .venv/bin/activate
flask run --host 0.0.0.0 --port=5001 --debug

# 3. 启动 Worker 服务（在新的终端窗口）
cd api
source .venv/bin/activate
celery -A app.celery worker -P gevent -c 1 -Q dataset,generation,mail,ops_trace --loglevel INFO

# 4. 启动 Web 服务（在新的终端窗口）
cd web
pnpm run dev

13. 环境变量详解

13.1 API 服务环境变量

FLASK_APP：Flask 应用入口
FLASK_DEBUG：是否启用调试模式
SECRET_KEY：应用密钥，用于会话加密
SQLALCHEMY_DATABASE_URI：数据库连接 URI
REDIS_HOST/PORT/PASSWORD：Redis 连接信息
CELERY_BROKER_URL：Celery 消息队列代理 URL
UPLOAD_DIR：文件上传目录
VECTOR_STORE_TYPE：向量存储类型（如 weaviate）

13.2 Web 服务环境变量

NEXT_PUBLIC_API_PREFIX：API 服务的控制台 API 端点
NEXT_PUBLIC_PUBLIC_API_PREFIX：API 服务的公共 API 端点
NEXT_PUBLIC_DEPLOY_ENV：部署环境（DEVELOPMENT/PRODUCTION）
NEXT_PUBLIC_EDITION：部署版本（SELF_HOSTED/CLOUD）

14. 常见问题总结

Docker 安装问题
- 使用 --force 选项解决冲突
- 确保 Docker Desktop 应用已启动
Poetry 安装问题
- 确保 Poetry 已添加到 PATH
- 使用完整路径执行命令
端口冲突
- 更改端口号，并相应更新配置
Redis 连接问题
- 确保 Redis 密码配置与实际一致
- 如果 Docker 中的 Redis 没有设置密码，则在配置中移除密码
虚拟环境激活问题
- 确保在正确的目录下执行命令
- 确保虚拟环境已创建
API 和 Web 服务连接问题
- 确保 Web 服务的环境配置中 API 端点与实际运行的 API 服务端口一致
文件类型检测问题
- 安装 libmagic：brew install libmagic

数据库迁移问题

如果遇到数据库迁移错误，尝试重置数据库：

css 复制代码

docker compose -f docker-compose.middleware.yaml --env-file middleware.env down -v
docker compose -f docker-compose.middleware.yaml --env-file middleware.env up -d
flask db upgrade

Worker 无法启动问题
- 检查 Celery 版本兼容性
- 确保 gevent 已正确安装
知识库导入失败
- 检查 Worker 服务是否正常运行
- 检查文件格式是否支持

15. 性能优化建议

增加 Worker 数量：对于大规模部署，可以增加 Worker 数量提高并发处理能力
css 复制代码
```
celery -A app.celery worker -P gevent -c 4 -Q dataset,generation,mail,ops_trace --loglevel INFO
```
使用生产级 Web 服务器：在生产环境中，使用 Gunicorn 或 uWSGI 替代 Flask 开发服务器
css 复制代码
```
gunicorn -w 4 -b 0.0.0.0:5001 app:app
```
启用 Redis 持久化：防止数据丢失
ini 复制代码
```
# 在 middleware.env 中添加
REDIS_APPENDONLY=yes
```
配置 PostgreSQL 优化：调整连接池大小和查询缓存
使用 CDN：对于公开部署的实例，使用 CDN 加速静态资源

按照本指南操作，应该能够成功在本地部署 Dify。