# 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.elevue\` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
- [ ] 创建数据库用户并授权
- [ ] 导入 SQL 脚本：`mysql -u root -proot rxthinkcmf.laravel13.elevue < document/mysql/rxthinkcmf.laravel13.elevue.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 配置

```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

### 更新后端

```bash
# -----------------------------------------------------------------------------
# 第 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.elevue > /backup/db_$(date +%Y%m%d).sql

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

# -----------------------------------------------------------------------------
# 第 3 步：更新数据库（如有迁移脚本）
# -----------------------------------------------------------------------------
mysql -u root -proot rxthinkcmf.laravel13.elevue < 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
```

### 更新前端

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

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

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

## 回滚方案

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

# 恢复数据库
mysql -u root -proot rxthinkcmf.laravel13.elevue < /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
```