# python-server

**Repository Path**: haifengworker/python-server

## Basic Information

- **Project Name**: python-server
- **Description**: 毕业设计 服务端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 中医药材管理系统 - 后端项目

基于 FastAPI + MySQL + MinIO + RAG 的现代化管理系统后端。

## 技术栈

- **Web 框架：** FastAPI 0.134
- **ASGI 服务器：** Uvicorn 0.41
- **数据库：** MySQL 8.0 + SQLAlchemy 2.0
- **对象存储：** MinIO 7.2
- **认证：** JWT (python-jose)
- **密码加密：** Bcrypt + Passlib
- **向量检索：** FAISS（本地持久化；配置项沿用 `CHROMA_PERSIST_DIRECTORY` / `CHROMA_COLLECTION_NAME` 命名）
- **嵌入模型：** sentence-transformers (BAAI/bge-small-zh-v1.5)
- **大语言模型：** 智谱 AI (GLM-4-Flash)
- **文档处理：** PyPDF、python-docx、markdown
- **图片处理：** Pillow
- **日志：** Loguru

## 功能特性

### 核心功能
- ✅ 用户认证与授权（JWT Token）
- ✅ 用户管理（CRUD、权限控制、密码管理）
- ✅ 药材信息管理
- ✅ 图片上传与存储（MinIO）
- ✅ RAG 智能问答系统
  - 文档上传与向量化
  - 语义检索
  - 智能回答生成
- ✅ 文档管理（PDF、TXT、MD、DOCX）
- ✅ 图片压缩与优化

### 技术特性
- ✅ RESTful API 设计
- ✅ 异步请求处理
- ✅ 数据库连接池
- ✅ 统一响应格式
- ✅ 全局异常处理
- ✅ CORS 跨域支持
- ✅ 请求日志记录
- ✅ 环境变量配置

## 环境要求

- **Python：** >= 3.10
- **MySQL：** >= 8.0
- **MinIO：** 最新版本

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd python-server
```

### 2. 创建虚拟环境

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置数据库

#### 4.1 创建数据库

```bash
mysql -u root -p
```

```sql
CREATE DATABASE graduation_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

#### 4.2 导入数据库结构

```bash
mysql -u root -p graduation_system < graduation_system.sql
```

> 说明：服务启动时会自动创建数据库（若不存在）并通过 SQLAlchemy 创建表结构；导入 `graduation_system.sql` 主要用于初始化示例数据/结构（可选但推荐）。

### 5. 配置 MinIO

#### 5.1 安装 MinIO

**Windows：**
```bash
# 下载 MinIO
wget https://dl.min.io/server/minio/release/windows-amd64/minio.exe

# 启动 MinIO
minio.exe server ./minio-data --console-address ":9001"
```

**Linux：**
```bash
# 下载 MinIO
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio

# 启动 MinIO
./minio server ./minio-data --console-address ":9001"
```

**Docker：**
```bash
docker run -d \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio \
  -v ./minio-data:/data \
  -e "MINIO_ROOT_USER=minioadmin" \
  -e "MINIO_ROOT_PASSWORD=minioadmin" \
  minio/minio server /data --console-address ":9001"
```

#### 5.2 访问 MinIO 控制台

打开浏览器访问 `http://localhost:9001`

- 用户名：`minioadmin`
- 密码：`minioadmin`

### 6. 配置环境变量

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

```env
# ============================================================
# MySQL 数据库配置
# ============================================================
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=graduation_system

# ============================================================
# MinIO 对象存储配置
# ============================================================

# MinIO S3 API 地址（默认 9000；控制台默认 9001）
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=graduation-system
MINIO_SECURE=False

# ============================================================
# JWT 认证配置
# ============================================================
JWT_SECRET_KEY=your_secret_key_here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440

# ============================================================
# 智谱 AI 配置
# ============================================================
ZHIPU_API_KEY=your_zhipu_api_key_here
ZHIPU_MODEL=glm-4-flash
```

**重要配置说明：**

1. **MySQL 配置：**
   - `MYSQL_HOST`：数据库服务器地址
   - `MYSQL_PASSWORD`：数据库密码（请修改为实际密码）

2. **MinIO 配置：**
   - `MINIO_ENDPOINT`：MinIO 服务器地址（不包含 http://）
   - `MINIO_ACCESS_KEY` 和 `MINIO_SECRET_KEY`：MinIO 访问凭证

3. **JWT 配置：**
   - `JWT_SECRET_KEY`：JWT 签名密钥（请修改为随机字符串）

4. **智谱 AI 配置：**
   - `ZHIPU_API_KEY`：智谱 AI API 密钥（用于 RAG 问答）
   - 获取地址：https://open.bigmodel.cn/

### 7. 启动服务

```bash
# 开发模式（自动重载）
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```

服务启动后访问：
- **API 文档（Scalar UI）：** http://localhost:8000/docs
- **OpenAPI JSON：** http://localhost:8000/openapi.json
- **健康检查：** http://localhost:8000/api/health

> 提示：`/docs` 使用 Scalar（通过 CDN 加载静态资源）。若内网/离线环境无法访问 CDN，可直接使用 `/openapi.json` 导入到 Postman / Apifox 等工具。

## 项目结构

```
python-server/
├── app/
│   ├── api/                    # API 路由
│   │   ├── auth/              # 认证相关接口
│   │   │   ├── login.py       # 登录
│   │   │   ├── register.py    # 注册
│   │   │   └── user.py        # 用户信息
│   │   ├── system_manage/     # 系统管理接口
│   │   │   └── user.py        # 用户管理
│   │   ├── herb/              # 药材管理接口
│   │   ├── upload/            # 文件上传接口
│   │   │   └── image.py       # 图片上传
│   │   └── rag/               # RAG 问答接口
│   │       ├── document.py    # 文档管理
│   │       └── chat.py        # 智能问答
│   ├── core/                  # 核心模块
│   │   ├── database.py        # 数据库连接
│   │   ├── security.py        # 安全相关（JWT、密码加密）
│   │   └── dependencies.py    # 依赖注入
│   ├── models/                # 数据库模型
│   │   ├── user.py           # 用户模型
│   │   ├── herb.py           # 药材模型
│   │   └── document.py       # 文档模型
│   ├── schemas/               # Pydantic 模型
│   │   ├── user.py           # 用户数据模型
│   │   ├── herb.py           # 药材数据模型
│   │   └── response.py       # 响应模型
│   ├── services/              # 业务逻辑
│   │   ├── minio_service.py  # MinIO 服务
│   │   ├── rag_service.py    # RAG 服务
│   │   └── user_service.py   # 用户服务
│   └── utils/                 # 工具函数
│       ├── logger.py         # 日志工具
│       └── image.py          # 图片处理
├── config/
│   └── settings.py           # 配置管理
├── storage/                  # 存储目录
│   ├── uploads/             # 文件上传目录
│   ├── chroma_db/           # 向量索引/元数据（FAISS 持久化目录）
│   └── logs/                # 日志文件
├── models/                   # AI 模型缓存
├── .env                      # 环境变量配置
├── main.py                   # 应用入口
├── requirements.txt          # Python 依赖
├── graduation_system.sql     # 数据库结构
└── README.md                 # 项目说明
```

## API 接口说明

> 说明：所有业务接口路径统一以 `/api` 开头；除登录接口外，其它接口需要在请求头中携带 `Authorization: Bearer <token>`。

### 认证与用户（前缀：`/api/auth`）

#### 1) 管理员登录
```http
POST /api/auth/admin-login
Content-Type: application/json

{
  "phone": "13800138000",
  "password": "123456"
}
```

登录成功会返回 `token` 与 `refreshToken`，随后前端会再调用 `/api/auth/info` 获取用户信息。

#### 2) 获取当前用户信息
```http
GET /api/auth/info
Authorization: Bearer <token>
```

#### 3) 用户列表（分页）
```http
GET /api/auth/users?page=1&page_size=10
Authorization: Bearer <token>
```

#### 4) 创建 / 更新 / 删除用户
```http
POST /api/auth/users
PUT /api/auth/users/{user_id}
DELETE /api/auth/users/{user_id}
Authorization: Bearer <token>
```

#### 5) 修改密码 / 重置密码
```http
PUT /api/auth/change-password
PUT /api/auth/users/{user_id}/reset-password
Authorization: Bearer <token>
```

### 中医药材与配方

- **药材（前缀：`/api/herb`）**：`POST /create`、`GET /list`、`GET /{herb_id}`、`PUT /{herb_id}`、`DELETE /{herb_id}`
- **配方（前缀：`/api/formula`）**：`POST /create`、`GET /list`、`GET /{formula_id}`、`PUT /{formula_id}`、`DELETE /{formula_id}`

### 文档与 RAG

- **文档（前缀：`/api/document`）**：`POST /upload`、`GET /list`、`GET /{document_id}`、`DELETE /{document_id}`
- **问答（前缀：`/api/chat`）**：`POST /query`、`POST /query-stream`（SSE 流式）
- **向量检索（前缀：`/api/search`）**：`POST /search`

### 图片上传（前缀：`/api/upload`）

#### 上传图片
```http
POST /api/upload/image
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <image_file>
```

**响应示例（字段名以实际返回为准）：**
```json
{
  "success": true,
  "code": 200,
  "message": "图片上传成功",
  "data": {
    "image_url": "http://localhost:9000/graduation-system/images/uuid_filename.jpg",
    "filename": "example.jpg",
    "size": 102400,
    "message": "图片上传成功"
  }
}
```

## 核心功能说明

### 1. JWT 认证

**Token 生成：**
```python
from app.core.security import create_access_token

access_token = create_access_token(
    data={"sub": str(user.user_id)}
)
```

**Token 验证：**
```python
from app.core.dependencies import get_current_user

@router.get("/protected")
async def protected_route(
    current_user: tuple = Depends(get_current_user)
):
    user_info, user_auth = current_user
    return {"user_id": user_info.user_id}
```

### 2. MinIO 图片存储

**上传图片：**
```python
from app.services.minio_service import MinIOService

minio_service = MinIOService()
image_url = await minio_service.upload_image(
    file_data=file.file.read(),
    filename=file.filename,
    content_type=file.content_type
)
```

**特性：**
- 自动压缩图片（最大 1920x1920，85% 质量）
- UUID + 原文件名命名
- 公开访问权限
- 永久 URL（非预签名）

### 3. RAG 智能问答

**工作流程：**
```
文档上传
    ↓
文本提取（PDF/DOCX/TXT/MD）
    ↓
文本分块（Chunk Size: 500, Overlap: 50）
    ↓
向量化（BAAI/bge-small-zh-v1.5）
    ↓
存储到本地向量索引（FAISS 持久化）
    ↓
用户提问
    ↓
问题向量化
    ↓
语义检索（Top K: 5）
    ↓
检索相关文档片段
    ↓
构建 Prompt
    ↓
调用智谱 AI 生成回答
    ↓
返回答案 + 来源
```

**配置参数：**
- `CHUNK_SIZE`：文本分块大小（默认 500 字符）
- `CHUNK_OVERLAP`：分块重叠大小（默认 50 字符）
- `DEFAULT_TOP_K`：检索文档数量（默认 5）
- `SIMILARITY_THRESHOLD`：相似度阈值（默认 0.7）

### 4. 数据库连接池

使用 SQLAlchemy 连接池管理数据库连接：

```python
from app.core.database import get_db

@router.get("/users")
async def get_users(db: Session = Depends(get_db)):
    users = db.query(User).all()
    return users
```

## 开发规范

### 代码风格

- 遵循 PEP 8 规范
- 使用类型注解
- 函数和类添加文档字符串

### API 响应格式

统一使用以下响应格式：

```python
{
    "code": 200,           # 状态码
    "message": "success",  # 消息
    "data": {}            # 数据
}
```

**状态码：**
- `200`：成功
- `400`：请求参数错误
- `401`：未授权
- `403`：无权限
- `404`：资源不存在
- `500`：服务器错误

### 异常处理

使用 HTTPException 抛出异常：

```python
from fastapi import HTTPException

if not user:
    raise HTTPException(
        status_code=404,
        detail="用户不存在"
    )
```

## 常见问题

### 1. 数据库连接失败

**问题：** `Can't connect to MySQL server`

**解决方案：**
1. 确认 MySQL 服务已启动
2. 检查 `.env` 中的数据库配置
3. 确认数据库用户有访问权限

### 2. MinIO 连接失败

**问题：** `MinIO connection error`

**解决方案：**
1. 确认 MinIO 服务已启动
2. 检查 `.env` 中的 MinIO 配置
3. 确认 `MINIO_ENDPOINT` 指向 **S3 API 端口**（默认 `9000`），不要填控制台端口（默认 `9001`）
4. 确认 MinIO 端口未被占用

### 3. 图片上传失败

**问题：** 上传图片返回错误

**解决方案：**
1. 检查 MinIO 存储桶是否存在
2. 确认 MinIO 访问权限配置正确
3. 查看服务器日志 `storage/logs/`

### 4. RAG 问答无响应

**问题：** 智能问答接口超时

**解决方案：**
1. 确认智谱 AI API Key 配置正确
2. 检查网络连接
3. 确认向量数据库中有文档数据

### 5. API 文档打不开

**问题：** 访问 `/docs` 空白或加载失败

**解决方案：**
1. `/docs` 使用 Scalar（通过 CDN 加载），内网/离线环境可能无法访问
2. 直接使用 `/openapi.json` 导入到 Postman / Apifox

### 6. 依赖安装失败

**问题：** pip install 报错

**解决方案：**
```bash
# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或升级 pip
pip install --upgrade pip
```

## 性能优化

### 1. 数据库优化

- 使用索引加速查询
- 使用连接池管理连接
- 避免 N+1 查询问题

### 2. 图片优化

- 自动压缩图片
- 限制上传文件大小
- 使用 CDN 加速访问

### 3. RAG 优化

- 缓存嵌入模型
- 批量处理文档
- 调整分块参数

## 部署建议

### 1. 生产环境配置

```bash
# 使用多进程
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

# 使用 Gunicorn + Uvicorn
gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

### 2. 使用 Docker 部署

```dockerfile
FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### 3. 使用 Nginx 反向代理

```nginx
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 相关文档

- [FastAPI 官方文档](https://fastapi.tiangolo.com/zh/)
- [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/)
- [MinIO 官方文档](https://min.io/docs/minio/linux/index.html)
- [智谱 AI 开放平台](https://open.bigmodel.cn/)
- [Sentence Transformers 文档](https://www.sbert.net/)

## 许可证

MIT License

## 联系方式

如有问题，请提交 Issue 或联系开发团队。