必须在中间件最前端完成租户识别，通过$_SERVER['HTTP_X_FORWARDED_HOST']或$_SERVER['HTTP_HOST']提取子域名并绑定至App::instance()->tenant；动态重置数据库连接需调用config()更新配置并执行Db::clearConnection('tenant')；模型层须用全局作用域强制tenant_id过滤；缓存、Session、配置及静态资源均须按域名隔离。
一、在中间件最前端完成租户识别
租户识别是整个多租户链路的起点，必须在请求生命周期最早期执行，否则模型事件、日志记录、缓存写入等操作可能已基于错误上下文完成，导致数据泄露或上下文错乱。该步骤严禁依赖 session、cookie 或 URL 参数，因其在 CLI 命令、队列任务、定时器等场景中不可用且易被篡改。
1、创建 app/middleware/CheckTenant.php 中间件文件，并确保其注册于 app/middleware.php 的首位（即最顶部）。
2、在 handle() 方法中，优先读取 $_SERVER['HTTP_X_FORWARDED_HOST']（适用于 Nginx/Apache 反向代理环境），若不存在则回退至 $_SERVER['HTTP_HOST']。
3、使用正则匹配提取子域名，例如：/^([a-z0-9\-]+)\.example\.com$/i，捕获组 $matches[1] 即为租户标识符。
立即学习“PHP免费学习笔记（深入）”；
4、对提取出的租户标识符执行合法性清洗：去除非法字符（如 @、.、/），替换为下划线，并限制长度不超过 64 字符，推荐使用 preg_replace('/[^a-zA-Z0-9_]/', '_', $rawId) 后拼接前缀 'tenant_' . $safeId。
5、将清洗后的租户 ID 绑定至可信上下文，调用 think\facade\App::instance()->tenant = $tenantId，禁止写入全局变量或 session。
二、动态重置数据库连接并强制重建
ThinkPHP 的数据库连接采用懒初始化与连接池复用机制，仅修改配置项不会触发实际连接切换；旧连接仍指向默认库，造成查不到数据、写入公共库等典型故障。必须在模型查询发生前完成配置更新与连接池清理。
1、在 CheckTenant.php 的 handle() 方法中，根据租户 ID 构建完整数据库连接配置数组，其中 'database' 字段必须为合法库名（如 'db_tenant1'），不得仅为前缀。
2、调用 config(['database.connections.tenant' => $config]) 覆盖连接配置，连接名统一设为 'tenant'。
3、立即执行 Db::clearConnection('tenant') 清空指定连接缓存，确保后续 Db::connect('tenant') 或模型调用时重新初始化连接。
4、所有业务模型必须显式声明 protected $connection = 'tenant';，禁止使用 Db::table() 绕过模型连接配置。
5、同步更新 PDO 配置中的 'charset' 与 'prefix'，避免跨租户表前缀错位引发 Table not found 错误。
三、通过全局作用域强制 tenant_id 过滤
即使数据库连接正确，ThinkPHP 模型本身不感知租户，User::find(1) 仍可能返回其他租户的数据。这是框架设计使然，非 Bug。必须通过全局作用域在所有查询构建器中自动注入 tenant_id 条件，实现强制数据隔离。
1、定义租户作用域类 app/model/scope/TenantScope.php，实现 think\Model\ScopeInterface 接口。
2、在 apply() 方法中，从 think\facade\App::instance()->tenant 获取租户 ID，并调用 $builder->where('tenant_id', $tenantId)。
3、在基模型 app/model/BaseModel.php 的 boot() 方法中，调用 static::addGlobalScope('tenant', new \app\model\scope\TenantScope()) 注册该作用域。
4、关联查询（with()）默认不继承主模型租户条件，须在关联定义中显式添加 ->where('tenant_id', $this->tenantId)。
5、禁止在业务逻辑中调用 withoutGlobalScope('tenant') 以外的方式绕过过滤；如确需跨租户操作，应限定于超级管理员模式并严格校验权限。
四、按域名隔离缓存、Session 与配置
多域名部署下，若缓存键、Session 名称、配置文件未做域名区分，将导致 A 域名覆盖 B 域名数据、路由错乱、配置混用等严重问题。必须在应用初始化早期注入域名标识，实现物理级命名空间隔离。
1、在 app/common.php 或自定义初始化逻辑中，获取当前域名：$domain = request()->host();，并生成唯一缓存前缀：'cache_' . str_replace('.', '_', $domain)。
2、所有缓存操作必须显式携带域名前缀，例如：cache('user_123_' . $domain, $data, 3600)；禁用框架默认缓存键生成逻辑。
3、Session 名称需动态设置，在 app/middleware/CheckTenant.php 中调用 session_name('sess_' . str_replace('.', '_', $domain))。
4、配置文件按域名加载：禁用 config_cache，改用 Config::load(config_path() . 'site/' . $domain . '.php') 加载对应域名专属配置。
5、路由注册不依赖静态缓存，而在 app/route.php 中根据 request()->host() 动态引入不同路由文件，例如：require config_path() . 'route/' . $domain . '.php';。
五、泛域名下的子站点动态识别与资源隔离
泛域名部署（如 *.example.com）要求系统能自动识别任意合法子域名，并为其分配独立数据库、缓存前缀、模板路径及静态资源目录。硬编码或环境变量切换无法满足动态性需求，必须在应用初始化阶段完成识别与配置覆盖。
1、在 app/common.php 或 app/middleware/CheckTenant.php 中，使用正则提取子域名：if (preg_match('/^([a-z0-9\-]+)\.example\.com$/i', $host, $matches)) { $siteName = $matches[1]; }。
2、数据库配置动态拼接：'database' => 'db_' . $siteName，并确保该库名经过去非法字符处理，符合 MySQL 库名规范。
3、模板路径按站点隔离：在视图配置中设置 'view_path' => app_path() . 'view/' . $siteName . '/'，各子站点拥有独立视图目录。
4、静态资源路径也需区分，例如在模板中输出 CSS 路径时使用：<link rel="stylesheet" href="/static/css/' . $siteName . '/main.css">。
5、Redis 缓存建议按域名使用不同 database（如 select 1 for site_a, select 2 for site_b），或在所有 key 前统一加 site_a: 前缀，避免 flushdb 误清全量缓存。
