CatchAdmin 专业版文档

主题

项目部署指南 ​

CatchAdmin 一键快捷部署 ​

CatchAdmin 提供了一个自动化快速打包部署功能，支持前端 Vue 项目和后端 PHP Laravel 项目的一键打包，只需要运行对应的 Artisan 命令即可完成整个项目的部署准备工作

shell
php artisan catch:build

该命令将会自动打包前端项目之后，将整个项目压缩成 zip 文件。使用者可以自己上传 zip 文件到服务器解压配置线上环境

如果打包过程遇到前端类型检查的问题，可以选择忽略类型检查

shell
php artisan catch:build --no-check

更多其他的 CatchAdmin 开发相关的内置命令

TIP

注意：此命令会将整个 CatchAdmin 项目打包，包含 Composer vendor 依赖文件夹，因此请确保线上生产环境与本地开发环境的 PHP 版本和扩展保持一致

前端 Vue 项目打包部署 ​

Vue 前端项目打包前，需要先配置生产环境 API 接口地址。在前端项目根目录下的 .env.production 环境配置文件中(如果没有，请先创建该文件)配置生产环境的 API 基础地址

# base api
// 例如 https://api.catchadmin.com/api/

VITE_BASE_URL = '正式环境的 API 地址'

Vue 项目环境配置完成后，使用 Yarn 包管理器执行以下命令进行生产环境打包构建

yarn run build

打包出现报错 ​

如果打包出现 ts 过多的类型错误，而你对类型又不太敏感的话，对应用没有影响。一个快速的解决办法就是修改 package.json 文件 build 命令

json
{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build", 
    "build": "vite build", 
    "preview": "vite preview"
  }
}

在打包完成之后呢，会在前端项目的根目录生成一个 dist 目录，dist 目录就是打包后的前端项目，是一个纯 html Js 项目，直接上传到服务器即可。

TIP

建议在 Nginx 或 Apache 服务器配置中开启 Gzip 压缩，可以显著提升 Vue 前端静态资源的加载速度和用户体验。

后端 PHP Laravel 项目部署 ​

CatchAdmin 后端基于 PHP Laravel 框架开发，你只需要将整个 PHP 项目源码上传至 Linux 服务器即可。对于 Composer 依赖包 vendor 文件夹，推荐在服务器端执行 composer install 安装依赖，而不是直接上传。如果遇到 Composer 网络安装问题，可以查看 使用镜像

WARNING

如果使用了 CatchAdmin CLI 工具初始化的项目目录结构，在上传 PHP Laravel 后端项目时，一定要排除 web 目录，因为该目录包含的是 Vue 前端源码，不需要与后端项目一并上传到服务器。前端部署只需要 Yarn 构建后的 dist 目录即可。

上线注意点 ​

  • .env 环境文件是否配置好？

    TIP

    APP_URL 一定要和上面前端打包的配置 VITE_BASE_URL 相同 还有数据库信息

  • 数据库表是否同步?
  • 数据表的数据是否同步，主要是权限菜单表permissions里是否同步
  • 模块是否开启? 模块如果没有开启，整个项目都会无法正常运行

    TIP

    一定要检查线上项目storage/app/modules.json 是否存在。如果不存在，要将本地项目storage/app/modules.json上传到服务器

  • 模块如果正常开启的状态下，路由还是无法正常工作

    TIP

    • 首先是用 php artisan route:clear
    • 然后查看路由 php artisan route:list
    • 最后缓存路由 php artisan route:cache

生产环境服务器部署配置 ​

WARNING

如果你使用的是宝塔面板进行服务器管理，请不要完全复制以下 Nginx 配置文件。宝塔面板已预配置了许多项目，如 HTTPS SSL 证书配置、PHP-FPM 管理等，这些无需手动配置。

前后端分离部署（双域名 Nginx 配置） ​

前后端分离部署是将 Vue 前端项目和 PHP Laravel 后端项目分别部署到不同域名。这里以 /www 作为服务器根目录示例，前端 Vue 构建产物部署到 /www/admin 目录，后端 PHP Laravel 项目部署到 /www/api 目录

TIP

这里的目录只做展示说明使用，实际部署请按照自身需求设置

  • /www/admin 上传 dist 目录内容到 admin 目录中
  • /www/api 上传后端项目到 api 目录中
nginx
server
{
    listen 80;
    server_name admin.catchadmin.com;
    return 301 https://admin.catchadmin.com$request_uri;
}

server
{
    listen  443  ssl http2;
    server_name admin.catchadmin.com;
    index.html index.php index.htm default.php default.htm default.html;


    ssl_certificate       # pem文件的路径
    ssl_certificate_key   # key文件的路径

    # HTTPS SSL 证书验证相关配置
    ssl_session_timeout  5m;    #缓存有效期
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    root /www/admin;
    location / {
    	try_files $uri $uri/ /index.html =404;
    }
}
nginx
server
{
    listen 80;
    server_name api.catchadmin.com;
    return 301 https://api.catchadmin.com$request_uri;
}


server
{
    listen  443  ssl http2;
    server_name api.catchadmin.com;
    index index.html index.php index.htm default.php default.htm default.html;
    root /www/api/public;

    ssl_certificate     /etc/nginx/acme/catchadmin.com/catchadmin.com.cer;  # pem文件的路径
    ssl_certificate_key  /etc/nginx/acme/catchadmin.com/catchadmin.com.key; # key文件的路径
    ssl_session_timeout  5m;    #缓存有效期
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    location / {
       if (!-e $request_filename) {
        rewrite  ^(.*)$  /index.php?s=/$1  last;
        break;
      }
    }

   # PHP Laravel-FPM 支持配置
    location ~ \.php$ {
        try_files $uri /index.php =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    ## Nginx 访问日志和错误日志配置（请根据实际需求配置）
    access_log;
    error_log;
}

前后端合并部署（单域名 Nginx 配置） ​

WARNING

如果使用宝塔部署，请看宝塔部署章节

前后端合并部署指的是在同一个域名下同时提供前端页面和后端 API 服务。继续使用上述 api 目录作为示例，该目录部署 PHP Laravel 后端项目，Vue 前端构建产物放置到 public/admin 目录下，通过 Nginx 路由规则实现统一域名访问

nginx

server
{
    listen 80;
    server_name api.catchadmin.com;
    return 301 https://api.catchadmin.com$request_uri;
}


server
{
    listen  443  ssl http2;
    server_name api.catchadmin.com;
    index index.html index.php index.htm default.php default.htm default.html;
    root /www/api/public;

    ssl_certificate     # pem文件的路径
    ssl_certificate_key  # key文件的路径
    ssl_session_timeout  5m;    #缓存有效期
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    # 因为接口都是以 api.catchadmin.com/api 开头，所以可以很好的使用 location
    # 如果访问 api.catchadmin.com/api 目录 则用 php 解释下
    location /api {
       if (!-e $request_filename) {
        rewrite  ^(.*)$  /index.php?s=/$1  last;
        break;
      }
    }

    # 根目录访问直接提供 Vue 前端静态文件
    location / {
      root /www/api/public/admin;
      try_files $uri $uri/ /index.html;
    }

    # CatchAdmin 文件上传静态资源访问配置
    location /uploads/ {
      alias /www/api/public/storage/uploads/;
      autoindex on;
    }


     # PHP Laravel-FPM 处理配置
    location ~ \.php$ {
          try_files $uri /index.php =404;
          fastcgi_split_path_info ^(.+\.php)(/.+)$;
          fastcgi_pass 127.0.0.1:9000;
          fastcgi_index index.php;
          fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
          include fastcgi_params;
    }
}

Laravel Octane 高性能部署配置 ​

Laravel Octane 是 Laravel 官方提供的高性能应用服务器，支持 Swoole 和 RoadRunner 驱动，可以显著提升 CatchAdmin 后端 API 的并发处理能力

php
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server
{
    listen 80;
    server_name api.catchadmin.com;
    return 301 https://api.catchadmin.com$request_uri;
}


server
{
   listen  443  ssl http2;
    server_name api.catchadmin.com;
    index index.html index.php index.htm default.php default.htm default.html;
    root /www/api/public;

    ssl_certificate     # pem文件的路径
    ssl_certificate_key  # key文件的路径
    ssl_session_timeout  5m;    #缓存有效期
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    # 因为接口都是以 api.catchadmin.com/api 开头，所以可以很好的使用 location
    # 如果访问 api.catchadmin.com/api 目录 则用 php 解释下
    location /api {
       if (!-e $request_filename) {
        rewrite  ^(.*)$  /index.php?s=/$1  last;
        break;
      }
    }

    # 根目录访问直接提供 Vue 前端静态文件
    location / {
      root /www/api/public/admin;
      try_files $uri $uri/ /index.html;
    }

    # CatchAdmin 文件上传静态资源访问配置
    location /uploads/ {
      alias /www/api/public/storage/uploads/;
      autoindex on;
    }

    location @octane {
        set $suffix "";

        if ($uri = /index.php) {
            set $suffix ?$query_string;
        }

        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header Scheme $scheme;
        proxy_set_header SERVER_PORT $server_port;
        proxy_set_header REMOTE_ADDR $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_pass http://172.18.0.2:9800$suffix;
    }
}