# flask-rbac-api

**Repository Path**: ceagle/flask-rbac-api

## Basic Information

- **Project Name**: flask-rbac-api
- **Description**: flask-rbac-api
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2025-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flask RBAC API

基于 Flask 框架的 RBAC（基于角色的访问控制）API 权限控制系统。本项目实现了一套完整的用户认证、角色管理和权限控制机制，适用于需要精细权限管理的 Web 应用。

## 功能特点

- 基于 JWT 的用户认证
- 基于 RBAC 的权限控制装饰器
- 用户、角色、权限的完整管理 API
- 灵活的权限分配机制
- 完整的测试用例
- 使用 uv 管理 Python 环境

## 项目结构

```
flask-rbac-api/
├── app.py              # 应用入口
├── config.py           # 配置文件
├── models.py           # 数据库模型
├── rbac.py             # RBAC 权限控制装饰器
├── auth.py             # 认证相关 API
├── api.py              # 业务 API
├── init_db.py          # 数据库初始化脚本
├── tests.py            # 测试脚本
├── requirements.txt    # 依赖包列表
└── .env.example        # 环境变量示例
```

## 环境搭建

### 前置条件

- Python 3.8+
- uv 包管理工具

### 安装步骤

1. 克隆项目

```bash
git clone https://gitee.com/ceagle/flask-rbac-api.git
cd flask-rbac-api
```

2. 使用 uv 创建虚拟环境并安装依赖

```bash
uv venv
source .venv/bin/activate  # Linux/macOS
# 或者 .venv\Scripts\activate  # Windows
uv pip install -r requirements.txt
```

3. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，设置适当的配置值
```

4. 初始化数据库

```bash
python init_db.py
```

## 运行应用

```bash
python app.py
```

应用将在 http://localhost:5000 上运行。

## API 端点

### 认证 API

- `POST /auth/register` - 用户注册
- `POST /auth/login` - 用户登录
- `GET /auth/profile` - 获取当前用户信息

### 用户管理 API

- `GET /api/users` - 获取所有用户列表
- `GET /api/users/<id>` - 获取指定用户信息
- `PUT /api/users/<id>` - 更新用户信息
- `DELETE /api/users/<id>` - 删除用户
- `PUT /api/users/<id>/roles` - 更新用户角色

### 角色管理 API

- `GET /api/roles` - 获取所有角色列表
- `POST /api/roles` - 创建新角色
- `PUT /api/roles/<id>` - 更新角色信息
- `DELETE /api/roles/<id>` - 删除角色

### 权限管理 API

- `GET /api/permissions` - 获取所有权限列表
- `POST /api/permissions` - 创建新权限

### 测试 API

- `GET /api/test/public` - 公开 API
- `GET /api/test/authenticated` - 需要认证的 API
- `GET /api/test/admin` - 需要管理员权限的 API
- `GET /api/test/editor` - 需要编辑者角色的 API
- `GET /api/test/permission` - 需要特定权限的 API

## 测试

运行测试用例：

```bash
python -m unittest tests.py
```

## RBAC 权限控制装饰器使用示例

```python
# 基本用法
@rbac_required(resource='user', action='create')
def create_user():
    # 实现创建用户的逻辑
    pass

# 基于角色的控制
@rbac_required(roles=['admin'])
def admin_only():
    # 只有管理员可以访问
    pass

# 基于权限的控制
@rbac_required(permissions=['user:delete'])
def delete_user():
    # 需要 user:delete 权限
    pass

# 便捷装饰器
@admin_required
def another_admin_only():
    # 只有管理员可以访问
    pass

@permission_required('content:publish')
def publish_content():
    # 需要 content:publish 权限
    pass

@role_required('editor')
def editor_only():
    # 需要编辑者角色
    pass
```
## 测试
```bash
# 启动应用
python run.py

# 注册用户
curl -s -X POST 'http://localhost:5000/auth/register' -H 'Content-Type: application/json' -d '{"username":"testuser","password":"test123","email":"test@example.com"}'

# 登录获取访问令牌
curl -s -X POST 'http://localhost:5000/auth/login' -H 'Content-Type: application/json' -d '{"username":"admin","password":"admin123"}' 
```
## 生产环境部署

对于生产环境，建议：

1. 使用 Gunicorn 或 uWSGI 作为 WSGI 服务器
2. 使用 Nginx 作为反向代理
3. 使用 PostgreSQL 或 MySQL 作为数据库
4. 设置更强的密钥和密码
5. 启用 HTTPS

### 生产环境配置示例

```bash
# 安装生产环境依赖
uv pip install gunicorn psycopg2-binary

# 设置环境变量
export FLASK_ENV=production
export DATABASE_URI=postgresql://user:password@localhost/dbname

# 使用 Gunicorn 运行应用
gunicorn -w 4 -b 0.0.0.0:8000 'app:create_app("production")'
```

## 安全注意事项

- 在生产环境中更改所有默认密钥和密码
- 定期更新依赖包以修复安全漏洞
- 使用 HTTPS 加密传输数据
- 实施适当的速率限制以防止暴力攻击
- 定期审查用户权限

## 许可证

MIT