rxthinkcmf/rxthinkcmf-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
gitadmin
2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/backend-start.md
+196
View File
@@ -0,0 +1,196 @@
# 2.2 后端服务启动
:::warning 特别提醒
官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
:::
## 步骤一：获取源码
前往 [官方网站](https://www.rxthink.cn) 购买授权后，按以下步骤获取源码：
```text
1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 D:\xampp8.2\htdocs\ 或 ~/www/）。
```
```bash
# 进入项目目录（以实际解压路径为准）
cd thinkphp6
```
:::tip 温馨提示
1. 源码包请务必从[官方网站](https://www.rxthink.cn)订单中心下载，确保获取的是正版授权的最新版本。
2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
3. 解压后请先阅读根目录下的 `README.md` 和 `CHANGELOG.md` 了解版本更新内容。
:::
## 步骤二：安装 Composer 依赖
```bash
# -----------------------------------------------------------------------------
# 安装项目依赖（从 composer.lock 精确安装，确保版本一致）
# -----------------------------------------------------------------------------
# install → 读取 composer.lock，安装锁定版本的依赖
# 安装完成后生成 vendor/ 目录，包含所有第三方库
composer install
# -----------------------------------------------------------------------------
# 如果国内下载慢，先配置阿里云镜像（加速依赖下载）
# -----------------------------------------------------------------------------
# config -g → 修改全局配置（所有项目生效）
# repo.packagist → 设置 Packagist 仓库的镜像地址
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
composer install
```
安装完成后，项目根目录会生成 `vendor/` 目录，包含所有第三方依赖。
## 步骤三：配置环境文件
```bash
# 复制环境配置模板（.env.example 是模板文件，.env 是实际配置）
cp .env.example .env
```
编辑 `.env` 文件，配置数据库连接等信息：
```ini
; 开启调试模式（开发环境 true，生产环境必须 false）
APP_DEBUG = true
; 数据库连接配置
[DATABASE]
TYPE = mysql ; 数据库类型（mysql / pgsql / sqlsrv / oracle / sqlite）
HOSTNAME = 127.0.0.1 ; 数据库服务器地址
DATABASE = rxthinkcmf.thinkphp6.elevue ; 数据库名称
USERNAME = root ; 数据库用户名
PASSWORD = root ; 数据库密码
HOSTPORT = 3306 ; 数据库端口
PREFIX = think_ ; 表前缀
; JWT 签名密钥（生产环境务必修改为强随机字符串）
[JWT]
SECRET = rxthinkcmf_jwt_secret_key_2024
; 文件上传配置
[FILE]
UPLOAD_DIR = D:/uploads/rxthinkcmf ; 上传文件存储目录（绝对路径）
DOMAIN_URL = http://file.thinkphp6.elevue ; 文件访问域名
```
:::danger 生产环境务必修改
1. `[JWT]` 下的 `SECRET` 必须修改为强随机字符串，生成方式：`php -r "echo bin2hex(random_bytes(32));"`
2. `APP_DEBUG` 生产环境必须设为 `false`
3. `[DATABASE]` 下的 `PASSWORD` 必须修改为强密码
:::
## 步骤四：启动内置开发服务器
ThinkPHP 内置了 PHP 开发服务器，无需安装 Nginx/Apache 即可启动：
```bash
# -----------------------------------------------------------------------------
# 启动开发服务器（默认监听 127.0.0.1:8000）
# -----------------------------------------------------------------------------
# run → 启动 ThinkPHP 内置的 PHP 开发服务器
# 启动后浏览器访问 http://localhost:8000 即可
php think run
# -----------------------------------------------------------------------------
# 指定端口（当 8000 被占用时更换端口）
# -----------------------------------------------------------------------------
# --port → 指定监听端口
php think run --port 8080
# -----------------------------------------------------------------------------
# 指定主机和端口（允许局域网其他设备访问）
# -----------------------------------------------------------------------------
# --host 0.0.0.0 → 监听所有网络接口（默认只监听 127.0.0.1）
# 适用于手机调试、前后端分离开发等场景
php think run --host 0.0.0.0 --port 8000
```
启动成功后会看到：
```html
ThinkPHP Development server is started
<http://0.0.0.0:8000>
You can exit with `CTRL-C`
```
## 步骤五：验证服务
```bash
# -----------------------------------------------------------------------------
# 访问根路径，确认服务正常运行
# -----------------------------------------------------------------------------
# curl → 命令行 HTTP 客户端工具
# 正常响应：{"code":200,"msg":"RxThinkCMF API Server","data":{"version":"1.0.0"}}
curl http://localhost:8000/
# -----------------------------------------------------------------------------
# 测试登录接口（POST 请求 + JSON 请求体）
# -----------------------------------------------------------------------------
# -X POST → 使用 POST 方法
# -H → 设置请求头（Content-Type: application/json）
# -d → 发送 JSON 格式的请求体
curl -X POST http://localhost:8000/api/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456"}'
# 测试租户账号登录
curl -X POST http://localhost:8000/api/login \
-H "Content-Type: application/json" \
-d '{"username":"tenant001","password":"123456"}'
```
:::tip 内置演示账号
| 账号 | 密码 | 角色 | 说明 |
|------|------|------|------|
| admin | 123456 | 超级管理员 | 平台管理，可管理所有租户 |
| tenant001 | 123456 | 租户管理员（客户租户A） | 租户视角，体验数据隔离效果 |
:::
## 常见问题
### 1. `composer install` 报错内存不足
```bash
# -d memory_limit=-1 → 取消 PHP 内存限制（-1 表示无限制）
php -d memory_limit=-1 /usr/local/bin/composer install
```
### 2. `vendor/` 目录权限问题
```bash
# 755 → owner 可读写执行，group/others 可读可执行
chmod -R 755 vendor/
```
### 3. 数据库连接失败
检查 `.env` 中的数据库配置是否正确：
```bash
# 1. 检查 .env 中 [DATABASE] 配置：HOSTNAME、PORT、USERNAME、PASSWORD、DATABASE 是否正确
# 2. 确认数据库服务已启动
# 3. 用原生 SQL 测试连接是否正常（以 MySQL 为例）
mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT 1;"
```
### 4. 端口被占用
```bash
# Windows：查找占用 8000 端口的进程
# findstr → Windows 版的 grep（过滤文本）
netstat -ano | findstr :8000
# macOS / Linux：查找占用 8000 端口的进程
# -i :8000 → 只显示使用 8000 端口的进程
lsof -i :8000
# 更换端口启动（避免冲突）
php think run --port 8080
```
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/database-init.md
+372
View File
@@ -0,0 +1,372 @@
# 2.4 数据库初始化
:::tip 概述
本章指导您完成数据库的创建和 SQL 脚本导入。项目为每种数据库提供了独立的 SQL 脚本，存放在 `document/` 目录下按数据库类型分组。
:::
## SQL 脚本目录结构
```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 版本
```
各数据库脚本已针对对应的 SQL 语法做了适配，可直接导入使用，无需手动转换。
---
## MySQL 初始化
### 1. 创建数据库
```bash
# 连接 MySQL（-u root 以 root 用户，-p 交互式输入密码）
mysql -u root -p
```
```sql
-- 创建项目数据库
-- CHARACTER SET utf8mb4 → 支持 emoji 等四字节字符
-- COLLATE utf8mb4_general_ci → 不区分大小写的排序规则
CREATE DATABASE `rxthinkcmf.thinkphp6.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
EXIT;
```
### 2. 导入 SQL 脚本
```bash
# -----------------------------------------------------------------------------
# 导入 MySQL 专用初始化脚本
# -----------------------------------------------------------------------------
# -u root -proot → 数据库用户名和密码
# rxthinkcmf... → 目标数据库名
# < file.sql → 将 SQL 文件内容作为 mysql 命令的输入
mysql -u root -proot rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.sql
```
:::tip 温馨提示
导入完成后，数据库中包含完整的表结构和初始数据（管理员账号、菜单、字典、城市数据等），可直接使用。
:::
### 3. 配置 .env
```ini
[DATABASE]
TYPE = mysql ; 数据库类型
HOSTNAME = 127.0.0.1 ; 数据库地址
DATABASE = rxthinkcmf.thinkphp6.elevue ; 数据库名
USERNAME = root ; 用户名
PASSWORD = root ; 密码
HOSTPORT = 3306 ; 端口
PREFIX = think_ ; 表前缀
```
---
## PostgreSQL 初始化
### 1. 创建数据库
```bash
# 以 postgres 系统用户身份进入 PostgreSQL 命令行
sudo -u postgres psql
```
```sql
-- 创建数据库用户（如已存在可跳过）
CREATE USER postgres WITH PASSWORD 'root';
-- 创建项目数据库
-- OWNER postgres → 指定数据库所有者
-- ENCODING 'UTF8' → 使用 UTF-8 编码
CREATE DATABASE "rxthinkcmf.thinkphp6.elevue" OWNER postgres ENCODING 'UTF8';
-- 授予用户对该数据库的所有权限
GRANT ALL PRIVILEGES ON DATABASE "rxthinkcmf.thinkphp6.elevue" TO postgres;
\q
```
### 2. 导入 SQL 脚本
```bash
# -----------------------------------------------------------------------------
# 导入 PostgreSQL 专用初始化脚本
# -----------------------------------------------------------------------------
# -U postgres → 连接用户
# -d ... → 目标数据库
# -f file.sql → 执行 SQL 文件
psql -U postgres -d rxthinkcmf.thinkphp6.elevue -f document/postgresql/rxthinkcmf.thinkphp6.elevue.sql
```
### 3. 配置 .env
```ini
[DATABASE]
TYPE = pgsql ; 数据库类型改为 pgsql
HOSTNAME = 127.0.0.1
DATABASE = rxthinkcmf.thinkphp6.elevue
USERNAME = postgres ; PostgreSQL 默认用户
PASSWORD = root
HOSTPORT = 5432 ; PostgreSQL 默认端口
PREFIX = think_
```
---
## SQLite 初始化
### 1. 创建数据库文件
```bash
# 安装 PHP 的 SQLite 扩展（如尚未安装）
sudo apt install php8.2-sqlite3
# 创建数据库文件存放目录（-p 参数：目录不存在时自动创建）
mkdir -p /www/api/runtime
# 创建空的 SQLite 数据库文件（touch 创建空文件）
touch /www/api/runtime/database.sqlite
```
### 2. 导入 SQL 脚本
```bash
# -----------------------------------------------------------------------------
# 导入 SQLite 专用初始化脚本
# -----------------------------------------------------------------------------
# sqlite3 → SQLite 命令行工具
# 数据库文件路径 → SQLite 数据库存储在单个文件中
# < file.sql → 将 SQL 文件作为输入执行
sqlite3 /www/api/runtime/database.sqlite < document/sqlite/rxthinkcmf.thinkphp6.elevue.sql
```
### 3. 配置 .env
```ini
[DATABASE]
TYPE = sqlite ; 数据库类型改为 sqlite
DATABASE = /www/api/runtime/database.sqlite ; SQLite 文件路径
PREFIX = think_
```
:::tip SQLite 特点
- 无需安装数据库服务器，数据存储在单个文件中
- 适合开发环境、小型项目或嵌入式场景
- 文件路径需确保 PHP 进程有读写权限
:::
---
## SQL Server 初始化
### 1. 创建数据库
```bash
# -----------------------------------------------------------------------------
# 使用 sqlcmd 创建数据库
# -----------------------------------------------------------------------------
# -S localhost → 服务器地址
# -U sa → 用户名（sa 为 SQL Server 管理员）
# -P root → 密码
# -Q → 执行 SQL 查询后退出
# COLLATE Chinese_PRC_CI_AS → 中文排序规则（不区分大小写）
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.thinkphp6.elevue] COLLATE Chinese_PRC_CI_AS"
```
### 2. 导入 SQL 脚本
```bash
# -----------------------------------------------------------------------------
# 导入 SQL Server 专用初始化脚本
# -----------------------------------------------------------------------------
# -d rxthinkcmf... → 目标数据库
# -i file.sql → 执行 SQL 文件
sqlcmd -S localhost -U sa -P root -d rxthinkcmf.thinkphp6.elevue -i document/sqlserver/rxthinkcmf.thinkphp6.elevue.sql
```
### 3. 配置 .env
```ini
[DATABASE]
TYPE = sqlsrv ; 数据库类型改为 sqlsrv
HOSTNAME = 127.0.0.1
DATABASE = rxthinkcmf.thinkphp6.elevue
USERNAME = sa ; SQL Server 默认管理员
PASSWORD = root
HOSTPORT = 1433 ; SQL Server 默认端口
PREFIX = think_
```
---
## Oracle 初始化
### 1. 创建表空间和用户
```sql
-- 使用 sqlplus 连接 Oracle（system 为管理员用户，XE 为服务名）
sqlplus system/root@localhost:1521/XE
-- 创建表空间（Oracle 数据存储的逻辑单元）
-- DATAFILE → 数据文件的物理路径
-- SIZE 100M → 初始大小 100MB
-- AUTOEXTEND ON NEXT 100M → 空间不足时自动扩展 100MB
CREATE TABLESPACE "rxthinkcmf_thinkphp6_elevue"
DATAFILE '/u01/oradata/rxthinkcmf_thinkphp6_elevue.dbf'
SIZE 100M AUTOEXTEND ON NEXT 100M;
-- 创建数据库用户
-- IDENTIFIED BY → 设置密码
-- DEFAULT TABLESPACE → 指定默认表空间
CREATE USER "root" IDENTIFIED BY "root"
DEFAULT TABLESPACE "rxthinkcmf_thinkphp6_elevue";
-- 授权
-- CONNECT → 连接权限
-- RESOURCE → 创建表/视图等对象的权限
-- CREATE VIEW → 创建视图的权限
-- UNLIMITED TABLESPACE → 不限制表空间使用量
GRANT CONNECT, RESOURCE, CREATE VIEW TO "root";
GRANT UNLIMITED TABLESPACE TO "root";
EXIT;
```
### 2. 导入 SQL 脚本
```bash
# -----------------------------------------------------------------------------
# 导入 Oracle 专用初始化脚本
# -----------------------------------------------------------------------------
# sqlplus → Oracle 命令行工具
# root/root@localhost:1521/XE → 用户/密码@主机:端口/服务名
# @file.sql → 执行 SQL 文件
sqlplus root/root@localhost:1521/XE @document/oracle/rxthinkcmf.thinkphp6.elevue.sql
```
### 3. 配置 .env
```ini
[DATABASE]
TYPE = oracle ; 数据库类型改为 oracle
HOSTNAME = 127.0.0.1
DATABASE = rxthinkcmf.thinkphp6.elevue
USERNAME = root
PASSWORD = root
HOSTPORT = 1521 ; Oracle 默认端口
PREFIX = think_
```
---
## 验证数据库
无论使用哪种数据库，都可以通过以下方式验证：
```bash
# 方式一：ThinkPHP 命令行（显示版本信息，验证框架可正常加载）
php think version
# 方式二：手动测试登录接口（POST 请求 + JSON 参数）
curl http://localhost:8000/api/login -X POST \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456"}'
```
各数据库直接查询验证：
```bash
# -----------------------------------------------------------------------------
# MySQL：查询用户表记录数（验证表是否创建成功且有数据）
# -----------------------------------------------------------------------------
# -e → 执行 SQL 后退出
mysql -u root -proot rxthinkcmf.thinkphp6.elevue -e "SELECT COUNT(*) FROM think_user;"
# -----------------------------------------------------------------------------
# PostgreSQL：查询用户表记录数
# -----------------------------------------------------------------------------
# -c → 执行 SQL 命令
psql -U postgres -d rxthinkcmf.thinkphp6.elevue -c "SELECT COUNT(*) FROM think_user;"
# -----------------------------------------------------------------------------
# SQLite：查询用户表记录数
# -----------------------------------------------------------------------------
sqlite3 /www/api/runtime/database.sqlite "SELECT COUNT(*) FROM think_user;"
# -----------------------------------------------------------------------------
# SQL Server：查询用户表记录数
# -----------------------------------------------------------------------------
# -Q → 执行查询后退出
sqlcmd -S localhost -U sa -P root -d rxthinkcmf.thinkphp6.elevue -Q "SELECT COUNT(*) FROM think_user;"
# -----------------------------------------------------------------------------
# Oracle：查询用户表记录数（需先进入 SQL 命令行）
# -----------------------------------------------------------------------------
sqlplus root/root@localhost:1521/XE
SELECT COUNT(*) FROM think_user;
EXIT;
```
---
## 默认数据
导入完成后，系统包含以下初始数据：
| 数据 | 说明 |
|------|------|
| 管理员账号 | admin / 123456 |
| 默认角色 | 超级管理员（data_scope=1，全部数据权限） |
| 系统菜单 | 完整的菜单和权限节点数据 |
| 字典数据 | 性别、状态等基础字典 |
| 系统参数 | DEFAULT_PASSWORD 等系统参数 |
| 城市数据 | 全国行政区划数据 |
---
## 常见问题
### Q: 导入报错字符集问题（MySQL）
```bash
# --default-character-set=utf8mb4 → 指定字符集为 utf8mb4（支持 emoji）
mysql -u root -proot --default-character-set=utf8mb4 rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.sql
```
### Q: 表已存在错误
```bash
# -----------------------------------------------------------------------------
# 先删除旧数据库再重建（⚠️ 会清空所有数据）
# -----------------------------------------------------------------------------
# DROP DATABASE IF EXISTS → 如果存在则删除
mysql -u root -proot -e "DROP DATABASE IF EXISTS \`rxthinkcmf.thinkphp6.elevue\`;"
# 创建数据库（指定字符集）
mysql -u root -proot -e "CREATE DATABASE \`rxthinkcmf.thinkphp6.elevue\` DEFAULT CHARACTER SET utf8mb4;"
# 重新导入 SQL
mysql -u root -proot rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.sql
```
### Q: PostgreSQL 导入报错
确保使用 `document/postgresql/` 目录下的脚本，该脚本已针对 PostgreSQL 语法做了适配。
### Q: SQLite 文件权限问题
```bash
# 664 → owner/group 可读写，others 只读
chmod 664 /www/api/runtime/database.sqlite
# 修改文件所有者为 Web 服务器用户
chown www-data:www-data /www/api/runtime/database.sqlite
```
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/docker.md
+471
View File
@@ -0,0 +1,471 @@
# 2.7 Docker 快速体验
:::tip 概述
Docker 方案适合快速体验项目功能，无需手动安装 PHP、MySQL 等环境。本文提供完整的 Nginx + PHP-FPM 架构配置，复制即可使用。生产环境部署请参考[第 11 章](/zh/deploy/checklist.html)。
:::
## 架构说明
```
浏览器 → localhost:8000 → [Nginx 容器:80] → [PHP-FPM 容器:9000] → ThinkPHP
↕
[MySQL 容器:3306] + [Redis 容器:6379]
```
## 文件结构
```
thinkphp6/
├── docker-compose.yml # 容器编排（项目根目录）
├── docker/
│ ├── Dockerfile # PHP-FPM 镜像定义
│ ├── nginx.conf # Nginx 站点配置
│ └── .env.docker # 环境变量（密码等）
├── .env # 应用配置
└── ...
```
## 快速启动
项目已内置完整的 Docker 配置文件（`docker-compose.yml`、`docker/Dockerfile`、`docker/nginx.conf`），无需手动创建，直接启动即可：
```bash
# 从官方网站 (https://www.rxthink.cn) 下载授权源码包并解压
cd thinkphp6
# 配置应用环境变量
cp .env.example .env
# 编辑 .env，修改数据库连接地址为 Docker 服务名（见下方说明）
# 启动所有服务（首次会自动构建镜像，约 2-5 分钟）
docker-compose up -d
# 查看运行状态
docker-compose ps
# 查看日志（确认无报错）
docker-compose logs -f app
```
:::tip 说明
`docker-compose.yml` 使用 `${VAR:-默认值}` 语法，未配置 `.env.docker` 时自动使用默认密码（Your_Strong_Password_2024 / Your_Redis_Password_2024），适合快速体验。生产部署请参考[第 11 章](/zh/deploy/docker.html)使用 `--env-file` 指定生产密码。
:::
## docker-compose.yml
项目根目录的 `docker-compose.yml` 内容如下（供参考，无需手动创建）：
```yaml
# =============================================================================
# Docker Compose — RXThinkCMF 容器编排
# =============================================================================
# 架构：Nginx(80) → PHP-FPM(9000) → MySQL(3306) + Redis(6379)
#
# 快速启动（使用默认密码）：
# docker-compose up -d
#
# 生产部署（使用 .env.docker 中的密码）：
# docker-compose --env-file docker/.env.docker up -d --build
# =============================================================================
version: '3.8'
services:
# ===========================================================================
# Nginx 反向代理
# ===========================================================================
# 接收浏览器请求，静态资源直接返回，.php 请求转发给 PHP-FPM 容器
# ===========================================================================
nginx:
image: nginx:1.25-alpine
container_name: rxthinkcmf-nginx
ports:
- "${NGINX_PORT:-8000}:80" # 宿主机端口（默认 8000），可通过环境变量覆盖
volumes:
- ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro # 站点配置（只读）
- ./:/var/www/html:ro # 项目代码（只读）
depends_on:
- app
networks:
- rxthinkcmf-net
restart: unless-stopped
# ===========================================================================
# PHP-FPM 应用服务
# ===========================================================================
# 执行 ThinkPHP 代码，处理 API 请求和业务逻辑
# ===========================================================================
app:
build:
context: . # 构建上下文为项目根目录
dockerfile: docker/Dockerfile # Dockerfile 路径
container_name: rxthinkcmf-app
volumes:
- ./:/var/www/html # 项目代码（可写）
- uploads_data:/opt/data/uploads # 上传文件持久化
environment:
- APP_DEBUG=${APP_DEBUG:-true} # 调试模式（快速体验默认开启）
depends_on:
mysql:
condition: service_healthy # 等待 MySQL 就绪
redis:
condition: service_started # 等待 Redis 启动
networks:
- rxthinkcmf-net
restart: unless-stopped
# ===========================================================================
# MySQL 数据库
# ===========================================================================
# 存储业务数据，首次启动自动导入 init.sql
# ===========================================================================
mysql:
image: mysql:8.0
container_name: rxthinkcmf-mysql
ports:
- "${MYSQL_PORT:-3306}:3306" # 宿主机端口（默认 3306），可通过环境变量覆盖
environment:
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-Your_Strong_Password_2024} # root 密码
MYSQL_DATABASE: ${MYSQL_DATABASE:-rxthinkcmf.thinkphp6.elevue} # 自动创建的数据库
MYSQL_CHARSET: utf8mb4
MYSQL_COLLATION: utf8mb4_general_ci
volumes:
- mysql_data:/var/lib/mysql # 数据持久化
- ./document/mysql/rxthinkcmf.thinkphp6.elevue.sql:/docker-entrypoint-initdb.d/init.sql:ro # 初始化 SQL
command:
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_general_ci
- --default-authentication-plugin=mysql_native_password
healthcheck: # 健康检查：确保 MySQL 可接受连接
test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD:-Your_Strong_Password_2024}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s # MySQL 启动较慢，给 30 秒缓冲
networks:
- rxthinkcmf-net
restart: unless-stopped
# ===========================================================================
# Redis 缓存
# ===========================================================================
# 提供缓存加速，与 config/cache.php 中的 redis 驱动配合
# ===========================================================================
redis:
image: redis:7-alpine
container_name: rxthinkcmf-redis
ports:
- "${REDIS_PORT:-6379}:6379" # 宿主机端口（默认 6379），可通过环境变量覆盖
command: redis-server --requirepass ${REDIS_PASSWORD:-Your_Redis_Password_2024} # 访问密码
volumes:
- redis_data:/data # 数据持久化
networks:
- rxthinkcmf-net
restart: unless-stopped
# =============================================================================
# 命名卷 — 持久化存储
# =============================================================================
# 容器删除后数据保留，彻底重置请执行：docker-compose down -v
# =============================================================================
volumes:
mysql_data: # MySQL 数据文件
redis_data: # Redis RDB 快照
uploads_data: # 用户上传文件
# =============================================================================
# 内部网络
# =============================================================================
# 容器间通过服务名（mysql / redis / app）互相访问
# =============================================================================
networks:
rxthinkcmf-net:
driver: bridge
```
## Dockerfile
将以下内容保存为 `docker/Dockerfile`：
```dockerfile
# =============================================================================
# Dockerfile — PHP-FPM 应用镜像
# =============================================================================
# 基础镜像：PHP 8.2 + FPM
# 构建命令：docker-compose build app
# =============================================================================
FROM php:8.2-fpm
# -----------------------------------------------------------------------------
# 1. 安装系统依赖
# -----------------------------------------------------------------------------
RUN apt-get update && apt-get install -y --no-install-recommends \
libpng-dev \ # GD 扩展 — PNG 支持
libjpeg-dev \ # GD 扩展 — JPEG 支持
libfreetype6-dev \ # GD 扩展 — 字体渲染（验证码）
libzip-dev \ # zip 扩展依赖
zip \ # Composer 解压依赖
unzip \
&& rm -rf /var/lib/apt/lists/*
# -----------------------------------------------------------------------------
# 2. 安装 PHP 扩展
# -----------------------------------------------------------------------------
# pdo_mysql=MySQL驱动 mbstring=多字节 gd=图片 bcmath=高精度 zip=压缩 redis=缓存
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
&& docker-php-ext-install -j$(nproc) pdo_mysql mbstring gd bcmath zip \
&& pecl install redis \
&& docker-php-ext-enable redis
# -----------------------------------------------------------------------------
# 3. 安装 Composer
# -----------------------------------------------------------------------------
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
# -----------------------------------------------------------------------------
# 4. PHP 生产配置
# -----------------------------------------------------------------------------
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \
&& echo '\
date.timezone = Asia/Shanghai\n\
memory_limit = 256M\n\
upload_max_filesize = 50M\n\
post_max_size = 50M\n\
max_execution_time = 60\n\
opcache.enable = 1\n\
opcache.memory_consumption = 256\n\
' >> "$PHP_INI_DIR/php.ini"
# -----------------------------------------------------------------------------
# 5. 安装项目依赖
# -----------------------------------------------------------------------------
WORKDIR /var/www/html
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-interaction
COPY . .
# -----------------------------------------------------------------------------
# 6. 目录权限
# -----------------------------------------------------------------------------
RUN mkdir -p runtime uploads \
&& chown -R www-data:www-data runtime uploads \
&& chmod -R 775 runtime uploads
EXPOSE 9000
CMD ["php-fpm"]
```
## Nginx 配置
将以下内容保存为 `docker/nginx.conf`：
```nginx
# =============================================================================
# Nginx 配置 — ThinkPHP 6 反向代理
# =============================================================================
server {
listen 80;
server_name localhost;
# ThinkPHP 入口目录
root /var/www/html/public;
index index.php;
# URL 重写（ThinkPHP 路由必需）
location / {
if (!-e $request_filename) {
rewrite ^(.*)$ /index.php?s=$1 last;
}
}
# PHP-FPM 转发（"app" 是 docker-compose 中的服务名）
location ~ \.php$ {
fastcgi_pass app:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
fastcgi_read_timeout 300;
fastcgi_send_timeout 300;
}
# 安全：禁止访问隐藏文件
location ~ /\. {
deny all;
}
# 安全：禁止上传目录执行 PHP
location ~ /uploads/.*\.php$ {
deny all;
}
# 静态资源缓存 30 天
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
# Gzip 压缩
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;
gzip_min_length 1024;
gzip_comp_level 5;
}
```
## 环境变量配置
将以下内容保存为 `docker/.env.docker`：
```ini
# Docker 环境变量（密码等敏感信息，切勿提交 Git）
MYSQL_ROOT_PASSWORD=Your_Strong_Password_2024
MYSQL_DATABASE=rxthinkcmf.thinkphp6.elevue
REDIS_PASSWORD=Your_Redis_Password_2024
APP_DEBUG=false
```
修改项目根目录 `.env` 文件中的数据库和缓存连接：
```ini
[DATABASE]
; 连接地址（Docker 内部使用服务名 "mysql"）
HOSTNAME = mysql
PASSWORD = Your_Strong_Password_2024
[CACHE]
; 连接地址（Docker 内部使用服务名 "redis"）
REDIS_HOST = redis
REDIS_PASSWORD = Your_Redis_Password_2024
[FILE]
; 上传目录（容器内路径）
UPLOAD_DIR = /opt/data/uploads
```
## 访问服务
启动成功后：
| 服务 | 地址 | 说明 |
|------|------|------|
| 后端 API | http://localhost:8000 | Nginx → PHP-FPM → ThinkPHP |
| MySQL | localhost:3306 | 用户名 root，密码 Your_Strong_Password_2024 |
| Redis | localhost:6379 | 密码 Your_Redis_Password_2024 |
验证后端是否正常：
```bash
# 访问首页
curl http://localhost:8000/
# 登录获取 Token
curl -X POST http://localhost:8000/api/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456","captcha":"618618"}'
```
## 常用命令
```bash
# --------------------------------------------------------------------------
# 服务管理
# --------------------------------------------------------------------------
# 启动服务
docker-compose up -d
# 停止服务（保留数据）
docker-compose down
# 停止并清空所有数据（重新开始）
docker-compose down -v
# 重建镜像（Dockerfile 或 composer.json 变更后）
docker-compose up -d --build
# --------------------------------------------------------------------------
# 日志排查
# --------------------------------------------------------------------------
# 查看所有日志
docker-compose logs -f
# 查看应用日志
docker-compose logs -f app
# --------------------------------------------------------------------------
# 进入容器
# --------------------------------------------------------------------------
# 进入 PHP-FPM 容器
docker-compose exec app bash
# 进入 MySQL 容器
docker-compose exec mysql bash
# --------------------------------------------------------------------------
# 数据库操作
# --------------------------------------------------------------------------
# 导入 SQL（手动方式）
docker-compose exec -T mysql mysql -uroot -pYour_Strong_Password_2024 rxthinkcmf.thinkphp6.elevue < document/mysql/rxthinkcmf.thinkphp6.elevue.sql
# 进入 MySQL 命令行
docker-compose exec mysql mysql -uroot -pYour_Strong_Password_2024 rxthinkcmf.thinkphp6.elevue
# --------------------------------------------------------------------------
# ThinkPHP 命令
# --------------------------------------------------------------------------
# 清除缓存
docker-compose exec app php think clear
# 查看路由
docker-compose exec app php think route:list
```
## 常见问题
### 端口被占用
```bash
# Windows 查看占用端口的进程
netstat -ano | findstr :8000
# Linux/Mac
lsof -i :8000
# 解决方案：修改 docker-compose.yml 中的端口映射
# ports:
# - "8080:80" # 改为 8080
```
### 数据库连接失败
确认 `.env` 中 `[DATABASE]` 下 `HOSTNAME = mysql`（Docker 服务名），不是 `127.0.0.1`。
### 容器启动后立即退出
```bash
# 查看退出原因
docker-compose logs app
# 常见原因：
# 1. PHP 扩展缺失 → 检查 Dockerfile 中的 docker-php-ext-install
# 2. 目录权限问题 → 确认 runtime 和 uploads 目录可写
# 3. composer install 失败 → 检查网络或镜像源
```
### 重新开始
```bash
# 删除所有容器、网络、数据卷，完全重来
docker-compose down -v
docker-compose up -d --build
```
## 相关文档
- [生产部署](/zh/deploy/docker.html) — 生产环境完整方案
- [后端启动](/zh/quickstart/backend-start.html) — 不用 Docker，手动启动
- [数据库初始化](/zh/quickstart/database-init.html) — 手动导入 SQL
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/env-vars.md
+264
View File
@@ -0,0 +1,264 @@
# 2.5 环境变量配置
:::tip 概述
项目使用 `.env` 文件管理环境变量，支持开发、测试、生产等多环境切换。配置优先级：`.env` > `config/*.php` > 代码默认值。
:::
## .env 文件结构
项目 `.env` 文件采用 INI 分组格式，每个分组对应一个 `config/*.php` 配置文件：
```ini
; =============================================================================
; .env 环境变量配置文件
; =============================================================================
; 格式：INI 分组格式，[分组] 下的键值对通过 env() 函数读取
; 优先级：.env > config/*.php > 代码默认值
; =============================================================================
; 全局开关（不属于任何分组）
APP_DEBUG = true ; 调试模式（开发 true，生产 false）
[APP]
DEFAULT_TIMEZONE = Asia/Shanghai ; 默认时区
DEMO = false ; 演示模式（true=拦截所有写操作）
SHOW_ERROR_MSG = true ; 显示错误详情（生产环境设为 false）
[DATABASE]
TYPE = mysql ; 数据库类型（mysql / pgsql / sqlsrv / oracle / sqlite）
HOSTNAME = 127.0.0.1 ; 数据库服务器地址
DATABASE = rxthinkcmf.thinkphp6.elevue ; 数据库名
USERNAME = root ; 用户名
PASSWORD = root ; 密码
HOSTPORT = 3306 ; 端口
CHARSET = utf8mb4 ; 字符集（支持 emoji）
DEBUG = true ; SQL 调试（显示执行的 SQL 语句）
PREFIX = think_ ; 表前缀
[JWT]
SECRET = rxthinkcmf_jwt_secret_key_2024 ; 签名密钥（生产环境务必修改）
ACCESS_TTL = 7200 ; access_token 有效期（秒），默认 2 小时
REFRESH_TTL = 604800 ; refresh_token 有效期（秒），默认 7 天
ISSUER = rxthinkcmf ; 签发者标识
[FILE]
UPLOAD_DIR = D:/uploads/rxthinkcmf ; 上传根目录（绝对路径）
DOMAIN_URL = http://file.thinkphp6.elevue ; 文件访问域名
IMAGE_EXT = gif,jpg,jpeg,png,bmp,webp,svg ; 允许的图片后缀
FILE_EXT = gif,jpg,jpeg,png,bmp,webp,svg,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv,mp3,mp4,sql,js,css ; 允许的文件后缀
MAX_SIZE = 10 ; 单文件最大大小（MB）
[CACHE]
DRIVER = file ; 缓存驱动（file=文件，redis=Redis）
REDIS_HOST = 127.0.0.1 ; Redis 地址（driver=redis 时生效）
REDIS_PORT = 6379 ; Redis 端口
REDIS_PASSWORD = ; Redis 密码（无密码留空）
REDIS_DB = 0 ; Redis 数据库编号
REDIS_PREFIX = rx: ; 缓存键前缀
[CORS]
ALLOW_ORIGIN = * ; 允许的来源（* = 所有）
[API]
CAMEL_SNAKE_CONVERT = true ; 驼峰/下划线自动转换
[CAPTCHA]
CAPTCHA_BYPASS_CODE = ; 万能验证码（开发用，生产务必留空）
CAPTCHA_LENGTH = 6 ; 验证码字符长度（4-6位）
CAPTCHA_EXPIRE = 300 ; 验证码过期时间（秒）
[LANG]
default_lang = zh-cn ; 默认语言
```
## 配置项详解
### 应用配置 `[APP]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEFAULT_TIMEZONE` | `Asia/Shanghai` | 默认时区 |
| `DEMO` | `false` | 演示模式，开启后拦截所有写操作 |
| `SHOW_ERROR_MSG` | `true` | 是否显示错误详情，生产环境设为 `false` |
全局变量（不属于任何分组）：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_DEBUG` | `true` | 调试模式，生产环境设为 `false` |
### 数据库配置 `[DATABASE]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `TYPE` | `mysql` | 数据库类型：mysql / pgsql / sqlsrv / oracle / sqlite |
| `HOSTNAME` | `127.0.0.1` | 数据库主机 |
| `DATABASE` | - | 数据库名称（SQLite 为文件路径） |
| `USERNAME` | `root` | 数据库用户名 |
| `PASSWORD` | - | 数据库密码 |
| `HOSTPORT` | `3306` | 数据库端口 |
| `CHARSET` | `utf8mb4` | 字符集 |
| `DEBUG` | `true` | 是否开启 SQL 调试 |
| `PREFIX` | `think_` | 表前缀 |
### JWT 配置 `[JWT]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET` | 内置默认值 | 签名密钥，**生产环境务必修改** |
| `ACCESS_TTL` | `7200` | access_token 有效期（秒），默认 2 小时 |
| `REFRESH_TTL` | `604800` | refresh_token 有效期（秒），默认 7 天 |
| `ISSUER` | `rxthinkcmf` | 签发者标识 |
### 文件上传配置 `[FILE]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `UPLOAD_DIR` | - | 上传根目录（绝对路径） |
| `DOMAIN_URL` | - | 文件访问域名 |
| `IMAGE_EXT` | `gif,jpg,jpeg,png,bmp,webp,svg` | 允许的图片后缀 |
| `FILE_EXT` | 多种后缀 | 允许的文件后缀 |
| `MAX_SIZE` | `10` | 单文件最大大小（MB） |
### 缓存配置 `[CACHE]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DRIVER` | `file` | 缓存驱动：`file` 或 `redis` |
| `REDIS_HOST` | `127.0.0.1` | Redis 主机（driver=redis 时生效） |
| `REDIS_PORT` | `6379` | Redis 端口（driver=redis 时生效） |
| `REDIS_PASSWORD` | - | Redis 密码 |
| `REDIS_DB` | `0` | Redis 数据库编号 |
| `REDIS_PREFIX` | `rx:` | 缓存键前缀 |
### CORS 配置 `[CORS]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ALLOW_ORIGIN` | `*` | 允许的来源，`*` 表示所有 |
### API 配置 `[API]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CAMEL_SNAKE_CONVERT` | `true` | 驼峰/下划线自动转换开关 |
### 验证码配置 `[CAPTCHA]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CAPTCHA_BYPASS_CODE` | （空） | 万能验证码，跳过验证。仅用于开发调试，**生产环境务必留空** |
| `CAPTCHA_LENGTH` | `6` | 验证码字符长度（4-6位） |
| `CAPTCHA_EXPIRE` | `300` | 验证码过期时间（秒），默认 5 分钟 |
| `CAPTCHA_RATE_WINDOW` | `60` | 防刷窗口期（秒） |
| `CAPTCHA_RATE_LIMIT` | `20` | 窗口期内最大获取次数 |
| `CAPTCHA_CHARS` | `ABCDEFGHJKLMNPQRSTUVWXYZ2346789` | 字符集（已排除 0O、1lI 等易混淆字符） |
| `CAPTCHA_FONT_PATH` | `static/fonts/Vera.ttf` | 字体路径 |
| `CAPTCHA_IMAGE_WIDTH` | `160` | 图片宽度（像素） |
| `CAPTCHA_IMAGE_HEIGHT` | `50` | 图片高度（像素） |
| `CAPTCHA_FONT_SIZE` | `28` | 字体大小 |
| `CAPTCHA_NOISE_LINES` | `8` | 干扰线数量 |
| `CAPTCHA_NOISE_DOTS` | `500` | 噪点数量 |
### 国际化配置 `[LANG]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `default_lang` | `zh-cn` | 默认语言 |
### 代码生成器配置 `[GENERATOR]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PARENT_MENU_ID` | `189` | 生成模块的父菜单ID |
| `APP_NAME` | `tool` | 模块应用名（影响路由前缀和前端目录） |
## 多环境配置
### 开发环境
```ini
; 开发环境配置（调试开启，使用文件缓存）
APP_DEBUG = true ; 开启调试模式
[APP]
SHOW_ERROR_MSG = true ; 显示错误详情
[DATABASE]
DEBUG = true ; 显示执行的 SQL
[CACHE]
DRIVER = file ; 使用文件缓存（无需 Redis）
```
### 生产环境
```ini
; 生产环境配置（调试关闭，使用 Redis 缓存）
APP_DEBUG = false ; 关闭调试模式
[APP]
SHOW_ERROR_MSG = false ; 不显示错误详情（防止泄露）
[DATABASE]
DEBUG = false ; 不显示 SQL
[CACHE]
DRIVER = redis ; 使用 Redis 缓存
REDIS_HOST = 127.0.0.1 ; Redis 地址
REDIS_PORT = 6379 ; Redis 端口
REDIS_PASSWORD = <你的Redis密码> ; Redis 密码
[JWT]
SECRET = <随机生成的强密钥> ; 签名密钥（必须修改）
[CORS]
ALLOW_ORIGIN = https://admin.example.com ; 限制为实际域名
```
### 生成强密钥
```bash
# Linux / macOS：使用 OpenSSL 生成 32 字节随机 Base64 字符串
openssl rand -base64 32
# PHP：生成 32 字节随机十六进制字符串（64 个字符）
# random_bytes(32) → 32 字节密码学安全随机数
# bin2hex() → 转为十六进制字符串
php -r "echo bin2hex(random_bytes(32));"
```
## 前端环境变量
前端使用 Vite 的环境变量机制，配置文件位于 `ui/` 目录：
### `.env.development`（开发环境）
```bash
# API 接口基础路径（Vite 代理会将此路径的请求转发到后端）
VITE_GLOB_API_URL=/api
# API 前缀（一般留空）
VITE_GLOB_API_URL_PREFIX=
# 是否启用 Mock 数据（false = 使用真实后端 API）
VITE_USE_MOCK=false
```
### `.env.production`（生产环境）
```bash
# API 接口基础路径（生产环境的实际后端地址）
VITE_GLOB_API_URL=/api
# API 前缀
VITE_GLOB_API_URL_PREFIX=
```
在代码中访问环境变量：
```typescript
// 通过 import.meta.env 访问 Vite 环境变量
// VITE_ 前缀的变量才会被暴露给客户端代码
const apiUrl = import.meta.env.VITE_GLOB_API_URL
```
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/environment.md
+1085
View File
File diff suppressed because it is too large Load Diff
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/faq.md
+104
View File
@@ -0,0 +1,104 @@
# 2.8 常见问题 FAQ
## 环境相关
### Q: PHP 版本低于 8.2 能运行吗？
A: 不能。项目使用了 PHP 8.2 的强类型特性（如 `readonly` 属性、`DNF` 类型等），必须使用 PHP 8.2+。
### Q: 缺少 PHP 扩展怎么办？
A: 运行 `php -m` 检查已安装的扩展。缺少的扩展参考 [2.1 节](/zh/quickstart/environment.html) 安装。最常见的是缺少 `pdo_mysql` 和 `gd`。
### Q: Composer 安装很慢怎么办？
A: 配置中国镜像：
```bash
# 配置阿里云 Composer 镜像（加速依赖下载）
# -g → 修改全局配置（所有项目生效）
# repo.packagist → 设置 Packagist 仓库镜像地址
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```
### Q: Redis 不安装可以吗？
A: 可以。Redis 是可选的缓存驱动，不安装时使用 file 缓存。将 `.env` 中 `CACHE.DRIVER` 设为 `file` 即可。
## 启动相关
### Q: `php think run` 报错 "Address already in use"
A: 端口被占用，更换端口：
```bash
# --port → 指定监听端口（默认 8000）
php think run --port 8080
```
### Q: 数据库连接失败 "Connection refused"
A: 检查以下几点：
1. MySQL 服务是否启动：`systemctl status mysql`
2. `.env` 中的数据库配置是否正确
3. 数据库用户是否有权限：`GRANT ALL ON \`rxthinkcmf.thinkphp6.elevue\`.* TO 'root'@'localhost'`
### Q: 登录返回 401
A: 可能原因：
1. Token 过期 → 重新登录
2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
3. JWT 密钥不匹配 → 检查 `.env` 中的 `JWT.SECRET`
## 前端相关
### Q: `pnpm install` 报错
A: 清除缓存重新安装：
```bash
# 删除依赖目录和锁文件，重新安装
rm -rf node_modules pnpm-lock.yaml # 删除旧的依赖和锁文件
pnpm install # 重新安装所有依赖
```
### Q: 前端请求后端 404
A: 检查以下几点：
1. 后端服务是否启动
2. Vite 代理配置是否正确（`vite.config.ts` 中的 `target`）
3. API 路径是否正确（应以 `/api` 开头）
### Q: 页面白屏
A: 打开浏览器控制台（F12）查看错误信息，常见原因：
1. JS 加载失败 → 检查网络请求
2. 路由配置错误 → 检查后端菜单数据
3. Token 过期 → 重新登录
## Oracle 相关
### Q: ThinkPHP 连接 Oracle 需要哪个 PHP 扩展？
A: 需要 `pdo_oci` 扩展。ThinkPHP 的 Oracle 连接器通过 PDO 连接数据库（DSN 前缀 `oci:dbname=`），XAMPP 8.2 已自带 `php_pdo_oci.dll`，只需在 php.ini 中启用即可。
### Q: XAMPP 下 pdo_oci 扩展加载失败怎么办？
A: 按以下顺序排查：
1. 是否安装了 Oracle Instant Client 19c（x64）并解压到固定路径
2. 该路径是否已添加到**系统变量** PATH 中（不是用户变量）
3. 是否安装了 VC++ 2015-2022 Redistributable（x64）
4. `php.ini` 中 `extension=pdo_oci` 是否已去掉分号
5. XAMPP 是否**完全关闭再启动**（不是只点 Apache 的 Start/Stop）
### Q: 命令行 `php -m` 能看到 pdo_oci，但浏览器 phpinfo() 里找不到？
A: Apache 作为 Windows 服务运行时，读取的是服务启动时的系统 PATH。如果在 Apache 启动**之后**才修改了 PATH 环境变量，Apache 不会感知到。解决方法：在 XAMPP 控制面板中完全停止 Apache，再重新启动。
### Q: Oracle Instant Client 应该下载哪个版本？
A: 推荐下载 **19c** 的 **Basic Package**（x64）。下载地址：https://www.oracle.com/database/technologies/instant-client/downloads.html
### Q: 为什么 Instant Client 必须解压到固定路径？
A: 因为系统 PATH 环境变量写入的是绝对路径。如果解压到桌面或下载文件夹，后续清理、移动或重命名都会导致 PATH 失效，PHP 无法加载 Oracle 客户端库。推荐路径：`C:\oracle\instantclient_19_20`。
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/first-api.md
+208
View File
@@ -0,0 +1,208 @@
# 2.6 第一个接口调试
:::tip 概述
本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。
:::
## 调试工具
推荐使用以下工具进行 API 调试：
- **ApiFox**：图形化 API 调试工具（https://apifox.com/）
- **curl**：命令行工具（系统自带）
- **浏览器开发者工具**：F12 → Network 面板
## 步骤一：获取验证码
```bash
# GET 请求获取验证码（返回 Base64 编码的图片 + 验证码 key）
curl http://localhost:8000/api/captcha
```
响应示例：
```json
{
"code": 0,
"ok": true,
"msg": "操作成功",
"data": {
"key": "a1b2c3d4e5f6...",
"image": "data:image/png;base64,iVBOR..."
}
}
```
将 `key` 保存备用，`image` 是 Base64 编码的验证码图片。
## 步骤二：登录获取 Token
```bash
# -----------------------------------------------------------------------------
# 登录接口（POST + JSON）
# -----------------------------------------------------------------------------
# -X POST → 使用 POST 方法
# -H "Content-Type: ..." → 告诉服务器请求体是 JSON 格式
# -d '{...}' → 发送 JSON 请求体
# username → 用户名
# password → 密码
# captchaKey → 步骤一返回的验证码 key
# captchaCode → 验证码图片上显示的字符
curl -X POST http://localhost:8000/api/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "123456",
"captchaKey": "a1b2c3d4e5f6...",
"captchaCode": "1234"
}'
```
响应示例：
```json
{
"code": 0,
"ok": true,
"msg": "登录成功",
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 7200,
"user": {
"id": 1,
"username": "admin",
"realname": "管理员",
"avatar": ""
}
}
}
```
将 `access_token` 保存备用。
## 步骤三：调用业务接口
使用 Token 调用需要认证的接口：
```bash
# -----------------------------------------------------------------------------
# 获取用户分页列表（GET + Authorization 头）
# -----------------------------------------------------------------------------
# pageNo=1\&pageSize=10 → 分页参数（\& 是 bash 转义，防止 & 被解释为后台运行符）
# -H "Authorization: Bearer <token>" → 在请求头中携带 JWT Token
curl http://localhost:8000/api/user/page?pageNo=1\&pageSize=10 \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
```
响应示例：
```json
{
"code": 0,
"ok": true,
"msg": "操作成功",
"data": {
"records": [
{
"id": 1,
"username": "admin",
"realname": "管理员",
"status": 1,
"statusText": "启用",
"createTime": "2026-01-01 00:00:00"
}
],
"total": 1,
"size": 10,
"current": 1,
"pages": 1
}
}
```
## 步骤四：测试其他接口
```bash
# -----------------------------------------------------------------------------
# 获取当前登录用户信息
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/index/getUser \
-H "Authorization: Bearer <your_token>"
# -----------------------------------------------------------------------------
# 获取当前用户的菜单列表（用于前端动态路由）
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/index/getMenus \
-H "Authorization: Bearer <your_token>"
# -----------------------------------------------------------------------------
# 获取字典项（gender = 性别字典的编码）
# -----------------------------------------------------------------------------
curl http://localhost:8000/api/dict/item/getDictItemList/gender \
-H "Authorization: Bearer <your_token>"
# -----------------------------------------------------------------------------
# 刷新 Token（access_token 过期后，用 refresh_token 换取新的）
# -----------------------------------------------------------------------------
curl -X POST http://localhost:8000/api/oauth2/token \
-H "Content-Type: application/json" \
-d '{"grant_type": "refresh_token", "refresh_token": "<your_refresh_token>"}'
```
## 错误响应示例
### 401 未授权（Token 缺失或无效）
```json
{
"code": 401,
"ok": false,
"msg": "未提供认证令牌",
"data": null
}
```
### 403 禁止访问（权限不足）
```json
{
"code": 403,
"ok": false,
"msg": "无访问权限：用户列表",
"data": null
}
```
### 422 参数验证失败
```json
{
"code": 1,
"ok": false,
"msg": "参数验证失败",
"data": {
"username": "用户名不能为空"
}
}
```
## ApiFox 配置建议
1. 创建环境，设置变量：
- `base_url` = `http://localhost:8000`
- `token` = 登录后填入 access_token
2. 在请求头中使用变量：
- `Authorization` = `Bearer {{token}}`
3. 登录请求的「后置操作」中添加脚本自动保存 Token：
```javascript
// 解析响应 JSON
var response = pm.response.json();
// 登录成功时自动将 access_token 保存到环境变量
if (response.code === 0) {
pm.environment.set("token", response.data.access_token);
}
```
RXThinkCMF_Laravel13_NaiveVue/zh/quickstart/frontend-start.md
+191
View File
@@ -0,0 +1,191 @@
# 2.3 前端服务启动
:::tip 概述
本章指导您启动前端开发服务器，包括依赖安装、环境配置和 Vite 开发服务器启动。
:::
## 步骤一：安装依赖
```bash
# 进入前端项目目录
cd ui
# -----------------------------------------------------------------------------
# 安装依赖（推荐 pnpm — 速度快、磁盘占用少）
# -----------------------------------------------------------------------------
# install → 从 pnpm-lock.yaml 精确安装所有依赖
pnpm install
# 如果没有 pnpm，也可以使用 npm
npm install
```
:::warning Node.js 版本
前端项目要求 Node.js >= 18，推荐使用 22.x。可通过 `node -v` 检查版本。
:::
## 步骤二：配置环境变量
前端有两个环境配置文件：
### `.env.development`（开发环境）
```bash
# 服务端口
VITE_PORT = 8001
# 公共基础路径
VITE_PUBLIC_PATH = /
# 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
VITE_PROXY = [["/api","http://admin.thinkphp6.elevue/api"]]
# API 接口基础路径（留空，由代理处理）
VITE_GLOB_API_URL =
# API 前缀
VITE_GLOB_API_URL_PREFIX = /api
# 上传接口地址
VITE_GLOB_UPLOAD_URL = /api/upload
# 图片访问地址
VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue
# 是否启用 Mock 数据（false = 使用真实后端 API）
VITE_USE_MOCK = false
```
### `.env.production`（生产环境）
```bash
# 公共基础路径
VITE_PUBLIC_PATH = /
# 是否在生产环境删除 console
VITE_DROP_CONSOLE = true
# API 接口基础路径（留空，由 Nginx 代理处理）
VITE_GLOB_API_URL =
# API 前缀
VITE_GLOB_API_URL_PREFIX = /api
# 上传接口地址
VITE_GLOB_UPLOAD_URL = /api/upload
# 图片访问地址
VITE_GLOB_IMG_URL = http://file.thinkphp6.elevue
# 是否启用 gzip 压缩
VITE_BUILD_COMPRESS = gzip
# 压缩后是否删除原文件
VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
```
## 步骤三：启动开发服务器
```bash
# -----------------------------------------------------------------------------
# 启动 Vite 开发服务器（支持热更新 — 修改代码后浏览器自动刷新）
# -----------------------------------------------------------------------------
pnpm dev
# 或使用 npm
npm run dev
```
启动成功后会看到：
```text
VITE v3.2.x ready in 1234 ms
➜ Local: http://localhost:8001/
➜ Network: http://192.168.1.100:8001/
```
## 步骤四：配置 API 代理
开发环境下，前端通过 Vite 代理将 `/api` 请求转发到后端服务。
在 `vite.config.ts` 中配置代理：
```typescript
// ui/vite.config.ts
server: {
port: 8001, // 开发服务器端口（对应 VITE_PORT）
proxy: {
'/api': {
target: 'http://admin.thinkphp6.elevue/api', // 后端服务地址（对应 VITE_PROXY）
changeOrigin: true, // 开启跨域（修改请求头的 Origin）
rewrite: (path) => path, // 保持路径不变（不做路径替换）
},
},
}
```
确保后端服务已启动（`php think run`），然后访问 `http://localhost:8001`。
## 步骤五：验证前后端联调
1. 打开浏览器访问 `http://localhost:8001`
2. 应该看到登录页面
3. 输入默认账号 `admin` / `123456`
4. 登录成功后进入控制台页面
:::tip 代理原理
浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://admin.thinkphp6.elevue/api/login` → 后端处理
:::
## 构建生产版本
```bash
# -----------------------------------------------------------------------------
# 构建生产版本（Vite 会压缩代码、Tree-shaking、分包）
# -----------------------------------------------------------------------------
# build → 输出到 ui/dist/ 目录
pnpm build
# -----------------------------------------------------------------------------
# 预览构建结果（本地启动一个静态文件服务器预览 dist/ 内容）
# -----------------------------------------------------------------------------
pnpm preview
```
构建完成后，`ui/dist/` 目录包含可部署的静态文件。
## 常见问题
### 1. `pnpm install` 报错
```bash
# -----------------------------------------------------------------------------
# 清除缓存重新安装（修复依赖冲突或缓存损坏）
# -----------------------------------------------------------------------------
# rm -rf → 递归强制删除（node_modules 和 lockfile）
rm -rf node_modules pnpm-lock.yaml
pnpm install
```
### 2. 端口 8001 被占用
修改 `.env.development` 中的 `VITE_PORT` 或 `vite.config.ts` 中的 `server.port`：
```typescript
server: {
port: 8002, // 改为其他端口（如 8002、8003 等）
}
```
### 3. API 请求 404
检查后端服务是否启动，以及代理配置是否正确：
```bash
# 确认后端在运行（直接请求后端登录接口）
# -X POST → POST 方法
# -H → 设置 Content-Type 为 JSON
# -d → 发送 JSON 请求体
curl http://admin.thinkphp6.elevue/api/login -X POST -H "Content-Type: application/json" -d '{"username":"admin","password":"123456"}'
```