开发指南

相关源文件

• .devcontainer/Dockerfile
• .devcontainer/README.md
• .devcontainer/devcontainer.json
• .devcontainer/noop.txt
• .devcontainer/post_create_command.sh
• .devcontainer/post_start_command.sh
• .devcontainer/troubleshooting.png
• .github/actions/setup-uv/action.yml
• .github/workflows/api-tests.yml
• .github/workflows/db-migration-test.yml
• .github/workflows/docker-build.yml
• .github/workflows/style.yml
• .github/workflows/vdb-tests.yml
• api/Dockerfile
• api/README.md
• api/constants/recommended_apps.json
• api/docker/entrypoint.sh
• api/events/app_event.py
• api/events/event_handlers/__init__.py
• api/events/event_handlers/delete_tool_parameters_cache_when_sync_draft_workflow.py
• api/migrations/README
• api/migrations/versions/5fda94355fce_custom_disclaimer.py
• api/migrations/versions/b2602e131636_add_workflow_run_id_index_for_message.py
• api/services/recommended_app_service.py
• dev/pytest/pytest_vdb.sh
• dev/reformat
• web/.husky/pre-commit
• web/Dockerfile
• web/README.md
• web/app/(commonLayout)/app/(appDetailLayout)/layout.tsx/app/(appDetailLayout)/layout.tsx)
• web/app/components/app/configuration/base/feature-panel/index.tsx
• web/app/components/app/configuration/config-vision/param-config.tsx
• web/app/components/header/maintenance-notice.tsx
• web/next.config.js

本指南为希望为 Dify 平台做出贡献或扩展 Dify 平台的开发者提供了全面的信息。它涵盖了开发环境设置、架构概述、开发工作流程、测试策略和贡献指南。

有关在生产环境中部署 Dify 的信息，请参阅 部署和配置。有关详细的 API 集成指南，请参阅 API 参考。有关后端或前端的具体开发任务，请参阅 后端开发 和 前端开发。

目的与范围

本开发指南涵盖

• 设置本地开发环境
• 理解代码库架构和关键组件
• 开发工作流程和最佳实践
• 测试策略和质量保证
• 代码标准和贡献指南
• 调试和排除开发问题

开发环境设置

先决条件

Dify 平台支持多种开发环境选项

环境	Python	Node.js	包管理器
本地开发	3.11-3.12	22.x	uv, pnpm 10.x
DevContainer	3.12	LTS	uv, pnpm
GitHub Codespaces	3.12	LTS	uv, pnpm

DevContainer 设置

推荐的开发方法是使用 VS Code DevContainers 以实现一致的环境

来源: .devcontainer/devcontainer.json .devcontainer/post_create_command.sh .devcontainer/post_start_command.sh

DevContainer 自动设置

• Python 环境，使用 uv 包管理器
• Node.js 环境，使用 pnpm
• Docker-in-Docker 用于中间件服务
• 预配置的 shell 别名，用于常用开发任务

本地开发设置

API 后端设置

1. 安装 Python 依赖项

2. 环境配置

3. 启动中间件服务

4. 初始化数据库

来源: api/README.md41-64 api/Dockerfile20-22

Web 前端设置

1. 安装 Node.js 依赖

2. 环境配置

3. 启动开发服务器

来源: web/README.md13-47 web/Dockerfile19-25

架构概述

核心组件映射

此图将高级系统组件与其对应的代码实体进行了映射

来源: api/Dockerfile27-28 web/Dockerfile2-3 .devcontainer/devcontainer.json api/README.md7-9

开发工作流程组件

此图展示了开发工具与流程之间的关系

来源: .github/workflows/style.yml48-53 dev/reformat8-12 web/.husky/pre-commit27-44 dev/pytest/pytest_vdb.sh

开发工作流程

API 开发工作流程

API 开发遵循以下模式

1. 服务层架构：业务逻辑组织在 services/ 目录中，具有专门的服务类
2. 控制器层：API 端点在 controllers/ 中使用 Flask blueprints 定义
3. 模型层：数据库模型在 models/ 目录中使用 SQLAlchemy ORM
4. 迁移管理：数据库模式更改使用 migrations/ 中的 Flask-Migrate

关键开发命令

任务	命令	描述
安装依赖项	uv sync --dev	安装所有开发依赖
运行 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	启动后台任务 worker
运行迁移	uv run flask db upgrade	应用数据库迁移
运行测试	uv run bash dev/pytest/pytest_all_tests.sh	执行完整的测试套件

来源: api/README.md66-78 api/docker/entrypoint.sh30-31

Web 开发工作流程

前端使用 Next.js 和 TypeScript

1. 组件架构：React 组件组织在 app/components/
2. 页面路由：App Router，布局组件位于 app/(routes)/
3. 状态管理：React hooks 和 context providers
4. 国际化：i18n 系统，支持多语言

关键开发命令

任务	命令	描述
安装依赖项	pnpm install	安装 Node.js 依赖
运行开发服务器	pnpm run dev	启动开发服务器
构建生产版本	pnpm run build	构建优化的生产 bundle
运行测试	pnpm run test	执行 Jest 测试套件
代码 Lint	pnpm run lint	运行 ESLint 检查

来源: web/README.md15-47 web/next.config.js22-67

Git 工作流程和提交前钩子

项目使用自动代码质量检查

来源: web/.husky/pre-commit14-78

测试策略

API 测试架构

API 测试基础设施非常全面，包含多种测试类型

来源: .github/workflows/api-tests.yml47-61 dev/pytest/pytest_vdb.sh .github/workflows/vdb-tests.yml79-83

测试执行环境

测试在隔离的环境中运行，使用 Docker 容器作为中间件服务

测试类型	依赖项	执行命令
单元测试	无	uv run bash dev/pytest/pytest_unit_tests.sh
工作流测试	沙箱、SSRF 代理	uv run bash dev/pytest/pytest_workflow.sh
工具测试	沙箱、SSRF 代理	uv run bash dev/pytest/pytest_tools.sh
VDB 测试	多个向量数据库	uv run bash dev/pytest/pytest_vdb.sh

来源: .github/workflows/api-tests.yml80-94 .github/workflows/vdb-tests.yml62-83

前端测试

Web 前端使用 Jest 进行单元测试

1. 组件测试：使用 React Testing Library 对 React 组件进行测试
2. 实用函数测试：对实用函数模块进行纯函数测试
3. 类型检查：TypeScript 编译检查
4. 暂存区 Lint：提交前对修改过的文件进行 Lint

来源: web/README.md95-108 web/.husky/pre-commit46-78

代码质量与标准

Python 代码标准

API 后端使用 ruff 进行代码格式化和 linting

1. 格式化: 使用 ruff format 自动格式化代码
2. Linting: 使用 ruff check 进行代码质量检查
3. 类型检查: 使用 mypy 进行静态类型分析
4. 导入排序: 自动组织导入语句

代码质量工具配置

来源: dev/reformat8-18 .github/workflows/style.yml48-57

前端代码标准

Web 前端使用 ESLint 和 TypeScript

1. ESLint 配置: 针对 React 和 TypeScript 的自定义规则
2. TypeScript 编译: 启用严格类型检查
3. 导入组织: 自动排序导入语句
4. 组件标准: 一致的 React 组件模式

来源: web/next.config.js46-55 .github/workflows/style.yml96-102

Docker 标准

API 和 Web 组件都使用多阶段 Docker 构建，以优化生产镜像

来源: api/Dockerfile1-80 web/Dockerfile1-77

贡献指南

开发流程

1. Fork 和 Clone: Fork 仓库并克隆到本地
2. 环境设置: 使用 DevContainer 或本地设置，如上所述
3. 创建分支: 从 main 分支创建功能分支
4. 代码开发: 遵循已建立的模式和约定
5. 测试: 确保所有测试在提交前通过
6. 代码质量: 运行 dev/reformat 来修复格式问题
7. Pull Request: 提交带有清晰描述和测试覆盖率的 PR

分支和提交标准

• 使用描述性的分支名称：feature/add-new-model-provider, fix/workflow-execution-bug
• 编写清晰的提交消息，遵循约定式提交格式
• 确保在推送更改前 pre-commit hooks 通过
• 为新功能和错误修复包含测试覆盖率

审查流程

所有代码更改都经过自动化检查

1. 样式验证: Python (Ruff) 和 TypeScript (ESLint) 样式检查
2. 类型检查: Python 使用 MyPy，前端使用 TypeScript 编译器
3. 测试执行: 单元测试、集成测试和 VDB 测试
4. Docker 构建: 多平台 Docker 镜像构建
5. 迁移测试: 数据库迁移验证

来源: .github/workflows/style.yml .github/workflows/api-tests.yml .github/workflows/docker-build.yml .github/workflows/db-migration-test.yml

环境变量和配置

开发需要正确的环境配置

• API 环境: 复制 api/.env.example 到 api/.env 并进行配置
• Web 环境: 复制 web/.env.example 到 web/.env.local 并进行配置
• Docker 环境: 复制 docker/.env.example 和 docker/middleware.env.example
• 密钥管理: 为本地开发生成安全的 SECRET_KEY 值

来源: api/README.md23-39 web/README.md19-41