本指南为希望为 Dify 贡献代码或扩展其功能的开发者提供全面指导，涵盖本地开发环境搭建、代码库架构理解、测试运行，以及自定义模型提供方或 UI 组件等扩展功能的实现方法。
开发环境搭建
Dify 包含两个主要组件：API 后端（Python/Flask）和 Web 前端（Next.js），本地开发需同时配置这两部分。
前置条件
- Python：3.11 或 3.12 版本
- Node.js：18.18.0 或更高版本
- PNPM：10.x 版本（用于 Web 开发）
- UV：Python API 开发的包管理器
- Docker & Docker Compose：运行中间件服务（数据库、Redis、向量存储等）
后端（API）设置
-
启动中间件服务（Docker Compose）：
cd docker cp middleware.env.example middleware.env docker compose -f docker-compose.middleware.yaml --profile weaviate -p dify up -d cd ../api -
配置环境变量：
cp .env.example .env # Linux 生成密钥 sed -i "/^SECRET_KEY=/c\SECRET_KEY=$(openssl rand -base64 42)" .env # Mac 生成密钥 secret_key=$(openssl rand -base64 42); sed -i '' "/^SECRET_KEY=/c\\SECRET_KEY=${secret_key}" .env -
安装依赖
pip install uv uv sync --dev -
应用数据库迁移：
uv run flask db upgrade -
启动 API 开发服务器：
uv run flask run --host 0.0.0.0 --port=5001 --debug -
启动异步任务 Worker（数据集导入等）：
uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion
前端（Web）设置
-
安装依赖：
cd web pnpm install -
配置环境：
cp .env.example .env.local -
启动开发服务器：
pnpm run devWeb 界面将在
http://localhost:3000可用。
架构概述
Dify 采用基于微服务的架构，组件通过容器化实现部署和扩展。
架构图：Dify 开发架构
组件概述
- API 后端（Flask）：
分层架构包括控制器（处理 HTTP 请求）、服务层（业务逻辑）、数据模型（数据库模式）和扩展（外部系统集成），并通过 Celery 处理异步任务（文档索引、数据集处理、邮件发送等）。 - Web 前端（Next.js）：
包含控制台界面（创建和管理 AI 应用）、应用界面（用户交互）和可复用组件库。 - 中间件服务（Docker）：
包括 PostgreSQL（主数据库）、Redis（缓存和消息代理）、向量数据库（存储文档嵌入）、沙箱（安全代码执行）、插件守护进程（插件管理）和 SSRF 代理（出站请求安全）。
开发工作流程
环境变量
Dify 通过环境变量配置，主要文件包括：
api/.env：API 后端配置web/.env.local：Web 前端配置docker/.env：Docker 部署配置docker/middleware.env：中间件服务配置
工作流流程
使用开发环境
在为 Dify 开发时，通常需要执行以下操作：
- 通过 Docker Compose 运行中间件服务
- 以调试模式运行 Flask 开发的 API 后端
- 以开发模式运行 Next.js 开发的 Web 前端
- 进行代码修改并实时查看更改效果
- 运行测试以确保更改不会破坏现有功能
对于更复杂的工作流，可能还需要：
- 运行 Celery 工作进程处理异步任务
- 设置和与向量数据库进行交互
- 测试插件功能
扩展 Dify
添加模型提供方
- 在对应模块创建新提供方实现；
- 实现文本生成、嵌入等模型类型的接口；
- 在提供方管理器中注册新提供方；
- 更新 UI 显示新提供方选项。
向量数据库集成
- 在
core/rag/datasource/vdb目录创建新数据库实现； - 实现向量数据库接口（创建、删除、搜索等）；
- 在向量工厂（Vector Factory）中注册新数据库。
插件开发
- 创建插件包并实现接口；
- 向插件守护进程注册插件。
前端组件开发
-
在对应目录创建新组件；
-
使用现有组件和样式保持一致性；
-
通过 Storybook 调试组件：
cd web && pnpm storybook访问
http://localhost:6006查看组件库。
国际化（i18n）
Dify 支持多语言。若要添加或更新翻译，请执行以下步骤：
- 将新的翻译字符串添加到相应的 JSON 文件中
- 在组件中使用翻译钩子
- 运行 i18n 检查命令以确保所有翻译保持同步：
cd web
pnpm check-i18n
测试
Dify 拥有针对 API 后端和 Web 前端的全面测试套件。
API 测试
API 后端使用 pytest 进行测试，包含多个测试脚本：
- 单元测试：对单个组件进行独立测试
- 集成测试：测试组件之间的交互逻辑
- 向量数据库测试：测试与各种向量数据库的集成功能
要运行 API 测试：
# 运行所有 API 测试
cd api && uv run bash dev/pytest/pytest_all_tests.sh
# 仅运行向量数据库测试
cd api && uv run bash dev/pytest/pytest_vdb.sh
Web 测试
使用 Jest 和 React Testing Library：
cd web && pnpm test
代码检查与格式化
Dify 通过代码检查工具和格式化工具维护代码质量：
- API 后端：使用 Ruff 检查和格式化 Python 代码
- Web 前端：使用 ESLint 检查 JavaScript/TypeScript 代码
运行代码检查
# API 后端（Python）
cd api
uv run ruff check ./ # 运行代码检查
uv run ruff format ./ # 自动格式化代码
# Web 前端（JavaScript/TypeScript）
cd web
pnpm run lint # 运行代码检查
可通过以下脚本一键重新格式化代码：
./dev/reforma
生产环境构建
Docker 构建
Dify 在生产部署中使用 Docker。API 和 Web 组件的 Dockerfile 位于各自的目录中。
要构建 Docker 镜像：
# 构建 API 镜像
docker build -t dify-api:latest ./api
# 构建 Web 镜像
docker build -t dify-web:latest ./web
# 完整部署（Docker Compose）
cd docker && cp .env.example .env && docker-compose up -d
生产配置注意事项
- 设置
DEBUG=false关闭调试模式； - 配置数据库连接、存储和安全密钥；
- 参考
.env.example完成生产环境变量配置。
常见问题排查
向量数据库连接问题：
- 确保数据库服务运行；
- 检查
.env中的配置； - 验证数据库初始化；
插件守护进程故障：
- 查看守护进程日志；
- 检查配置和通信端口。
Worker 不处理任务：
- 确认 Redis 运行正常；
- 检查 Celery Worker 日志和队列订阅。
开发命令参考
# 启动 API 服务器
cd api && uv run flask run --host 0.0.0.0 --port=5001 --debug
# 启动 Celery Worker
cd api && uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion
# 运行API测试
cd api && uv run bash dev/pytest/pytest_all_tests.sh
# 启动 Web 开发服务器
cd web && pnpm run dev
# 运行 Web 测试
cd web && pnpm test
# 启动 Storybook
cd web && pnpm storybook
扫一扫
3162
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
