Dify-16: 开发环境配置
本指南提供了为 Dify 搭建本地开发环境的全面说明，涵盖 API 后端（Python 编写）和 Web 前端（Next.js 构建）组件。
系统架构概述
在深入搭建流程前，先了解开发过程中需要接触的 Dify 核心组件：
前置条件
必需软件
- Python：3.11 或 3.12 版本（API 后端必需）
- Node.js：v18.18.0 或更高版本（Web 前端必需）
- 包管理器：
- UV（Python 依赖管理）
- pnpm v10.x（JavaScript 依赖管理）
- Docker 与 Docker Compose：运行中间件服务
推荐开发工具
- IDE：Visual Studio Code 或其他支持 Python/JavaScript 的 IDE
- Git：版本控制工具
- 数据库客户端：查看 PostgreSQL 数据
中间件服务设置
Dify 需要通过 Docker Compose 运行的多个中间件服务。
使用 Docker Compose 运行中间件
-
进入 docker 目录：
cd docker -
创建中间件环境文件：
cp middleware.env.example middleware.env -
启动中间件服务：
# 默认使用 Weaviate 向量数据库 docker compose -f docker-compose.middleware.yaml --profile weaviate -p dify up -d
API 后端设置
配置
-
进入 API 目录：
cd api -
创建 .env 文件：
cp .env.example .env -
生成密钥：
# Linux sed -i "/^SECRET_KEY=/c\SECRET_KEY=$(openssl rand -base64 42)" .env # macOS secret_key=$(openssl rand -base64 42) sed -i '' "/^SECRET_KEY=/c\\ SECRET_KEY=${secret_key}" .env
安装依赖
API 后端使用 UV 管理依赖：
# 若未安装 UV，先安装
pip install uv
# 安装依赖
uv sync --dev
数据库迁移
首次运行前需迁移数据库：
uv run flask db upgrade
运行 API 服务器
启动开发模式的 API 服务器：
uv run flask run --host 0.0.0.0 --port=5001 --debug
运行 Celery Worker
处理数据集导入、文档索引等异步任务：
uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion
Web 前端设置
配置
-
进入 web 目录：
cd web -
创建
.env.local文件：cp .env.example .env.local -
配置环境变量（本地开发关键参数）：
NEXT_PUBLIC_API_PREFIX：控制台 API URL（默认：http://localhost:5001/console/api）NEXT_PUBLIC_PUBLIC_API_PREFIX：Web 应用 API URL（默认：http://localhost:5001/api）
安装依赖
Web 前端使用 pnpm 管理依赖：
# 若未安装 pnpm，先安装
npm install -g pnpm@10.8.0 # 安装依赖
pnpm install
运行 Web 服务器
启动开发模式的 Web 服务器：
pnpm run dev
Next.js 开发服务器将运行于 http://localhost:3000。
开发工作流程
目录结构
代码库主要组件：
api/：Python 后端（Flask）web/：Next.js 前端docker/：Docker 配置文件
测试
API 测试
cd api
# 运行所有测试
uv run bash dev/pytest/pytest_all_tests.sh # 仅运行单元测试
uv run bash dev/pytest/pytest_unit_tests.sh # 运行向量数据库（VDB）测试
uv run bash dev/pytest/pytest_vdb.sh
Web 测试
cd web
pnpm test
代码格式化与检查
API（Python）
# 格式化代码
uv run --directory api --dev ruff format ./ # 检查代码
uv run --directory api --dev ruff check ./
Web（JavaScript/TypeScript）
# 代码检查
pnpm run lint # 自动修复检查问题
pnpm run fix
使用 Docker 运行
若希望通过 Docker 容器运行完整栈，可使用提供的 Docker Compose 文件。
运行完整 Docker Compose 栈
-
创建环境文件：
cd docker cp .env.example .env -
启动所有服务：
docker compose up -d
将启动包括 API、Web、Worker、数据库和中间件的所有服务。
环境变量参考
理解关键环境变量对配置开发环境至关重要。
API 环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
| SECRET_KEY | 安全会话 Cookie 签名密钥 | （自动生成） |
| CONSOLE_API_URL | 控制台 API 后端 URL | http://127.0.0.1:5001 |
| CONSOLE_WEB_URL | 控制台 Web 前端 URL | http://127.0.0.1:3000 |
| DB_USERNAME | 数据库用户名 | postgres |
| DB_PASSWORD | 数据库密码 | difyai123456 |
| DB_HOST | 数据库主机 | localhost |
| DB_PORT | 数据库端口 | 5432 |
| DB_DATABASE | 数据库名称 | dify |
| REDIS_HOST | Redis 主机 | localhost |
| REDIS_PORT | Redis 端口 | 6379 |
| REDIS_PASSWORD | Redis 密码 | difyai123456 |
| VECTOR_STORE | 向量数据库类型 | weaviate |
Web 环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
| NEXT_PUBLIC_API_PREFIX | 控制台 API URL | http://localhost:5001/console/api |
| NEXT_PUBLIC_PUBLIC_API_PREFIX | Web 应用 API URL | http://localhost:5001/api |
| NEXT_PUBLIC_DEPLOY_ENV | 部署环境 | DEVELOPMENT |
| NEXT_PUBLIC_EDITION | 部署版本 | SELF_HOSTED |
组件关系图
以下图表展示了开发环境中关键代码组件的关系：
故障排查
常见问题与解决方案
- 数据库连接错误：
- 确保 PostgreSQL 在 Docker 中运行；
- 检查
.env文件中的数据库凭证； - 确认已通过
flask db upgrade迁移数据库。
- 向量数据库连接错误：
- 检查 Docker Compose 中是否启用了正确的向量数据库配置；
- 验证
.env中的向量数据库配置。
- Redis 连接错误：
- 确保 Redis 在 Docker 中运行；
- 检查
.env文件中的 Redis 凭证。
- 模块未找到错误：
- 在 API 目录运行
uv sync --dev确保依赖已安装； - 确认使用了正确的 Python 版本（3.11 或 3.12）。
- 在 API 目录运行
- 端口冲突：
- 若服务因端口冲突启动失败，修改 Docker Compose 文件或环境变量中的暴露端口。
开发技巧
-
使用便捷脚本：
dev/reformat：格式化 Python 代码；dev/pytest/pytest_unit_tests.sh：运行单元测试。
-
设置 Git 钩子：项目包含预提交检查的 Git 钩子，自动对修改文件运行代码检查。
-
监控日志：关注 API、Web 和 Worker 服务的日志，快速定位问题。
-
使用 Storybook：Web 前端集成了 Storybook 用于 UI 组件开发：
cd web && pnpm storybook -
IDE 配置：VSCode 用户可将
web/.vscode/settings.example.json重命名为web/.vscode/settings.json，启用代码检查配置。