第 3 期：从源码部署 Dify 开发环境

更新于 2026/4/6

为什么需要源码部署？

Docker 部署虽然方便，但当你需要：

  • 调试 Dify 核心逻辑
  • 开发自定义 Plugin
  • 向开源社区贡献代码

你就需要搭建完整的源码开发环境。

架构分层

graph TB
    subgraph "本地开发环境"
        subgraph "基础服务 (Docker)"
            PG[(PostgreSQL)]
            Redis[(Redis)]
            Weaviate[(Weaviate)]
        end
        
        subgraph "API 后端 (Python)"
            Flask[Flask API :5001]
            Celery[Celery Worker]
        end
        
        subgraph "Web 前端 (Node.js)"
            Next[Next.js :3000]
        end
        
        Flask --> PG
        Flask --> Redis
        Flask --> Weaviate
        Celery --> PG
        Celery --> Redis
        Next --> Flask
    end

步骤一：启动基础服务

cd dify/docker
docker compose -f docker-compose.middleware.yaml up -d
# 只启动 PostgreSQL / Redis / Weaviate，不启动应用层

步骤二：API 后端

cd dify/api

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux

# 安装依赖
pip install -r requirements.txt

# 复制并配置 .env
cp .env.example .env

# 数据库迁移
flask db upgrade

# 启动 API 服务
flask run --host 0.0.0.0 --port 5001 --debug

步骤三：Celery 异步 Worker

# 新开一个终端，同一个虚拟环境
cd dify/api
source venv/bin/activate

celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,plugin

步骤四：Web 前端

cd dify/web

# 安装依赖
pnpm install

# 复制并配置环境变量
cp .env.example .env.local

# 确保 API 地址指向本地
# .env.local 中设置:
# NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
# NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api

# 启动开发服务器
pnpm dev

验证启动

# 检查 API 健康状态
curl http://localhost:5001/health
# 期望输出: {"status": "ok"}

# 检查前端
open http://localhost:3000/install

常用开发命令速查

# 运行后端测试
cd api && python -m pytest tests/ -v

# 运行前端 lint
cd web && pnpm lint

# 数据库迁移（修改 Model 后）
cd api && flask db migrate -m "your migration message"
cd api && flask db upgrade