agentic_huge_data_base / wiki
页面 Dify · 11.1 开发环境设置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 11.1

11.1 · 开发环境设置（Development Environment Setup）

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目Dify 章节11.1 状态全文译文 模块安装与启动、测试、发布与运维、工作流与编排、配置治理
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Development Environment Setup 上一章11 下一章11.2
源码线索
  • .devcontainer/Dockerfile
  • .devcontainer/README.md
  • .devcontainer/devcontainer.json
  • .devcontainer/post_create_command.sh
  • .devcontainer/post_start_command.sh
  • .github/CODE_OF_CONDUCT.md
  • .github/dependabot.yml
  • .github/pull_request_template.md
  • .github/workflows/deploy-agent-dev.yml
  • .github/workflows/deploy-dev.yml
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 工作流与编排
  • 配置治理
  • 文档对象与元数据

章节正文

开发环境设置

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/11.1-development-environment-setup

开发环境搭建

相关源文件

本章引用的主要源码文件：

  • .devcontainer/Dockerfile
  • .devcontainer/README.md
  • .devcontainer/devcontainer.json
  • .devcontainer/post_create_command.sh
  • .devcontainer/post_start_command.sh
  • .github/CODE_OF_CONDUCT.md
  • .github/dependabot.yml
  • .github/pull_request_template.md
  • .github/workflows/deploy-agent-dev.yml
  • .github/workflows/deploy-dev.yml
  • .github/workflows/deploy-hitl.yml
  • .github/workflows/labeler.yml
  • .github/workflows/stale.yml
  • .gitignore
  • .vite-hooks/pre-commit
  • .vscode/README.md
  • .vscode/launch.json.template
  • CONTRIBUTING.md
  • Makefile
  • api/README.md
  • api/docker/entrypoint.sh
  • api/tasks/generate_summary_index_task.py
  • api/tasks/regenerate_summary_index_task.py
  • api/tasks/remove_document_from_index_task.py
  • api/tests/unit_tests/tasks/test_summary_queue_isolation.py
  • dev/setup
  • dev/start-api
  • dev/start-docker-compose
  • dev/start-web
  • dev/start-worker
  • dev/update-uv
  • e2e/README.md
  • e2e/features/smoke/unauthenticated-entry.feature
  • e2e/features/step-definitions/common/auth.steps.ts
  • e2e/features/step-definitions/common/navigation.steps.ts
  • e2e/features/step-definitions/smoke/install.steps.ts
  • web/service/fetch.spec.ts

本文档记录了如何为 Dify 平台配置本地开发环境。内容涵盖前提条件、安装脚本、服务编排、开发容器（Devcontainer）的使用以及调试配置。关于测试基础设施的信息，请参阅测试基础设施与策略。关于部署配置，请参阅环境配置与运行时模式。

目的与范围

本指南提供以下操作的说明：

  • 安装所需工具（Python 的 uv，Node.js 的 pnpm）。
  • 运行自动化安装脚本以初始化开发环境。
  • 在本地启动后端 API、前端 Web 和 Worker 服务。
  • 使用 VS Code 开发容器（Devcontainer）来保证开发环境的一致性。
  • 配置 VS Code 的调试配置，用于 API、Worker 和前端的调试。

前提条件

Dify 开发环境需要两个主要的包管理器：

工具用途最低版本
uvPython 包管理（v1.3.0 起替代 Poetry）最新版
pnpmNode.js 包管理9.x
Node.js前端运行时22.x (LTS)
Python后端运行时3.12
Docker中间件服务20.x+

来源： api/README.md:5-11, Makefile:44-44

开发环境搭建架构

下图展示了安装脚本、环境配置以及最终运行时服务之间的关系。

Dify · 开发环境搭建架构 · 图 1
Dify · 开发环境搭建架构 · 图 1

来源： api/README.md:13-58, dev/start-worker:86-129, Makefile:17-46

使用脚本进行自动化安装

仓库在 dev/ 目录下提供了辅助脚本，这些脚本会基于自身位置解析路径，因此可以从仓库中的任何位置运行。此外，还提供了一个 Makefile 用于标准操作。

初始安装
# 使用 dev 脚本
./dev/setup

# 或使用 Makefile
make dev-setup

Makefile 中的 dev-setup 目标会执行以下操作：

  1. prepare-docker：将 docker/envs/middleware.env.example 复制为 docker/middleware.env，并启动中间件栈。Makefile:22-31
  2. prepare-web：将 web/.env.example 复制为 web/.env.local，并运行 pnpm install。Makefile:34-39
  3. prepare-api：将 api/.env.example 复制为 api/.env，运行 uv sync --dev，并执行 flask db upgrade。Makefile:41-46

来源： api/README.md:17-21, api/README.md:43-43, Makefile:18-19

环境变量配置

运行安装脚本后，请检查并修改以下文件：

文件用途关键变量
api/.env后端配置SECRET_KEY, DB_*, REDIS_*, VECTOR_STORE
web/.env.local前端配置NEXT_PUBLIC_API_URL, NEXT_PUBLIC_DEPLOY_ENV
docker/middleware.env中间件服务配置POSTGRES_*, REDIS_*, WEAVIATE_*
生成 SECRET_KEY

必须生成 SECRET_KEY 以确保安全的会话管理：

# Linux
sed -i "/^SECRET_KEY=/c\\SECRET_KEY=$(openssl rand -base64 42)" api/.env

# macOS
secret_key=$(openssl rand -base64 42)
sed -i '' "/^SECRET_KEY=/c\\
SECRET_KEY=${secret_key}" api/.env

重要提示： 当前端和后端运行在不同的子域名下时，需要设置 COOKIE_DOMAIN 为网站的顶级域名（例如 example.com），以便共享认证 Cookie。api/README.md:61-63

来源： api/README.md:59-79

服务启动顺序

标准的本地开发流程是：先启动中间件，然后是 API，最后是前端和后台 Worker。

Dify · 服务启动顺序 · 图 2
Dify · 服务启动顺序 · 图 2
启动中间件服务
./dev/start-docker-compose

此命令会使用 docker/middleware.env 中定义的环境，以分离模式（detached mode）启动必要的中间件（PostgreSQL、Redis 和默认的向量数据库）。api/README.md:25-29

启动 API 服务
./dev/start-api

此脚本会：

  1. 通过 flask upgrade-db 运行数据库迁移。api/docker/entrypoint.sh:11-13
  2. 在 0.0.0.0:5001 上以调试模式启动 Flask 开发服务器。api/docker/entrypoint.sh:121-124

来源： api/README.md:31-35

启动 Worker 服务
# 使用默认队列启动（基于版本）
./dev/start-worker

# 使用特定队列启动
./dev/start-worker --queues dataset,workflow --concurrency 2

dev/start-worker 脚本使用 uv run 来执行 Celery Worker。它支持多个 CLI 选项，便于开发：

  • -q, --queues：逗号分隔的队列列表。
  • -c, --concurrency：Worker 进程数（默认：1）。
  • -P, --pool：池实现（默认：gevent）。
  • --loglevel：日志级别（默认：INFO）。

来源： dev/start-worker:1-129, api/README.md:47-51

Worker 队列配置

如果未指定，队列会根据 EDITION 环境变量自动配置。社区版（SELF_HOSTED）包含 workflow 队列，而 CLOUD 版则使用特定于层级的队列。api/docker/entrypoint.sh:35-45

版本默认队列
SELF_HOSTEDapi_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution
CLOUD将 workflow 替换为 workflow_professional,workflow_team,workflow_sandbox。

来源： api/docker/entrypoint.sh:34-45, dev/start-worker:103-114

开发容器（Devcontainer）

Dify 提供了一个预配置的 VS Code 开发容器，以确保环境一致性。

开发容器配置

该环境基于 python:3.12-bookworm，并包含了数值库所需的系统依赖。.devcontainer/Dockerfile:1-5

特性实现
基础镜像mcr.microsoft.com/devcontainers/python:3.12-bookworm
系统依赖libgmp-dev, libmpfr-dev, libmpc-dev
辅助别名

post_create_command.sh 脚本会安装 uv，在 web 目录下执行 pnpm install，并在 ~/.bashrc 中设置几个方便的 bash 别名：

  • start-api：在 5001 端口运行 Flask 开发服务器。
  • start-worker：使用标准队列和 threads 池运行 Celery Worker。
  • start-web：为前端运行 pnpm dev:inspect。
  • start-containers：使用 docker-compose.middleware.yaml 启动中间件栈。
  • stop-containers：停止中间件栈。

来源： .devcontainer/post_create_command.sh:1-17

VS 代码启动配置

.vscode/launch.json.template 提供了主要的调试目标。

配置关联

下图展示了 VS Code 启动配置与其各自的入口点和参数之间的映射关系。

Dify · 配置关联 · 图 3
Dify · 配置关联 · 图 3

来源： .vscode/launch.json.template:1-55

调试详情
  1. Python: API (gevent)：直接执行 api/app.py。它使用虚拟环境路径 ${workspaceFolder}/api/.venv/bin/python。.vscode/launch.json.template:5-13
  2. Python: Celery Worker (Solo)：运行 celery 模块。它使用 solo 池（-P solo）来确保任务在与调试器相同的进程中运行，这对于在异步任务代码中命中断点至关重要。.vscode/launch.json.template:15-36
  3. Next.js: debug full stack：使用 --inspect 参数运行 Next.js 二进制文件。它包含一个 serverReadyAction，用于在 Next.js 服务器就绪时自动启动 Chrome 并附加调试器。.vscode/launch.json.template:38-52

代码质量与测试

本地环境已配置为通过 Makefile 执行以下质量检查：

# 运行所有格式化工具和 linter
make lint

# 运行类型检查（pyrefly + mypy）
make type-check

# 运行后端单元测试
make test

来源： Makefile:67-112, api/README.md:98-103

使用 uv 进行测试

如需直接使用 uv 包管理器进行测试：

# 安装开发依赖
cd api && uv sync --group dev

# 运行所有测试
uv run pytest

# 运行特定测试组
uv run pytest tests/unit_tests/
uv run pytest tests/integration_tests/

来源： api/README.md:83-96