路径说明(2026-09-20): 本文成稿时
docker-compose-storage-only.yml/docker-compose-storage-only.auth-none.yml/docker-compose.test.yml位于仓库根;2026-09-20 起三者迁入docker/目录(commit1854cae)。文中根目录原路径为历史记录,不再逐一回改;实际使用时请替换为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/manifestDELETE只注册路由并返回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 →DENIED403;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 |
实现时若需偏离本节,必须先修改计划并说明原因,不得在代码中静默改语义。
- 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 形态需要镜像分发(需重新评审认证与配额)。
- 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"(与 gitauth_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 流时。
- 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表。
- 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 或回收能力时。
- 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 白名单校验后原样入对象存储(keymanifests/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 兼容或平台重写时。
- 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
_stateURL 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 可用且需省一趟读时。
- 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。
- 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-02DR-02 -> DR-03DR-03 -> DR-04DR-04 -> DR-06DR-05 -> DR-06DR-06 -> DR-07DR-07 -> DR-08DR-08 -> DR-09DR-09 -> DR-10DR-10 -> DR-11DR-01 -> DR-11DR-11 -> DR-12DR-11 -> DR-13DR-12 -> DR-14DR-13 -> DR-14DR-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)。
目标: 计划 Codex 评审 PASS;本计划文档 + docs/plan/README.md 索引行落库。
进入条件: 无(计划文档工作)。
退出条件: Review log 最终行 PASS;libra tip 含 docs/plan/plan-20260902.md。
目标: DR-01(配置门)+ DR-02(4 表迁移)+ DR-03(实体与 OciDbStorage)+ DR-04(命名空间 + OciService 对象层)。
进入条件: Phase 0 退出。
退出条件: [oci] 校验生效;apply_migrations 后 4 表存在;oci 命名空间 roundtrip 测试绿。
目标: 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。
目标: DR-12(进程 IT)+ DR-13(docker live smoke)。
进入条件: DR-11 发布。
退出条件: tests/integration_oci 全绿;smoke 脚本在 docker daemon 可用环境下 0 failed。
目标: DR-14(文档)+ DR-15(计划收口 release)。
进入条件: DR-12、DR-13 发布。
退出条件: 文档与索引一致;DR-15 三门在含 DR-14 最终变更的树上全绿并推送。
N/A(原因:全文逐字遵守 plan-template.md 的 G-01..G-11 与推荐拆分/反模式速查;不在本文件复制以免与模板漂移。本计划以各卡 Granularity 行与「任务卡粒度审计表」为机器可核对摘要。)
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 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.enabledserde 缺省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 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 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 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_blobpass 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 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 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 -
PUTmanifest by tag(多段名)→201 -
PUTby tag 后oci_tag行指向服务端计算的 digest -
PUTby digest 与计算值不符 →DIGEST_INVALID -
PUTrepo 名非法(含..段)→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 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:
-
GETby tag → 200 -
GETby digest → 200 -
GETIf-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 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 -
Rangestart ≥ 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 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-Rangestart ≠ 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 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 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 形态 →
/v2404 -
enabled=false→/v2404 - 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 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 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/SKIPsummary - 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 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 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 warnings0 警告 -
source .env.test && cargo test --all全绿(被测树含 DR-14 最终变更) -
cargo build0 错误 0 警告 -
cargo build --tests0 错误 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 / tip070783e)。
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/ tip070783e)。 - 必要的 docs/配置/错误契约/测试矩阵更新已完成(见上节「兼容与文档收口」;对照代码于 2026-09-11 复核)。
- 必要的 migration、rollback、failure-recovery 验证已完成;每张卡的
Rollback mode都已被实际验证或记录为不可验证的原因(已推 tip 前滚;DR-02forward-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)。