Open Badge 烘焙详解:JSON 如何藏在 PNG 里

「烘焙」后的 Open Badge 是一张 PNG 图片,断言 JSON 以图像元数据的形式嵌入其中。徽章文件本身就是凭证。本文讲解烘焙的原理,以及如何验证烘焙后的徽章。

Nacho Coll 作者 更新于 18 分钟阅读
「烘焙」后的 Open Badge 是一张 PNG 图片,断言 JSON 以图像元数据的形式嵌入其中。徽章文件本身就是凭证。本文讲解烘焙的原理,以及如何验证烘焙后的徽章。

从几乎任何颁发者那里下载一枚 Open Badge,你得到的都是一张看起来很普通的 PNG。把它丢进聊天窗口、附在邮件里、打印出来,它看上去和其他图片没有区别。但这个文件还带着第二层看不见的内容:凭证本身,以元数据的形式写进了图像里。这就是 Open Badges 社区所说的 烘焙徽章(baked badge),也正因如此,一枚徽章可以只靠一个文件流转,同时仍能证明是谁、向谁、因何而颁发。

本指南会讲清楚什么是烘焙、数据在文件的哪个位置、验证方如何把它读出来,以及作为凭证颁发者你需要做哪些决定。使用烘焙徽章并不需要写代码。如果你通过 https://badges.ninja 颁发,烘焙会自动完成。但了解其中的机制,能帮你回答接收者和雇主真正会问的问题:「这张图是真的吗?」以及「别人能直接复制吗?」

「烘焙」是什么意思

一枚 Open Badge 由两部分组成,很容易混淆:

  • 图片。 人们在个人主页、幻灯片或证书上看到的 PNG 或 SVG。
  • 断言。 一份小小的 JSON 文档,陈述事实:接收者是谁(以哈希标识符表示)、获得了哪个徽章类别、由谁颁发、何时颁发,以及在哪里验证。

烘焙,就是把断言写进图片里,让两者无法分离。结果是一个文件。把这张 PNG 交给别人,你就同时交出了图片和它背后的声明。

这一理念来自最初由 Mozilla 开发、现由 1EdTech 维护的 Open Badges 规范。其设计目标是可移植性。早期的徽章只存在于单一平台内,想把它搬到别处,就得重新上传,还得祈祷元数据没有丢失。烘焙后的文件无论走到哪里,都自带元数据。

JSON 在 PNG 里的什么位置

PNG 文件由一段简短的签名和一连串 数据块(chunk)组成。每个数据块包含长度、四个字母的类型、若干数据以及校验和。查看器根据 IDAT 数据块绘制像素,并忽略它们不认识的数据块类型。正是这种宽容让烘焙成为可能:你可以加入一个装满文本的数据块,而世界上所有图像查看器依然会正常显示这张图片。

对于 Open Badges 2.0,断言会写入关键字为 openbadges 的文本数据块。可以承载它的文本数据块类型如下:

数据块编码说明
tEXtLatin-1简单,但仅限 Latin-1 字符。
iTXtUTF-8首选,因为姓名和描述往往不是 ASCII。

无论使用哪种数据块,结构都是一样的:关键字 openbadges、一个分隔符,然后是载荷。载荷是以下两种之一,取决于颁发者选择的烘焙方式:

  1. 断言 JSON 本身。 文件自带说明。验证方无需任何网络请求就能读取声明。
  2. 指向托管断言的 URL。 文件更小,颁发者可以让线上记录保持权威性,例如用来表明某枚徽章后来被撤销或已过期。

对于带签名的徽章还有第三种变体,载荷是签名令牌而非纯 JSON。如果你的场景需要签名,请阅读 如何验证 Open Badge 签名。

SVG 呢?

SVG 徽章同样可以烘焙,因为 SVG 就是 XML。断言被放在文件内的 openbadges XML 命名空间元素中,verify 属性则携带托管断言的 URL。原理与 PNG 相同:元数据随图像文件一起传递。实际上大多数平台烘焙的是 PNG,因为几乎所有需要上传徽章的地方都接受 PNG。

嵌入的断言长什么样

对于 2.0 格式,托管断言是一份 JSON-LD,把接收者、徽章类别和验证方法串联起来。下面是一个精简示例:

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://example.org/assertions/abc123",
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "deadsea",
    "identity": "sha256$c7ef86405ba71b85acd8e2e95166c4b111448089f2e1599f42fe1bba46e865c5"
  },
  "badge": "https://example.org/badges/data-analysis-101",
  "issuedOn": "2026-05-14T00:00:00Z",
  "verification": { "type": "hosted" }
}

注意接收者部分。电子邮件不是明文存储的,而是加盐的 SHA-256 哈希。对于一个注定要四处传播的文件,这一点很重要。任何持有这张 PNG 的人都能读取断言,所以断言绝不能泄露接收者的邮箱地址。已经知道邮箱的验证方,可以用同样的盐对其做哈希,并检查是否一致。想逐字段了解这份文档,请参阅 Open Badge JSON-LD 逐步解析。

验证方如何读取烘焙徽章

验证烘焙徽章是一个简短而机械的过程:

  1. 打开 PNG,遍历它的数据块。
  2. 找到关键字为 openbadges 的文本数据块。
  3. 读取载荷。如果是 JSON,就解析它;如果是 URL,就去获取它。
  4. 检查断言指向的徽章类别和颁发者是否符合预期,以及接收者身份是否与出示徽章的人一致。
  5. 如果验证类型是 hosted,确认托管断言在其 id URL 上仍然存在,且没有被撤销或过期。

第 5 步是人们最常跳过的,却恰恰是让凭证值得信赖的一步。嵌入的副本只是一个快照,托管记录才是事实来源。

用 Node 自己读取

你可以用一段简短的脚本检查任意 PNG。下面这段脚本会遍历数据块,并打印 openbadges 载荷,同时支持 tEXt 和 iTXt:

import { readFileSync } from "node:fs";
import { inflateSync } from "node:zlib";
const png = readFileSync(process.argv[2]);
let pos = 8; // skip the 8-byte PNG signature
while (pos < png.length) {
  const length = png.readUInt32BE(pos);
  const type = png.toString("ascii", pos + 4, pos + 8);
  const data = png.subarray(pos + 8, pos + 8 + length);
  if (type === "iTXt" || type === "tEXt") {
    const nul = data.indexOf(0);
    const keyword = data.toString("latin1", 0, nul);
    if (keyword === "openbadges") {
      let text;
      if (type === "tEXt") text = data.toString("latin1", nul + 1);
      else {
        const compressed = data[nul + 1] === 1;
        let p = nul + 3; // skip compression flag + method
        p = data.indexOf(0, p) + 1; // language tag
        p = data.indexOf(0, p) + 1; // translated keyword
        const body = data.subarray(p);
        text = (compressed ? inflateSync(body) : body).toString("utf8");
      }
      console.log(text);
      process.exit(0);
    }
  }
  pos += 12 + length; // length + type + data + CRC
}
console.error("No openbadges chunk found: this PNG is not baked.");
process.exit(1);

用 node extract-badge.mjs my-badge.png 运行它。如果文件经过烘焙,你会看到 JSON 或一个 URL;如果没有,则会得到一条简单的「未烘焙」提示。这是一个教学工具,而不是完整的验证器:它不会检查数据块校验和,不会解析带签名的载荷,也不会获取托管记录。

如果你不想写代码,在线徽章验证器或 PNG 元数据查看器同样能显示这个数据块。格式是标准化的,所以任何合规的工具都能读取任何合规的徽章。

为什么烘焙很重要

可移植性。 仅仅是一张 PNG 的凭证,可以通过邮件发送、上传到学习平台,或存进个人档案。携带它不需要任何账号。

不依赖颁发者营销网站的验证路径。 嵌入的断言标明了颁发者并指向托管记录,因此验证方只需一个文件就能开始验证。

离线和低技术场景。 当载荷是完整的 JSON 时,读取方可以在没有网络的机器上检查声明,之后再验证托管记录。

不易被随手伪造的证据。 任何人都可以给徽章截图。截图没有元数据,因此无法作为徽章文件被验证。仅这一点就把真正的凭证与被复制的图片区分开来。但它无法阻止有人把伪造的断言烘焙进一张盗来的图片,这正是托管验证这一步存在的原因。

烘焙的局限

请坦诚地向接收者说明这些局限,因为它们会影响你描述凭证的方式。

  • 元数据会被剥离。 许多社交网络、图片优化工具和即时通讯应用会对上传的图片重新编码,并丢弃非像素数据块。发布到社交动态里的烘焙徽章通常已不再是烘焙状态。这是预期之内的,也正是文件旁边还需要一个公开验证链接的原因。
  • 烘焙本身不是证明。 嵌入的 JSON 任何人都可以写。信任来自颁发者域名上的托管断言,或来自有效的签名。
  • 编辑图片会破坏关联。 在编辑器里缩放或重新保存可能会丢失该数据块。
  • 仅支持 PNG 和 SVG。 规范中没有 JPEG 对应的数据块约定,因此导出为 JPEG 的照片风格徽章无法按标准方式烘焙。

实际的结论是:把烘焙后的文件当作方便的载体,把验证页面当作权威。如果你正在为项目权衡格式,Open Badges 与 PDF 证书 解释了为什么机器可读的凭证胜过静态文档。

https://badges.ninja 上的烘焙是怎么运作的

当你在 https://badges.ninja 上授予徽章时,平台会为该接收者构建 Open Badge 断言,并在颁发过程中把它烘焙进徽章图片。你不需要配置工具,也不需要运行命令。流程如下:

  1. 你在可视化设计器中设计徽章,或上传自己的图片。
  2. 你颁发一次授予:可以通过控制台、通过 CSV 上传进行批量授予,或通过 API。
  3. 平台创建断言,把它烘焙进 PNG,并将结果与该授予一起存储。
  4. 接收者会得到位于 https://badges.ninja/awards/<awardId> 的公开验证页面、一份 PDF 证书、一个二维码,以及 Add to LinkedIn 选项。

如果徽章设计使用了合并字段(例如接收者姓名),每次授予都会生成一张个性化图片,而被烘焙的正是这张个性化图片。

烘焙被视为颁发的增强功能,而不是门槛:如果某张图片无法烘焙(例如一张退化的占位图),授予仍会使用原始图片颁发,公开验证页面和 Open Badge JSON-LD 不受影响。你上传的图片也必须达到最小尺寸,因此一块极小的空白画布会在到达烘焙环节之前就被拒绝。

由于公开页面才是权威,任何人无需注册就能查验一次授予。某次授予的机器可读 Open Badge v2.0 JSON-LD 可在 https://api.badges.ninja/certify-badge/award/<awardId> 获取。

通过 API 颁发一次授予

大多数读者会使用控制台,但如果你要自动化颁发,一次请求就能创建授予(烘焙后的图片随之生成)。请将密钥和徽章 id 替换为你自己的:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": "bws_YOUR_KEY_HERE", "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId: "your-badge-id",
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();
const verifyUrl = `https://badges.ninja/awards/${awardId}`;

该调用返回 HTTP 200 和 { "awardId": "<guid>" }。用这个 id 构建验证 URL。密钥设置和完整的请求参考,请参阅 Awards API 文档 和 身份验证指南。

https://badges.ninja 控制台中的徽章详情页面

给颁发者的实用建议

始终在文件旁边发布验证链接。 把链接放在授予邮件里、证书上,以及任何展示该徽章的页面上。由于社交平台会剥离元数据,分享之后让凭证依然可验证的正是这个链接。

使用干净且尺寸足够的源图。 从有真实尺寸的 PNG 开始。设计师制作的正常分辨率徽章可以稳定烘焙;1 像素的占位图则不行。

不要编辑交付的文件。 告诉接收者分享原始下载文件或验证链接,而不是裁剪过的截图。

想清楚你要如何说明撤销和过期。 因为托管记录才是权威,烘焙文件可能比凭证本身的有效状态存在得更久。请在项目文档中明确说明,让雇主知道应当查看验证页面,而不是只信任文件。

端到端测试一枚徽章。 给自己颁发一次授予,下载 PNG,用上面的脚本或公共验证器检查,并打开验证链接。五分钟的测试就能让你知道接收者会有怎样的体验。

https://badges.ninja 控制台中的徽章列表

常见问题

烘焙徽章和数字证书是一回事吗? 不是。证书通常是用于阅读和打印的 PDF。烘焙徽章则是同时携带机器可读凭证数据的图片。https://badges.ninja 能从同一次授予生成这两者。

不用平台也能烘焙徽章吗? 可以。规范是开放的,多种语言都有相应的库。更难的部分是把断言托管在稳定的 URL 上,而这正是让验证有意义的关键。这部分由平台替你处理。

烘焙会暴露接收者的邮箱吗? 身份经过哈希时不会。断言存储的是加盐哈希,因此文件不会泄露邮箱地址。

LinkedIn 会读取烘焙数据吗? LinkedIn 的 Add to Profile 流程依据的是凭证名称、颁发者、日期和 URL,而不是文件元数据。请参阅 添加 Add to LinkedIn 按钮。

总结

烘焙后的 Open Badge 是一张 PNG(或 SVG),凭证被写入名为 openbadges 的文本数据块中。它让徽章可移植、自带说明,但真正的信任来自颁发者域名上的托管断言。为可移植性而烘焙,为信任而发布验证链接,并预期社交网络会剥离元数据。

准备好颁发你的第一份可验证凭证了吗? 在 badges.ninja 免费开始 — 可视化设计器、公开验证页面、PDF 证书、Open Badge v2.0 输出。无需信用卡。

Nacho Coll

关于作者

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

返回博客

相关文章