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)

目录

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

简介

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

章节来源

• [go.mod]
• [架构文档.md]

核心组件

• 应用入口与配置加载：从 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 段构造模块与资源名，去除复数后拼接冒号分隔

图表来源

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

章节来源

• [rbac.go]

用户管理（CRUD）

• 支持创建、更新、删除、批量删除、分页查询、重置密码、启停状态、分配角色、查询角色列表
• 密码采用 bcrypt 哈希存储
• 分配角色时记录操作人，便于审计

图表来源

• [user.go]

章节来源

• [user.go]

角色管理（含菜单与数据权限）

• 支持创建、更新、删除、批量删除、分页查询、启用禁用、查询菜单列表、分配菜单、分配数据范围、查询权限集合
• 分配菜单与数据范围时记录操作人，便于审计

图表来源

• [role.go]

章节来源

• [role.go]

菜单管理

• 支持创建、更新、删除、查询详情、列表查询、按角色查询菜单树
• 删除时检查是否存在子节点，避免破坏树形结构

图表来源

• [menu.go]

章节来源

• [menu.go]

系统配置管理

• 支持创建、更新（字段合并防覆盖）、删除、批量删除、按 ID/Key 查询、分页查询
• 更新时对关键字段进行保护性合并，避免空值覆盖旧值

图表来源

• [config.go]

章节来源

• [config.go]

日志审计与操作追踪

• 登录日志：创建、删除、批量删除、清空、分页查询
• 操作日志：创建、删除、批量删除、清空、分页查询
• 提供统一的分页参数校验与日志落库

章节来源

• [log.go]

数据访问与事务

• 提供数据库与 Redis 客户端封装，统一关闭资源
• 事务支持：InTx 将 gorm 事务注入上下文，后续 GetDB 优先返回事务句柄
• 事务内回调函数可安全访问数据库与缓存

图表来源

• [data.go]

章节来源

• [data.go]

服务装配与启动

• 使用 Wire 组合 gRPC/HTTP 服务器与注册器
• 通过 Nacos 配置源加载环境化配置，支持 dev/test/prod 环境切换

章节来源

• [server.go]
• [main.go]

依赖关系分析

更新 移除了对 bi-proto 模块的依赖，简化了服务间的通信方式

• 外部依赖：Kratos、Wire、GORM、Nacos SDK、Prometheus、OpenTelemetry 等
• 内部依赖：bi-common 提供通用鉴权、日志、注册发现、缓存、数据库等能力
• 依赖注入：通过 Wire 集成 server、data、biz、middleware 等模块
• 协议定义：直接使用本地 Protobuf 定义，不再依赖 bi-proto 模块

图表来源

• [go.mod]

章节来源

• [go.mod]

性能考量

• 权限缓存：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 日志组件输出结构化日志

章节来源

• [main.go]
• [架构文档.md]

Protobuf 接口定义

• 用户管理接口定义详见 user.proto
• 角色管理接口定义详见 role.proto
• 菜单管理接口定义详见 menu.proto
• 通用类型定义详见 common.proto

章节来源

• [user.proto]
• [role.proto]
• [menu.proto]
• [common.proto]