# rbac-user-front

**Repository Path**: grow-project/rbac-user-front

## Basic Information

- **Project Name**: rbac-user-front
- **Description**: 前端react的管理后台权限管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RBAC 后台权限管理系统 - 前端

基于 RBAC（基于角色的访问控制）模型的用户中心与权限管理平台前端，支持细粒度的权限控制与审计日志。

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 前端框架 | React | 19 |
| UI 组件库 | Ant Design | 6 |
| 路由 | react-router-dom | 7 |
| HTTP 客户端 | axios | 1 |
| 日期处理 | dayjs | 1 |
| 构建工具 | Vite | 8 |
| 语言 | TypeScript | 6 |
| 代码检查 | oxlint | 1 |
| 包管理 | pnpm | 10 |

## 项目结构

```
src/
├── api/                # API 请求封装
│   ├── request.ts      # Axios 实例 + 拦截器（JWT 注入、Token 刷新）
│   ├── auth.ts         # 认证相关接口
│   ├── user.ts         # 用户管理接口
│   ├── role.ts         # 角色管理接口
│   └── permission.ts   # 权限接口
├── contexts/
│   └── AuthContext.tsx  # 认证上下文（用户状态、权限、登录/登出）
├── layouts/
│   └── AdminLayout.tsx  # 管理后台布局（侧边栏 + 顶栏 + 内容区）
├── pages/
│   ├── Login.tsx        # 登录页
│   ├── Dashboard.tsx    # 控制台首页
│   ├── UserManagement.tsx    # 用户管理
│   ├── RoleManagement.tsx    # 角色管理
│   ├── PermissionConfig.tsx  # 权限配置
│   └── OperationLog.tsx      # 操作日志
├── types/
│   └── index.ts         # 全局 TypeScript 类型定义
├── App.tsx              # 根组件（路由 + 主题 + 路由守卫）
├── main.tsx             # 应用入口
└── index.css            # 全局样式
```

## 快速开始

### 环境要求

- Node.js >= 18
- pnpm >= 8

### 安装依赖

```bash
pnpm install
```

### 开发

```bash
pnpm dev
# 或
make dev
```

### 构建

```bash
pnpm build
# 或
make build
```

### 代码检查

```bash
pnpm lint
# 或
make lint
```

## Makefile 命令

| 命令 | 说明 |
|------|------|
| `make dev` | 启动开发服务器 |
| `make build` | 类型检查 + 构建 |
| `make lint` | 代码检查 |
| `make preview` | 预览构建产物 |
| `make install` | 安装依赖 |
| `make typecheck` | TypeScript 类型检查 |
| `make clean` | 删除 node_modules 和 dist |
| `make reinstall` | 清理后重新安装依赖 |

## 路由

| 路径 | 页面 | 需认证 |
|------|------|--------|
| `/login` | 登录页 | 否 |
| `/` | 控制台 | 是 |
| `/users` | 用户管理 | 是 |
| `/roles` | 角色管理 | 是 |
| `/permissions` | 权限配置 | 是 |
| `/logs` | 操作日志 | 是 |

## 认证流程

1. 用户登录后，JWT Token 存储在 `sessionStorage`
2. 请求拦截器自动注入 `Authorization: Bearer <token>`
3. 401 响应自动使用 refresh_token 刷新，刷新失败跳转登录页
4. 业务错误码 `10002` 触发会话过期处理

## 后端对接

开发环境通过 Vite proxy 代理到后端服务：

- `/api` → `http://localhost:8080`
- `/health` → `http://localhost:8080`

后端 API 基础路径：`/api/v1/`，管理员接口：`/api/v1/admin/`

## 上线前准备与部署指南

### 1. 环境与配置要求

#### 1.1 生产环境依赖

| 依赖 | 最低版本 | 说明 |
|------|---------|------|
| Node.js | >= 18 LTS | 构建环境需要，生产服务器不需要 |
| pnpm | >= 8 | 构建环境包管理器 |
| Nginx | >= 1.24 | 生产环境静态资源服务器与反向代理 |
| 后端 API 服务 | - | Go + Gin，端口 8080，需提前部署就绪 |

#### 1.2 系统参数配置

| 参数 | 建议值 | 说明 |
|------|--------|------|
| 操作系统 | Ubuntu 22.04 / CentOS 7+ | Linux 发行版 |
| 内存 | >= 2GB | Nginx + 构建过程 |
| 磁盘 | >= 10GB | 构建产物 + 日志 |
| 开放端口 | 80 / 443 | HTTP / HTTPS |

#### 1.3 关键配置项说明

**环境变量**（通过 `.env.production` 或构建时注入）：

```bash
# .env.production（如需自定义 API 地址，默认走 Nginx 同域代理无需配置）
VITE_API_BASE_URL=/api
```

**Nginx 关键配置项**：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # Gzip 压缩（减小传输体积）
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 1024;

    # 静态资源根目录
    root /usr/share/nginx/html;
    index index.html;

    # SPA 路由：所有非文件路径返回 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 60s;
        proxy_read_timeout 120s;
    }

    # 健康检查代理
    location /health {
        proxy_pass http://127.0.0.1:8080/health;
    }

    # 静态资源长缓存（Vite 构建产物带 hash）
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }
}
```

**构建配置项**（`vite.config.ts` 可选优化）：

```typescript
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'antd': ['antd', '@ant-design/icons'],
          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
        },
      },
    },
    chunkSizeWarningLimit: 1000,
  },
});
```

### 2. 部署与上线流程

#### 2.1 代码构建

```bash
# 1. 拉取最新代码
git pull origin main

# 2. 安装依赖
pnpm install --frozen-lockfile

# 3. 代码检查（必须通过）
pnpm lint

# 4. TypeScript 类型检查（必须通过）
pnpm exec tsc -b --noEmit

# 5. 生产构建
pnpm build

# 构建产物在 dist/ 目录
ls -la dist/
# index.html  assets/index-xxx.js  assets/index-xxx.css  ...
```

#### 2.2 服务部署

```bash
# 1. 将构建产物上传到服务器
scp -r dist/* user@your-server:/usr/share/nginx/html/

# 2. 上传 Nginx 配置
scp nginx.conf user@your-server:/etc/nginx/conf.d/rbac-admin.conf

# 3. SSH 到服务器
ssh user@your-server

# 4. 检查 Nginx 配置语法
sudo nginx -t

# 5. 重载 Nginx
sudo nginx -s reload
```

#### 2.3 正式上线检查清单

| 序号 | 检查项 | 验证方式 | 通过标准 |
|------|--------|---------|---------|
| 1 | 构建无报错 | `pnpm build` 退出码为 0 | 无 TypeScript 错误、无构建警告 |
| 2 | Lint 无错误 | `pnpm lint` | 无 error 级别问题 |
| 3 | 页面可访问 | 浏览器访问 `http://domain` | 登录页正常渲染 |
| 4 | 登录功能 | 输入账号密码登录 | 成功跳转控制台 |
| 5 | API 连通 | 登录后查看网络请求 | `/api/v1/profile` 返回 200 |
| 6 | 路由守卫 | 未登录状态直接访问 `/users` | 自动跳转到 `/login` |
| 7 | Token 刷新 | 等待 access_token 过期后操作 | 自动刷新，无感知 |
| 8 | 静态资源缓存 | 浏览器 DevTools Network | `/assets/` 资源返回 304 或命中缓存 |
| 9 | HTTPS | 访问 HTTPS 地址 | 证书有效，无混合内容 |

### 3. 运维与保障策略

#### 3.1 健康检查验证

**前端健康检查**：

```bash
# 检查 Nginx 是否正常响应
curl -s -o /dev/null -w "%{http_code}" http://localhost/
# 期望返回 200

# 检查 index.html 是否存在
curl -s http://localhost/ | head -5
# 期望返回 HTML 内容

# 检查静态资源可访问
curl -s -o /dev/null -w "%{http_code}" http://localhost/assets/$(ls dist/assets/*.js | head -1 | xargs basename)
# 期望返回 200
```

**后端健康检查**：

```bash
# 通过 Nginx 代理检查后端
curl -s http://localhost/health
# 期望返回 200

# 直接检查后端服务
curl -s http://127.0.0.1:8080/health
# 期望返回 200
```

**自动化监控脚本**：

```bash
#!/bin/bash
# healthcheck.sh - 添加到 crontab 每 5 分钟执行
# */5 * * * * /opt/scripts/healthcheck.sh >> /var/log/healthcheck.log 2>&1

FRONTEND_URL="http://localhost"
BACKEND_URL="http://localhost/health"
ALERT_WEBHOOK="https://your-webhook-url"

check() {
  local name=$1 url=$2
  status=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "$url")
  if [ "$status" != "200" ]; then
    echo "[$(date)] ALERT: $name returned $status" 
    # curl -s -X POST "$ALERT_WEBHOOK" -H 'Content-type: application/json' \
    #   --data "{\"text\":\"$name health check failed: HTTP $status\"}"
  fi
}

check "Frontend" "$FRONTEND_URL"
check "Backend" "$BACKEND_URL"
```

#### 3.2 回滚方案

**方案一：版本化部署（推荐）**

```bash
# 每次部署保留历史版本
DEPLOY_DIR="/usr/share/nginx"
VERSION=$(date +%Y%m%d%H%M%S)

# 部署新版本（不删除旧版本）
mkdir -p "$DEPLOY_DIR/releases/$VERSION"
cp -r dist/* "$DEPLOY_DIR/releases/$VERSION/"

# 切换软链接
ln -sfn "$DEPLOY_DIR/releases/$VERSION" "$DEPLOY_DIR/html-current"
# Nginx root 指向 /usr/share/nginx/html-current

# 重载 Nginx
sudo nginx -s reload

# 回滚到上一版本
PREVIOUS=$(ls -t "$DEPLOY_DIR/releases/" | sed -n '2p')
ln -sfn "$DEPLOY_DIR/releases/$PREVIOUS" "$DEPLOY_DIR/html-current"
sudo nginx -s reload
echo "Rolled back to $PREVIOUS"

# 保留最近 5 个版本，清理更早的
cd "$DEPLOY_DIR/releases/" && ls -t | tail -n +6 | xargs rm -rf
```

**方案二：Git 快速回滚**

```bash
# 1. 查看提交历史，找到上一个稳定版本
git log --oneline -10

# 2. 回退到指定版本
git checkout <stable-commit-hash>

# 3. 重新构建并部署
pnpm install --frozen-lockfile
pnpm build
scp -r dist/* user@your-server:/usr/share/nginx/html/
ssh user@your-server "sudo nginx -s reload"

# 4. 回到最新代码
git checkout main
```

**方案三：备份恢复**

```bash
# 部署前备份当前版本
BACKUP_VERSION=$(date +%Y%m%d%H%M%S)
ssh user@your-server "cp -r /usr/share/nginx/html /usr/share/nginx/html-backup-$BACKUP_VERSION"

# 异常时恢复
ssh user@your-server "rm -rf /usr/share/nginx/html && mv /usr/share/nginx/html-backup-$BACKUP_VERSION /usr/share/nginx/html"
ssh user@your-server "sudo nginx -s reload"
```

#### 3.3 常见异常处理

| 异常现象 | 可能原因 | 处理方式 |
|---------|---------|---------|
| 页面白屏 | 构建产物缺失或路径错误 | 检查 `dist/` 是否完整、Nginx root 配置 |
| 404 刷新 | Nginx 未配置 SPA fallback | 确认 `try_files $uri $uri/ /index.html` |
| API 502 | 后端服务未启动 | 检查后端进程、重启后端服务 |
| 登录后空白 | API 连接失败 | 检查 Nginx proxy_pass 配置、后端日志 |
| 静态资源 404 | 构建后未替换全部文件 | 清空 html 目录后重新上传 dist/ |
| Token 刷新循环 | 后端 refresh 接口异常 | 检查后端日志、确认 refresh_token 有效 |