architecture.md 15 KB
shadcn管理后台前后端全栈启动模板 - 架构设计文档
项目概述
基于PRD需求，本架构设计提供一个完整的shadcn管理后台全栈启动模板，专注于用户管理功能，采用现代化的技术栈和最佳实践。
系统架构总览
graph TB
subgraph "前端应用层"
A[Admin管理后台 - React 19]
B[Web端 - React 19]
C[小程序 - Taro 4]
end
subgraph "后端服务层"
D[Hono API服务器]
E[认证服务]
F[用户管理服务]
end
subgraph "数据存储层"
G[MySQL数据库]
H[Redis缓存]
I[MinIO文件存储]
end
subgraph "基础设施层"
J[Docker容器]
K[CI/CD流水线]
L[监控日志]
end
A --> D
B --> D
C --> D
D --> E
D --> F
E --> G
F --> G
D --> H
D --> I
J --> A&B&C&D
一、项目结构
1.1 主项目结构（Monorepo）
shadcn-admin-template/
├── packages/
│ ├── client/ # 前端管理后台
│ │ ├── src/
│ │ │ ├── components/ # 通用组件
│ │ │ ├── pages/ # 页面组件
│ │ │ │ ├── auth/ # 认证相关页面
│ │ │ │ ├── users/ # 用户管理页面
│ │ │ │ └── dashboard/ # 仪表板页面
│ │ │ ├── hooks/ # 自定义Hooks
│ │ │ ├── lib/ # 工具库
│ │ │ ├── types/ # TypeScript类型定义
│ │ │ └── styles/ # 样式文件
│ │ ├── public/ # 静态资源
│ │ └── vite.config.ts # Vite配置
│ ├── server/ # 后端API服务
│ │ ├── src/
│ │ │ ├── api/ # API路由
│ │ │ │ ├── auth/ # 认证路由
│ │ │ │ ├── users/ # 用户路由
│ │ │ │ └── health/ # 健康检查
│ │ │ ├── modules/ # 业务模块
│ │ │ │ ├── auth/ # 认证模块
│ │ │ │ ├── users/ # 用户模块
│ │ │ │ └── database/ # 数据库模块
│ │ │ ├── middleware/ # 中间件
│ │ │ │ ├── auth.ts # 认证中间件
│ │ │ │ ├── cors.ts # CORS中间件
│ │ │ │ └── error.ts # 错误处理
│ │ │ ├── migrations/ # 数据库迁移脚本
│ │ │ ├── types/ # 类型定义
│ │ │ └── utils/ # 工具函数
│ │ └── package.json
│ └── shared/ # 共享代码
│ └── types/ # 共享类型定义
├── docker/ # Docker配置
├── docs/ # 文档
├── scripts/ # 部署脚本
└── package.json # 根package.json
1.2 小程序项目结构
mini/
├── config/ # 配置文件
│ ├── dev.js # 开发环境配置
│ ├── prod.js # 生产环境配置
│ └── index.js # 主配置
├── src/
│ ├── pages/ # 页面组件
│ │ ├── index/ # 首页
│ │ ├── auth/ # 认证页面
│ │ └── profile/ # 个人资料
│ ├── components/ # 通用组件
│ ├── utils/ # 工具函数
│ │ ├── api.ts # API调用
│ │ ├── auth.ts # 认证工具
│ │ └── request.ts # 请求封装
│ ├── services/ # 服务层
│ ├── stores/ # 状态管理
│ └── assets/ # 静态资源
├── types/ # 类型定义
├── app.config.ts # 应用配置
└── package.json
二、技术栈详细配置
2.1 前端技术栈
2.1.1 管理后台 (Admin) - shadcn/ui
{
"dependencies": {
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-router-dom": "^7.0.0",
"@tanstack/react-query": "^5.0.0",
"react-hook-form": "^7.0.0",
"@hookform/resolvers": "^5.2.1",
"zod": "^4.0.14",
"lucide-react": "^0.300.0",
"@heroicons/react": "^2.0.0",
"clsx": "^2.0.0",
"tailwind-merge": "^2.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
"vite": "^7.0.0",
"@vitejs/plugin-react": "^5.0.0",
"tailwindcss": "^4.0.0",
"autoprefixer": "^10.0.0",
"postcss": "^8.0.0",
"eslint": "^9.0.0",
"prettier": "^3.0.0",
"vitest": "^3.0.0",
"@testing-library/react": "^16.0.0",
"cross-env": "^7.0.0"
}
}
2.1.2 Web端 (Home) - shadcn/ui
与技术栈2.1.1相同，可根据业务需求调整组件库。
2.1.3 小程序 (Mini)
{
"dependencies": {
"@tarojs/taro": "^4.0.0",
"@tarojs/react": "^4.0.0",
"react": "^18.0.0",
"react-dom": "^18.0.0",
"@tanstack/react-query": "^5.0.0",
"react-hook-form": "^7.0.0",
"@hookform/resolvers": "^5.2.1",
"zod": "^4.0.14",
"@egoist/tailwindcss-icons": "^0.6.0",
"clsx": "^2.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
"@tarojs/plugin-framework-react": "^4.0.0",
"tailwindcss": "^4.0.0",
"vitest": "^3.0.0"
}
}
2.2 后端技术栈
框架选型说明: 选用Hono框架而非Express，主要基于以下考虑：
- RPC类型安全: Hono Client提供端到端类型安全的RPC调用，确保前后端API契约一致性
- 生态集成: @hono/swagger-ui提供开箱即用的API文档生成和测试界面
- 性能优势: Hono专为Edge环境优化，提供更快的启动时间和更低的内存占用
- TypeScript支持: 原生TypeScript支持，提供更好的类型安全性和开发体验
- 现代API设计: 支持最新的Web标准，包括WebSocket、Server-Sent Events等
- 中间件兼容: 兼容Express中间件生态，便于迁移和扩展
部署灵活性: 支持多种运行时环境(Node.js, Deno, Bun, Cloudflare Workers等)
{ "dependencies": { "hono": "^4.0.0", "typeorm": "^0.3.0", "mysql2": "^3.0.0", "ioredis": "^5.0.0", "bcrypt": "^5.0.0", "jsonwebtoken": "^9.0.0", "openai": "^4.0.0", "minio": "^7.0.0", "compression": "^1.7.0", "dotenv": "^16.0.0", "debug": "^4.3.0", "uuid": "^9.0.0", "dayjs": "^1.11.0", "axios": "^1.0.0", "zod": "^4.0.14" }, "devDependencies": { "typescript": "^5.0.0", "@types/node": "^20.0.0", "vitest": "^3.0.0", "@types/bcrypt": "^5.0.0", "@types/jsonwebtoken": "^9.0.0", "@types/compression": "^1.7.0", "@types/debug": "^4.1.0", "@types/uuid": "^9.0.0", "cross-env": "^7.0.0" } }
2.3 数据库设计
User表结构
CREATE TABLE users (
id VARCHAR(36) PRIMARY KEY DEFAULT UUID(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
name VARCHAR(100) NOT NULL,
role ENUM('admin', 'user', 'moderator') DEFAULT 'user',
status ENUM('active', 'inactive', 'suspended') DEFAULT 'active',
avatar_url VARCHAR(500),
last_login_at TIMESTAMP NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_email (email),
INDEX idx_status (status),
INDEX idx_created_at (created_at)
);
Session存储方案（使用Redis）
由于我们使用了Redis，Session信息可以完全存储在Redis中，无需在数据库中创建Session表。Redis提供了更好的性能和自动过期功能。
Redis Session数据结构:
// Session数据格式
interface SessionData {
userId: string;
email: string;
name: string;
role: UserRole;
issuedAt: number; // 时间戳
expiresAt: number; // 时间戳
}
// Redis键格式: session:{token}
// 设置过期时间与JWT token过期时间一致
优势:
- ⚡ 性能更好 - 内存访问 vs 磁盘I/O
- ⏰ 自动过期 - Redis支持TTL自动清理
- 🔍 查询效率 - 基于token直接查找
- 🧹 维护简单 - 无需手动清理过期session
- 📈 扩展性 - Redis集群支持分布式session
Redis配置示例:
// session服务示例
const sessionService = {
async createSession(token: string, user: User, expiresIn: number) {
const sessionData = {
userId: user.id,
email: user.email,
name: user.name,
role: user.role,
issuedAt: Date.now(),
expiresAt: Date.now() + expiresIn * 1000
};
await redis.setex(`session:${token}`, expiresIn, JSON.stringify(sessionData));
},
async getSession(token: string) {
const data = await redis.get(`session:${token}`);
return data ? JSON.parse(data) : null;
},
async deleteSession(token: string) {
await redis.del(`session:${token}`);
},
async deleteUserSessions(userId: string) {
// 可以使用Redis SCAN命令查找并删除用户的所有session
const keys = await redis.keys(`session:*`);
for (const key of keys) {
const session = await redis.get(key);
if (session && JSON.parse(session).userId === userId) {
await redis.del(key);
}
}
}
};
三、模块设计与交互
3.1 认证模块
sequenceDiagram
participant Client as 前端应用
participant AuthAPI as 认证API
participant DB as 数据库
participant Redis as Redis缓存
Client->>AuthAPI: POST /auth/login
AuthAPI->>DB: 验证用户凭据
DB-->>AuthAPI: 用户数据
AuthAPI->>AuthAPI: 生成JWT Token
AuthAPI->>Redis: 存储Session
AuthAPI-->>Client: 返回Token
Client->>AuthAPI: 携带Token请求
AuthAPI->>Redis: 验证Token有效性
Redis-->>AuthAPI: Session信息
AuthAPI-->>Client: 授权数据
3.2 用户管理模块
flowchart TD
A[用户列表请求] --> B[认证中间件]
B --> C{Token有效?}
C -->|是| D[查询用户数据]
C -->|否| E[返回401错误]
D --> F[数据库查询]
F --> G[数据格式化]
G --> H[返回分页结果]
I[创建用户请求] --> J[数据验证]
J --> K{验证通过?}
K -->|是| L[密码加密]
K -->|否| M[返回验证错误]
L --> N[保存用户数据]
N --> O[返回创建结果]
3.3 API接口设计
认证接口
// POST /auth/login
interface LoginRequest {
email: string;
password: string;
}
interface LoginResponse {
token: string;
user: User;
expiresIn: number;
}
// POST /auth/register
interface RegisterRequest {
email: string;
password: string;
name: string;
}
// POST /auth/refresh
interface RefreshResponse {
token: string;
expiresIn: number;
}
用户管理接口
// GET /users
interface GetUsersRequest {
page?: number;
limit?: number;
search?: string;
status?: UserStatus;
}
interface GetUsersResponse {
users: User[];
total: number;
page: number;
limit: number;
}
// POST /users
interface CreateUserRequest {
email: string;
password: string;
name: string;
role?: UserRole;
}
// PUT /users/:id
interface UpdateUserRequest {
name?: string;
role?: UserRole;
status?: UserStatus;
}
// DELETE /users/:id
interface DeleteUserResponse {
success: boolean;
message: string;
}
四、开发环境配置
4.1 Docker开发环境
# docker-compose.dev.yml
version: '3.8'
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: shadcn_admin
MYSQL_USER: admin
MYSQL_PASSWORD: admin123
ports:
- "3306:3306"
volumes:
- mysql_data:/var/lib/mysql
- ./init.sql:/docker-entrypoint-initdb.d/init.sql
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redis_data:/data
minio:
image: minio/minio
ports:
- "9000:9000"
- "9001:9001"
environment:
MINIO_ROOT_USER: minioadmin
MINIO_ROOT_PASSWORD: minioadmin
command: server /data --console-address ":9001"
volumes:
- minio_data:/data
api:
build:
context: .
dockerfile: Dockerfile.api
ports:
- "3001:3001"
environment:
- NODE_ENV=development
- DATABASE_URL=mysql://admin:admin123@db:3306/shadcn_admin
- REDIS_URL=redis://redis:6379
- JWT_SECRET=your-jwt-secret
depends_on:
- db
- redis
volumes:
- ./packages/server:/app
- /app/node_modules
client:
build:
context: .
dockerfile: Dockerfile.client
ports:
- "3000:3000"
environment:
- VITE_API_URL=http://localhost:3001
depends_on:
- api
volumes:
- ./packages/client:/app
- /app/node_modules
volumes:
mysql_data:
redis_data:
minio_data:
4.2 环境变量配置
# .env.example
# 数据库配置
DATABASE_URL=mysql://user:password@localhost:3306/shadcn_admin
# Redis配置
REDIS_URL=redis://localhost:6379
# JWT配置
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=7d
# 文件存储
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=shadcn-admin
# 应用配置
NODE_ENV=development
PORT=3001
CORS_ORIGIN=http://localhost:3000
# 前端配置
VITE_API_URL=http://localhost:3001
VITE_APP_NAME=Shadcn Admin
五、测试策略
5.1 测试金字塔
pie title 测试策略分布
"单元测试" : 70
"集成测试" : 20
"端到端测试" : 10
5.2 测试覆盖范围
- 单元测试: 工具函数、工具类、纯函数
- 集成测试: API端点、数据库操作、服务集成
- 端到端测试: 用户流程、关键业务路径
六、部署架构
6.1 生产环境部署
graph LR
A[用户请求] --> B[CDN]
B --> C[负载均衡器]
C --> D[前端容器]
D --> E[API网关]
E --> F[API容器集群]
F --> G[MySQL主从]
F --> H[Redis集群]
F --> I[MinIO集群]
subgraph "监控系统"
J[Prometheus]
K[Grafana]
L[ELK日志]
end
F --> J
F --> L
6.2 CI/CD流水线
flowchart LR
A[代码提交] --> B[代码扫描]
B --> C[单元测试]
C --> D[构建镜像]
D --> E[集成测试]
E --> F[安全扫描]
F --> G[部署预发布]
G --> H[端到端测试]
H --> I[生产部署]
I --> J[健康检查]
七、安全考虑
- 认证安全: JWT Token + Refresh Token机制
- 密码安全: bcrypt加密 + 密码策略
- API安全: CORS配置 + 速率限制
- 数据库安全: 参数化查询 + 连接池
- 文件安全: 文件类型验证 + 病毒扫描
- 监控安全: 日志审计 + 异常检测
八、性能优化
- 数据库优化: 索引优化 + 查询缓存
- API优化: 响应压缩 + 数据分页
- 前端优化: 代码分割 + 图片懒加载
- 缓存策略: Redis缓存 + CDN加速
- 并发处理: 连接池 + 异步处理
本文档根据PRD需求和技术规范创建，提供了完整的架构设计方案，可作为开发实施的蓝图。