init

specs/002-fiber-single-proxy/quickstart.md

@@ -0,0 +1,52 @@
+# Quickstart: HTTP 服务与单仓代理
+
+## 前置条件
+- Go 1.25+，可运行 `go run` 与 `go test`。
+- 访问 Docker Hub 或准备本地 fake upstream（见 tests/integration）。
+- 端口 5000 可用。
+
+## 步骤
+1. **准备配置**
+   ```bash
+   cp configs/docker.sample.toml config.toml
+   ```
+   修改 `[[Hub]]` 中的 `Domain`(例如 `docker.hub.local`)，并确保 `/etc/hosts` 映射到 `127.0.0.1`。
+2. **启动代理**
+   ```bash
+   go run ./cmd/any-hub --config ./config.toml
+   ```
+   终端将打印 `action=startup` 日志。
+3. **发起请求并观察路由**
+   ```bash
+   curl -H "Host: docker.hub.local" http://127.0.0.1:5000/v2/
+   ```
+   响应中会包含 `X-Any-Hub-Upstream`、`X-Any-Hub-Cache-Hit: false` 与 `X-Request-ID`，日志记录 `action=proxy`、`hub=docker`、`upstream_status=200`。
+4. **验证 Host 未配置时的 404**
+   ```bash
+   curl -i -H "Host: unknown.hub.local" http://127.0.0.1:5000/v2/
+   ```
+   代理会返回 `404 {"error":"host_unmapped"}`，日志显示 `action=host_lookup`。
+5. **切换 NPM 示例**
+   ```bash
+   cp configs/npm.sample.toml config.toml
+   npm config set registry http://127.0.0.1:5000 --global
+   npm view lodash --registry http://127.0.0.1:5000 --fetch-timeout=60000
+   ```
+6. **运行路由集成测试**
+   ```bash
+   go test ./tests/integration -run HostRouting -v
+   ```
+7. **使用示例配置快速体验**
+   ```bash
+   # Docker Hub 示例
+   ./scripts/demo-proxy.sh docker
+
+   # NPM 示例 (监听 5001)
+   ./scripts/demo-proxy.sh npm
+   ```
+   脚本会直接引用 `configs/docker.sample.toml` / `configs/npm.sample.toml` 并启动代理，确保对应域名已指向本机。
+
+## 故障排查
+- `host_unmapped`: 检查 Host 头与 `config.toml` 中 Domain 是否一致。
+- `cache_write_failed`: 确认 `StoragePath` 可写，并有足够磁盘空间。
+- 上游 401/403: 公共仓库可能需要额外匿名访问 header；可在配置中新增自定义 header（future work）。