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

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:44:31.287Z

翻译模型：deepseek-chat

原文字符数：13749

项目：Dify (dify)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

开发环境搭建

目的与范围

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

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

前提条件

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

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

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

开发环境搭建架构

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

graph TB
    subgraph "安装阶段"
        SetupScript["dev/setup 脚本"]
        EnvCopy["复制 .env 文件"]
        APIDeps["uv sync --group dev"]
        WebDeps["pnpm install"]
    end

    subgraph "配置文件"
        APIEnvExample["api/.env.example"]
        APIEnv["api/.env"]
        WebEnvExample["web/.env.example"]
        WebEnvLocal["web/.env.local"]
        MiddlewareEnvExample["docker/envs/middleware.env.example"]
        MiddlewareEnv["docker/middleware.env"]
    end

    subgraph "服务启动"
        StartDocker["dev/start-docker-compose"]
        StartAPI["dev/start-api"]
        StartWeb["dev/start-web"]
        StartWorker["dev/start-worker"]
        StartBeat["dev/start-beat"]
    end

    subgraph "运行时服务"
        Middleware["PostgreSQL + Redis + Weaviate"]
        API["Flask API :5001"]
        Web["Next.js :3000"]
        Worker["Celery Worker"]
        Beat["Celery Beat"]
    end

    SetupScript --> EnvCopy
    SetupScript --> APIDeps
    SetupScript --> WebDeps

    EnvCopy --> APIEnv
    EnvCopy --> WebEnvLocal
    EnvCopy --> MiddlewareEnv

    APIEnvExample -.模板.-> APIEnv
    WebEnvExample -.模板.-> WebEnvLocal
    MiddlewareEnvExample -.模板.-> MiddlewareEnv

    StartDocker --> Middleware
    StartAPI --> API
    StartWeb --> Web
    StartWorker --> Worker
    StartBeat --> Beat

    API --> Middleware
    Worker --> Middleware
    Beat --> Middleware

来源： 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 目标会执行以下操作：

prepare-docker：将 docker/envs/middleware.env.example 复制为 docker/middleware.env，并启动中间件栈。Makefile:22-31
prepare-web：将 web/.env.example 复制为 web/.env.local，并运行 pnpm install。Makefile:34-39
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。

sequenceDiagram
    participant Dev as 开发者
    participant Docker as Docker Compose
    participant Middleware as 中间件服务
    participant API as Flask API
    participant Worker as Celery Worker
    participant Web as Next.js

    Dev->>Docker: ./dev/start-docker-compose
    Docker->>Middleware: 启动 PostgreSQL, Redis, VectorDB
    Middleware-->>Dev: 服务就绪

    Dev->>API: ./dev/start-api
    API->>API: flask upgrade-db
    API->>Middleware: 连接 DB/Redis
    API-->>Dev: API 监听 :5001

    Dev->>Worker: ./dev/start-worker
    Worker->>Middleware: 连接 Redis 消息代理
    Worker-->>Dev: Worker 处理队列

    Dev->>Web: ./dev/start-web
    Web->>API: 代理请求
    Web-->>Dev: Web UI 在 :3000

启动中间件服务

./dev/start-docker-compose

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

启动 API 服务

./dev/start-api

此脚本会：

通过 flask upgrade-db 运行数据库迁移。api/docker/entrypoint.sh:11-13
在 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_HOSTED`	`api_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 启动配置与其各自的入口点和参数之间的映射关系。

graph LR
    subgraph "VS Code 调试器"
        Launch["launch.json"]
    end

    subgraph "Python: API (gevent)"
        API_Target["api/app.py"]
        API_CWD["cwd: api"]
    end

    subgraph "Python: Celery Worker (Solo)"
        Worker_Module["module: celery"]
        Worker_Args["args: -A app.celery worker -P solo -c 1"]
    end

    subgraph "Next.js: 调试全栈"
        Web_Bin["web/node_modules/next/dist/bin/next"]
        Web_Inspect["runtimeArgs: --inspect"]
    end

    Launch --> API_Target
    Launch --> Worker_Module
    Launch --> Web_Bin

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

调试详情

Python: API (gevent)：直接执行 api/app.py。它使用虚拟环境路径 ${workspaceFolder}/api/.venv/bin/python。.vscode/launch.json.template:5-13
Python: Celery Worker (Solo)：运行 celery 模块。它使用 solo 池（-P solo）来确保任务在与调试器相同的进程中运行，这对于在异步任务代码中命中断点至关重要。.vscode/launch.json.template:15-36
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