nova-admin 1.0.0

Enterprise-level FastAPI admin framework with SQLModel and Starlette Admin

Nova Admin

🏗️ 企业级 FastAPI 后台管理框架

基于 FastAPI + SQLModel + Starlette Admin 构建，集成权限、多租户、工作流、报表、API 网关等全套企业级功能的一站式后台解决方案。

---

📋 项目状态

Phase	版本	状态
Phase 1: MVP	v0.1.0	✅ 已完成
Phase 2: 进阶功能	v0.5.0	✅ 已完成
Phase 2.5: 用户认证增强	v0.6.6	✅ 已完成
Phase 3: 功能完善	v1.0.0	✅ 100% 完成

---

🚀 核心特性

基础能力

• 🚀 异步高性能 — 基于 FastAPI 原生异步支持
• 🔐 RBAC 权限系统 — 用户-角色-权限三级模型，支持行级数据权限
• 🏢 多租户支持 — 字段隔离策略，自动租户过滤
• 📝 灵活 CRUD — 物理删除/逻辑删除切换，乐观锁并发控制
• 🔒 安全防护 — SQL 注入检测、XSS 防护、限流保护
• 🌍 国际化 (i18n) — 内置多语言支持，可扩展翻译管理

进阶功能

• 🎨 主题系统 — 支持多主题切换（亮色/暗色），CSS 变量，自定义主题
• 🔌 插件系统 — 插件生命周期管理，钩子系统，插件配置
• 📊 Dashboard 组件 — 统计卡片、折线图、柱状图、饼图、表格组件的可视化看板
• 📈 报表系统 — 5 类报表（业务/系统/财务/运营/自定义），8 种图表类型，定时报表，多维分析
• ⚙️ 工作流引擎 — 审批流（或签/会签/依次审批），条件分支，抄送，驳回/退回，任务分配
• 📁 文件管理 — 完整的上传、下载、存储、预览功能
• 📋 数据导入导出 — CSV/Excel/JSON 双向导入导出

微服务&部署

• 🌐 API 网关 — 动态路由、熔断器（CLOSED→OPEN→HALF_OPEN）、负载均衡（轮询/加权/一致性Hash）、API 版本管理
• 🔍 服务注册与发现 — 内存/Consul/DNS 后端，心跳检测，标签过滤
• ⚙️ 配置中心 — YAML/JSON 热加载，环境变量覆盖，命名空间隔离
• 🔗 分布式追踪 — W3C Trace Context 传播，Span 嵌套，Jaeger/Zipkin 导出
• 🐳 容器化部署 — Docker 镜像、Docker Compose 微服务编排、Kubernetes 配置（含 HPA）
• 📋 CI/CD 流水线 — GitHub Actions：测试（3 个 Python 版本）、Lint、Build、PyPI 发布、Docker 镜像

---

🛠️ 技术栈

组件	技术	说明
Web 框架	FastAPI	高性能异步 Web 框架，自动 OpenAPI 文档
ORM	SQLModel	Pydantic + SQLAlchemy 合体，类型安全
数据库迁移	Alembic	SQLAlchemy 官方迁移工具
Admin UI	Starlette Admin	多 ORM 支持，Tabler UI 界面
API 文档	Scalar	现代化 API 文档 UI
日志	Loguru	开箱即用，比 logging 友好
配置管理	Pydantic Settings	类型安全，多环境支持
缓存	Redis / InMemory	可插拔缓存后端
依赖管理	UV	Rust 编写的极速包管理器

---

📦 安装

# 使用 UV 安装
uv pip install nova-admin

# 或使用 pip
pip install nova-admin

# 安装可选依赖
pip install "nova-admin[postgres]"    # PostgreSQL 支持
pip install "nova-admin[mysql]"       # MySQL 支持
pip install "nova-admin[redis]"       # Redis 缓存支持
pip install "nova-admin[all]"         # 全部功能

---

🚀 快速开始

最简示例

from fastapi import FastAPI
from sqlmodel import SQLModel, Field, create_engine
from nova_admin import Admin, ModelView

class User(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    username: str
    email: str

app = FastAPI()
engine = create_engine("sqlite:///./app.db")

admin = Admin(engine, title="Nova Admin")
admin.add_view(ModelView(User))
admin.mount_to(app)

# 访问 http://localhost:8000/admin

CRUD API 快速生成

from fastapi import FastAPI
from nova_admin.api.crud_api import create_crud_router

app = FastAPI()

# 一行代码为任意 Model 生成完整 CRUD 路由
# app.include_router(create_crud_router(User, prefix="/api/users"))

完整示例

cd examples/complete_demo
python main.py
# 默认账号: admin / admin123
# API: http://localhost:8000/docs
# Admin: http://localhost:8000/admin

---

📚 文档

文档	说明
项目概述	项目介绍和功能概览
技术可行性分析	技术选型和可行性评估
架构设计	系统架构和模块设计
RBAC 权限系统	权限模型和使用方法
多租户设计	多租户实现方案
CRUD 基类	CRUD 操作封装与高级用法
开发计划	开发进度和里程碑
认证系统完善方案	认证增强详细方案
认证使用指南	认证系统快速上手指南

---

📁 项目结构

nova-admin/
├── nova_admin/                    # 核心代码包
│   ├── core/                      # 核心模块
│   │   ├── config.py              # 配置管理
│   │   ├── database.py            # 数据库连接
│   │   ├── database_multi.py      # 多数据库支持
│   │   ├── logging.py             # 日志配置
│   │   ├── security.py            # 安全认证
│   │   ├── security_audit.py      # 安全审计
│   │   ├── auth_manager.py        # 认证管理器
│   │   └── response.py            # 统一响应
│   ├── models/                    # 数据模型
│   │   ├── base.py                # 基础模型 Mixin
│   │   ├── system.py              # 系统模型
│   │   ├── auth.py                # 认证模型
│   │   ├── workflow.py            # 工作流模型
│   │   └── report.py              # 报表模型
│   ├── admin/                     # Admin 模块
│   │   ├── base.py                # Admin 基类
│   │   ├── views.py               # ModelView 视图
│   │   ├── auth.py                # Admin 认证
│   │   └── data_permission.py     # 行级权限
│   ├── api/                       # API 路由
│   │   ├── auth.py                # 认证 API
│   │   ├── oauth.py               # OAuth2.0 API
│   │   ├── chinese_oauth.py       # 国内平台 OAuth
│   │   ├── saml.py                # SAML 2.0 API
│   │   ├── audit.py               # 审计日志 API
│   │   ├── crud_api.py            # 高级 CRUD API
│   │   ├── workflow_api.py        # 工作流 API
│   │   └── report_api.py          # 报表 API
│   ├── crud/                      # CRUD 服务层
│   │   ├── base.py                # CRUD 基类
│   │   └── tenant_aware.py        # 多租户 CRUD
│   ├── services/                  # 业务服务
│   │   ├── email_service.py       # 邮件服务
│   │   ├── token_manager.py       # Token 管理
│   │   ├── permission_service.py  # 权限服务
│   │   ├── two_factor_service.py  # 双因素认证
│   │   ├── login_security_service.py  # 登录安全
│   │   ├── oauth_service.py       # OAuth2.0 服务
│   │   ├── saml_service.py        # SAML 服务
│   │   ├── audit_log_service.py   # 审计日志
│   │   ├── advanced_crud_service.py  # 高级 CRUD 服务
│   │   ├── workflow_service.py    # 工作流引擎
│   │   └── report_service.py      # 报表引擎
│   ├── extensions/                # 扩展模块
│   │   ├── permission_service.py  # 权限服务
│   │   ├── tenant_middleware.py   # 租户中间件
│   │   ├── audit_log.py           # 审计日志
│   │   ├── file_upload.py         # 文件上传
│   │   ├── data_io.py             # 数据导入导出
│   │   ├── quota_service.py       # 配额管理
│   │   ├── cache.py               # 缓存管理
│   │   ├── rate_limiter.py        # 限流保护
│   │   ├── plugin_system.py       # 插件系统
│   │   ├── theme_system.py        # 主题系统
│   │   ├── dashboard.py           # Dashboard 组件
│   │   ├── i18n.py                # 国际化
│   │   ├── api_gateway.py         # API 网关
│   │   ├── healthcheck.py         # 健康检查
│   │   ├── service_registry.py    # 服务注册与发现
│   │   ├── config_center.py       # 配置中心
│   │   └── distributed_tracing.py # 分布式追踪
│   └── cli/                       # CLI 工具
│       ├── generator.py           # 代码生成器
│       └── commands.py            # CLI 命令
├── examples/                      # 示例项目
│   ├── basic/                     # 基础示例
│   └── complete_demo/             # 完整示例
├── deploy/                        # 部署配置
│   └── k8s-nova-admin.yaml        # Kubernetes 部署
├── .github/workflows/
│   └── ci-cd.yml                  # CI/CD 流水线
├── docs/                          # 文档
├── tests/                         # 测试
├── alembic/                       # 数据库迁移
├── Dockerfile                     # 多阶段构建
├── docker-compose.yml             # 微服务编排
└── pyproject.toml                 # 项目配置

---

🐳 Docker 部署

# 使用 Docker Compose（PostgreSQL + Redis + API Gateway + Auth + Worker）
docker-compose up -d

# 仅构建并运行单个服务
docker build -t nova-admin .
docker run -p 8000:8000 nova-admin

# Kubernetes 部署
kubectl apply -f deploy/k8s-nova-admin.yaml

---

🔨 CLI 工具

# 创建新模块
nova-admin generate model Product --fields name:str,price:float,stock:int

# 从数据库反向生成
nova-admin generate from-db --table products --model Product

# 运行迁移
nova-admin migrate --autogenerate -m "Add product table"

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

---

📄 许可证

本项目采用 Apache 2.0 License 开源协议。

---

Made with ❤️ by william.ren