跳到主要内容

系统设置

系统设置是运维人员为所有租户统一设置的实例级值。一共有四项，位于管理控制台的**设置（Settings）**中。它们的优先级都低于租户自己的配置：没有设置任何值的租户使用实例默认值；设置了自身值的租户则不会使用该默认值。

键决定什么说明位置
basemap.default每个租户最初使用的地图瓦片底图
branding.default实例的标题、徽标和配色白标
entity.token_masks控制台生成的所有令牌的格式下文
locale.default控制台打开时使用的语言下文

读取设置需要 settings:read，写入需要 settings:write。两者都是运维人员级权限，不属于任何租户角色。已登录用户无需这两项权限，即可读取以下内容：

  • tokenMasks 查询：只提供实际生效的令牌模板映射，使每个控制台创建表单都能生成令牌。
  • 租户实际生效的品牌、底图和语言：租户对象已经将这些值与实例默认值合并后提供。

所有设置写入都必须遵守的规则​

以下三条规则按顺序适用于全部四个键：

  1. 键必须是上表中的四个之一。 可用键是封闭集合。未知键会被拒绝，而不是创建新的设置；拒绝发生在检查值之前。无法通过 API 添加键。
  2. 值不得超过 64 KB。 超出时，写入会被拒绝，错误中会指出字节限制（65,536）。限制适用于整个 JSON 文档，而不是某个字段。对于 branding.default 尤其重要，因为内联 data: 徽标原本可能大得多：
    • 租户的品牌记录允许 256 KB 的内联徽标，因为它保存在带类型的列中，而不是设置中。
    • 实例层则受 64 KB 文档限制，约可容纳 48 KB 图像。这一层的控制台徽标字段要求输入 https URL，不提供上传；在这个限制下，URL 是实用选择。
  3. 值必须是有效 JSON。

随后每个键会执行自己的验证，说明见上表链接的页面。

令牌模板​

entity.token_masks 决定每个控制台创建表单预填的令牌。每个实体都通过令牌寻址。为每台新设备手动输入令牌既繁琐又容易出错，因此控制台根据模板生成令牌，并允许你在保存前修改。

该设置将实体类型映射到模板。没有专属条目的实体类型使用 default 键：

{
  "default": "{slug}",
  "device": "dev-{alphanumeric-8}",
  "area": "area-{slug}"
}

模板由固定文本和占位符组成：

占位符生成内容
{slug}根据正在输入的名称生成 slug，例如设备名为 "Cold Store Probe" 时，会建议 cold-store-probe
{uuid}UUID
{alphanumeric-N}N 个随机字母和数字
{numeric-N}N 个随机数字

默认配置是 {"default": "{slug}"}。

无论模板生成什么，都必须符合令牌语法，因此某些模板不可能有效。如果模板符合以下任一情况，就会被拒绝：

  • 为空；
  • 使用未知占位符。dev-{sulg} 会为所有实体静默生成 dev-，因为未知占位符不产生任何内容；
  • 没有任何占位符。所有实体都会得到相同令牌，第一次创建成功，之后全部冲突；
  • 声明的宽度超过 128 个字符，无法生成有效令牌；
  • 生成的样本不符合令牌语法。my.device-{slug} 会因句点被拒绝，在任何实体使用它创建之前就会发现问题。

最后一项检查说明了为什么要在保存模板时验证，而不是在创建时验证。否则，保存错误模板的运维人员不会发现问题，却会让每个打开创建表单的控制台用户遇到问题。

这控制的是建议，而不是规则

模板决定控制台建议的内容。手动输入的令牌或集成通过 API 发送的令牌，只需符合令牌语法。写入路径不强制使用模板，修改模板也不会影响现有实体。

默认语言​

locale.default 决定尚未自行选择语言的人打开控制台时使用的语言。值是 JSON 字符串中的 BCP-47 语言标签（"en"、"es"、"pt-BR"），或默认值 null。

null 不表示“未设置”，而表示没有实例级默认值，由各查看者的浏览器决定。因此，默认控制台会跟随西班牙语浏览器使用西班牙语。在此设置标签会覆盖所有未自行选择语言的用户的浏览器语言，除非其租户设有自身默认值。在控制台中清空字段，会重新存储 null。

控制台按四层优先级选择语言。在设置前请了解顺序，因为这四项系统设置中，只有语言可以由用户覆盖：

  1. 用户通过语言切换器选择的语言，此处的设置不会改变它。
  2. 租户管理员在**设置 → 语言（Settings → Language）**中设置的租户默认语言。租户没有设置时，由本设置补充。
  3. 查看者浏览器请求的语言。
  4. 英语。

因此，此处的标签只影响原本会使用第 3、4 层的用户：未自行选择语言，且租户没有自身默认值的人。如果设置了标签，已经使用过语言切换器的同事不会看到语言改变。这是有意设计的，也通常是此处修改“没有生效”的原因。

标签检查只验证格式，不检查当前构建是否提供该语言：

  • 未知但格式正确的标签会被存储，在提供对应语言目录前不会生效。输入时控制台会提示警告。
  • 标签必须以规范形式存储（es-MX，而不是 es-mx）。
  • 空字符串会被拒绝，请使用 null。

区域标签会回退到基础语言，因此只提供 es 的构建中，es-MX 会显示西班牙语。