# universalAdmin

**Repository Path**: ainiyaer_admin/universal-admin

## Basic Information

- **Project Name**: universalAdmin
- **Description**: 通用中后台项目(含有颗粒权限)

- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-27
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI + Vue3 通用中后台(按钮级权限)
**项目速览**
![截屏2025-11-10 19.12.46](assets/%E6%88%AA%E5%B1%8F2025-11-10%2019.12.46.png)

![截屏2025-11-10 19.13.05](assets/%E6%88%AA%E5%B1%8F2025-11-10%2019.13.05.png)


![截屏2025-11-10 19.13.14](assets/%E6%88%AA%E5%B1%8F2025-11-10%2019.13.14.png)


**项目技术栈速览**

| 层级        | 技术                                                 | 一句话定位                       |
|-----------|----------------------------------------------------|-----------------------------|
| **前端框架**  | Vue 3.5 + Vite 7                                   | 极速冷启动、Composition API 全面拥抱  |
| **UI 框架** | Naive UI 2.42                                      | 大厂级组件 + 主题变量，零配置暗黑模式        |
| **状态管理**  | Pinia 3                                            | TypeScript 原生 Store，模块热替换   |
| **路由**    | Vue-Router 4.5                                     | 支持动态路由、权限守卫                 |
| **网络库**   | Axios 1.11（二次封装）                                   | 重试/缓存/并发/优先级/取消，一行调用        |
| **图表**    | ECharts 6                                          | 响应式图表，一键导入                  |
| **代码高亮**  | highlight.js 11                                    | Markdown / SQL / JSON 高亮零配置 |
| **工具链**   | unplugin-vue-components + vite-plugin-vue-devtools | 自动按需引入 + 调试神器               |
| **样式**    | Sass 1.90 + vfonts                                 | 变量主题 + 字体 CDN               |
| **后端框架**  | FastAPI 0.118                                      | 自动生成 OpenAPI 文档，Pydantic 校验 |
| **ORM**   | SQLAlchemy 2.0                                  | 同步异步双模式，Alembic 一行迁移，复杂查询还能链式   |
| **任务队列**  | Celery 5.5 + Redis                                 | 高并发异步任务，实时 Flower 监控        |
| **鉴权**    | python-jose + passlib                              | JWT + Argon2 加密             |
| **文件存储**  | 阿里云 OSS / 七牛 / COS                                 | 一行配置多平台                     |
| **部署**    | Uvicorn + Gunicorn + Docker                        | 容器化一键上线                     |

## 前段

- 前端.vue 文件在 TypeScript 中的类型支持
    - 默认情况下，TypeScript 无法识别 .vue 文件导入的类型信息，因此我们将 tsc CLI 替换为 vue-tsc 来做类型检查。
      在编辑器里，需要安装 Volar（VS Code 插件）才能让 TypeScript 语言服务正确识别 .vue 文件的类型。

#### 项目依赖安装

```sh
pnpm install
```

#### 项目运行

```sh
pnpm dev
```

#### 类型检查、编译并压缩以供生产环境部署

```sh
pnpm build
```

## 后端
<span style="color:red">当前建议使用 Python 3.12 版本，因为新发布的 Python 3.13 版本与许多第三方库的兼容性尚有待完善。</span>

**目录结构**

```
 backend/   后端根目录
    ├──app/    应用
    │  ├──api/   控制器(router)
    │  ├──celerys/ 分布式任务
    │  ├──common/ 公用
    │  │  ├──exception/  异常处理
    │  │  ├──common_fuc.py  公用函数
    │  │  ├──pagination.py  公用函数
    │  │  ├──response.py    统一返回
    │  │  ├──timer.py       定时器
    │  │  └──tools.py       工具函数
    │  ├──core/ 配置
    │  │  ├──config.py     配置
    │  │  └──db.py         数据库会话管理
    │  ├──enum/   枚举
    │  ├──libs/ 扩展包
    │  │  ├──captcha       验证码
    │  │  ├──oss_file      oss文件
    │  │  ├──ras           ras加密工具
    │  │  ├──wechat        微信工具
    │  │  └──wsocket       websokcet
    │  ├──models/ 数据库模型
    │  ├──schemas/      数据验证/数据序列化
    │  ├──service/      业务层
    │  └──utils/   工具类
    │  │  ├──files.py  文件处理工具(上传，下载)
    │  │  ├──jwt.py    jwt工具
    │  │  ├──log.py    日志工具
    │  │  └──redis.py  redis缓存工具
    │  └──__init__.py   应用管理
    │  ├──decorator.py    装饰器函数
    │  ├──middleware.py 中间件
    │  ├──security.py   权限鉴
    ├──logs/   日志
    ├──static/ 静态文件  
    ├──.env    项目配置 
    ├──main.py 项目入口
    └──requirements.txt  项目依赖的文件
```

## 部署及安装

### 执行一下命令安装依赖包

```sh
pip install -r requirements.txt
```

### 数据库迁移（SQLAlchemy 2.0）
- 1.在项目根目录生成 migrations 仓库
    ```shell
    alembic init migrations
    ```
    目录结构如下：
    ```sh
    project/
        ├─ alembic.ini              # 主配置
        └─ migrations/
            ├─ env.py                # 运行环境
            ├─ script.py.mako        # 脚本模板
            └─ versions/             # 生成的迁移文件
    ```
- 2.配置
    migrations/env.py中添加以下内容 
    ```py
    import sys, os
    sys.path.append(os.path.dirname(os.path.dirname(__file__)))  # 把项目根加入 PYTHONPATH

    from app.models import DatabaseModel   # 你的 DeclarativeBase 子类
    import app.models                      # 触发模型加载

    target_metadata = DatabaseModel.metadata  # 关键：告诉 Alembic 扫描哪些表
    ```
    migrations/env.py完整版(复制粘贴即可用)：
    ```py
    import os
    import sys
    from logging.config import fileConfig

    from sqlalchemy import engine_from_config
    from sqlalchemy import pool

    from alembic import context


    sys.path.append(os.path.dirname(os.path.dirname(__file__)))

    from app.models import DatabaseModel
    import app.models



    from app.core.config import conf


    # this is the Alembic Config object, which provides
    # access to the values within the .ini file in use.
    
    config = context.config
    config.set_main_option('sqlalchemy.url', conf.database.sync_url)
    
    # Interpret the config file for Python logging.
    # This line sets up loggers basically.
    
    if config.config_file_name is not None:
        fileConfig(config.config_file_name)

    # add your model's MetaData object here
    # for 'autogenerate' support
    # from myapp import mymodel
    # target_metadata = mymodel.Base.metadata

    target_metadata = DatabaseModel.metadata

    # other values from the config, defined by the needs of env.py,
    # can be acquired:
    # my_important_option = config.get_main_option("my_important_option")
    # ... etc.


    def run_migrations_offline() -> None:
        """Run migrations in 'offline' mode.

        This configures the context with just a URL
        and not an Engine, though an Engine is acceptable
        here as well.  By skipping the Engine creation
        we don't even need a DBAPI to be available.

        Calls to context.execute() here emit the given string to the
        script output.

        """
        url = config.get_main_option("sqlalchemy.url")
        context.configure(
            url=url,
            target_metadata=target_metadata,
            literal_binds=True,
            dialect_opts={"paramstyle": "named"},
        )

        with context.begin_transaction():
            context.run_migrations()


    def run_migrations_online() -> None:
        """Run migrations in 'online' mode.

        In this scenario we need to create an Engine
        and associate a connection with the context.

        """
        connectable = engine_from_config(
            config.get_section(config.config_ini_section, {}),
            prefix="sqlalchemy.",
            poolclass=pool.NullPool,
        )

        with connectable.connect() as connection:
            context.configure(
                connection=connection, target_metadata=target_metadata
            )

            with context.begin_transaction():
                context.run_migrations()


    if context.is_offline_mode():
        run_migrations_offline()
    else:
        run_migrations_online()
    
    ```
    
    
    
    
- 3.然后执行以下命令
    ```sh 
    # 环境是否能连接 + 元数据完整
    alembic check 
    
    #生成迁移脚本
    alembic revision --autogenerate -m "init"
    
    #把迁移真正执行到数据库
    alembic upgrade head
    ```
    - 日常迁移(改完模型后)
    ```sh
    alembic revision --autogenerate -m "描述"  
    
    #更新
    alembic upgrade head
    ```
     



### 分布式任务

- 在默认情况下，系统使用 RabbitMQ
  作为消息队列服务。用户可以根据实际业务需求对相关配置进行调整，具体修改可参考以下文件路径：<br/>
  `app/celerys/__init__.py`

  ```py
    # Rabbitmq版本
    celery_app = Celery(
            "tasks",
            broker="amqp://guest:guest@localhost:5672//",
            backend="rpc://",
            include=["app.celerys.order"]  # 包含任务模块
    )
        
    # redis版本
    celery_app = Celery(
        "tasks",
        broker="redis://localhost:6379/0",  # 使用 Redis 作为 Broker
        backend="redis://localhost:6379/1",  # 存储任务结果（可选）
        include=["app.celerys.order"]  # 包含任务模块
    )
    ```

  - <span>最后记得启动分布式任务服务：celery</span>

    ```bash 
     celery -A app.celerys:celery_app worker --loglevel=info
    ```

    | 参数部分              |      作用      | 必填 |    默认值    |
    |:------------------|:------------:|:--:|:---------:|
    | `celery`          |     主命令      | ✅  |     -     |
    | `-A celerys`      | 指定Celery应用模块 | ✅  |     -     |
    | `worker`          |    启动工作进程    | ✅  |     -     |
    | `--loglevel=info` |    设置日志级别    | ❌  | `warning` |

### 导出所使用的包

```bash
pip freeze > requirements.txt

# 如果出现 pandas @ file:///private/var...

# 使用以下的
pip list --format=freeze > requirements.txt
```

### 初次运行项目可能出现的问题(如果不出现请忽略)

1.如果报以下错误:

```sh
line 620, in _load_backend_mixin
version = _bcrypt.__about__.__version__
              ^^^^^^^^^^^^^^^^^
AttributeError: module 'bcrypt' has no attribute '__about__'
 # 修改源码中的passlib/handlers/bcrypt.py
  version = _bcrypt.__about__.__version__ 
  # 改为以下
   version = _bcrypt.__version__
```