CentOS下SQLAdmin插件与扩展使用指南

一、基础环境准备

在CentOS上使用SQLAdmin前，需先安装Python 3.7+、FastAPI、SQLAlchemy及数据库驱动（如pymysql for MySQL、asyncpg for PostgreSQL）。推荐使用虚拟环境隔离依赖：

# 创建并激活虚拟环境
python3 -m venv sqladmin_env
source sqladmin_env/bin/activate

# 安装核心依赖
pip install "sqladmin[fastapi]" sqlalchemy pymysql

二、插件/扩展类型及安装

SQLAdmin的扩展主要分为官方内置扩展（如权限控制、元数据定制）和第三方自定义扩展（如报表、自定义操作）。以下是常见扩展的安装与配置：

1. 官方内置扩展：权限控制

权限控制是SQLAdmin的核心扩展之一，可通过配置ModelView类的属性限制用户操作：

from sqladmin import ModelView
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String)

class UserAdmin(ModelView, model=User):
    # 允许创建、编辑，禁止删除
    can_create = True
    can_edit = True
    can_delete = False
    
    # 允许查看详情、导出数据
    can_view_details = True
    can_export = True
    
    # 模型显示配置
    name = "用户"  # 后台显示名称
    name_plural = "用户列表"
    icon = "fa-user"  # FontAwesome图标

说明：通过can_create、can_edit等布尔属性，可快速控制模型的增删改查权限。

2. 第三方自定义扩展：报表视图

若需添加数据报表功能，可通过继承BaseView创建自定义视图。以下是一个用户数量统计报表示例：

from sqladmin import BaseView, expose
from sqlalchemy import select, func
from sqlalchemy.ext.asyncio import AsyncSession
from fastapi import Request

class ReportView(BaseView):
    name = "数据报表"  # 导航栏显示名称
    icon = "fa-solid fa-chart-line"  # 图标
    
    @expose("/report", methods=["GET"])
    async def report_page(self, request: Request):
        # 执行SQL查询（异步）
        async with AsyncSession(self.engine) as session:
            stmt = select(func.count(User.id)).select_from(User)
            result = await session.execute(stmt)
            users_count = result.scalar_one()
        
        # 渲染模板（需创建templates/report.html）
        return await self.templates.TemplateResponse(
            request, 
            "report.html", 
            {"users_count": users_count}
        )

# 注册视图到Admin
admin.add_view(ReportView(name="报表", icon="fa-chart-line"))

说明：自定义视图需继承BaseView，通过@expose装饰器定义路由，使用TemplateResponse渲染HTML模板。

3. 模型视图扩展：自定义表单

若需调整模型表单的字段或校验规则，可通过form_columns和form_extra_fields配置：

from wtforms import StringField, validators
from sqladmin import ModelView

class UserAdmin(ModelView, model=User):
    # 仅显示id、name、email字段
    form_columns = ["id", "name", "email"]
    
    # 添加自定义校验（如email必填）
    form_extra_fields = {
        "email": StringField(
            "邮箱", 
            validators=[validators.DataRequired(), validators.Email()]
        )
    }

说明：form_columns控制表单显示的字段，form_extra_fields可添加自定义表单字段及校验规则。

三、自定义扩展开发步骤

若内置扩展无法满足需求，可开发自定义扩展。以下是详细步骤：

1. 创建自定义视图类

继承BaseView，定义路由和处理逻辑。例如，添加一个用户批量删除的自定义操作：

from sqladmin import BaseView, expose
from fastapi import Request, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import delete

class UserBulkDeleteView(BaseView):
    name = "批量删除"
    icon = "fa-solid fa-trash"
    
    @expose("/bulk-delete", methods=["POST"])
    async def bulk_delete(self, request: Request, session: AsyncSession = Depends(get_session)):
        # 获取前端传递的用户ID列表
        user_ids = request.json().get("ids", [])
        
        # 执行批量删除
        if user_ids:
            stmt = delete(User).where(User.id.in_(user_ids))
            await session.execute(stmt)
            await session.commit()
        
        return {"status": "success", "message": f"成功删除{len(user_ids)}条记录"}

2. 注册扩展到Admin

将自定义视图添加到Admin实例：

admin = Admin(app, engine, title="我的后台")
admin.add_view(UserBulkDeleteView(name="批量操作", icon="fa-tools"))

3. 配置模板（可选）

若需自定义视图的前端页面，可在项目根目录下创建templates文件夹，添加HTML模板（如report.html）。SQLAdmin默认使用Tabler主题，可通过修改模板继承Tabler的样式。

四、配置文件管理

SQLAdmin的配置文件通常位于项目根目录下的sqladmin.conf（或通过代码配置）。以下是常见配置项：

# 数据库连接配置
[database]
host = localhost
port = 3306
user = root
password = your_password
database = mydb

# 服务器配置
[server]
host = 0.0.0.0
port = 8000

# 日志配置
[logging]
level = INFO
file = /var/log/sqladmin.log

说明：通过配置文件可管理数据库连接、服务器端口、日志级别等参数，避免硬编码。

五、常见问题解决

1. 插件加载失败

• 原因：依赖未安装或版本冲突。
• 解决：检查pip freeze确认依赖版本，使用虚拟环境隔离。

2. 权限不生效

• 原因：can_xxx属性未正确设置或用户角色未配置。
• 解决：确认ModelView中的权限属性（如can_delete），确保用户角色拥有对应权限。

3. 自定义视图无法访问

• 原因：路由未正确注册或模板路径错误。
• 解决：检查admin.add_view()是否调用，确认templates目录路径正确。

通过以上步骤，可在CentOS上快速使用SQLAdmin的插件与扩展，定制符合业务需求的管理后台。如需更复杂的功能，可参考SQLAdmin的官方文档（GitHub Wiki）获取更多示例。