70 lines
4.1 KiB
Markdown
70 lines
4.1 KiB
Markdown
# 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_ | — | — |
|