53 lines
1.9 KiB
Markdown
53 lines
1.9 KiB
Markdown
# 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）。
|