bi-sys 系统管理服务
**本文引用的文件** - [[[[[go.mod]]]]](../file/bi-sys/go.mod) - [[[[[main.go]]]]](../file/bi-sys/cmd/bi-sys/main.go) - [[[[[rbac.go]]]]](../file/bi-sys/internal/middleware/rbac.go) - [[[[[user.go]]]]](../file/bi-sys/internal/biz/user.go) - [[[[[role.go]]]]](../file/bi-sys/internal/biz/role.go) - [[[[[menu.go]]]]](../file/bi-sys/internal/biz/menu.go) - [[[[[config.go]]]]](../file/bi-sys/internal/biz/config.go) - [[[[[log.go]]]]](../file/bi-sys/internal/biz/log.go) - [[[[[data.go]]]]](../file/bi-sys/internal/data/data.go) - [[[[[server.go]]]]](../file/bi-sys/internal/server/server.go) - [[[[[架构文档.md]]]]](../file/bi-sys/docs/architecture-bi-sys.md) - [[[[[user.proto]]]]](../file/bi-sys/api/sys/v1/user.proto) - [[[[[role.proto]]]]](../file/bi-sys/api/sys/v1/role.proto) - [[[[[menu.proto]]]]](../file/bi-sys/api/sys/v1/menu.proto) - [[[[[common.proto]]]]](../file/bi-sys/api/sys/v1/common.proto)
目录
简介
本文件为 bi-sys 系统管理服务的技术文档，聚焦系统管理能力的设计与实现，包括用户管理、菜单配置、角色权限、系统配置与日志审计等模块。文档深入解析基于 RBAC 的权限模型与菜单权限控制机制，阐述与 Nacos 配置中心的集成与热更新流程，并提供 API 接口说明、部署运维建议与常见问题排查方法。
项目结构
bi-sys 采用分层架构与 Wire 依赖注入，主要目录与职责如下：
- cmd/bi-sys: 应用入口，负责配置加载、服务注册、应用启动
- internal/biz: 业务用例层，封装用户、角色、菜单、配置、日志等业务逻辑
- internal/data: 数据访问层，封装数据库与缓存客户端，提供事务与上下文传播
- internal/middleware: 中间件层，如 RBAC 权限中间件
- internal/server: 服务层，提供 gRPC/HTTP 服务器装配
- api/sys/v1: Protobuf 定义与生成的 gRPC/HTTP 适配代码
- configs: 环境化配置文件，用于 Nacos 配置源
- docs: 架构与 PRD 文档
- k8s: Kubernetes 部署清单
图表来源
- [[[[main.go]]]]
- [[[[rbac.go]]]]
- [[[[user.go]]]]
- [[[[role.go]]]]
- [[[[menu.go]]]]
- [[[[config.go]]]]
- [[[[log.go]]]]
- [[[[data.go]]]]
- [[[[server.go]]]]
章节来源
核心组件
- 应用入口与配置加载：从 Nacos 加载环境化配置，初始化日志、雪花 ID、服务注册与 Wire 组装的服务实例
- 权限中间件：基于路径映射生成权限标识，结合用户权限缓存与数据库回退，实现统一 RBAC 校验
- 业务用例：用户、角色、菜单、配置、日志等 CRUD 与组合操作
- 数据访问：GORM 客户端与 Redis 客户端封装，提供事务与上下文透传
- 服务装配：gRPC/HTTP 服务器装配，配合 Nacos 注册
章节来源
- [[[[main.go]]]]
- [[[[rbac.go]]]]
- [[[[user.go]]]]
- [[[[role.go]]]]
- [[[[menu.go]]]]
- [[[[config.go]]]]
- [[[[log.go]]]]
- [[[[data.go]]]]
- [[[[server.go]]]]
架构总览
bi-sys 采用三层架构与微服务模式：
- 表层：gRPC/HTTP 接口由 service 层实现，经中间件进入业务用例
- 业务层：biz 用例处理业务规则（如密码哈希、菜单树组装、权限聚合）
- 数据层：data 层封装数据库与缓存，提供事务与上下文传播
图表来源
- [[[[rbac.go]]]]
- [[[[user.go]]]]
- [[[[role.go]]]]
- [[[[menu.go]]]]
- [[[[config.go]]]]
- [[[[log.go]]]]
- [[[[data.go]]]]
详细组件分析
RBAC 权限中间件
- 白名单路径支持精确匹配与前缀通配符
- 从请求上下文中提取用户信息；超级管理员直接放行
- 权限来源优先缓存（Redis），未命中则回源数据库并写回缓存
- 路径到权限标识映射：按 URL 路径第 3、4 段构造模块与资源名，去除复数后拼接冒号分隔
图表来源
章节来源
用户管理（CRUD）
- 支持创建、更新、删除、批量删除、分页查询、重置密码、启停状态、分配角色、查询角色列表
- 密码采用 bcrypt 哈希存储
- 分配角色时记录操作人，便于审计
图表来源
章节来源
角色管理（含菜单与数据权限）
- 支持创建、更新、删除、批量删除、分页查询、启用禁用、查询菜单列表、分配菜单、分配数据范围、查询权限集合
- 分配菜单与数据范围时记录操作人，便于审计
图表来源
章节来源
菜单管理
- 支持创建、更新、删除、查询详情、列表查询、按角色查询菜单树
- 删除时检查是否存在子节点，避免破坏树形结构
图表来源
章节来源
系统配置管理
- 支持创建、更新（字段合并防覆盖）、删除、批量删除、按 ID/Key 查询、分页查询
- 更新时对关键字段进行保护性合并，避免空值覆盖旧值
图表来源
章节来源
日志审计与操作追踪
- 登录日志：创建、删除、批量删除、清空、分页查询
- 操作日志：创建、删除、批量删除、清空、分页查询
- 提供统一的分页参数校验与日志落库
章节来源
数据访问与事务
- 提供数据库与 Redis 客户端封装，统一关闭资源
- 事务支持：InTx 将 gorm 事务注入上下文，后续 GetDB 优先返回事务句柄
- 事务内回调函数可安全访问数据库与缓存
图表来源
章节来源
服务装配与启动
- 使用 Wire 组合 gRPC/HTTP 服务器与注册器
- 通过 Nacos 配置源加载环境化配置，支持 dev/test/prod 环境切换
章节来源
依赖关系分析
更新 移除了对 bi-proto 模块的依赖，简化了服务间的通信方式
- 外部依赖：Kratos、Wire、GORM、Nacos SDK、Prometheus、OpenTelemetry 等
- 内部依赖：bi-common 提供通用鉴权、日志、注册发现、缓存、数据库等能力
- 依赖注入：通过 Wire 集成 server、data、biz、middleware 等模块
- 协议定义：直接使用本地 Protobuf 定义，不再依赖 bi-proto 模块
图表来源
章节来源
性能考量
- 权限缓存：RBAC 中间件优先从 Redis 读取用户权限，降低数据库压力
- 事务上下文：InTx 将事务绑定到上下文，减少重复连接与事务开销
- 分页参数：业务用例对分页参数进行默认值校正，避免无效查询
- 并发与进程：引入 automaxprocs，自动设置 GOMAXPROCS，提升并发性能
故障排除指南
- 权限相关
- 未登录：确认鉴权中间件是否正确注入，请求头是否携带有效令牌
- 无权限访问：检查路径到权限标识映射规则与用户权限缓存是否一致
- 超级管理员仍受限：确认用户上下文中的 IsSuper 标记是否正确传递
- 用户管理
- 创建失败：检查用户名唯一性校验与密码哈希过程
- 批量删除参数无效：确认传入的 ID 列表非空
- 角色管理
- 角色编码冲突：更新时检查唯一性约束
- 分配菜单失败：确认操作人 ID 正确且菜单存在
- 菜单管理
- 删除失败：确认菜单不存在子节点
- 配置管理
- 更新字段被清空：确认字段合并逻辑生效，避免空值覆盖
- 数据访问
- 事务未生效：确认回调中使用 GetDB 获取事务上下文
- 配置中心
- Nacos 配置未生效：确认环境参数与配置文件路径正确，且配置已推送
章节来源
- [[[[rbac.go]]]]
- [[[[user.go]]]]
- [[[[role.go]]]]
- [[[[menu.go]]]]
- [[[[config.go]]]]
- [[[[data.go]]]]
- [[[[main.go]]]]
结论
bi-sys 通过清晰的分层架构与中间件化权限控制，提供了完善的系统管理能力。RBAC 权限模型与菜单权限控制机制结合缓存与数据库双通道，兼顾性能与一致性。与 Nacos 的深度集成实现了配置热更新与环境隔离。移除 bi-proto 依赖后，服务间的通信更加直接高效。建议在生产环境中强化权限缓存失效策略与审计日志留存周期，并完善监控告警与容量规划。
附录
API 接口文档（概要）
- 用户管理
- 创建用户：POST /api/v1/sys/users
- 更新用户：PUT /api/v1/sys/users/
- 删除用户：DELETE /api/v1/sys/users/
- 批量删除：DELETE /api/v1/sys/users
- 分页查询：GET /api/v1/sys/users
- 重置密码：POST /api/v1/sys/users/{id}/reset-password
- 更新状态：POST /api/v1/sys/users/{id}/status
- 分配角色：POST /api/v1/sys/users/{id}/roles
- 获取角色列表：GET /api/v1/sys/users/{id}/roles
- 角色管理
- 创建角色：POST /api/v1/sys/roles
- 更新角色：PUT /api/v1/sys/roles/
- 删除角色：DELETE /api/v1/sys/roles/
- 批量删除：DELETE /api/v1/sys/roles
- 分页查询：GET /api/v1/sys/roles
- 启停状态：POST /api/v1/sys/roles/{id}/status
- 分配菜单：POST /api/v1/sys/roles/{id}/menus
- 分配数据范围：POST /api/v1/sys/roles/{id}/datascope
- 获取权限集合：GET /api/v1/sys/roles/{id}/permissions
- 菜单管理
- 创建菜单：POST /api/v1/sys/menus
- 更新菜单：PUT /api/v1/sys/menus/
- 删除菜单：DELETE /api/v1/sys/menus/
- 查询菜单：GET /api/v1/sys/menus/
- 菜单列表：GET /api/v1/sys/menus
- 角色菜单树：GET /api/v1/sys/menus/by-role/
- 配置管理
- 创建配置：POST /api/v1/sys/configs
- 更新配置：PUT /api/v1/sys/configs/
- 删除配置：DELETE /api/v1/sys/configs/
- 批量删除：DELETE /api/v1/sys/configs
- 查询配置：GET /api/v1/sys/configs/
- 按Key查询：GET /api/v1/sys/configs/key/
- 分页查询：GET /api/v1/sys/configs
- 日志管理
- 登录日志：CRUD 与分页
- 操作日志：CRUD 与分页
部署运维指南
- 环境准备
- 准备 Nacos 配置中心与服务注册中心
- 准备 MySQL 与 Redis
- 配置加载
- 通过 -env 参数选择 dev/test/prod，对应 configs 下的 application-{env}.yaml
- 确认 Nacos 配置项与本地配置一致
- 启动方式
- 使用 Kratos 服务框架启动，自动注册至 Nacos
- 监控与日志
- 开启 Prometheus 指标与 OpenTelemetry 链路追踪
- 使用 bi-common 日志组件输出结构化日志
章节来源
Protobuf 接口定义
- 用户管理接口定义详见 user.proto
- 角色管理接口定义详见 role.proto
- 菜单管理接口定义详见 menu.proto
- 通用类型定义详见 common.proto
章节来源