CatchAdmin 专业版文档

主题

安装指南 ​

购买提示

多租户扩展是 CatchAdmin 的高级功能模块，需要单独购买。

安装前准备 ​

当前租户数据库管理器使用 MySQL。安装前请确认中央数据库已经连接，并提交或备份以下目录中的自定义内容：

  • config/tenancy.php
  • database/migrations/tenancy
  • database/migrations/monitor
  • database/seeders/TenancyMenusSeeder.php
  • web/src/views/tenancy

安装命令会使用 --force 重新发布这些文件，已有同名文件会被覆盖。

安装扩展 ​

shell
composer require catchadmin/tenancy
php artisan catch:tenant:install

catch:tenant:install 会依次完成：

  1. 强制发布配置到 config/tenancy.php。
  2. 强制发布租户迁移到 database/migrations/tenancy，并执行迁移。
  3. 强制发布队列、调度监控迁移到 database/migrations/monitor，并执行迁移。
  4. 强制发布菜单 Seeder，执行 TenancyMenusSeeder。
  5. 强制发布前端页面到固定目录 web/src/views/tenancy。
  6. 确保 web/.env 和 web/.env.production 包含 VITE_TENANCY_MODE=true；缺少这条完整配置时会追加。
  7. 在项目根目录 .env 缺少 TENANCY_QUEUE_MONITOR 时追加 TENANCY_QUEUE_MONITOR=true。

包配置中的队列监控默认值为 false。安装命令只在环境变量完全缺失时写入 true，已有的 true 或 false 都会保留。

数据库迁移 ​

租户核心迁移创建以下中央库数据：

数据用途
租户租户资料、状态、套餐、有效期和数据库配置
域名domain 模式下的租户域名映射
套餐套餐状态和权限范围
操作日志创建、编辑、续期、变更套餐、停用和恢复记录
凭据加密加密已有租户数据库凭据

监控迁移创建中央库的队列监控表和调度监控表。租户业务库的模块迁移在创建租户或执行 catch:tenant:migrate 时处理。

选择识别模式 ​

同一套部署全局使用一种租户识别模式。默认值为 domain。

独立域名模式：

dotenv
# 项目根目录 .env
TENANCY_IDENTIFICATION_MODE=domain
TENANT_CENTRAL_DOMAIN=admin.example.com

# web/.env.production
VITE_TENANCY_IDENTIFICATION_MODE=domain

共享域名模式：

dotenv
# 项目根目录 .env
TENANCY_IDENTIFICATION_MODE=shared_domain
TENANT_CENTRAL_DOMAIN=admin.example.com

# web/.env.production
VITE_TENANCY_IDENTIFICATION_MODE=shared_domain

后端与前端识别模式必须保持一致。VITE_TENANCY_IDENTIFICATION_MODE 由部署人员写入对应的 web/.env* 文件。

共享域名入口为：

text
https://admin.example.com/#/login?tenant=<tenant-uuid>

两种模式的请求协议和反向代理要求参见租户配置。

创建公开上传软链接 ​

shell
php artisan storage:link

确认软链接指向正确目录：

text
public/uploads -> storage/uploads

租户初始化后，三个租户磁盘分别使用：

text
storage/uploads/tenant-{uuid}/...
storage/static/tenant-{uuid}/...
storage/certs/tenant-{uuid}/...

uploads 存放可公开访问的业务上传。static 和 certs 保持私有，不提供浏览器直连地址。密钥、证书和需要鉴权的文件应放在私有磁盘。

公开上传接口返回类似以下相对路径：

text
uploads/tenant-{uuid}/2026-07-18/attachments/example.jpg

页面使用以下地址访问：

text
/uploads/tenant-{uuid}/2026-07-18/attachments/example.jpg

重新发布前端页面 ​

升级包后只重新发布前端页面：

shell
php artisan catch:tenant:install --only-view

该命令只强制发布 web/src/views/tenancy，不会发布配置、执行迁移、运行 Seeder 或写入环境变量。

VITE_TENANCY_MODE=true 负责让管理端 API 使用当前页面源站的 /api 地址。VITE_TENANCY_IDENTIFICATION_MODE 负责租户页面的识别模式。租户上下文、Header 和 Token 的处理方式参见租户配置。修改 Vite 环境变量后需要重新启动开发服务或重新构建前端。

安装验证 ​

shell
php artisan migrate:status --path=database/migrations/tenancy
php artisan migrate:status --path=database/migrations/monitor
php artisan route:list --path=api/tenancy
php artisan route:list --name=stancl.tenancy.asset

最后检查：

  • 租户、套餐、队列监控和调度监控菜单可以访问。
  • web/src/views/tenancy 已发布。
  • VITE_TENANCY_IDENTIFICATION_MODE 与 TENANCY_IDENTIFICATION_MODE 一致。
  • public/uploads 软链接有效。
  • domain 模式可通过租户域名登录，或 shared_domain 模式可通过带租户 UUID 的入口登录。