init

specs/003-hub-auth-fields/plan.md

@@ -0,0 +1,69 @@
+# 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](./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 路由代理的配置增强：
+1. 将监听端口提升到全局 `ListenPort` 字段，所有 Hub 共享同一 Fiber 端口并严格依赖 Host 头；旧的 `[[Hub]].Port` 需在配置校验阶段报错并提供迁移指引。
+2. 为 Hub 添加可选 `Username`/`Password` 字段，由 CLI 在回源时自动注入 Authorization header，同时在日志中只暴露掩码。
+3. 为 Hub 添加必填 `Type` 枚举（当前支持 docker/npm/go），驱动日志字段与未来协议特定策略，并保留扩展钩子。
+4. 更新示例配置、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)
+
+```text
+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)
+```text
+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_ | — | — |