CatchAdmin 专业版安装指南

INFO

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

环境要求

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

WARNING

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

开发工具准备

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

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

WARNING

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

下载代码

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

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

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

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

CatchAdmin 专业版项目安装

WARNING

命令行认证和手动安装依赖开发工具准备中的本地工具。Docker 一键安装只需要本机具备 Docker 和 Docker Compose 运行环境。

命令行认证

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 命令进行项目初始化配置。

Docker 一键安装

INFO

Docker 安装适合本地开发环境。该方式会启动前端、后端、MySQL、Redis 等服务，并在首次启动时完成依赖安装、数据库初始化和基础模块安装。

使用 Docker 安装前，请先安装并启动 Docker Desktop、OrbStack 或其他兼容 Docker Compose 的运行环境。

进入项目根目录，复制 Docker 环境配置：

shell

cp docker/env.example docker/.env

编辑 docker/.env，至少配置授权信息和端口：

dotenv

# Laravel 授权配置（必填）
AUTH_EMAIL=your-email@example.com
AUTH_PASSWORD=your-auth-password

# 数据库配置
DB_DATABASE=laravel_test
DB_USERNAME=root
DB_PASSWORD=123456

# Redis 配置
REDIS_PASSWORD=catch@admin

# 应用配置
APP_NAME=CatchAdmin
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

# 前端接口地址
VITE_BASE_URL=http://localhost/api/

# 端口配置
WEB_PORT=10086
NGINX_HTTP_PORT=80
MYSQL_PORT=3306
REDIS_PORT=6379

启动服务：

shell

bash docker/start.sh

首次启动会自动完成以下步骤：

使用 AUTH_EMAIL 和 AUTH_PASSWORD 安装 PHP 依赖
初始化 Laravel 配置、应用密钥和 JWT 密钥
执行数据库迁移和基础数据填充
安装 permissions 和 system 基础模块
启动前端开发服务和后端 API 服务

启动完成后访问：

text

后台前端：http://localhost:10086
后端 API：http://localhost/api
MySQL：127.0.0.1:3306
Redis：127.0.0.1:6379

前后端分离服务说明：

text

web 容器：前端 Vite 开发服务，默认端口 10086
nginx 容器：后端 API 入口，默认端口 80
app 容器：Laravel PHP-FPM 服务
mysql 容器：MySQL 数据库
redis 容器：Redis 服务

如果本机端口被占用，可以修改 docker/.env：

dotenv

NGINX_HTTP_PORT=8080
APP_URL=http://localhost:8080
VITE_BASE_URL=http://localhost:8080/api/

MYSQL_PORT=3307

修改后访问地址对应变为：

text

后端 API：http://localhost:8080/api
MySQL：127.0.0.1:3307

TIP

MySQL 数据会保存在 Docker volume 中。DB_PASSWORD 在新 volume 首次初始化时生效。需要更换已有数据库密码时，可以清理旧容器和旧 volume 后重新启动。

查看后端初始化日志：

shell

cd docker
docker compose --env-file .env logs -f app

重新执行 Docker 初始化：

shell

# 在项目根目录执行
rm -f storage/app/.docker-installed
bash docker/start.sh

WARNING

docker/.env 中包含授权码和数据库密码，请保存在本地环境中，并保持仓库忽略状态。

Docker 常见问题

Docker Hub 拉取镜像超时或 Bad Gateway

如果出现以下错误：

text

Client.Timeout exceeded while awaiting headers
Bad Gateway

这是 Docker Hub 网络或鉴权服务不稳定导致的。可以先单独拉取基础镜像：

shell

docker pull nginx:alpine
docker pull redis:alpine
docker pull mysql:8.0.42
docker pull catchadmin/php83
docker pull catchadmin/node22:latest

如果长期拉取失败，可以为 Docker 配置镜像加速器，或将基础镜像替换为团队内部镜像源。

Apple Silicon / ARM 设备镜像架构不匹配

如果出现：

text

no matching manifest for linux/arm64/v8

说明当前镜像没有 ARM64 架构版本。Docker 配置中前端镜像应使用：

yaml

catchadmin/node22:latest

PHP 镜像应使用：

yaml

catchadmin/php83

MySQL 密码修改后仍然连接失败

MySQL 容器首次初始化时会把数据写入 Docker volume。volume 已存在后，修改 docker/.env 中的 DB_PASSWORD 不会改变已有数据库密码。

解决方式：

使用旧密码继续启动
或清理旧容器和旧 volume 后重新初始化

shell

cd docker
docker compose --env-file .env down
docker volume ls | grep mysql

确认 volume 名称后再删除：

shell

docker volume rm <mysql_volume_name>

WARNING

删除 MySQL volume 会清空本地数据库数据，请确认没有需要保留的数据后再执行。

Module [permissions] has been created

这表示 storage/app/modules.json 中已经存在 permissions 模块记录，再次执行完整安装命令会触发重复安装。

Docker 初始化会使用本地状态文件避免重复执行：

text

storage/app/.docker-installed

如果需要重新初始化 Docker 安装状态，可以删除该文件后重启：

shell

rm -f storage/app/.docker-installed
bash docker/start.sh

如果数据库和模块状态已经混乱，建议同时清理数据库 volume 后重新启动。

前端容器提示 nc: not found

部分 Node 镜像没有内置 nc。当前脚本使用 curl 做健康检查。如果你使用旧脚本，可以更新 Docker 文件，或确认镜像内存在 curl：

shell

docker run --rm catchadmin/node22:latest curl --version

端口被占用

如果本机已有 Nginx、MySQL 或 Redis，占用 80、3306、6379 等端口，可以修改 docker/.env：

dotenv

NGINX_HTTP_PORT=8080
MYSQL_PORT=3307
REDIS_PORT=6380

同步调整前端 API 地址：

dotenv

APP_URL=http://localhost:8080
VITE_BASE_URL=http://localhost:8080/api/

查看容器日志和状态

shell

cd docker
docker compose --env-file .env ps
docker compose --env-file .env logs -f app
docker compose --env-file .env logs -f web

手动安装

创建数据库

手动安装时，数据库需要先由你自己创建。本地开发使用 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

CatchAdmin 专业版安装指南 ​

环境要求 ​

开发工具准备 ​

下载代码 ​

CatchAdmin 专业版项目安装 ​

命令行认证 ​

Docker 一键安装 ​

Docker 常见问题 ​

手动安装 ​

创建数据库 ​

配置后端环境文件 ​

生成应用密钥 ​

发布配置文件 ​

执行数据库迁移 ​

创建存储软链接 ​

刷新 Composer 自动加载 ​

安装前端依赖 ​

配置前端环境文件 ​

开发环境启动 ​

如何实现 ​

最佳开发实践 ​

补丁安装 ​

CatchAdmin 专业版安装指南

环境要求

开发工具准备

下载代码

CatchAdmin 专业版项目安装

命令行认证

Docker 一键安装

Docker 常见问题

手动安装

创建数据库

配置后端环境文件

生成应用密钥

发布配置文件

执行数据库迁移

创建存储软链接

刷新 Composer 自动加载

安装前端依赖

配置前端环境文件

开发环境启动

如何实现

最佳开发实践

补丁安装