上传

上传入口复制锚点链接

四个入口走同一条上传管道：格式校验、像素预算、配额预检、EXIF 处理、写入渠道、入库。 差别只在字节从哪来，以及能带哪些选项：S3 入口不能逐次指定有效期，不做 EXIF 处理，也不支持幂等键。

上传 Token 在后台「上传 Token」页签发，见 管理后台。

用接口上传复制锚点链接

curl -H "Authorization: Bearer imgy_xxxxxxxx" \
  -F "file=@photo.jpg" \
  https://img.example.com/api/upload

带上全部可选项：

curl -H "Authorization: Bearer imgy_xxxxxxxx" \
  -H "Idempotency-Key: 7d0c6a2e-photo-0001" \
  -F "file=@photo.jpg" \
  -F "ttl=604800" \
  -F "exif_policy=strip" \
  https://img.example.com/api/upload

ttl 与 exif_policy 只从 multipart 表单字段读取，写在 URL 查询参数里不生效；每个字段最多 1 KiB，超出返回 400。表单里的其他字段被忽略。 请求头 Idempotency-Key 可选，见 幂等键。

成功返回 200：

{
  "id": "R0RjUyP1UW",
  "url": "https://img.example.com/i/R0RjUyP1UW"
}

• id 是 10 位短 ID，字符取自 0-9A-Za-z。
• url 恒为绝对地址：设置了「对外站点地址」（base_url）就用它；没设置时按本次请求推导，协议看连接是否 TLS，域名取 Host 头。 经信任的反向代理转发时改看 X-Forwarded-Proto 与 X-Forwarded-Host（信任范围由环境变量 IMGYOUNG_TRUSTED_PROXIES 决定）。 反代或 CDN 对外的域名与请求里的域名不一致时，必须配置 base_url，见 配置 与 反向代理。

失败时返回 {"error": "…"}，状态码见 状态码速查。完整接口定义见 接口参考：数据面。

幂等键复制锚点链接

网络不稳时客户端可能重发同一次上传。请求带 Idempotency-Key 头，就能避免重发产生第二张图：

• 键按用户隔离，不同用户用同一个键互不影响，也就无法借幂等键探测或取到别人的图。
• 保留期内，同一用户带同一个键的请求直接返回第一次成功上传的 id 与 url，不再写入渠道。保留期由 idempotency_key_ttl_hours 决定，出厂 24 小时，从第一次成功时起算。
• 命中后不比较本次请求的内容：同一个键换了文件，返回的仍是第一次的那张图。每张不同的图要用不同的键。
• 只有成功的上传会记下键；失败的请求可以带同一个键放心重试。
• 并发发出的同键请求只有一个真正入库，其余返回同一结果。
• 超过保留期的键由清理扫描回收；图片被删除时，指向它的键一并删除。此后再用这个键会被当作新上传。

/api/upload、/api/upload/url 都支持幂等键；S3 入口没有。

URL 转存复制锚点链接

给一个图片地址，服务端替你下载后入库，常用来把散在其他图床的图收回来。抓回的字节与直接上传走同一条上传管道，格式白名单、像素预算、EXIF 处理与配额照常生效；服务端不会把远端文件直接拷进渠道。

curl -H "Authorization: Bearer imgy_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.png", "ttl": "never"}' \
  https://img.example.com/api/upload/url

请求体是 JSON 对象，只允许以下字段（出现其他字段返回 400），大小不超过 8 KiB：

返回体与 Idempotency-Key 的用法和表单上传相同。抓回的字节按内容判定格式，远端声明的 Content-Type 不参与判断。

抓取限制复制锚点链接

这个入口相当于让服务端替请求方发起外部请求，所以抓取有一组固定约束，防止被借来探测你的内网：

被拒绝的地址段：

• IPv4：0.0.0.0/8、10.0.0.0/8、100.64.0.0/10、127.0.0.0/8、169.254.0.0/16（含云厂商元数据地址 169.254.169.254）、172.16.0.0/12、192.0.0.0/24、192.168.0.0/16、198.18.0.0/15、224.0.0.0/4、240.0.0.0/4。
• IPv6：::/128、::1/128、::/96、64:ff9b::/96、64:ff9b:1::/48、2002::/16、fc00::/7、fe80::/10、ff00::/8。IPv4 映射地址（如 ::ffff:127.0.0.1）按其中的 IPv4 判定。

另外几点：

• 抓取直连目标，不使用 HTTP_PROXY 之类的代理环境变量。
• 请求不带 Referer，User-Agent 是 Go 标准库的默认值。开了防盗链或屏蔽爬虫的源站可能拒绝，表现为 502。
• 抓取期间占用一个上传并发名额（见 格式与上限）。

在管理后台上传复制锚点链接

在「图片」页点「上传图片」，弹窗里有两个标签：

• 「本地文件」：点击选择或把图片拖进虚线框，可多选；弹窗打开期间按 Ctrl / ⌘ + V 可直接粘贴剪贴板里的图片。文件每次最多两个同时上传，其余排队。
• 「链接转存」：填图片地址后点「转存」，等同于 URL 转存。

弹窗下方的「有效期」（默认 / 永久 / 自定义小时数）与「EXIF」（默认 / 剥离 / 保留）对之后加入的文件生效，「默认」即不传该字段。 关闭弹窗不会中断进行中的上传；每张上传成功后列表里显示链接，可一键复制。

后台上传归属当前登录账号，不需要 Token，图片详情里的「来源」显示为「后台上传 / 来源已删除」。它与 Token 上传共用频控与并发闸。

格式与上限复制锚点链接

只接受 JPEG、PNG、GIF、WebP。格式按文件内容（magic bytes）判定，并与解码器识别出的格式交叉核对，扩展名与客户端声明的类型一概不看。

• 不接受 SVG（可内嵌脚本）。
• 动画 GIF 可以上传，原样保存，访问时始终输出原图，动画保留。
• 动画 WebP 不支持，上传返回 400。

• 并发闸全局只有一份，数据面上传、URL 转存、后台上传与全部 S3 请求（包括 GET / HEAD / DELETE）共用。它限制的是同时在处理的请求数；上传内容不论大小都只在内存里处理、不写临时文件，所以这个数决定了上传的峰值内存。满了立即返回 429，不排队。
• 像素预算挡的是解码后的内存：它由分辨率决定，与文件大小无关，一张 2000 万像素的图解码成 RGBA 约 80 MB。所以先只读图片头判断，超限的图不进入解码。
• 频控按用户计，同一用户经 Token、后台与 S3 PutObject 的上传共享额度。算法是令牌桶：可以一次性连续上传 N 张（N 为每分钟额度），之后每 60/N 秒恢复一张。额度保存在进程内存里，重启即重置。
• 配额按引用计全额：每条图片记录都按其物理文件的完整大小计入归属用户，后台查重合并不会减少已用量。预检用上传时的原始字节数。

以上配置都在「设置 → 运行配置」修改，保存即生效，见 配置。用户配额在「用户」页设置。

状态码速查复制锚点链接

EXIF 处理复制锚点链接

出厂默认是 passthrough：存储商能看到原图的问题由渠道存储加密解决；要不要对拿到链接的访客抹掉元数据，是上传者自己的选择，所以默认不改动原图。

本次上传的档位按「表单字段（或 JSON 字段）> 全局默认 exif_policy」决定。S3 上传不做 EXIF 处理，一律按原字节保存：S3 客户端按大小与 ETag 核对上传结果，保存的字节必须与上传的一致。 spoof（伪造元数据）尚未开放，传入返回 400，也不能设为全局默认。

strip 是字节级操作，不重新编码、不改动任何像素：

• 图片的 SHA-256（后台显示的哈希、查重的依据）按剥离后实际保存的字节计算。
• passthrough 保存的原图里的 GPS 等信息，任何拿到链接的人都能取到原始字节读出来。 按需处理 输出的衍生图是重新编码的，不带元数据，但原图本身仍可访问。

为什么在上传时处理复制锚点链接

EXIF 档位在上传那一刻生效，保存的就是处理后的字节；访问时不再按当前设置重新处理原图。

原因是访问层的缓存建立在「同一个 /i/ 链接的字节永不改变」之上：响应带 Cache-Control: immutable，浏览器与 CDN 可以放心缓存一年。 如果改成访问时处理，全局档位一改，同一个链接输出的字节就变了：CDN 上的缓存要整体清除，而访客浏览器里已经缓存的旧字节无法让它失效。

访问时处理的主要好处，是原图可以原样留在渠道、只在出口净化；存储商侧的隐私已由渠道存储加密解决，上传时处理加上默认 passthrough 已经覆盖了这层需要，不值得为它放弃不可变缓存。

同一张图多次上传复制锚点链接

上传路径上不做查重：同一个文件上传两次，得到两个短 ID，渠道里也会先写入两份。

这是有意的：上传路径上没有「秒传」之类的分支，每次上传都完整走一遍校验、写渠道与入库，出问题的面最小。查重只用上传时顺手算好的哈希， 在后台是纯数据库操作，不必重新解码图片。

后台查重循环（出厂每 300 秒一轮，dedup_scan_seconds）会把实际保存字节完全相同的物理文件自动合并为一份，多余的那份按删除宽限期清理。合并后：

• 每次上传仍有自己的短 ID、有效期、访问计数与归属用户，所有链接继续可用。
• 配额按引用计全额，合并不减少已用量。

用不同 EXIF 档位上传的同一张照片，保存的字节不同，不会被自动合并；它们的感知哈希接近，会进入「疑似重复」等管理员裁决。 细节见 生命周期与查重。客户端重试造成的重复，用 幂等键 从源头避免。

写入语义复制锚点链接

一次上传在返回之前，按优先级从高到低依次写入健康渠道，直到写成功的份数达到 min_success（「最少同步副本」，出厂 1）：

1. 写入失败或超时（每次写入最长 10 分钟）就顺延到下一个健康渠道；第一个写成功的渠道就是这张图的主渠道。
2. 份数凑够后写入元数据库并返回。其余渠道记为待补齐，由后台补齐任务异步复制，不拖慢本次上传。
3. 健康渠道不足、或全部尝试后份数仍不够，返回 503。已经写进渠道的对象成为孤儿，由对账任务在 48 小时宽限期后回收。

min_success 大于 1 时，一次上传要等多个渠道都写完才返回，换来返回时就已有多份副本；健康渠道数少于该值时上传一律 503。 渠道的优先级、健康探测与补齐见 存储渠道。