--- title: "看板源 Registries：index.json、安装 ID 与更新 · Metrix.Bar" description: "Metrix.Bar 看板源参考：index.json 结构、官方与 Awesome 源、复合安装 ID、SHA-256 校验、HTTPS 规则、自托管与更新流程。" canonical: "https://metrix.bar/zh/docs/registries" language: "zh-CN" --- # 看板源 Registries > Metrix.Bar 如何从远程看板源发现、校验并安装 .bar 看板。 ## 概览 看板源（Registry）是一个静态 JSON 索引，列出可安装的 `.bar` 看板。Metrix.Bar 读取看板源、展示目录，并通过 HTTPS 下载每个看板——不需要包管理服务器或账号。 每个看板源在固定 URL 发布一个 `index.json`。条目指向同源的 `.bar` 文件，带完整性哈希，并使用短 ID——安装时在设备上组合成全局唯一的安装 ID。 ## `index.json` 结构 ```json { "$schema": "https://metrix.bar/dashboards/schema.json", "schema_version": 1, "id": "official", "name": "Official", "dashboards": [ { "id": "github-repo", "name": "GitHub Repository", "file": "github-repo.bar", "protocol_version": "0", "version": "1.0.0", "category": "development", "description": "Track GitHub repository stars, forks, and activity.", "icon": "star", "license": "AGPL-3.0-only", "homepage": "https://agili.app", "sha256": "7c9bbe54c15a8b940486b167094a18f7f9f6f3eccad4d5c63a17e070eebacc72" } ] } ``` 完整源码见[官方 GitHub 看板](https://metrix.bar/dashboards/github-repo.bar)，摘要必须匹配实际发布文件的字节。 | 字段 | 必填 | 规则 | | ------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$schema` | 否 | 可选 JSON Schema URI 提示（如 `https://metrix.bar/dashboards/schema.json`），仅供编辑器提示与校验。客户端不下载该文件，`schema_version` 仍为唯一协议依据。 | | `schema_version` | 是 | 必须为 `1`。 | | `id` | 是 | 看板源 slug —— `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`，不能含 `--`。 | | `name` | 是 | 显示名。 | | `dashboards[].id` | 是 | 看板 slug，同 ID 规则，源内唯一。 | | `dashboards[].name` | 是 | 显示名。 | | `dashboards[].file` | 是 | 相对 `index.json` 的同源 `.bar` 路径——不能以 `/` 开头、不能带 scheme 或 host、不能带 query（`?`）、fragment（`#`）或反斜杠（`\`）。百分号编码解码后仍须为同源相对 `.bar` 路径。 | | `dashboards[].protocol_version` | 是 | 必须为 `"0"`。 | | `dashboards[].version` | 是 | 严格 SemVer 2.0.0——`major.minor.patch`，可带预发布/构建号，不带 `v` 前缀，数字部分无前导零。 | | `dashboards[].category` | 否 | 可选 slug，缺省为 `other`。显式空字符串 `""` 或 `null` 无效。官方分类：`ai`、`analytics`、`development`、`weather`、`finance`、`utilities`。 | | `dashboards[].description` | 否 | 可选简介。允许空字符串 `""`，不能为 `null`。 | | `dashboards[].icon` | 否 | 可选图标名或 URL。允许空字符串 `""`，不能为 `null`。 | | `dashboards[].license` | 否 | 可选 SPDX 风格许可证字符串。允许空字符串 `""`，不能为 `null`。 | | `dashboards[].homepage` | 否 | 可选展示 URL。若提供必须为非空绝对 HTTPS URL，无凭据且 host 非空（允许自定义端口和 fragment），不能为 `null`。仅用于展示。 | | `dashboards[].docs` | 否 | 来自 `.bar` 中 `` 的纯文本配置说明，保留内部换行，不能为 `null`。缺失或为空字符串时不展示。 | | `dashboards[].sha256` | 是 | `.bar` 原始字节的小写 64 位十六进制 SHA-256。 | 结构契约发布在 [`/dashboards/schema.json`](/dashboards/schema.json)，仓库内位于 `schemas/dashboard-registry.schema.json`。 ## 安装 ID 安装看板时，看板源 ID 与看板 ID 以双连字符组合： ``` {registryID}--{dashboardID} official--github-repo awesome--crypto-ticker ``` 安装 ID 只存在于设备上，不会写回看板源。安装时 Metrix.Bar： 1. 通过 HTTPS 获取 `.bar`。 2. 用条目中的 `sha256` 校验原始字节，在来源记录 `Source` 中记为 `sha256`。 3. 只把根 `` 改写为复合安装 ID，再重新解析文档。 4. 计算改写后的文件摘要，记为 `installed_sha256`（磁盘上的文件与 `index.json` 的 `sha256` 不再一致，因根 ID 被改写，这是预期行为）。 来源记录同时绑定 `registry_id`、`registry_url`（规范化 Canonical URL）与 `dashboard_id`。绑定严格遵循 `registryID + dashboardID + Canonical registry URL`。若缺少来源记录或源 URL 变更，Metrix.Bar 不会接管已安装看板；本地未绑定的看板绝不猜测远端来源。 因根 ID 改写，`installed_sha256` 与原始分发摘要 `sha256` 通常本来就不同。应用据此进行两处不同的哈希比对： - **本地修改检测**：比对当前磁盘文件的实际 SHA-256 与记录的 `installed_sha256`。 - **上游更新检测**：比对远端条目的 `sha256` 与记录的原始 `sha256`。 ## 官方与 Awesome - **Official** —— `https://metrix.bar/dashboards/index.json`。固定且始终启用，不能移除或停用。分发全部 16 个官方 `.bar` 看板——其中仅 GitHub 仓库看板同时随 App 内置，其余按需从该看板源安装。 - **Awesome** —— `https://awesome.metrix.bar/dashboards/index.json`。预置的社区索引地址，默认关闭；启用后是否可用取决于 `awesome.metrix.bar` 是否提供有效索引。 两者都是普通看板源，只是默认值不同。 ## 自托管看板源 任何能在 HTTPS 上提供合法 `index.json` 的 URL 都可以作为看板源。要求： - **HTTPS，局域网可用 HTTP**——看板源与 `.bar` 文件下载使用 HTTPS（任意主机与端口）；局域网主机（私网 IP、`.local` 等）也可用 HTTP，方便自托管。禁止凭据与 fragment，重定向必须同源。请求遵循应用的代理设置，fake-ip / TUN 代理下同样可用。`metrixbar://` 链接中的地址仍只接受公网 HTTPS。 - **同源文件**——每个 `file` 相对 `index.json` URL 解析且必须严格同源；重定向也必须维持原始协议与主机端口同源。 - **合法结构**——文档必须符合 `dashboard-registry.schema.json`（`schema_version: 1`、slug ID、必填字段、64 位小写十六进制 SHA-256 哈希）。 - **异步校验与容错**——保存看板源配置时立即持久化配置列表，网络请求与索引校验在后台异步进行。若网络请求失败或验证未通过，Metrix.Bar 保留错误状态并维持已有缓存，不会拒绝保存配置。 - **ID 唯一**——看板 ID 在源内唯一且符合 slug 规则（不能含 `--`，该符号为安装 ID 保留）。 最小自托管索引就是一个放在任意 HTTPS 主机上的静态文件（以下 SHA-256 对应原始字节 `Example setup instructions`，末尾无换行）： ```json { "$schema": "https://metrix.bar/dashboards/schema.json", "schema_version": 1, "id": "my-team", "name": "My Team", "dashboards": [ { "id": "example", "name": "Example", "file": "example.bar", "protocol_version": "0", "version": "1.0.0", "docs": "Example setup instructions", "sha256": "85d4f03b07795353f523e35227c575af674c6910e00e0f833bf6ed54ee6bac94" } ] } ``` ### 使用 `build.js` 构建看板源 为方便打包与发布自定义看板源，官网托管了独立的构建脚本，可直接下载运行： ```bash curl -fsS https://metrix.bar/dashboards/build.js -o build.js node build.js --input ./dashboards --output ./dist/dashboards --id my-team --name "My Team" ``` 构建脚本特点： - **无外部依赖**：已内置 XML 解析依赖（`saxes` 与 `xmlchars`），可在普通目录、CommonJS 和 ESM 项目中运行，只需 Node 22+ 运行环境，无需 `npm install`。 - **不发布 npm、不设 MCP**：脚本仅随官网托管供直接下载使用，不发布到 npm 仓库，也不作为 MCP 工具提供。 - **保真与摘要计算**：按相对目录结构保真复制 `.bar` 文件，并自动计算原始字节的 SHA-256 摘要与 `$schema` 提示生成 `index.json`。 - **静态校验与运行时校验区别**：`build.js` 仅校验 XML 语法、根属性、SemVer 规范、分类 slug 与 URL 格式等静态内容。它**不会**执行 Worker 脚本，也不会校验运行时环境；完整的运行时行为与渲染校验请使用本地 API 的 `POST /v0/check`、`POST /v0/validate` 或命令行 `metrixbar check`。 ## 更新 Metrix.Bar 每 24 小时自动检查已启用的看板源，也可手动触发。自动流程仅查询更新，绝不静默应用更新。 - **严格 SemVer 与人工确认**：更新要求 SemVer 版本严格更高且必须由用户明确确认。相同版本下远端 hash 变化视为异常并拒绝。 - **本地修改保护**：比对当前磁盘文件的 SHA-256 与保存的 `installed_sha256`。若本地源码被修改过，更新前必须经用户明确确认；在应用更新前，Metrix.Bar 会自动在数据目录保存备份副本（`-local-*.bar`），绝不静默覆盖本地改动。 - **并发保护**：更新确认流程严格绑定目标文件的 ETag。若在确认与应用之间文件被并发修改导致 ETag 不一致，中止更新。 - **配置与 secret 兼容保留**：兼容的输入项与系统凭据库中的密钥在更新后完整保留。若新版本存在移除输入项或字段类型变更等不兼容情况，更新会被拒绝，需先处理不兼容项。 ## 安全说明 - 看板源请求走 HTTPS，带 Metrix.Bar 标准头（`User-Agent: Metrix.Bar/`、`X-Requested-With: bar.metrix`）。 - 安装或更新前都会校验 `sha256`；不一致则中止安装。 - 看板源元数据不会授予额外权限——`.bar` 文件自己的 `` 仍然控制网络源与文件访问，secret 仍保存在系统凭据库中。 ## 安装链接 `metrixbar://open` 可唤起主窗口，`metrixbar://open/<实例ID>` 可选择看板，`metrixbar://refresh[/<实例ID>]` 可刷新一个或全部实例。实例 ID 保留解码后的值与大小写，支持点号和 Unicode。ID 须编码为单个路径段；拒绝 `.`、`..`、路径分隔符与 NUL。 `metrixbar://install/github-repo` 可从官方目录安装；附加 `?registry=awesome` 或其他已配置来源 ID 可选择来源。禁用的来源会先请求启用确认。`metrixbar://install/?registry_url=<编码后的 HTTPS 索引 URL>` 可从其他索引安装，确认窗口会展示来源、权限与 inputs；新来源仅在确认安装时与看板一起保存，取消不会添加来源。`metrixbar://registry/add?url=<编码后的 HTTPS 索引 URL>` 仅请求添加来源。 重复点击同来源、同版本、同原始 SHA-256 的 registry 安装链接会打开已有看板。应用会重新校验当前索引，不写检查时间或缓存；同版本摘要变化视为异常，更高版本仍须确认更新。 `metrixbar://install?url=<编码后的 HTTPS .bar URL>` 可直接导入，附加 `&sha256=<64 位十六进制摘要>` 可验证内容。确认窗口展示下载域名、权限与 inputs，确认后才安装运行。直链导入保留原始看板 ID 和下载来源，不提供后台更新。再次点击同 URL 时，若下载摘要与记录的原始摘要相同，即使本地文件已编辑，也会打开已有看板；摘要变化则请求再次导入确认，允许版本不变。显式摘要须先校验通过。更新保留兼容配置与 secret，本地修改需要明确允许替换并备份，准备后文件或来源变化会中止，保存失败会回滚。其他来源不能覆盖相同 ID 的已安装看板。 嵌套 URL 须编码为查询参数值。重复或冲突参数、凭据、fragment 与非法摘要会被拒绝。下载使用有大小限制的公网 HTTPS，仅允许同源重定向。多个链接会等主窗口就绪后依次处理，重复等待中的点击只处理一次；取消或关闭错误确认后可继续下一条。