架构与系统设计 / 系统课时
租户登录入口设计
租户登录入口设计
本课完成一个可落地的租户登录入口:明确租户编码、账号、密码与验证码的职责,确定后端校验顺序,并给出可直接联调的请求协议与验收标准。
学习目标
- 设计稳定、可扩展的租户登录参数
- 理解验证码、租户和用户的正确校验顺序
- 完成登录接口联调并验证返回结果
登录参数如何划分
租户登录不能只提交账号和密码,因为同一个账号名可能同时存在于多个租户。最小登录请求应包含 tenantCode、username、password、captchaKey 和 captchaCode。
| 参数 | 是否必填 | 作用 |
|---|---|---|
tenantCode |
是 | 将请求定位到唯一租户,建议使用不可变编码 |
username |
是 | 在当前租户内定位用户 |
password |
是 | 完成身份凭证校验 |
captchaKey |
是 | 关联服务端保存的验证码记录 |
captchaCode |
是 | 防止脚本批量尝试登录 |
租户名称可能被修改,也可能重复,不适合作为登录标识。租户编码应在创建租户时生成,并限制为小写字母、数字和短横线等稳定字符。
登录请求与处理顺序
后端应先验证请求格式和验证码,再检查租户状态,最后在租户范围内查询用户并校验密码。验证成功后签发令牌,令牌中至少保存 tenantId 和 userId,后续请求不能再次依赖前端传入的租户编码。

以下以 /api/auth/login 作为约定接口。将 <HOST>、<ID> 和验证码替换为实际值后即可发起联调请求。
curl -s -X POST "https://<HOST>/api/auth/login" \
-H "Content-Type: application/json" \
-d '{
"tenantCode": "acme",
"username": "admin",
"password": "P@ssw0rd!",
"captchaKey": "<ID>",
"captchaCode": "7284"
}'预期结果:接口返回成功状态,并按约定响应结构返回令牌、租户标识和用户标识。令牌值及 ID 会因环境不同而变化。
{
"code": 0,
"message": "success",
"data": {
"accessToken": "<TOKEN>",
"tenantId": "<ID>",
"userId": "<ID>"
}
}安全与交互边界
登录失败时不应分别提示“租户不存在”或“用户不存在”,否则攻击者可以枚举有效租户和账号。对外统一返回“账号或密码错误”,内部日志再记录具体失败阶段。
验证码应一次性消费并设置较短有效期。登录限流建议同时组合 IP、租户编码和账号,避免只限制单个维度。密码只能通过 HTTPS 传输,服务端必须使用安全哈希算法保存,不能记录明文密码或完整登录请求。
前端可以记住最近使用的租户编码,但不应记住密码。租户编码输入框可执行去首尾空格和转小写处理,后端仍需重复规范化,避免不同客户端产生不一致结果。
验收登录入口
完成实现后,应至少验证以下场景:
- 正确租户、账号、密码和验证码能够获得令牌
- 验证码错误、过期或重复使用时登录失败
- 租户被停用后,其全部用户都不能登录
- 相同账号名在不同租户下可以分别登录
- 失败响应不暴露租户或用户是否真实存在
本课总结
- 租户编码决定用户查询边界,不能用可变的租户名称替代
- 登录应按“验证码、租户、用户、密码、令牌”的顺序处理
- 令牌必须固化
tenantId,后续业务不能信任客户端重复传入的租户身份
下一课预告
下一课将把登录参数落到用户查询上,设计租户内唯一约束,并解决不同租户使用同名账号时的定位问题。