init

specs/001-config-bootstrap/quickstart.md

@@ -0,0 +1,40 @@
+# Quickstart: 配置与骨架
+
+## 前置条件
+- 已安装 Go 1.25+，并能运行 `go test ./...`。
+- 提供一份最小 `config.toml`，包含全局设置与至少一个 `[[Hub]]`。
+- 当前分支：`001-config-bootstrap`。
+
+## 步骤
+1. **编写配置文件**
+   - 复制 `config.example.toml`（若无则创建）到项目根目录 `config.toml`。
+   - 填写必填字段：`StoragePath`、`[[Hub]]` 的 `Name/Domain/Port/Upstream`。
+2. **运行配置校验**
+   - 执行 `go run ./cmd/any-hub --check-config --config ./config.toml`。
+   - 观察输出：成功时显示“配置验证通过”；失败时按日志提示修复字段。
+3. **启动 CLI**
+   - `go run ./cmd/any-hub --config ./config.toml`。
+   - 启动日志会打印版本、配置路径、监听端口。
+4. **查看版本**
+   - `go run ./cmd/any-hub --version`。
+   - 确认输出如 `any-hub version 0.1.0 (commit abc1234)`。
+5. **检查日志**
+   - 若配置写入文件：查看 `LogFilePath` 位置的滚动日志。
+   - 默认 stdout：在终端确认日志字段（level, action, hub, domain, result）。
+
+## 验证清单
+- [ ] `--check-config` 能阻断非法配置并返回非零退出码。
+- [ ] CLI 成功读取默认或自定义配置路径。
+- [ ] `--version` 立即输出版本信息。
+- [ ] 日志初始化遵循配置的级别与输出。
+
+## 常见错误排查
+- 出现 `Hub[docker].Domain: Domain 不允许包含协议头`：检查 Hub 配置中是否误写 `http://` 前缀。
+- 出现 `Global.StoragePath: 不能为空`：确保 `config.toml` 中填写路径或使用默认值。
+- 若日志提示 `logger_fallback`，说明文件不可写，删除 `LogFilePath` 或放宽目录权限。
+
+## 日志字段说明
+- `action`: 表示当前操作（`check_config`、`startup` 等）。
+- `configPath`: 实际使用的配置文件路径，方便验证 flag/环境变量生效。
+- `result`: 操作结果（`ok`、`error`）。
+- `hub` / `domain` / `cacheHit`: 由 `internal/logging.RequestFields` 提供，后续代理请求会自动填充。