介绍

Github 开源地址：

https://github.com/aminalaee/sqladmin

网站说明链接地址：

https://aminalaee.dev/sqladmin/

一个现代、优雅的 SQLAlchemy 管理后台工具，非常适合用在 FastAPI 项目中

SQLAdmin 是一个基于 FastAPI + SQLAlchemy 构建的管理后台框架，灵感来自于 Django Admin，目标是为 Python 项目提供：

• 🚀 简洁易用的后台界面

• 📋 基于 SQLAlchemy 的模型自动管理

• ⚙️ 快速 CRUD（增删改查）

• ✨ Jinja2 渲染漂亮的 Bootstrap 风格后台

功能	描述
🎨 UI	基于 Tabler（Bootstrap 风格）构建
🔁 CRUD 自动化	自动根据模型生成增删改查
🔍 搜索 / 过滤	表字段搜索、过滤支持
🧩 多数据库支持	支持 SQLite、PostgreSQL、MySQL 等
🔐 自定义认证	可扩展自定义登录（如你用的 AdminAuth）
🧠 异步支持	与 FastAPI 完美配合，支持异步视图
🔧 高度可配置	支持列隐藏、格式化、标签等配置项

支持models 的类型：

✅ 支持 SQLAlchemy 吗？	是，必须基于 SQLAlchemy ORM 模型
✅ 支持 SQLAlchemy 1.x 吗？	是
✅ 支持 SQLAlchemy 2.x 吗？	是，从 sqladmin 0.15.0+ 开始全面支持
❌ 支持 Tortoise ORM 吗？	不支持
❌ 支持 Django ORM 吗？	不支持

为什么使用？

很多项目都是异步，而异步里面ORM 性能最好的就是 SQLAlchemy 2.0

特性	优势	是否推荐
✅ 新的 2.0 风格语法	更清晰、类型安全，统一 async / sync 用法	强烈推荐
✅ 原生异步支持（async_engine）	适配 FastAPI、aiohttp 等异步框架	✔
✅ Declarative Mapping 更加清晰	不再混用 Base = declarative_base() 和 mapper()	✔
✅ 更强的类型提示支持	IDE 友好，调试更舒服	✔
✅ Session 语义改进	显式事务控制、更加安全	✔
✅ 官方长期维护方向	所有新功能只在 2.x 上更新	✔

特性 / 框架	SQLAlchemy 2.0 (async)	Tortoise ORM	asyncpg (原生驱动)
⭐ 异步支持	✅ 原生 async API（2.0 起）	✅ 原生 async	✅ 原生 async
🎯 ORM 支持	✅ 完整 ORM（经典 + 声明式）	✅ 类 Django 的 ORM	❌ 没有 ORM，需手写 SQL
⚙️ 事务处理	✅ async with session.begin()	✅ transaction() 上下文	✅ 需手动写 SQL + 事务处理
🔧 灵活性	✅ 高（支持 ORM + Core）	中等（ORM风格较固定）	极高（最贴近 SQL）
📚 学习曲线	稍高（但文档全）	较低，适合 Django 用户	中等（需掌握 SQL）
🚀 性能	优（合理用 async）	优（轻量）	最优（直接操作 protocol）
✅ 类型支持	✅ Pydantic 配合良好	✅ 也能配合 Pydantic 使用	❌ 无自动转换，手动处理
🧩 支持的数据库	多（PostgreSQL, MySQL, SQLite等）	PostgreSQL、MySQL、SQLite	PostgreSQL 专用
🔍 社区 & 文档	非常成熟（官方长期维护）	活跃，偏小众	官方是 PostgreSQL 的推荐驱动

你的需求	推荐方案
需要强大的 ORM + 类型检查 + 可扩展性	✅ SQLAlchemy 2.0 + Async
想快速上手、有 Django ORM 背景	✅ Tortoise ORM
要极致性能，手写 SQL 不怕麻烦	✅ asyncpg

结合应用

from sqlalchemy import Column, Integer, String, create_engine,Enum as SAEnum,JSON
from sqladmin.authentication import AuthenticationBackend
import json
import hashlib
from sqlalchemy import eventfrom sqlalchemy.orm import declarative_base
from enum import Enum
from sqlalchemy.ext.hybrid import hybrid_propertyBase = declarative_base()
engine = create_engine("sqlite:///example.db",connect_args={"check_same_thread": False},
)# 定义枚举类型
class GenderEnum(str, Enum):MALE = "male"FEMALE = "female"OTHER = "other"class User(Base):__tablename__ = "users"id = Column(Integer, primary_key=True)name = Column(String)gender = Column(SAEnum(GenderEnum), nullable=False, comment="性别")password = Column("password", String, nullable=False)  # 真实存储加密后的密码class JsonConfig(Base):__tablename__ = "json_config"id = Column(Integer, primary_key=True)name = Column(String)config = Column(JSON)Base.metadata.create_all(engine)  # Create tables，后面改了字段需要删除from fastapi import FastAPI
from sqladmin import Admin, ModelView
from fastapi import Requestapp = FastAPI()class AdminAuth(AuthenticationBackend):async def login(self, request: Request) -> bool:form = await request.form()username, password = form["username"], form["password"]# Validate username/password credentials# And update sessionif username == "admin" and password == "123456":request.session.update({"sqladmin_token": "..."})return Trueelse:return Falsereturn Trueasync def logout(self, request: Request) -> bool:# Usually you'd want to just clear the sessionrequest.session.clear()return Trueasync def authenticate(self, request: Request) -> bool:token = request.session.get("sqladmin_token")if not token:return False# Check the token in depthreturn Trueauthentication_backend = AdminAuth(secret_key="secret_key")admin = Admin(app, engine,base_url="/super",authentication_backend=authentication_backend)class UserAdmin(ModelView, model=User):self_md5_salt = "123456"column_list = [User.id, User.name,User.gender,User.password]# 自定义列标签（让 SQLAdmin UI 显示中文）column_labels = {"id": "用户 ID","name": "姓名","gender": "性别","password": "密码",}async def insert_model(self, request: Request, data: dict):"""拦截插入逻辑，确保 `password` 经过 MD5 加密"""raw_password = data.pop("password", None)if raw_password:data["password"] = hashlib.md5((raw_password+self.self_md5_salt).encode()).hexdigest()return await super().insert_model(request, data)async def update_model(self, request: Request, pk: str, data: dict):"""拦截更新逻辑，确保 `password` 经过 MD5 加密"""raw_password = data.pop("password", None)if raw_password:data["password"] = hashlib.md5((raw_password+self.self_md5_salt).encode()).hexdigest()return await super().update_model(request, pk, data)class JsonConfigAdmin(ModelView, model=JsonConfig): column_list = [JsonConfig.id, JsonConfig.name,JsonConfig.config]# 前端页面插入的时候 只能使用双引号的json 不能使用单引号的jsonadmin.add_view(UserAdmin)
admin.add_view(JsonConfigAdmin)if __name__ == "__main__":import uvicornuvicorn.run(app, host="127.0.0.1", port=8000)
# uvicorn test_sqladmin:app --host 127.0.0.1 --port 8000 --reload
# 后台地址： http://127.0.0.1:8000/super# pip install itsdangerous  sqladmin