AI 生成的 PNG 入对象存储前先验字节
文章区分裸 Base64、Data URL 和远程 URL,建议取得 Node.js Buffer 后先在本地验证 PNG,再以 image/png 上传。损坏的 Base64 应在上传前拒绝,网络重试留给对象存储写入。
AI 深度解读
AI 生图接口返回了结果,对象存储也写入成功,用户打开图片却看到加载失败。问题可能早在上传之前就发生了:Node.js worker 传给存储的是 base64 文本,或者拿到了一个能解码、却没有 PNG 文件头的 Buffer。
作者建议把解码和校验放在上传之前,同一份输入只解码一次,通过检查后才把二进制写入存储。本地校验失败直接记录,网络写入再按错误类型决定是否重试。顺着这条链路看,前端的上传进度、后端的写入成功和用户最终能打开图片,各自能证明什么就清楚了。
为什么能得到 Buffer,还要校验输入?
先确定生图接口返回的是什么。普通 base64 是编码后的文本,data:image/png;base64,... 是带媒体类型和编码声明的 data URL,远程 URL 则指向另一处资源。三种响应需要各自的处理路径。字段应按生产方的接口约定选取,只有约定返回 PNG data URL 时,才识别并去掉 data:image/png;base64, 前缀。远程 URL 需要先取回资源字节,具体获取策略原文没有展开。
Buffer.from(value, "base64") 的解码行为比较宽松,得到一个非空 Buffer 只说明它解出了字节。作者建议先检查文本非空,按约定的 base64 变体检查字符集、填充规则和允许的空白,再用配置的长度上限挡住超大输入。上限取决于预期尺寸、压缩情况和 worker 并发。缩略预览和高分辨率导出可以分别设限,原文没有给出通用阈值。
解码之后,检查 Buffer 至少有 8 个字节,且开头匹配 PNG 签名 89 50 4e 47 0d 0a 1a 0a。通过后,直接把这份 Buffer 作为对象写入的请求体,设置 Content-Type: image/png。如果把 Buffer 转成 UTF-8 字符串,或者把原来的 base64 文本当作请求体,即使存储端接受了写入,对象里的字节也会偏离预期。
原文用这段 Python 示例演示适配器如何在写入前拒绝空值、非法 base64 和缺少 PNG 签名的字节。
import base64
PNG_SIGNATURE = bytes.fromhex("89504e470d0a1a0a")
def decode_png(payload: str) -> bytes:
if payload.startswith("data:"):
header, separator, payload = payload.partition(",")
if separator != "," or header != "data:image/png;base64":
raise ValueError("expected a PNG data URL")
if not payload:
raise ValueError("empty image payload")
try:
image = base64.b64decode(payload, validate=True)
except Exception as error:
raise ValueError("invalid base64 image payload") from error
if not image.startswith(PNG_SIGNATURE):
raise ValueError("decoded payload is not a PNG")
return image
注意 if not image.startswith(PNG_SIGNATURE): 这一行,它只检查文件头,文件头完整、后续数据被截断的输入仍可能通过。示例也没有实现大小限制,移到 Node.js worker 时要单独补上。
哪些失败该重试,哪些该找上游?
选错 JSON 字段、漏掉 data URL 前缀、队列收到非图片内容,都可能让解码失败。拿同一条消息重新解码,结果通常一样。如果 worker 把这些情况都算成上传失败,坏消息会反复占用队列,存储指标也会变得难读。选取响应字段和校验输入可以放在同一个模块,排查时能直接追到生产方和消费方的接口约定。
作者建议为拒绝事件记录稳定的错误分类、编码字符数、声明的媒体类型、关联 ID,以及能拿到的解码字节数。图片内容和 prompt 留在日志之外。排查时可以按生产方的发布版本、模型响应结构和队列消费者聚合,看看异常是否集中在某次变更之后。
写入阶段再给可恢复的网络错误设有限的重试次数。若第一次请求已写入,只是 worker 没收到成功响应,稳定的对象键能让下一次请求仍落到同一个对象。作者建议用请求 ID 派生这种幂等键(idempotency key)。对象键可能出现在日志、链路追踪和客服工具里,用户的 prompt 没必要跟着流转。遇到权限配置错误,则需要先排查授权。
写入成功后,怎么确认用户能读到图?
单元测试可以用替身观察 put_object 或 Node.js 对象写入接口是否被调用。测试样本包含合法的普通 base64、合法的 PNG data URL、协议允许的空白、非法字符、截断数据、编码后的非 PNG 内容、空值和超限值。测试重点是让无效输入在本地停下,合法样本以二进制进入写入接口。
集成测试再走生产使用的授权和读取路径。写入一张小图、读回对象,比较读回内容和解码后 Buffer 的摘要(digest),同时检查 Content-Type: image/png。这样能验证读回的是同一份字节,也能测到实际读取路径上的权限和元数据行为。
浏览器侧还有一层容易混淆。XMLHttpRequest.upload 的进度事件反映请求体传输了多少。进度条走完后,应用仍需要写入完成记录和验证结果,才能向用户展示相应的状态。
作者也提醒,S3 兼容主要描述请求和对象模型。生命周期、权限、元数据、复制和恢复行为要以实际端点为准。涉及对象过期、版本保留或合规要求时,应拿代表性对象跑一遍规则。自建是否合适,要看团队是否有人负责容量、升级、复制和恢复演练。算容量时也要把预览图、放弃的任务、重试流量和高峰后清理积压的负载算进去。
我的判断
文章最扎实的地方是把故障定位落实到了可以测试的接口上。只看对象写入成功,可能把问题留到浏览器打开图片时才发现。加上输入校验、文件头检查和读回摘要,已经能定位不少常见的格式和存储问题。作者给出了示例和测试思路,没有提供故障率、延迟或成本的对照数据,按图片类别设上限、如何做告警等建议应当视为工程经验。
「验证 PNG」这个说法需要看清范围。签名检查能挡住错格式,摘要比对能确认存储前后的字节一致。如果生成端给出的 PNG 从一开始就缺少后半段,文件头和摘要仍可能都过关。产品如果要承诺用户能打开图片,更强的做法是用图片解码器做一次实际解码,代价是增加 CPU 和内存开销。团队可以根据图像来源的稳定性和可用性要求决定验证深度。原文建议部署前做集成验证,没有要求每张图上传后都额外读回一次。
能拿来做什么
- 在 Node.js 生图适配器里,把响应字段、允许的表示形式和大小上限写进校验逻辑,让
Buffer.from(value, "base64")只执行一次,写入接口直接接收通过检查的Buffer。 - 给队列 worker 分开记录解码拒绝和上传失败。前者按来源和发布版本统计,后者只对可恢复的错误执行有限重试,并使用请求 ID 派生稳定对象键。
- 给对象存储适配器加一条集成测试,用生产路径完成小图的写入和读取,校验摘要和
Content-Type。对可打开性有明确要求时,在验收样本里再做一次实际图片解码。 - 前端把传输进度和图片可用状态分开显示。进度条用
XMLHttpRequest.upload更新,图片状态等待服务端确认写入及相应验证结果。