简介

Platform Admin Prototype 是一个基于现代 Web 技术栈构建的后台管理系统原型。它提供了企业级应用所需的核心基础设施，包括用户认证、权限管理、数据展示、表单处理等通用功能，帮助开发团队在几天而非几周内搭建起生产可用的管理后台。

设计理念

  • 约定优于配置 - 开箱即用的最佳实践，减少决策疲劳

  • 渐进式增强 - 核心功能稳定，扩展功能按需引入

  • 类型安全优先 - 全栈 TypeScript，编译期捕获错误

  • 开发体验至上 - 热重载、自动生成、一键部署

适用场景

场景推荐度说明
内部管理后台 (CMS, ERP, CRM)⭐⭐⭐⭐⭐标准 CRUD + 权限控制
SaaS 多租户管理平台⭐⭐⭐⭐内置租户隔离架构
数据大屏/可视化看板⭐⭐⭐需配合图表库扩展
高并发实时系统⭐⭐建议引入 WebSocket/微服务

核心功能

1. 用户认证与授权

1
2
3
4
5
6
7
8
9
10
┌─────────────────────────────────────────────────┐
│  认证体系                                        │
├─────────────────────────────────────────────────┤
│  ✅ JWT Access/Refresh Token 双令牌机制          │
│  ✅ 基于 RBAC 的角色权限控制 (Role-Based)        │
│  ✅ 基于 ABAC 的属性权限控制 (Attribute-Based)   │
│  ✅ 多因子认证 (MFA) - TOTP / 短信 / 邮箱        │
│  ✅ 单点登录 (SSO) - OAuth2/OIDC / SAML          │
│  ✅ 会话管理 - 强制下线、设备管理、登录日志       │
└─────────────────────────────────────────────────┘

2. 权限管理系统

  • 资源级权限 - 页面、按钮、API 接口粒度控制

  • 数据权限 - 部门、岗位、自定义维度的数据范围隔离

  • 权限继承 - 角色继承、临时授权、权限回收审批流

  • 动态菜单 - 基于权限自动渲染侧边栏/顶部导航

3. 通用业务组件库

组件类别包含组件状态
数据展示Table, Card, List, Timeline, Tree, Chart✅ 完成
表单输入Form, Select, DatePicker, Upload, Editor, Cascader✅ 完成
反馈组件Modal, Drawer, Message, Notification, Progress✅ 完成
导航组件Menu, Breadcrumb, Tabs, Steps, Pagination✅ 完成
高级组件Schema Form, Json Editor, Flow Designer, Code Editor🚧 开发中

4. 代码生成与低代码能力

1
2
3
4
# 一键生成完整 CRUD 模块
npm run gen:crud -- --name=User --fields="name:string,email:string,role:select"

# 生成包含：实体、DTO、Service、Controller、Vue/React 页面、路由、菜单、权限

5. 系统内置模块

  • 用户管理 - 创建/编辑/禁用/重置密码/导入导出

  • 角色管理 - 角色 CRUD、权限分配、成员维护

  • 菜单管理 - 多级菜单、路由映射、图标选择、显隐控制

  • 部门管理 - 树形结构、负责人、排序、数据权限范围

  • 字典管理 - 系统字典、业务字典、标签色彩、缓存刷新

  • 参数配置 - 系统参数、分组管理、动态刷新无需重启

  • 操作日志 - 登录日志、操作审计、异常追踪、导出分析

  • 定时任务 - Cron 表达式、任务分组、执行日志、手动触发

技术栈

后端 (推荐)

层级技术选型版本备选方案
框架NestJS / Spring Boot / Go-ZeroLatestExpress, Fastify, Gin
ORMTypeORM / Prisma / GORMLatestSequelize, Drizzle
数据库PostgreSQL / MySQL15+ / 8.0+SQLite (dev), TiDB
缓存Redis (Cluster)7+KeyDB, Dragonfly
消息队列RabbitMQ / Kafka / Redis Stream-NATS, Pulsar
认证Passport.js / Spring Security / Casbin-Keycloak, Auth0

前端 (推荐)

层级技术选型版本备选方案
框架Vue 3 / React 18LatestSvelte, Solid
构建工具Vite / RsbuildLatestWebpack, Turbopack
UI 库Element Plus / Ant Design / Arco DesignLatestNaive UI, Shadcn
状态管理Pinia / Zustand / Redux ToolkitLatestJotai, Valtio
请求库Axios / Ky / TanStack QueryLatestSWR, RTK Query
类型安全TypeScript + Orval / tRPCLatestGraphQL Codegen

DevOps & 基建

1
2
3
4
5
6
7
8
9
10
11
12
# docker-compose.yml 片段
services:
  app:
    build: .
    ports: ["3000:3000"]
    depends_on: [postgres, redis]
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: admin_proto
  redis:
    image: redis:7-alpine

快速开始

环境要求

  • Node.js >= 18.17 / Java >= 17 / Go >= 1.21

  • PostgreSQL >= 15 / MySQL >= 8.0

  • Redis >= 7

  • pnpm >= 8 / npm >= 9 / yarn >= 4

1. 克隆与安装

1
2
3
4
5
6
7
8
9
# 克隆仓库
git clone https://github.com/your-org/platform-admin-prototype.git
cd platform-admin-prototype

# 安装依赖 (推荐 pnpm)
pnpm install

# 复制环境变量模板
cp .env.example .env.local

2. 配置环境变量

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# .env.local
# 数据库
DATABASE_URL="postgresql://user:pass@localhost:5432/admin_proto?schema=public"

# Redis
REDIS_URL="redis://localhost:6379"

# JWT
JWT_SECRET="your-super-secret-key-min-32-chars"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"

# 前端
VITE_API_BASE_URL="/api"
VITE_APP_TITLE="Platform Admin"

3. 数据库初始化

1
2
3
4
5
6
7
8
# 运行迁移
pnpm db:migrate

# 填充种子数据 (管理员账号: admin / Admin@123)
pnpm db:seed

# 或使用 Prisma Studio 可视化管理
pnpm db:studio

4. 启动开发环境

1
2
3
4
5
6
# 同时启动前后端 (推荐)
pnpm dev

# 或分别启动
pnpm dev:backend  # 后端 http://localhost:3000
pnpm dev:frontend # 前端 http://localhost:5173

5. 访问系统

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
platform-admin-prototype/
├── .github/                 # CI/CD 工作流
├── .husky/                  # Git Hooks
├── docs/                    # 文档站点 (VitePress)
├── packages/                # Monorepo 包 (可选)
│   ├── shared/              # 共享类型、工具函数
│   ├── ui/                  # 通用 UI 组件库
│   └── config/              # 共享配置 (ESLint, TSConfig)
├── apps/
│   ├── backend/             # 后端应用
│   │   ├── src/
│   │   │   ├── modules/     # 业务模块 (按领域划分)
│   │   │   │   ├── auth/    # 认证授权│   │   │   │   ├── users/   # 用户管理
│   │   │   │   ├── roles/   # 角色权限
│   │   │   │   ├── menu/    # 菜单路由
│   │   │   │   └── system/  # 系统配置
│   │   │   ├── common/      # 公共模块 (拦截器/守卫/管道)
│   │   │   └── database/    # 数据库连接与迁移
│   │   └── test/            # 单元/集成测试
│   └── frontend/            # 前端应用
│       ├── src/
│       │   ├── api/         # API 请求封装
│       │   ├── components/  # 业务组件
│       │   ├── layouts/     # 布局 (侧边栏/顶栏/标签页)
│       │   ├── router/      # 路由与权限守卫
│       │   ├── store/       # 状态管理
│       │   ├── views/       # 页面 (按模块组织)
│       │   └── utils/       # 工具函数
│       └── public/          # 静态资源
├── docker/                  # Docker/Compose 配置
├── scripts/                 # 自动化脚本
├── .env.example             # 环境变量模板
└── README.md                # 项目文档

进阶使用指南

API 调用示例

登录获取 Token

1
2
3
4
5
6
7
8
9
10
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@123"}'

# 响应
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 900
}

携带 Token 访问受保护接口

1
2
curl http://localhost:3000/api/users?page=1&pageSize=10 \
  -H "Authorization: Bearer <accessToken>"

刷新 Token

1
2
3
curl -X POST http://localhost:3000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"eyJhbGciOiJIUzI1NiIs..."}'

权限配置示例 (Casbin 模型)

1
2
3
4
5
6
7
8
9
10
11
12
# 模型定义
[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = r.sub == p.sub && keyMatch(r.obj, p.obj) && regexMatch(r.act, p.act)
1
2
3
4
5
6
# 策略示例
p, admin, /api/users*, GET
p, admin, /api/users*, POST
p, admin, /api/users*, PUT
p, admin, /api/users*, DELETE
p, operator, /api/users, GET

自定义业务模块 (三步走)

1
2
3
4
5
6
7
8
# 第一步：生成模块骨架
npm run gen:module -- --name=Order

# 第二步：定义实体
npm run gen:entity -- --name=Order --fields="orderNo:string,amount:number,status:enum"

# 第三步：生成 CRUD
npm run gen:crud -- --name=Order

最佳实践

性能优化

  • 数据库 - 索引优化、分页查询、慢查询日志、读写分离

  • 缓存策略 - Redis 缓存热点数据、缓存穿透/击穿/雪崩防护

  • 前端优化 - 路由懒加载、组件按需加载、虚拟列表、图片懒加载

  • CDN 加速 - 静态资源托管、Gzip/Brotli 压缩

安全加固

  • 密码使用 bcrypt/argon2 加盐哈希存储

  • 接口全链路 HTTPS + 速率限制 (Rate Limit)

  • 防 SQL 注入 (ORM 参数化)、防 XSS (输出转义)、防 CSRF (Token 校验)

  • 敏感字段 (手机号/邮箱) 脱敏展示、日志不落盘明文

  • 定期安全扫描: npm audit, SonarQube, 依赖漏洞检测

测试策略

1
2
3
4
5
6
7
8
9
10
11
# 单元测试
pnpm test:unit

# 集成测试
pnpm test:integration

# E2E 测试 (Playwright)
pnpm test:e2e

# 覆盖率报告
pnpm test:coverage

部署方案

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Docker 一键部署
docker-compose up -d --build

# K8s 部署 (Helm)
helm upgrade --install admin ./charts/admin

# CI/CD 流水线 (GitHub Actions 片段)
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install && pnpm build
      - run: docker build -t admin:${{ github.sha }} .
      - run: docker push registry.example.com/admin:${{ github.sha }}

常见问题 (FAQ)

Q: 支持多租户吗？
A: 支持。内置租户隔离机制（Schema 级 / 行级），提供租户切换、独立数据域与配额管理，可参考 docs/multi-tenant.md。

Q: 能否接入现有系统？
A: 可以。提供标准 RESTful API 与 OpenAPI 文档，支持 OAuth2/OIDC 对接企业统一认证，也支持作为子模块嵌入已有项目。

Q: 移动端适配如何？
A: 前端采用响应式布局，桌面端完整功能，移动端提供基础管理能力；如需独立移动端可复用同一套 API。

Q: 数据迁移与备份？
A: 提供版本化数据库迁移工具（up/down 可回滚），支持定时自动备份到对象存储，生产环境建议开启 WAL 归档。

Q: 是否有中文文档？
A: 有。文档站点支持中英文切换，包含快速上手、架构说明、API 参考与部署指南。

版本与路线图

版本状态亮点
v1.0✅ 已发布核心认证、RBAC、基础 CRUD
v1.1✅ 已发布操作日志、定时任务、数据字典
v1.2🚧 开发中低代码表单、可视化流程设计器
v2.0📋 规划中微前端、多租户增强、国际化

总结

Platform Admin Prototype 不是又一个「脚手架」，而是一套经过生产验证的后台开发方法论：

  • 对个人开发者 - 省去重复造轮子，专注业务本身

  • 对创业团队 - 快速验证产品，MVP 到生产只需一条命令

  • 对企业 - 统一技术规范，降低维护成本与人员流动风险

它把「认证、权限、日志、部署」这些繁琐但必要的部分提前做好，让你把时间花在真正有价值的事情上。

立即开始：克隆仓库 → pnpm install → pnpm dev → 三分钟内拥有一个生产级管理后台！

相关链接

本文由 Platform Admin Prototype 团队整理，持续更新中。