import{_ as i,o as a,c as n,a2 as l}from"./chunks/framework.BbmSSMjL.js";const c=JSON.parse('{"title":"2.3 后端服务启动","description":"","frontmatter":{},"headers":[],"relativePath":"zh/quickstart/backend-start.md","filePath":"zh/quickstart/backend-start.md"}'),t={name:"zh/quickstart/backend-start.md"};function p(e,s,h,k,d,r){return a(),n("div",null,[...s[0]||(s[0]=[l(`

2.3 后端服务启动 ​

特别提醒

官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。

步骤一：获取源码 ​

前往 官方网站 购买授权后，按以下步骤获取源码：

text
1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 D:\\laragon\\www\\ 或 ~/www/）。
bash
# 进入项目目录（以实际解压路径为准）
cd RXThinkCMF_Laravel13_NaiveVue

温馨提示

  1. 源码包请务必从官方网站订单中心下载，确保获取的是正版授权的最新版本。
  2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
  3. 解压后请先阅读根目录下的 README.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/ 目录，包含所有第三方依赖。

一键初始化

以上两步（含后续的环境文件、APP_KEY、数据库迁移、前端构建）可合并为一条命令：

bash
composer setup
# 等价于：composer install → 复制 .env → key:generate → migrate --force → npm install → npm run build

步骤三：配置环境文件 ​

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.naivevue   # 数据库名称（需提前创建）
DB_USERNAME=root                    # 数据库用户名
DB_PASSWORD=root                    # 数据库密码
DB_PREFIX=laravel_                  # 表前缀（数据库脚本使用 laravel_ 前缀，必须保留）

# JWT 签名密钥（必须 >= 32 字符，应用启动 fail-close 校验）
JWT_SECRET=your_random_jwt_secret_key_at_least_32_bytes

# Redis 配置（必需；设置了 requirepass 时必须同步）
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# 会话 / 缓存 / 队列统一走 Redis
SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis

# 文件上传配置
FILE_UPLOAD_DIR=uploads             # 上传目录（相对 public/）
FILE_DOMAIN_URL=                    # 文件访问域名（空则返回相对路径）

生产环境务必修改

  1. JWT_SECRET 必须修改为强随机字符串（>= 32 字符），生成方式：openssl rand -base64 32。为空或长度不足时应用拒绝启动。
  2. APP_DEBUG 生产环境必须设为 false。
  3. DB_PASSWORD 必须修改为强密码。

步骤四：启动服务 ​

bash
# -----------------------------------------------------------------------------
# 推荐：一键启动（同时启动 API 服务 + 队列 + 日志流 + Vite 四个进程）
# -----------------------------------------------------------------------------
composer dev

# -----------------------------------------------------------------------------
# 方式二：单独启动 API 服务（内置 PHP 开发服务器，默认监听 127.0.0.1:8000）
# -----------------------------------------------------------------------------
# serve → 启动 Laravel 内置的 PHP 开发服务器
# 启动后浏览器访问 http://admin.laravel13.naivevue 即可
php artisan serve

# -----------------------------------------------------------------------------
# 指定端口（当 8000 被占用时更换端口）
# -----------------------------------------------------------------------------
php artisan serve --port=8080

# -----------------------------------------------------------------------------
# 指定主机和端口（允许局域网其他设备访问）
# -----------------------------------------------------------------------------
# --host=0.0.0.0 → 监听所有网络接口（默认只监听 127.0.0.1）
# 适用于手机调试、前后端分离开发等场景
php artisan serve --host=0.0.0.0 --port=8000

启动成功后会看到：

text
INFO  Server running on [http://127.0.0.1:8000].
INFO  Press Ctrl-C to quit.

composer dev 四进程说明

进程命令用途
serverphp artisan serveAPI 服务
queuephp artisan queue:listen队列消费（导入导出等异步任务）
logsphp artisan pail实时日志流
vitenpm run dev前端构建（HMR）

步骤五：验证服务 ​

bash
# -----------------------------------------------------------------------------
# 健康检查（Laravel 内置 /up 路由）
# -----------------------------------------------------------------------------
curl http://admin.laravel13.naivevue/up
# → {"status":"ok"}

# -----------------------------------------------------------------------------
# 验证码接口（公开接口，同时验证 PHP → Redis 链路）
# -----------------------------------------------------------------------------
curl http://admin.laravel13.naivevue/api/captcha
# → {"code":0,"ok":true,"msg":"操作成功","data":{"key":"...","captcha":"data:image/png;base64,..."}}

# -----------------------------------------------------------------------------
# 测试登录接口（POST 请求 + JSON 请求体）
# -----------------------------------------------------------------------------
# -X POST       → 使用 POST 方法
# -H            → 设置请求头（Content-Type: application/json）
# -d            → 发送 JSON 格式的请求体
curl -X POST http://admin.laravel13.naivevue/api/login \\
  -H "Content-Type: application/json" \\
  -d '{"username":"admin","password":"123456"}'

# 未传验证码时返回校验失败响应（说明路由与验证链路已通）：
# {"code":1,"ok":false,"msg":"请输入验证码","data":null}

内置演示账号

账号密码角色说明
admin123456超级管理员平台管理，可管理所有租户
tenant001123456租户管理员（客户租户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. 应用拒绝启动，报 JWT_SECRET 错误 ​

.env 中 JWT_SECRET 为空或不足 32 字符（应用启动 fail-close 校验）。生成并重试：

bash
openssl rand -base64 32     # 或 php -r "echo bin2hex(random_bytes(32));"
# 将结果写入 .env 的 JWT_SECRET 后重新启动

4. 数据库连接失败 ​

检查 .env 中的数据库配置是否正确：

bash
# 1. 检查 .env 中 DB_* 配置：DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_DATABASE 是否正确
# 2. 确认数据库服务已启动、数据库已创建并导入脚本
# 3. 用原生 SQL 测试连接是否正常（以 MySQL 为例）
mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT 1;"

# 4. 若报表不存在，检查 DB_PREFIX 是否为 laravel_

5. 端口被占用 ​

bash
# Windows：查找占用 8000 端口的进程
# findstr → Windows 版的 grep（过滤文本）
netstat -ano | findstr :8000

# macOS / Linux：查找占用 8000 端口的进程
lsof -i :8000

# 更换端口启动（避免冲突）
php artisan serve --port=8080

6. 验证码接口报"缓存服务(Redis)连接失败" ​

Redis 未启动或密码不匹配（.env 中 REDIS_PASSWORD 与 Redis 实际 requirepass 不一致），接口返回「缓存服务(Redis)连接失败，请检查 Redis 配置（地址、端口、密码）后重试」，真实原因见日志 验证码写入 Redis 失败。验证：

bash
redis-cli ping                                     # 输出 PONG
php artisan config:clear                           # 清除配置缓存
php artisan tinker --execute="try { \\Illuminate\\Support\\Facades\\Redis::setex('t', 5, 'ok'); echo 'OK'; } catch (\\Throwable \\$e) { echo \\$e->getMessage(); }"

详见 2.2 Laragon 环境搭建 「Redis 密码配置」。

`,41)])])}const E=i(t,[["render",p]]);export{c as __pageData,E as default};