角色管理
角色管理用于维护用户权限集合。一个用户可以绑定多个角色；角色内可同时配置 API 权限、菜单权限和按钮权限。权限不足时，用户可能看不到菜单、看不到按钮，或调用接口时被拒绝。
先看术语
| 术语 | 现场理解 |
|---|---|
| 角色 | 一组权限集合，例如“只读监控”“运行维护”“项目管理员”。 |
| API 权限 | 后台接口调用权限。页面按钮可见但缺少 API 权限时，操作仍可能失败。 |
| 菜单权限 | 左侧导航和页面入口的可见权限。没有菜单权限时，用户通常看不到该页面。 |
| 按钮权限 | 页面内新增、编辑、删除、导出、授权等按钮的操作权限。 |
| 授权 | 给角色勾选 API、菜单和按钮权限的过程。 |
| 最小权限 | 只给完成工作必需的权限。生产环境不要把普通用户都配置成超级管理员。 |
页面入口
登录 GatewayRuntime Web 后，进入“系统管理 → 角色管理”。
授权前准备
- 明确该角色要完成的具体任务和禁止执行的高风险动作，按最小权限分配。
- 准备一个非管理员测试用户，避免直接用超级管理员账号判断授权是否生效。
- 调整现有角色前记录当前 API、菜单和按钮权限；生产环境的重要权限变更应保留审批依据。
页面结构
| 区域 | 说明 |
|---|---|
| 角色名称搜索 | 按角色名称过滤列表。 |
| 工具按钮 | 依次为新增、批量删除、刷新。批量删除需要先勾选角色。 |
| 角色列表 | 显示角色名称、描述、启用状态和操作按钮。 |
| 操作列 | 包含编辑、授权、复制和删除。超级管理员角色不可删除。 |
列表字段
| 字段 | 说明 |
|---|---|
| 角色名称 | 角色显示名称，也是用户分配角色时看到的名称。 |
| 描述 | 角色用途说明，例如“运行维护”“只读监控”“项目管理员”。 |
| 状态 | 已启用或已禁用。禁用角色不会继续提供权限。 |
| 操作 | 编辑、授权、复制、删除。 |
新增和编辑角色
点击新增按钮，或点击角色行的编辑按钮，打开角色配置抽屉。
| 配置项 | 说明 |
|---|---|
| 角色名称 | 必填。建议按职责命名，不要使用个人姓名作为长期角色名。 |
| 描述 | 可选。说明角色适用对象、权限边界和维护注意事项。 |
| 启用 | 控制角色是否生效。临时停用角色时可关闭此开关。 |
授权抽屉
点击角色行的授权按钮，打开“角色授权”抽屉。抽屉内包含“API 授权”和“菜单按钮授权”两个页签，底部提供“取消”“预览差异”“保存”。
API 授权
API 授权控制角色可以调用哪些服务接口。即使页面按钮可见，如果缺少对应 API 权限，接口调用仍可能失败。
| 区域 | 说明 |
|---|---|
| 搜索 API | 按权限编码、接口 URL 或描述过滤接口列表。 |
| 全选 | 选中当前 API 权限列表中的全部接口。 |
| 清空 | 清除当前 API 权限选择。 |
| 权限编码 | 业务权限标识，例如变量写入、用户维护、日志导出等。 |
| 接口 URL | 当前权限对应的接口路径。 |
| 描述 | 接口用途说明。 |
API 授权适合按功能最小化分配。例如只读监控角色通常只保留查询类接口；运维角色可增加写入、重启、导入导出和日志导出接口。
菜单按钮授权
菜单按钮授权控制用户能看到哪些菜单，以及菜单内哪些按钮可操作。
| 区域 | 说明 |
|---|---|
| 搜索菜单或按钮 | 按菜单名称、按钮名称过滤权限树。 |
| 全选 | 选中所有菜单和按钮节点。 |
| 清空 | 清除所有菜单和按钮选择。 |
| 菜单节点 | 控制左侧导航菜单和页面入口是否可见。 |
| 按钮节点 | 控制页面内新增、编辑、删除、导出、授权等按钮是否可见。 |
授权树中“菜单”和“按钮”使用不同标签标识。勾选菜单时应同时检查其下按钮，避免用户能进入页面但缺少必要操作按钮。
调试权限分层
采集配置和数据转发菜单下分别提供五个调试按钮权限。它们按风险逐级拆分，角色可以只获得查看或读取能力，不必同时拥有写入和控制能力。
| 按钮权限 | API 权限编码 | 适用范围 |
|---|---|---|
| 调试查看 | debug:view | 查看调试标签、对象概览、运行状态和脱敏摘要。 |
| 只读调试 | debug:query | 执行主动读取、节点浏览、状态查询和只读诊断。 |
| 普通调试写入 | debug:write | 普通点位写入、发布、订阅和低风险协议命令。 |
| 危险调试控制 | debug:dangerous | PLC 启停、复位、机器人运动、批量 IO、任意命令、删除数据集和断开客户端等高风险动作。 |
| 敏感调试数据 | debug:sensitive | 查看证书信任信息、身份信息等敏感调试内容。 |
授权时先在“菜单按钮授权”中勾选采集配置或数据转发下对应的调试按钮，再在“API 授权”中核对相同权限编码。默认用户角色只包含“调试查看”和“只读调试”；其余三项必须由管理员通过独立角色授予。
推荐拆分为以下角色：
| 角色 | 建议调试权限 |
|---|---|
| 只读调试 | 调试查看、只读调试。 |
| 普通写入 | 在只读调试基础上增加普通调试写入。 |
| 危险控制 | 按设备维护职责增加危险调试控制，不默认附带敏感数据。 |
| 敏感数据审查 | 按业务需要增加敏感调试数据，不默认附带写入或危险控制。 |
不要为了让一个按钮可用而勾选全部调试权限。危险控制和敏感数据属于不同职责，应分别审批、分别授权，并通过操作日志和审计日志复核使用记录。
预览差异与保存
点击“预览差异”后，抽屉底部会显示本次权限调整统计。
| 差异项 | 说明 |
|---|---|
| 新增菜单 / 取消菜单 | 本次保存后会新增或取消的菜单权限数量。 |
| 新增按钮 / 取消按钮 | 本次保存后会新增或取消的按钮权限数量。 |
| 新增 API / 取消 API | 本次保存后会新增或取消的接口权限数量。 |
确认差异无误后点击“保存”。保存后，已登录用户通常需要刷新页面或重新登录，才能看到最新菜单、按钮和接口权限效果。
复制角色
点击角色行的复制按钮，可基于已有角色创建新角色。复制适合以下场景：
| 场景 | 建议 |
|---|---|
| 创建相似职责 | 先复制已有角色，再增减少量权限。 |
| 临时授权 | 复制常用角色后单独增加临时权限，结束后禁用或删除。 |
| 权限对比 | 复制后通过“预览差异”确认调整范围。 |
复制角色后应立即修改角色名称和描述，避免多个角色用途难以区分。
常用角色建议
| 角色类型 | 权限建议 |
|---|---|
| 只读监控 | 系统总览、数据查询、实时报警、日志查询的只读 API 和菜单。 |
| 只读调试 | 只读监控基础上增加调试查看和只读调试，不包含写入、危险控制或敏感数据。 |
| 运维人员 | 只读调试基础上按职责增加普通调试写入、变量写入、日志导出和重启运行时等权限。 |
| 控制工程师 | 仅对需要维护的采集配置或数据转发范围增加危险调试控制，并保留现场审批记录。 |
| 配置管理员 | 采集配置、数据转发、脚本、节点、规则和插件维护权限。 |
| 安全管理员 | 用户管理、角色管理、菜单管理、审计日志权限。 |
常见问题与注意
| 场景 | 建议 |
|---|---|
| 超级管理员 | 超级管理员权限最高，应限制账号共享，并定期检查登录审计。 |
| API 与按钮不一致 | 只授权按钮但未授权 API 时，页面操作可能失败；只授权 API 但未授权按钮时，用户可能无法从页面触发。 |
| 删除角色 | 删除前先检查用户绑定关系，避免用户登录后没有可用权限。 |
| 批量删除 | 只对确定不用的普通角色执行，超级管理员角色不可删除。 |
| 权限调整审计 | 重要权限调整后查看系统日志中的审计记录。 |
验证结果
- 把角色绑定到测试用户，让测试用户刷新页面或重新登录。
- 检查目标菜单和按钮可见，未授权菜单和高风险按钮不可见。
- 执行一个允许的只读操作和一个职责内操作，确认接口不返回无权限。
- 尝试访问一个明确未授权的功能，确认页面或接口被拒绝。
- 返回管理员账号查看权限审计，确认变更角色、操作人和差异与本次调整一致。
只有“允许的能用、禁止的不能用、审计可追溯”同时满足时，角色授权才算完成。