Implementation Plan: APT/APK 包缓存模块

Branch: 007-apt-apk-cache | Date: 2025-11-17 | Spec: /home/rogee/Projects/any-hub/specs/007-apt-apk-cache/spec.md Input: Feature specification from /specs/007-apt-apk-cache/spec.md

Summary

为 any-hub 增加 APT（Debian/Ubuntu）与 Alpine APK 的缓存代理模块：索引（Release/InRelease/Packages*/APKINDEX）必须再验证，包体（pool/.deb、packages/）视作不可变直接缓存，支持 Acquire-By-Hash/签名透传，不影响现有各模块。

Technical Context

Language/Version: Go 1.25+ (静态链接，单二进制)
Primary Dependencies: Fiber v3（HTTP 服务）、Viper（配置）、Logrus + Lumberjack、标准库 net/http/io
Storage: 本地 StoragePath/<Hub>/<path> + .meta；索引需带 Last-Modified/ETag 元信息；包体按原路径落盘
Protocols: APT (/dists/<suite>/<component>/binary-<arch>/Packages*, Release, InRelease, pool/*), Acquire-By-Hash；Alpine (APKINDEX.tar.gz, packages/<arch>/…)
Caching Rules: 索引 RequireRevalidate=true；包体 AllowStore/AllowCache=true、RequireRevalidate=false；签名/校验文件原样透传
Testing: go test ./...，构造 httptest 上游返回 Release/Packages/APKINDEX 与包体，验证首次回源+再验证+命中；使用临时目录校验缓存落盘
Target Platform: Linux/Unix CLI，systemd/supervisor 托管，匿名客户端
Constraints: 单一 config.toml 控制；禁止新增第三方依赖；保持现有模块行为不变
Risk/Unknowns: Acquire-By-Hash 路径映射是否需额外校验逻辑（选择原样透传，路径即校验）

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Feature 仍然是“轻量多仓 CLI 代理”，未引入 Web UI、账号体系或与代理无关的能力。
仅使用 Go + 宪法指定依赖；任何新第三方库都已在本计划中说明理由与审核结论。
行为完全由 config.toml 控制，新增配置项已规划默认值、校验与迁移策略。
方案维持缓存优先 + 流式回源路径，并给出命中/回源/失败的日志与观测手段。
计划内列出了配置解析、缓存读写、Host Header 路由等强制测试与中文注释交付范围。

Status: PASS（未引入新依赖/界面，新增配置仅增加模块枚举与示例）

Project Structure

Documentation (this feature)

specs/007-apt-apk-cache/
├── plan.md              # 本文件
├── research.md          # Phase 0 输出
├── data-model.md        # Phase 1 输出
├── quickstart.md        # Phase 1 输出
├── contracts/           # Phase 1 输出
└── tasks.md             # Phase 2 (/speckit.tasks 生成)

Source Code (repository root)

cmd/any-hub/main.go        # CLI 入口、参数解析
internal/config/           # TOML 加载、默认值、校验
internal/server/           # Fiber 服务、路由、中间件
internal/cache/            # 磁盘/内存缓存与 .meta 管理
internal/proxy/            # 上游访问、缓存策略、流式复制
internal/hubmodule/*       # 各模块 Hooks/元数据（新增 debian/apk 模块）
configs/                   # 示例 config.toml（如需）
tests/                     # go test 下的单元/集成测试

Structure Decision: 新增模块位于 internal/hubmodule/debian 或类似命名；复用现有 hook 注册与缓存策略接口；配置扩展在 internal/config 追加枚举与默认值。

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
None	—	—

Phase 0: Outline & Research

Unknowns / Research Tasks

Acquire-By-Hash 处理策略：是否需要额外校验逻辑 → 选择透传路径并依赖上游校验。
Alpine APKINDEX 签名校验需求 → 方案为透传签名文件，保持客户端校验。

Research Output

/home/rogee/Projects/any-hub/specs/007-apt-apk-cache/research.md

Phase 1: Design & Contracts

Artifacts

/home/rogee/Projects/any-hub/specs/007-apt-apk-cache/data-model.md
/home/rogee/Projects/any-hub/specs/007-apt-apk-cache/contracts/proxy-paths.md
/home/rogee/Projects/any-hub/specs/007-apt-apk-cache/quickstart.md
Agent context updated via .specify/scripts/bash/update-agent-context.sh codex

Design Focus

定义 APT/APK 路径匹配与缓存策略（索引再验证、包体直接缓存）。
Acquire-By-Hash/签名文件透传，避免破坏校验。
示例配置与测试入口（httptest 上游 + 临时缓存目录）。

Phase 2: Task Breakdown (deferred to /speckit.tasks)

基于用户故事和设计生成 tasks.md（后续命令）

4.8 KiB Raw Blame History Unescape Escape