docs/delivery-index-benchmark.md

Rama main · réplica de lectura del repositorio original.

# 阶段 4 交付索引基线

测量日期：2026-07-29  
固定模型：临时 SQLite 中保存一个图片目标，分别挂载 10,000 与 100,000 条规范化历史路径；测量完整 `delivery.Build` 数据库加载，再执行 1,000,000 次标准路径命中、别名命中和别名未命中。

测量程序先在单事务中准备数据，随后在完整索引加载前后执行 Go GC 并读取 `runtime.MemStats.HeapAlloc`。内存增量包含查询扫描后保留的索引 map、规范化路径字符串、图片 ID 值和一个交付目标；不包含 SQLite 原生内存、图片文件或 HTTP 缓冲。构建耗时从读取图片表开始，覆盖文件存在性校验、读取全部别名、严格路径校验和生成完整新 map；查找期间不访问 SQLite。

## Apple M4 arm64 本机

| 路径数 | 构建耗时（ms） | Go heap 增量（bytes） | 每路径（bytes） | 标准命中（ns） | 别名命中（ns） | 别名未命中（ns） |
|---:|---:|---:|---:|---:|---:|---:|
| 10,000 | 6.414 | 1,621,168 | 162.12 | 18.24 | 30.62 | 16.12 |
| 100,000 | 57.245 | 14,870,488 | 148.70 | 16.35 | 29.74 | 17.79 |

两组共 6,000,000 次查找的失败计数均为 0。100,000 条历史路径的完整加载耗时约 57 ms，Go heap 增量约 14.18 MiB，仍适合 V1 单进程完整索引；没有引入 LRU、TTL 或 SQLite 回源的依据。管理员主动重建时短暂保留新旧两份同规模索引，100,000 条路径对应的额外 Go heap 仍约为这一增量，而不是常驻翻倍。

## 自动验证

GitHub Actions [Verify run 30467177771](https://github.com/Willxup/imagesilo/actions/runs/30467177771) 在提交 `6d17dfb362a60c2be85cbad38ebbe26a099790f0` 上使用原生 `linux/amd64` 与 `linux/arm64` runner 执行同一程序。该测量只加载 SQLite、构建 Go map 和执行内存查找，不解码图片。

### 原生 linux/arm64

| 路径数 | 构建耗时（ms） | Go heap 增量（bytes） | 每路径（bytes） | 标准命中（ns） | 别名命中（ns） | 别名未命中（ns） |
|---:|---:|---:|---:|---:|---:|---:|
| 10,000 | 13.762 | 1,616,744 | 161.67 | 30.06 | 64.20 | 37.63 |
| 100,000 | 156.322 | 14,848,280 | 148.48 | 30.01 | 91.14 | 63.15 |

### 原生 linux/amd64

| 路径数 | 构建耗时（ms） | Go heap 增量（bytes） | 每路径（bytes） | 标准命中（ns） | 别名命中（ns） | 别名未命中（ns） |
|---:|---:|---:|---:|---:|---:|---:|
| 10,000 | 15.631 | 1,616,472 | 161.65 | 33.07 | 73.16 | 32.27 |
| 100,000 | 159.459 | 14,854,144 | 148.54 | 34.15 | 82.29 | 40.37 |

两个架构的 100,000 路径完整加载都低于 160 ms，Go heap 增量约 14.16 MiB，三类查找均低于 100 ns/次且失败计数为 0。该规模不需要 Redis、LRU、TTL、重复目标元数据或请求时 SQLite 回源。

复现命令：

```bash
go run ./tests/performance/delivery_index_benchmark
```