管理后台使用指南

Unicode Framework 提供了一个功能完整的管理后台应用（Admin Panel），基于 Vue3 + Element Plus 构建，提供了权限管理、资源管理、配置管理等核心功能。

概述

Admin 应用位于 app/admin/ 目录，是一个独立的应用，具有以下特性：

• ✅ 完整的 RBAC 权限系统 - 管理员、角色、权限管理
• ✅ 标准化的资源管理 - 基于 ResourceController 的 CRUD 操作
• ✅ 灵活的配置管理 - 支持分组配置，可动态修改
• ✅ 文件上传与管理 - 支持多种存储方式，文件分类管理
• ✅ 操作日志记录 - 自动记录管理员操作
• ✅ 数据库管理工具 - 表结构查看、迁移文件生成
• ✅ Vue3 SPA 前端 - 现代化的管理界面

快速开始

1. 访问管理后台

在路径策略下，管理后台的访问路径为：

http://your-domain.com/admin

2. 默认管理员账号

首次使用需要创建管理员账号，可以通过数据库迁移或命令行工具创建：

// 在数据库迁移中创建默认管理员
$admin = AdminUser::create([
    'username' => 'admin',
    'password' => password_hash('admin123', PASSWORD_DEFAULT),
    'nickname' => '超级管理员',
    'email' => 'admin@example.com',
    'status' => true,
]);

3. 登录系统

访问 /admin 会自动跳转到登录页面，使用管理员账号登录即可。

权限管理（RBAC）

Admin 应用提供了完整的基于角色的访问控制（RBAC）系统。

核心概念

• 管理员（AdminUser） - 系统的使用者
• 角色（Role） - 权限的集合
• 权限（Permission） - 具体的操作权限
• 菜单（Menu） - 前端菜单项，可关联权限

管理员管理

#### 创建管理员

use App\Admin\Model\AdminUser;
$admin = new AdminUser();
$admin->username = 'newadmin';
$admin->setPassword('password123');
$admin->nickname = '新管理员';
$admin->email = 'newadmin@example.com';
$admin->status = true;
$admin->save();
// 分配角色
$admin->assignRoles([1, 2]); // 角色ID数组

#### 验证密码

$admin = AdminUser::findByUsername('admin');
if ($admin && $admin->verifyPassword('password123')) {
    // 密码正确
}

角色管理

#### 创建角色

use App\Admin\Model\Role;
$role = Role::create([
    'name' => '编辑',
    'description' => '内容编辑角色',
    'status' => true,
]);
// 分配权限
$role->assignPermissions([1, 2, 3]); // 权限ID数组

#### 检查权限

// 在控制器中检查当前管理员是否有权限
$admin = $request->attribute('admin'); // 从中间件获取
if (!$admin->hasPermission('article.create')) {
    return Response::json(['message' => '无权限'], 403);
}

权限配置

权限通过配置文件定义，位于 app/admin/config/permissions.php：

return [
    'article' => [
        'title' => '文章管理',
        'permissions' => [
            'article.view' => '查看文章',
            'article.create' => '创建文章',
            'article.update' => '更新文章',
            'article.delete' => '删除文章',
        ],
    ],
];

资源管理

Admin 应用提供了 ResourceController 基类，可以快速创建标准化的 CRUD 控制器。

使用 ResourceController

#### 1. 创建控制器

<?php
namespace App\Admin\Controller;
use App\Admin\Model\Article;
class ArticleController extends ResourceController
{
    protected function getModelClass(): string
    {
        return Article::class;
    }
// 可选：配置可搜索字段
    protected function getSearchableFields(): array
    {
        return ['title', 'content', 'author'];
    }
// 可选：配置可筛选字段
    protected function getFilterableFields(): array
    {
        return ['status', 'category_id'];
    }
}

#### 2. 配置路由

// app/admin/route.php
Route::group('/api/articles', function () {
    Route::get('/', [ArticleController::class, 'index'], 'admin.api.articles.index');
    Route::get('/{id}', [ArticleController::class, 'show'], 'admin.api.articles.show');
    Route::post('/', [ArticleController::class, 'store'], 'admin.api.articles.store');
    Route::put('/{id}', [ArticleController::class, 'update'], 'admin.api.articles.update');
    Route::delete('/{id}', [ArticleController::class, 'destroy'], 'admin.api.articles.destroy');
    Route::post('/batch-destroy', [ArticleController::class, 'batchDestroy'], 'admin.api.articles.batch-destroy');
});

#### 3. API 接口说明

列表查询 - GET /api/articles

支持以下查询参数：

• page - 页码（默认 1）
• pageSize - 每页数量（默认 15）
• keyword - 关键词搜索（在可搜索字段中搜索）
• status - 筛选字段（如果配置了可筛选字段）
• sort - 排序字段（格式：field:direction，如 created_at:desc）
详情查询 - GET /api/articles/{id} 创建资源 - POST /api/articles

请求体包含要创建的数据。

更新资源 - PUT /api/articles/{id}

请求体包含要更新的数据。

删除资源 - DELETE /api/articles/{id}

支持软删除（如果模型启用了软删除）。

批量删除 - POST /api/articles/batch-destroy

请求体：

{
  "ids": [1, 2, 3]
}

自定义钩子方法

ResourceController 提供了多个钩子方法，可以在子类中重写：

class ArticleController extends ResourceController
{
    // 在查询前执行
    protected function beforeQuery(Request $request, QueryBuilder $query): void
    {
        // 添加自定义查询条件
        $query->where('status', '!=', 'deleted');
    }
// 在保存前执行（创建和更新）
    protected function beforeSave(Request $request, array &$data): void
    {
        // 修改或验证数据
        $data['author_id'] = $request->attribute('admin')->id;
    }
// 在保存后执行
    protected function afterSave(Request $request, Model $model): void
    {
        // 保存后的操作，如清除缓存
    }
// 在删除前执行
    protected function beforeDelete(Request $request, Model $model): void
    {
        // 删除前的检查
        if ($model->status === 'published') {
            throw new \Exception('已发布的文章不能删除');
        }
    }
}

配置管理

Admin 应用提供了灵活的配置管理系统，支持分组配置和动态修改。

配置服务

使用 Common\Config\ConfigService 来读取配置：

use Common\Config\ConfigService;
$configService = new ConfigService();
// 获取配置值（默认分组为 basic）
$siteName = $configService->get('site_name', '默认站点名称');
// 获取指定分组的配置值
$smtpHost = $configService->get('email.smtp_host', 'localhost');
// 获取整个分组的配置
$emailConfig = $configService->getGroup('email');
// 获取所有配置
$allConfigs = $configService->getAll();

配置类型

配置支持以下类型：

• text - 文本（默认）
• number - 数字（自动转换为 int 或 float）
• boolean - 布尔值（自动转换为 true/false）
• json - JSON 数据（自动解析为数组）

配置分组

建议的配置分组：

• basic - 基础配置（站点名称、描述等）
• email - 邮件配置（SMTP 设置等）
• storage - 存储配置（OSS、S3 等）
• payment - 支付配置
• sms - 短信配置
• upload - 上传配置（文件大小限制等）

管理界面

Admin 应用提供了两个配置管理页面：

• Settings.vue - 完整配置管理（开发人员使用）

- 可以添加、编辑、删除配置项 - 可以修改配置的所有属性 - 访问路径：/config/settings

• ConfigView.vue - 简化配置页面（普通用户使用）
- 只能修改配置值 - 不能修改配置结构 - 访问路径：/config/view

文件管理

Admin 应用集成了文件上传和管理功能，支持多种存储方式。

文件上传

use Common\File\FileUploadService;
$uploadService = new FileUploadService();
// 上传文件
$result = $uploadService->upload($request->files['file'], [
    'category' => 'image', // 文件分类
    'disk' => 'local',     // 存储磁盘
]);
// 返回结果包含文件信息
// [
//     'id' => 1,
//     'path' => 'uploads/2024/01/file.jpg',
//     'url' => 'http://example.com/uploads/2024/01/file.jpg',
//     'size' => 1024,
//     'mime_type' => 'image/jpeg',
// ]

文件分类

文件分类用于组织和管理文件，可以通过管理界面或代码创建：

use App\Admin\Model\FileCategory;
$category = FileCategory::create([
    'name' => '图片',
    'code' => 'image',
    'description' => '图片文件',
]);

文件查询

use Common\File\FileManagerService;
$fileManager = new FileManagerService();
// 根据ID获取文件
$file = $fileManager->getFile(1);
// 根据路径获取文件
$file = $fileManager->getFileByPath('uploads/file.jpg', 'local');

操作日志

Admin 应用会自动记录管理员的操作日志。

配置操作日志

在 app/admin/config/operation_log.php 中配置：

return [
    // 是否启用操作日志
    'enabled' => true,
// 记录的操作类型
    'actions' => [
        'create', 'update', 'delete', 'login', 'logout',
    ],
// 排除的路由（不记录日志）
    'except' => [
        '/api/me',
        '/api/captcha',
    ],
];

查看操作日志

操作日志存储在 admin_operation_logs 表中，可以通过管理界面或 API 查看。

数据库管理

Admin 应用提供了数据库管理工具，可以查看表结构和生成迁移文件。

查看表结构

访问 /admin/database/tables 可以查看所有数据库表。

生成迁移文件

访问 /admin/database/migrations/generate 可以根据表结构生成迁移文件。

中间件配置

Admin 应用的中间件配置位于 app/admin/middleware.php：

return [
    // 全局中间件
    'middleware' => [
        \App\Admin\Middleware\CsrfMiddleware::class,
        \App\Admin\Middleware\AdminAuthMiddleware::class,
        \App\Admin\Middleware\AdminOperationLogMiddleware::class,
    ],
// 例外路由（不需要执行中间件）
    'except' => [
        'GET /api/csrf-token',
        'GET /api/captcha',
        'POST /api/login',
    ],
];

CSRF 防护

Admin 应用使用 Session 存储 CSRF Token，前端需要在请求头中携带：

// 获取 CSRF Token
const response = await fetch("/admin/api/csrf-token");
const { token } = await response.json();
// 在请求头中携带
fetch("/admin/api/articles", {
  method: "POST",
  headers: {
    "X-CSRF-Token": token,
  },
});

认证中间件

AdminAuthMiddleware 会自动验证管理员身份，并将管理员信息存储到请求属性中：

// 在控制器中获取当前管理员
$admin = $request->attribute('admin');

前端开发

Admin 应用的前端基于 Vue3 + Element Plus，位于 resources/js/admin/ 目录。

项目结构

resources/js/admin/
├── components/      # 公共组件
├── views/          # 页面组件
├── router/         # 路由配置
├── store/          # 状态管理
├── api/            # API 接口
└── main.js         # 入口文件

路由配置

路由配置支持动态加载，菜单数据从后端获取：

// router/index.js
import { addDynamicRoutes } from "./dynamic";
// 添加动态路由
await addDynamicRoutes(router);

API 调用

使用统一的 API 客户端：

import api from "@/api";
// GET 请求
const articles = await api.get("/articles", { params: { page: 1 } });
// POST 请求
const result = await api.post("/articles", { title: "标题", content: "内容" });

权限控制

前端路由支持权限控制，无权限的路由会自动隐藏：

// 在路由配置中添加权限
{
  path: '/articles',
  component: ArticleList,
  meta: {
    permission: 'article.view',
  },
}

最佳实践

• 权限设计 - 遵循最小权限原则，只授予必要的权限
• 资源管理 - 使用 ResourceController 统一 CRUD 操作
• 配置管理 - 将可配置项统一管理，便于维护
• 操作日志 - 重要操作都要记录日志，便于审计
• 前端路由 - 使用动态路由，根据权限动态加载菜单

常见问题

1. 如何创建第一个管理员？

可以通过数据库迁移或命令行工具创建：

// 在迁移文件中
$admin = AdminUser::create([
    'username' => 'admin',
    'password' => password_hash('admin123', PASSWORD_DEFAULT),
    'nickname' => '超级管理员',
    'status' => true,
]);

2. 如何自定义 ResourceController 的行为？

重写钩子方法，如 beforeSave、afterSave 等。

3. 如何添加新的配置分组？

直接在数据库中插入配置记录，指定新的分组名称即可。

4. 如何禁用操作日志？

在 app/admin/config/operation_log.php 中设置 'enabled' => false。

相关文档

• 多应用架构 - 了解多应用模式
• 认证系统 - JWT 认证详解
• 文件系统 - 文件存储配置
• 配置管理 - 配置服务详细说明