bi-tenant 租户管理服务
更新摘要
所做更改
- 更新了依赖分析部分，反映移除对 bi-proto 模块的依赖
- 新增了 bi-tenant-m 管理端 API 的详细说明
- 更新了服务架构图，体现新的 API 分层结构
- 完善了租户管理服务的完整依赖关系描述
目录
简介
本文件为 bi-tenant 租户管理服务的技术文档，聚焦于多租户架构的设计与实现，涵盖租户隔离、资源分配与权限控制；用户认证与授权流程（含 JWT 令牌机制与 RBAC 权限模型）；租户配置管理、组织架构管理与订阅服务集成；API 接口规范（用户管理、角色分配与权限验证）；与 bi-sys 系统的集成关系与数据同步机制；以及租户迁移、备份恢复与安全防护的最佳实践，最后提供部署配置与监控告警的实施方案。
更新 本版本反映了 bi-tenant 服务架构的重大调整，移除了对 bi-proto 模块的依赖，采用了更加灵活的 API 设计模式。
项目结构
bi-tenant 采用 Kratos 微服务框架，按领域驱动分层组织代码：
- cmd：应用入口与依赖注入装配
- internal：业务域（biz）、数据访问（data）、服务适配（service）、服务器（server）、中间件（middleware）、配置（conf）
- api：Protobuf 定义与生成的 gRPC/HTTP 适配
- configs：运行时配置（Nacos）
图示来源
- [main.go]
- [wire.go]
- [conf.proto]
- [tenant.go]
- [user.go]
- [role.go]
- [org.go]
- [tenant.go]
- [tenant.go]
- [rbac.go]
- [auth.proto]
- [org.proto]
- [role.proto]
- [profile.proto]
- [log.proto]
- [tenant.proto]
章节来源
核心组件
- 应用启动与依赖注入：通过 Kratos App 启动 gRPC/HTTP 服务，结合 Nacos 注册与配置中心，完成服务发现与动态配置加载。
- 业务用例（biz）：封装租户、用户、角色、组织等核心领域逻辑，负责编排数据仓库与事务策略。
- 数据仓库（data）：基于 GORM 访问 MySQL，提供 CRUD、聚合查询与统计能力。
- 服务适配（service）：将 Protobuf 请求映射到 biz 用例，并输出 Protobuf 响应。
- RBAC 权限：统一权限提供者，支持本地权限与 bi-sys RPC 权限的组合模式。
章节来源
架构总览
bi-tenant 以"领域用例 + 数据仓库 + 服务适配 + 服务器中间件"的分层架构实现多租户能力，配合 Nacos 实现服务注册与配置下发，支持 gRPC/HTTP 双栈对外暴露。更新 服务现在采用双 API 层设计：tenant 客户端 API 和 tenant-m 管理端 API，分别服务于前端应用和后台管理系统。
图示来源
- [main.go]
- [tenant.go]
- [rbac.go]
- [auth.proto]
- [org.proto]
- [role.proto]
- [profile.proto]
- [log.proto]
- [tenant.proto]
详细组件分析
多租户架构与租户生命周期
- 租户创建：自动生成租户编码、创建默认组织、创建超管用户；可选绑定套餐并创建订阅记录。
- 租户更新/删除/批量删除：软删除策略，保留审计痕迹。
- 租户查询：支持按名称、联系方式、状态、套餐等条件分页查询；支持下拉选项查询。
- 租户状态与套餐：通过订阅表维护最新有效套餐，支持套餐变更与到期统计。
图示来源
章节来源
用户与角色管理
- 用户管理：用户名唯一性校验、密码加密存储、默认账户保护、状态与管理员标识管理、角色/门店/委托人分配。
- 角色管理：角色编码唯一性校验、菜单与模板授权、权限集合获取、角色与用户的绑定关系维护。
- 组织架构：树形组织结构构建（祖先链），父子关系约束，禁止删除仍有子节点或用户的组织。
图示来源
章节来源
权限模型与认证流程（RBAC + JWT）
- 权限提供者：本地权限提供者根据用户角色聚合权限；组合提供者在管理端通过 bi-sys RPC 获取权限，客户端使用本地权限。
- 权限聚合：对角色权限进行去重合并；提供统一的权限查询接口。
- API 路径识别：通过请求路径判断是否为管理端 API，从而选择不同的权限来源。
- 与 bi-sys 集成：管理端 API 在 RBAC 中间件中调用 bi-sys 的权限 RPC，实现跨服务权限校验。
图示来源
章节来源
API 接口文档（节选）
以下为租户相关 API 的请求/响应字段说明（以 Protobuf 定义为准）。具体字段含义请参考对应 pb 文件。
租户客户端 API（tenant/v1）
- 认证管理
- Login：用户登录获取 JWT 令牌
- Logout：用户登出
- GetUserInfo：获取当前用户信息
- GetUserMenus：获取用户菜单权限
- RefreshToken：刷新访问令牌
- GetCaptcha：获取图形验证码
- InitBi：BI 系统初始化数据
- SetFavorite/GetFavorite：收藏菜单管理
租户管理端 API（tenant-m/v1）
租户管理
- ListTenant：分页查询租户列表，支持按名称、手机号、状态、套餐过滤
- GetTenant：按 ID 获取租户详情
- CreateTenant：创建租户并返回管理员账号与初始密码
- UpdateTenant/UpdateTenantStatus/UpdateTenantPackage/DeleteTenant/BatchDeleteTenant：更新状态、套餐、删除租户
- ListTenantOptions：获取租户下拉选项
- GetTenantStats：获取租户统计指标
用户管理
- CreateTenantUser / UpdateTenantUser / DeleteTenantUser / BatchDeleteTenantUser：用户增删改查
- ResetTenantUserPassword：重置用户密码
- AssignTenantUserRole / AssignTenantUserStore / AssignTenantUserDelegate：角色/门店/委托分配
角色管理
- CreateTenantRole / UpdateTenantRole / DeleteTenantRole / BatchDeleteTenantRole：角色增删改查
- AssignTenantRoleMenu / AssignTenantRoleTemplate：菜单与模板授权
- GetTenantRolePermissions：获取角色权限集合
组织管理
- CreateTenantOrg / UpdateTenantOrg / DeleteTenantOrg：组织增删改
- ListTenantOrg / ListTenantOrgOptions：组织查询与下拉
个人资料与日志
- GetTenantUserProfile / UpdateTenantUserProfile：用户资料
- ListTenantUserLog：用户操作日志
章节来源
与 bi-sys 系统的集成与数据同步
- 鉴权集成：管理端 API 通过 RBAC 中间件调用 bi-sys 的权限 RPC，实现统一鉴权。
- 数据同步：租户侧通过订阅表维护套餐与有效期，结合统计接口输出运营指标；用户侧通过角色/菜单/模板授权实现细粒度权限控制。
图示来源
章节来源
租户迁移、备份恢复与安全防护最佳实践
- 租户迁移
- 数据迁移：导出租户、用户、角色、组织、订阅等核心表，按祖先链重建组织树，确保角色与权限映射一致。
- 配置迁移：Nacos 配置与服务注册信息需同步迁移至目标集群。
- 备份恢复
- 定期全量备份 MySQL；对租户关键表（租户、用户、角色、订阅）进行增量备份；建立恢复演练流程。
- 安全防护
- 密码加密：统一使用 bcrypt 存储用户密码；默认账户禁止删除与重置。
- 权限最小化：基于 RBAC 的权限最小授权；定期审计角色与权限映射。
- 传输安全：启用 TLS；限制管理端 API 的访问范围与白名单。
依赖分析
更新 bi-tenant 服务已移除对 bi-proto 模块的直接依赖，采用更加灵活的本地 API 定义方式。服务现在主要依赖 bi-common 模块提供基础设施支持。
bi-tenant 依赖 bi-common 提供的日志、注册、配置、JWT、RBAC 中间件与通用工具模块；使用 Kratos 作为微服务框架，GORM 访问 MySQL，Nacos 作为注册与配置中心。
图示来源
章节来源
性能考虑
- 数据库优化
- 对常用查询字段（租户名、手机号、状态、套餐）建立索引；分页查询使用覆盖索引减少回表。
- 统计查询使用子查询与聚合函数，避免大结果集扫描。
- 缓存策略
- 对热点租户信息与套餐信息进行缓存；权限聚合结果可短期缓存以降低重复计算。
- 并发与连接
- 合理配置数据库连接池与最大并发；对高并发接口进行限流与熔断。
- 日志与追踪
- 使用统一日志与 OpenTelemetry 追踪，定位慢查询与异常请求。
故障排查指南
- 租户创建失败
- 检查租户编码是否重复；确认默认组织与超管用户创建是否成功；订阅创建失败不影响租户主流程但需关注日志。
- 用户操作被拒
- 确认是否为默认账户；检查角色与权限是否正确分配；核对管理端 API 是否正确路由到 bi-sys RPC。
- 权限异常
- 核对 RBAC 中间件的 API 路径识别逻辑；检查本地权限提供者与 bi-sys RPC 的返回一致性。
- 统计异常
- 检查订阅表的有效性与到期时间；确认统计查询的子查询逻辑与时间点。
章节来源
结论
bi-tenant 通过清晰的分层架构与 RBAC 权限模型，实现了多租户场景下的租户管理、组织架构与权限控制能力。更新 服务架构的演进体现了从集中式 API 管理向本地化 API 设计的转变，移除了对 bi-proto 的依赖，提高了服务的独立性和可维护性。结合 bi-sys 的统一鉴权与 Nacos 的动态配置，满足了生产环境的可用性与可运维性要求。建议在实际落地中重点关注数据一致性、权限最小化与安全合规，并完善自动化运维与监控体系。
附录
- 部署配置
- 使用 Nacos 作为配置中心与服务注册；通过 Kratos App 启动服务；按环境加载 application-{env}.yaml。
- 监控告警
- 基于 OpenTelemetry 收集指标与日志；设置关键接口延迟与错误率阈值告警；对租户创建、套餐变更等关键事件进行审计与告警。
章节来源