# x-dify

**Repository Path**: chain-engine/x-dify

## Basic Information

- **Project Name**: x-dify
- **Description**: 一个基于 Dify 的工作流编排平台
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# x-dify

## 项目简介

一个基于 Dify 的工作流编排平台后端服务。提供标准化的 API 接口，帮助企业快速构建智能化工作流应用。

## 核心特征

- **LLM 对话工作流**：基于大模型的多轮对话
- **任务调度自动化**：定时触发、事件驱动的任务调度和执行
- **多节点流程编排**：支持条件分支、循环、并行等复杂流程控制
- **API 编排与集成**：连接外部 API、数据库、第三方服务的编排能力
- **生产级架构**：支持高并发、可扩展、易维护的企业级应用架构
- **标准化 API**：遵循 RESTful 规范，提供 OpenAPI 文档
- **配置中心**：支持 .env + config.yaml 双配置体系，多环境切换

## 项目结构

```
x-dify/
├── .env.example                # 环境变量模板
├── config.yaml                 # 主配置文件（YAML 格式）
├── pyproject.toml              # 项目配置 (推荐使用 uv)
├── uv.lock                     # 依赖锁定文件
├── uv.toml                     # uv 配置文件
├── .python-version             # Python 版本指定
├── Dockerfile                  # Docker 部署文件
├── src/                        # 核心业务代码
│   ├── core/                   # 核心模块
│   │   ├── config.py           # 配置中心（双配置体系：.env + config.yaml）
│   │   ├── logger.py           # 日志配置
│   │   ├── exceptions.py       # 全局异常定义
│   │   ├── middleware.py       # 中间件定义
│   │   ├── responses.py        # 响应标准化工具
│   │   └── schemas.py          # 数据模型和Schema

│   ├── models/                 # 数据模型
│   │   └── schemas.py          # Pydantic 请求/响应模型
│   ├── services/               # 外部服务调用
│   │   └── dify_client.py      # Dify API 客户端（对话、工作流、日志）
│   ├── workflows/              # 工作流编排引擎
│   │   ├── engine.py           # 执行引擎（多节点编排、LLM/HTTP/条件分支）
│   │   └── manager.py          # 工作流 CRUD 管理
│   ├── scheduler/              # 任务调度
│   │   └── task_scheduler.py   # Cron 定时调度器
│   ├── api/                    # API 层
│   │   ├── middleware/         # 中间件
│   │   │   ├── cors.py         # CORS 跨域
│   │   │   ├── error_handler.py # 全局异常处理
│   │   │   └── rate_limiter.py # 请求限流（令牌桶）
│   │   └── routes/             # 路由
│   │       ├── health.py       # 健康检查 + 版本接口
│   │       ├── chat.py         # Dify 对话接口
│   │       ├── workflow.py     # 工作流管理接口
│   │       └── scheduler.py    # 任务调度接口
│   ├── utils/                  # 工具函数
│   │   └── helpers.py
│   └── main.py                 # FastAPI 主入口
├── examples/                   # 使用示例
│   └── workflow_example.py     # 工作流调用示例
├── tests/                      # 测试目录（待填充）
├── scripts/                    # 部署脚本
│   ├── start.sh                # Linux 启动脚本
│   └── start.bat               # Windows 启动脚本
├── docs/                       # 项目文档
├── .gitignore
├── LICENSE
├── README.md
├── README.en.md
├── pyproject.toml              # 项目配置 (推荐使用 uv)
├── uv.lock                     # 依赖锁定文件
└── Dockerfile                  # Docker 部署文件
```

## 系统架构

### 系统分层架构图

```mermaid
graph TB
    subgraph "客户端层"
        A[Web UI] --> B[Mobile App]
        C[API Client] --> B
    end
    
    subgraph "API 网关层"
        D[FastAPI] --> E[CORS Middleware]
        D --> F[Rate Limiter]
        D --> G[Error Handler]
    end
    
    subgraph "业务逻辑层"
        H[Workflow Engine] --> I[Dify Client]
        J[Task Scheduler] --> K[Workflow Manager]
        L[Chat Service] --> I
    end
    
    subgraph "数据模型层"
        M[Pydantic Models] --> N[Request Validation]
        M --> O[Response Standardization]
    end
    
    subgraph "外部服务层"
        P[Dify Platform] --> Q[LLM Services]
        R[Database] --> S[Redis Cache]
    end
    
    A --> D
    B --> D
    C --> D
    D --> H
    D --> J
    D --> L
    H --> M
    J --> M
    L --> M
    I --> P
    K --> R
```

### 核心功能业务流程图

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant API as API 网关
    participant Engine as 工作流引擎
    participant Dify as Dify 服务
    participant LLM as LLM 服务

    Client->>API: 发起工作流执行请求
    API->>Engine: 解析并验证请求
    Engine->>Engine: 执行节点编排逻辑
    loop 每个 LLM 节点
        Engine->>Dify: 调用 Dify 对话 API
        Dify->>LLM: 执行 LLM 推理
        LLM-->>Dify: 返回推理结果
        Dify-->>Engine: 返回对话结果
    end
    Engine->>API: 返回工作流执行结果
    API-->>Client: 返回最终响应
```

### 模块依赖关系图

```mermaid
graph LR
    A[src/main.py] --> B[FastAPI]
    A --> C[Config]
    A --> D[Logger]
    
    C --> E[config.yaml]
    C --> F[.env]
    
    B --> G[API Routes]
    G --> H[Health]
    G --> I[Chat]
    G --> J[Workflow]
    G --> K[Scheduler]
    
    J --> L[Workflow Engine]
    J --> M[Workflow Manager]
    L --> N[Dify Client]
    M --> L
    
    K --> O[Task Scheduler]
    O --> L
    
    P[Pydantic Models] --> H
    P --> I
    P --> J
    P --> K
```

## 快速开始

### ① 环境要求

#### Windows
- Python 3.11+
- pip
- Git

#### Linux
- Python 3.11+
- pip
- Git
- virtualenv (可选)

### ② 项目克隆

```bash
git clone https://gitee.com/your-repo/x-dify.git
cd x-dify
```

### ③ 依赖安装

```bash
# 安装 uv (如果尚未安装)
pip install uv

# 使用 pyproject.toml (推荐)
# 直接同步项目依赖
uv sync
# 或者只安装运行时依赖
uv sync --no-dev
```

### ④ 配置文件创建

复制配置文件模板：

```bash
copy .env.example .env
```

编辑 `.env` 文件，配置以下参数：

```env
# Dify 配置
DIFY_BASE_URL=http://localhost/v1
DIFY_API_KEY=your-dify-api-key-here

# 数据库配置（可选）
DB_HOST=localhost
DB_PORT=5432
DB_NAME=xdify
DB_USER=your-db-user
DB_PASSWORD=your-db-password

# Redis 配置（可选）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
```

### ⑤ 服务启动

#### 1. 本地开发模式启动

```bash
# 确保虚拟环境已激活
# 使用 uv 运行（推荐）
uv run python -m src.main
# 或直接运行
python -m src.main
```

服务将在 `http://localhost:8000` 启动，支持热重载和调试模式。

#### 2. Docker 容器化部署

首先创建 Dockerfile：

```dockerfile
FROM python:3.11-slim

# 安装 uv
RUN pip install uv

WORKDIR /app

COPY pyproject.toml .
COPY uv.lock .
RUN python -m uv sync --no-dev

COPY . .

EXPOSE 8000

CMD ["python", "-m", "src.main"]
```

然后使用 Docker Compose 部署：

```yaml
version: '3.8'

services:
  x-dify:
    build: .
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=production
      - DIFY_BASE_URL=${DIFY_BASE_URL}
      - DIFY_API_KEY=${DIFY_API_KEY}
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./.env:/app/.env
      - ./logs:/app/logs
    restart: unless-stopped
```

或者使用 uv 运行（如果容器内安装了 uv）：

```yaml
version: '3.8'

services:
  x-dify:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=production
      - DIFY_BASE_URL=${DIFY_BASE_URL}
      - DIFY_API_KEY=${DIFY_API_KEY}
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    restart: unless-stopped
```

使用 Docker Compose 部署时，确保将以下文件复制到容器中：
- pyproject.toml
- uv.lock
- .env (如果存在)
- config.yaml
- src/ (源代码目录)

### ⑥ 常用命令

```bash
# 启动服务
python -m src.main
# 或使用 uv
uv run python -m src.main

# 运行测试
pytest tests/
# 或使用 uv
uv run pytest tests/

# 代码格式化
uv run black src/

# 代码检查
uv run flake8 src/
```

## 技术栈

### 依赖管理
- uv: 快速的 Python 包管理器和项目管理工具

### Web 框架
- FastAPI: 现代高性能 Web 框架
- Uvicorn: ASGI 服务器

### 数据验证 & 配置管理
- Pydantic: 数据验证和设置管理
- Pydantic Settings: 配置管理扩展
- Python-dotenv: 环境变量加载

### HTTP 客户端
- Httpx: 现代异步 HTTP 客户端

### 日志管理
- Loguru: 现代化日志库

### 配置解析
- PyYAML: YAML 配置文件解析

### 任务调度
- APScheduler: 高级 Python 调度器

### 开发 & 测试
- Pytest: 测试框架
- Pytest-asyncio: 异步测试支持

## API 文档

- Swagger UI 交互式 API 文档: [http://localhost:8000/docs](http://localhost:8000/docs)
- ReDoc 只读 API 文档: [http://localhost:8000/redoc](http://localhost:8000/redoc)
- OpenAPI JSON 文档: [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)

## 存储配置

### 本地存储
- 日志文件存储在 `logs/` 目录
- 配置文件存储在 `config/` 目录

### 对象存储
- 通过 Dify 服务集成的对象存储功能
- 支持阿里云 OSS、AWS S3 等多种对象存储服务

## 许可证

本项目采用 [LICENSE](./LICENSE) 许可证。

## 参考资料

- [uv 官方文档](https://docs.astral.sh/uv/)
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Python 官方文档](https://docs.python.org/3/)
- [Pydantic 官方文档](https://docs.pydantic.dev/)
- [Dify 官方文档](https://docs.dify.ai/)

## 联系方式

- 作者：John Young
- 网络昵称：夜雨诗来
- 邮箱：john.young@foxmail.com
- Gitee：[https://gitee.com/yeyushilai](https://gitee.com/yeyushilai)
- GitHub：[https://github.com/yeyushilai](https://github.com/yeyushilai)