3、系统管理员角色：系统管理员职责、系统设置、邮件服务器配置、OAuth2.0配置
系统管理员（System Administrator）是 ThingsBoard 平台中权限最高的角色，负责整个平台的全局运维、基础配置与安全策略。与租户管理员仅管理单个租户范围不同，系统管理员的操作会直接影响所有租户及系统级功能。本章将详细解析系统管理员的职责边界、核心系统设置、邮件服务器集成以及 OAuth2.0 单点登录配置。
3.1 系统管理员职责与权限边界
系统管理员拥有对平台最高级别的控制权，其核心职责包括但不限于：
- 租户生命周期管理：创建、激活、挂起或删除租户账户。
- 系统级配置：管理邮件服务器、OAuth2.0、SMTP、系统安全设置。
- 全局监控：查看系统健康状态、资源使用率、审计日志。
- 管理员账户管理：创建或禁用其他系统管理员账户。
- 版本升级与维护：管理平台更新、备份与恢复策略。
权限边界提示： 系统管理员无法直接操作租户内部的数据实体（如设备、资产、仪表板），但可以查看所有租户的元数据信息（如租户名称、状态、创建时间）。数据层面的完全隔离由租户管理员负责。
3.2 系统设置核心面板
系统管理员登录后，通过顶部导航栏进入“系统设置”模块。该模块集中管理平台的基础运行参数。下表列出了关键配置项及其说明：
| 配置类别 | 配置项 | 说明 |
|---|---|---|
| 基础 | 平台标题 | 自定义浏览器标签页标题及系统内显示名称 |
| 基础 | 基础 URL | 平台对外访问的完整地址，用于邮件链接生成 |
| 安全 | 密码策略 | 最小长度、复杂度要求、过期天数 |
| 安全 | 会话超时 | 用户无操作后的自动登出时间（分钟） |
| 通知 | 默认时区 | 系统时间戳的默认显示时区 |
| 通知 | 语言 | 系统界面默认语言（支持多语言包） |
最佳实践： 在配置“基础 URL”时，务必使用 HTTPS 协议地址，否则邮件中的重置密码链接可能被浏览器标记为不安全。
3.3 邮件服务器配置
邮件服务器是 ThingsBoard 发送通知、用户激活、密码重置等事务性邮件的核心组件。系统管理员需在“系统设置” > “邮件” 页面完成配置。支持 SMTP 协议及部分云邮件服务。
3.3.1 配置参数清单
| 参数 | 示例值 | 说明 |
|---|---|---|
| SMTP 主机 | smtp.gmail.com | 邮件服务器地址 |
| SMTP 端口 | 587 | 通常 25/465/587，465 需 SSL |
| 用户名 | admin@example.com | SMTP 认证账户 |
| 密码 | ******** | SMTP 认证密码或应用专用密码 |
| TLS 启用 | true | 是否启用 STARTTLS |
| 发件人邮箱 | noreply@example.com | 邮件头中的 From 地址 |
| 发件人名称 | ThingsBoard 平台 | 邮件头中的显示名称 |
3.3.2 配置步骤
- 登录系统管理员账户，进入“系统设置” > “邮件”。
- 填写 SMTP 主机、端口、用户名、密码。
- 根据邮件服务商要求，启用或禁用 TLS。
- 填写发件人邮箱与名称。
- 点击“发送测试邮件”按钮，输入测试接收地址。
- 检查测试邮件是否成功接收，若失败则根据错误日志调整参数。
常见错误： 使用 Gmail 时，需开启“允许不够安全的应用”或使用应用专用密码；使用企业邮箱时，需确认 SMTP 端口未被防火墙封锁。
3.4 OAuth2.0 配置
OAuth2.0 允许用户通过第三方身份提供商（如 Google、GitHub、Azure AD）登录 ThingsBoard，实现单点登录（SSO）。系统管理员可在“系统设置” > “OAuth2.0” 页面配置多个提供商。
3.4.1 核心配置参数
| 参数 | 说明 |
|---|---|
| 客户端 ID | 第三方应用注册时生成的唯一标识 |
| 客户端密钥 | 第三方应用注册时生成的密钥 |
| 授权 URI | 第三方提供的授权端点地址 |
| 令牌 URI | 第三方提供的令牌交换端点地址 |
| 用户信息 URI | 第三方提供的用户信息获取端点 |
| 作用域 | 请求的权限范围，如 openid, email, profile |
| 映射属性 | 将第三方返回的字段映射到 ThingsBoard 用户属性（如 email、名、姓） |
3.4.2 配置流程
- 在第三方身份提供商（如 Google Cloud Console）中创建 OAuth 2.0 客户端，设置重定向 URI 为
https://你的域名/api/auth/login/oauth2/code/。 - 在 ThingsBoard 系统设置中，点击“添加 OAuth2.0 提供商”。
- 填写客户端 ID、客户端密钥、授权 URI、令牌 URI、用户信息 URI。
- 配置属性映射：例如将第三方返回的
email字段映射到 ThingsBoard 的email属性。 - 保存配置，并在登录页面验证 OAuth2.0 按钮是否正常显示及跳转。
安全提示： 客户端密钥属于敏感信息，建议使用 ThingsBoard 的“凭据”存储功能或环境变量注入，避免明文存储在数据库中。
3.5 配置验证与故障排查
完成配置后，系统管理员应执行以下验证步骤：
- 邮件测试：使用“发送测试邮件”功能，确认邮件能正常送达。
- OAuth2.0 登录测试：使用无痕浏览器窗口，尝试通过第三方提供商登录，确认能成功创建或关联用户。
- 日志检查：查看
/var/log/thingsboard/thingsboard.log中是否有ERROR或WARN级别与邮件/OAuth 相关的记录。
快速定位： 如果 OAuth2.0 登录后页面空白或报 500 错误，通常是因为重定向 URI 不匹配或属性映射字段名错误。请仔细核对第三方控制台与 ThingsBoard 配置中的 URI 是否完全一致（包括末尾斜杠）。