CatchAdmin 专业版文档

主题

CatchAdmin 专业版安装指南 ​

INFO

本章节介绍 CatchAdmin 专业版本地开发环境的安装配置。生产环境部署请查看部署章节

环境要求 ​

#环境版本
1PHP>= 8.2+
2Nginxlatest
3Mysql>= 5.7
4Node>= 22

WARNING

CatchAdmin 专业版 3.x 版本需要 Node.js 20，4.0+ 版本需要 Node.js 22。请根据项目版本选择对应的 Node.js 运行环境。

开发工具准备 ​

在安装 CatchAdmin 专业版项目之前，您需要准备以下必要的开发工具和运行环境：

#必须官网
1Composer PHP 依赖管理器https://getcomposer.org/download/
2Node.js (>= 22)https://nodejs.org/zh-cn/
3Yarn 前端包管理器https://yarn.bootcss.com/
4Vite 前端构建工具https://cn.vitejs.dev/

WARNING

请确保上述开发工具已正确安装并可在命令行中使用，否则 CatchAdmin 专业版项目安装将会失败。

下载代码 ​

购买 CatchAdmin 专业版授权后，可以从授权仓库下载项目源码 授权仓库 在授权仓库进行下载。这里分四种方式，分别解释下。

  • 版本: 阶段性稳定功能的版本，可以在更新里面看到 版本更新日志
  • 分支: 分支功能都是优先于版本的，都是直接提交的，你可以当作开发分支来看，不保证稳定性。
  • commit: commit 用于修复一些紧急 bug，你可以看作一个一个的即时的小补丁
  • 补丁：版本之间的 diff 差异，例如你目前正在使用 v3.5.0，需要升级到 v4.0.0，就需要下载 v4.0.0 的补丁。查看如何更新补丁。需要注意的是补丁不会跨版本。

请根据实际需求选择合适的版本下载源码包，所有代码包均为 zip 压缩格式，下载解压后即可进行 CatchAdmin 专业版项目的安装配置。

进行开发时建议阅读最佳开发实践，了解项目结构和版本升级流程

CatchAdmin 专业版项目安装 ​

WARNING

请确保已完成开发工具准备中的所有环境配置，缺少必要工具将导致 CatchAdmin 专业版安装失败。

命令行认证 ​

INFO

推荐使用该方式安装

CatchAdmin 专业版提供便捷的授权认证脚本，自动完成用户验证和项目依赖安装。进入项目根目录，执行以下认证命令

首先获取授权码，在授权码页面获取，点击生成授权码之后。记得保存，页面不做二次展示授权码页面

进入到源码解压之后的根目录，然后使用下面的命令

shell
php auth 邮箱 这里替换成生成的授权码

# 假设你的邮箱是 catch@pro.com，授权码是 123456 , 那么需要执行如下的命令
php auth catch@pro.com 123456

WARNING

系统会对每个账户下载来源统计，所以请不要泄露账户。如果出现不寻常的情况，我们会对账户进行一些限制。如果有误，烦请联系管理员

系统将自动通过 Composer 安装 PHP 项目依赖包。依赖安装完成后，需要初始化 CatchAdmin 专业版项目配置和数据库结构，执行以下命令

shell
# 安装后台, 按照提示输入对应信息即可
php artisan catch:install

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

TIP

生产环境部署时，请使用 php artisan catch:install --prod 命令进行项目初始化配置。

手动安装 ​

创建数据库 ​

手动安装时，数据库需要先由你自己创建。本地开发使用 navicat 等客户端操作

MySQL 示例：

sql
CREATE DATABASE `admin` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

配置后端环境文件 ​

复制环境文件：

shell
cp .env.example .env

编辑 .env，至少配置以下内容：

dotenv
APP_NAME="admin"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=admin
DB_USERNAME=root
DB_PASSWORD=123456
DB_PREFIX=

生成应用密钥 ​

shell
php artisan key:generate
php artisan jwt:secret

发布配置文件 ​

shell
php artisan vendor:publish --tag=catch-config
php artisan vendor:publish --tag=sanctum-config
php artisan vendor:publish --tag=sanctum-migrations

执行完成后，请确认以下文件已经存在：

  • config/catch.php
  • config/sanctum.php
  • database/migrations/*_create_personal_access_tokens_table.php

WARNING

database/migrations 中只保留一个 create_personal_access_tokens_table migration 文件。重复文件会导致后续迁移失败。

执行数据库迁移 ​

shell
php artisan migrate

php artisan catch:migrate user
php artisan catch:db:seed user

php artisan catch:migrate develop
php artisan catch:db:seed develop

再安装 permissions 和 system 两个基础模块：

shell
php artisan catch:module:install

根据命令行提示勾选：

  • 权限管理
  • 系统管理

创建存储软链接 ​

shell
php artisan storage:link

刷新 Composer 自动加载 ​

shell
composer dump-autoload

安装前端依赖 ​

进入 web 目录：

shell
cd web

#安装依赖
yarn config set registry https://registry.npmmirror.com
yarn install

配置前端环境文件 ​

在 web 目录创建 .env：

dotenv
VITE_BASE_URL=http://127.0.0.1:8000/api/
VITE_APP_NAME=admin

VITE_BASE_URL 需要与后端 APP_URL 保持一致，并保留结尾的 /api/。

安装完成后请确认：

  • 后端命令执行过程无报错
  • storage/app/modules.json 已生成
  • 登录页可正常打开
  • 登录接口请求正常

默认账号：

text
账号: catch@admin.com
密码: catchadmin

开发环境启动 ​

CatchAdmin 专业版 4.0.0+ 版本提供了一键启动开发环境的便捷命令，无需分别执行 php artisan serve 和 yarn dev

shell
composer run dev

WARNING

如果本地开发环境已配置了集成环境（如 XAMPP、WAMP Laragon 等）或使用 Nginx/Apache 等 Web 服务器，请不要使用 composer run dev 命令。

此种情况下请单独启动前端项目：进入 web 目录后执行 yarn dev

如何实现 ​

以下为技术实现说明，便于故障排查：

  • 此命令启动的 PHP 内置服务器默认监听 8000 端口，如需修改请编辑 composer.json 中的启动脚本

  • 依赖 concurrently 包实现并发启动，通常已预装。如缺失可全局安装：npm install -g concurrently

最佳开发实践 ​

开发实践, 如何升级

补丁安装 ​

请从授权仓库下载对应版本的升级补丁包 补丁安装 下载补丁包后，将其放置到 CatchAdmin 专业版项目根目录。假设补丁文件名为 xxxxx.zip，使用以下命令执行版本升级

shell
php artisan catch:upgrade xxxx.zip