架构

单实例设计复制锚点链接

ImgYoung 明确按单实例设计：一个进程、一个数据目录。

• 元数据库是一个 SQLite 文件（数据目录下的 imgyoung.db，WAL 模式）。写操作走单连接排队，读操作走连接池；驱动是纯 Go 的 modernc.org/sqlite。
• 任务队列在同一个库里：异步任务由 River 执行，它的任务表与业务表在同一个 SQLite 文件中，不需要额外的队列服务。
• 其余状态都在本机：上传并发闸、按用户的上传频控、登录限速、访问活跃度的聚合都在进程内存里，衍生图缓存在本地磁盘上。不使用 Redis。
• 单个静态二进制：全程 CGO_ENABLED=0，管理后台的前端产物与 OpenAPI 文档都编译进二进制。

因此 ImgYoung 不支持多个进程共享同一个数据目录，也不支持水平扩展。需要高可用时，升级路径是把数据库换成 PostgreSQL （River 本身支持 PostgreSQL，任务队列随之迁过去），进程内的共享状态届时再外置；当前代码只有 SQLite 实现。

分层与依赖方向复制锚点链接

http ──→ core ──→ infra
  │        └────→ store
  └─────────────→ infra

store 与 infra 是两个并列的叶子：store 不依赖任何 internal/ 包，infra 不依赖 core、store 与 http；core 同时依赖二者。 依赖方向由 golangci-lint 的 depguard 规则强制，CI 不通过即不能合并：

另外两条约定：

• 接口由使用方定义：各包在自己内部声明只含所需方法的小接口（如 upload.ChannelSelector、publicapi.BlobChannels），由具体类型隐式满足。 store/driver.Driver 是唯一的一等抽象。
• 身份显式传参：中间件解析出认证主体放进请求上下文，handler 取出后作为参数传给 core；core 不读 context 里的身份，按用户隔离在 core 中强制执行。

HTTP handler 与 River worker 都只是把外部触发翻译成服务调用的薄适配；周期任务是各服务自带的 Run(ctx, wait) 循环，由装配根统一编排，没有单独的调度层。

数据模型复制锚点链接

数据模型的核心是物理图与上传引用两层分离：

images(上传引用)──→ blobs(物理图)──→ blob_channels(各渠道的副本)──→ channels
       N : 1                  1 : N                          N : 1

• blobs 是一份实际存储的字节。每次上传都新建一个 blob；后台查重把字节完全相同的 blob 合并后，一个 blob 可以被多条引用指向。 它记录净化后字节的 sha256、感知哈希 phash、渠道内对象键 storage_key（形如 {short_id}_{sha256 前 8 位}）、MIME、大小、尺寸， 以及引用计数 ref_count 与待删标记。
• images 是一次上传产生的引用，对外的短 ID（10 位）就是它的主键。归属用户、来源 Token、S3 对象键别名、到期时刻与访问活跃度、 冷图标签与清理豁免都挂在引用上，不挂在 blob 上。
• blob_channels 记录某个 blob 在某个渠道上的副本，兼作补齐任务的状态：pending → uploading → done / failed，另有尝试次数与最近错误。

两层分离让几件事各得其所：查重合并只是把引用改指到保留的 blob；TTL、冷图与配额按引用计算；副本、补齐与物理删除按 blob 进行。

引用计数：ref_count 的增减都是原子的 UPDATE … SET ref_count = ref_count ± 1。删除引用与递减计数在同一个事务里； 计数归零的 blob 被标记待删，并按运营配置 delete_grace_minutes 记下物理删除时刻。到点后清理任务先清掉它的衍生图缓存， 再在一个事务里删除业务行并复查删除条件（期间又被引用就放弃本次删除），最后为每个持有副本的渠道入队对象删除任务。

其余的表：

表结构以 internal/infra/db/schema/ 下每表一个文件的声明式 SQL 为准，每张表与每一列都有注释。版本化迁移由 Atlas 据此生成， 随二进制内嵌，进程启动时按顺序自动应用，已应用的版本记在 schema_revisions 表里，跨多个版本升级也会补齐中间的迁移。

迁移不支持降级：库里记有本二进制不认识的迁移版本（即库已被更新版本的二进制迁移过）时，进程拒绝启动，错误信息写明库里与本二进制各自的最新迁移版本。 回滚只能用「旧二进制 + 升级前的快照」，见 升级。

上传数据流复制锚点链接

数据面上传、后台上传、URL 转存与 S3 PutObject 只在「字节从哪来」上不同，拿到字节之后走同一条管道。上传路径不查重：每次上传都新建 blob， 查重在后台进行，上传路径因此是一条没有分支的直线。

整个上传在内存中完成，不写临时文件；峰值内存约为「并发数 × max（单图上限，像素预算对应的解码内存）」，调低这几项即可适配小内存机器。 渠道写入成功而落库失败时会留下孤儿对象，由对账 GC 回收，不回滚渠道写入。

访问数据流复制锚点链接

GET / HEAD /i/{id}（以及 S3 对象键别名 /o/{user_id}/{key}；后台预览图 /api/admin/images/{id}/thumb 走同一条管线，但不计访问）：

1. 防盗链中间件按 Referer 白名单放行或返回 403（后台预览图不经过这一步）。
2. 查引用，查不到返回 404。到期时刻已过的引用立即按不存在处理，不必等清理任务回收，也不会被访问续期。
3. 校验处理参数：w 不在宽度档位、显式 format 不在允许格式时返回 400（GIF 原图不处理，忽略这两个参数）。
4. 计访问：只有对外入口的 GET 才在内存中累计活跃度，按 activity_flush_seconds 批量落库；HEAD、参数非法的请求与后台预览图都不计访问。
5. 需要缩放或转格式时走按需处理：带 w、显式 format，或未指定格式而浏览器接受 WebP、档位允许且原图不是 WebP。GIF 一律输出原图。 命中衍生图缓存直接返回；未命中则在 process_workers 并发上限内处理并写入缓存，相同参数的并发请求合并为一次处理； 处理繁忙或失败时降级输出原图，并带 Cache-Control: no-store。HEAD 请求同样取或生成衍生图，只是不返回正文。
6. 否则输出原图：候选渠道为「健康、不在清理中、该图副本为 done」的渠道，按优先级排序。访问模式为 redirect 且候选中有允许直链、 未加密并配置了公开地址的渠道时，302 到该渠道，重定向带 Cache-Control: no-store（目标随渠道健康与配置变化，不能被缓存）； HEAD 请求只写响应头，不读渠道对象；其余用 failover.Open 代理读取，第一个渠道读不到立即切下一个。

缓存语义按入口区分：

两个入口的原图与衍生图都带强 ETag（原图为内容哈希，衍生图为哈希加处理参数），请求的 If-None-Match 与之相同时返回 304； 304 带上 200 响应会有的 ETag、Cache-Control 与 Vary，缓存据此续用已存的副本。格式经 Accept 协商的响应带 Vary: Accept； 降级输出的原图为 no-store，不走 304。数据库查询失败时返回纯文本 500，可以重试。

outbox 围栏：业务表是唯一真相复制锚点链接

异步补齐由 River 执行，但 River 的任务只是幂等的触发器，副本状态的唯一真相是业务表 blob_channels：

• 补齐任务的含义是「确保 blob X 在渠道 Y 上有副本」。worker 先读业务表：已是 done 直接返回；开始复制前置为 uploading， 失败退回 pending 交给 River 重试，最后一次尝试仍失败置为 failed，成功置为 done。
• 入队按（blob，渠道）去重，只对尚未结束的任务去重，同一副本不会在队列里出现两份。
• 对账在启动时与之后每 10 分钟执行一次：为清理中的渠道补入排空任务；为每个渠道补种缺失的副本行；把健康渠道上 failed 的副本复位为 pending； 再按主键游标分页扫描全部 pending / uploading 副本，重新入队；扫描期间有副本变成 done 也不会让后面的页错位漏行。

所以即使 River 的任务表丢失或损坏，队列也能从业务表完整重建；进程被强制杀死时正在执行的任务，超过 16 分钟仍停在运行态会被 River 重新排程。 新建渠道时为存量 blob 播种 pending 副本行，同样由这套机制自然收敛，没有额外的回填逻辑。

其他异步任务遵循同一原则：删除渠道上的对象（delete_object）、排空清理中的渠道（drain_channel：先按剩余的副本行逐个删除副本对象，进度就是剩余的副本行；再删除该渠道上 _imgyoung/ 下的系统对象（含元数据库快照）与深探测残留，别的程序写的对象不动；最后删除渠道记录）、 清理 CDN 缓存（cdn_purge）。它们都是幂等的，失败由 River 退避重试：对象删除最终失败留下的孤儿由对账 GC 回收； 排空任务删对象第一次失败就把原因写进渠道的探测结果并触发 drain_failed 告警，之后一直退避重试，尝试次数用尽后由对账重新入队， 不会停止（任务自身超时或停机取消不算失败），出口是在后台对该渠道选择「直接移除」（远端对象保留）；CDN 清理最终失败时，边缘缓存在 CDN 自身的缓存期满后过期。

周期任务复制锚点链接

周期任务都是服务自带的循环，由装配根统一启停。间隔取自运营配置的，在后台修改后立即按新值重新计时，不必等旧的周期走完。

对账 GC 的口径复制锚点链接

对账 GC 处理的对象（系统目录 _imgyoung/ 与轻探测键不参与比对）：

• 孤儿：只回收同时满足以下条件的对象——键名是本服务的对象键格式 {short_id}_{sha256 前 8 位}；库里没有该渠道任何状态的副本记录； 修改时间不早于该渠道的绑定时刻；已过 48 小时宽限期（覆盖「已写入渠道、尚未落库」的在途上传）。其余库里没有记录的对象， 例如别的程序写进来的文件、灾备时新实例接入旧桶而元数据还没恢复的对象、从快照恢复之前写进渠道而恢复后的库里没有记录的对象，只计数不回收，对账日志里记为 foreign。
• 深探测残留：深探测删除失败留下的 .imgyoung-probe- 临时对象不看写入时刻，过 48 小时宽限期即删，也不计入对账统计的对象数与字节数。
• 幻影：库里记为 done、渠道上实际缺失的副本，退回 pending 并重新入队补齐。

绑定时刻（channels.bound_at）表示这条渠道记录从什么时候起对应当前的存储位置，本服务只会在它之后往这个位置写对象：

• 新建渠道时等于创建时刻。新实例接入旧桶时，桶里原有的对象都早于它，只计数不回收。
• 在后台编辑渠道时，后端名或任何配置参数有改动，即重置为编辑时刻；重新输入同一个密码也算改动（rclone 编码密码时带随机 IV）。 只改名称、优先级或直链开关不重置，令牌刷新写回也不重置。
• 从快照恢复后，全部渠道重置为恢复后启动的时刻：换入快照之前，在数据目录写下标记文件 imgyoung.db.restored； 迁移之后、加载主密钥之前见到标记即重置，成功后删除标记，日志为 换入快照后已把渠道绑定时刻重置为当前时刻,快照之后写入渠道的对象不会被对账回收。这样，快照之后上传、在恢复后的库里没有记录的对象不会被当作孤儿删除。 标记在换入暂存文件 <数据目录>/imgyoung.db.restore 时写下，后台恢复就是先暂存这个文件；手动恢复也要把快照放成这个文件再启动， 不要直接覆盖 imgyoung.db，否则不会写标记、不会重置绑定时刻。

created_at 不随绑定时刻变化：它与渠道 ID 一起参与加密渠道的密钥派生。

停机复制锚点链接

停机（收到 SIGINT / SIGTERM，或在后台恢复备份快照后请求重启）按顺序进行：先停收新请求，在途请求最多等 6 秒，超时强制断开； 再取消后台循环与在途的补齐任务，补齐子系统最多等 2 秒，各循环退出前把内存中待落库的数据写完；最后关闭渠道驱动与数据库。 两段合计 8 秒，在 Docker 默认 10 秒的强制终止时限之内，deploy/ 下的示例配置还另留了余量（compose 的 stop_grace_period: 15s、 systemd 的 TimeoutStopSec=15s）。被取消的补齐任务状态留在业务表里，下次启动由对账重新入队。

技术选型复制锚点链接

选型围绕同一个前提：单实例、单个静态二进制，除了存储渠道，部署时不需要任何外部服务。依赖的具体版本以仓库的 go.mod 为准。

语言与构建复制锚点链接

• Go：静态编译成单个二进制，Docker 镜像小；多渠道写入、异步补齐、健康探测、任务队列这类 I/O 编排用 goroutine 写起来直接； 对象存储、HTTP、指标监控的生态成熟，语法简单、编译快，参与贡献的门槛低。决定性的一条是 rclone 本身用 Go 编写， 只有 Go 能在进程内直接调用它的后端，见为什么在进程内集成 rclone。
• 全程 CGO_ENABLED=0：不依赖 C 工具链与系统库，才能交叉编译出 Linux、macOS、Windows 各两种架构的发布包， 并放进只有一个二进制的 distroless 镜像。下面每一项依赖都是纯 Go 或不需要 cgo。构建一律带 -tags nodynamic： WebP 库默认会在运行期尝试加载系统的 libwebp，关掉这条路径后，Linux 二进制才不依赖动态链接器。

依赖复制锚点链接

项目以 MIT 许可发布：与 rclone 一致，贡献门槛最低；自部署工具不存在被云厂商拿去托管转售的现实顾虑。

不引入的东西复制锚点链接

• Redis：单实例下没有它的位置。幂等键、引用计数这类需要原子性的地方交给 SQLite 的约束与原子更新，限流是进程内令牌桶， 衍生图缓存在本地磁盘。单实例下进程内的实现严格优于 Redis：没有网络往返与序列化，也不多运维一个服务。走向多实例时才需要重新考虑。
• 配置文件与配置库：环境变量只负责把进程启动起来，其余运营配置以数据库里的 settings 表为唯一依据、在后台修改， 「这个值从哪来」永远只有一个答案，见配置。
• ORM、DI 框架、cron 库：理由见上表。

SQLite 与版本化迁移复制锚点链接

SQLite 是单个文件、没有外部依赖，一致性快照也就是一个文件，最贴合自部署，也与单实例设计相配。 版本化迁移从第一天起就有：长期运行的自部署实例会跨很多个版本升级，没有版本化迁移，表结构很快失控。迁移只有升级方向，见数据模型。

两条升级缝复制锚点链接

只有两处预期会被替换，其余选型都是定死的：Go 生态的薄库都贴着标准库的形状，真要替换也是机械劳动，为此预留灵活性没有收益。

• 图像处理引擎：按需处理的唯一入口是 internal/infra/imaging 的 Processor.Process(src, params)。当前是纯 Go 实现：标准库解码 JPEG / PNG / GIF，WebP 编码用 gen2brain/webp，只输出 WebP、JPEG、PNG，GIF 只收发原图不处理。AVIF、HEIF 不在其列：使用率低， 编码器（如 libaom）又重。需要更多格式或更快的处理时（例如基于 libvips 的实现），替换的是这个处理器。
• 数据库：当前是 SQLite。表结构以声明式 SQL 为准，迁移由 Atlas 生成，查询代码由 sqlc 生成；换 PostgreSQL 时， 按目标方言重新生成查询代码与迁移，并换上 River 的 PostgreSQL 驱动。

两处目前都只有一个实现，没有为它们预先定义接口类型。

为什么在进程内集成 rclone复制锚点链接

存储层的原则是：rclone 只负责「把字节存到某个后端、取回、查询、列举、删除」，主备切换、补齐、引用计数、查重、TTL、健康判断全部由 ImgYoung 自己实现， 两者之间隔着 store/driver.Driver 接口。

集成方式是直接 import rclone 的 fs 与后端包，在进程内以参数映射构造 fs.Fs，而不是调用 rclone 命令行、librclone 的 RPC 接口或 rclone 配置文件：

• 流式、不落盘：上传用 fs.Fs.Put 直接写内存里的字节，读取直接把对象流转给 HTTP 响应。
• 配置在自己的库里：渠道参数用主密钥加密后存在 channels 表，运行时解密成映射交给后端；参数含凭证，不写日志，错误链也不携带参数。
• 令牌写回只有一个刷新者：rclone 自己刷新 OAuth 令牌，经参数写回钩子交给应用，立即加密落库；应用不另起刷新循环。
• 一个句柄完成全部操作：读、写、探测、列举、删除走同一个 fs.Fs，错误映射只维护一套（对象缺失统一收敛为 driver.ErrNotFound）。
• 渠道加密零额外代码：加密渠道在后端之上叠加 rclone 的 crypt 层，上传与访问路径无需改动；crypt 是公开格式，持密码可以用标准 rclone 独立解密。见 渠道存储加密。
• 配置可以原样导出：后台能为每个渠道导出一份 rclone 配置文件，参数与驱动实际交给后端的完全一致，加密渠道另带 crypt 远端； 它由 store/rclone 的 ConfigFile 生成，与构造驱动共用同一套参数整理，标准 rclone 凭它即可脱离 ImgYoung 读写渠道数据。见 驱动接口与 rclone 实现。
• 测试不需要云账号：rclone 的 local 与 memory 后端让整条存储链路可以在本机做集成测试。

注册全部 rclone 后端（backend/all）意味着任何 rclone 支持的存储都能直接作为渠道使用，rclone 升级即带来新后端；代价是二进制体积达到百 MB 量级。 这里用的是 rclone 的内部 API，它不承诺稳定，所以 go.mod 固定了 rclone 版本，升级由人工进行并跑完整测试。

Driver 接口不假设 rclone 存在，这也是 rclone 内部 API 变动时的退路：换一个 Driver 实现即可，业务代码不动。 接口与 rclone 实现拆成两个包，也让应用之外的 Go 项目可以单独复用这套存储引擎，见 作为 Go 库使用。