CM95/docs/Global_CM95_Pipeline_v1.md

Global CM95 Pipeline v1

目标

把 /mnt/sda1/CM93_2014.zip 的全球 CM93/CM95 数据稳定导入独立 PostGIS 数据库，并生成 coverage/sparse 的 z0-z12 基础 PBF。

稳定跑完优先于速度。流水线禁止依赖一个长寿命 Python 进程连续运行数天。

固定资源边界

• X220：2 物理核 / 4 逻辑 CPU。
• systemd service 固定 CPUAffinity=0 1，完整保留 CPU2/3 所在物理核给其他工作。
• Nice=10，I/O priority=7。
• 每个 segment 为独立 oneshot 进程，默认 4 小时 hard timeout。
• MemoryHigh=3 GiB，MemoryMax=4 GiB。
• PBF 最多 2 worker；单次最多 100 tile jobs。
• /mnt/sda1 空闲低于 30 GiB 时不领取新 segment。
• MemAvailable 低于 900 MiB 或 load1 高于 6 时进入 WAIT_RESOURCE，不破坏 checkpoint。

阶段

1. PRECHECK：ZIP CRC、SHA256、cell 数、代码 fingerprint。
2. EXTRACT：原子解压到 /mnt/sda1/cm95-global/source/CM93_2014。
3. INVENTORY：冻结 source manifest 与 64-shard 分配。
4. QUARANTINE_VALIDATE：验证已知坏源的 relative path / SHA256 / size；不改写原始 source。
5. SOURCE_SCAN_000..063：每 shard 独立 source-only parse audit；shard 分配完成后再过滤 quarantine，避免重排。
6. DB_INIT：创建独立 cm95_global_2014 + PostGIS schema。
7. POSTGIS_IMPORT_000..063：每 shard 一个全新 importer 进程，并使用同一 quarantine。
8. DB_AUDIT_000..063：每 shard 独立 source↔DB audit，并使用同一 quarantine。
9. FID_MANIFEST：检查 int32 FID 容量后生成全球 deterministic manifest。
10. COVERAGE_PLAN_Z00..Z12：每 zoom 独立生成 sparse tile ledger。
11. BASE_PBF_SEGMENT_xxxxxx：每次领取一小批 tile；结束后释放全部内存/连接。
12. FINAL_AUDIT：数据库 fingerprint、PBF ledger、实际文件数与冻结资源 hash。
13. PIPELINE_DONE：基础 PostGIS + sparse PBF 完成。

Bathymetry v5 为第二套独立 PBF，不与基础 PBF 放在同一长任务故障域中。

Source quarantine

Global source 保持原始字节不变；parser 继续严格 fail-closed。若极少数 CM93 cell 经二进制检查确认无法可靠恢复，可进入 config/global/cm95_global_2014_quarantine_v1.json。每条 quarantine 必须绑定 source relative path、SHA256、file size 与原因；运行时任一项不匹配立即停止，禁止按文件名模糊跳过。

Quarantine 在既有 shard 取模分配完成后过滤，因此不会改变其他 cell 的 shard 归属。SOURCE_SCAN、POSTGIS_IMPORT、DB_AUDIT 三阶段必须消费同一清单；最终 release/report 必须显式记录 quarantine 数量与字节数，不得把隔离源伪装成成功解析。

Checkpoint / Tag

运行状态位于 /mnt/sda1/cm95-global/state/。每段 PASS 写 tags/<SEGMENT>.PASS.json；失败尝试写 tags/<SEGMENT>.attemptN.FAIL.json。

Tag 固定记录开始/结束机器状态、elapsed、peak RSS、磁盘、swap、DB 大小和本段业务统计。

同一 segment 最多自动尝试 3 次。source/import/audit shard 连续失败 3 次后继续其他 shard，到阶段边界 fail-closed；PBF 单 tile 最多尝试 3 次。

代码冻结

PRECHECK 会对 parser、PostGIS/PBF/global pipeline、config、S-52 resource 与 schema 计算代码 fingerprint。后续任一 segment 发现 fingerprint 改变，自动进入 CODE_VERSION_CHANGED / PAUSED，禁止一套 release 静默混用两个算法版本。

调度

安装并启动：scripts/cm95_global_install_service.sh --enable。

查看：.venv/bin/cm95global status、systemctl status cm95-global.timer --no-pager、journalctl -u cm95-global.service。

暂停/恢复：.venv/bin/cm95global pause / .venv/bin/cm95global resume。

timer 只触发 run-next。每次只执行一个 segment，然后整个 Python 进程退出；下一次 timer 再启动全新进程。