📄 系统多租户使用

PigX 多租户实现方式

• 多个租户共享同一个数据库(Database)和模式(Schema)
• 通过表中的 TenantID 字段区分不同租户的数据
• 系统会自动维护租户 ID，开发时无需手动处理

使用方法

1. 数据表配置

在需要支持多租户的表中添加 tenant_id 字段:

2. 租户隔离配置

有两种配置方式：

方式一：使用注解（v5.4+）

在实体类上添加注解：

@TenantTable

方式二：YAML 配置

在对应微服务的 nacos 配置中添加：

pigx:
  tenant:
    column: tenant_id  # 租户ID字段名
    tables:           # 需要进行租户隔离的表
      - sys_user

高级用法

手动切换租户

注意事项

禁止在实体对象中直接设置 tenant 字段，这会导致错误

正确的切换方式是使用 TenantContextHolder：

TenantContextHolder.setTenantId(tenantId);

跳过租户过滤

在需要查询所有租户数据时：

TenantContextHolder.setTenantSkip();

示例：

域名自动匹配功能

什么是域名自动匹配

域名自动匹配是指系统能够根据访问的域名自动识别并切换到对应的租户环境。例如，当用户通过 tenant1.example.com 访问系统时，PigX 会自动识别这是租户1的域名，并将当前请求的租户上下文切换到租户1，从而实现不同租户数据的自动隔离。

这种方式使得多租户系统可以通过不同的域名入口提供服务，无需用户手动选择租户，提升了用户体验。

配置方法

1. 在租户管理中配置租户对应的域名：

2. 在前端开启域名匹配功能：

技术实现原理

系统基于 MyBatis-Plus 的多租户 SQL 解析器 (opens new window)实现，主要包含：

1. 租户 ID 传递

通过全局过滤器获取并存储租户 ID：

public class TenantContextHolderFilter extends GenericFilterBean {
    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) {
        // 从请求头获取租户ID
        String tenantId = request.getHeader(CommonConstants.TENANT_ID);
        
        // 设置租户上下文
        if (StrUtil.isNotBlank(tenantId)) {
            TenantContextHolder.setTenantId(Integer.parseInt(tenantId));
        } else {
            TenantContextHolder.setTenantId(CommonConstants.TENANT_ID_1);
        }
        
        filterChain.doFilter(request, response);
        TenantContextHolder.clear();
    }
}

2. 跨线程租户信息传递

使用阿里巴巴的 TransmittableThreadLocal 实现：

public class TenantContextHolder {
    private final ThreadLocal<Integer> THREAD_LOCAL_TENANT = new TransmittableThreadLocal<>();
}