622 lines
22 KiB
Markdown
622 lines
22 KiB
Markdown
# 1.4 新手入门指南
|
||
|
||
:::warning 特别提醒
|
||
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
|
||
:::
|
||
|
||
## 教程概述
|
||
|
||
本教程将带你从零开始，完成一个完整的后台管理系统的搭建和运行。整个过程分为以下几个步骤：
|
||
|
||
```text
|
||
1. 环境准备：安装 PHP、MySQL、Redis、Composer、Node.js 等基础软件。
|
||
2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包并解压。
|
||
3. 后端启动：安装 Composer 依赖、配置环境变量、初始化数据库、启动后端服务。
|
||
4. 前端启动：安装前端依赖、启动前端开发服务器。
|
||
5. 功能验证：登录系统，验证各功能模块是否正常。
|
||
6. 新增模块：以 example 模块为例，演示如何新增一个完整的业务模块。
|
||
```
|
||
|
||
## 第一步：环境准备
|
||
|
||
确保电脑上已安装以下软件：
|
||
|
||
| 软件 | 版本要求 | 用途 |
|
||
|------|----------|------|
|
||
| PHP | 8.3+ | 后端运行环境 |
|
||
| MySQL | 8.0+ | 数据库（另支持 PostgreSQL、SQL Server、Oracle、SQLite） |
|
||
| Redis | 6.0+ | **必需**：JWT 会话、权限缓存、验证码、字典缓存均依赖 |
|
||
| Composer | 2.x | PHP 依赖管理 |
|
||
| Node.js | 22.18.0（22+） | 前端构建环境 |
|
||
|
||
:::tip 温馨提示
|
||
Windows 环境推荐使用 Laragon 集成安装（含 PHP / MySQL / Redis），详细步骤请参考 [2.1 开发环境准备](/zh/quickstart/environment.html) 与 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)。不想手动搭建环境可直接使用 [2.8 Docker 快速体验](/zh/quickstart/docker.html)。
|
||
:::
|
||
|
||
## 第二步：获取源码
|
||
|
||
前往 [官方网站](https://www.rxthink.cn) 购买授权后，按以下步骤获取源码：
|
||
|
||
1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
|
||
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
|
||
3. 下载的压缩包包含完整的后端源码、数据库脚本及部署配置文件。
|
||
4. 将压缩包解压到本地开发目录（如 `D:\laragon\www\` 或 `~/www/`）。
|
||
|
||
```bash
|
||
# 进入项目目录（以实际解压路径为准）
|
||
cd RXThinkCMF_Laravel13_EleVue
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. 源码包请务必从[官方网站](https://www.rxthink.cn)订单中心下载，确保获取的是正版授权的最新版本。
|
||
2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
|
||
3. 解压后请先阅读根目录下的 `README.md` 了解项目概况。
|
||
:::
|
||
|
||
## 第三步：后端启动
|
||
|
||
### 3.1 安装 Composer 依赖
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 方式一：一键初始化（推荐，自动完成依赖安装 + .env + APP_KEY + 迁移 + 前端构建）
|
||
# -----------------------------------------------------------------------------
|
||
composer setup
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 方式二：手动逐步执行
|
||
# -----------------------------------------------------------------------------
|
||
# 安装项目依赖（从 composer.lock 精确安装）
|
||
composer install
|
||
|
||
# 如果国内下载慢，先配置阿里云镜像（加速依赖下载）
|
||
# config -g → 修改全局配置（所有项目生效）
|
||
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
|
||
composer install
|
||
```
|
||
|
||
### 3.2 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板（.env.example 是模板，.env 是实际配置文件）
|
||
cp .env.example .env
|
||
|
||
# 生成应用加密密钥（APP_KEY，写入 .env）
|
||
php artisan key:generate
|
||
```
|
||
|
||
编辑 `.env` 文件，重点确认以下配置：
|
||
|
||
```ini
|
||
# 开启调试模式（开发环境 true，生产环境必须 false）
|
||
APP_DEBUG=true
|
||
|
||
# 数据库配置
|
||
DB_CONNECTION=mysql # 数据库类型（mysql / pgsql / sqlsrv / sqlite）
|
||
DB_HOST=127.0.0.1 # 数据库地址
|
||
DB_PORT=3306 # 端口
|
||
DB_DATABASE=rxthinkcmf.laravel13.elevue # 数据库名（需提前创建）
|
||
DB_USERNAME=root # 用户名
|
||
DB_PASSWORD=root # 密码
|
||
DB_PREFIX=laravel_ # 表前缀（数据库脚本使用 laravel_ 前缀，必须保留）
|
||
|
||
# JWT 密钥配置（应用启动 fail-close 校验：必须 >= 32 字符）
|
||
JWT_SECRET=your_random_jwt_secret_key_at_least_32_bytes
|
||
JWT_ACCESS_TTL=7200 # access_token 有效期（秒，默认 2 小时）
|
||
JWT_REFRESH_TTL=604800 # refresh_token 有效期（秒，默认 7 天）
|
||
|
||
# Redis 配置（必需；设置了 requirepass 时必须同步本项）
|
||
REDIS_CLIENT=phpredis
|
||
REDIS_HOST=127.0.0.1
|
||
REDIS_PASSWORD=null # Redis 有密码时改为实际密码
|
||
REDIS_PORT=6379
|
||
|
||
# 会话 / 缓存 / 队列统一走 Redis（数据库脚本不含 framework 表）
|
||
SESSION_DRIVER=redis
|
||
CACHE_STORE=redis
|
||
QUEUE_CONNECTION=redis
|
||
|
||
# 跨域（本地开发允许前端域名，生产环境改为具体域名）
|
||
CORS_ALLOW_ORIGIN=*
|
||
|
||
# 文件上传
|
||
FILE_UPLOAD_DIR=uploads # 上传目录（相对 public/）
|
||
FILE_DOMAIN_URL= # 文件访问域名（空则返回相对路径）
|
||
FILE_MAX_SIZE=10 # 单文件大小上限（MB）
|
||
```
|
||
|
||
:::danger 重要提示
|
||
1. `JWT_SECRET` 为空或不足 32 字符时，应用**拒绝启动**并抛出异常（fail-close 安全机制）。生成方式：`openssl rand -base64 32` 或 `php -r "echo bin2hex(random_bytes(32));"`。
|
||
2. `DB_PREFIX=laravel_` 必须保留，数据库脚本中的表均使用该前缀。
|
||
3. Redis 设置了密码（`requirepass`）时，`.env` 中 `REDIS_PASSWORD` 必须同步配置，否则验证码、JWT 会话等会全部失败。
|
||
:::
|
||
|
||
### 3.3 初始化数据库
|
||
|
||
**本项目未使用 Laravel 迁移建表**（`database/migrations/` 为空），数据库结构以 SQL 脚本为准：
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 第 1 步：登录 MySQL，创建数据库
|
||
# -----------------------------------------------------------------------------
|
||
mysql -uroot -p
|
||
|
||
# 在 MySQL 命令行中执行（创建项目数据库）：
|
||
# CHARACTER SET utf8mb4 → 支持 emoji 等四字节字符
|
||
# COLLATE utf8mb4_general_ci → 不区分大小写的排序规则
|
||
CREATE DATABASE `rxthinkcmf.laravel13.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 2 步：导入数据库脚本（约 226MB，含 25 张业务表 + 初始数据）
|
||
# -----------------------------------------------------------------------------
|
||
mysql -uroot -proot rxthinkcmf.laravel13.elevue < document/mysql/rxthinkcmf.laravel13.elevue.sql
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
- 脚本位于 `document/mysql/rxthinkcmf.laravel13.elevue.sql`（五种数据库各有专用脚本，按 `document/<数据库类型>/` 分组），导入耗时约 1~3 分钟；
|
||
- 使用 [2.8 Docker 快速体验](/zh/quickstart/docker.html) 时无需手动导入，首次启动自动完成；
|
||
- 详细的多数据库初始化步骤请参考 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
|
||
:::
|
||
|
||
初始化完成后，数据库中包含以下默认数据：
|
||
|
||
```text
|
||
管理员账号：admin / 123456（超级管理员，ID=1，跳过权限校验）
|
||
默认角色：超级管理员角色
|
||
默认菜单：系统管理、内容管理、监控管理等菜单及权限节点
|
||
数据字典：系统内置字典数据
|
||
系统配置：系统默认配置项、系统参数
|
||
城市数据：全国行政区划数据
|
||
默认租户：平台租户数据
|
||
```
|
||
|
||
### 3.4 启动后端服务
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 推荐：一键启动（同时启动 artisan serve + 队列 + 日志流 + Vite 四个进程）
|
||
# -----------------------------------------------------------------------------
|
||
composer dev
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 或单独启动 API 服务（默认监听 127.0.0.1:8000）
|
||
# -----------------------------------------------------------------------------
|
||
php artisan serve
|
||
```
|
||
|
||
启动成功后会看到：
|
||
|
||
```text
|
||
INFO Server running on [http://127.0.0.1:8000].
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
打开浏览器访问 `http://localhost:8000/` 可验证后端服务是否正常启动；健康检查接口为 `http://localhost:8000/up`。
|
||
:::
|
||
|
||
## 第四步：前端启动
|
||
|
||
### 4.1 安装前端依赖
|
||
|
||
前端 EleVue 管理后台位于本仓库的 `ui/` 目录（Vue3 + ElementPlus）：
|
||
|
||
```bash
|
||
# 进入前端项目目录
|
||
cd ui
|
||
|
||
# 安装依赖（从 lock 文件精确安装）
|
||
npm install
|
||
# 或
|
||
pnpm install
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
如果安装速度较慢，可配置国内镜像源：
|
||
|
||
```bash
|
||
# npm 国内镜像
|
||
npm config set registry https://registry.npmmirror.com
|
||
|
||
# pnpm 国内镜像
|
||
pnpm config set registry https://registry.npmmirror.com
|
||
```
|
||
:::
|
||
|
||
### 4.2 启动前端开发服务器
|
||
|
||
```bash
|
||
# 启动 Vite 开发服务器（支持热更新 — 修改代码后浏览器自动刷新）
|
||
pnpm dev
|
||
```
|
||
|
||
启动成功后会看到：
|
||
|
||
```text
|
||
VITE v3.x.x ready in xxx ms
|
||
|
||
➜ Local: http://localhost:8001/
|
||
```
|
||
|
||
### 4.3 访问系统
|
||
|
||
打开浏览器访问 `http://localhost:8001`，使用默认账号登录：
|
||
|
||
```text
|
||
账号：admin
|
||
密码：123456
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
前端默认运行在 `8001` 端口，后端默认 `8000` 端口。Vite 开发代理由 `ui/.env.development` 的 `VITE_PROXY` 决定（默认转发到 `http://admin.laravel13.elevue/api`；直连 `php artisan serve` 时改为 `http://localhost:8000/api`，改后重启生效）。登录后请立即修改默认密码。
|
||
:::
|
||
|
||
## 第五步：功能验证
|
||
|
||
登录成功后，可以验证以下核心功能：
|
||
|
||
```text
|
||
1. 控制台：首页仪表盘，显示系统概况。
|
||
2. 用户管理：系统管理 → 用户管理，查看用户列表、新增、编辑、删除。
|
||
3. 角色管理：系统管理 → 角色管理，管理角色和权限分配。
|
||
4. 菜单管理：系统管理 → 菜单管理，管理菜单和权限节点。
|
||
5. 数据字典：数据管理 → 字典管理，管理系统字典数据。
|
||
6. 操作日志：系统管理 → 日志管理 → 操作日志，查看操作记录。
|
||
7. 代码生成：开发工具 → 代码生成，体验代码生成功能。
|
||
```
|
||
|
||
也可直接用命令行验证接口链路（验证码接口同时验证 PHP → Redis 链路）：
|
||
|
||
```bash
|
||
curl http://localhost:8000/api/captcha
|
||
# → {"code":0,"ok":true,"msg":"操作成功","data":{...}}
|
||
```
|
||
|
||
## 第六步：新增业务模块
|
||
|
||
以项目内置的「案例演示」模块为例，演示如何新增一个完整的 CRUD 模块（该模块是代码生成器的参考模板，以下代码均摘自项目实际源码）。
|
||
|
||
### 6.1 数据库建表
|
||
|
||
```sql
|
||
-- =============================================================================
|
||
-- 创建案例演示表
|
||
-- =============================================================================
|
||
-- 表前缀 laravel_ 由 .env 中 DB_PREFIX 决定
|
||
-- 模型 Trait 会自动管理 create_user / create_time / update_user / update_time
|
||
-- =============================================================================
|
||
|
||
CREATE TABLE `laravel_example` (
|
||
`id` INT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
|
||
`name` VARCHAR(200) NOT NULL COMMENT '案例名称',
|
||
`code` VARCHAR(50) DEFAULT '' COMMENT '案例编码',
|
||
`avatar` VARCHAR(500) DEFAULT '' COMMENT '头像/图片地址',
|
||
`type` TINYINT(1) DEFAULT 1 COMMENT '类型：1=类型1 2=类型2 3=类型3 4=类型4',
|
||
`status` TINYINT(1) DEFAULT 1 COMMENT '状态：1=在用 2=停用',
|
||
`sort` INT DEFAULT 0 COMMENT '排序值',
|
||
`is_delete` TINYINT(1) DEFAULT 0 COMMENT '软删除标记：0=正常 1=已删除',
|
||
`create_user` VARCHAR(50) DEFAULT '' COMMENT '创建人',
|
||
`create_time` DATETIME DEFAULT NULL COMMENT '创建时间',
|
||
`update_user` VARCHAR(50) DEFAULT '' COMMENT '更新人',
|
||
`update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
|
||
PRIMARY KEY (`id`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='案例演示';
|
||
```
|
||
|
||
### 6.2 模型层 — Model
|
||
|
||
`app/Models/Example.php`：
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Models;
|
||
|
||
use App\Models\Concerns\HasAuditColumns;
|
||
use App\Models\Concerns\SoftDeletesByFlag;
|
||
use Illuminate\Database\Eloquent\Model;
|
||
|
||
/**
|
||
* 案例演示模型
|
||
*
|
||
* 对应数据表 example，继承 Eloquent Model 获得通用模型能力。
|
||
*
|
||
* 说明：
|
||
* - 通过 HasAuditColumns 自动维护审计字段（如 created_by、updated_by 等）。
|
||
* - 通过 SoftDeletesByFlag 实现基于标志位的软删除（如 is_deleted 字段）。
|
||
* - type 类型：1=类型1，2=类型2，3=类型3，4=类型4。
|
||
* - status 状态：1=在用，2=停用。
|
||
*/
|
||
class Example extends Model
|
||
{
|
||
use HasAuditColumns, SoftDeletesByFlag;
|
||
|
||
/**
|
||
* 数据表名
|
||
*
|
||
* 显式指定表名为 example，覆盖默认的类名推导规则。
|
||
*
|
||
* @var string
|
||
*/
|
||
protected $table = 'example';
|
||
|
||
/**
|
||
* 允许批量赋值的字段列表
|
||
*
|
||
* @var array<int, string>
|
||
*/
|
||
protected $fillable = [
|
||
'name', // 名称
|
||
'avatar', // 头像/图片地址
|
||
'type', // 类型：1=类型1，2=类型2，3=类型3，4=类型4
|
||
'status', // 状态：1=在用，2=停用
|
||
'sort', // 排序值，数值越小越靠前（视业务而定）
|
||
];
|
||
}
|
||
```
|
||
|
||
:::tip
|
||
表名 `example` 不含前缀，实际查询时由 `DB_PREFIX=laravel_` 自动拼接为 `laravel_example`。
|
||
:::
|
||
|
||
### 6.3 参数验证 — FormRequest
|
||
|
||
`app/Http/Requests/ExampleRequest.php`：
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Requests;
|
||
|
||
/**
|
||
* 案例表单请求
|
||
*
|
||
* 负责案例演示新增/修改接口的参数校验。
|
||
*
|
||
* 说明：
|
||
* - 继承 BaseRequest，基础校验能力（失败响应统一处理）由基类提供。
|
||
* - 本类只声明案例特有的字段规则与自定义错误消息。
|
||
* - 前端传参使用 camelCase，数据库字段为 snake_case；
|
||
*/
|
||
class ExampleRequest extends BaseRequest
|
||
{
|
||
/**
|
||
* 校验规则
|
||
*
|
||
* @return array<string, string> 字段规则
|
||
*/
|
||
public function rules(): array
|
||
{
|
||
return [
|
||
'name' => 'required|string|max:255', // 案例名称：必填，最长 255
|
||
'avatar' => 'nullable|string|max:255', // 头像/图片地址：可空，最长 255
|
||
'type' => 'nullable|integer|in:1,2,3,4', // 类型：1=类型1，2=类型2，3=类型3，4=类型4
|
||
'status' => 'nullable|integer|in:1,2', // 状态：1=在用，2=停用
|
||
'sort' => 'nullable|integer', // 排序值：可空，整数
|
||
];
|
||
}
|
||
|
||
/**
|
||
* 自定义错误消息
|
||
*
|
||
* @return array<string, string> 字段规则 => 错误消息
|
||
*/
|
||
public function messages(): array
|
||
{
|
||
return [
|
||
'name.required' => '案例名称不能为空',
|
||
'name.max' => '案例名称不能超过 255 个字符',
|
||
'type.in' => '案例类型不合法，允许：1-类型1 2-类型2 3-类型3 4-类型4',
|
||
'status.in' => '状态值不合法，允许：1-在用 2-停用',
|
||
'sort.integer' => '排序值格式不正确',
|
||
];
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.4 业务逻辑 — Service
|
||
|
||
`app/Services/ExampleService.php`（节选，完整代码见项目源码）：
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Services;
|
||
|
||
use App\Models\Example;
|
||
use App\Services\Concerns\HasCrudOperations;
|
||
use App\Services\Concerns\HasQueryScopes;
|
||
use App\Services\Concerns\HasSerializeMaps;
|
||
use App\Services\Concerns\HasUniqueCheck;
|
||
|
||
/**
|
||
* 案例演示业务逻辑服务
|
||
*
|
||
* 继承 BaseService，案例作为示例数据，不参与多租户隔离。
|
||
*
|
||
* 说明：
|
||
* - 组合的 Trait 职责：
|
||
* - HasCrudOperations：add/update/delete/batchDelete 主流程；
|
||
* - HasQueryScopes：列表查询条件、排序白名单；
|
||
* - HasSerializeMaps：为 status 补 statusText（字典编码为 status）；
|
||
* - HasUniqueCheck：新增/修改时校验 name 唯一；
|
||
* - 未 use HasDataScope，因此不做数据权限与租户隔离；
|
||
*/
|
||
class ExampleService extends BaseService
|
||
{
|
||
use HasCrudOperations, HasQueryScopes, HasSerializeMaps, HasUniqueCheck;
|
||
|
||
/**
|
||
* 绑定的模型类
|
||
*/
|
||
protected string $modelClass = Example::class;
|
||
|
||
/**
|
||
* LIKE 模糊匹配字段
|
||
*
|
||
* @var array<int, string>
|
||
*/
|
||
protected array $pageLikeFields = ['name'];
|
||
|
||
/**
|
||
* 精确匹配字段
|
||
*
|
||
* status 用于按状态筛选。
|
||
*
|
||
* @var array<int, string>
|
||
*/
|
||
protected array $pageEqFields = ['status'];
|
||
|
||
/**
|
||
* 唯一性校验字段
|
||
*
|
||
* @var array<int, string>
|
||
*/
|
||
protected array $uniqueFields = ['name'];
|
||
|
||
/**
|
||
* 字典翻译配置：[字段 => 字典编码]
|
||
*
|
||
* 读取时为 status 补 statusText。
|
||
*
|
||
* @var array<string, string>
|
||
*/
|
||
protected array $serializeMaps = [
|
||
'status' => 'example_status',
|
||
];
|
||
}
|
||
```
|
||
|
||
分页、新增、修改、删除等方法**全部由 Trait 提供，无需手写**——这就是声明式 CRUD。
|
||
|
||
### 6.5 接口入口 — Controller
|
||
|
||
`app/Http/Controllers/Api/ExampleController.php`（节选）：
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Controllers\Api;
|
||
|
||
use App\Attributes\OperationLog;
|
||
use App\Attributes\Permission;
|
||
use App\Http\Controllers\Controller;
|
||
use App\Http\Requests\ExampleRequest;
|
||
use App\Services\ExampleService;
|
||
use Illuminate\Http\JsonResponse;
|
||
|
||
/**
|
||
* 示例管理控制器
|
||
*
|
||
* 具体业务逻辑委托给 ExampleService，控制器仅做参数校验、
|
||
* 权限与日志标注及响应封装。
|
||
*/
|
||
class ExampleController extends Controller
|
||
{
|
||
public function __construct(protected ExampleService $exampleService) {}
|
||
|
||
/**
|
||
* 查询分页
|
||
*
|
||
* 对应权限：sys:example:page，操作日志类型：查询。
|
||
*
|
||
* @return JsonResponse 分页数据
|
||
*/
|
||
#[OperationLog('示例管理-查询分页', OperationLog::TYPE_QUERY)]
|
||
#[Permission('sys:example:page', '示例分页')]
|
||
public function page(): JsonResponse
|
||
{
|
||
return $this->_page($this->exampleService);
|
||
}
|
||
|
||
/**
|
||
* 新增
|
||
*
|
||
* @param ExampleRequest $request 已通过校验的示例请求
|
||
* @return JsonResponse 新增结果
|
||
*/
|
||
#[OperationLog('示例管理-新增', OperationLog::TYPE_ADD, '新增示例：{name}')]
|
||
#[Permission('sys:example:add', '添加示例')]
|
||
public function add(ExampleRequest $request): JsonResponse
|
||
{
|
||
return $this->_add($this->exampleService, $request->validated());
|
||
}
|
||
|
||
// 修改 / 删除 / 批量删除 / 导出 / 导入同理：
|
||
// _update / _delete / _batchDelete / _export / _import 快捷方法一行调用
|
||
}
|
||
```
|
||
|
||
### 6.6 注册路由
|
||
|
||
在 `routes/api.php` 的认证中间件组中添加：
|
||
|
||
```php
|
||
// --- 案例演示 ---
|
||
Route::get('example/page', [Api\ExampleController::class, 'page']);
|
||
Route::get('example/list', [Api\ExampleController::class, 'list']);
|
||
Route::get('example/detail/{id}', [Api\ExampleController::class, 'detail']);
|
||
Route::post('example/add', [Api\ExampleController::class, 'add']);
|
||
Route::put('example/update', [Api\ExampleController::class, 'update']);
|
||
Route::delete('example/delete/{id}', [Api\ExampleController::class, 'delete']);
|
||
Route::delete('example/batchDelete', [Api\ExampleController::class, 'batchDelete']);
|
||
Route::get('example/export', [Api\ExampleController::class, 'export']);
|
||
Route::post('example/import', [Api\ExampleController::class, 'import']);
|
||
```
|
||
|
||
:::tip
|
||
公开接口（无需认证）应放在中间件组**外面**，认证接口放在 `['auth.jwt', 'tenant', 'demo', 'log.operation']` 组内——见 [3.7 路由注册](/zh/guide/route.html)。
|
||
:::
|
||
|
||
### 6.7 前端开发
|
||
|
||
在前端仓库的 `src/api/tool/example.ts` 中定义接口，在 `src/views/tool/example/` 中创建页面文件（列表页 / 编辑弹窗 / 详情弹窗 / 表格列定义 / 查询条件）。
|
||
|
||
### 6.8 配置菜单权限
|
||
|
||
在系统管理 → 菜单管理中：
|
||
|
||
```text
|
||
1. 新增菜单：案例演示（路由 /example，组件 tool/example/index）
|
||
2. 新增按钮：查看（sys:example:page）、新增（sys:example:add）、编辑（sys:example:update）、删除（sys:example:delete）
|
||
3. 在角色管理中为角色分配"案例演示"菜单权限
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
也可以使用代码生成器一键生成以上所有代码，详见 [第 10 章 代码生成器](/zh/generator/overview.html)。
|
||
:::
|
||
|
||
## 常见问题
|
||
|
||
在部署和使用过程中，可能会遇到以下常见问题：
|
||
|
||
```text
|
||
1. 端口被占用：执行 php artisan serve --port 8080 更换端口。
|
||
2. 数据库连接失败：检查 .env 中的数据库配置，确认 MySQL 服务已启动、数据库已创建并导入脚本。
|
||
3. 应用拒绝启动并提示 JWT_SECRET：密钥为空或不足 32 字符，用 openssl rand -base64 32 生成后重试。
|
||
4. 验证码报"服务不可用"：确认 Redis 已启动，且 .env 中 REDIS_PASSWORD 与 Redis 实际密码一致。
|
||
5. PHP 扩展缺失：运行 php -m 检查 pdo_mysql、mbstring、gd、redis 等扩展（Laragon 下需手动安装 php_redis.dll，
|
||
见 2.2 Laragon 环境搭建）。
|
||
6. Composer 安装慢：配置国内镜像 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
|
||
7. npm install 失败：配置国内镜像 npm config set registry https://registry.npmmirror.com。
|
||
8. 前端白屏：检查后端服务是否启动，浏览器控制台是否有报错。
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
更多问题请参考 [2.9 常见问题 FAQ](/zh/quickstart/faq.html) 章节。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
通过以上步骤，你已经完成了从零搭建一个完整的后台管理系统的全过程：
|
||
|
||
```text
|
||
1. 环境准备：PHP 8.3 + MySQL 8.0 + Redis 6.0 + Composer 2.x + Node.js 22.18.0
|
||
2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包
|
||
3. 后端启动：composer setup → 配置 .env → 导入数据库 → composer dev
|
||
4. 前端启动：cd ui → pnpm install → pnpm dev
|
||
5. 功能验证：登录系统，验证各模块功能
|
||
6. 新增模块：建表 → Model → FormRequest → Service → Controller → 路由 → 前端页面 → 菜单权限
|
||
```
|
||
|
||
整个搭建过程约 30 分钟即可完成。如果在操作过程中遇到问题，请查阅文档或在社区寻求帮助。
|