底图

DeviceChain 的每个地图界面都在底图上绘制位置：从你选择的提供方获取栅格地图瓦片。这包括地理围栏编辑器、仪表板地图组件，以及通过独立查看器嵌入的仪表板。

新实例开箱即可显示地图。默认提供 OpenStreetMap 标准瓦片图层，无需账户。平台不会静默选择：默认值有明确名称，在**设置（Settings）**中可见，一次编辑即可替换。每个能够设置瓦片来源的层级都必须提供其许可证要求的署名信息。

进入生产前，请决定默认提供方是否适合你。参见选择提供方。

底图属于租户

你在控制台的设置 → 地图（Settings → Map）中按租户配置底图，需要 basemap:write 权限。

从列表选择提供方，DeviceChain 会填入其瓦片模板和许可证要求的署名信息。两个字段都仍可编辑。对于不在列表中的提供方，例如内部瓦片服务器，可以直接输入这两个字段；参见选择提供方。

底图属于租户，因为瓦片 URL 通常带有 API 密钥。密钥属于租户，意味着租户自己的地图账户独立计费、限速、限制访问，并可撤销而不影响实例中的其他人。一个租户耗尽配额不会让另一个租户的地图变空白，已有提供方合同的租户也可以继续使用。

basemap:write 有意与 branding:write 分开，虽然两者都影响租户控制台外观。绑定两者会使每次授权隐含另一项权限：修改徽标的人可以读取地图密钥，配置地图的人可以修改控制台外观。

值来自哪里

值来自三个层级，最具体的优先：

层级	设置者	位置
单界面覆盖值	编辑该界面的任何人	地图组件自身选项；地理围栏编辑器底图字段，保存在浏览器中
租户	租户管理员（basemap:write）	控制台 → 设置 → 地图
实例默认值	运维人员（settings:write）	管理控制台 → 设置 → basemap.default

每层补充上层留空的内容。单租户或设备式部署可以只在实例层设置一次。

单界面层级会一直保留。可以先在单个仪表板或自己的浏览器中试用提供方，再决定是否为所有人启用。

瓦片来源作为一个整体继承

瓦片 URL 和许可证要求的署名是一个值，而不是两个。它们一起验证，不能只保存其中一个，也必须一起继承。

共同继承尤其重要。如果租户设置自己的瓦片 URL 却将署名留空，不会保留实例默认署名。将一个提供方的瓦片显示为另一个提供方的署名违反许可证，因此级联不会制造这种组合。租户层和实例层会在保存时提前拒绝。

单界面层级在浏览器中设置，不经过该验证，因此在使用时执行同样规则。组件选项或地理围栏编辑器字段如果只有瓦片 URL、没有署名，会被完全忽略，地图回退到租户正确署名的底图。地理围栏编辑器会告知这种情况。填写不完整的覆盖值会被整体舍弃，而不是只应用一半，否则就会显示没有署名的瓦片。

初始视图约束较少，但仍有约束：

• zoom 单独继承，因此租户可以修改缩放，无需重新指定提供方。
• centerLat 和 centerLon 是一对，因为半个坐标不能确定一个点。只设置其中一个会被拒绝。
• 在较低层级只覆盖其中一个，不会从上层借用另一个，而是清除继承的中心点，使该界面没有初始视图。

初始视图只是回退，绝不覆盖已有内容

只有地图没有自身内容需要适配时，才应用中心点和缩放。已有形状的地理围栏会打开在该形状上；有标记的地图组件会适配标记。因此，即使租户中心设在亚特兰大，编辑罗马的围栏时仍会显示罗马。

瓦片 URL 必须符合什么格式

违反以下规则的值会在保存时被拒绝，因为否则都会在之后静默失败。

这些规则只适用于租户层和实例层。 单界面覆盖值（地图组件的瓦片 URL，或地理围栏编辑器的个人字段）保存在浏览器中，不到达服务器。除了上述署名规则，没有其他检查。因此，http:// URL、包含 Leaflet 风格 {s} 的 URL，或指向样式 JSON 的 URL，在该层都可能被接受并直接交给渲染器。随后渲染器显示空白瓦片，不提示，也不回退。如果个人覆盖值导致地图为空，请按下列规则逐项检查。

• 只允许 https。 HTTPS 控制台会将 HTTP 瓦片作为混合内容阻止，因此 http:// 来源即使保存也无法渲染。内部瓦片服务器使用普通 HTTP 时，请在前面配置 TLS。
• 必须是模板。 URL 需要 {z}、{x} 和 {y}，或 {bbox-epsg-3857}，或 {quadkey}。没有占位符时，地图每块瓦片都请求同一图像。常见粘贴错误就是单块瓦片 URL 和样式 JSON URL。
• 只允许渲染器认识的占位符：{prefix}、{z}、{x}、{y}、{ratio}、{bbox-epsg-3857} 和 {quadkey}。花括号中的其他内容会作为原文发给提供方。这能发现最常见的复制问题：Leaflet URL 使用 {s} 子域占位符，而 DeviceChain 渲染器不替换它。请换成固定子域，例如 a.tile.example.com 而非 {s}.tile.example.com，这也是当前推荐做法。
• 必须提供署名，标记格式受限，只能是纯文本加上严格采用 <a href="https://…">text</a> 格式的链接。允许链接，是因为一些提供方的许可证要求署名链接到版权页面。其他标记都被拒绝。

目前只支持栅格瓦片，不接受矢量样式 URL，瓦片使用标准 256 像素 {z}/{x}/{y} 寻址。在相同坐标下返回 512 像素图像的高分辨率端点可用，显示更清晰；{ratio} 就用于此用途。真正使用 512 瓦片方案、坐标含义不同的服务器不受支持。

数值与长度限制

租户层和实例层保存时还会拒绝超出以下范围的值：

字段	限制
tileUrl	2048 个字符
attribution	512 个字符，不允许控制字符
zoom	0 到 24
centerLat	−90 到 90
centerLon	−180 到 180

服务器会指出违反的限制，因此保存时即可发现。控制台表单只检查视图字段是否为数字，不检查范围。缩放值 30 会通过表单，再作为服务器错误返回，而不是输入时提示。

选择提供方

默认值让你第一天就有可用地图，但未必自动适合生产部署。决定因素通常是谁应当承载你的流量。

**提供方（Provider）**列表包含瓦片模板和署名信息均已根据提供方自己的文档核对的提供方。选择后填充两个字段。需要 API 密钥的提供方有独立密钥字段，平台帮你组合到 URL 中，因此之后轮换密钥无需重新粘贴模板。

列表有意不做两件事：

• 不描述任何提供方的条款。 每项直接链接其条款和价格页面。是否免费、是否需要账户、是否限速，都可能在其他网站上改变而我们未察觉，因此列表指向原始来源而不是总结。依赖某提供方之前请阅读。
• 不穷尽所有提供方，这是准入标准，而不是待办缺口。 只有提供方自己公布必需署名时才列入。错误署名比缺失条目更糟：它会将违反许可证的内容预填到你本应可以信任的地方。如果没有你的提供方，请选择自定义（Custom…），自行输入两个字段。

选择**自定义（Custom…）**绝不会更改字段现有内容。它表示“我要自己输入”，此时覆盖内容最具破坏性。

OpenStreetMap 默认值

OpenStreetMap 瓦片服务器由非营利组织运营，通过捐赠资助。瓦片使用政策说明其要求，DeviceChain 按这些要求构建：只在浏览时获取瓦片，不预取、不归档，并始终显示署名。以下两点仍由你负责：

• 不要在控制台前配置限制性 Referrer-Policy。 政策要求浏览器客户端提供有效 Referer。移除它可能让实例在没有警告的情况下被封禁，本地唯一现象只是地图不再绘制。
• 扩大使用规模前阅读政策。 使用影响服务时，政策保留不预先通知就阻止访问的权利。对于捐赠基础设施，这是合理要求，但不应在客户演示时才发现。

如果地图对你的业务重要，请将租户或实例默认值指向与你有服务关系的提供方。租户层正是为此而设。接下来请阅读 API 密钥部分。

没有瓦片来源时显示简图世界，而非空白

运维人员将实例默认值设为 {}，且租户不设置时，就完全没有瓦片来源。

关闭地图来源应使用 {}，而不是重置

**恢复默认（Reset to default）**与关闭地图来源相反：它会恢复内置提供方。要关闭，必须显式设置 {}。

地图界面随后回退到内置世界底图：公共领域 Natural Earth 陆地和国界轮廓，直接编译进应用。它不向任何外部主机请求资源，所有内容都由 DeviceChain 自身提供。因此它适合隔离网络安装，也适合有意关闭提供方的运维人员。

它明确是一张简图，只有大陆和国界，街道级缩放没有细节，因此表达的是“请配置提供方”，而不是“这里坏了”。其他功能与瓦片地图完全相同。你仍能绘制地理围栏，坐标仍然精确，因为投影与瓦片地图相同。

瓦片 URL 中的 API 密钥不是秘密

租户的任何使用者都能看到它

如果提供方瓦片 URL 带有 API 密钥，该密钥会到达浏览器。必须如此，因为浏览器负责获取瓦片。请使用下述提供方控制机制保护它。

密钥作为普通配置保存，而不是放入密钥存储，因为客户端必须读取的值无法对客户端保密。API 密钥字段用于将密钥放在模板正确位置，不是用来保护它。

按地图提供方预期的方式保护密钥：在提供方控制台中设置HTTP 来源限制，限定到提供控制台的主机名；提供方支持时，还应设置每密钥配额和 API 限制。这些控制才真正限制此类密钥的滥用。定期轮换，并为每个租户使用独立密钥，撤销一个不会影响其他租户。

嵌入式仪表板

独立仪表板查看器以自己的用户身份登录，读取同一租户底图，因此其中嵌入的仪表板使用与控制台相同的瓦片。

如果嵌入仪表板显示的底图与控制台不同，请检查查看器是否以同一租户成员身份登录。最明显的情况是原本预期瓦片，却看到内置世界简图。底图跟随租户，而不是仪表板。