# fastapi-openai-template

**Repository Path**: ggxx/fastapi-openai-template

## Basic Information

- **Project Name**: fastapi-openai-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 脚手架, AI, Python

## README

# FastAPI OpenAI Template

FastAPI 开发基础模版，集成用户认证、文件上传、AI 对话等常见功能，开箱即用。

## 功能特性

- **用户系统** — 注册、登录、JWT 双令牌认证（Access + Refresh）、会话管理、登出
- **管理员模块** — 独立管理端登录/登出/鉴权，基于 `is_admin` 角色标识
- **文件上传** — 按日期/用户分目录存储，支持扩展名白名单，可选登录
- **AI 对话** — 接入 OpenAI 兼容接口（支持 DeepSeek、通义千问、智谱等），一键切换模型
- **数据库** — SQLAlchemy 2.0 异步引擎，默认 SQLite（开发），可切换 MySQL
- **日志** — Loguru 统一业务日志，自动抑制第三方库噪音
- **静态文件** — 内置 `/static` 和 `/ui` 挂载点，便于前后端同仓部署

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | FastAPI 0.104 + Uvicorn 0.24 |
| ORM | SQLAlchemy 2.0（异步） |
| 数据库 | SQLite（默认）/ MySQL |
| 认证 | JWT（python-jose）+ bcrypt |
| AI | OpenAI SDK（兼容多厂商） |
| 日志 | Loguru |
| 配置 | pydantic-settings + .env |

## 快速开始

### 1. 环境准备

```bash
# 需要 Python 3.9 ~ 3.12
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖（推荐使用 uv）
pip install uv
uv sync
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入实际配置（至少填写 OPENAI_API_KEY）
```

### 3. 启动开发服务

```bash
# 方式一：Python 脚本
python app_dev.py

# 方式二：Shell 脚本
bash app.sh dev

# 方式三：Windows 批处理
app.bat dev
```

服务默认监听 `http://0.0.0.0:8127`，启动后自动创建数据库表和默认管理员账户。

### 4. 生产部署

```bash
bash app.sh prod
```

使用 Gunicorn + Uvicorn Worker，配置文件见 `gunicorn/config.py`。

## API 接口

| 模块 | 路径前缀 | 说明 |
|------|----------|------|
| 用户 | `/api/user` | 注册、登录、获取信息、刷新令牌、登出 |
| 管理员 | `/admin/api` | 管理员登录、登出、获取信息 |
| 上传 | `/api` | 文件上传（`POST /api/upload`） |
| AI | `/api/ai` | AI 对话（`POST /api/ai/chat`） |

### 默认管理员账户

首次启动自动创建：

- 用户名：`admin`
- 密码：`ChangeMe123!`

**请立即修改初始密码。**

## 项目结构

```
├── app/                    # 应用主目录
│   ├── __init__.py         # 应用工厂（create_app）
│   ├── config.py           # 配置管理（pydantic-settings）
│   ├── models.py           # ORM 模型（User, UserSession）
│   ├── security.py         # 认证与安全（JWT, bcrypt, 会话管理）
│   ├── middleware.py        # 中间件（请求日志）
│   ├── exceptions.py       # 全局异常处理
│   ├── routers/            # 路由模块
│   │   ├── user.py         # 用户接口
│   │   ├── admin.py        # 管理员接口
│   │   ├── upload.py       # 文件上传接口
│   │   └── ai.py           # AI 对话接口
│   ├── services/           # 业务服务
│   │   └── ai_service.py   # AI 服务封装
│   ├── schemas/            # 请求/响应模型
│   ├── db/                 # 数据库
│   │   ├── database.py     # 引擎与会话管理
│   │   └── crud.py         # 通用 CRUD
│   └── utils/              # 工具模块
│       └── logger.py       # 日志配置
├── data/                   # SQLite 数据库文件
├── static/                 # 静态资源
│   └── uploads/            # 上传文件目录
├── logs/                   # 日志文件
├── sql/                    # SQL 脚本
│   └── init/               # 初始化脚本
├── gunicorn/               # Gunicorn 配置
├── ui/                     # 前端静态页面
├── app_dev.py              # 开发启动入口
├── app.sh                  # Linux 启动脚本
├── app.bat                 # Windows 启动脚本
├── .env.example            # 环境变量模板
└── pyproject.toml          # 项目依赖
```

## 环境变量说明

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET_KEY` | `hard_to_guess_string` | 应用密钥，生产环境务必替换 |
| `DEBUG` | `true` | 调试模式 |
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `8127` | 监听端口 |
| `DATABASE_URL` | SQLite 本地路径 | 数据库连接串 |
| `OPENAI_API_KEY` | 空 | AI 接口密钥 |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | AI 接口地址 |
| `OPENAI_MODEL` | `gpt-4o-mini` | 默认模型名称 |
| `BASE_URL` | `http://localhost:8127` | 对外访问地址 |
| `MAX_CONTENT_LENGTH` | `16777216`（16MB） | 上传文件大小限制 |

完整配置项见 `.env.example`。

## License

MIT