# gi-python

**Repository Path**: lin0716/gi-python

## Basic Information

- **Project Name**: gi-python
- **Description**: 一个python + uv管理 的后端项目
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 后台管理系统 — 后端

基于 **FastAPI + SQLModel + MySQL 8** 的最简后端项目，提供用户登录认证与用户基础 CRUD。

## 技术栈

| 组件 | 说明 |
|------|------|
| FastAPI | Web 框架 |
| SQLModel | ORM + API Schema（同步模式，底层 SQLAlchemy 2.0） |
| MySQL 8 | 数据库 |
| Alembic | 数据库迁移 |
| JWT + bcrypt | 认证与密码哈希 |
| uv | 依赖管理与运行 |
| pytest | 测试 |

## 目录结构

```
gi-python/
├── app/
│   ├── main.py              # 应用入口
│   ├── api/                 # 路由层
│   │   ├── deps.py          # 依赖注入（鉴权等）
│   │   └── v1/              # v1 版本 API
│   ├── core/                # 核心配置与安全
│   ├── db/                  # 数据库连接、类型、查询封装
│   ├── models/              # ORM 表模型 + 领域 Schema（UserOut 等）
│   ├── schemas/             # 通用 Schema（auth、分页参数等）
│   ├── services/            # 业务逻辑
│   └── middleware/          # 中间件
├── alembic/                 # 数据库迁移
├── scripts/
│   ├── seed.py              # 初始化默认账号
│   └── docker-entrypoint.sh # 容器启动脚本
├── tests/                   # 测试
├── .env.example             # 环境变量示例
├── docker-compose.yml       # MySQL 本地容器（开发）
├── docker-compose.prod.yml  # 生产编排（MySQL + App）
├── Dockerfile               # 应用镜像
└── deploy.sh                # 生产一键部署脚本
```

## 快速开始

### 1. 安装依赖

```bash
uv sync --extra dev
```

### 2. 启动 MySQL

```bash
docker compose up -d
```

### 3. 配置环境变量

```bash
copy .env.example .env
```

按需修改 `.env` 中的数据库连接和 JWT 密钥。

### 4. 执行数据库迁移

```bash
uv run alembic upgrade head
```

### 5. 启动服务（自动初始化默认数据）

```bash
uv run uvicorn app.main:app --reload
```

服务启动时会自动执行幂等 seed，写入默认角色、账号、字典与菜单（已存在则跳过）。

也可手动执行：

```bash
uv run python scripts/seed.py
```

默认账号：

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | 123456 | 管理员 |
| user | 123456 | 普通用户 |

访问 API 文档：http://localhost:8000/docs

## 生产部署（Docker）

适用于 Linux 服务器，通过 Docker Compose 同时启动 **MySQL 8** 与 **FastAPI 应用**。容器启动时会自动执行数据库迁移，应用启动后还会幂等写入默认 seed 数据。

### 前置条件

- 已安装 [Docker](https://docs.docker.com/engine/install/) 与 Docker Compose 插件（`docker compose version` 可用）
- 服务器开放 **8000** 端口（或自行修改 `docker-compose.prod.yml` 中的端口映射）
- 当前用户有权限执行 `docker` 命令

### 1. 获取代码

```bash
git clone <仓库地址> gi-python
cd gi-python
```

也可通过 `scp` 等方式上传代码目录；非 Git 目录时 `deploy.sh` 会跳过 `git pull`。

### 2. 配置生产环境变量

```bash
cp .env.example .env
```

编辑 `.env`，至少修改以下项：

| 变量 | 说明 |
|------|------|
| `DEBUG` | 生产环境设为 `false` |
| `JWT_SECRET_KEY` | 改为足够长的随机字符串 |
| `MYSQL_ROOT_PASSWORD` | MySQL root 强密码 |
| `DATABASE_URL` | 主机名必须为 `mysql`（容器内服务名），密码与 `MYSQL_ROOT_PASSWORD` 一致 |

生产示例：

```env
DEBUG=false
JWT_SECRET_KEY=your-random-secret-key
MYSQL_ROOT_PASSWORD=your-strong-mysql-password
DATABASE_URL=mysql+pymysql://root:your-strong-mysql-password@mysql:3306/gi_python_sql?charset=utf8mb4
```

> 注意：`DATABASE_URL` 中的密码若包含 `@`、`#`、`%` 等特殊字符，需进行 URL 编码。

### 3. 一键部署

```bash
bash deploy.sh
```

脚本会依次：检查 Docker → 拉取最新代码（Git 目录）→ 校验 `.env` → 构建镜像并启动容器 → 等待健康检查通过。

也可手动执行：

```bash
docker compose -f docker-compose.prod.yml up -d --build
```

### 4. 验证部署

```bash
curl http://127.0.0.1:8000/
```

浏览器访问 `http://<服务器IP>:8000/docs`。默认账号与本地开发相同（admin / 123456）。

### 常用运维命令

```bash
# 查看应用日志
docker compose -f docker-compose.prod.yml logs -f app

# 仅重启应用（不重建镜像）
bash deploy.sh restart

# 停止并移除容器（数据卷 mysql_data 会保留）
docker compose -f docker-compose.prod.yml down

# 停止并清除数据库数据（慎用）
docker compose -f docker-compose.prod.yml down -v
```

### 部署文件说明

| 文件 | 作用 |
|------|------|
| `Dockerfile` | 基于 Python 3.12 + uv 构建应用镜像 |
| `docker-compose.prod.yml` | 生产编排：MySQL + App，MySQL 不对外暴露端口 |
| `scripts/docker-entrypoint.sh` | 等待 MySQL 就绪 → 执行迁移 → 启动 uvicorn |
| `deploy.sh` | 部署脚本，含环境校验与健康检查 |
| `.dockerignore` | 排除测试、缓存等，减小镜像体积 |

### 已知注意点

- **密码一致性**：`MYSQL_ROOT_PASSWORD` 与 `DATABASE_URL` 中的密码必须相同，否则应用无法连接数据库。
- **首次部署较慢**：MySQL 健康检查与迁移可能需要 30～60 秒，`deploy.sh` 会等待最多约 60 秒。
- **Windows 开发上传**：若在 Windows 上编辑后上传到 Linux，shell 脚本需使用 LF 换行（项目已通过 `.gitattributes` 约束）；`deploy.sh` 需在 Linux / Git Bash 下执行，不能直接在 PowerShell 中运行。
- **本地 compose 区别**：`docker-compose.yml` 仅启动 MySQL，供宿主机开发；生产请使用 `docker-compose.prod.yml`。

## API 概览

### 认证 `/api/v1/auth`

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/login` | 公开 | 登录 |
| POST | `/refresh` | 公开 | 刷新 token |
| POST | `/logout` | 已登录 | 登出 |
| GET | `/me` | 已登录 | 当前用户信息 |

### 用户 `/api/v1/users`

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/` | admin | 分页列表 |
| GET | `/{id}` | admin 或本人 | 用户详情 |
| PUT | `/{id}` | admin 或本人 | 更新信息 |
| PUT | `/{id}/password` | admin 或本人 | 修改密码 |

### 统一响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "success": true
}
```

分页响应 `data` 结构：

```json
{
  "total": 100,
  "records": []
}
```

## 运行测试

测试使用 SQLite 内存数据库，无需启动 MySQL：

```bash
uv run pytest -v
```

## 权限说明

- **admin**：可查看/修改所有用户、重置他人密码
- **user**：仅可查看/修改自己的信息、修改自己的密码（需旧密码）

## 开发说明

- 分层架构：**Router → Service → Model**
- 路由层只做参数校验和响应包装，业务逻辑在 Service 层
- 数据库 schema 变更通过 Alembic 管理，不要手动改表
- 密码经 bcrypt 哈希存储，API 响应中永不返回 password 字段