bi-tenant 租户管理服务

**本文引用的文件** - [[[[[go.mod]]]]](../file/bi-tenant/go.mod) - [[[[[main.go]]]]](../file/bi-tenant/cmd/bi-tenant/main.go) - [[[[[wire.go]]]]](../file/bi-tenant/cmd/bi-tenant/wire.go) - [[[[[conf.proto]]]]](../file/bi-tenant/internal/conf/conf.proto) - [[[[[tenant.go]]]]](../file/bi-tenant/internal/biz/tenant.go) - [[[[[user.go]]]]](../file/bi-tenant/internal/biz/user.go) - [[[[[role.go]]]]](../file/bi-tenant/internal/biz/role.go) - [[[[[org.go]]]]](../file/bi-tenant/internal/biz/org.go) - [[[[[tenant.go]]]]](../file/bi-tenant/internal/data/tenant.go) - [[[[[rbac.go]]]]](../file/bi-tenant/internal/server/rbac.go) - [[[[[tenant.go]]]]](../file/bi-tenant/internal/service/tenant.go) - [[[[[auth.proto]]]]](../file/bi-tenant/api/tenant/v1/auth.proto) - [[[[[org.proto]]]]](../file/bi-tenant/api/tenant/v1/org.proto) - [[[[[role.proto]]]]](../file/bi-tenant/api/tenant/v1/role.proto) - [[[[[profile.proto]]]]](../file/bi-tenant/api/tenant/v1/profile.proto) - [[[[[log.proto]]]]](../file/bi-tenant/api/tenant/v1/log.proto) - [[[[[tenant.proto]]]]](../file/bi-tenant/api/tenant-m/v1/tenant.proto)

更新摘要

所做更改

• 更新了依赖分析部分，反映移除对 bi-proto 模块的依赖
• 新增了 bi-tenant-m 管理端 API 的详细说明
• 更新了服务架构图，体现新的 API 分层结构
• 完善了租户管理服务的完整依赖关系描述

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件为 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]]]]

章节来源

• [[[[main.go]]]]
• [[[[wire.go]]]]
• [[[[conf.proto]]]]

核心组件

• 应用启动与依赖注入：通过 Kratos App 启动 gRPC/HTTP 服务，结合 Nacos 注册与配置中心，完成服务发现与动态配置加载。
• 业务用例（biz）：封装租户、用户、角色、组织等核心领域逻辑，负责编排数据仓库与事务策略。
• 数据仓库（data）：基于 GORM 访问 MySQL，提供 CRUD、聚合查询与统计能力。
• 服务适配（service）：将 Protobuf 请求映射到 biz 用例，并输出 Protobuf 响应。
• RBAC 权限：统一权限提供者，支持本地权限与 bi-sys RPC 权限的组合模式。

章节来源

• [[[[main.go]]]]
• [[[[tenant.go]]]]
• [[[[tenant.go]]]]
• [[[[tenant.go]]]]
• [[[[rbac.go]]]]

架构总览

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]]]]

详细组件分析

多租户架构与租户生命周期

• 租户创建：自动生成租户编码、创建默认组织、创建超管用户；可选绑定套餐并创建订阅记录。
• 租户更新/删除/批量删除：软删除策略，保留审计痕迹。
• 租户查询：支持按名称、联系方式、状态、套餐等条件分页查询；支持下拉选项查询。
• 租户状态与套餐：通过订阅表维护最新有效套餐，支持套餐变更与到期统计。

图示来源

• [[[[tenant.go]]]]
• [[[[tenant.go]]]]
• [[[[tenant.go]]]]
• [[[[tenant.go]]]]

章节来源

• [[[[tenant.go]]]]
• [[[[tenant.go]]]]
• [[[[tenant.go]]]]

用户与角色管理

• 用户管理：用户名唯一性校验、密码加密存储、默认账户保护、状态与管理员标识管理、角色/门店/委托人分配。
• 角色管理：角色编码唯一性校验、菜单与模板授权、权限集合获取、角色与用户的绑定关系维护。
• 组织架构：树形组织结构构建（祖先链），父子关系约束，禁止删除仍有子节点或用户的组织。

图示来源

• [[[[user.go]]]]
• [[[[user.go]]]]
• [[[[role.go]]]]
• [[[[org.go]]]]

章节来源

• [[[[user.go]]]]
• [[[[role.go]]]]
• [[[[org.go]]]]

权限模型与认证流程（RBAC + JWT）

• 权限提供者：本地权限提供者根据用户角色聚合权限；组合提供者在管理端通过 bi-sys RPC 获取权限，客户端使用本地权限。
• 权限聚合：对角色权限进行去重合并；提供统一的权限查询接口。
• API 路径识别：通过请求路径判断是否为管理端 API，从而选择不同的权限来源。
• 与 bi-sys 集成：管理端 API 在 RBAC 中间件中调用 bi-sys 的权限 RPC，实现跨服务权限校验。

图示来源

• [[[[rbac.go]]]]
• [[[[rbac.go]]]]

章节来源

• [[[[rbac.go]]]]
• [[[[rbac.go]]]]

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：用户操作日志

章节来源

• [[[[tenant.go]]]]
• [[[[auth.proto]]]]
• [[[[org.proto]]]]
• [[[[role.proto]]]]
• [[[[profile.proto]]]]
• [[[[log.proto]]]]
• [[[[tenant.proto]]]]

与 bi-sys 系统的集成与数据同步

• 鉴权集成：管理端 API 通过 RBAC 中间件调用 bi-sys 的权限 RPC，实现统一鉴权。
• 数据同步：租户侧通过订阅表维护套餐与有效期，结合统计接口输出运营指标；用户侧通过角色/菜单/模板授权实现细粒度权限控制。

图示来源

• [[[[rbac.go]]]]
• [[[[tenant.go]]]]

章节来源

• [[[[rbac.go]]]]
• [[[[tenant.go]]]]

租户迁移、备份恢复与安全防护最佳实践

• 租户迁移
  • 数据迁移：导出租户、用户、角色、组织、订阅等核心表，按祖先链重建组织树，确保角色与权限映射一致。
  • 配置迁移：Nacos 配置与服务注册信息需同步迁移至目标集群。
• 备份恢复
  • 定期全量备份 MySQL；对租户关键表（租户、用户、角色、订阅）进行增量备份；建立恢复演练流程。
• 安全防护
  • 密码加密：统一使用 bcrypt 存储用户密码；默认账户禁止删除与重置。
  • 权限最小化：基于 RBAC 的权限最小授权；定期审计角色与权限映射。
  • 传输安全：启用 TLS；限制管理端 API 的访问范围与白名单。

依赖分析

更新 bi-tenant 服务已移除对 bi-proto 模块的直接依赖，采用更加灵活的本地 API 定义方式。服务现在主要依赖 bi-common 模块提供基础设施支持。

bi-tenant 依赖 bi-common 提供的日志、注册、配置、JWT、RBAC 中间件与通用工具模块；使用 Kratos 作为微服务框架，GORM 访问 MySQL，Nacos 作为注册与配置中心。

图示来源

• [[[[go.mod]]]]
• [[[[main.go]]]]

章节来源

• [[[[go.mod]]]]
• [[[[main.go]]]]

性能考虑

• 数据库优化
  • 对常用查询字段（租户名、手机号、状态、套餐）建立索引；分页查询使用覆盖索引减少回表。
  • 统计查询使用子查询与聚合函数，避免大结果集扫描。
• 缓存策略
  • 对热点租户信息与套餐信息进行缓存；权限聚合结果可短期缓存以降低重复计算。
• 并发与连接
  • 合理配置数据库连接池与最大并发；对高并发接口进行限流与熔断。
• 日志与追踪
  • 使用统一日志与 OpenTelemetry 追踪，定位慢查询与异常请求。

故障排查指南

• 租户创建失败
  • 检查租户编码是否重复；确认默认组织与超管用户创建是否成功；订阅创建失败不影响租户主流程但需关注日志。
• 用户操作被拒
  • 确认是否为默认账户；检查角色与权限是否正确分配；核对管理端 API 是否正确路由到 bi-sys RPC。
• 权限异常
  • 核对 RBAC 中间件的 API 路径识别逻辑；检查本地权限提供者与 bi-sys RPC 的返回一致性。
• 统计异常
  • 检查订阅表的有效性与到期时间；确认统计查询的子查询逻辑与时间点。

章节来源

• [[[[tenant.go]]]]
• [[[[user.go]]]]
• [[[[rbac.go]]]]
• [[[[tenant.go]]]]

结论

bi-tenant 通过清晰的分层架构与 RBAC 权限模型，实现了多租户场景下的租户管理、组织架构与权限控制能力。更新 服务架构的演进体现了从集中式 API 管理向本地化 API 设计的转变，移除了对 bi-proto 的依赖，提高了服务的独立性和可维护性。结合 bi-sys 的统一鉴权与 Nacos 的动态配置，满足了生产环境的可用性与可运维性要求。建议在实际落地中重点关注数据一致性、权限最小化与安全合规，并完善自动化运维与监控体系。

附录

• 部署配置
  • 使用 Nacos 作为配置中心与服务注册；通过 Kratos App 启动服务；按环境加载 application-{env}.yaml。
• 监控告警
  • 基于 OpenTelemetry 收集指标与日志；设置关键接口延迟与错误率阈值告警；对租户创建、套餐变更等关键事件进行审计与告警。

章节来源

• [[[[main.go]]]]
• [[[[conf.proto]]]]