FastapiAdmin SaaS 架构全景图

多租户企业级 SaaS 管理平台 · v3.6.0 · 40 个功能模块

40 模块 5 大分层 37 张数据库表 120+ API 端点

按功能领域分层展示全部 40 个模块,呈现"平台运营 → 租户管理 → 商业闭环 → 自动运维 → 基础设施"的五层产品架构

8
平台管理模块
11
租户管理模块
8
商业运营模块
7
插件扩展模块
6
基础设施模块

产品功能分层架构

自顶向下:对外接口层 → 平台管理层 → 租户管理层 → 商业运营层 → 自动化运维层 → 基础设施层。箭头表示依赖关系。

对外接口层 API Gateway RESTful API (/api/v1) JWT Bearer Token 鉴权 Swagger / Redoc 文档 API 限流 + 用量统计 平台管理层 Platform Admin (超管端) Tenant 租户管理 创建/启禁/冻结/归档 套餐变更 · 配额管理 到期处理 · 生命周期 Package 套餐管理 套餐CRUD · 菜单绑定 价格/周期/配额定义 默认套餐 · 试用配置 Ticket 工单管理 提交/处理/关闭 回复 · 关单原因 邮件通知集成 Dashboard 运营大盘 MRR / 退款率 / 活跃度 套餐分布 · 收入趋势 API 用量趋势图 AuditLog 审计日志 13 种审计事件 不可篡改 · 3年保留 CSV/JSON 导出 Order 订单支付 支付宝/微信支付 支付回调 · 幂等性 退款流程 · 原路退回 Invoice 发票管理 增值税普票/专票 百望云/票通对接 一单一票 · PDF下载 Email 邮件服务 SMTP 配置 · 模板管理 发送日志 · 站内信降级 5 大业务集成点 API Usage 用量统计 Redis 中间件计数 定时持久化 · 异常检测 429 限流保护 LoginLog 登录日志 登录成功/失败记录 IP/地域/设备追踪 异常登录检测 租户管理层 Tenant Admin (租户端) User 用户管理 CRUD · 状态 · 密码 多租户绑定 · 角色分配 邀请注册 · 邮箱验证 Role 角色权限 角色CRUD · 数据范围 菜单绑定 · owner保护 默认角色不可删除 Menu 菜单管理 树形结构 · 路由配置 按钮权限 · 图标 租户菜单授权 Dept 部门岗位 部门树 · 岗位管理 数据范围绑定 用户部门归属 Dict 数据字典 字典类型 · 字典值 Redis 缓存 前端全局数据源 Notice 通知公告 发布/编辑/撤回 已读未读状态追踪 站内信推送 SelfService 自助服务 自助选套餐 · 购买续费 套餐升级/降级预览 支付后自动激活 Invite 用户邀请 UUID 邀请码生成 邮件邀请 · 角色预分配 7天过期自动清理 Param 系统参数 系统级配置管理 租户配置覆盖 Redis 缓存 OpLog 操作日志 CRUD 操作追踪 请求参数 · 响应记录 IP/耗时/状态码 自动化运维层 Automation Cronjob 定时任务 到期扫描 · 订单过期 · 日志归档 · 发票清理 Workflow 工作流 审批流程 · 节点配置 · 条件分支 · 触发器 Monitor 监控 在线用户 · 缓存监控 · 资源管理 · 服务器监控 基础设施层 Infrastructure MySQL / PostgreSQL 主库 + 只读副本 + Alembic 迁移 Redis Session · 缓存 · 限流 文件存储 本地存储 / S3 / OSS 外部服务网关 支付宝 · 微信支付 · SMTP · 百望云 可观测性 Prometheus · Grafana 插件扩展层 Plugins (可选启用) AI Chat AI 对话 CodeGen 代码生成器 Demo 示例模块 Common 文件/健康/指标 更多 可扩展
对外接口层
平台管理层 (8 模块)
租户管理层 (11 模块)
自动化运维层 (3 模块)
基础设施层
插件扩展层 (7 模块)

40 模块归属清单

按 Part 分组,标注数据隔离策略(✅ TenantMixin = 租户隔离,无标记 = 平台级)

Part 章节 模块 租户隔离 表数
Part 1
平台管理
§3系统管理(认证/用户)3
§5Menu 菜单管理1
§6Role 角色管理3
§7Dept 部门岗位1
§8Dict 数据字典2
§11Notice 通知公告1
§12Param 系统参数1
§14OpLog 操作日志1
§15Tenant 租户管理1
§16Package 套餐管理1
§17Ticket 工单管理1
§23Email 邮件服务3
§39AuditLog 审计日志1
§40Dashboard 运营大盘
Part 2
商业运营
§24Order 订单支付2+1
§25TenantSelfService 自助服务
§26APIUsage 用量统计1
§27UserInvite 用户邀请1
§38Invoice 发票管理1
Part 3
自动化
§18LoginLog 登录日志1
§19到期处理机制
§32Cronjob 定时任务1
§33Workflow 工作流1
§36Monitor 监控
Part 4
插件
§31AI Chat 聊天1
§34CodeGen 代码生成1
§35Demo 示例1
§37Common 公共1
可扩展更多插件

核心业务逻辑流转:租户生命周期、RBAC 鉴权链路、订单支付闭环、发票开票流程、API 用量追踪

业务流 1:租户全生命周期

从自助注册/超管创建 → 试用 → 支付激活 → 到期宽限 → 续费/降级 → 销户的全生命周期状态机

0=active 正常使用 1=grace 宽限期 (7天) 2=suspended 暂停使用 3=frozen 冻结(超管) 4=expired 已到期 5=archived 已归档 续费恢复 → active(0) 宽限期超时未续费 超管操作 到期后 30 天自动 触发逻辑 支付成功 → 0(active) 首次购买/续费/升级 end_time 到期 → 1(grace) 定时任务每日扫描 宽限期超时 → 2(suspended) 7天后自动暂停 暂停 30 天 → 4(expired) 到期不可逆 关键操作 创建租户 → 自动建 owner 角色 + 分配全量菜单 套餐变更 → 预览影响(菜单+配额) → 同步更新限制 删除租户 → 仅 status=5(archived) 可删 → 软删除 冻结/解冻 → 超管手动操作,status 3↔0

业务流 2:用户认证与 RBAC 鉴权链路

从登录到菜单渲染的完整鉴权流程:JWT 解析 → 租户上下文注入 → 角色菜单查询 → 按钮权限判断

1. 用户登录 POST /auth/login username + password 2. Bcrypt 验证 密码哈希比对 登录限流(Redis) 3. 签发 JWT sub=user_id tenant_id + roles 4. 请求到达 API Authorization Header Bearer {token} 5. JWT 中间件验证 解密 → 校验过期 注入 request.state 6. 租户隔离中间件 (TenantMiddleware) ORM 事件层:自动注入 tenant_id before_insert / before_update CRUD 业务层:查询自动过滤 tenant_id Model.query.filter_by(tenant_id=...) 权限策略层:RABC 角色菜单权限检查 @require_permission("user:create") 7. RBAC 鉴权详细流程 从 JWT 获取 user_id + tenant_id 查询用户角色列表 sys_user_roles JOIN sys_role 查询角色菜单权限 sys_role_menus JOIN sys_menu 匹配接口所需权限 @require_permission 装饰器 通过/拒绝 前端:登录后请求 /auth/menus → 返回该用户角色下的菜单树 → Vue Router 动态注册 → 菜单渲染

业务流 3:订单支付闭环

从选择套餐到支付回调激活的完整闭环:创建订单 → 第三方支付 → 异步回调 → 激活套餐 → 可退款

选择套餐 GET /tenant/package/available 含价格/配额/菜单对比 创建订单 POST /tenant/order/create 生成订单号 + 签名 跳转第三方支付 支付宝 / 微信支付收银台 扫码/网页支付 用户完成支付 支付宝/微信APP内付款 返回支付结果页 异步回调激活 POST /payment/callback/ 签名验证 → 激活套餐 支付回调详细处理流程 IP 白名单校验 Nginx 层过滤 验证签名 RSA/AES 验签 分布式锁 Redis SETNX 30s 金额一致性校验 回调金额 == 订单金额 状态校验 仅 status=0 可处理 激活套餐 更新 tenant 根据 order_type 执行激活: new(新购)→设置套餐+到期时间 激活为正常使用状态 renew(续费)→延长到期时间 end_time += period upgrade(升级)→变套餐+配配额 只增不减:max_users/roles/depts downgrade(降级)→缩菜单+配额 清理超出菜单但不删已有数据 退款流程 租户申请 → 7天内可退 超管审核 → 批准/驳回 批准 → 原路退回(支付宝/微信API) 套餐回退 → 恢复购买前套餐+到期时间 退款约束:支付后7天内 · 全额退款 · 原路退回 · 免费套餐不支持退款 · 降级订单退款后套餐回升

业务流 4:发票开票与 API 用量追踪

左边:支付完成后开具发票的完整流程;右边:API 用量实时计数 → 持久化 → 异常检测

发票开票流程 订单支付完成 status=1(已支付) 租户申请开票 POST /tenant/invoice/apply 超管审核 校验专票信息完整性 调用第三方开票API 百望云/票通 · 重试3次 生成电子发票 PDF 下载 + 通知 开票规则: 一单一票(order_id UNIQUE) · 支付后30天内可申请 · 专票必填税号+开户行+地址 · PDF存储路径 invoice/{tenant_id}/{invoice_no}.pdf · 当月可作废 API 用量追踪 API 请求到达 携带 tenant_id Redis 中间件计数 INCR api_usage:{id}:{date}:{path} 定时持久化 每5分钟写入DB 异常检测 + 限流 5倍基线→告警 · 10倍→429 运营大盘展示 Dashboard 图表

从前端到后端的完整技术栈:Vue 3 + FastAPI 分层架构 + MySQL/Redis + Docker 部署拓扑

技术架构全景图

六层技术架构:接入层 → 前端层 → 后端API层 → 业务中间件层 → 数据层 → 外部服务层

接入层 Nginx 反向代理 + HTTPS SSL 终结 · 静态资源 · Gzip IP 白名单 / 限流 / WAF 支付回调IP过滤 · DDoS防护 CDN 加速 Vue SPA 静态资源分发 TLS 1.3 加密传输 前端层 (SPA) Vue 3.4 + Composition API Vite 5 构建工具 Element Plus 组件库 Pinia 状态管理 Vue Router 4 Axios TypeScript · ECharts 可视化 · vue-i18n 国际化 · ESLint + Prettier 路由守卫(动态注册菜单) · Token 自动刷新 · 请求/响应拦截器 页面组成:登录/注册 · 超管仪表盘 · 租户管理 · 套餐配置 · 订单管理 · 发票 · 审计日志 · 运营大盘 租户端:用户管理 · 角色权限 · 菜单 · 部门 · 自助服务 · 邀请 · 工单 · 个人中心 后端层 (FastAPI + Python 3.13) Uvicorn/Gunicorn ASGI 服务器 · 多worker 热重载(dev) · 优雅关闭 FastAPI 应用核心 路由注册 · 依赖注入 · 全局异常处理 Swagger / Redoc 自动文档 中间件链 (Middleware) CORS → JWT Auth → Tenant Isolation → OpLog → API Rate Limit 后台任务引擎 APScheduler · BackgroundTasks Cronjob 定时执行 业务模块组织: module_system (14) module_platform (8) module_task (2) module_generator (1) module_example (1) module_ai (1) module_common (1) SQLAlchemy 2.0 ORM + AsyncSession Alembic 数据库迁移管理 Pydantic v2 数据验证+序列化 aioredis 异步 Redis 客户端 数据层 MySQL 8.0+ 主库 InnoDB · 37张业务表 读写分离(主写从读) 定时备份(全量+增量) 支持 PostgreSQL 14+ / SQLite(dev) Redis 7.x Session 存储 (JWT黑名单) 验证码 · 登录限流计数器 API 用量实时计数 租户配置缓存 · 字典缓存 文件存储 本地存储 / S3 / OSS 用户头像 · 发票PDF 文件管理 CRUD 审计日志归档(冷存储) 可观测性 Prometheus Metrics Grafana 仪表盘 日志采集 (ELK/Loki) 健康检查端点 /health 外部服务集成 支付宝支付 当面付/网页支付 · RSA签名 异步回调通知 微信支付 JSAPI/Native · APIv3签名 支付结果通知 SMTP 邮件服务 密码重置 · 到期提醒 邀请·支付通知·开票通知 百望云/票通 电子发票 API 自动重试 3 次 扩展预留 短信 · SSO Webhook 部署与运维 Docker 容器化 Dockerfile + docker-compose 前端/后端/MySQL/Redis 编排 CI/CD 流水线 GitHub Actions / GitLab CI lint → test → build → deploy Alembic 数据库迁移 版本化 migration 脚本 升级前自动备份 · 失败可回滚 CloudStudio 沙箱部署 快速预览 · 静态站点托管 即时分享 demo 链接

技术栈清单

前端 (SPA)
Vue 3.4
TypeScript
Vite 5
Element Plus
Pinia
Vue Router 4
Axios
ECharts
vue-i18n
后端 (API)
Python 3.13
FastAPI
Uvicorn / Gunicorn
SQLAlchemy 2.0
Pydantic v2
APScheduler
aioredis
Alembic
数据存储
MySQL 8.0+
PostgreSQL 14+
SQLite (dev)
Redis 7.x
S3 / OSS
Prometheus
外部集成
支付宝 OpenAPI
微信支付 APIv3
SMTP (任意服务商)
百望云/票通
Prometheus Pushgateway

非功能性需求 (NFR) 指标

指标 要求
API 响应时间P95 ≤ 500ms(查询),P95 ≤ 2s(写入/批操作)
并发用户单实例支持 500+ 并发租户用户(需压测验证)
可用性99.5%(不包含计划运维窗口)
数据安全TLS 1.3 + Bcrypt + AES-256 + 日志脱敏
数据库备份每日全量(保留30天) + 每小时增量(保留7天) + 异地存储 + 季度恢复演练
容灾恢复RTO ≤ 4小时,RPO ≤ 1小时,主从自动切换
版本升级Alembic migration + 升级前自动备份 + 失败回滚 + 主版本7天通知
兼容性MySQL 8.0+ / PostgreSQL 14+ / SQLite(dev) · Python ≥ 3.10 · Node.js ≥ 20