架构与系统设计 / 系统课时
用户定位与同名账号
用户定位与同名账号
本课解决多租户系统中最常见的账号冲突:允许不同租户都存在 admin,同时保证同一租户内账号唯一,并通过联合索引和带租户条件的查询准确定位用户。
学习目标
- 理解用户账号的租户内唯一性边界
- 使用联合唯一索引阻止同租户重复账号
- 避免查询、缓存和认证过程发生跨租户命中
账号唯一性的正确边界
在单体用户系统中,账号通常全局唯一;在 SaaS 系统中,真实身份键应是 (tenant_id, username)。租户 A 的 admin 与租户 B 的 admin 是两个完全独立的用户,密码、角色和状态都不能互相影响。

因此,登录流程必须先把 tenantCode 转换为内部 tenantId,再使用 tenantId 和规范化后的账号共同查询。任何只按 username 获取第一条记录的实现都存在串租户风险。
建表与查询示例
下面的 MySQL 脚本创建最小用户表,并插入两个租户的同名账号。联合唯一索引 uk_tenant_username 允许跨租户重名,但会拒绝同一租户内重复账号。<HASH_A> 与 <HASH_B> 表示实际密码哈希值。
DROP TABLE IF EXISTS sys_user;
CREATE TABLE sys_user (
id BIGINT NOT NULL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
username VARCHAR(64) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
status TINYINT NOT NULL DEFAULT 1,
UNIQUE KEY uk_tenant_username (tenant_id, username)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO sys_user (id, tenant_id, username, password_hash)
VALUES
(101, 1001, 'admin', '<HASH_A>'),
(201, 2001, 'admin', '<HASH_B>');
SELECT id, tenant_id, username, status
FROM sys_user
WHERE tenant_id = 2001
AND username = 'admin';预期结果:查询只返回租户 2001 下的用户,不会命中租户 1001 的同名账号。
+-----+-----------+----------+--------+
| id | tenant_id | username | status |
+-----+-----------+----------+--------+
| 201 | 2001 | admin | 1 |
+-----+-----------+----------+--------+
1 row in set实际项目还应明确账号是否区分大小写。若业务规定不区分,应在写入和查询前统一执行去首尾空格、转小写,并让数据库字段排序规则与该规则保持一致,避免 Admin 与 admin 的行为在不同环境中变化。
查询与缓存的隔离规则
用户仓储方法应直接表达租户条件,例如 findByTenantIdAndUsername,不要提供容易被误用的 findByUsername。查询不到时返回统一认证失败,不应退回全局查询或尝试其他租户。
缓存键也必须包含租户标识,例如 user:1001:admin。若缓存键只有 user:admin,后登录的租户可能覆盖先登录租户的数据,即使数据库查询正确,认证结果仍会被缓存污染。
创建用户时不要先执行“查询是否存在”再插入作为唯一防线,因为并发请求可能同时通过检查。数据库联合唯一索引才是最终约束,应用层只负责把唯一键冲突转换为可理解的提示。
常见错误与修正
| 错误做法 | 风险 | 正确做法 |
|---|---|---|
username 建全局唯一索引 |
不同租户无法使用同名账号 | 建立 (tenant_id, username) 联合唯一索引 |
登录只按 username 查询 |
可能命中其他租户用户 | 先定位 tenantId,再联合查询 |
| 缓存键缺少租户标识 | 同名账号缓存互相覆盖 | 缓存键包含 tenantId |
| 先查重再插入 | 并发下仍可能重复 | 依赖数据库唯一约束兜底 |
验收用户定位
验收时应分别创建两个租户,并在两个租户中都创建 admin。两个账号应能使用各自密码登录;在同一租户再次创建 admin 时,数据库应拒绝写入。
还要检查所有用户查询、密码重试计数、登录失败锁定和用户缓存的键是否都包含租户维度。只要其中一个环节遗漏 tenantId,系统仍可能发生跨租户数据污染。
本课总结
- SaaS 用户的唯一身份由
tenantId与账号共同决定 - 联合唯一索引负责阻止同租户重复账号,并允许跨租户重名
- 查询、缓存、锁定和失败计数都必须携带租户维度
下一课预告
下一课将继续设计认证上下文,把登录令牌中的租户身份安全地传递到网关、接口和数据访问层。