524 lines
17 KiB
Markdown
524 lines
17 KiB
Markdown
# 1.4 新手入门指南
|
||
|
||
:::warning 特别提醒
|
||
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
|
||
:::
|
||
|
||
## 教程概述
|
||
|
||
本教程将带你从零开始，完成一个完整的后台管理系统的搭建和运行。整个过程分为以下几个步骤：
|
||
|
||
```text
|
||
1. 环境准备：安装 PHP、MySQL、Composer、Node.js 等基础软件。
|
||
2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包并解压。
|
||
3. 后端启动：安装 Composer 依赖、配置环境变量、初始化数据库、启动后端服务。
|
||
4. 前端启动：安装前端依赖、启动前端开发服务器。
|
||
5. 功能验证：登录系统，验证各功能模块是否正常。
|
||
6. 新增模块：以 example 模块为例，演示如何新增一个完整的业务模块。
|
||
```
|
||
|
||
## 第一步：环境准备
|
||
|
||
确保电脑上已安装以下软件：
|
||
|
||
| 软件 | 版本要求 | 用途 |
|
||
|------|----------|------|
|
||
| PHP | 8.2+ | 后端运行环境 |
|
||
| MySQL | 8.0+ | 数据库（也支持 PostgreSQL、SQL Server、Oracle、SQLite） |
|
||
| Composer | 2.x | PHP 依赖管理 |
|
||
| Node.js | 22+ | 前端构建环境 |
|
||
| pnpm | 12+ | 前端包管理器 |
|
||
|
||
:::tip 温馨提示
|
||
详细的安装步骤请参考 [开发环境准备](/zh/quickstart/environment.html) 章节。
|
||
:::
|
||
|
||
## 第二步：获取源码
|
||
|
||
前往 [官方网站](https://www.rxthink.cn) 购买授权后，按以下步骤获取源码：
|
||
|
||
```text
|
||
1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
|
||
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
|
||
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
|
||
4. 将压缩包解压到本地开发目录（如 D:\xampp\htdocs\ 或 ~/www/）。
|
||
```
|
||
|
||
```bash
|
||
# 进入项目目录（以实际解压路径为准）
|
||
cd thinkphp6
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. 源码包请务必从[官方网站](https://www.rxthink.cn)订单中心下载，确保获取的是正版授权的最新版本。
|
||
2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
|
||
3. 解压后请先阅读根目录下的 `README.md` 和 `CHANGELOG.md` 了解版本更新内容。
|
||
:::
|
||
|
||
## 第三步：后端启动
|
||
|
||
### 3.1 安装 Composer 依赖
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 安装项目依赖（从 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
|
||
```
|
||
|
||
编辑 `.env` 文件，配置数据库连接信息：
|
||
|
||
```ini
|
||
; 开启调试模式（开发环境 true，生产环境必须 false）
|
||
APP_DEBUG = true
|
||
|
||
; 数据库配置
|
||
[DATABASE]
|
||
TYPE = mysql ; 数据库类型
|
||
HOSTNAME = 127.0.0.1 ; 数据库地址
|
||
DATABASE = rxthinkcmf.thinkphp6.elevue ; 数据库名
|
||
USERNAME = root ; 用户名
|
||
PASSWORD = root ; 密码
|
||
HOSTPORT = 3306 ; 端口
|
||
CHARSET = utf8mb4 ; 字符集（支持 emoji）
|
||
PREFIX = think_ ; 表前缀
|
||
|
||
; JWT 密钥配置（生产环境务必修改为强随机字符串）
|
||
[JWT]
|
||
SECRET = rxthinkcmf_jwt_secret_key_2024 ; 签名密钥
|
||
ACCESS_TTL = 7200 ; access_token 有效期（秒）
|
||
REFRESH_TTL = 604800 ; refresh_token 有效期（秒）
|
||
|
||
; 文件上传配置
|
||
[FILE]
|
||
UPLOAD_DIR = D:/uploads/rxthinkcmf ; 上传目录（绝对路径）
|
||
DOMAIN_URL = http://file.thinkphp6.elevue ; 文件访问域名
|
||
```
|
||
|
||
:::danger 重要提示
|
||
1. `.env` 使用 INI 分组格式，`[DATABASE]` 下的 `DATABASE` 是数据库名称，需提前在 MySQL 中创建。
|
||
2. `[JWT]` 下的 `SECRET` 生产环境务必修改为强随机字符串，生成方式：`php -r "echo bin2hex(random_bytes(32));"`
|
||
3. `[FILE]` 下的 `UPLOAD_DIR` 需使用绝对路径，确保目录存在且有写入权限。
|
||
:::
|
||
|
||
### 3.3 初始化数据库
|
||
|
||
**方式一：导入 SQL 脚本（推荐）**
|
||
|
||
项目为每种数据库提供了独立的 SQL 脚本，存放在 `document/` 目录下：
|
||
|
||
```text
|
||
document/
|
||
├── mysql/rxthinkcmf.thinkphp6.elevue.sql # MySQL 版本
|
||
├── postgresql/rxthinkcmf.thinkphp6.elevue.sql # PostgreSQL 版本
|
||
├── sqlserver/rxthinkcmf.thinkphp6.elevue.sql # SQL Server 版本
|
||
├── oracle/rxthinkcmf.thinkphp6.elevue.sql # Oracle 版本
|
||
└── sqlite/rxthinkcmf.thinkphp6.elevue.sql # SQLite 版本
|
||
```
|
||
|
||
以 MySQL 为例：
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 第 1 步：登录 MySQL，创建数据库
|
||
# -----------------------------------------------------------------------------
|
||
# -uroot -p → 以 root 用户连接，-p 交互式输入密码
|
||
mysql -uroot -p
|
||
|
||
# 在 MySQL 命令行中执行（创建项目数据库）：
|
||
# CHARACTER SET utf8mb4 → 支持 emoji 等四字节字符
|
||
# COLLATE utf8mb4_general_ci → 不区分大小写的排序规则
|
||
CREATE DATABASE `rxthinkcmf.thinkphp6.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
||
|
||
# -----------------------------------------------------------------------------
|
||
# 第 2 步：导入数据库脚本
|
||
# -----------------------------------------------------------------------------
|
||
# -uroot -proot → 用户名和密码
|
||
# rxthinkcmf... → 目标数据库名
|
||
# < file.sql → 将 SQL 文件作为 mysql 命令的输入
|
||
mysql -uroot -proot rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.sql
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
项目支持 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 五种数据库。请根据你使用的数据库类型选择对应的脚本导入。详细的多数据库初始化步骤请参考 [数据库初始化](/zh/quickstart/database-init.html) 章节。
|
||
:::
|
||
|
||
初始化完成后，数据库中包含以下默认数据：
|
||
|
||
```text
|
||
管理员账号：admin / 123456（超级管理员，ID=1，跳过权限校验）
|
||
默认角色：超级管理员角色
|
||
默认菜单：系统管理、内容管理、监控管理等菜单及权限节点
|
||
数据字典：系统内置字典数据
|
||
系统配置：系统默认配置项
|
||
城市数据：全国行政区划数据
|
||
```
|
||
|
||
### 3.4 启动后端服务
|
||
|
||
```bash
|
||
# -----------------------------------------------------------------------------
|
||
# 使用 ThinkPHP 内置开发服务器（默认监听 127.0.0.1:8000）
|
||
# -----------------------------------------------------------------------------
|
||
php think run
|
||
```
|
||
|
||
启动成功后会看到：
|
||
|
||
```html
|
||
ThinkPHP Development server is started
|
||
<http://0.0.0.0:8000>
|
||
You can exit with `CTRL-C`
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
打开浏览器访问 `http://localhost:8000/` 可验证后端服务是否正常启动。
|
||
:::
|
||
|
||
## 第四步：前端启动
|
||
|
||
### 4.1 安装前端依赖
|
||
|
||
```bash
|
||
# 进入前端项目目录
|
||
cd ui
|
||
|
||
# 安装依赖（从 pnpm-lock.yaml 精确安装）
|
||
pnpm install
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
如果安装速度较慢，可配置国内镜像源：
|
||
```bash
|
||
# 配置 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.config.ts` 中配置了代理，前端请求 `/api/*` 路径时自动转发到后端 `http://admin.thinkphp6.elevue/api/`。
|
||
:::
|
||
|
||
## 第五步：功能验证
|
||
|
||
登录成功后，可以验证以下核心功能：
|
||
|
||
```text
|
||
1. 控制台：首页仪表盘，显示系统概况。
|
||
2. 用户管理：系统管理 → 用户管理，查看用户列表、新增、编辑、删除。
|
||
3. 角色管理：系统管理 → 角色管理，管理角色和权限分配。
|
||
4. 菜单管理：系统管理 → 菜单管理，管理菜单和权限节点。
|
||
5. 数据字典：数据管理 → 字典管理，管理系统字典数据。
|
||
6. 操作日志：系统管理 → 日志管理 → 操作日志，查看操作记录。
|
||
7. 代码生成：开发工具 → 代码生成，体验代码生成功能。
|
||
```
|
||
|
||
## 第六步：新增业务模块
|
||
|
||
以项目内置的「案例演示」模块为例，演示如何新增一个完整的 CRUD 模块。
|
||
|
||
### 6.1 数据库建表
|
||
|
||
```sql
|
||
-- =============================================================================
|
||
-- 创建案例演示表
|
||
-- =============================================================================
|
||
-- 表前缀 think_ 由 .env 中 DATABASE.PREFIX 决定
|
||
-- BaseModel 会自动管理 create_time / update_time / create_user / update_user
|
||
-- =============================================================================
|
||
|
||
CREATE TABLE think_example (
|
||
id INT PRIMARY KEY AUTO_INCREMENT, -- 主键，自增
|
||
name VARCHAR(200) NOT NULL COMMENT '案例名称', -- 业务字段
|
||
type TINYINT(1) DEFAULT 0 COMMENT '案例类型', -- 字典字段（example_type）
|
||
status TINYINT(1) DEFAULT 0 COMMENT '案例状态', -- 字典字段（example_status）
|
||
sort INT DEFAULT 0 COMMENT '排序', -- 排序值（升序）
|
||
avatar VARCHAR(500) DEFAULT '' COMMENT '头像', -- 文件字段
|
||
is_delete TINYINT(1) DEFAULT 0, -- 软删除标记（0=正常，1=已删除）
|
||
create_user VARCHAR(50) DEFAULT '', -- 创建人（BaseModel 自动写入）
|
||
create_time DATETIME, -- 创建时间（BaseModel 自动写入）
|
||
update_user VARCHAR(50) DEFAULT '', -- 更新人（BaseModel 自动写入）
|
||
update_time DATETIME -- 更新时间（BaseModel 自动写入）
|
||
);
|
||
```
|
||
|
||
### 6.2 后端开发
|
||
|
||
**Model** — `app/model/Example.php`：
|
||
|
||
```php
|
||
<?php
|
||
namespace app\model;
|
||
use app\BaseModel;
|
||
|
||
/**
|
||
* 案例模型
|
||
* 继承 BaseModel 自动获得软删除、时间戳、创建人等功能
|
||
*/
|
||
class Example extends BaseModel
|
||
{
|
||
/**
|
||
* 对应数据库表名（不含前缀）
|
||
*
|
||
* @var string
|
||
*/
|
||
protected $name = 'example';
|
||
}
|
||
```
|
||
|
||
**Validate** — `app/validate/ExampleValidate.php`：
|
||
|
||
```php
|
||
<?php
|
||
namespace app\validate;
|
||
use think\Validate;
|
||
|
||
/**
|
||
* 案例验证器
|
||
* 定义字段验证规则和场景
|
||
*/
|
||
class ExampleValidate extends Validate
|
||
{
|
||
/**
|
||
* 验证规则
|
||
*
|
||
* name 字段必填
|
||
*
|
||
* @var array
|
||
*/
|
||
protected $rule = ['name' => 'require'];
|
||
|
||
/**
|
||
* 自定义错误提示
|
||
*
|
||
* @var array
|
||
*/
|
||
protected $message = ['name.require' => '请输入案例名称'];
|
||
|
||
/**
|
||
* 验证场景
|
||
*
|
||
* add 和 update 场景都验证 name
|
||
*
|
||
* @var array
|
||
*/
|
||
protected $scene = ['add' => ['name'], 'update' => ['name']];
|
||
}
|
||
```
|
||
|
||
**Logic** — `app/logic/ExampleLogic.php`：
|
||
|
||
```php
|
||
<?php
|
||
namespace app\logic;
|
||
use app\BaseLogic;
|
||
use app\model\Example;
|
||
|
||
/**
|
||
* 案例业务逻辑
|
||
* 继承 BaseLogic 自动获得分页、新增、更新、删除、详情等基础 CRUD
|
||
*/
|
||
class ExampleLogic extends BaseLogic
|
||
{
|
||
/**
|
||
* 关联的模型类
|
||
*
|
||
* @var string
|
||
*/
|
||
protected string $modelClass = Example::class;
|
||
|
||
/**
|
||
* 需要自动处理的文件上传字段
|
||
*
|
||
* @var array
|
||
*/
|
||
protected array $fileFields = ['avatar'];
|
||
|
||
/**
|
||
* 文件保存的子目录
|
||
*
|
||
* @var string
|
||
*/
|
||
protected string $fileSaveDir = 'example';
|
||
|
||
/**
|
||
* LIKE 模糊匹配字段
|
||
*
|
||
* @var array
|
||
*/
|
||
protected array $pageLikeFields = ['name'];
|
||
|
||
/**
|
||
* 精确匹配字段
|
||
*
|
||
* @var array
|
||
*/
|
||
protected array $pageEqFields = ['type', 'status'];
|
||
|
||
/**
|
||
* 默认排序规则
|
||
*
|
||
* @var array
|
||
*/
|
||
protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];
|
||
|
||
/**
|
||
* 枚举显示名映射
|
||
*
|
||
* @var array
|
||
*/
|
||
protected array $serializeMaps = [
|
||
'type' => 'example_type',
|
||
'status' => 'example_status',
|
||
];
|
||
}
|
||
```
|
||
|
||
**Controller** — `app/controller/ExampleController.php`：
|
||
|
||
```php
|
||
<?php
|
||
namespace app\controller;
|
||
use app\BaseController;
|
||
use app\logic\ExampleLogic;
|
||
use app\attribute\Log; // 操作日志注解
|
||
use app\attribute\Permission; // 权限注解
|
||
use think\response\Json;
|
||
|
||
/**
|
||
* 案例控制器
|
||
* 定义 API 路由对应的处理方法
|
||
*/
|
||
class ExampleController extends BaseController
|
||
{
|
||
protected ExampleLogic $logic;
|
||
|
||
protected function initialize(): void
|
||
{
|
||
$this->logic = new ExampleLogic(); // 初始化业务逻辑层
|
||
}
|
||
|
||
// #[Log] 注解：自动记录操作日志
|
||
// #[Permission] 注解：自动校验用户权限
|
||
#[Log('案例演示-查询分页', Log::TYPE_QUERY)]
|
||
#[Permission('sys:example:page', '案例分页')]
|
||
public function page(): Json
|
||
{
|
||
return parent::_index($this->logic); // 调用父类分页方法
|
||
}
|
||
|
||
#[Log('案例演示-新增', Log::TYPE_ADD, '新增案例：{name}')]
|
||
#[Permission('sys:example:add', '添加案例')]
|
||
public function add(): Json
|
||
{
|
||
return parent::_add($this->logic, $this->getJsonBody()); // 调用父类新增方法
|
||
}
|
||
|
||
// ... 其他 CRUD 方法
|
||
}
|
||
```
|
||
|
||
### 6.3 注册路由
|
||
|
||
在 `route/app.php` 中添加：
|
||
|
||
```php
|
||
// 案例演示模块路由（RESTful 风格）
|
||
Route::group('example', function () {
|
||
Route::get('page', 'ExampleController/page'); // 分页查询
|
||
Route::get('detail/:id', 'ExampleController/detail'); // 详情（路径参数）
|
||
Route::post('add', 'ExampleController/add'); // 新增
|
||
Route::put('update', 'ExampleController/update'); // 更新
|
||
Route::delete('delete/:id', 'ExampleController/delete'); // 删除单条
|
||
Route::delete('batchDelete', 'ExampleController/batchDelete'); // 批量删除
|
||
});
|
||
```
|
||
|
||
### 6.4 前端开发
|
||
|
||
在 `ui/src/api/tool/example.ts` 中定义接口，在 `ui/src/views/tool/example/` 中创建页面文件。
|
||
|
||
### 6.5 配置菜单权限
|
||
|
||
在系统管理 → 菜单管理中：
|
||
|
||
```text
|
||
1. 新增菜单：案例演示（路径：/example，组件：tool/example/index）
|
||
2. 新增按钮：查看（sys:example:page）、新增（sys:example:add）、编辑（sys:example:update）、删除（sys:example:delete）
|
||
3. 在角色管理中为角色分配"案例演示"菜单权限
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
也可以使用代码生成器一键生成以上所有代码，详见 [代码生成器](/zh/generator/overview.html) 章节。
|
||
:::
|
||
|
||
## 常见问题
|
||
|
||
在部署和使用过程中，可能会遇到以下常见问题：
|
||
|
||
```text
|
||
1. 端口被占用：执行 php think run --port 8080 更换端口。
|
||
2. 数据库连接失败：检查 .env 中的数据库配置，确认 MySQL 服务已启动。
|
||
3. PHP 扩展缺失：运行 php -m 检查 pdo_mysql、mbstring、gd 等扩展。
|
||
4. Composer 安装慢：配置国内镜像 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
|
||
5. pnpm install 失败：配置国内镜像 pnpm config set registry https://registry.npmmirror.com。
|
||
6. 前端白屏：检查后端服务是否启动，浏览器控制台是否有报错。
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
更多问题请参考 [常见问题FAQ](/zh/quickstart/faq.html) 章节。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
通过以上步骤，你已经完成了从零搭建一个完整的后台管理系统的全过程：
|
||
|
||
```text
|
||
1. 环境准备：PHP 8.2 + MySQL 8.0 + Composer 2.x + Node.js 22 + pnpm
|
||
2. 获取源码：从[官方网站](https://www.rxthink.cn)下载授权源码包
|
||
3. 后端启动：composer install → 配置 .env → 导入数据库 → php think run
|
||
4. 前端启动：pnpm install → pnpm dev
|
||
5. 功能验证：登录系统，验证各模块功能
|
||
6. 新增模块：Model → Validate → Logic → Controller → Route → 前端页面 → 菜单权限
|
||
```
|
||
|
||
整个搭建过程约 30 分钟即可完成。如果在操作过程中遇到问题，请查阅文档或在社区寻求帮助。
|