bntcloudcom/dify-api

Dify Backend API

概述

Dify Backend API是Dify应用的后端服务组件，负责提供核心API接口、数据处理及业务逻辑实现。自v1.3.0版本起，该服务使用uv替代poetry作为包管理器，需依赖PostgreSQL（数据库）、Redis（缓存）和Weaviate（向量数据库）等中间件协同工作。

核心功能与特性

• 依赖管理：采用uv作为包管理器，高效处理Python依赖
• 中间件集成：支持PostgreSQL、Redis、Weaviate等中间件，可通过配置切换向量数据库
• 数据库迁移：提供Flask-Migrate工具，支持数据库 schema 版本管理
• 异步任务处理：通过Celery支持异步任务（如数据集导入、文档索引、邮件发送等）
• 开发调试：支持调试模式启动，提供完整的测试环境配置

使用场景

• Dify应用的后端服务部署
• 本地开发与测试环境搭建
• 需要处理大规模文档索引和数据集导入的场景
• 企业内部私有化部署Dify服务

使用方法

前置要求

• 已安装Docker及Docker Compose
• 已安装Python 3.8+
• 已安装OpenSSL（用于生成SECRET_KEY）

1. 启动中间件服务

后端服务依赖PostgreSQL、Redis和Weaviate等中间件，可通过docker-compose一键启动：

bash
cd ../docker
cp middleware.env.example middleware.env
# 如需使用其他向量数据库，修改配置文件中的profile
docker compose -f docker-compose.middleware.yaml --profile weaviate -p dify up -d
cd ../api

2. 配置环境变量

复制环境变量示例文件并生成必要配置：

bash
cp .env.example .env

3. 生成SECRET_KEY

根据操作系统生成安全密钥：

Linux系统：

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

Mac系统：

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

4. 安装uv包管理器

Dify API使用uv管理依赖，需先安装uv：

bash
# 通过pip安装
pip install uv

# 或在macOS上通过Homebrew安装
brew install uv

5. 安装依赖

使用uv安装项目依赖：

bash
uv sync --dev

6. 数据库迁移

首次启动前需执行数据库迁移，确保schema为最新版本：

bash
uv run flask db upgrade

7. 启动后端服务

启动API服务，默认监听5001端口：

bash
uv run flask run --host 0.0.0.0 --port=5001 --debug

8. 启动Web服务

按照Web服务文档启动前端服务。

9. 完成应用配置

访问http://localhost:3000完成应用初始设置。

10. 启动异步任务 worker

如需处理异步任务（如数据集导入、文档索引等），启动Celery worker：

bash
uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace,app_deletion

测试

1. 安装测试依赖

安装后端及测试环境所需依赖：

bash
uv sync --dev

2. 运行测试

使用pyproject.toml中tool.pytest_env配置的模拟环境变量运行测试：

bash
uv run -P api bash dev/pytest/pytest_all_tests.sh