11.1 部署 Checklist

:::tip 本章概要从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 :::

首次部署 Checklist

第 1 阶段：服务器准备

服务器操作系统：CentOS 7+ / Ubuntu 20.04+ / Debian 11+
防火墙开放端口：80（HTTP）、443（HTTPS）、22（SSH）
创建部署用户（非 root）
配置 SSH 密钥登录
配置时区：timedatectl set-timezone Asia/Shanghai

第 2 阶段：环境安装

PHP 环境：

安装 PHP 8.3+（Laravel 13 要求）
安装必需扩展：pdo_mysql、mbstring、gd、bcmath、zip、openssl、fileinfo、json
安装 Redis 扩展：redis（phpredis，缓存/会话/队列/JWT 均依赖，必需）
安装 Composer 2.x
配置 PHP-FPM（如使用 Nginx）

数据库：

安装 MySQL 8.0+（或 PostgreSQL / SQL Server / Oracle / SQLite）
创建数据库：CREATE DATABASE \rxthinkcmf.laravel13.naivevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
创建数据库用户并授权
导入 SQL 脚本：mysql -u root -proot rxthinkcmf.laravel13.naivevue < document/mysql/rxthinkcmf.laravel13.naivevue.sql

:::info 表结构来源本项目表结构以 SQL 脚本为准（document/mysql/），database/migrations/ 为空，不要依赖 php artisan migrate 建表。 :::

Redis（必需）：

安装 Redis 6.0+
配置密码
测试连接：redis-cli ping

Node.js（前端构建）：

安装 Node.js 22 LTS（根目录资源构建 Vite 7 要求 20.19+/22.12+；ui/ 前端为 Vite 3，兼容 Node 14+）
安装 pnpm：npm install -g pnpm

第 3 阶段：应用部署

后端：

上传项目代码到服务器
安装 Composer 依赖：composer install --no-dev --optimize-autoloader
配置 .env 文件（数据库、Redis、JWT 密钥、文件上传等）
生成应用密钥与 JWT 密钥：php artisan key:generate、php -r "echo bin2hex(random_bytes(32));"（写入 JWT_SECRET）
设置目录权限：chmod -R 755 storage/、chmod -R 755 bootstrap/cache/、chmod -R 755 public/uploads/
测试启动：php artisan serve --host=127.0.0.1 --port=8000（生产由 Nginx + PHP-FPM 承载）
配置定时任务：crontab -e → * * * * * cd /www/api && php artisan job:run

前端：

安装前端依赖：cd ui && pnpm install
构建前端：pnpm build
上传构建产物（ui/dist/ 目录）到服务器

第 4 阶段：Nginx 配置

# =============================================================================
# 后端 API 站点配置
# =============================================================================
server {
    listen 80;                                      # 监听 80 端口
    server_name api.example.com;                    # 绑定域名
    root /www/api/public;                           # Laravel 入口目录（必须指向 public/）
    index index.php;                                # 默认索引文件

    # URL 重写（Laravel 路由必需）
    location / {
        try_files $uri $uri/ /index.php?$query_string;  # 非真实文件请求转发到 index.php
    }

    # PHP-FPM 转发
    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;             # PHP-FPM 监听地址
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }

    # 安全：禁止上传目录执行 PHP
    location ~ /uploads/.*\.php$ { deny all; }
}

# =============================================================================
# 前端 SPA 站点配置
# =============================================================================
server {
    listen 80;                                      # 监听 80 端口
    server_name admin.example.com;                  # 绑定域名
    root /www/admin/dist;                           # 前端构建产物目录（ui/dist）
    index index.html;                               # 默认索引文件

    # Vue Router History 模式（所有非文件请求回退到 index.html）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理到后端
    location /api/ {
        proxy_pass http://127.0.0.1:8000;           # 后端服务地址
        proxy_set_header Host $host;                 # 传递原始 Host
        proxy_set_header X-Real-IP $remote_addr;     # 传递客户端 IP
    }
}

第 5 阶段：安全加固

.env 中 APP_DEBUG=false
.env 中 APP_ENV=production
.env 中 JWT_SECRET 已修改为强随机密钥（≥32 字符）
.env 中 CORS_ALLOW_ORIGIN 已限制为实际域名
启用 HTTPS（SSL 证书）
上传目录禁止执行 PHP
数据库不允许外网访问
Redis 已设置密码且不对公网开放

第 6 阶段：验证

健康检查正常：访问 /up 返回 200
验证码接口正常：/api/captcha 返回 code=0
访问前端页面正常
登录功能正常（admin / root）
各模块 CRUD 功能正常
文件上传功能正常
定时任务正常执行（php artisan job:run，查看任务日志表）
操作日志正常记录

版本更新 Checklist

更新后端

# -----------------------------------------------------------------------------
# 第 1 步：备份（更新前必须备份）
# -----------------------------------------------------------------------------
# 备份项目代码（cp -r 递归复制整个目录）
cp -r /www/api /www/api_backup_$(date +%Y%m%d)

# 备份数据库（mysqldump 导出 SQL，$(date +%Y%m%d) 自动生成日期后缀）
mysqldump -u root -proot rxthinkcmf.laravel13.naivevue > /backup/db_$(date +%Y%m%d).sql

# -----------------------------------------------------------------------------
# 第 2 步：更新代码
# -----------------------------------------------------------------------------
cd /www/api                                         # 进入项目目录
composer install --no-dev --optimize-autoloader     # 安装依赖（排除开发依赖，优化自动加载）

# -----------------------------------------------------------------------------
# 第 3 步：更新数据库（如有迁移脚本）
# -----------------------------------------------------------------------------
mysql -u root -proot rxthinkcmf.laravel13.naivevue < document/mysql/migration.sql

# -----------------------------------------------------------------------------
# 第 4 步：清除并重建缓存
# -----------------------------------------------------------------------------
php artisan cache:clear       # 清除应用缓存
php artisan config:clear      # 清除配置缓存
php artisan route:clear       # 清除路由缓存
php artisan view:clear        # 清除编译视图
php artisan dict:clear-cache  # 清除字典缓存（本项目自定义命令）

# 生产环境重新构建缓存（可选）
php artisan config:cache && php artisan route:cache && php artisan view:cache

# -----------------------------------------------------------------------------
# 第 5 步：重启 PHP-FPM（使 OPcache 失效，加载新代码）
# -----------------------------------------------------------------------------
sudo systemctl restart php8.3-fpm

更新前端

# -----------------------------------------------------------------------------
# 第 1 步：构建前端
# -----------------------------------------------------------------------------
cd ui && pnpm install && pnpm build     # 安装依赖并执行生产构建

# -----------------------------------------------------------------------------
# 第 2 步：部署构建产物
# -----------------------------------------------------------------------------
cp -r dist/* /www/admin/dist/           # 将构建产物复制到 Nginx 站点目录

# -----------------------------------------------------------------------------
# 第 3 步：重载 Nginx（不断开现有连接）
# -----------------------------------------------------------------------------
sudo nginx -s reload

回滚方案

# -----------------------------------------------------------------------------
# 后端回滚（恢复代码 + 数据库）
# -----------------------------------------------------------------------------
# 恢复项目代码
cp -r /www/api_backup_20260920/* /www/api/

# 恢复数据库
mysql -u root -proot rxthinkcmf.laravel13.naivevue < /backup/db_20260920.sql

# 重启 PHP-FPM（清除 OPcache，加载旧代码）
sudo systemctl restart php8.3-fpm

# -----------------------------------------------------------------------------
# 前端回滚（恢复构建产物）
# -----------------------------------------------------------------------------
cp -r /www/admin_backup_20260920/dist/* /www/admin/dist/

# 重载 Nginx（应用旧的前端文件）
sudo nginx -s reload

8.9 KiB Raw Blame History Unescape Escape