Implementation Plan: Hub 配置凭证字段

Branch: 003-hub-auth-fields | Date: 2025-11-14 | Spec: /home/rogee/Projects/any-hub/specs/003-hub-auth-fields/spec.md Input: Feature specification from /specs/003-hub-auth-fields/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

交付单端口 Host 路由代理的配置增强：

将监听端口提升到全局 ListenPort 字段，所有 Hub 共享同一 Fiber 端口并严格依赖 Host 头；旧的 [[Hub]].Port 需在配置校验阶段报错并提供迁移指引。
为 Hub 添加可选 Username/Password 字段，由 CLI 在回源时自动注入 Authorization header，同时在日志中只暴露掩码。
为 Hub 添加必填 Type 枚举（当前支持 docker/npm/go），驱动日志字段与未来协议特定策略，并保留扩展钩子。
更新示例配置、quickstart、文档与测试，确保凭证/类型/单端口行为可独立验证。

Technical Context

Language/Version: Go 1.25+（静态链接单二进制）
Primary Dependencies: Fiber v3（HTTP 服务）、Viper（配置加载/校验）、Logrus + Lumberjack（结构化日志 & 滚动）、标准库 net/http/io（代理回源）
Storage: 本地 StoragePath/<Hub>/<path> + .meta 元数据缓存布局
Testing: GOCACHE=/tmp/go-build go test ./...，基于 httptest + upstream stub + 临时目录验证配置、代理、缓存、Host 路由
Target Platform: Linux/Unix CLI 进程，由 systemd/supervisor 管理，匿名下游客户端
Project Type: 单 Go 模块（cmd/any-hub 入口 + internal/config|server|cache|proxy）
Performance Goals: 回源路径仍需流式复制并保持单请求 <256MB；凭证注入不可降低缓存命中率；单端口模式吞吐与现状持平
Constraints: 禁止新增依赖；所有行为受单一 config.toml 控制；凭证不得写入日志；需提供向后兼容的迁移提示
Scale/Scope: 当前支持 docker/npm/go 三类仓库，未来可扩展 apt/yum/composer/go proxy 等；单端口 Host 路由需支撑数十 Hub 并保持透明体验

Constitution Check

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

方案继续服务“轻量 CLI 多仓代理”使命，未引入 UI/账号体系或附加系统。
仍使用 Go + Fiber/Viper/Logrus/Lumberjack/标准库，无新增依赖。
所有新增能力均由 config.toml 驱动，且设计了默认值/校验/迁移提示。
缓存优先 + 流式回源路径保持不变；凭证注入仅影响上游请求头。
计划列出了配置解析、代理凭证、Host 路由等必备测试，并要求中文注释与 quickstart 更新。

Project Structure

Documentation (this feature)

specs/003-hub-auth-fields/
├── 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 schema + 校验 + 默认值
internal/server/           # Host Registry、Fiber 启动
internal/cache/            # 缓存方案（需保持兼容）
internal/proxy/            # 凭证注入、类型策略、流式代理
configs/                   # 示例 config（docker/npm/go）
tests/                     # 单元/集成测试 (httptest、stubs)

Structure Decision: 延续既有模块划分；单端口逻辑集中在 internal/server，凭证/类型侧重 internal/config + internal/proxy，必要时可新增 internal/server/types 等子包但需保持依赖有向无环。

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	—	—

4.1 KiB Raw Permalink Blame History Unescape Escape