做云图库这类项目前几篇聊架构、聊协同、聊权限的时候都挺顺一旦推进到用户真的把图传上来这一步问题才会集中爆发。我带的几个类似项目里上传与元数据解析这一段几乎都经历过一次返工要么图片传上去了但方向是躺着的要么列表页里一堆图的拍摄时间是今天要么同一张图被反复传了五六次占了一倍存储要么解析服务在某个周末被一波批量上传把内存吃满直接挂掉。智能协同云图库这个项目也一样用户传图与元数据自动解析看起来只是收个文件、读几个字段实际上它同时牵扯上传协议设计、文件安全校验、EXIF 解析的兼容性、去重策略、异步任务编排和状态一致性这几条线任何一条没考虑到后面做标签检索、时间轴、地图相册、协同评论都会踩空。这篇内容面向三类人刚接手文件上传模块、想搞清楚为什么要拆成这么多步的同学正在被 EXIF 方向、拍摄时间、重复图折磨、想找一个能直接抄的实现方案的开发者以及想把云图库从能存能看升级成能搜能筛的产品侧同学。我会把这一篇的核心关键词——用户传图、元数据自动解析、分片上传、EXIF、感知哈希、去重、异步解析——都揉进具体的取舍和代码里不讲空话只讲我在真实项目里怎么选、为什么这么选、踩过哪些坑。1. 上传链路的整体设计与取舍1.1 为什么把接收文件和解析元数据拆成两段我一开始图省事接收文件、解析 EXIF、生成缩略图、写数据库全塞在同一个请求里本地测小图没问题一上真实环境就暴露了用户手机拍的 12MP 照片单张解析加缩略图大概 300 到 800 毫秒一次选 20 张上传前端看到的进度条直接卡在 100% 等半分钟接口超时用户以为失败又重传一遍。更麻烦的是解析器一旦遇到一张畸形 JPEG 抛异常整个请求挂了文件其实已经落盘数据库里却没有记录变成孤儿文件。拆成两段的核心逻辑是用户能感知到的只有文件是否安全到达而不是元数据是否解析完毕。接收入口的唯一职责是校验、落盘、登记一条待解析任务然后立刻返回一个 upload_id解析器作为独立消费者慢工出细活。这样做的收益有三点接口 P99 从几秒压到百毫秒级解析失败可以重试而不用让用户重传解析环节可以独立扩容批量导入时把 worker 从 2 个拉到 10 个就完事。代价是要接受元数据有短暂的空窗期。我的做法是在返回体里带一个parse_status字段前端列表项先显示占位骨架轮询或者用服务端推送把状态刷成 ready。用户体感上完全无感因为解析通常在 1 秒内就完成了。提示如果你的产品形态是上传后立刻要展示标签给用户编辑那就别硬拆异步改成同步只解析轻量字段尺寸、方向、拍摄时间重量级字段OCR、自动打标、人脸走异步做一个两级解析。1.2 服务端中转与直传对象存储怎么选这一步的取舍直接决定后面的成本结构。两条路服务端中转前端把文件 POST 给业务服务服务写本地盘或转手推到对象存储。优点是全链路可控鉴权、校验、审计都在自己手里缺点是大文件会占用服务带宽和连接数服务实例的出口带宽往往是最贵的资源。客户端直传对象存储服务端只签发一个短期的上传凭证前端直接和对象存储通信传完回调通知业务服务。优点是带宽成本转移到存储侧服务只处理元信息缺点是校验只能放在签凭证和回调确认两个时点中间的文件流你摸不到。我在这个云图库里选的是混合方案默认走直传但对小文件小于 2MB 的头像、图标、截图走服务端中转。理由是小文件走直传的流程开销申请凭证、建立连接、回调确认反而比直接传给服务还大而大文件走服务端会给带宽带来不成比例的压力。分界线定在 2MB 是基于实测这个尺寸以下中转请求的 P95 在 200ms 内用户可以接受同步等待。注意走直传时客户端声明的 MIME 类型和文件大小完全不可信必须在回调确认阶段用 HEAD 请求拿真实的对象大小和类型再和登记时的值比对。我遇到过前端把一个改后缀的 exe 声明成 image/png 传上来的情况靠回调校验拦住了。1.3 链路分层接入层、校验层、解析层、索引层把整条链路摊开看是四层层级职责关键产出失败处理接入层签凭证 / 收流、鉴权、限流upload_id、临时存储路径直接返回错误码不落盘校验层魔数、体积、像素上限、安全检查校验结论、sha256拒绝并清理临时文件解析层EXIF、尺寸、色彩、缩略图、哈希、打标结构化元数据进重试队列超过次数标 failed索引层写主表、写检索索引、更新相册计数可查询记录事务回滚 补偿任务这个分层的价值在于每一层都能独立替换。比如后面想接入一个新的图像识别服务只改解析层想把 MySQL 换成带向量检索的库只改索引层。我自己在第二个项目里就是直接把这套结构搬过去只替换了解析层的具体实现索引层一行没动。1.4 同步做校验、异步做解析的分界线这条分界线我划得比较死凡是会影响这张图能不能留在系统里的判断一律同步做凡是只影响这张图能被怎么找到的判断一律异步做。同步的包括文件魔数是否在白名单、解码后的像素总数是否超过阈值防解压炸弹、文件大小是否超限、用户配额是否还有余量、sha256 是否命中已存在的文件命中直接秒传不需要再走解析。异步的包括EXIF 完整解析、缩略图多尺寸生成、感知哈希计算、OCR、自动标签、地理信息反查。这条线一旦划错最典型的症状是用户上传后立刻去搜索搜不到或者秒传命中了但缩略图没生成列表页一片空白。前者是因为该同步的索引没写完后者是因为秒传分支漏了复用已有缩略图的逻辑。2. 元数据的三层结构与解析要点2.1 三层元数据文件本体信息、EXIF原始信息、业务衍生信息很多人把元数据当成一个笼统的概念结果表设计出来几十个字段混在一起既不好维护也不好迁移。我更习惯按来源分三层第一层是文件本体信息不依赖任何解析库就能拿到文件大小、sha256、MIME、扩展名、上传时间、上传者、原始文件名。这一层的可靠性最高因为全部来自系统自身。第二层是 EXIF/IPTC/XMP 原始信息从文件字节里读出来拍摄设备、镜头、光圈、快门、ISO、焦距、拍摄时间、GPS、方向、色彩空间。这一层的特点是不可信——可以被用户随意编辑可以缺失格式还特别多。第三层是业务衍生信息宽高、宽高比、是否透明、主色调、缩略图路径、感知哈希、自动标签、人脸框、OCR 文本。这一层是我们自己算出来的可靠性取决于算法。分层的实际好处是表结构可以按层拆表第一层和主表放一起查询高频第二层单独一张image_exif表字段多、查询低频、允许缺失第三层放检索表。这样一来主表不至于膨胀到七八十个字段加新算法时也不用改主表。2.2 EXIF解析最容易被忽略的四个坑坑一Orientation 字段不等于已经旋转好了。手机拍照时传感器方向和握持方向经常不一致相机不会真的旋转像素只在 EXIF 里写一个 Orientation 值1 到 8。如果你直接读宽高展示横图会显示成竖图如果你只按 Orientation6 处理那 Orientation8 的图又会歪。完整的映射关系是这样的Orientation 值含义需要的变换1正常无2水平镜像左右翻转3旋转 180 度旋转 1804垂直镜像上下翻转5顺时针 90 后镜像转置6顺时针 90旋转 907逆时针 90 后镜像反转置8逆时针 90旋转 270处理原则只在生成缩略图和派生图时应用变换原图保持字节不变。原图一旦被改写sha256 就变了秒传和去重全部失效。坑二DateTimeOriginal 和 DateTime 不是一回事。EXIF 里有三个时间字段DateTime文件修改时间最不可信、DateTimeOriginal拍摄时间最可信、DateTimeDigitized数字化时间。读取优先级应该是 Original Digitized DateTime。而且这些字段是本地时间且不带时区格式固定为YYYY:MM:DD HH:MM:SS。如果同时存在OffsetTimeOriginal可以用它补时区没有的话我通常按上传者所在时区兜底并在字段上打一个tz_inferred标记避免后面做时间轴时把跨时区旅行拍的照片排错顺序。坑三HEIC/HEIF 在多数服务端环境里读不出 EXIF。手机默认格式越来越常见Pillow 原生不支持 HEIC强行打开直接抛异常。稳妥的做法是引入专门的解码插件或者在接入层就把 HEIC 转成 JPEG 再进入解析流程。转码这个动作要记在新的一列里别覆盖原文件。坑四GPS 是度分秒的有理数不是十进制度。EXIF 里 GPSLatitude 是三个分数组成的数组还需要配合 GPSLatitudeRefN/S和 GPSLongitudeRefE/W才能确定符号。换算公式是十进制度 度 分/60 秒/3600南纬和西经取负。这一步算错后面地图相册的点位会整体偏移几百米而且很难发现。2.3 尺寸、色彩、透明通道的读取姿势尺寸这件事有两个值EXIF 里记录的像素宽高和解码后的真实像素宽高。前者可能缺失也可能和真实值不一致尤其经过编辑软件二次保存的图。我的做法是真实宽高以解码结果为准EXIF 宽高只作为参考存一列用于对比分析。色彩方面要存的是色彩空间sRGB / Display P3 / Adobe RGB / 灰度 / CMYK、位深、是否带 Alpha 通道。带 Alpha 的 PNG 在生成缩略图时如果直接转 JPEG透明区域会变成黑色这个细节在头像和 logo 类图片上特别扎眼。处理方式是按有 Alpha 就补白底再转 JPEG同时额外保留一份 WebP。还有一个容易被忽略的点像素总数的上限。一张 30000×30000 的 PNG 只有几百 KB解码后却要占几个 G 内存这就是典型的解压炸弹。我的阈值定在 5000 万像素大约 8660×5773超过直接拒绝并记录来源用户连续触发就给这个账号加验证。2.4 内容哈希与感知哈希的分工这两个东西经常被混为一谈实际上解决的是完全不同的问题。**内容哈希sha256**解决字节级完全相同同一张图被重复上传、被当作附件转发再传回来、用户误点两次上传按钮。命中就直接秒传零成本。**感知哈希pHash / dHash**解决看起来一样但字节不同同一张图被微信压缩过、被截图再存、被改了尺寸、被加了水印。这类重复无法用 sha256 抓到。我的实现里两个都算但用途分开sha256 命中 → 秒传直接复用已有的存储对象和全部元数据前端拿到的行为和普通上传成功一模一样。pHash 相似度超过阈值汉明距离 ≤ 6→ 不拦截只在结果里标记possible_duplicate给用户一个你可能传过这张图的提示最终由人决定。为什么 pHash 不做强制拦截因为误判成本太高。一张纯色背景的产品图和另一张同色系的同类产品图pHash 很容易判成相似硬拦会让用户觉得系统有病。而 sha256 是确定性判断拦截零风险。pHash 的计算步骤不复杂但有几个参数选择需要说明先把图转灰度、缩放到 32×32、做二维 DCT、取左上角 8×8 的低频系数含直流分量、求这 64 个系数的均值、大于均值的位记 1 否则记 0得到 64 位指纹。取 8×8 而不是 16×16是因为高频系数对压缩和轻微裁剪太敏感低频才反映整体结构。缩放前要先做一次高斯模糊去掉细碎纹理的干扰实测误判率能降三成左右。2.5 自动打标、OCR与地理信息的落点这三类衍生信息属于锦上添花但不能没有的部分它们决定了云图库能不能真的智能。自动打标我不用通用模型直接吐一堆泛化标签室内人物风景这种因为对检索帮助很小。更实用的做法是通用模型 业务词表映射模型输出给到一张映射表把猫科动物映射成宠物·猫把建筑外立面映射成建筑·外观。映射表由产品侧维护可以随时调整不用重新跑模型。OCR主要针对截图、票据、文档翻拍。要点是只对判定为截图或文档的图做 OCR靠宽高比接近屏幕比例、色彩数量少、边缘特征大量直角做预筛避免对每张风景照都跑一遍 OCR 白烧算力。地理信息EXIF 里有 GPS 就直接用没有的话结合上传时的网络出口大致区域做粗定位但一定要标记来源是exif还是inferred界面上区分展示。这一点很重要粗定位的精度只到城市级直接当地图坐标用会闹笑话。3. 从接收到入库的完整实操3.1 接口契约与前端分片策略接口设计上我拆成三个端点POST /api/v1/upload/init # 初始化返回 upload_id 与分片计划 PUT /api/v1/upload/{id}/part # 上传单个分片 POST /api/v1/upload/{id}/complete # 合并并入库init的请求体带上文件名、大小、sha256、分片总数服务端先查 sha256 是否已存在存在直接返回instant: true和一个 asset_id前端跳过后续所有步骤。分片策略固定分片大小 5MB阈值上小于 5MB 的文件不分片直接单次 PUT。为什么不用动态分片因为动态分片会让断点续传的已传分片列表变得难以对齐测试和排查成本明显上升而 5MB 对绝大多数场景已经够用。分片总数上限设 1000超过说明文件大于 5GB直接拒绝。断点续传的关键是init时如果发现同 sha256 有未完成的会话把已完成的分片编号列表返回给前端前端跳过这些编号。这个逻辑我用 Redis 存一个 Setkey 是upload:{sha256}:parts每个分片传完 SADD 一次会话超过 24 小时自动过期。3.2 服务端流式校验魔数与体积校验绝对不能信前端传的 Content-Type。我的做法是边收流边读前 16 个字节判断魔数同时累加字节数一旦超过声明大小立刻中断连接。MAGIC_WHITELIST { b\xff\xd8\xff: image/jpeg, b\x89PNG\r\n\x1a\n: image/png, bGIF87a: image/gif, bGIF89a: image/gif, bRIFF: image/webp, # 需再校验偏移 8 处的 WEBP bII*\x00: image/tiff, bMM\x00*: image/tiff, } def sniff(head: bytes) - str | None: for magic, mime in MAGIC_WHITELIST.items(): if head.startswith(magic): if mime image/webp and head[8:12] ! bWEBP: continue return mime return None注意 RIFF 这个魔数是容器级的AVI、WAV 都是它必须再看偏移 8 到 12 是不是WEBP。这类细节在安全校验里不能省否则白名单形同虚设。体积校验有个不那么直观的点用 Content-Length 预检只是优化不能作为安全边界。客户端可以谎报必须靠流式累加的实测字节数来兜底。3.3 解析WorkerPillow pyexiv2 的组合实现解析层我用的是 Pillow 做解码和缩略图、pyexiv2 做 EXIF 原样读取。为什么不用 Pillow 自带的_getexif()因为它是懒加载且字段名是数字键可读性差而且对某些厂商私有标签支持不全。pyexiv2 能拿到完整的标签字典还保留了原始类型。from PIL import Image, ImageOps Image.MAX_IMAGE_PIXELS 50_000_000 # 解压炸弹防线 def parse_image(path: str) - dict: result {} with Image.open(path) as im: im.verify() # 先做完整性校验 with Image.open(path) as im: raw_w, raw_h im.size orientation im.getexif().get(0x0112, 1) fixed ImageOps.exif_transpose(im) # 只作用于派生图 result[width] fixed.width result[height] fixed.height result[orientation] orientation result[mode] im.mode result[has_alpha] im.mode in (RGBA, LA, PA) result[format] im.format if result[has_alpha]: bg Image.new(RGB, fixed.size, (255, 255, 255)) bg.paste(fixed, maskfixed.split()[-1]) thumb_src bg else: thumb_src fixed.convert(RGB) thumb thumb_src.copy() thumb.thumbnail((512, 512), Image.LANCZOS) thumb_path path .thumb.webp thumb.save(thumb_path, WEBP, quality82, method4) result[thumb_path] thumb_path return result两个实操细节im.verify()之后文件对象会失效必须重新 open 一次这是很多人第一次写会踩的坑thumbnail()会原地修改并保持宽高比但不会放大小图传进去出来还是小图别指望它统一尺寸。EXIF 部分单独处理import pyexiv2 from datetime import datetime def parse_exif(path: str) - dict: out {} try: with pyexiv2.Image(path) as img: exif img.read_exif() except Exception: return out for key in (Exif.Photo.DateTimeOriginal, Exif.Photo.DateTimeDigitized, Exif.Image.DateTime): if key in exif: try: out[shot_at] datetime.strptime( exif[key].strip(), %Y:%m:%d %H:%M:%S) out[shot_at_source] key.split(.)[-1] break except ValueError: continue if Exif.Photo.OffsetTimeOriginal in exif: out[tz_offset] exif[Exif.Photo.OffsetTimeOriginal] if Exif.Image.Make in exif: out[camera_make] exif[Exif.Image.Make].strip(\x00 ) if Exif.Image.Model in exif: out[camera_model] exif[Exif.Image.Model].strip(\x00 ) if Exif.Photo.FNumber in exif: out[f_number] float(exif[Exif.Photo.FNumber].split(/)[0]) / \ float(exif[Exif.Photo.FNumber].split(/)[1]) return outFNumber、ExposureTime这类值在 EXIF 里是28/10这样的分数字符串直接存字符串后面做筛选排序会很难受一定要在做解析的时候就转成浮点。字符串里的\x00填充也很常见不 strip 掉前端展示出来就是Apple\x00\x00\x00。3.4 缩略图生成与方向校正缩略图我按三档生成160列表小图、512卡片、1280预览。三档都是 WebPquality 分别 75、82、86。为什么不存原图直接让前端缩因为原图动辄 8MB列表页一屏 30 张就是 240MB移动端直接崩。方向校正必须做在缩略图这一步而且三档都要用同一份已校正的图作为源不要每档重新读一次原图重新校正否则容易因为不同分支的处理差异导致三档方向不一致。还有一个实际遇到的问题竖构图的长图比如手机截图 1080×2400按最长边缩到 512宽度只剩 230列表卡片里会显得很小很空。我的处理是缩略图按短边对齐、长边裁切生成一份方形版本专门给网格视图用原比例版本给瀑布流用。两份都存多花一点存储换来的是布局不塌。3.5 秒传与重复图判定流程完整判定流程是这样的计算 sha256查asset表命中 → 直接创建一条新的用户-资源关联记录复用已有存储对象返回instant: true。这一步不产生任何新的文件。未命中 → 走正常上传落盘后再算 pHash用汉明距离在同用户最近 1000 张范围内比对距离 ≤ 6 标记possible_duplicate。无论是否命中都要写入用户配额统计。为什么只在同用户最近 1000 张里比对因为全库比对的计算量不可接受而实际场景中重复图 95% 以上来自同一个人的误操作或转发。1000 这个数字来自实测超过 1000 张以后命中率下降不明显但比对耗时已经上了 50ms。如果确实需要全库查重正确做法是用向量索引而不是暴力遍历。3.6 表结构与索引设计主表只放高频查询字段其余拆表CREATE TABLE asset ( id BIGINT PRIMARY KEY, owner_id BIGINT NOT NULL, sha256 CHAR(64) NOT NULL, storage_key VARCHAR(255) NOT NULL, mime VARCHAR(64) NOT NULL, bytes BIGINT NOT NULL, width INT, height INT, shot_at DATETIME, parse_status TINYINT NOT NULL DEFAULT 0, -- 0待解析 1成功 2失败 created_at DATETIME NOT NULL, UNIQUE KEY uk_sha (sha256), KEY idx_owner_time (owner_id, shot_at), KEY idx_status (parse_status, created_at) ); CREATE TABLE asset_exif ( asset_id BIGINT PRIMARY KEY, camera_make VARCHAR(64), camera_model VARCHAR(64), f_number DECIMAL(4,1), exposure VARCHAR(16), iso INT, focal_length DECIMAL(6,1), gps_lat DECIMAL(10,7), gps_lng DECIMAL(10,7), orientation TINYINT, raw JSON ); CREATE TABLE asset_feature ( asset_id BIGINT PRIMARY KEY, phash BIGINT UNSIGNED, dominant_color CHAR(7), ocr_text TEXT, tags JSON, KEY idx_phash (phash) );两个设计决策值得说sha256建唯一索引把防重复下沉到数据库层面避免并发下的 TOCTOU 问题shot_at允许为空并按它建索引是因为大量截图和下载图没有拍摄时间查询时要用COALESCE(shot_at, created_at)兜底排序索引也要按业务侧的实际排序键来设计。raw JSON那一列是刻意的冗余解析逻辑会演进新字段出来之前先把原始 EXIF 存一份后面想补算随时可以离线重跑不用让用户重传。4. 并发、性能与一致性4.1 内存控制与流式处理上传模块最容易出的事故是内存。我踩过的一次是服务被 OOM Kill事后看是三个原因叠加框架默认把请求体整个读进内存、多张图并发处理没有限流、缩略图生成时同时打开了原图和三个副本。逐条对策请求体不落内存。用流式读写边读边算 sha256 边写临时文件缓冲区设 64KB单请求内存占用稳定在几百 KB。解析 worker 并发数严格控制。CPU 密集型任务用进程池而不是线程池workers min(cpu_count, 4)超过这个数收益被上下文切换吃掉。缩略图逐档生成每档存完立刻调close()并触发一次gc.collect()别指望引用计数在复杂对象图里立刻生效。临时文件用完立即删除且要放在独立分区防止某次批量上传把根分区写满导致整个服务起不来。提示给解析服务单独设一个内存水位告警比如 RSS 超过 70% 持续 2 分钟比等到 OOM 再查日志省事得多。4.2 队列削峰、重试与幂等解析任务走消息队列key 用 asset_id消费者拿到任务后先查一次parse_status已经是成功状态就直接 ack 丢弃。这一条幂等检查能在重投、重复消费、手动补跑这几种情况下救你一命。重试策略是三次间隔 10s、60s、300s指数退避但不无限增长。三次都失败标parse_status2并把错误摘要写进日志同时发一条告警。别做无限重试一张永远解析不了的畸形文件会把队列堵死。队列积压时的处理监控消费延迟超过 5 分钟就自动扩容 worker。这里要小心一个陷阱——扩容 worker 的同时数据库连接池也得跟着扩否则 worker 起来了却卡在拿不到连接。我遇到过扩容后吞吐反而下降查了半天是这个原因。4.3 状态机与失败补偿parse_status不是简单的 0/1中间还有一个处理中状态否则重试时会重复处理同一个资源。完整状态是0 待解析 → 3 处理中 → 1 成功任何一步异常回到0累计失败三次进2 失败。失败补偿有两个来源定时扫描parse_status0 且 created_at 早于 10 分钟的记录重新投递以及数据库里存在但对象存储里找不到文件的幽灵记录扫描后标为异常并清理。还有一个跨服务一致性场景解析成功写了元数据但更新相册封面计数时数据库超时。这类非关键更新我用补偿队列异步做不让主流程因为它失败而整体回滚。4.4 上线后要盯的几组指标指标含义关注阈值上传接口 P99接入层响应 300ms解析成功率成功/总数 99.5%解析耗时 P95单张完整解析 1.5s秒传命中率命中 sha256 的比例观察值通常 5%~15%队列积压深度待消费任务数 1000孤儿文件数有文件无记录每日归零解析服务 RSS内存水位 70%秒传命中率这个指标挺有意思它不作为健康度判断但能反映用户行为。我之前专门看过一段数据命中率突然从 8% 涨到 23%排查发现是某个团队在批量导入同一批素材属于正常现象。这类业务信号比单纯的技术指标更有排查价值。5. 常见问题与排查速查5.1 上传中断与分片缺失症状是complete时提示分片不完整。三种原因前端并发上传分片时某个请求被浏览器取消、网关对单请求设了超时、对象存储侧合并时顺序不对。排查顺序先看 Redis 里的已完成分片 Set 和声明的总数对不对得上缺哪几片就补传哪几片别整个重传。网关超时的问题把分片大小从 5MB 降到 2MB 通常能绕开如果还是超时那就是网关配置的问题得去改。合并顺序一定要按分片编号排序后再拼按到达顺序拼出来的文件字节是乱的但大小完全正确这种错误极其隐蔽我遇到过一次一张图能打开但下半部分是花屏。5.2 图片方向错乱分三种表现缩略图躺着、原图躺着、只有部分图躺着。缩略图躺着 →exif_transpose没用或者用在了错误的时机。原图躺着 → 正常原图本来就不应该被修改。如果期望原图也正得在下载时按 orientation 动态处理或生成校正版。只有部分图躺着 → 检查是不是有些图走了特殊分支比如 HEIC 转码路径漏了校正。验证方法很简单找一张 iPhone 竖拍的照片看缩略图和原图里的同一根电线杆是不是都竖直。5.3 拍摄时间对不上最常见的表现是列表页所有图的日期都是今天。原因是只读了DateTime或者 EXIF 完全缺失后 fallback 到了created_at但代码里没做区分UI 全按shot_at展示。正确的兜底逻辑shot_at取 EXIF 拍摄时间 → 没有就取文件修改时间 → 再没有才取上传时间同时把来源记下来UI 上对推断出来的时间加个浅色标记。用户看到今天和看到今天推断接受度完全不一样。5.4 重复图与误判两个方向的问题都有。漏判的典型是改了一像素的图pHash 距离在 8 到 12 之间阈值 6 抓不到。误判的典型是纯色背景产品图互相撞车。我的调参经验阈值别贪心宁可漏判不要误判。因为漏判的后果是用户多存了一张误判的后果是用户觉得自己被系统冤枉了。真要抓得更严用pHash 主色调 宽高比三个条件同时满足才判重准确率能明显提升。5.5 内存与句柄暴涨表现是解析服务跑一段时间后响应变慢、最终挂掉。八成是文件句柄没关。Image.open返回的对象不 close句柄会一直挂着pyexiv2.Image一定要用with。排查手段看进程的open files数量正常应该在两位数几百个就说明在漏。另外注意异常分支里的清理try/finally里该 close 的必须 close别只在成功路径写。5.6 速查表现象大概率原因处理方式接口秒回但列表无图索引层异步没写完检查 parse_status 与轮询逻辑提示文件类型不支持魔数不在白名单 / RIFF 误判补白名单校验 WEBP 子类型上传卡在 100%落盘后退回慢 / 解析在同步阶段拆异步限制并发图片全黑或全白CMYK 或 16bit 位深解码问题先做色彩空间转换再处理透明区域变黑RGBA 直接转 JPEG补白底或改存 WebP大图上传直接 413网关请求体上限走直传或调大网关阈值同一张图存了多份sha256 唯一索引缺失补唯一约束 秒传逻辑解析耗时越来越长队列积压 / 死循环重试看积压深度检查重试次数上限这些条目基本覆盖了我在两个项目里真实遇到过的问题其中上传卡在 100%和同一张图存了多份是出现频率最高的两个建议在做这一模块的时候直接把对应的防护措施写进代码别等出事再补。最后分享一个我在实操中养成的小习惯解析模块上线前先手工构造一个坏样本集——包含一张 Orientation8 的竖图、一张无 EXIF 的截图、一张带 Alpha 的 PNG、一张改了后缀的伪 PNG、一张 40000×40000 的纯色大图、一张 HEIC、一张 0 字节文件。每次改解析逻辑先跑这七个全过再谈上线。这个习惯帮我省掉的返工时间比任何一次代码审查都多。
