Skip to content

Latest commit

 

History

History
1647 lines (1116 loc) · 122 KB

plan-20260902.md

File metadata and controls

1647 lines (1116 loc) · 122 KB

storage-only OCI Distribution 容器镜像仓库计划(2026-09-02)

路径说明(2026-09-20): 本文成稿时 docker-compose-storage-only.yml / docker-compose-storage-only.auth-none.yml / docker-compose.test.yml 位于仓库根;2026-09-20 起三者迁入 docker/ 目录(commit 1854cae)。文中根目录原路径为历史记录,不再逐一回改;实际使用时请替换为 docker/ 前缀路径。

改名註記(2026-09-17): 本文成稿與執行時,Cargo 包名/二進制名為舊名,lib 為舊名 _core;2026-09-17 起全倉統一改名為 Mega2(mega2 / mega2_core),本文中的命令、路徑、環境變量與服務名已同步更新,歷史提交記錄本身不變。

模板版本: v2;依据 plan-template.md,核对日期 2026-09-10。

文档职责

本文解决「mega2 在 storage-only 形态下无法承载 OCI Distribution 协议(容器镜像 push/pull)」的缺口。目标是交付:仅在 git.storage_only()(push_auth 显式配置)且 [oci].enabled=true 时挂载 /v2 协议面——最小 push/pull 端点集(/v2/、manifests GET/HEAD/PUT/DELETE、blobs GET/HEAD/DELETE、blobs/uploads 全状态机、tags/list),认证复用 git 面(匿名读由 git.anonymous_access、写由 git.push_auth/[[git.push_tokens]] 决定;docker 客户端走 Basic 静态凭据流),元数据落 DB(4 张新表)、字节落对象存储(新增 oci 命名空间)。review 形态不注册任何 /v2 路由(fail-closed)。

参照实现分析基于 /run/media/genedna/data/tmp/ 下的三个 pinned checkout:docker/distribution(规范基准)、rk8s project/distribution(Rust+axum 同构实现,主要移植蓝本,其 /v2/{*tail} 派发器是路由形态基准)、spegel(最小只读面)。kraken/harbor/quay/dragonfly 仅作概念参照(不 pin、不移植)。

本文只规划任务,不宣称实现完成。落地时每个任务都必须先刷新源码锚点(GC-01),再按任务卡验收。

适用范围

  • src/config/:新增 [oci] 段(enabled 布尔)、known_fields、storage-only 校验门。
  • src/callisto/ + src/jupiter/migration/:4 张新表(oci_manifest / oci_tag / oci_blob_ref / oci_upload)与实体、迁移注册。
  • src/jupiter/storage/ + src/jupiter/service/:OciDbStorage + OciService(DB 元数据 + 对象存储字节)。
  • src/orbit_api/object_storage.rs:ObjectNamespace::Oci 附录式新增。
  • src/ceres/oci/(新目录):OCI 错误封套、认证助手(Basic/Bearer 静态凭据流、registry ping 策略)、digest 工具、manifest 领域模型。
  • src/api/router/oci_router.rs(新,/v2/{*tail} 单 catch-all + 路径派发器)+ src/server/http_server.rs + src/api/api_doc.rs:路由、挂载、OpenAPI。
  • tests/integration_oci.rs(新):进程级黑盒 IT;scripts/oci_smoke_storage_only.sh(新):docker CLI live smoke。
  • 文档:docs/refactoring/oci.md(新)、docs/refactoring/orbit.md(命名空间清单)、docs/deploy-trunk.md、docs/refactoring/integration.md、docs/plan/README.md、plan-long.md 索引。

非目标

  • 不在 review 形态(无 git.push_auth)挂载 /v2;[oci].enabled=true 且非 storage-only 时启动校验直接拒绝(ADR-DR-01)。
  • 不实现 _catalog、referrers API、token 颁发服务(/v2/auth)、跨仓 GC、pull-through 代理/P2P(DEFER-DR-01..04);blob/manifest DELETE 只注册路由并返回 UNSUPPORTED(不实现删除语义)。
  • 不实现 独立 OCI token 体系;无 OCI 专用凭据配置(ADR-DR-02)。
  • 不支持 sha256 以外的 digest 算法(ADR-DR-05);不做 manifest list 平台重写(docker ≥1.13 不需要)。
  • 不修改 docker-compose-storage-only.yml(本计划 smoke 脚本独立运行,不新增 compose profile)。
  • 不触碰 Git smart protocol / LFS 既有实现语义(只新增挂载点,不改变 catch-all 行为)。

成功定义

  • storage-only + [oci].enabled=true:docker login(Basic 静态凭据)+ docker push registry:9000/<repo>:<tag> + docker pull(含多段 repo 名、分层并行拉取、chunked 上传、digest 校验)端到端可用;anonymous_access=true 时匿名 docker pull 无需凭据(含 registry ping 放行)。
  • 认证矩阵生效:push_auth=token 时未认证写 401(WWW-Authenticate: Basic 挑战 + UNAUTHORIZED 封套)、有效 token 不覆盖 repo → DENIED 403;push_auth=none 时全放行;读侧完全跟随 git.anonymous_access。
  • review 形态或 enabled=false:/v2/* 全部 404(不注册),OpenAPI 不含 /v2 路径。
  • 上传会话跨重启可续(DB 行含 offset/chunks + 分片对象持久);digest 校验失败保留会话;CAS 键只在 digest 验证通过后写入(两遍流式)。
  • 全部非延后任务卡 Lifecycle=done 且 Acceptance=complete;计划级 Codex 评审对本计划文档 PASS。

事实基线

所有行号和源码锚点必须在开工当天刷新(GC-01)。下列锚点核对日为 2026-09-10。

类别 当前事实 证据
工作树 VCS 本 checkout 使用 Libra(.libra);发布走 libra add / libra commit / libra push origin main(模板 GC-12/ER-07 的 git * 对本 checkout 以 AGENTS 为准) test -d .libra;libra status --short --branch
mega2 tip ca5a8667c5ee717dd979d7e81df755570682f14a(feat(smoke): register HTTP shallow clone depth=1 case, SO-11) libra log -1
包版本 0.8.22(Cargo.toml/Cargo.lock 干净)。版本面受并行 SO- 发布流影响持续前进*——本计划所有版本号均为示例,每卡以 ER-08 开工日 parity 预检为准 Cargo.toml:3
storage-only 定义 git.push_auth.is_some();ssh_receive_pack_enabled() 恒 false src/config/model.rs:984-994
storage-only 启动门 trunk 必须显式 push_auth;storage-only 必须显式 ssh_receive_pack=false src/config/validate.rs:637-656
未知字段拒绝 reject_unknown_fields + known_fields(path) 白名单 src/config/validate.rs:1056-1110、:1511
配置样例 config/config.toml(review 形态样例,含 [git] 注释段);config-storage-only.toml(storage-only 样例) config/config.toml:337-350;config/config-storage-only.toml
HTTP 路由组装 app():protocol_surface = storage_only || trunk;组装期先挂 /{*path} catch-all,随后对 router nest /info/lfs(静态前缀优先于 catch-all,语义上不被捕获);OCI 挂载将采用同一手法 src/server/http_server.rs:639-765(catch-all :712-717/726;/info/lfs nest :760-763)
storage-only router 集 storage_only_routers() 只读子集 src/api/api_router.rs:59-71
Git 认证复用点 lookup_push_token(常数时间);token_covers_repo 前缀匹配;auth_failed 发 Basic realm="Mega", Bearer realm="Mega" 挑战;Basic/Bearer 凭据解析 src/contract/git_protocol/mod.rs:133-159;src/contract/git_protocol/http.rs:99-165
LFS 认证模式 enforce_trunk_lfs_access:读跟 anonymous_access、写查 push token;LFS 侧已解析 Basic+Bearer src/api/router/lfs_router.rs:185-299
LFS 路由结构类比 lfs_routes()(Router)+ routers()(OpenApiRouter)双形态 src/api/router/lfs_router.rs:97-124
对象存储 trait MegaObjectStorage::{put_stream, get_stream, get_range_stream, exists, delete};无 list/rename/copy 原语;get_range_stream 契约 start >= size 非法 src/orbit_api/object_storage.rs:173-344
对象命名空间 ObjectNamespace::{Git, Lfs, Log, Artifact, Attachment},字符串形式是稳定契约 src/orbit_api/object_storage.rs:105-126
Storage 挂载模式 Storage 含 lfs_service: LfsService 等字段;test_storage 构造 + *::mock() src/jupiter/storage/mod.rs:149/202/582
迁移注册 sea-orm-migration migrations() 列表 src/jupiter/migration/mod.rs
OpenAPI 文档组装 storage_only_openapi_doc()/trunk_openapi_doc() 不接受配置参数(oci.enabled 门需要改签名) src/server/http_server.rs:768-785;测试 :1187-1233
测试基建 test_db_connection + apply_migrations(&db, true);进程级 IT 以 CARGO_BIN_EXE_mega2 黑盒 src/jupiter/tests.rs;tests/integration_git_ssh.rs:38-287(boot_storage_only_ssh:524)
D 组 .github/workflows/ 为空目录(无 workflow 文件) 2026-09-10 现场 ls
工作区前置 .env.test 存在;宿主机 docker CLI 29.7.2 可用(DR-13 live smoke 用) .env.test;docker --version
工作区脏文件 docs/deploy-trunk.md(M,他人改动)、docs/plan/plan-20260906.md(M,他人改动)、scripts/git_protocol_smoke_storage_only.sh(M,他人改动)、secrets/(??,既有未跟踪)、docs/plan/plan-20260902.md(??,本计划自身,预期)——不得并入本计划提交。本计划写集相交点:DR-14 触及 docs/deploy-trunk.md——开工时先核对脏改动内容,只追加本计划 OCI 段、不覆盖不并入无关改动(GC-12 精确提交);DR-13 新建独立脚本,不碰 git smoke 脚本 libra status --short --branch(2026-09-10)
外部参照 docker/distribution 5b354e6fda6126a188df7d3769bfdfb02d8d020b;rk8s c862eea340b63aef22435614793cc668aa77b926(project/distribution/);spegel a8d80fdd01639a2f247098a4cc6964ff0d030fc7 /run/media/genedna/data/tmp/{distribution,rk8s,spegel},核对 2026-09-10

当前缺口

ID 缺口 影响 证据 计划动作
GAP-DR-01 无 /v2 协议面:全部 OCI 请求落到 /{*path} catch-all → smart protocol 404 容器镜像无法 push/pull;storage-only 形态无镜像分发能力 http_server.rs:712-726 DR-11
GAP-DR-02 无 [oci] 配置段与 storage-only 门 无法声明启用/禁用;无 fail-closed 校验 config/model.rs:9-53;validate.rs:1511 DR-01
GAP-DR-03 ObjectNamespace 无 OCI 命名空间 镜像字节与 git/lfs 对象无法分离管理 orbit_api/object_storage.rs:105-126 DR-04
GAP-DR-04 无 OCI 元数据表(tag→digest、repo→blob、上传会话) tags/list、digest 解析、上传续传无事实源 src/callisto/ DR-02/DR-03
GAP-DR-05 无 OCI 错误封套与认证复用助手 docker 客户端无法解析错误/挑战,无法复用 push token src/common/errors/(CommonResult 形状不符 OCI) DR-05
GAP-DR-06 无进程级 IT / live smoke / 文档 协议行为无黑盒证据 tests/;scripts/ DR-12/DR-13/DR-14

与其它计划的关系

计划/文档 关系 本计划处理
plan-20260905.md / plan-20260909.md 前置:storage-only 形态与 LFS token 认证已交付 复用 push_auth/push_tokens/anonymous_access 与 lookup_push_token;不重做
plan-20260906.md 并行:storage-only Git 协议 smoke(SO-*,进行中) 不触碰其写集;DR-13 新建独立 OCI smoke 脚本(工作区中该计划文件与 git smoke 脚本为脏状态,不并入本计划提交)
docs/refactoring/protocol.md Git 协议事实源 不触碰;OCI 另立 docs/refactoring/oci.md(DR-14)
docs/refactoring/orbit.md 对象存储命名空间契约 DR-04 附录式追加 oci 命名空间;清单随 DR-14 同步
plan-long.md 无 PT 强制关联 DR-14 索引登记本计划
AGENTS.md / 任务卡发布规则 Libra 发布 遵守;本计划文档提交 Version increment=N/A

评审结论与修订记录

计划成稿前自审:

维度 结论 修订动作
合理性 storage-only 无用户系统、无 token 服务器,镜像分发只能走静态 token/匿名形态;参照实现证明最小面即可满足 docker 客户端 本计划承接
可行性 栈同构(axum + sea-orm + object_store 全齐);rk8s 已有 Rust 完整实现可参照;无新依赖 十五张 S–M 卡
任务卡粒度 配置 / 表 / DB 层 / 对象层 / 领域 / ping+manifest 写 / manifest 读 / blob / uploads 会话 / uploads 完成 / tags+挂载 / IT / smoke / 文档 / 收口分轴;AC 按独立谓词单条计数(R3 修正) 见粒度审计表
依赖与顺序 全串行(oci_router.rs 多卡共享、jupiter/storage/mod.rs 多卡共享);无环 DAG 见实施顺序
完整性 测(单元+进程 IT+live smoke)/文档/forward-only 迁移/回滚齐全 见各卡
安全性 不新增认证体系;写侧复用 push token;mount 要求源 pull 授权;CAS 键先验证后写入 ADR-DR-01/02/06
功能正确性 Basic 静态凭据流对 docker login 可执行且匿名 ping 可放行;/{*tail} 派发器支持多段 repo 名;complete 两遍流式(pass A 哈希 → pass B 落 CAS),CAS 键只在验证后写入 ADR-DR-02/06/08
接口兼容 /v2 是全新路径;review 形态零变化;OpenAPI builder 增参门控;range 契约与 trait 对齐(router 判 416) DR-11
数据流 上传字节不整块驻留内存;complete 两遍流式(2 读 + 1 写 O(size));分片键由 DB chunks 计数确定性寻址 ADR-DR-06;GC-10
性能 blob GET 用范围读;无全表扫描(tag/manifest 均按复合 pk 点查) 性能摘要
可靠性 会话跨重启可续;崩溃窗口均有定义(孤儿分片 / 部分 CAS 对象均无害且可重试覆写) DR-09/DR-10;故障恢复矩阵
可维护性 领域(ceres/oci)与 HTTP(api/router)分层,仿 LFS 双 router 形态 GC-DR-05

修订历史

日期 触发 变更内容 原卡 → 新卡 受影响的引用
2026-09-10 成稿 首版:DR-01..DR-11;ADR-DR-01..07;GAP-DR-01..06 N/A 全文
2026-09-10 Codex R1 FAIL ①认证改 Basic 静态凭据流;②路由改 /{*tail} 单 catch-all 派发器;③oci_upload 增 chunks 列;④DR-02 拆 migration/存储两卡,全卡重数 AC;⑤mount 补源 pull 授权;⑥OpenAPI builder 增参;⑦DAG 对齐;⑧NAME_INVALID 入枚举;⑨DELETE 注册返回 UNSUPPORTED;⑩no-release C/D 覆盖改继承收口卡;⑪baseline/prod-files/orbit.md 校正;⑫Review log 记 R1 DR-01..DR-11 → DR-01..DR-12 全文
2026-09-10 Codex R2 FAIL ①AC 按独立谓词单条重写:manifest 写/读拆卡;DR-02 收窄为纯 DDL;DR-03 校正 M 并登记 split-from;②registry ping 跟随 anonymous_access;③complete 改两遍流式(pass A 哈希 → pass B 落 CAS,删除 exists→skip);④range 契约对齐 trait(router 判 416、service 空流);⑤事实基线刷新(tip/版本/脏文件) DR-01..DR-12 → DR-01..DR-13 全文
2026-09-10 Codex R3 FAIL ①DR-02 含 schema 变更不得 scope S → 改 M;uploads 拆为「会话写(DR-09:init/PATCH/status)」与「完成/清理(DR-10:complete/mount/DELETE)」两卡,AC 全部单谓词重写;DR-06(ping+manifest PUT)AC 重数至 8 条单谓词;tags/挂载(DR-11)、IT(DR-12)、smoke(DR-13)、docs(DR-14)顺延;②DR-14 no-release 的 C/D 宿主改为具名收口卡 DR-15(release 类型);③事实基线刷新(tip 31a81e1f、版本 0.8.18、脏文件含 docs/deploy-trunk.md);④landing 计数按目录口径校正(DR-06=1、DR-12 prod-files=0 等) DR-01..DR-13 → DR-01..DR-15(原 DR-09 拆出 DR-10;新增 DR-15 收口卡) 全文(DAG、审计表、追溯、里程碑、风险、性能、故障矩阵)
2026-09-10 Codex R4 FAIL ①DR-05 ping 三态矩阵与 DR-12 多场景行仍超单谓词口径——本轮 DR-05 拆为 8 条单谓词(ping 行为归 DR-06 三条 AC + DR-05 VER 矩阵)、DR-12 拆为 8 条单谓词(docker SKIP 降 VER);②DR-12 AC 计数 6→8 校正;③事实基线刷新(版本 0.8.19;脏文件增 Cargo.toml/Cargo.lock——他人发布进行中,ER-01/ER-12 特化:DR-15 开工须等待);里程碑与 DR-15 示例版本号按 0.8.19 基重算 DR-05/DR-12 字段修订 粒度审计表、ER-01、里程碑、Review log
2026-09-10 Codex R5 FAIL ①DR-12 末条 AC(全协议走查)仍为多场景矩阵——本轮降为 7 条单谓词 AC,走查整体移入 VER(--test integration_oci 即为走查);②事实基线过期(tip 2163edf SO-08、版本面已干净)——本轮刷新并把手改为「开工时条件检查」;③DR-15 VER 按独立门口径重计为 4(三门属 ER-04 强制门不计入) DR-12/DR-15 字段修订 粒度审计表、事实基线、ER-01、Review log
2026-09-10 Codex R6 FAIL P1×2:①基线过期(tip 前进至 9e08621 SO-09、版本 0.8.20 已提交干净、脏文件仅 secrets/ 与本计划文件)——本轮刷新并把版本面声明为「受并行 SO-* 发布流影响、逐卡以 ER-08 parity 预检为准」,里程碑示例按 0.8.20 基重算为 0.8.21..34;②DR-15 VER 首行与强制门重复——本轮删除,VER=3/12 DR-15 字段修订 + 事实基线 粒度审计表、事实基线、ER-01、里程碑、Review log
2026-09-10 Codex R7 FAIL P0×1:DR-03/04/06/07/08/09/10/11 的 AC 仍按行计而非独立谓词(单个头、单列、单状态各计一条)——本轮全部协议卡 AC 重写为单谓词至 8/8(DR-02 8/8、DR-03 8/8、DR-04 8/8、DR-07 8/8、DR-08 8/8),细粒度断言(其余头/字节/清理细节/错误码矩阵)整体下沉 VER DR-02/03/04/06/07/08/09/10/11 字段修订 粒度审计表、各卡 Granularity、Review log
2026-09-10 Codex R8 FAIL P0×1:AC 仍含头/字节等保真细节且 VER 仍为捆绑矩阵——本轮 AC 收敛为纯行为谓词(状态码/错误码/行为结果),全部保真细节(头/字节/清理)下沉为逐测试函数的 VER 门(DR-03 VER=5、DR-04 VER=6、DR-05 VER=6、DR-06 AC=7/VER=8、DR-07 AC=6/VER=8、DR-08 AC=6/VER=7、DR-09/10/11 VER=8、DR-12 三组 IT 过滤门)。P1×1:版本面等待规则只覆盖 DR-15——本轮扩展为全部独立发布卡(DR-01..DR-13、DR-15)开工与发布窗口前均须 parity 预检;基线刷新(tip 804fac5 SO-10、版本 0.8.21 干净),里程碑示例按 0.8.21 基重算为 0.8.22..35 全卡 AC/VER 修订 + ER-01 + 事实基线 粒度审计表、各卡 Granularity、ER-01、里程碑、Review log
2026-09-10 Codex R9 FAIL P0×1:AC 残留字节保真(DR-04「两遍流式」、DR-10「字节一致」)与不可执行 VER(DR-01 命名测试、DR-02 单模块门)——本轮 DR-04 AC 改「pass B 写入 CAS 键」、DR-10 AC 改「blob GET → 200」,DR-01 VER 改真实过滤命令,DR-02 VER 拆为 5 个逐表/逐列测试函数门(VER=5/8)。P1×1:脏文件清单过期(docs/deploy-trunk.md 等再次变脏)——本轮刷新并写明「只追加不覆盖」处置 DR-02/DR-04/DR-10 字段修订 + 事实基线 粒度审计表、事实基线、ER-01、Review log
2026-09-10 Codex R10 FAIL P0×2:①命名测试过滤门可零命中通过(cargo 未匹配过滤器退出 0)——本轮新增 GC-DR-06(--exact + 输出断言)并对全部命名门生效;②DR-13 AC 仍为复合行——本轮拆为 7 条单谓词(AC=7/8)。P1×1:DR-14 VER 为复合散文——本轮改为逐条可执行命令(越界检查 / 链接存在性循环 / 人工核对证据登记) DR-13/DR-14 字段修订 + GC-DR-06 粒度审计表、全局工程约束、Review log
2026-09-10 Codex R11 FAIL P0×1:DR-05 的 digest 双选择与 4 mediaType 常量、DR-14 的存在性/完整性/pin/脏文件处置仍为捆绑谓词——本轮 DR-05 AC 收窄为 6 条(digest/mediaType 下沉 3 个命名测试函数门,VER=8/8),DR-14 AC 拆为 11 条单谓词(11/20)。P1×1:DR-14 VER 越界面与链接清单不完整——本轮越界检查扩至 src/config/Cargo/scripts/tests,链接循环覆盖全部 6 个 Deliverables DR-05/DR-14 字段修订 粒度审计表、Review log
2026-09-10 Codex R12 FAIL P0×2:①命名测试门缺 --exact——本轮全文批量补齐(DR-12 三组 IT 门);②DR-03 实体注册×4(mod.rs+prelude = 8 谓词)超限——本轮 AC 收窄为 4 条行为谓词(注册检查下沉 callisto 导出守卫,VER=6/8)。P1×1:DR-14 范围检查无法区分既有脏改动——本轮改为暂存区 allowlist 检查(libra add 仅加 Deliverables,A 区零越界) DR-03/DR-14 字段修订 + 全文 VER 命令 粒度审计表、全局工程约束 GC-DR-06、Review log
2026-09-10 Codex R13 FAIL P0×1:批量补 --exact 时 bash 展开 $1 导致 55 条命名门命令体丢失——本轮以逐行映射脚本重建全部 55 条命令(零空命令残留)。P1×1:DR-14 路径级暂存会把 docs/deploy-trunk.md 既有脏 hunk 一并纳入——本轮改为「物主先提交/复位(否则 blocked)+ 暂存区 allowlist」双重前提 55 条 VER 命令重建 + DR-14 AC/VER Review log、DR-14 字段
2026-09-10 Codex R14 FAIL P0×1:三处 AC 仍按行计——本轮 DR-01 拆字段/缺省为两条(AC=7/8);DR-13 拆「无服务」与「docker 不可用」两条并补无服务 SKIP VER(AC=8/8、VER=4/8);DR-15 拆 bump/lock/commit/push/远端 ref 为五条(AC=10/12) DR-01/DR-13/DR-15 字段修订 粒度审计表、Review log
2026-09-10 Codex R15 FAIL P0×2:①DR-15 仍含复合 AC(lock 双谓词、commit 双谓词、ref 双谓词 = 13 超限)——本轮拆至 12 条单谓词(AC=12/12);②GC-DR-06 与模块级全量门冲突——本轮把规则收窄为函数级过滤门(::tests::<fn>)必须 --exact,模块级门明确豁免。P1×1:DR-13 SKIP 验证为散文——本轮给出精确命令(PATH=/bin 去 docker、MEGA2_OCI_SMOKE_REGISTRY=http://127.0.0.1:1 端点不可达) DR-15/DR-13 字段修订 + GC-DR-06 粒度审计表、全局工程约束、Review log
2026-09-10 Codex R16 FAIL P1×2:①DR-13 docker 缺失路径 PATH=/bin 在本次 checkout 无效(/bin 是 /usr/bin 符号链接)——本轮改为 PATH=/nonexistent + 绝对路径 bash;②DR-15 远端 ref 验证为散文——本轮改为 libra rev-parse HEAD 与 libra ls-remote --heads origin main 的 test 比对命令 DR-13/DR-15 VER 修订 Review log
2026-09-10 Codex R17 FAIL P1×2:①DR-15 远端比对把裸 hash 与 ls-remote 全行输出比较必然失败——本轮改为 awk 提取首字段并断言恰一条 ref;②基线过期(SO 流前进至 ca5a866 SO-11、版本 0.8.22、脏文件快照更新)——本轮刷新,里程碑示例重算为 0.8.23..36 DR-15 VER + 事实基线 里程碑、Review log
2026-09-10 Codex R18 FAIL P1×1:DR-15 远端比对在命令替换内丢弃 awk 失败状态仍 fail-open——本轮改为先赋 remote_ref 变量再 && 链式 test 比对(awk 计数失败即短路) DR-15 VER 修订 Review log
2026-09-10 Codex R19 PASS 全部 P0/P1 关闭;P2×3 具名接受(作者 genedna) N/A Review log
2026-09-11 文档收口(对照代码) 勾选「兼容与文档收口」与「完成判据」;Review log CLOSE;索引已为已完成(96077b9) N/A 完成判据、兼容清单、Review log

已决议设计决策

实现时若需偏离本节,必须先修改计划并说明原因,不得在代码中静默改语义。

ADR-DR-01: /v2 双重门——显式 [oci].enabled + storage-only

  • Status: Accepted
  • Context: 需求「只在 storage-only 模式下执行」。storage_only() 是 push_auth.is_some() 的推导;仅凭推导无法显式声明意图,也无法 fail-closed 拒绝错误部署。
  • Decision: 新增 [oci] 段,仅一个字段 enabled(serde 缺省 false)。app() 挂载条件为 config.git.storage_only() && config.oci.enabled。校验:oci.enabled=true 且非 storage-only → 启动拒绝;storage-only 且 enabled 缺省 → 不挂载(非错误,日志提示)。
  • Alternatives considered: (1) 纯推导(storage-only 恒开)——拒绝:无法按实例关闭,违反最小暴露;(2) 独立 token——拒绝:与 git 面双轨。
  • Consequences: 部署者需在 config-storage-only.toml 显式加 [oci] enabled = true 才启用;/v2 默认 404。
  • Revisit when: 若 trunk 形态需要镜像分发(需重新评审认证与配额)。

ADR-DR-02: 静态 Basic 凭据流,复用 push token;registry ping 跟随匿名读策略

  • Status: Accepted
  • Context: docker 客户端对带 token 服务(realm/token URL)的 Bearer 流需要额外服务端组件;纯 Basic 挑战(WWW-Authenticate: Basic realm=...)docker 原生支持:docker login 先 GET /v2/ 验证凭据(200 = 有效、401 = 无效),此后所有请求带 Authorization: Basic base64(user:password)。storage-only 已有 push token 体系(lookup_push_token 常数时间比较);为 OCI 再造 token 服务器违反 GC-02。匿名 docker pull 前同样会 ping /v2/,因此 ping 必须跟随读策略。
  • Decision:
    • 凭据解析:Authorization: Bearer <token> 直取;Authorization: Basic 取 password 为 token(username 可为任意值,仅记日志),复用 git 面解析习惯(git_protocol/http.rs 既有实现或等价代码)。
    • 挑战:401 时发 WWW-Authenticate: Basic realm="mega2 registry", Bearer realm="mega2 registry"(与 git auth_failed 同风格)。
    • 读(GET/HEAD manifest/blob、tags/list、GET /v2/ ping):anonymous_access=true 且无凭据 → 放行;anonymous_access=false → 要求有效 push token;携带凭据但无效 → 401(含 ping,保证 docker login 失败可呈现)。
    • 写(POST/PATCH/PUT/DELETE):push_auth=token → lookup_push_token + token_covers_repo("/" + repo);token 有效但不覆盖 repo → DENIED(403);push_auth=none → 全放行。
  • Alternatives considered: 独立 token 服务器/Bearer realm——拒绝:新增组件与面;silly 式任意非空 Bearer——拒绝(无实际保护);ping 恒 401——拒绝(阻断匿名 pull,R2 修正)。
  • Consequences: docker login <host> -u <任意> -p <push token> 即完成认证;OCI 写权限粒度 = token.paths 前缀匹配(repo 当 /repo)。无 token 服务器、无 scope 协商。
  • Revisit when: 需要细粒度仓库配额/租户或标准 Bearer token 流时。

ADR-DR-03: 元数据 4 表 + 字节对象存储,无 link 文件

  • Status: Accepted
  • Context: docker/distribution 用存储驱动 link 文件表达 tag/manifest/blob 关系;S3 上 link 文件遍历昂贵且无事务。quay/harbor 证明 DB 元数据模型成熟。storage-only 形态本就有 Postgres(无内嵌 DB 模式)。
  • Decision: 4 表:oci_manifest(repo_name, digest, media_type, size, created_at)、oci_tag(repo_name, tag, digest, updated_at)(复合 pk)、oci_blob_ref(repo_name, digest, size, created_at)(repo→blob 成员关系,供 manifest 校验与未来 GC)、oci_upload(uuid pk, repo_name, offset, chunks, started_at, updated_at)。字节全部在对象存储 oci 命名空间。无 oci_repository 表——repo 存在性 = 有 manifest/tag/blob_ref 行(_catalog 非目标)。
  • Alternatives considered: link 文件布局——拒绝(S3 遍历/一致性差);内存会话表——拒绝(跨重启不可续)。
  • Consequences: manifest PUT 校验引用 blob 走 oci_blob_ref 点查;NAME_UNKNOWN 判定走 manifest 行存在性。
  • Revisit when: 引入 _catalog 或配额时考虑 oci_repository 表。

ADR-DR-04: 端点范围 = 最小 push/pull + tags/list;DELETE 注册但恒 UNSUPPORTED

  • Status: Accepted
  • Context: docker 客户端 push/pull 全流程只需:/v2/、manifest GET/HEAD/PUT、blob GET/HEAD、uploads 全状态机(含 mount、monolithic)、tags/list。
  • Decision: 实现上述端点。manifest/blob DELETE 注册路由但恒返回 UNSUPPORTED(405 封套,与 distribution 默认 delete.enabled=false 行为一致;不注册会导致裸 404/405 而非 OCI 封套)。_catalog、referrers 不注册。tags/list 支持 n/last 分页与 Link 头。
  • Alternatives considered: 完整 spec——拒绝:catalog/delete 与安全/GC 强耦合,超出本计划轴。
  • Consequences: 依赖 catalog 的 UI/工具不可用(DEFER-DR-01);docker/containerd/oras/crane 不受影响。
  • Revisit when: 需要 registry UI 或回收能力时。

ADR-DR-05: 仅 sha256;manifest 原样存回,不做平台重写

  • Status: Accepted
  • Context: docker 实际只发 sha256;4 种 manifest mediaType(Docker schema2 / manifest list v2 / OCI manifest / OCI index)需按原字节往返。
  • Decision: digest 解析仅接受 sha256:<hex64>,其余 DIGEST_INVALID。manifest PUT 按 mediaType 白名单校验后原样入对象存储(key manifests/sha256/<hex>),GET 原样返回存储 mediaType。by-tag PUT 的 digest 由服务端对 body 计算(manifest 自身无 digest 字段;仅 by-digest PUT 校验 URI digest 与计算值一致)。不重写 manifest list 平台(docker ≥1.13 发送 Accept 覆盖 list)。
  • Alternatives considered: 完整 OCI spec crate(oci-spec)——拒绝:新依赖,本仓约束禁止无谓增依赖;sha512——拒绝:无客户端使用。
  • Consequences: docker pull 旧客户端(<1.13)对多平台 list 可能取不到默认平台(极低风险,DEFER-DR-05)。
  • Revisit when: 需要 schema1 兼容或平台重写时。

ADR-DR-06: 上传会话 = DB 行(offset+chunks)+ 分片对象 keys;complete 两遍流式、CAS 键先验证后写入

  • Status: Accepted
  • Context: S3 无 append 语义;对象存储 trait 无 list/rename/copy 原语(src/orbit_api/object_storage.rs:173-344),分片寻址必须完全确定性;put_stream 落键必须在流开始前确定,而 CAS 键由 digest 决定、digest 只能在流式读完分片后得到——单遍写 CAS 键意味着未验证字节已污染内容寻址存储;distribution 的 HMAC _state 方案在有 DB 时冗余。
  • Decision:
    • POST 建 oci_upload 行(uuid,offset=0,chunks=0);每个 PATCH 写分片 uploads/<uuid>/<seq>(seq = 当前行 chunks 值),随后条件更新 UPDATE ... SET offset=?, chunks=chunks+1 WHERE offset=<写入前值>(冲突 → RANGE_INVALID,防并发 PATCH 交错);GET 状态读 DB offset。
    • PUT ?digest= 完成走两遍流式:pass A 按 seq 0..chunks-1 顺序流式读分片仅做 sha256(不落任何 CAS 键)→ 与请求 digest 比对,不符 → DIGEST_INVALID(会话/分片保留);pass B 再次流式读分片 → put_stream(blobs/sha256/<actual>)(键由已验证的 actual digest 决定)。两遍均常数内存;总成本 2 读 + 1 写 O(size)。
    • 成功 → 写 oci_blob_ref、按 seq 逐个删分片、删会话行;DELETE → 按 seq 逐个删分片 + 删行。跨重启可续(行与分片都持久)。
    • 崩溃窗口:PATCH 写分片成功但 DB 未更新 → 孤儿分片(不可达、无害,GC 延后 DEFER-DR-03);pass A 后崩溃 → 会话原样,重试无副作用;pass B 中途崩溃 → CAS 键存在部分字节但 oci_blob_ref 缺失(对读者不可见),重试 complete 覆写同键(内容寻址,覆写安全)。不使用 exists → skip 快捷路径。
  • Alternatives considered: HMAC _state URL token——拒绝(DB 已可校验会话归属);object_store multipart API——拒绝(LocalFileSystem 后端不支持);单遍流式写 CAS 键——拒绝(未验证字节污染 CAS,R2 修正);staging 键 + 整对象 copy——拒绝(trait 无 copy 原语,且成本同为 2 读 1 写)。
  • Consequences: complete 成本固定 2 读 + 1 写 O(size);对 >1GiB 层可接受(见性能摘要)。
  • Revisit when: S3 multipart/copy 可用且需省一趟读时。

ADR-DR-07: oci 命名空间键布局

  • Status: Accepted
  • Context: 需与既有命名空间(git/lfs/...)互不干扰且可预测。
  • Decision: 全部键以 namespace oci 前缀:
    • blobs/sha256/<hex>(CAS blob)
    • manifests/sha256/<hex>(原始 manifest JSON bytes)
    • uploads/<uuid>/<seq>(上传分片,seq 从 0 递增十进制,见 ADR-DR-06) ObjectKey 校验与 default_sharding() 沿用既有逻辑。
  • Alternatives considered: distribution 三层 shard 路径——拒绝:本仓 default_sharding 已提供 sharding。
  • Consequences: 键与 digest 一一对应;GC 时按前缀枚举即可。
  • Revisit when: 引入多算法 digest。

ADR-DR-08: /v2 路由 = 单 /{*tail} catch-all + 路径派发器

  • Status: Accepted
  • Context: OCI repo 名含 /(team/image),axum 的 {name} 单段参数无法匹配;rk8s 的 create_v2_router + dispatch_handler 用 /{*tail} 自解析(api/v2.rs:20/55);mega2 git 协议本就是 catch-all 自解析(parse_git_protocol_path)。
  • Decision: /v2 下注册单条 /{*tail} catch-all(base /v2/ 用同路由空 tail 处理),handler 内自实现路径解析:按后缀分派 blobs/uploads/<uuid> → blobs/<digest> → manifests/<reference> → tags/list,name = 剩余前缀段(校验 name 正则,段内禁 ..)。每个子 handler 返回 OciError 封套;未知形状 → NAME_INVALID/BLOB_UPLOAD_UNKNOWN 等对应码。
  • Alternatives considered: nest("/v2", Router::new().route("/{*name}/manifests/{ref}", ...))——axum 0.8 {*name} 中间段捕获不支持多段+后缀组合的确定性分派(已知限制),且 * 通配只能出现在末尾;拒绝。
  • Consequences: OpenAPI 无法自动生成细粒度路径(本计划以路径级文档 + 运行时聚合说明,见 DR-11);所有 OCI 请求走同一 handler 入口(与 git 协议一致)。
  • Revisit when: axum 支持中段通配或迁移到专用 registry 服务时。

全局工程约束

遵守模板 GC-01..GC-12;本 checkout 发布命令以 AGENTS.md 的 Libra 为准。本计划附加:

  • GC-DR-01: /v2 只允许在 storage_only() && oci.enabled 时挂载;review 形态任何提交不得出现 /v2 路由。
  • GC-DR-02: OCI 认证不得弱于 git 面:写侧必须经过 apply_push_auth_gate 等价语义(token 覆盖检查 / none 显式放行);读侧(含 ping)必须跟随 anonymous_access;mount 必须同时要求目标写授权与源读授权。
  • GC-DR-03: OCI 响应一律走 OciError 封套({"errors":[{code,message,...}]}),禁止复用 ApiError/CommonResult(JSON 形状不符 docker 客户端解析)。
  • GC-DR-04: 上传/下载字节流式处理(put_stream/get_range_stream),禁止把整层读入内存(GC-10)。
  • GC-DR-05: 不新增 crate 级 #[allow(...)];生产路径不新增裸 unwrap/expect。
  • GC-DR-06 命名测试门防幽灵: 本计划所有函数级命名测试过滤门(cargo test ... '<mod>::tests::<fn>')一律加 --exact,并以其输出出现目标测试名且 1 passed; 0 failed 为判定依据;cargo 对未匹配过滤器返回 0 属幽灵验收,判 FAIL。模块级全量门(--lib '<mod>' -- --nocapture)不是函数级过滤,不加 --exact,其覆盖以全量输出佐证。带多个测试名的过滤(前缀过滤除外)按多个独立门计数。

执行检查必备需求(强制)

全文遵守 plan-template.md 的 ER-01..ER-12。特化:

  • VCS: libra status / libra add <paths> / libra commit -m / libra push origin main;禁止 --force。模板中的 git * 替换为上述 Libra 命令。
  • ER-04 D 组: .github/workflows/ 为空(2026-09-10)。所有卡 D 组 N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中);Acceptance 在 C 覆盖后可直接 complete。
  • ER-01: 工作区核对日有 4 个无关脏文件/目录(见事实基线)。处置规则:docs/deploy-trunk.md(DR-14 写集相交)——开工先核对脏改动内容,只追加本卡 OCI 段,不覆盖不并入无关改动;其余脏文件任何卡不触碰;secrets/ 不得纳入提交。版本面(Cargo.toml/Cargo.lock)受并行 SO- 发布流影响持续前进*:**每一张独立发布的卡(DR-01..DR-13、DR-15)**开工与进入发布窗口前都必须先 libra status 确认版本面无他人未提交改动;若存在,等待其发布后重读当前版本并做 parity 预检(ER-08),bump 从该干净状态派生(ER-12 串行发布)。任何卡提交前 libra add 只加本卡写集路径(GC-12)。
  • ER-08: 实现卡按各卡 Version increment(全部 patch);本计划文档成稿提交不 bump。

实施顺序

  • DR-01 -> DR-02
  • DR-02 -> DR-03
  • DR-03 -> DR-04
  • DR-04 -> DR-06
  • DR-05 -> DR-06
  • DR-06 -> DR-07
  • DR-07 -> DR-08
  • DR-08 -> DR-09
  • DR-09 -> DR-10
  • DR-10 -> DR-11
  • DR-01 -> DR-11
  • DR-11 -> DR-12
  • DR-11 -> DR-13
  • DR-12 -> DR-14
  • DR-13 -> DR-14
  • DR-14 -> DR-15

依赖登记表

ID direction 类型 对象 Owner 产物与可用性判据 证据 超时与失败策略
DEP-DR-01 incoming 外部参照 docker/distribution 5b354e6f、rk8s c862eea3(project/distribution/)、spegel a8d80fdd 只读参照(本计划) 本地 checkout 可读;规范语义(errcode 状态码表、uploads 状态机)以 distribution 为准,Rust 结构(含 /v2/{*tail} 派发器)参照 rk8s /run/media/genedna/data/tmp/{distribution,rk8s,spegel}(2026-09-10 核对) 缺失则协议语义以 OCI Distribution Spec v1.1 文本为准,不得凭空造端点
DEP-DR-02 incoming 外部服务 宿主机 docker CLI/daemon(仅 DR-13 live smoke) 本计划 DR-13 docker --version ≥ 27 且 daemon 可达 docker --version(29.7.2,2026-09-10) 不可用 → smoke 用例 SKIP(脚本显式原因,退出码 0),不得判 FAIL

发布分组与并发窗口

ID 成员 唯一发布点 窗口规则 失败回滚顺序 理由
N/A — — 默认每卡独立发布(G-07) — 写集顺序依赖已用 DAG 表达,无需家族

并发声明: 实现阶段全串行(G-10:src/api/router/oci_router.rs(DR-06/07/08/09/10/11)、src/jupiter/storage/mod.rs(DR-03/04)、docs/refactoring/integration.md(DR-12/14)相交)。

发布者: 执行本计划的单一 Agent(ER-12)。

发布窗口顺序: DR-01 → DR-02 → DR-03 → DR-04 → DR-05 → DR-06 → DR-07 → DR-08 → DR-09 → DR-10 → DR-11 → DR-12 → DR-13 → DR-14(no-release,仅提交不 bump)→ DR-15(收口 bump)。

Phase 0: 基线冻结

目标: 计划 Codex 评审 PASS;本计划文档 + docs/plan/README.md 索引行落库。

进入条件: 无(计划文档工作)。

退出条件: Review log 最终行 PASS;libra tip 含 docs/plan/plan-20260902.md。

Phase 1: 配置、表与存储层

目标: DR-01(配置门)+ DR-02(4 表迁移)+ DR-03(实体与 OciDbStorage)+ DR-04(命名空间 + OciService 对象层)。

进入条件: Phase 0 退出。

退出条件: [oci] 校验生效;apply_migrations 后 4 表存在;oci 命名空间 roundtrip 测试绿。

Phase 2: 领域与协议端点

目标: DR-05(封套/认证/模型)+ DR-06(ping+manifest 写)+ DR-07(manifest 读)+ DR-08(blob)+ DR-09(uploads 会话)+ DR-10(uploads 完成)+ DR-11(tags+挂载+OpenAPI)。

进入条件: Phase 1 四卡 locally-accepted 且可发布。

退出条件: storage-only + enabled 下 /v2 全端点可用;review 形态 OpenAPI 无 /v2。

Phase 3: 黑盒验证

目标: DR-12(进程 IT)+ DR-13(docker live smoke)。

进入条件: DR-11 发布。

退出条件: tests/integration_oci 全绿;smoke 脚本在 docker daemon 可用环境下 0 failed。

Phase 4: 文档与收口

目标: DR-14(文档)+ DR-15(计划收口 release)。

进入条件: DR-12、DR-13 发布。

退出条件: 文档与索引一致;DR-15 三门在含 DR-14 最终变更的树上全绿并推送。

任务卡

任务卡粒度规则(G-*)

N/A(原因:全文逐字遵守 plan-template.md 的 G-01..G-11 与推荐拆分/反模式速查;不在本文件复制以免与模板漂移。本计划以各卡 Granularity 行与「任务卡粒度审计表」为机器可核对摘要。)

Verification 判定口径

N/A(原因:逐字继承 plan-template.md「Verification 判定口径」,含零命中 rg 退出码模板。本卡 Verification 只登记本卡特有命令。补充(GC-DR-06):本计划所有命名测试过滤门一律加 --exact 并以输出出现目标测试名且 1 passed; 0 failed 为判定依据,未匹配过滤器时 cargo 退出 0 属幽灵验收。)

字段全局默认与例外

  • Release boundary 默认: independent
  • Task type 默认: implementation
  • Rollback mode 默认: revert
  • Migration and rollback 默认: N/A
  • Security and privacy 默认: 继承 GC-07、GC-DR-01..02
  • Performance budget 默认: 继承 GC-10、GC-DR-04
  • Docs and compatibility impact 默认: 按 GC-05 同步触及的 docs 与 config 注释

默认覆盖:

任务 偏离的字段 取值与理由
DR-02 Task type / Rollback mode / Migration migration / forward-only / 新建 4 表(down 空实现,无运行期 down 入口)
DR-14 Task type / Release boundary / Version increment / C/D coverage from docs / no-release / N/A / 继承 DR-15(计划收口 release 卡)
DR-15 Task type release:计划收口点,不引入新行为,bump + 三门 + 推送

规则 waiver: 无(无 EX-*)。

任务卡粒度审计表

任务 type axis recovery complete self-contained AC VER landing / prod-files scope deps writeset release split-from exception
DR-01 implementation [oci] 配置段与 storage-only 门 revert 删除配置段 yes yes 7/8 4/8 2/4 M none 序列化于 DR-11 independent N/A N/A
DR-02 migration OCI 元数据 4 表建表迁移 forward-only 前滚 yes yes 8/8 5/8 1/2 M DR-01 序列化于 DR-03 independent N/A N/A
DR-03 implementation OCI 实体与 OciDbStorage 挂载 revert 删除存储层 yes yes 4/8 6/8 2/8 M DR-02 序列化于 DR-02 independent R1 版 DR-02(成稿拆分) N/A
DR-04 implementation ObjectNamespace::Oci + OciService 对象层 revert 删除服务层 yes yes 8/8 6/8 3/4 M DR-03 序列化于 DR-03 independent N/A N/A
DR-05 implementation OCI 封套/认证/领域模型 revert 删除模块 yes yes 6/8 8/8 2/6 M none 序列化于 DR-06 independent N/A N/A
DR-06 implementation /v2/ base ping + manifest 写 revert 删除路由 yes yes 7/8 8/8 1/2 M DR-04,DR-05 序列化于 DR-05 independent R2 版 DR-06 拆出 DR-07(读轴) N/A
DR-07 implementation manifest 读(GET/HEAD/DELETE) revert 删除路由 yes yes 6/8 8/8 1/1 M DR-06 序列化于 DR-06 independent 自 R2 版 DR-06 读轴拆出 N/A
DR-08 implementation blob GET/HEAD/DELETE + Range revert 删除路由 yes yes 6/8 7/8 1/1 M DR-07 序列化于 DR-07 independent N/A N/A
DR-09 implementation uploads 会话(init/PATCH/status) revert 删除状态机 yes yes 8/8 8/8 2/2 M DR-08 序列化于 DR-08 independent R2 版 DR-09 拆出 DR-10(完成轴) N/A
DR-10 implementation uploads 完成(complete/mount/DELETE) revert 删除状态机 yes yes 8/8 8/8 2/2 M DR-09 序列化于 DR-11 independent 自 R2 版 DR-09 完成轴拆出 N/A
DR-11 implementation tags/list + /v2 挂载 + OpenAPI revert 撤销挂载 yes yes 8/8 8/8 3/3 M DR-01,DR-10 序列化于 DR-12 independent N/A N/A
DR-12 implementation 进程级 IT tests/integration_oci revert 删除 IT yes yes 7/8 3/8 2/0 S DR-11 序列化于 DR-14 independent N/A N/A
DR-13 implementation docker CLI live smoke 脚本 revert 删除脚本 yes yes 8/8 4/8 1/1 S DR-11,DEP-DR-02 no-overlap independent N/A N/A
DR-14 docs 文档收口 revert 文档 yes yes 11/20 3/20 0/0 M DR-12,DR-13 no-overlap no-release N/A N/A
DR-15 release 计划收口(bump + 三门 + 推送) revert 收口提交 yes yes 12/12 3/12 0/0 S DR-14 no-overlap independent N/A N/A

Task DR-01: 新增 [oci] 配置段与 storage-only 校验门

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 按 ADR-DR-01 新增 OciConfig { enabled: bool }(serde 缺省 false),Config 挂 #[serde(default)] oci 字段;known_fields 增 oci/enabled;validate_trunk_config_surface(或等价校验函数)增门:oci.enabled=true 且 !git.storage_only() → 启动拒绝(错误信息提及 [oci] 与 git.push_auth);config/config.toml 增注释 [oci] 样例(默认注释掉);config/config-storage-only.toml 增 [oci] enabled = true 样例。

Out of scope:

  • 路由挂载与 OpenAPI(由 DR-11 承接)
  • 任何表/对象存储改动(DR-02/03/04)
  • 部署长文(DR-14);本卡只改两个样例 toml

Current evidence:

事实 证据
根配置含 [oci] src/config/model.rs OciConfig + Config.oci
未知字段白名单 src/config/validate.rs known_fields("oci")
storage-only 校验入口 src/config/validate.rs oci.enabled && !storage_only 门
review 样例配置 config/config.toml 注释 [oci]
storage-only 样例配置 config/config-storage-only.toml [oci] enabled = true

Acceptance criteria:

  • Config 含 pub oci: OciConfig 字段
  • OciConfig.enabled serde 缺省 false
  • reject_unknown_fields 接受 [oci] enabled = true
  • review 形态 + enabled=true 经 config validate 非零退出
  • storage-only + enabled=true 经 config validate 退出 0
  • config/config.toml 含注释掉的 [oci] 样例
  • config/config-storage-only.toml 含 [oci] enabled = true

Verification:

  • source .env.test && cargo test -p mega2 --lib 'config::' -- --nocapture
  • (new) cargo test -p mega2 --lib 'config::tests::oci_enabled_requires_storage_only' -- --exact
  • cargo run -p mega2 -- --config config/config.toml config validate 退出 0(相对已提交样例)
  • 守卫(模板):rg -n 'OciConfig' src/config/model.rs 有命中且仅限本卡预期落点(allowlist 比对)

Dependencies: 无

Deliverables: N/A

Implementation write set: src/config/model.rs;src/config/validate.rs;src/config/tests.rs;src/config/mod.rs(Default 构造补 oci);src/config/testing.rs(TestConfigBuilder 补 oci);config/config.toml(注释段);config/config-storage-only.toml

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 公开配置新增(缺省关闭,向后兼容);长文 DR-14

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: 未知字段 fail-closed 保持;enabled 缺省 false = 最小暴露

Performance budget: N/A

Estimated scope: M(landing=2;prod-files=4)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=[oci] 配置段与 storage-only 门; recovery=revert 删除配置段; complete=yes; self-contained=yes; AC=7/8; VER=4/8; landing=2; prod-files=4; scope=M; deps=none; writeset=序列化于 DR-11; release=independent; split-from=N/A; exception=N/A

Task DR-02: OCI 元数据 4 表建表迁移

Task type: migration

Lifecycle / Acceptance: done / complete

Description: 按 ADR-DR-03 新增建表迁移 m20260902_000100_add_oci_tables:oci_manifest(复合 pk repo_name+digest,media_type、size、created_at)、oci_tag(复合 pk repo_name+tag,digest、updated_at)、oci_blob_ref(复合 pk repo_name+digest,size、created_at)、oci_upload(pk uuid,repo_name、offset、chunks、started_at、updated_at);migrations() 末尾登记;down 空实现(本仓无运行期 down 入口)。本卡只做 DDL,不写任何查询/实体/存储层。

Out of scope:

  • sea-orm 实体文件与 OciDbStorage(DR-03 承接)
  • 对象存储/HTTP(DR-04+)
  • 无枚举类型(oci_upload 只有「存在」一种态,删除即完成/取消)

Current evidence:

事实 证据
迁移注册列表 src/jupiter/migration/mod.rs migrations() 末尾
迁移实现 src/jupiter/migration/m20260902_000100_add_oci_tables.rs
信息架构断言 同文件 #[cfg(test)] mod tests

Acceptance criteria:

  • m20260902_000100_add_oci_tables 登记于 migrations() 末尾
  • oci_manifest 表存在
  • oci_tag 表存在
  • oci_blob_ref 表存在
  • oci_upload 表存在
  • oci_upload 含 chunks 列
  • down 为空实现
  • 本卡 Rollback mode 声明 forward-only

Verification:

  • (new) cargo test -p mega2 --lib 'jupiter::migration::m20260902_000100_add_oci_tables::tests::oci_manifest_table_exists' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::migration::m20260902_000100_add_oci_tables::tests::oci_tag_table_exists' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::migration::m20260902_000100_add_oci_tables::tests::oci_blob_ref_table_exists' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::migration::m20260902_000100_add_oci_tables::tests::oci_upload_table_exists' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::migration::m20260902_000100_add_oci_tables::tests::oci_upload_has_chunks_column' -- --exact

Dependencies: DR-01

Deliverables: N/A

Implementation write set: src/jupiter/migration/m20260902_000100_add_oci_tables.rs(新);src/jupiter/migration/mod.rs;src/jupiter/migration/m20260815_000100_merge_queue_requester.rs(UN-18 前缀 helper:按名定位 MW-05 drop,允许其后追加 DR-02 等迁移)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 内部 schema;docs/refactoring/integration.md 不需单列(随 DR-12)

Rollback mode: forward-only

Migration and rollback: down 空实现(本仓无运行期 migrate down 入口);恢复 = 前滚新迁移 DROP 四表。数据不变量:四表为全新,无存量数据。

Security and privacy: N/A

Performance budget: N/A(一次性 DDL)

Estimated scope: M(landing=1;prod-files=2;schema 变更不适用 S)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=migration; axis=OCI 元数据 4 表建表迁移; recovery=forward-only 前滚; complete=yes; self-contained=yes; AC=8/8; VER=5/8; landing=1; prod-files=2; scope=M; deps=DR-01; writeset=序列化于 DR-03; release=independent; split-from=N/A; exception=N/A

Task DR-03: OCI 实体与 OciDbStorage(挂载到 Storage)

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 手写 4 个 sea-orm 实体文件(对应 DR-02 表),注册进 src/callisto/mod.rs 与 prelude.rs;新增 src/jupiter/storage/oci_db_storage.rs OciDbStorage:tag(upsert/read/list 前缀分页)、manifest(put/read)、blob_ref(put/read/exists)、upload(insert/get/update offset+chunks/delete),一个 #[cfg(test)] mod tests 覆盖四类 roundtrip 与复合 pk 幂等;Storage 挂 oci_db_storage 字段(构造 + test_storage/mock 同步)。

Out of scope:

  • DDL(DR-02 已交付,本卡只消费)
  • OciService 对象存储编排(DR-04)
  • HTTP 端点(DR-06+)

Current evidence:

事实 证据
实体文件 src/callisto/oci_{manifest,tag,blob_ref,upload}.rs
实体注册 src/callisto/mod.rs、prelude.rs
OciDbStorage src/jupiter/storage/oci_db_storage.rs
Storage 挂载 src/jupiter/storage/mod.rs AppService + accessor

Acceptance criteria:

  • tag 可写入并读回(upsert/read roundtrip)
  • manifest 可写入并读回(put/read roundtrip)
  • upload 会话 offset/chunks 可更新并读回(update roundtrip)
  • Storage 含 oci_db_storage 字段

Verification:

  • (new) cargo test -p mega2 --lib 'jupiter::storage::oci_db_storage::tests::tag_upsert_read_roundtrip' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::storage::oci_db_storage::tests::manifest_put_read_roundtrip' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::storage::oci_db_storage::tests::blob_ref_put_read_exists_roundtrip' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::storage::oci_db_storage::tests::upload_update_roundtrip' -- --exact
  • source .env.test && cargo test -p mega2 --lib 'jupiter::' -- --nocapture(幂等 upsert、tag 前缀 list、test_storage/mock 构造回归)
  • callisto 导出守卫(模板退出码口径):rg -n 'oci_manifest|oci_tag|oci_blob_ref|oci_upload' src/callisto/mod.rs src/callisto/prelude.rs 两文件各命中 4 个实体注册(allowlist 比对)

Dependencies: DR-02(消费其迁移产物)

Deliverables: N/A

Implementation write set: src/callisto/oci_manifest.rs、src/callisto/oci_tag.rs、src/callisto/oci_blob_ref.rs、src/callisto/oci_upload.rs(均新);src/callisto/mod.rs;src/callisto/prelude.rs;src/jupiter/storage/oci_db_storage.rs(新);src/jupiter/storage/mod.rs;src/jupiter/tests.rs

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 内部模块;无用户面

Rollback mode: revert

Migration and rollback: N/A(表由 DR-02 保留;revert 后空表无害)

Security and privacy: N/A

Performance budget: 全部按复合 pk 点查;tags/list 按 (repo_name, tag) 前缀范围扫描(分页 n 上限由 DR-11 钳制)

Estimated scope: M(landing=2;prod-files=8)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=OCI 实体与 OciDbStorage 挂载; recovery=revert 删除存储层; complete=yes; self-contained=yes; AC=4/8; VER=6/8; landing=2; prod-files=8; scope=M; deps=DR-02; writeset=序列化于 DR-02; release=independent; split-from=R1 版 DR-02(成稿拆分); exception=N/A

Task DR-04: ObjectNamespace::Oci 与 OciService 对象存储层

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 按 ADR-DR-07 附录式新增 ObjectNamespace::Oci(字符串形式 "oci",沿用既有 validate/默认 sharding);新增 src/jupiter/service/oci_service.rs OciService(组合 OciDbStorage + MegaObjectStorageWrapper):put_blob/get_blob/get_blob_range/blob_exists/delete_blob(blobs/sha256/<hex>)、put_manifest/get_manifest(manifests/sha256/<hex>)、put_chunk/get_chunk_stream/delete_chunks(uuid, count)(uploads/<uuid>/<seq>,seq 0..count-1 确定性遍历)、finalize_blob(uuid, chunks, expected_digest)(ADR-DR-06 两遍流式:pass A 哈希校验 → pass B 落 CAS,常数内存);jupiter/service/mod.rs 注册;Storage 挂 oci_service 字段(构造 + OciService::mock() + test_storage 同步)。

Out of scope:

  • 上传会话业务状态机(offset/chunks 编排、条件更新)(DR-09/DR-10 承接;本卡只提供原语)
  • HTTP 端点(DR-06+)
  • manifest 内容校验(DR-05/06)

Current evidence:

事实 证据
ObjectNamespace::Oci src/orbit_api/object_storage.rs
OciService src/jupiter/service/oci_service.rs
Storage 挂载 src/jupiter/storage/mod.rs

Acceptance criteria:

  • ObjectNamespace::Oci 序列化为 "oci"
  • blob 键布局 = blobs/sha256/<hex>
  • manifest 键布局 = manifests/sha256/<hex>
  • chunk 键布局 = uploads/<uuid>/<seq>
  • finalize_blob pass A 校验失败时不写 CAS 键
  • finalize_blob 校验通过后写入 CAS 键(pass B)
  • Storage.oci_service 在 build 路径构造
  • get_blob_range 对 start >= size 返回空流

Verification:

  • source .env.test && cargo test -p mega2 --lib 'orbit_api::object_storage' -- --nocapture
  • (new) cargo test -p mega2 --lib 'jupiter::service::oci_service::tests::blob_roundtrip' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::service::oci_service::tests::range_boundary' -- --exact
  • (new) cargo test -p mega2 --lib 'jupiter::service::oci_service::tests::finalize_multipart_sha256' -- --exact(两遍流式、常数内存经代码审查确认)
  • (new) cargo test -p mega2 --lib 'jupiter::service::oci_service::tests::finalize_pass_a_rejects' -- --exact
  • source .env.test && cargo test -p mega2 --lib 'jupiter::' -- --nocapture(OciService::mock() 与 test_storage 构造)

Dependencies: DR-03(消费 OciDbStorage 类型)

Deliverables: N/A

Implementation write set: src/orbit_api/object_storage.rs;src/jupiter/service/oci_service.rs(新);src/jupiter/service/mod.rs;src/jupiter/storage/mod.rs;src/jupiter/tests.rs

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 命名空间契约追加;docs/refactoring/orbit.md 命名空间清单随 DR-14 同步

Rollback mode: revert

Migration and rollback: N/A(无 schema;表由 DR-02 建立,revert 不删表)

Security and privacy: 键路径由 ObjectKey::validate 兜底(digest/uuid/seq 均为白名单字符集)

Performance budget: finalize_blob 2 读 + 1 写 O(size)、常数内存;blob GET 走 get_range_stream(范围读,不整读)

Estimated scope: M(landing=3;prod-files=4)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=ObjectNamespace::Oci + OciService 对象层; recovery=revert 删除服务层; complete=yes; self-contained=yes; AC=8/8; VER=6/8; landing=3; prod-files=4; scope=M; deps=DR-03; writeset=序列化于 DR-03; release=independent; split-from=N/A; exception=N/A

Task DR-05: OCI 错误封套、认证助手与领域模型(src/ceres/oci/)

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 新建 src/ceres/oci/(ceres/mod.rs 注册):error.rs——OciError 枚举(NAME_UNKNOWN/NAME_INVALID/MANIFEST_UNKNOWN/MANIFEST_INVALID/MANIFEST_BLOB_UNKNOWN/BLOB_UNKNOWN/BLOB_UPLOAD_UNKNOWN/BLOB_UPLOAD_INVALID/DIGEST_INVALID/SIZE_INVALID/RANGE_INVALID/TAG_INVALID/UNAUTHORIZED/DENIED/UNSUPPORTED/PAGINATION_NUMBER_INVALID,共 16 变体)+ HTTP 状态码映射(对照 distribution errcode/register.go;NAME_INVALID→400)+ IntoResponse 封套 {"errors":[{code,message,detail?}]}(detail 空省略)+ 401 附 WWW-Authenticate: Basic realm="mega2 registry", Bearer realm="mega2 registry";auth.rs——凭据解析(Bearer 直取 / Basic 取 password)+ authorize_repo_read/authorize_repo_write(ADR-DR-02)+ registry_ping_allowed(读策略:anonymous_access 开 → 无凭据放行,关 → 需有效 token;无效凭据恒拒);digest.rs——sha256:<hex64> 解析/校验/计算;model.rs——Descriptor 与 4 种 manifest mediaType 常量 + 最小 manifest JSON 结构。

Out of scope:

  • HTTP handler/路由(DR-06+ 消费本卡产物)
  • 对象存储/DB 调用(本卡纯函数/纯领域)
  • OCI token 颁发(永久非目标)

Current evidence:

事实 证据
模块 src/ceres/oci/
注册 src/ceres/mod.rs

Acceptance criteria:

  • 错误码 → 状态码映射表与 distribution errcode 一致(全枚举对照测试)
  • 封套 JSON 形状 {"errors":[{"code","message"}]}
  • Basic 凭据的 password 解析为 token
  • authorize_repo_write 未认证 → Unauthorized
  • authorize_repo_write 有效 token 不覆盖 repo → Denied
  • authorize_repo_read:anonymous_access=false 未认证 → Unauthorized

Verification:

  • source .env.test && cargo test -p mega2 --lib 'ceres::oci::' -- --nocapture
  • (new) cargo test -p mega2 --lib 'ceres::oci::error::tests::envelope_shape' -- --exact
  • (new) cargo test -p mega2 --lib 'ceres::oci::error::tests::status_map_full_enum' -- --exact
  • (new) cargo test -p mega2 --lib 'ceres::oci::auth::tests::auth_matrix' -- --exact(含 DENIED、ping 矩阵、Basic/Bearer 解析与挑战头断言)
  • (new) cargo test -p mega2 --lib 'ceres::oci::digest::tests::rejects_non_sha256_prefix' -- --exact
  • (new) cargo test -p mega2 --lib 'ceres::oci::digest::tests::rejects_short_hex' -- --exact
  • (new) cargo test -p mega2 --lib 'ceres::oci::model::tests::manifest_model_roundtrip' -- --exact(4 mediaType 常量 + 最小结构解析)
  • 零命中守卫(模板):rg -n 'ApiError|CommonResult' src/ceres/oci/ → 退出码 1

Dependencies: 无(复用既有 git 配置面;不依赖 DR-01 新字段)

Deliverables: N/A

Implementation write set: src/ceres/oci/mod.rs、src/ceres/oci/error.rs、src/ceres/oci/auth.rs、src/ceres/oci/digest.rs、src/ceres/oci/model.rs(均新);src/ceres/mod.rs

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 内部模块;错误码清单随 DR-14 入 docs/refactoring/oci.md

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: token 比较沿用常数时间 lookup_push_token;DENIED 与 UNAUTHORIZED 区分(不泄漏覆盖关系以外的信息)

Performance budget: N/A(纯函数)

Estimated scope: M(landing=2;prod-files=6)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=OCI 封套/认证/领域模型; recovery=revert 删除模块; complete=yes; self-contained=yes; AC=6/8; VER=8/8; landing=2; prod-files=6; scope=M; deps=none; writeset=序列化于 DR-06; release=independent; split-from=N/A; exception=N/A

Task DR-06: /v2/ base(ping)与 manifest 写(PUT)

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 新建 src/api/router/oci_router.rs(仿 lfs_router.rs 双形态:oci_routes() Router + routers() OpenApiRouter),按 ADR-DR-08 实现 /{*tail} 单 catch-all + 路径解析派发器骨架(本卡只分派 ping/manifest-write 两族,未知形状 → NAME_INVALID,后续卡续加分派)。实现:GET /v2/ → 走 registry_ping_allowed(ADR-DR-02);PUT /v2/{name}/manifests/{reference}(name 支持多段(team/image);name 正则校验(distribution reference.NameRegexp 等价)否则 NAME_INVALID;4MiB 上限(读满 N+1 判定 MANIFEST_INVALID);mediaType 白名单否则 MANIFEST_INVALID(ADR-DR-05);SHA-256 计算;by-digest 时与 URI digest 不符 → DIGEST_INVALID;by-tag 时 digest 取计算值;引用校验:schema2/oci manifest 的 config+layers 必须都在 oci_blob_ref(缺失 → MANIFEST_BLOB_UNKNOWN),list/index 的子 manifest digest 必须都在 oci_manifest;成功:manifest 字节入对象存储 + oci_manifest/oci_tag 行 + 201 + Location + Docker-Content-Digest)。写路径先过 DR-05 authorize_repo_write。

Out of scope:

  • manifest 读(GET/HEAD/DELETE)(DR-07 承接)
  • blob/uploads/tags 族(DR-08/09/10/11)
  • 挂载与 OpenAPI 聚合(DR-11)

Current evidence:

事实 证据
路由实现 src/api/router/oci_router.rs
模块注册 src/api/router/mod.rs

Acceptance criteria:

  • ping:anonymous 开且未认证 → 200
  • ping:anonymous 关且未认证 → 401
  • ping:无效凭据 → 401
  • PUT manifest by tag(多段名)→ 201
  • PUT by tag 后 oci_tag 行指向服务端计算的 digest
  • PUT by digest 与计算值不符 → DIGEST_INVALID
  • PUT repo 名非法(含 .. 段)→ NAME_INVALID

Verification:

  • source .env.test && cargo test -p mega2 --lib 'api::router::oci_router::tests' -- --nocapture
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::ping_anonymous_open_ok' -- --exact(含 Docker-Distribution-API-Version 头断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::ping_anonymous_closed_401' -- --exact(含 Basic 挑战头断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::ping_invalid_credentials_401' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::put_manifest_by_tag_201' -- --exact(含 Location/Docker-Content-Digest 头断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::put_manifest_sets_tag_row' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::put_manifest_by_digest_mismatch' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::put_manifest_invalid_name' -- --exact

Dependencies: DR-04(OciService)、DR-05(封套/认证/模型)

Deliverables: N/A

Implementation write set: src/api/router/oci_router.rs(新);src/api/router/mod.rs

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 新 HTTP 面;utoipa 注解随挂载(DR-11)进入 OpenAPI

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: repo 名正则白名单;路径穿越拒绝(.. 段);manifest body 上限 4MiB

Performance budget: manifest 点查/单写;引用校验按 layers 数点查 oci_blob_ref(layers 数量级 ≤ 数百)

Estimated scope: M(landing=1;prod-files=2;公开接口变更 = /v2 路由)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=/v2/ base(ping)+ manifest 写(PUT); recovery=revert 删除路由; complete=yes; self-contained=yes; AC=7/8; VER=8/8; landing=1; prod-files=2; scope=M; deps=DR-04,DR-05; writeset=序列化于 DR-05; release=independent; split-from=R2 版 DR-06 拆出 DR-07(读轴); exception=N/A

Task DR-07: manifest 读(GET/HEAD)与 manifest DELETE 注册

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 在 oci_router.rs 派发器追加 manifest 读族:GET/HEAD /v2/{name}/manifests/{reference}(tag→digest 经 oci_tag;If-None-Match/ETag → 304;Docker-Content-Digest 头;未知 repo/tag → NAME_UNKNOWN/MANIFEST_UNKNOWN);DELETE /v2/{name}/manifests/{reference} → UNSUPPORTED(405 封套,ADR-DR-04)。读路径先过 DR-05 authorize_repo_read。

Out of scope:

  • manifest 写(DR-06 已交付)
  • manifest 删除语义(ADR-DR-04 恒 UNSUPPORTED)
  • blob/uploads/tags 族(DR-08/09/10/11)

Current evidence:

事实 证据
manifest GET 参照 /run/media/genedna/data/tmp/distribution registry/handlers/manifests.go(5b354e6f,ETag/304/错误码)
派发器 DR-06 产物(oci_router.rs)
repo 存在性 OciDbStorage::repo_exists(tag/manifest/blob_ref,ADR-DR-03)

Acceptance criteria:

  • GET by tag → 200
  • GET by digest → 200
  • GET If-None-Match 匹配 → 304
  • 未知 repo → NAME_UNKNOWN
  • 未知 tag → MANIFEST_UNKNOWN
  • DELETE → UNSUPPORTED

Verification:

  • source .env.test && cargo test -p mega2 --lib 'api::router::oci_router::tests' -- --nocapture
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_manifest_by_tag_200' -- --exact(含存储 mediaType 与 Docker-Content-Digest 头断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_manifest_by_digest_200' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_manifest_if_none_match_304' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_manifest_unknown_repo' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_manifest_unknown_tag' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::head_manifest_headers_no_body' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::manifest_read_auth_anonymous_off' -- --exact

Dependencies: DR-06(同文件追加 + 写路径产物)

Deliverables: N/A

Implementation write set: src/api/router/oci_router.rs;src/jupiter/storage/oci_db_storage.rs(repo_exists,ADR-DR-03)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 随 DR-11 OpenAPI

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: 读侧认证跟随 anonymous_access(ADR-DR-02)

Performance budget: manifest 点查 + O(manifest) 流式读;无整读入内存

Estimated scope: M(landing=1;prod-files=1;公开接口变更 = /v2 路由)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=manifest 读(GET/HEAD/DELETE); recovery=revert 删除路由; complete=yes; self-contained=yes; AC=6/8; VER=8/8; landing=1; prod-files=1; scope=M; deps=DR-06; writeset=序列化于 DR-06; release=independent; split-from=自 R2 版 DR-06 读轴拆出; exception=N/A

Task DR-08: blob GET/HEAD/DELETE 与 Range

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 在 oci_router.rs 派发器追加 blob 族:GET/HEAD /v2/{name}/blobs/{digest}。成员判定走 oci_blob_ref(repo+digest)缺失 → BLOB_UNKNOWN 404;HEAD → 200 头(Content-Length/Docker-Content-Digest/Accept-Ranges: bytes);GET 全量 → 200 流式(get_stream);Range: bytes=s-e 单区间 → 206 + Content-Range: bytes s-e/size(get_range_stream),router 前置校验 start ≥ size → 416(对齐 trait start >= size 非法契约,不调用 service);多区间/If-Range 不支持 → 忽略按全量 200(distribution 兼容行为);DELETE → UNSUPPORTED 405 封套。读侧认证同 DR-07。

Out of scope:

  • blob 删除语义(ADR-DR-04)
  • uploads(DR-09/DR-10);挂载(DR-11)

Current evidence:

事实 证据
get_range_stream 契约(start >= size 非法) src/orbit_api/object_storage.rs:235-253
blob 处理参照 /run/media/genedna/data/tmp/distribution registry/handlers/blob.go、registry/storage/blobserver.go(5b354e6f)
范围响应参照 /run/media/genedna/data/tmp/spegel pkg/registry/registry.go blobHandler(a8d80fdd)

Acceptance criteria:

  • HEAD 存在 blob → 200
  • GET → 200
  • Range: bytes=s-e → 206
  • Range start ≥ size → 416
  • 未知 blob → BLOB_UNKNOWN
  • DELETE → UNSUPPORTED

Verification:

  • source .env.test && cargo test -p mega2 --lib 'api::router::oci_router::tests' -- --nocapture
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::head_blob_sets_three_headers' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_blob_returns_source_bytes' -- --exact(含 Docker-Content-Digest 头断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_blob_range_206_content_range' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_blob_range_start_ge_size_416' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::get_blob_unknown_404' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::blob_read_auth_anonymous_off' -- --exact

Dependencies: DR-07(同文件追加 + OciService 既有方法)

Deliverables: N/A

Implementation write set: src/api/router/oci_router.rs

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 随 DR-11 OpenAPI

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: digest 参数经 DR-05 解析器白名单化,杜绝路径注入

Performance budget: 全量/范围均流式;无整层驻留内存

Estimated scope: M(landing=1;prod-files=1;公开接口变更 = /v2 路由)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=blob GET/HEAD/DELETE + Range; recovery=revert 删除路由; complete=yes; self-contained=yes; AC=6/8; VER=7/8; landing=1; prod-files=1; scope=M; deps=DR-07; writeset=序列化于 DR-07; release=independent; split-from=N/A; exception=N/A

Task DR-09: uploads 会话(init/PATCH/status)

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 在 oci_router.rs 派发器追加 uploads 会话族,并在 OciService 增补会话方法(ADR-DR-06):POST /v2/{name}/blobs/uploads/(无 mount/digest 查询时建会话:oci_upload 行(uuid v4,offset=0,chunks=0)→ 202 + Location: /v2/{name}/blobs/uploads/{uuid} + Docker-Upload-UUID + Range: 0-0;mount/单体 ?digest= 分派到 DR-10);PATCH /v2/{name}/blobs/uploads/{uuid}(会话存在且 repo 匹配否则 BLOB_UPLOAD_UNKNOWN;Content-Range 提供时 start ≠ offset → RANGE_INVALID;Content-Length 与区间长度不符 → SIZE_INVALID;无 Content-Range 则顺序追加;写 uploads/<uuid>/<seq>(seq=行 chunks)→ 条件更新 WHERE offset=<写入前值> SET offset/chunks+1(冲突 → RANGE_INVALID)→ 202 + 更新后 Range: 0-<offset-1>);GET .../{uuid}(204 + Range: 0-<offset-1> + UUID)。会话跨重启可续(行含 offset/chunks + 分片持久)。写侧认证同 DR-06。

Out of scope:

  • complete/mount/单体上传/会话 DELETE(DR-10 承接)
  • 上传 GC(DEFER-DR-03);multipart 加速(ADR-DR-06 备选)

Current evidence:

事实 证据
状态机参照 /run/media/genedna/data/tmp/distribution registry/handlers/blobupload.go(5b354e6f)
Rust 参照 /run/media/genedna/data/tmp/rk8s project/distribution/src/service/blob.rs(c862eea3)
OciService 原语 DR-04 产物(put_chunk/get_chunk_stream)
OciDbStorage 会话方法 DR-03 产物(upload insert/get/update)

Acceptance criteria:

  • init 返回 202
  • PATCH 顺序分片 → 202
  • PATCH 后 offset 递增
  • PATCH 后 chunks 递增
  • PATCH Content-Range start ≠ offset → RANGE_INVALID
  • PATCH Content-Length 不符 → SIZE_INVALID
  • GET 状态 → 204
  • 未知 uuid → BLOB_UPLOAD_UNKNOWN

Verification:

  • source .env.test && cargo test -p mega2 --lib 'api::router::oci_router::tests' -- --nocapture
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::init_returns_session_headers' -- --exact(Location/Docker-Upload-UUID/Range: 0-0 断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::patch_updates_offset' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::patch_updates_chunks' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::patch_range_mismatch_keeps_session' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::patch_size_mismatch_keeps_session' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::status_204_with_range_header' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::session_survives_restart' -- --exact

Dependencies: DR-08(同文件追加 + OciService 既有方法)

Deliverables: N/A

Implementation write set: src/api/router/oci_router.rs;src/jupiter/service/oci_service.rs(会话方法);src/jupiter/storage/oci_db_storage.rs(CAS offset 更新)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 随 DR-11 OpenAPI

Rollback mode: revert

Migration and rollback: N/A(复用 DR-02 表;revert 后残留会话行无害)

Security and privacy: uuid 会话不暴露分片键;repo 与 uuid 归属双重校验(防跨仓续传)

Performance budget: PATCH 每片一次对象写 + 一次条件 DB 更新;单片上限 DEFAULT_MAX_UPLOAD_CHUNK 128MiB(常量,DR-11 挂 body limit 同值)

Estimated scope: M(landing=2;prod-files=2;公开接口变更 = /v2 路由)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=uploads 会话(init/PATCH/status); recovery=revert 删除状态机; complete=yes; self-contained=yes; AC=8/8; VER=8/8; landing=2; prod-files=2; scope=M; deps=DR-08; writeset=序列化于 DR-08; release=independent; split-from=R2 版 DR-09 拆出 DR-10(完成轴); exception=N/A

Task DR-10: uploads 完成(complete/mount/DELETE)

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 在 oci_router.rs 派发器追加 uploads 完成族(ADR-DR-06):PUT /v2/{name}/blobs/uploads/{uuid}?digest=(可选尾片 → finalize_blob(uuid, chunks, expected) 两遍流式 → 不符 DIGEST_INVALID 且会话保留 → 成功写 oci_blob_ref、按 seq 0..chunks-1 删分片、删会话行 → 201 + Location + Docker-Content-Digest);POST /v2/{name}/blobs/uploads/?mount=<digest>&from=<repo>(先要求目标写授权 + 源读授权(GC-DR-02),源 oci_blob_ref 存在 → 目标写 blob_ref → 201 + blob Location;源缺 → 退化为 DR-09 普通新会话);POST .../uploads/?digest= 单体上传 → 收流写分片 → 两遍完成 → 201;DELETE .../{uuid}(按 seq 删分片 + 删行 → 204;未知 uuid → BLOB_UPLOAD_UNKNOWN)。写侧认证同 DR-06。

Out of scope:

  • init/PATCH/status(DR-09 已交付)
  • 上传 GC(DEFER-DR-03);multipart 加速(ADR-DR-06 备选)
  • blob 删除语义(DR-08 已注册 UNSUPPORTED)

Current evidence:

事实 证据
complete 状态机参照 /run/media/genedna/data/tmp/distribution registry/handlers/blobupload.go(5b354e6f,mount/monolithic/complete)
OciService 原语 DR-04 产物(finalize_blob/delete_chunks/put_blob)
OciDbStorage 会话方法 DR-03 产物(upload delete;blob_ref put/exists)

Acceptance criteria:

  • PUT ?digest= 完成返回 201
  • digest 不符返回 DIGEST_INVALID
  • digest 不符后重试 complete 成功
  • mount 源有读授权且目标写授权时返回 201
  • mount 源无读授权 → DENIED
  • mount 源缺失 → 新会话
  • DELETE 返回 204
  • 完成后 blob GET → 200

Verification:

  • source .env.test && cargo test -p mega2 --lib 'api::router::oci_router::tests' -- --nocapture
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::complete_creates_blob_ref' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::complete_removes_chunks' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::complete_returns_dcd_header' -- --exact(含 Location 与会话行清除断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::digest_mismatch_keeps_session' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::retry_after_mismatch_succeeds' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::monolithic_upload_201' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::pass_b_crash_retry_safe' -- --exact

Dependencies: DR-09(同文件 + 会话产物)

Deliverables: N/A

Implementation write set: src/api/router/oci_router.rs;src/jupiter/service/oci_service.rs(完成路径方法)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 随 DR-11 OpenAPI

Rollback mode: revert

Migration and rollback: N/A(复用 DR-02 表)

Security and privacy: mount 源读授权(GC-DR-02);CAS 键只在 pass A 验证后写入(ADR-DR-06)

Performance budget: complete 2 读 + 1 写 O(size)、常数内存;无 DB 事务膨胀(blob_ref 单行)

Estimated scope: M(landing=2;prod-files=2;公开接口变更 = /v2 路由)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=uploads 完成(complete/mount/DELETE); recovery=revert 删除状态机; complete=yes; self-contained=yes; AC=8/8; VER=8/8; landing=2; prod-files=2; scope=M; deps=DR-09; writeset=序列化于 DR-11; release=independent; split-from=自 R2 版 DR-09 完成轴拆出; exception=N/A

Task DR-11: tags/list、/v2 挂载与 OpenAPI

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 在 oci_router.rs 派发器追加 GET /v2/{name}/tags/list(repo 无 manifest 行 → NAME_UNKNOWN;n(上限 100)/last 分页 → {"name","tags"} + Link 头;非法 n → PAGINATION_NUMBER_INVALID)。在 http_server.rs::app() 的 protocol_surface 分支挂载(与 /info/lfs 同法,静态前缀优先于 catch-all)nest /v2(gate = config.git.storage_only() && config.oci.enabled,两条件缺一不注册);OCI 路由 route_layer(DefaultBodyLimit::max(128MiB))(与 DR-09 单片上限一致);ApiDoc 增 OCI tag 常量;storage_only_openapi_doc()/trunk_openapi_doc() 增 include_oci: bool 参数(由 config.oci.enabled 传入;既有调用点与 http_server 测试同步更新)——include_oci=true 时合并 oci routers(),false 不含;review routers() 恒不含。

Out of scope:

  • _catalog/referrers(DEFER-DR-01/04);删除语义(ADR-DR-04 已定)
  • 进程 IT(DR-12)、smoke(DR-13)、文档(DR-14)

Current evidence:

事实 证据
app() 组装点 src/server/http_server.rs:639-765(protocol_surface :719-736;catch-all :712-717/726;/info/lfs nest :760-763)
OpenAPI 文档组装(无参) http_server.rs:768-785;测试 :1187-1233
tags/list 参照 /run/media/genedna/data/tmp/distribution registry/handlers/tags.go(5b354e6f)
body limit 现状 axum 默认 2MiB(无全局 DefaultBodyLimit 层)

Acceptance criteria:

  • tags/list → 200
  • 无 manifest 的 repo → NAME_UNKNOWN
  • n 分页生效
  • last 分页生效
  • storage-only + enabled=true → /v2/ 可达
  • review 形态 → /v2 404
  • enabled=false → /v2 404
  • OpenAPI include_oci=true 含 /v2 路径

Verification:

  • source .env.test && cargo test -p mega2 --lib 'api::router::oci_router::tests' -- --nocapture
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::tags_list_returns_name_tags_shape' -- --exact(含 Link 头断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::tags_list_pagination_n' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::tags_list_pagination_last' -- --exact
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::tags_list_invalid_n' -- --exact
  • source .env.test && cargo test -p mega2 --lib 'server::http_server' -- --nocapture(include_oci=true 含 /v2、false 不含的双态断言)
  • (new) cargo test -p mega2 --lib 'api::router::oci_router::tests::body_limit_128mib_accepts_large_chunk' -- --exact
  • cargo run -p mega2 -- --config config/config.toml config validate 退出 0

Dependencies: DR-01(config 字段)、DR-10(路由族齐备)

Deliverables: N/A

Implementation write set: src/api/router/oci_router.rs;src/server/http_server.rs;src/api/api_doc.rs;src/jupiter/storage/oci_db_storage.rs(manifest_exists)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 运行时 OpenAPI 新路径(storage-only/trunk 形态且 enabled);storage_only_openapi_doc/trunk_openapi_doc 签名变更(内部函数 + 测试)

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: 双条件 gate fail-closed;enabled=false 时任何 /v2 请求到 catch-all(保持现状 404)

Performance budget: tags/list 走 (repo_name, tag) 前缀扫描,n 上限钳制(100)

Estimated scope: M(landing=3;prod-files=3)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=tags/list + /v2 挂载 + OpenAPI; recovery=revert 撤销挂载; complete=yes; self-contained=yes; AC=8/8; VER=8/8; landing=3; prod-files=3; scope=M; deps=DR-01,DR-10; writeset=序列化于 DR-12; release=independent; split-from=N/A; exception=N/A

Task DR-12: 进程级 IT tests/integration_oci.rs

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 新建进程级黑盒 IT tests/integration_oci.rs,分三组用例(命名前缀可过滤):integration_oci_auth_matrix(token 形态未认证写 401、Basic 凭据写成功、push_auth=none 放行、anonymous_access=false 读 401 与 token 读成功、有效 token 不覆盖 repo → DENIED);integration_oci_protocol_walkthrough(多段名 team/image 全协议:匿名 ping、chunked 上传、单体上传、mount、manifest PUT/GET/304、blob GET + Range 206、tags/list);integration_oci_docker_gated(docker CLI 用例,daemon 可用才跑,否则 SKIP 并断言原因,不构成 PASS 依据)。引导方式:以 CARGO_BIN_EXE_mega2 起 storage-only 服务(复用 tests/integration_git_ssh.rs 的 TestDatabase/ServiceProcess 模式,MEGA_OBJECT_STORAGE__STORAGE_TYPE=local + MEGA_GIT__PUSH_AUTH=token + toml 追加 [oci] enabled = true),用 raw HTTP(reqwest,不依赖宿主 docker)。同步 docs/refactoring/integration.md 覆盖矩阵(GC-06)。

Out of scope:

  • smoke 脚本(DR-13,docker 为必须而非可选)
  • 文档长文(DR-14)

Current evidence:

事实 证据
IT 引导模式 tests/integration_git_ssh.rs:38-287(boot_storage_only_ssh:524)
服务进程管理 同上 ServiceProcess
集成矩阵文档 docs/refactoring/integration.md
reqwest 依赖 Cargo.toml(reqwest = "0.13")

Acceptance criteria:

  • tests/integration_oci.rs 存在(cargo 自动发现)
  • docs/refactoring/integration.md 矩阵同步
  • token 形态:未认证写 401
  • token 形态:Basic 凭据写成功
  • push_auth=none 形态:写放行
  • anonymous_access=false:读 401
  • anonymous_access=false:token 读成功

Verification:

  • source .env.test && cargo test -p mega2 --test integration_oci integration_oci_auth_matrix -- --exact --test-threads=1
  • source .env.test && cargo test -p mega2 --test integration_oci integration_oci_protocol_walkthrough -- --exact --test-threads=1(chunked/monolithic/mount、manifest put/get/304、blob range、tags/list、多段名)
  • source .env.test && cargo test -p mega2 --test integration_oci integration_oci_docker_gated -- --exact --test-threads=1(daemon 不可用 → SKIP 且不 FAIL,sanitized 证据记录原因)

Dependencies: DR-11(完整 /v2 面)

Deliverables: N/A

Implementation write set: tests/integration_oci.rs(新);docs/refactoring/integration.md;src/server/http_server.rs(/v2/ nest + OpenAPI 不并入 live 路由,IT 前置修复)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 集成矩阵新增行

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: 测试 token 用 .env.test 约定值;证据脱敏(ER-11)

Performance budget: N/A(测试)

Estimated scope: S(landing=2;prod-files=0;无 schema/公开接口变更)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=进程级 IT integration_oci; recovery=revert 删除 IT; complete=yes; self-contained=yes; AC=7/8; VER=3/8; landing=2; prod-files=0; scope=S; deps=DR-11; writeset=序列化于 DR-14; release=independent; split-from=N/A; exception=N/A

Task DR-13: docker CLI live smoke 脚本

Task type: implementation

Lifecycle / Acceptance: done / complete

Description: 新建 scripts/oci_smoke_storage_only.sh(独立新脚本,仿 scripts/git_protocol_smoke_storage_only.sh 的 case/skip/summary 结构,不修改后者):针对 storage-only 栈(默认 http://127.0.0.1:9000,MEGA2_OCI_SMOKE_REGISTRY env 可覆盖)用宿主机 docker CLI 完成:docker login(push token 作密码,MEGA2_OCI_SMOKE_TOKEN env;缺省读 secrets/mega2-push-token.local 的默认 dev token)→ 构建/导入一个小镜像(docker import 优先避免外网依赖)→ docker tag <host>/<repo>:<tag> → docker push(多段 repo 名)→ 清本地 → docker pull → digest/分层拉取断言 → docker logout。docker/daemon 不可用或端点不可达 → 全部 SKIP + 显式原因 + 退出码 0;输出 PASS/FAIL/SKIP summary。不修改 docker-compose-storage-only.yml。

Out of scope:

  • compose 集成(未来由独立卡/计划承接)
  • 非 docker 客户端(containerd/oras/crane)矩阵

Current evidence:

事实 证据
smoke 脚本结构参照 scripts/git_protocol_smoke_storage_only.sh(工作区脏文件,只读参照)
默认 dev token secrets/mega2-push-token.local(未跟踪,运行期读取)
storage-only 栈端口 docker-compose-storage-only.yml(HTTP 9000,本卡只读不修改)
docker CLI 宿主 29.7.2(2026-09-10)

Acceptance criteria:

  • 脚本文件存在
  • 无服务 → 用例全部 SKIP
  • docker 不可用 → 用例全部 SKIP
  • SKIP 时脚本退出码 0
  • 有服务 + daemon → push/pull roundtrip PASS
  • 无 token → docker 呈现 401
  • 输出含 PASS/FAIL/SKIP summary
  • summary 与日志无 token 泄漏(ER-11)

Verification:

  • bash -n scripts/oci_smoke_storage_only.sh
  • 有服务 + daemon:MEGA2_OCI_SMOKE_REGISTRY=http://127.0.0.1:9000 bash scripts/oci_smoke_storage_only.sh,末行 summary 断言 0 failed
  • SKIP 路径(docker 缺失):env PATH="/nonexistent" /bin/bash scripts/oci_smoke_storage_only.sh(PATH 无 docker 二进制),输出含 SKIP 且退出码 0
  • SKIP 路径(无服务):MEGA2_OCI_SMOKE_REGISTRY=http://127.0.0.1:1 bash scripts/oci_smoke_storage_only.sh(端点不可达),输出含 SKIP 且退出码 0

Dependencies: DR-11;DEP-DR-02(运行时前置:docker CLI/daemon)

Deliverables: N/A

Implementation write set: scripts/oci_smoke_storage_only.sh(新)

Release write set: Inherited

Files likely touched: 同上

Docs and compatibility impact: 脚本头注释自文档化(用法 + 前置);deploy 文档随 DR-14

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: token 只经 env/文件注入,不进提交日志;镜像源优先离线(docker import)

Performance budget: N/A(测试工具)

Estimated scope: S(landing=1;prod-files=1)

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=implementation; axis=docker CLI live smoke 脚本; recovery=revert 删除脚本; complete=yes; self-contained=yes; AC=8/8; VER=4/8; landing=1; prod-files=1; scope=S; deps=DR-11,DEP-DR-02; writeset=no-overlap; release=independent; split-from=N/A; exception=N/A

Task DR-14: 文档收口

Task type: docs

Lifecycle / Acceptance: done / complete

Description: 新建 docs/refactoring/oci.md(架构与数据流:端点表、路由派发器(ADR-DR-08)、键布局(ADR-DR-07)、认证矩阵(ADR-DR-02 Basic 流与 ping 语义)、错误码清单(DR-05 16 码)、上传状态机(ADR-DR-06 两遍流式与崩溃窗口)、与 distribution/rk8s 参照 pin 及差异、边界与非目标);docs/deploy-trunk.md 增 storage-only OCI 段(启用步骤、docker login 用法、认证语义;脏文件前提——先核对工作区脏改动);docs/refactoring/orbit.md 命名空间清单追加 oci(DR-04 的契约同步义务);docs/plan/README.md 本计划行状态更新为收口终态(Phase 0 已加「新建」行);plan-long.md 日期计划索引登记;复核 DR-12 的 docs/refactoring/integration.md 矩阵行。

Out of scope:

  • 任何 src//Cargo.toml/config 行为改动(发现则 ER-03 重分类)
  • 新 feature 描述(OCI 能力仅由 DR-01..DR-13 引入)

Current evidence:

事实 证据
协议文档参照 docs/refactoring/protocol.md(Git 专用,不并入)
部署文档 docs/deploy-trunk.md(工作区脏文件)
命名空间契约 docs/refactoring/orbit.md
计划索引 docs/plan/README.md;docs/plan/plan-long.md
集成矩阵 docs/refactoring/integration.md

Acceptance criteria:

  • docs/refactoring/oci.md 存在
  • docs/refactoring/oci.md 含参照 pin 章节
  • docs/refactoring/oci.md 含「非目标」章节
  • docs/deploy-trunk.md 含 storage-only OCI 启用段
  • docs/deploy-trunk.md 的既有脏改动开工前已由物主提交(libra status 该文件干净后才动笔)
  • docs/refactoring/orbit.md 命名空间清单含 oci
  • docs/plan/README.md 含本计划行
  • docs/plan/README.md 状态为收口终态
  • plan-long.md 日期计划索引含本计划
  • docs/refactoring/integration.md 含 integration_oci 行
  • 本卡新增 docs/*.md 链接全部指向真实存在的文件

Verification:

  • 暂存区 allowlist:本卡动笔前 libra status 确认 docs/deploy-trunk.md 无既有脏改动(有则先由物主提交/复位,否则本卡 blocked);随后 libra add 仅加 6 个 Deliverables 路径,libra status --short 的暂存区(A 区)仅含这 6 个路径(src/、config/、Cargo.toml、Cargo.lock、scripts/、tests/ 零命中)
  • 链接存在性检查覆盖全部 Deliverables(模板退出码口径):for f in docs/refactoring/oci.md docs/deploy-trunk.md docs/refactoring/orbit.md docs/plan/README.md docs/plan/plan-long.md docs/refactoring/integration.md; do rg -o '\]\([^)#]+\.md' "$f" | sed -E 's/^\]\(//' | while read -r p; do test -f "$(dirname "$f")/$p" || echo "MISSING $p"; done; done → 零 MISSING 输出
  • 章节完整性与 file:line 锚点人工核对(sanitized 证据,登记于本卡 Review log)

Dependencies: DR-12、DR-13

Deliverables: docs/refactoring/oci.md(新);docs/deploy-trunk.md;docs/refactoring/orbit.md;docs/plan/README.md;docs/plan/plan-long.md;docs/refactoring/integration.md(复核)

Implementation write set: 上列 docs 路径

Release write set: N/A

Files likely touched: 同上

Docs and compatibility impact: 本卡即文档

Rollback mode: revert

Migration and rollback: N/A

Security and privacy: 文档不含真实 token;示例用 <token> 占位(ER-11)

Performance budget: N/A

Estimated scope: M(产物文件 ≤ 15)

Version increment: N/A

Release boundary: no-release

C/D coverage from: DR-15(计划收口 release 卡:其三门运行发生在 DR-14 提交之后,被测树包含本卡最终变更)

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=docs; axis=文档收口; recovery=revert 文档; complete=yes; self-contained=yes; AC=11/20; VER=3/20; landing=0; prod-files=0; scope=M; deps=DR-12,DR-13; writeset=no-overlap; release=no-release; split-from=N/A; exception=N/A

Task DR-15: 计划收口(release)

Task type: release

Lifecycle / Acceptance: done / complete

Description: 计划收口点:在 DR-14 文档变更已提交、工作树处于全计划最终状态的前提下,执行完整发布切片——版本面 parity 预检 → patch +1 bump(示例 0.8.35 → 0.8.36,实际以 ER-08 开工日核对为准;开工时若版本面存在他人未提交改动则先等待其发布,ER-12)+ Cargo.lock 刷新 → 三门 → build 校验 → libra commit + libra push origin main。本卡不引入新行为;其 C 组运行同时构成 DR-14 的 C/D 覆盖证据。

Out of scope:

  • 任何行为/文档再修改(发现问题按 ER-10 走 FIX-*,不就地并入本卡)
  • tag/release artifact(本仓无发布流水线,N/A)

Current evidence:

事实 证据
版本面 Cargo.toml:3(bump 前以开工日 rg -n '^version' Cargo.toml 为准)
前置卡 DR-14 Lifecycle=done(本卡开工前提)
D 组 .github/workflows/ 为空(2026-09-10)

Acceptance criteria:

  • cargo +nightly fmt --all --check 无 diff
  • cargo clippy --all-targets --all-features -- -D warnings 0 警告
  • source .env.test && cargo test --all 全绿(被测树含 DR-14 最终变更)
  • cargo build 0 错误 0 警告
  • cargo build --tests 0 错误 0 警告
  • 版本面已 bump 至计划预期值
  • Cargo.lock 已刷新
  • Cargo.lock 版本条目与版本面自洽
  • libra commit 成功
  • 提交信息含 v<version>
  • libra push origin main 成功
  • 远端 ref 含本卡提交

Verification:

  • libra log -1 为本卡提交(bump 值与 Cargo.lock 自洽)
  • 远端 ref 比对:remote_ref=$(libra ls-remote --heads origin main | awk 'NR==1{h=$1} END{print h; if(NR!=1) exit 1}') && test "$(libra rev-parse HEAD)" = "$remote_ref" 退出 0(恰一条匹配 ref 且 hash 与本地 HEAD 一致;ER-09:不一致或非 fast-forward 停并报告)
  • libra status --short --branch 无越界改动(除已知未跟踪项)

Dependencies: DR-14

Deliverables: N/A

Implementation write set: 无(仅 Release write set)

Release write set: Cargo.toml(version)+ Cargo.lock

Files likely touched: 同上

Docs and compatibility impact: N/A(无行为变化)

Rollback mode: revert(本地未推送前 revert;已推送则按 ER-09/前滚)

Migration and rollback: N/A

Security and privacy: N/A

Performance budget: N/A

Estimated scope: S

Version increment: patch

Release boundary: independent

C/D coverage from: self

D-group (ER-04): N/A(本 checkout 无 CI workflow 文件,无 paths 过滤器可命中)

Granularity: type=release; axis=计划收口(bump + 三门 + 推送); recovery=revert 收口提交; complete=yes; self-contained=yes; AC=12/12; VER=3/12; landing=0; prod-files=0; scope=S; deps=DR-14; writeset=no-overlap; release=independent; split-from=N/A; exception=N/A

测试矩阵

类别 必须覆盖 Target / command
单元 配置门、封套/认证矩阵(含 DENIED 与 ping 矩阵)、digest、manifest 模型 --lib 'config::';--lib 'ceres::oci::'
集成(DB) 4 表迁移 + OciDbStorage 幂等 --lib 'jupiter::migration';--lib 'jupiter::storage::oci_db_storage'
集成(对象) 命名空间键、两遍流式 finalize、range 边界 --lib 'orbit_api::object_storage';--lib 'jupiter::service::oci_service'
HTTP 各端点 oneshot 走查(多段名;ping/manifest/blob/uploads/tags) --lib 'api::router::oci_router::tests'
进程黑盒 认证矩阵 + 全协议走查(raw HTTP,Basic 凭据) --test integration_oci -- --test-threads=1
live/gated docker CLI login/push/pull(daemon 必需) bash scripts/oci_smoke_storage_only.sh
配置 [oci] 白名单/校验门 cargo run -p mega2 -- ... config validate
Git 协议 挂载不回归 catch-all 既有 --test integration_git_ssh 全量(三门内)
性能 finalize 两遍流式、range 流式、常数内存 DR-04/08 单测断言(代码审查 + 流式实现)
安全 401 Basic 挑战、DENIED、路径白名单、mount 双授权 --lib 'ceres::oci::' + IT 认证矩阵

追溯表

任务 来源/证据 mega2 落点 文档/兼容动作 指定测试
DR-01 GAP-DR-02;ADR-DR-01 src/config/**;两个样例 toml 样例注释 --lib 'config::'
DR-02 GAP-DR-04;ADR-DR-03/06 src/jupiter/migration/** 内部 schema migration 信息架构断言
DR-03 GAP-DR-04 src/callisto/**;oci_db_storage.rs;jupiter/storage/mod.rs 内部 oci_db_storage 走查
DR-04 GAP-DR-03;ADR-DR-07 src/orbit_api/object_storage.rs;oci_service.rs orbit.md 清单(DR-14) --lib 'jupiter::service::oci_service'
DR-05 GAP-DR-05;ADR-DR-02/05 src/ceres/oci/** 错误码清单(DR-14) --lib 'ceres::oci::'
DR-06 distribution manifests.go;rk8s api/v2.rs src/api/router/oci_router.rs OpenAPI(DR-11) oneshot 走查(多段名 + ping)
DR-07 distribution manifests.go(ETag/304) 同上 OpenAPI(DR-11) oneshot 走查
DR-08 distribution blob.go/blobserver.go;spegel registry.go 同上 OpenAPI(DR-11) oneshot 走查
DR-09 distribution blobupload.go;rk8s service/blob.rs oci_router.rs;oci_service.rs OpenAPI(DR-11) 会话走查 + 重启续传
DR-10 distribution blobupload.go(mount/complete) 同上 OpenAPI(DR-11) complete/mount 走查
DR-11 GAP-DR-01;distribution tags.go oci_router.rs;http_server.rs;api_doc.rs 运行时 OpenAPI 证据(include_oci 双态) openapi 断言 + config validate
DR-12 GAP-DR-06 tests/integration_oci.rs integration.md 矩阵 --test integration_oci
DR-13 DEP-DR-02 scripts/oci_smoke_storage_only.sh 脚本头注释 live smoke
DR-14 GAP-DR-06 docs only oci.md/deploy-trunk/orbit.md/索引 链接门
DR-15 本计划完成判据 版本面 + Cargo.lock N/A 三门

里程碑验收与回滚

里程碑 完成条件 发布/证据 回滚或前滚
M0 计划 Codex PASS;Phase 0 本文件 Review log;libra tip 含本计划 revert 计划文档
M1 DR-01..DR-04 发布 0.8.23..26(示例;以开工日 parity 预检为准);校验门/四表/DB 层/命名空间测试绿 revert DR-01/03/04;DR-02 只能前滚
M2 DR-05..DR-11 发布 0.8.27..33(示例);/v2 全端点 + 挂载门 + OpenAPI 双态 revert 各卡
M3 DR-12+DR-13 发布 0.8.34..35(示例);IT 全绿 + smoke 0 failed revert
M4 DR-14 文档 + DR-15 收口 0.8.36(示例);文档与索引一致;三门含 DR-14 最终变更全绿 revert 文档/收口提交

故障恢复矩阵

故障点 可接受残留 恢复动作 禁止结果
DR-02 已推、DR-03 未推 空表 + 无存储层 继续 DR-03;空表无害 手工插表当事实源
DR-10 已推、DR-11 未推 端点存在但未挂载 继续 DR-11;无外部可达性 绕过 gate 临时挂载
PATCH 后崩溃(分片已写、DB 未更新) 孤儿分片(seq 未被计数) 会话 DELETE/complete 只清计数内分片;孤儿留给 GC(DEFER-DR-03) 把孤儿分片计入最终 blob
complete pass A 后崩溃 会话原样(分片未动) 重试 complete(pass A 无副作用) 跳 pass A 直接落 CAS
complete pass B 中途崩溃 CAS 键部分字节 + oci_blob_ref 缺失(对读者不可见) 重试 complete 覆写同键(内容寻址,覆写安全) 以 exists 跳过验证
会话过期残留(无 GC) 分片对象 + oci_upload 行堆积 手工/后续 GC(DEFER-DR-03) 自动删除在途会话
docker daemon 不可用(DR-13) smoke 全 SKIP 脚本退出 0 + 原因 把 SKIP 记成 PASS
DR-14 已提交、DR-15 三门失败 文档已入树、版本未 bump 修三门问题(文档 revert 或前滚);再跑 DR-15 带着三门红结果推送

风险登记

风险 影响 缓解 任务
docker 客户端行为与 spec 细节偏差(头/状态码) 高:push/pull 失败 以 distribution 为语义基准 + DR-12 raw HTTP 先证 + DR-13 live 终验 DR-06..10/12/13
oci_router.rs 六卡共享文件导致串行阻塞 中:调度受限 计划已声明全串行(G-10) DR-06..11
工作区脏文件(deploy-trunk.md 等)混入提交 中:用户改动被覆盖 ER-01 特化:先核对、不覆盖;libra add 只加本卡路径 DR-14
S3 后端 complete 两遍流式成本 低-中:大镜像推送变慢 2 读 1 写常数内存;multipart 优化 DEFER-DR-03 DR-04/10
manifest list 旧客户端平台重写缺失 低:docker <1.13 ADR-DR-05 明示;DEFER-DR-05 DR-06
token paths 前缀语义对 repo 名映射歧义 低:路径前缀天然适配 ADR-DR-02(repo 当 /repo) DR-05
/{*tail} 派发器解析错误导致 500/错误路由 中:手写解析覆盖不全 ADR-DR-08 参照 rk8s dispatch;oneshot 矩阵 + IT 多段名覆盖 DR-06/09/10/11/12
计划成稿期间工作树持续前进(SO-* 卡发布) 中:锚点漂移 GC-01 开工日刷新锚点;本计划写集与 SO-* 写集不相交 全部卡

性能与容量摘要

操作 单次成本 累积成本 预算/上限 验证
manifest GET/PUT O(1) 点查 + O(manifest) 读写 与 tag 数无关 4MiB body 上限 DR-06/07 走查
blob GET(全量/范围) O(读区间) 流式 带宽线性 常数内存 DR-08 走查
PATCH 分片 O(片) 对象写 + O(1) 条件 DB 更新 O(size) 单片 128MiB 上限 DR-09 走查
upload complete 2 读 + 1 写 O(size) + 单遍 sha256 O(size) 常数内存;无 DB 事务膨胀(blob_ref 单行) DR-04/10 走查
tags/list O(k) 前缀扫描(分页钳制) O(tags) n ≤ 100 DR-11 走查

兼容与文档收口

  • docs/errors.md 已同步,或说明 N/A(OCI 错误封套独立于 MegaError,DR-05 代码注释 + docs/refactoring/oci.md 清单,不改 errors.md;树内 docs/errors.md 无 OCI 条目)。
  • docs/refactoring/oci.md 已创建;orbit.md 命名空间清单与 integration.md 已同步(DR-12/DR-14;ObjectNamespace::Oci / integration_oci 行在树)。
  • config/config.toml 注释样例与 config-storage-only.toml 样例已同步(DR-01;后者活跃 [oci] enabled = true)。
  • 运行时 OpenAPI(/api/openapi.json)证据已取得(DR-11:storage_only_openapi_include_oci_dual_state / trunk_openapi_include_oci_dual_state 在 http_server.rs)。
  • README.md / AGENTS.md:N/A(不改工程约束;AGENTS.md 无需新增 OCI 小节,除非本计划引入新命令/配置约定——无)。
  • src/callisto/、src/jupiter/storage/ 与 migrations() 已同步(DR-02/03/04;oci_*.rs + OciDbStorage + m20260902_000100_add_oci_tables)。
  • 新引入的 docs/*.md 引用全部指向真实存在的文件(DR-14;oci.md 本地链接抽检无缺失)。
  • plan-long.md 日期计划索引已登记(DR-14;状态 已完成,收口 v0.8.53 / tip 070783e)。

Review log

Result 只允许 PASS 或 FAIL。FAIL 必须列出 P0/P1 条目并在下一轮复审关闭;P2 可由具名责任人书面接受为 residual risk,但不改变本轮 FAIL 记录(ER-05)。

Round Scope Result P0/P1 P2 处置 Evidence
R1 本计划成稿(Codex) FAIL P0×8:by-tag PUT 误要求 digest 字段;认证不可执行于 docker;{name} 不支持多段名;分片寻址不可恢复;mount 缺源读授权;OpenAPI builder 无参;粒度审计按行计且 DR-02 混轴;no-release C/D 宿主不成立。P1×6:DAG 不一致、NAME_INVALID 缺失、DELETE 矛盾、prod-files 计数、orbit.md 归属、Review log 占位符——全部关闭 无 target/tmp/plan-20260902-codex-r1.txt
R2 R1 修订后(Codex) FAIL P0×3:粒度审计仍按行计谓词、DR-03 写集与 scope 不符;匿名 pull 被 ping 401 阻断;complete 单遍写 CAS 键不可实现。P1×2:range 契约冲突;事实基线过期——全部关闭 无 target/tmp/plan-20260902-codex-r2.txt
R3 R2 修订后(Codex) FAIL P0×1:DR-02 含 schema 变更误标 S、DR-09/DR-06 AC 仍按行计数——本轮 DR-02 改 M、uploads 拆 DR-09/DR-10 两卡、全部 AC 单谓词重写。P1×2:DR-14 no-release 缺具名宿主——本轮新增 DR-15(release)收口卡并声明为宿主;事实基线过期——本轮刷新。P2×2:DR-06 landing 计数、DR-12 prod-files 计数——本轮校正 无 target/tmp/plan-20260902-codex-r3.txt
R4 R3 修订后(Codex) FAIL P0×1:DR-05 ping 三态矩阵、DR-12 多场景行仍超单谓词口径——本轮 DR-05/DR-12 均拆为 8 条单谓词。P1×2:DR-12 AC 计数 6→8 校正;基线过期(版本 0.8.19、脏文件增 Cargo.toml/Cargo.lock)——本轮刷新并加 ER-01/ER-12 版本面等待特化 无 target/tmp/plan-20260902-codex-r4.txt
R5 R4 修订后(Codex) FAIL P0×1:DR-12 末条 AC 仍为多场景矩阵——本轮降为 7 条单谓词 AC、走查移入 VER。P1×2:基线过期(tip 2163edf、版本面已干净)——本轮刷新并把手改为条件检查;DR-15 VER 按独立门重计为 4——本轮校正 无 target/tmp/plan-20260902-codex-r5.txt
R6 R5 修订后(Codex) FAIL P1×2:基线过期(tip 9e08621 SO-09、版本 0.8.20 已提交、脏文件收敛为 secrets/)——本轮刷新并把版本面声明为受并行发布流影响;DR-15 VER 首行与强制门重复——本轮删除并改 VER=3/12 无 target/tmp/plan-20260902-codex-r6.txt
R7 R6 修订后(Codex) FAIL P0×1:协议卡 AC 仍按行计谓词(头/列/状态各计一条)——本轮全部协议卡 AC 重写为单谓词至 8/8,细粒度断言下沉 VER 无 target/tmp/plan-20260902-codex-r7.txt
R8 R7 修订后(Codex) FAIL P0×1:AC 仍含头/字节保真细节、VER 仍为捆绑矩阵——本轮 AC 收敛为纯行为谓词、VER 拆为逐测试函数门。P1×1:版本面等待规则只覆盖 DR-15——本轮扩展至全部独立发布卡;基线刷新至 804fac5/0.8.21 无 target/tmp/plan-20260902-codex-r8.txt
R9 R8 修订后(Codex) FAIL P0×1:AC 残留字节保真与不可执行 VER——本轮 DR-04/DR-10 AC 改行为谓词,DR-01/DR-02 VER 改逐函数过滤门。P1×1:脏文件清单过期——本轮刷新并写明只追加不覆盖处置 无 target/tmp/plan-20260902-codex-r9.txt
R10 R9 修订后(Codex) FAIL P0×2:命名测试门可零命中通过——本轮新增 GC-DR-06(--exact + 输出断言);DR-13 AC 复合行——本轮拆为 7 条单谓词。P1×1:DR-14 VER 复合散文——本轮改为逐条可执行命令 无 target/tmp/plan-20260902-codex-r10.txt
R11 R10 修订后(Codex) FAIL P0×1:DR-05 digest/mediaType 与 DR-14 文档项仍为捆绑谓词——本轮 DR-05 AC 收窄为 6、DR-14 AC 拆为 11。P1×1:DR-14 VER 越界面/链接清单不完整——本轮补全 无 target/tmp/plan-20260902-codex-r11.txt
R12 R11 修订后(Codex) FAIL P0×2:命名测试门缺 --exact——本轮全文补齐;DR-03 注册谓词超限——本轮 AC 收窄为 4。P1×1:DR-14 范围检查无法区分既有脏改动——本轮改为暂存区 allowlist 无 target/tmp/plan-20260902-codex-r12.txt
R13 R12 修订后(Codex) FAIL P0×1:批量补 --exact 致 55 条命令体丢失——本轮脚本重建。P1×1:DR-14 路径暂存会纳入既有脏 hunk——本轮改为物主先提交 + 暂存区 allowlist 无 target/tmp/plan-20260902-codex-r13.txt
R14 R13 修订后(Codex) FAIL P0×1:DR-01/DR-13/DR-15 三处 AC 仍按行计——本轮逐一拆分(7/8、8/8、10/12)并补无服务 SKIP 验证 无 target/tmp/plan-20260902-codex-r14.txt
R15 R14 修订后(Codex) FAIL P0×2:DR-15 复合 AC 超限——本轮拆至 12;GC-DR-06 与模块级门冲突——本轮收窄至函数级门。P1×1:DR-13 SKIP 验证散文——本轮改精确命令 无 target/tmp/plan-20260902-codex-r15.txt
R16 R15 修订后(Codex) FAIL P1×2:DR-13 docker 缺失路径无效——本轮改 PATH=/nonexistent;DR-15 远端 ref 验证散文——本轮改 rev-parse/ls-remote test 比对 无 target/tmp/plan-20260902-codex-r16.txt
R17 R16 修订后(Codex) FAIL P1×2:DR-15 比对裸 hash vs 全行输出必然失败——本轮 awk 提取首字段;基线过期(SO-11/0.8.22)——本轮刷新并重算里程碑 无 target/tmp/plan-20260902-codex-r17.txt
R18 R17 修订后(Codex) FAIL P1×1:DR-15 比对命令替换内丢弃 awk 失败状态仍 fail-open——本轮改为变量赋值 + && 链式比对 无 target/tmp/plan-20260902-codex-r18.txt
R19 R18 修订后(Codex) PASS 无 P2×3(residual,具名接受:作者 genedna):awk 先赋值后比对已验证(0/多 ref 短路);审计行与 Granularity 一致;oci.md 为 DR-14 同卡产物非悬空链接 target/tmp/plan-20260902-codex-r19.txt
DR-01-IR1 DR-01 实现(Codex) PASS 无 无 target/tmp/dr01-codex-r1.txt
DR-02-IR1 DR-02 实现(Codex) PASS 无 无 target/tmp/dr02-codex-r1.txt
DR-02-IR2 DR-02 写集扩 UN-18 helper(Codex) PASS 无 无 target/tmp/dr02-codex-r2.txt
DR-03-IR1 DR-03 实现(Codex) PASS 无 无 target/tmp/dr03-codex-r1.txt
DR-04-IR1 DR-04 实现(Codex) PASS 无 无 target/tmp/dr04-codex-r1.txt
DR-05-IR1 DR-05 实现(Codex) PASS 无 无 target/tmp/dr05-codex-r1.txt
DR-06-IR1 DR-06 实现(Codex) FAIL P0:repository name regex 不等价 distribution remoteName(尾分隔符误收、内部分隔符误拒) 本轮修正 target/tmp/dr06-codex-r1.txt
DR-06-IR2 DR-06 实现(Codex,regex 修正后) PASS 无 无 target/tmp/dr06-codex-r2.txt
DR-07-IR1 DR-07 实现(Codex) FAIL P1:缺失 tag 时仅用 list_tags 判 repo 存在 → blob_ref/manifest-only 误报 NAME_UNKNOWN 本轮修正 repo_exists target/tmp/dr07-codex-r1.txt
DR-07-IR2 DR-07 实现(Codex,repo_exists 后) FAIL 卡面仍 pending(实现已齐) 本轮标 done/complete target/tmp/dr07-codex-r2.txt
DR-07-IR3 DR-07 实现(Codex,卡面 done 后) PASS 无 无 target/tmp/dr07-codex-r3.txt
DR-08-IR1 DR-08 实现(Codex) PASS 无 无 target/tmp/dr08-codex-r1.txt
DR-09-IR1 DR-09 实现(Codex) FAIL P1:PATCH 先写分片后 CAS,并发可覆盖已接受分片 本轮改为先 CAS 再写分片 target/tmp/dr09-codex-r1.txt
DR-09-IR2 DR-09 实现(Codex,CAS-first 后) FAIL P1:无条件 rollback 可抹掉后继 claim;CAS 仅 offset 时空 PATCH 竞态 本轮 CAS(offset+chunks)+条件 rollback target/tmp/dr09-codex-r2.txt
DR-09-IR3 DR-09 实现(Codex,CAS 双列+条件 rollback) PASS 无 无 target/tmp/dr09-codex-r3.txt
DR-10-IR1 DR-10 实现(Codex) PASS 无 无 target/tmp/dr10-codex-r1.txt
DR-11-IR1 DR-11 实现(Codex) PASS 无 无 target/tmp/dr11-codex-r1.txt
DR-12-IR1 DR-12 实现(Codex) PASS 无 无 target/tmp/dr12-codex-r1.txt
DR-13-IR1 DR-13 实现(Codex) FAIL P1:无 token 用例未强制 401;sanitize 用 bash glob 替换不安全 本轮强制 401 + Python 字面 redact target/tmp/dr13-codex-r1.txt
DR-13-IR2 DR-13 实现(Codex,401+Python redact) FAIL P1:sed glob-escape fallback 语法破损 本轮改纯 bash 逐字 escape target/tmp/dr13-codex-r2.txt
DR-13-IR3 DR-13 实现(Codex,bash escape) FAIL P1:backslash 未正确 escape 本轮 case 匹配单反斜杠 target/tmp/dr13-codex-r3.txt
DR-13-IR4 DR-13 实现(Codex,单反斜杠 escape) PASS 无 无 target/tmp/dr13-codex-r4.txt
DR-14-IR1 DR-14 实现(Codex) FAIL P1:索引暂存混入 plan-20260911 行 本轮从 README/plan-long 剥离 target/tmp/dr14-codex-r1.txt
DR-14-IR2 DR-14 实现(Codex,索引纯化后) PASS 无 无 target/tmp/dr14-codex-r2.txt
DR-15-IR1 DR-15 收口(三门+build+push) PASS 无 无 target/tmp/dr15-clippy.log;target/tmp/dr15-cargo-test-all.log
CLOSE 计划文档收口(对照代码勾选完成判据) PASS 无 DEFER-DR-01..06 保留 树内 oci_* / oci_router / integration_oci / oci.md;索引 96077b9;target/tmp/dr-doc-close-*.log

非目标与延后项

ID 延后内容 原因 重启条件 承接位置
DEFER-DR-01 _catalog、repo 枚举 与安全/配额耦合;docker 客户端不需要 registry UI/配额需求出现 新日期计划
DEFER-DR-02 manifest/blob 删除语义 + GC(含上传会话与孤儿分片清扫) 删除语义需回收与引用计数设计 引入 GC 与配额时 新日期计划(先补 oci_repository 表与引用计数)
DEFER-DR-03 S3 multipart / copy 加速 complete 现有两遍流式正确但 2 读 1 写 O(size) 大镜像推送成为瓶颈时 新日期计划
DEFER-DR-04 referrers API(/v2/<name>/referrers/<digest>) cosign/notation 场景,超出最小面 签名工件需求出现 新日期计划
DEFER-DR-05 manifest list 平台重写(老客户端兼容) docker ≥1.13 客户端自选平台 出现老客户端投诉 新日期计划
DEFER-DR-06 compose smoke profile 集成(docker-compose-storage-only.yml) 已由 plan-20261001 的 BB-10..BB-23 与 BB-90/BB-91 交付:interop-smoke 默认栈 OCI 12 passed / 0 failed,auth-none opt-in case PASS 且恢复默认栈 已关闭 plan-20261001

完成判据

计划只有在以下条件全部满足后才能标记完成:

  • 所有任务卡满足粒度规则 G-*:无未登记的 L 例外、无 XL 卡、无碎片卡、无未登记的合并发布例外、实现写集冲突均已消解;「任务卡粒度审计表」已填齐。
  • 所有非延后任务的 acceptance criteria 已满足,且 Lifecycle=done 且 Acceptance=complete(ER-04;本计划所有卡 D 组 N/A)。DR-14(no-release)的 C 覆盖由 DR-15 的收口三门提供(其被测树含 DR-14 最终变更)。
  • 所有任务的 Verification 命令已运行并记录结果。
  • 计划完成门(由 DR-15 执行):cargo +nightly fmt --all --check、cargo clippy --all-targets --all-features -- -D warnings、source .env.test && cargo test --all 全绿,且 cargo build、cargo build --tests 均 0 错误 0 警告;不得新增 crate 级 #[allow(...)](证据 DR-15-IR1 / tip 070783e)。
  • 必要的 docs/配置/错误契约/测试矩阵更新已完成(见上节「兼容与文档收口」;对照代码于 2026-09-11 复核)。
  • 必要的 migration、rollback、failure-recovery 验证已完成;每张卡的 Rollback mode 都已被实际验证或记录为不可验证的原因(已推 tip 前滚;DR-02 forward-only)。
  • 代码 review 最终结论为 PASS,P0/P1 全部关闭;仅 P2 residual risk 允许保留,且有具名接受人(R19;各卡 IR 最终 PASS)。
  • 版本面已按各卡 Version increment(patch)逐卡 bump 且自洽、构建、提交、推送证据已完成(ER-08;DR-15 收口 bump 至 v0.8.53 / 070783e);无 release artifact 要求(本仓无发布流水线),写 N/A 及原因。
  • 「修订历史」已记录成稿后的全部规范性变更(G-09)。
  • plan-long.md 日期计划索引已同步(DR-14;已完成,96077b9)。