# YGadmin

**Repository Path**: ksufer/ygadmin

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YGadmin

一个基于 FastAPI + Supabase 的现代化用户管理系统，支持用户注册、登录、资料管理等功能。

## ✨ 功能特性

- 🔐 **用户认证** - 基于 Supabase Auth 的注册/登录系统
- 🍪 **安全会话** - JWT Token + HttpOnly Cookie 认证
- 👤 **用户资料** - 新用户首次登录自动引导填写资料
- 📝 **日志系统** - 按日期分割，错误日志单独记录
- 🎨 **美观界面** - 现代化 UI，包含多种自定义错误页面
- 🐳 **Docker 支持** - 完整的容器化部署方案
- 🔧 **工程化架构** - 模块化设计，易于维护和扩展

## 📁 项目结构

```
YGadmin/
├── app/                          # 应用主目录
│   ├── core/                     # 核心模块
│   │   ├── config.py             # 配置管理 (pydantic-settings)
│   │   ├── database.py           # Supabase 数据库连接
│   │   ├── logging.py            # 日志系统
│   │   └── security.py           # JWT & Cookie 认证
│   ├── middleware/               # 中间件
│   │   ├── auth.py               # 认证 & 请求日志中间件
│   │   └── decorators.py         # 装饰器
│   ├── routers/                  # 路由模块
│   │   ├── auth.py               # 认证路由 (登录/注册/登出)
│   │   └── user.py               # 用户路由
│   ├── services/                 # 服务层
│   │   └── user_service.py       # 用户业务逻辑
│   └── main.py                   # 应用入口
├── templates/                    # Jinja2 模板
│   ├── errors/                   # 错误页面 (401/403/404/500)
│   ├── login.html                # 登录/注册页面
│   ├── profile_form.html         # 资料填写页面
│   └── welcome.html              # 欢迎页面
├── demo/                         # 演示代码
│   └── mini-demo.py              # 极简示例
├── logs/                         # 日志目录 (自动创建)
├── Dockerfile                    # Docker 镜像配置
├── docker-compose.yml            # Docker Compose 配置
├── nginx.conf                    # Nginx 反向代理配置
├── requirements.txt              # Python 依赖
├── run.py                        # 启动脚本
└── env.example                   # 环境变量示例
```

## 🚀 快速开始

### 环境要求

- Python 3.10+
- Supabase 项目（需要创建 `public.user` 表）

### 数据库准备

在 Supabase 中创建 `user` 表：

```sql
CREATE TABLE public.user (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(255) UNIQUE NOT NULL,
    gender CHAR(1),
    age INTEGER,
    address TEXT,
    phone VARCHAR(50)
);
```

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd YGadmin
   ```

2. **创建虚拟环境**
   ```bash
   python -m venv .venv
   .venv\Scripts\activate  # Windows
   # source .venv/bin/activate  # Linux/Mac
   ```

3. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

4. **配置环境变量**
   ```bash
   copy env.example .env
   ```
   编辑 `.env` 文件，填入你的 Supabase 配置：
   ```env
   DEBUG=true
   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_KEY=your-anon-key
   SECRET_KEY=your-secret-key
   ```

5. **启动应用**
   ```bash
   python run.py
   ```

6. **访问应用**
   
   打开浏览器访问 http://127.0.0.1:8001

## 🐳 Docker 部署

### 使用 Docker Compose（推荐）

```bash
# 1. 配置环境变量
copy env.example .env
# 编辑 .env 文件

# 2. 构建并启动
docker-compose up -d --build

# 3. 查看日志
docker-compose logs -f

# 4. 停止服务
docker-compose down
```

### 单独使用 Docker

```bash
# 构建镜像
docker build -t ygadmin .

# 运行容器
docker run -d -p 8001:8001 \
  -e SUPABASE_URL=your-url \
  -e SUPABASE_KEY=your-key \
  -e SECRET_KEY=your-secret \
  ygadmin
```

## 📚 API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 登录/注册页面 |
| POST | `/login` | 处理登录 |
| POST | `/register` | 处理注册 |
| GET | `/logout` | 登出 |
| GET | `/welcome` | 欢迎页面（需登录） |
| GET | `/profile` | 资料填写页面（需登录） |
| POST | `/save-profile` | 保存用户资料 |
| GET | `/health` | 健康检查 |

## 🔒 安全特性

- **HttpOnly Cookie** - 防止 XSS 攻击
- **JWT Token** - 安全的会话管理
- **CORS 配置** - 可配置的跨域策略
- **Secure Cookie** - 生产环境强制 HTTPS
- **请求限流** - Nginx 层面的 API 限流
- **安全响应头** - X-Frame-Options, X-Content-Type-Options 等

## 📝 配置说明

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `DEBUG` | 调试模式 | `false` |
| `HOST` | 监听地址 | `0.0.0.0` |
| `PORT` | 监听端口 | `8001` |
| `SUPABASE_URL` | Supabase 项目 URL | - |
| `SUPABASE_KEY` | Supabase Anon Key | - |
| `SECRET_KEY` | JWT 签名密钥 | - |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | Token 过期时间（分钟） | `1440` |

## 🛠️ 开发指南

### 添加新路由

1. 在 `app/routers/` 下创建新路由文件
2. 在 `app/main.py` 中注册路由：
   ```python
   from app.routers import new_router
   app.include_router(new_router.router)
   ```

### 添加新服务

1. 在 `app/services/` 下创建服务文件
2. 在路由中引入使用

### 日志使用

```python
from app.core.logging import get_logger

logger = get_logger(__name__)
logger.info("这是一条日志")
logger.error("这是错误日志")
```

## 📄 License

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！