存储架构¶

当前内容契约更新：固定来源 PDF 已恢复为 paper_access 开关下的鉴权字节，关闭404，qa_、别名、Range、历史原件不能绕过。新内容在独立 qatlas-content 桶的 content/ 命名空间不可变发布：source 绑定确切 PDF SHA，arXiv vN 是语义版本、 S3VersionId 是物理版本、parse revision 是独立不可变身份；三者不可混用。同 paper/SHA 可复用 source；冻结导入别名不同字节409（overwrite也不替换）。解析上传必须完整支持的 Middle+Markdown，保留所有成员原名/字节，MD-only拒收； manifest最后核验发布且PG必需，重传新revision，不覆盖历史。旧MD/JSON/images忽略，只在内容/PDF访问按需冻结旧PDF，不bulk回填、不删除旧桶；没有nightly/boot/入库自动推理。下文涉及旧三桶覆盖、仅full.md+images、原PDF410/外部直链的段落保留为历史背景， 不作为当前操作规则。当前API/上传/续读统一见论文内容契约与Upload API；完整read视图不是原Middle JSON。

范围：QuantumAtlas 处理大体量论文时各存储引擎（对象存储 + PostgreSQL registry/corpus）的职责边界、数据流与对账规则。本文给"为什么不把 PDF 塞数据库"、"registry 漂移了怎么重建"、 "桶之间漏对象怎么核"这类反复出现的问题一个 canonical 回答。

不在范围：具体安装步骤 / 容器配置 / bootstrap 脚本走 deployment/；项目整体应用分层走 architecture.md；多边缘节点拓扑走内部仓库的部署文档。

1. 为什么分多个引擎¶

QuantumAtlas 处理论文图谱的本质问题是：

PDF 是 MB 级 blob，存量 TB 级，IO 模式是"偶尔整文件下载"。
元数据要按字段筛（"有 PDF 但没 markdown 的"、"上周处理过的"、"category=quant-ph"）。
引用关系是集合型 join（OpenAlex works 的内联 referenced_work_ids，GIN 反查），跟 blob IO 完全不同，但跟元数据筛选天然同构。

强行让一个引擎全包是反模式。用合适的引擎做合适的事，各层各管各的，通过稳定标识符串起来：

层	引擎	存什么	数据量级	访问模式	source of truth
Raw blobs	RustFS（S3 兼容）	PDF / Markdown / 图片 / OpenAlex snapshot	TB	偶尔整文件下载	✅ 原文不可变
Metadata 索引	PostgreSQL catalog	`papers` + `paper_assets` 表 + partial indexes	134k 行起步	字段筛选 / count / group by / MinerU lease	❌ 可从 bucket LIST 重建
OpenAlex 语料	PostgreSQL（同库，另一组表）	`openalex_works`(jsonb，含内联 `openalex_referenced_work_ids`) + `work_embeddings`	~2.87×10⁸ 行 / 1–2 TB	jsonb `@>` / 引用 join / 向量 join	❌ 可从 OpenAlex snapshot 重灌

这几层不竞争，互补。Raw 量翻 10×，registry 完全不动；PostgreSQL registry 漂移，从 bucket LIST 跑 papers sync 重建 + 对账；OpenAlex corpus 漂移，从 snapshot 重灌。

2. 三层是怎么串起来的¶

        flowchart LR
    USER[Client<br/>浏览器 / qatlas CLI]

    subgraph EDGE ["Edge — qatlasd Go 进程"]
        API[HTTP API]
        PG[PostgreSQL catalog<br/>papers + paper_assets]
        API -.->|SQL| PG
    end

    subgraph RUSTFS ["RustFS 对象存储"]
        PDF[(qatlas-pdf)]
        MD[(qatlas-md)]
        IMG[(qatlas-images)]
        OA[(qatlas-openalex)]
    end

    USER -->|HTTPS| API
    API -->|S3 GET/PUT| PDF
    API -->|S3 GET/PUT| MD
    API -->|S3 GET/PUT| IMG
    API -->|S3 GET/PUT| OA

    OA -.->|openalex bootstrap-pg| PG
    PDF -.->|papers sync<br/>reconcile| PG

    style RUSTFS fill:#e8f5e9
    style EDGE fill:#e3f2fd

arxiv ID 作为稳定标识符（不 content-addressed）：

对象 key 形如 <yymm>/<stem>.<ext>（如 2401/2401.00001.pdf），arxiv-id 寻址
sha256 进 object metadata (x-amz-meta-sha256) 做 content-aware idempotency：
- 同 arxiv_id 重传相同字节 → 短路 200 unchanged，不重写 S3
- 不同字节 → 409 with both hashes，旧对象不动
- --overwrite 才覆盖（旧版本由 bucket versioning 自动保留）
多 client 并发用 S3 conditional PUT (If-None-Match: "*") 保证 race-safe（不会 silent last-writer-wins）
client 上传时 ?expected_sha256= 做 in-transit 损坏防护（PyPI / Docker 同款）

完整 upload 写口语义、conditional PUT 实现细节走 reference/upload-api.md。

3. RustFS 桶布局¶

5 + 1 桶速查¶

桶	内容	key 模板	大小	访问模式	公开 / 私有
`qatlas-pdf`	论文 PDF blob	`<yymm>/<stem>.pdf`	MB / 个	仅 server / 贡献者上传通道	🔒 字节永不外发（无下载 API）
`qatlas-md`	MinerU 转换的 markdown	`<yymm>/<stem>.md`	KB / 个	仅内部读取 / 贡献者上传	🔒 字节永不外发
`qatlas-images`	markdown 内联图（一个 paper 一个子目录）	`<yymm>/<stem>/<file>`	KB ~ 100KB / 张	仅内部读取	🔒 字节永不外发
`qatlas-openalex`	OpenAlex 字节级 snapshot mirror	`data/<entity>/<part>.gz`	GB / part，TB / 桶	离线 bootstrap / 定期增量	🔒 仅内部使用
`qatlas-raw`	历史单桶（v0.6.x 时代），冻结只读做 cold backup	`pdf/<yymm>/...` 等	TB	备查	🔒 不再写
`qatlas-s3-events`	RustFS notify webhook 落盘的 PUT/DELETE 事件流（NDJSON.snappy）	Fluent Bit 自管	KB ~ MB / 文件	审计 / 离线分析	🔒 无 Delete 权限（write-once 审计）

PostgreSQL catalog 不在 RustFS 桶里；RustFS 只保存资产对象。catalog 漂移时通过 qatlasd papers sync --full --from-rustfs 从三桶 LIST 重建资产状态。

命名约定¶

<yymm> shard：所有论文资产按 arxiv ID 前 4 位 <yymm>（YearMonth）分片。

2401.00001 → <yymm> = 2401
老格式 quant-ph/9508027 → <yymm> = 9508（含 80s/90s 历史论文）

每月 quant-ph 通常几百到几千对象（月均 ~500 篇），listing / 迁移 / 对账按 yymm 切批友好—— 单次 list 在 RustFS HDD 上可控。

<stem> arxiv ID：path-safe arxiv ID 字符串。

新格式 → 2401.00001 直接当 stem
老格式 → quant-ph_9508027（/ 换 _，跨文件系统安全）

一篇 paper 在三桶里的 key 是对齐的：

qatlas-pdf/2401/2401.00001.pdf
qatlas-md/2401/2401.00001.md
qatlas-images/2401/2401.00001/fig1.png
qatlas-images/2401/2401.00001/fig2.jpg

按 stem 索引就能一次找到一篇 paper 的所有资产。

Router 抽象（应用层 kind → 桶名翻译）¶

应用层不直接知道桶名——internal/objstore.Router 按 key 的首段 "kind" 分桶：

应用层 key	实际桶
`pdf/2401/2401.00001.pdf`	`qatlas-pdf/2401/2401.00001.pdf`
`markdown/2401/2401.00001.md`	`qatlas-md/2401/2401.00001.md`
`images/2401/2401.00001/fig1.png`	`qatlas-images/2401/2401.00001/fig1.png`

⚠️ 应用层 kind 名是 markdown，但桶名是 qatlas-md——不要在 mc / mirror 脚本里用 markdown 当桶名找不到。Router 这层翻译只在 Go 进程内做。

环境变量（每桶独立配，all-or-nothing 切换）：

QATLAS_S3_BUCKET_PDF → 通常 qatlas-pdf
QATLAS_S3_BUCKET_MD → 通常 qatlas-md
QATLAS_S3_BUCKET_IMAGES → 通常 qatlas-images
QATLAS_S3_BUCKET_OPENALEX_SNAPSHOT → qatlas-openalex

启动时如果检测到老的单桶 QATLAS_S3_BUCKET 还在 .env 里，server fail loud 拒绝启动，要求改成多桶（防止 stale .env 把所有对象 silently 灌进一个桶）。

ACL 与外发策略¶

桶	公网直读	字节外发 API	字节是否离开后端
`qatlas-pdf`	❌	❌（无 download endpoint）	❌
`qatlas-md`	❌	❌（无 download endpoint）	❌
`qatlas-images`	❌	❌（无 download endpoint）	❌
`qatlas-openalex`	❌	❌（仅内部 bootstrap / 增量 sync 用）	❌
`qatlas-raw`	❌（历史，已停写）	—	—

资产桶字节永不通过 API 外发——这是版权红线：arxiv PDF 字节版权归原作者， QuantumAtlas 只做 metadata + 引用图谱。v0.9.0 起公开 server 删除了所有 PDF / markdown 字节级 download endpoint；终端用户想拿 PDF 自己去 arxiv.org 拉。详见 license-and-attribution.md。

桶生命周期约束¶

资产桶之间的应用层约束（v0.7.0+ 必须满足）：

qatlas-pdf 是 truth-of-record —— papers sync 据其 list 重建 registry 的 pdf_path 状态
qatlas-md ⊆ qatlas-pdf（先有 PDF 才会跑 MinerU 出 md，反之不成立——有些 PDF 还没跑 MinerU）
qatlas-images ⊆ qatlas-md（一篇 paper 没 md 就不会有 images 目录，反之不一定——MinerU 没提图）
qatlas-openalex 跟其它桶无引用关系，独立增量同步

任一约束 break → 数据完整性问题，按 §6 对账文档的怀疑路径排查。

4. 反模式¶

只要不踩这三个反模式，对象存储和 registry 层完全是好邻居：

❌ 把 PDF 塞进数据库 blob 列¶

INSERT INTO papers (arxiv_id, pdf_bytes) VALUES ('...', '<2MB binary>');

关系库的存储 / buffer pool / 备份链路不是为 MB 级 blob 设计的——会让表膨胀、缓存失效、备份变慢。PDF 永远只通过 RustFS 引用，registry 里只存对象 key 与 sha256。

❌ 把关系数据编码到 JSON 塞回对象存储¶

把"这篇 paper 引用了哪些"当 JSON 写回 RustFS，查询时去 RustFS 拉所有 JSON 自己 join—— 退化成"对象存储当 KV 库用"，集合查询性能直接归零。所有集合查询只在 PostgreSQL。

❌ 派生库当 source of truth¶

如果 registry 里有的行在对象存储 / OpenAlex snapshot 找不到出处，就说明有人绕开 pipeline 直接写库。这会让"重建 registry"操作丢数据。所有写都必须可从 source 派生（详见 §5）。

5. 派生与重建（硬约束）¶

Source of truth = 2 类原始数据：

qatlas-openalex 桶 —— 从 OpenAlex S3 抓回的 filtered jsonl.gz（byte-faithful filter，不 mutate）。所有 paper metadata + 引用关系的 source。文件结构镜像 OpenAlex 官方： works/updated_date=YYYY-MM-DD/part_NNNN.jsonl.gz。
qatlas-pdf / qatlas-md / qatlas-images 三桶 —— PDF / MinerU markdown / 抽出的图片。文件 path 编码 arxiv_id 本身就标示了 has_X 状态。md 是纯 MinerU 输出，不挂任何 frontmatter / yaml header。

PostgreSQL registry 是从这 2 类 source 派生出的可查询 index。任何时候 registry 整库 rebuild，必须能从这 2 份 source 一比一重建出完整 catalog。

重建命令（first-class CLI）：

qatlasd papers sync --full --from-rustfs      # 从 RustFS 重建 papers / paper_assets / has_X 状态
qatlasd openalex bootstrap-pg                 # 从 qatlas-openalex 桶灌 openalex_works 语料

派生即可重建（derive-able）的强制要求¶

OpenAlex ingest pipeline 必须 byte-faithful：filter 不 mutate，输出的 jsonl byte-for-byte 等于 OpenAlex 原始 payload 的子集。这样未来想换 registry schema / 扩档 / 改 ingest 逻辑，重跑 sync 就行。
不允许 registry-only 字段：加新表 / 新列时，第一个问题永远是"它的 source 在哪？怎么从 source 重建？" 答不出来 = 该字段不能加。
MinerU lease 等短期租约是合法例外：运行时状态，过期即失效，不参与重建。

写路径约定¶

用户 / admin 不直接操作 RustFS 桶（应用独占，Nextcloud-style）。所有写都通过 qatlasd API（upload-pdf / upload-mineru / OpenAlex bootstrap 子命令）。RustFS notification webhook 不参与回路——应用独占下没有"外部写"需要 reconcile，靠周期 papers sync 兜底 Cypher 写失败的极端 case。

为什么这条原则比项目其它任何约束都重要：业务数据真正的权威在对象存储（本来就有的稳定层）。pb_data / PostgreSQL registry / 任何 derived backend 都是可替换、可重建的工具——让其它一切组件都成为可替换的快速失败 + 快速重建对象。

6. Catalog 健康度对账¶

对账 = §5 硬约束的运行时验证：桶里实际有什么 = source of truth，registry 行 = 派生 index，对账失败 → registry 偏离 source → 跑 papers sync 重建。

为什么对账（mirror "DONE" ≠ 完整）¶

S3 兼容存储的批量迁移（mc mirror / mc cp --recursive 等）在弱后端（HDD IOPS、低性能 CPU、并发抢占）上不保证零失败：

单个 prefix 内部分对象因 server 端 IO timeout 被 client 标 fail，但其它 obj 已成功 transfer
listing API 在大桶上可能超时翻页中断，client 报 success 但实际只 cover 部分 prefix
多次 retry / restart 后已 done 的对象会被 mc skip，但漏 cover 的对象不会自动补
papers sync 报告 image objects: 0 不一定是真的 0，可能是 list API 在某次返回 timeout 被 silently swallowed

结论：迁移命令 "DONE" 字样不等于完整。要靠独立对账确认。

三个 invariant（pdf / md / images）¶

迁移或增量完成后，对每一类资产都应满足：

count(target bucket recursive) >= count(source bucket recursive prefix)

不等号是 >= 不是 ==，因为 v0.7.0+ 生产环境持续在写新桶（mirror 期间和之后），target 含 source + v0.7.0+ 自然增量。

判定：

target >= source → mirror 至少覆盖了 source（OK）
target < source → mirror 漏对象，需要排查 fail 集合
target == source → 可能 OK 也可能 mirror 漏 + 生产没新写（取决于桶活跃度）

一个语义 invariant（md vs images）¶

布局约定：

qatlas-md/<yymm>/<stem>.md —— 每篇 paper 一个 markdown 文件（flat）
qatlas-images/<yymm>/<stem>/<sha>.jpg —— 每篇 paper 一个目录，目录里 N 张图（N ≥ 0）

每个 image 目录都对应一篇 paper（按 arxiv stem 索引），但反过来不成立：

有些 paper 没图（MinerU 没提取出图 / 这类论文本来就没图）→ md 文件存在但 images 下无目录
有些 paper 有图 → md 文件 + images 下有同 stem 目录

所以语义 invariant：

{ <yymm>/<stem> | qatlas-images/<yymm>/<stem>/ 存在 }
  ⊆
{ <yymm>/<stem> | qatlas-md/<yymm>/<stem>.md 存在 }

数量上 count(image paper-level dirs) <= count(md files)。

判定：

包含关系成立（image dirs ⊆ md stems）→ OK
反例（image 有但 md 无）→ 数据完整性破坏：上传 image 时漏写 md，或 mirror 漏 md，或 image 来自别处（不是同 paper 体系）
image / md 比率异常低（如 < 5%）→ MinerU 没跑或解析失败率高（需要核 MinerU pipeline），不一定是 mirror 问题

失败模式 → 怀疑路径¶

对账失败	怀疑顺序
`target pdf/md < source` 同前缀	1. mirror 漏（看 mirror log fail list） 2. source 还在被写（应该 v0.7.0+ 不允许）3. mc skip 误判某些 obj 已存在
`target images < source`	同上 + listing timeout（images 桶常因小文件多 prefix 深 + HDD 慢）
image dirs > md files	1. 上传 pipeline 漏写 md 2. md mirror 段漏 3. 历史脏数据（v0.7.0 之前的 stale image）
image/md 比率突然降到 < 5%	多半 MinerU pipeline 问题（image 提取失败），不是 mirror 锅
registry 行数 << 桶对象数	`papers sync` 没跑过 / 跑过但 list 失败被 silently swallowed（用 fail-loud 版本 rerun）/ registry 行本身缺失

何时跑对账¶

任何一次 batch migration / mirror 完成后（首次必跑）
上线新版 server 改了 upload pipeline / sync 逻辑后
怀疑某次 papers sync 报告异常（如 image objects: 0 但桶里明明有图）
定期（季度）作为 catalog 健康度巡检
papers sync 出 fail-loud error 后修完代码 → rerun + 对账

7. 容量估算¶

按 100 万 paper、平均 30 条 reference 估算：

层	存储	物理位置
Raw PDF	100w × 2 MB ≈ 2 TB	`qatlas-pdf` 桶，NAS RustFS
Markdown	100w × ~50 KB ≈ 50 GB	`qatlas-md` 桶
Images	100w × ~5 张 × 50 KB ≈ 250 GB	`qatlas-images` 桶
OpenAlex snapshot	全量约 300 GB（works/authors/sources/...）	`qatlas-openalex` 桶
PostgreSQL catalog	100w 行 × 数十列 + indexes ≈ 数百 MB 级	PostgreSQL
OpenAlex corpus	~2.87×10⁸ 行 jsonb + 索引 ≈ 1–2 TB	PostgreSQL（可与 catalog 同库）

raw 量再涨 10x（千万 paper、20 TB PDF），registry 还是只要数百 MB——关系库只存 "key + 状态 + 元数据"，存储成本基本不随 PDF 大小变化。这是这种分层架构能扛任意规模的根本原因。

8. 延伸阅读¶

部署侧细节（具体安装步骤 / 配置 / 运维）：

deployment/rustfs.md —— RustFS bucket / user / policy bootstrap， notify webhook + Fluent Bit 事件流，dual-endpoint presign 配置
deployment/backup-and-upgrade.md —— 数据的备份与灾难恢复（PostgreSQL dump、RustFS rsync、PocketBase pb_data 备份）

项目整体分层：

architecture.md —— 应用代码 / 对象存储 / PostgreSQL registry 的分层边界分工；PostgreSQL catalog 节解释了非登录态元数据、PDF/MD/DOI 状态和 MinerU claim 的存储
data-flow.md —— 一篇论文从 arXiv 进来到生成可运行代码的全链路图

API 与运维：

reference/upload-api.md —— upload handler 同步写、S3 conditional PUT、sha256 idempotency、bucket versioning 完整规范
deployment/migration-storage-layout.md —— 把 raw / data / pb_data 从仓库内搬到 XDG / 挂载点的实操步骤

多边缘部署：跨节点拓扑（节点列表、IP、共享什么、不共享什么、用户/PAT 影响、presign URL 同源等）属于运维细节，见内部仓库的多边缘部署文档。

参考链接¶

RustFS —— S3 兼容 Rust 对象存储
MinerU —— PDF 抽取
OpenAlex API —— paper metadata + 引用 resolve
CrossRef API —— DOI 解析