开发环境设置

相关源文件

• .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 平台的本地开发环境设置，包括 DevContainer 支持、GitHub Codespaces 和传统的本地设置。本页面侧重于开发工作流程和工具设置。有关生产部署配置，请参阅 Docker 部署。有关环境变量和配置管理，请参阅 环境配置。

开发环境选项

Dify 支持多种开发环境方法，以适应不同的开发者偏好和限制。每种方法都提供了一个功能齐全的开发环境，支持热重载、调试功能和集成测试。

来源：.devcontainer/devcontainer.json1-52 api/README.md1-94 web/README.md1-119 .devcontainer/README.md1-38

先决条件和依赖

开发环境需要特定版本的核心工具和运行时依赖。该平台使用现代包管理器和开发工具，以确保不同设置中的环境一致。

组件	版本	包管理器	配置文件
Python	3.11+ / 3.12	UV 0.6.14	api/pyproject.toml, api/uv.lock
Node.js	22.11.x+	pnpm 10.11.1	web/package.json, web/pnpm-lock.yaml
Docker	最新版	Docker Compose v2	docker/docker-compose.middleware.yaml

来源：api/Dockerfile1-80 web/Dockerfile1-77 api/README.md43-56 web/README.md9-17

本地开发设置

本地开发提供了最快的开发体验，可以直接访问主机系统工具并获得最大的性能。此方法需要手动安装依赖项，但提供了对开发环境的最大控制。

API 服务设置

API 服务使用 UV 作为包管理器，取代了 1.3.0 版本之前的 Poetry 设置。开发服务器运行在端口 5001，并启用了热重载。

设置命令

1. 启动中间件服务

2. 配置 API 环境

3. 安装依赖项并运行迁移

4. 启动开发服务器

5. 启动后台工作进程（可选）

来源：api/README.md11-78 api/docker/entrypoint.sh1-42

Web 服务设置

Web 前端使用 Next.js 和 pnpm 作为包管理器。开发服务器运行在端口 3000，并支持热模块重载。

设置命令

1. 安装依赖项

2. 配置环境

3. 启动开发服务器

Web 服务连接到运行在端口 5001 的 API 服务。关键环境变量包括：

• NEXT_PUBLIC_API_PREFIX：控制台 API 端点（默认为 http://:5001/console/api）
• NEXT_PUBLIC_PUBLIC_API_PREFIX：公共 API 端点（默认为 http://:5001/api）

来源：web/README.md13-49 web/next.config.js16-67

DevContainer 开发

DevContainers 提供了一个一致的、容器化的开发环境，可与 VS Code 和 GitHub Codespaces 配合使用。该设置会自动配置所有依赖项和开发工具。

DevContainer 特性

• 基础镜像：mcr.microsoft.com/devcontainers/python:3.12
• Node.js：自动安装 LTS 版本
• Docker-in-Docker：已启用，用于运行中间件容器
• VS Code 扩展：预装 Python、Pylint 和 GitHub Copilot

设置过程

1. 自动安装依赖项（.devcontainer/post_create_command.sh1-15)

2. 开发别名（.devcontainer/post_create_command.sh7-12)

   • start-api：启动 Flask 开发服务器
   • start-worker：启动 Celery 工作进程
   • start-web：启动 Next.js 开发服务器
   • start-containers：启动 Docker 中间件

3. 运行时同步（.devcontainer/post_start_command.sh1-4)

来源：.devcontainer/devcontainer.json1-52 .devcontainer/Dockerfile1-5 .devcontainer/post_create_command.sh1-15 .devcontainer/post_start_command.sh1-4

GitHub Codespaces

GitHub Codespaces 提供基于云的开发环境，使用相同的 DevContainer 配置。此选项无需本地设置，即可在浏览器中提供完全配置的开发环境。

访问方法

• 直接链接：单击存储库中的“在 GitHub Codespaces 中打开”徽章
• 存储库界面：使用 GitHub 的 Codespaces 集成
• VS Code：通过 Remote-Containers 扩展进行连接

Codespaces 配置

• 自动使用 DevContainer 配置
• 默认提供 2 核、4GB RAM 的环境
• 包括服务（3000、5001 等）的端口转发
• 预装所有开发依赖项

已知问题

• 在 Codespaces 环境中，“/signin”端点可能会被阻止
• 解决方法：暂时使用其他端点进行身份验证，然后切换回来

来源：.devcontainer/README.md4-37

测试和代码质量

开发环境包括全面的测试和代码质量工具，这些工具会在 CI/CD 流水线中自动运行，并可以在开发过程中在本地执行。

API 测试命令

1. 单元测试

2. 配置测试

3. 代码格式化

Web 测试命令

1. 单元测试

2. 代码 Linting

提交前钩子：存储库包含提交前钩子，可自动对修改的文件运行 linting 和测试

• API 文件：运行 Ruff linting 和格式化
• Web 文件：对修改过的实用工具文件运行 ESLint 和单元测试
• 自动修复：尝试自动修复格式化问题

来源： .github/workflows/api-tests.yml47-94 dev/reformat1-19 web/.husky/pre-commit1-79 dev/pytest/pytest_vdb.sh1-22

开发工作流集成

开发环境与 GitHub Actions 集成，实现持续集成，为所有代码更改提供自动化测试和验证。

CI/CD集成

• API 测试：在 Python 3.11 和 3.12 上运行，实现完整的测试覆盖率
• 风格检查：强制执行代码格式和 linting 标准
• 向量数据库测试：验证与多个向量数据库的集成
• Docker 构建：测试多架构容器构建

开发命令摘要

任务	命令	描述
启动 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	后台任务处理
启动 Web	pnpm run dev	Next.js 开发服务器
运行测试	uv run bash dev/pytest/pytest_all_tests.sh	完整的测试套件
格式化代码	dev/reformat	自动修复 linting 问题
类型检查	dev/mypy-check	静态类型验证

来源： .github/workflows/api-tests.yml1-94 .github/workflows/style.yml1-184 .github/workflows/vdb-tests.yml1-84 api/docker/entrypoint.sh30-41