# 后台

**Repository Path**: zigzagwag/background

## Basic Information

- **Project Name**: 后台
- **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-01-27
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 用户认证系统

## 项目概述

这是一个基于 FastAPI 构建的用户认证系统，提供了完整的用户注册、登录、JWT 认证和用户管理功能。系统使用 SQLAlchemy 作为 ORM，SQLite 作为数据库，并集成了 FastAPI-Users 库来简化用户认证流程。

## 主要特性

- ✅ 用户注册与登录
- ✅ JWT 令牌认证
- ✅ 用户信息管理
- ✅ 跨域资源共享 (CORS) 支持
- ✅ 数据库迁移 (Alembic)
- ✅ 异步数据库操作
- ✅ 用户角色管理 (user/admin)
- ✅ 会员专属内容保护

## 技术栈

- **后端框架**: FastAPI
- **数据库**: SQLite (支持异步)
- **ORM**: SQLAlchemy
- **用户认证**: FastAPI-Users
- **配置管理**: Pydantic Settings
- **数据库迁移**: Alembic
- **Python版本**: 3.8+

## 项目结构

```
my-project/
├── app/
│   ├── __init__.py
│   ├── main.py              # 应用入口点
│   ├── db.py               # 数据库配置
│   ├── api/
│   │   └── v1/
│   │       └── api_user.py # 用户认证路由
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py       # 应用配置
│   │   └── users.py        # 用户管理逻辑
│   ├── models/
│   │   ├── __init__.py
│   │   └── user.py         # 用户数据模型
│   └── schemas/
│       ├── __init__.py
│       └── user.py         # 用户数据验证模式
├── migrations/             # 数据库迁移文件
├── .env                   # 环境变量配置
├── alembic.ini           # Alembic 配置
├── test.db               # SQLite 数据库文件
└── README.txt            # 本文件
```

## 安装与配置

### 1. 环境准备

确保已安装 Python 3.8+ 和 pip。

### 2. 安装依赖

```bash
# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖包
pip install fastapi
pip install "uvicorn[standard]"
pip install sqlalchemy
pip install aiosqlite
pip install fastapi-users[sqlalchemy]
pip install pydantic-settings
pip install alembic
```

### 3. 环境配置

项目使用 `.env` 文件管理配置，默认配置如下：

```env
DATABASE_URL=sqlite+aiosqlite:///./test.db
SECRET_KEY=super_secret_key_123456
```

- `DATABASE_URL`: 数据库连接字符串
- `SECRET_KEY`: JWT 令牌签名密钥（生产环境请使用强密钥）

## 数据库初始化

### 1. 初始化数据库迁移

```bash
# 初始化 Alembic（如果尚未初始化）
alembic init migrations

# 生成迁移文件
alembic revision --autogenerate -m "Initial migration"

# 应用迁移
alembic upgrade head
```

### 2. 直接运行（使用现有迁移）

项目已包含迁移文件，可直接运行：

```bash
alembic upgrade head
```

## 运行应用

### 开发模式

```bash
# 直接运行 main.py
python app/main.py

# 或使用 uvicorn
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

应用将在 `http://127.0.0.1:8000` 启动。

### 验证运行状态

访问 `http://127.0.0.1:8000/` 将看到：
```json
{"message": "Server is running"}
```

访问 `http://127.0.0.1:8000/docs` 查看完整的 API 文档（Swagger UI）。

## API 接口

### 认证相关

#### 1. 用户注册
- **URL**: `POST /api/v1/auth/register`
- **请求体**:
```json
{
  "email": "user@example.com",
  "password": "securepassword",
  "nickname": "可选昵称"
}
```

#### 2. 用户登录
- **URL**: `POST /api/v1/auth/jwt/login`
- **请求体**:
```json
{
  "username": "user@example.com",
  "password": "securepassword"
}
```
- **响应**: 返回 JWT 令牌

#### 3. 获取当前用户信息
- **URL**: `GET /api/v1/auth/users/me`
- **认证**: Bearer Token
- **响应**: 返回当前用户信息

#### 4. 更新用户信息
- **URL**: `PATCH /api/v1/auth/users/me`
- **认证**: Bearer Token
- **请求体**: 可更新字段（email, nickname, role 等）

### 会员内容

#### 1. 获取会员专属内容
- **URL**: `GET /api/v1/auth/vip-content`
- **认证**: Bearer Token
- **响应**: 返回会员专属消息

## 前端集成

### CORS 配置

应用已配置 CORS，允许来自 `http://localhost:5173` 的请求（Vite 默认开发服务器）。如需修改，请编辑 `app/main.py` 中的 `allow_origins` 列表。

### 前端调用示例

```javascript
// 用户登录
const login = async (email, password) => {
  const response = await fetch('http://localhost:8000/api/v1/auth/jwt/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      username: email,
      password: password
    })
  });
  
  const data = await response.json();
  localStorage.setItem('token', data.access_token);
  return data;
};

// 获取会员内容（需要认证）
const getVipContent = async () => {
  const token = localStorage.getItem('token');
  const response = await fetch('http://localhost:8000/api/v1/auth/vip-content', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
};
```

## 开发指南

### 1. 添加新功能

#### 创建新模型
1. 在 `app/models/` 目录下创建新模型文件
2. 运行 `alembic revision --autogenerate -m "描述"`
3. 运行 `alembic upgrade head`

#### 添加新 API 路由
1. 在 `app/api/v1/` 目录下创建新路由文件
2. 在 `app/main.py` 中导入并包含路由

### 2. 数据库操作

使用异步会话进行数据库操作：

```python
from app.db import get_async_session
from sqlalchemy.ext.asyncio import AsyncSession
from fastapi import Depends

async def some_function(session: AsyncSession = Depends(get_async_session)):
    # 数据库操作
    pass
```

### 3. 用户认证依赖

使用 FastAPI-Users 提供的依赖：

```python
from app.core.users import current_active_user
from app.models.user import User
from fastapi import Depends

async def protected_route(user: User = Depends(current_active_user)):
    return {"message": f"Hello {user.email}"}
```

## 生产部署建议

### 1. 安全配置
- 修改 `.env` 中的 `SECRET_KEY` 为强随机字符串
- 使用环境变量而非 `.env` 文件存储敏感信息
- 启用 HTTPS

### 2. 数据库
- 考虑使用 PostgreSQL 或 MySQL 替代 SQLite
- 配置数据库连接池

### 3. 性能优化
- 启用 Gzip 压缩
- 配置适当的 CORS 策略
- 使用 Redis 缓存

### 4. 监控与日志
- 添加结构化日志
- 集成应用性能监控 (APM)
- 设置健康检查端点

## 数据库迁移到 MySQL/PostgreSQL

### 1. 切换到 MySQL

#### 安装 MySQL 驱动
```bash
# 安装异步 MySQL 驱动
pip install asyncmy
# 或安装同步驱动（如果使用同步模式）
pip install pymysql
```

#### 修改 .env 配置文件
```env
# MySQL 连接字符串格式
DATABASE_URL=mysql+asyncmy://username:password@localhost:3306/database_name
# 或使用 pymysql
# DATABASE_URL=mysql+pymysql://username:password@localhost:3306/database_name
```

#### 创建 MySQL 数据库
```sql
CREATE DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

#### 应用数据库迁移
```bash
# 重新生成迁移文件（如果需要）
alembic revision --autogenerate -m "Migrate to MySQL"

# 应用迁移
alembic upgrade head
```

### 2. 切换到 PostgreSQL

#### 安装 PostgreSQL 驱动
```bash
# 安装异步 PostgreSQL 驱动
pip install asyncpg
# 或安装同步驱动
pip install psycopg2-binary
```

#### 修改 .env 配置文件
```env
# PostgreSQL 连接字符串格式
DATABASE_URL=postgresql+asyncpg://username:password@localhost:5432/database_name
# 或使用 psycopg2
# DATABASE_URL=postgresql+psycopg2://username:password@localhost:5432/database_name
```

#### 创建 PostgreSQL 数据库
```sql
CREATE DATABASE database_name;
```

#### 应用数据库迁移
```bash
# 重新生成迁移文件（如果需要）
alembic revision --autogenerate -m "Migrate to PostgreSQL"

# 应用迁移
alembic upgrade head
```

### 3. 重要注意事项

#### 数据类型差异
- **SQLite 到 MySQL/PostgreSQL**: 某些数据类型可能需要调整
- **布尔类型**: SQLite 使用 INTEGER(0/1)，MySQL 使用 TINYINT(1)，PostgreSQL 使用 BOOLEAN
- **字符串长度**: MySQL 有 VARCHAR 长度限制，PostgreSQL 没有

#### 迁移策略
1. **开发环境测试**: 先在开发环境测试迁移
2. **数据备份**: 迁移前备份 SQLite 数据
3. **导出数据**: 使用 SQLite 导出工具导出数据
   ```bash
   sqlite3 test.db .dump > backup.sql
   ```
4. **导入数据**: 根据目标数据库调整 SQL 语法后导入

#### 连接池配置
对于生产环境，建议配置连接池：
```python
# 在 app/db.py 中添加连接池配置
engine = create_async_engine(
    settings.DATABASE_URL,
    pool_size=20,
    max_overflow=30,
    pool_pre_ping=True,
    pool_recycle=3600
)
```

#### 性能优化
- **MySQL**: 配置合适的字符集和排序规则
- **PostgreSQL**: 考虑使用连接池管理器如 PgBouncer
- **索引优化**: 根据查询模式添加适当索引

### 4. 验证迁移
迁移完成后，验证以下功能：
1. 用户注册和登录
2. 数据库查询性能
3. 并发连接处理
4. 数据一致性检查

## 故障排除

### 常见问题

1. **数据库迁移失败**
   - 检查 `DATABASE_URL` 配置
   - 确保数据库文件可写
   - 尝试 `alembic downgrade -1` 然后重新升级

2. **JWT 认证失败**
   - 验证 `SECRET_KEY` 配置
   - 检查令牌过期时间
   - 确认请求头格式正确

3. **CORS 错误**
   - 检查前端 origin 是否在允许列表中
   - 验证 CORS 中间件配置

### 日志查看

应用日志将输出到控制台，包含请求详情和错误信息。

## 贡献指南

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

## 许可证

本项目仅供学习参考，可根据需要修改使用。

## 联系信息

如有问题或建议，请通过项目仓库提交 Issue。

---
*最后更新: 2026年1月27日*