# dify_plugins_server

**Repository Path**: pgwanban/dify_plugins_server

## Basic Information

- **Project Name**: dify_plugins_server
- **Description**: dify 插件服务，专门用来写各种插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-12
- **Last Updated**: 2025-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DifyPlug Server

一个基于 FastAPI 的无状态工具服务，采用插件式架构设计，支持动态加载和扩展功能模块。

## ✨ 特性

- 🚀 **高性能**: 基于 FastAPI 和 uvicorn，支持异步处理
- 🔌 **插件化**: 支持动态加载插件，易于扩展新功能
- 🛡️ **安全**: 可选的 Bearer Token 认证机制
- 📝 **标准化**: 统一的 API 响应格式和错误处理
- 🔍 **可观测**: 结构化日志记录和请求追踪
- 📚 **文档**: 自动生成的 OpenAPI 文档
- 🐳 **容器化**: 支持 Docker 部署
- 🧪 **测试**: 完整的测试覆盖

## 🏗️ 架构设计

```
difyplug_server/
├── app/
│   ├── common/           # 通用模块
│   │   ├── errors.py     # 错误处理
│   │   └── responses.py  # 统一响应
│   ├── middleware/       # 中间件
│   │   ├── auth.py       # 认证中间件
│   │   └── request_id.py # 请求ID中间件
│   ├── plugins/          # 插件目录
│   │   ├── example_hello/# 示例插件
│   │   └── README.md     # 插件开发文档
│   ├── routers/          # 路由模块
│   │   ├── base.py       # 基础路由
│   │   └── v1.py         # V1 API路由
│   ├── schemas/          # 数据模型
│   ├── config.py         # 配置管理
│   ├── logging.py        # 日志配置
│   └── main.py           # 应用入口
├── tests/                # 测试文件
├── pyproject.toml        # 项目配置
├── Dockerfile            # Docker配置
└── Makefile              # 开发工具
```

## 🚀 快速开始

### 环境要求

- Python 3.11+
- uv (推荐) 或 pip

### 安装依赖

```bash
# 使用 uv (推荐)
uv sync

# 或使用 pip
pip install -r pyproject.toml
```

### 启动服务

```bash
# 开发模式（热重载）
make dev
# 或
uv run uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

# 生产模式
make run
# 或
uv run uvicorn app.main:app --host 0.0.0.0 --port 8080 --workers 4
```

### 访问服务

- API 文档: http://localhost:8080/docs
- 健康检查: http://localhost:8080/healthz
- 版本信息: http://localhost:8080/version

## 🔧 配置

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `APP_NAME` | `DifyPlug Server` | 应用名称 |
| `APP_VERSION` | `1.0.0` | 应用版本 |
| `APP_ENV` | `dev` | 运行环境 (dev/staging/prod) |
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `8080` | 监听端口 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `ENABLE_AUTH` | `false` | 是否启用认证 |
| `AUTH_TOKEN` | - | 认证令牌 |
| `ROUTER_PREFIX` | - | 路由前缀 |

### 配置文件

可以通过 `.env` 文件或环境变量进行配置：

```bash
# .env
APP_ENV=production
ENABLE_AUTH=true
AUTH_TOKEN=your-secret-token
LOG_LEVEL=INFO
```

## 🔌 插件开发

### 创建新插件

1. 在 `app/plugins/` 目录下创建插件文件夹
2. 创建 `router.py` 文件定义路由
3. 可选：创建 `schemas.py` 定义数据模型

### 示例插件结构

```
app/plugins/my_plugin/
├── __init__.py
├── router.py      # 路由定义（必需）
└── schemas.py     # 数据模型（可选）
```

### 插件路由示例

```python
from fastapi import APIRouter
from app.common.responses import ok

# 创建路由器
router = APIRouter(
    prefix="/my-plugin",
    tags=["my-plugin"]
)

@router.get("/hello")
async def hello():
    """Hello 接口"""
    return ok({"message": "Hello from my plugin!"})
```

详细的插件开发指南请参考 [插件开发文档](app/plugins/README.md)。

## 🧪 测试

```bash
# 运行所有测试
make test

# 运行测试并生成覆盖率报告
make test-cov

# 监视文件变化自动运行测试
make test-watch
```

## 🔍 代码质量

```bash
# 代码检查
make lint

# 代码格式化
make format

# 类型检查
make type-check

# 运行所有检查
make check-all
```

## 🐳 Docker 部署

### 构建镜像

```bash
make docker-build
# 或
docker build -t difyplug-server .
```

### 运行容器

```bash
# 基本运行
make docker-run

# 开发模式
make docker-run-dev

# 自定义配置
docker run -p 8080:8080 \
  -e APP_ENV=production \
  -e ENABLE_AUTH=true \
  -e AUTH_TOKEN=your-secret-token \
  difyplug-server
```

## 📊 监控和日志

### 健康检查

- `GET /healthz` - 健康状态检查
- `GET /readyz` - 就绪状态检查
- `GET /version` - 版本信息

### 日志格式

应用使用结构化 JSON 日志格式：

```json
{
  "timestamp": "2024-01-15T10:30:00.123Z",
  "level": "INFO",
  "logger": "app.main",
  "message": "Application startup completed",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "extra": {}
}
```

## 🔐 安全

### 认证

启用认证后，所有 API 请求需要在请求头中包含 Bearer Token：

```bash
curl -H "Authorization: Bearer your-token" http://localhost:8080/v1/example-hello/ping
```

### 免认证路径

以下路径默认免认证：
- `/docs`, `/redoc`, `/openapi.json` (API 文档)
- `/healthz`, `/readyz`, `/version` (健康检查)
- `/` (根路径重定向)

## 🛠️ 开发工具

项目提供了丰富的 Makefile 命令：

```bash
make help          # 显示所有可用命令
make setup         # 初始化开发环境
make dev           # 启动开发服务器
make test          # 运行测试
make lint          # 代码检查
make format        # 代码格式化
make docker-build  # 构建 Docker 镜像
make clean         # 清理临时文件
```

## 📝 API 文档

启动服务后，可以通过以下地址访问 API 文档：

- Swagger UI: http://localhost:8080/docs
- ReDoc: http://localhost:8080/redoc
- OpenAPI JSON: http://localhost:8080/openapi.json

## 🤝 贡献

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 开发规范

- 遵循 PEP 8 代码风格
- 使用类型注解
- 编写单元测试
- 更新文档

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🆘 支持

如果您遇到问题或有建议，请：

1. 查看 [FAQ](docs/FAQ.md)
2. 搜索现有的 [Issues](https://github.com/your-org/difyplug-server/issues)
3. 创建新的 Issue

## 🔄 更新日志

### v1.0.0 (2024-01-15)

- ✨ 初始版本发布
- 🔌 插件系统实现
- 🛡️ 认证中间件
- 📝 统一响应格式
- 🔍 请求追踪
- 🐳 Docker 支持
- 🧪 测试覆盖

---

**Made with ❤️ by DifyPlug Team**