unkey 的 kitchensink:一个纯 Go 标准库实现的平台功能探针 HTTP 服务
unkey 的 kitchensink:一个纯 Go 标准库实现的平台功能探针 HTTP 服务
kitchensink 是 unkey 仓库中一个刻意保持“最小化”的 Go 服务:它只依赖 Go 标准库,把平台各项能力(网关策略、部署路由、环境变量注入、请求头透传、日志采集等)各自封装成独立子包,每个子包就是一个端到端的“探针(probe)”。本文将以 svc/kitchensink/README.md 为主线,结合 main.go 及全部探针子包的源码实现,完整讲解它的设计约束、路由清单、配置方式、扩展方法、运行方式,以及每个探针背后真正验证的平台能力。读完本文,你将掌握如何运行、探测和扩展这个服务,也能理解它如何被当作 unkey 平台各类网关与部署特性的“活文档”。
kitchensink 是什么:探针即示例
Stdlib-only HTTP server. Each probe lives in its own subpackage and demonstrates one platform feature end-to-end — gateway policies, deployment routing, env injection, header propagation, and so on.
kitchensink 是一个仅使用 Go 标准库的 HTTP 服务器。它的核心理念是:每个探针(probe)独立成包,端到端演示一项平台能力——网关策略(gateway policies)、部署路由(deployment routing)、环境变量注入(env injection)、请求头透传(header propagation)等。
这些探针同时承担“可运行的工作示例(worked example)”角色:工程师阅读任意一个子包,就能获得一份完整、可直接复制粘贴的集成示例,了解如何接入对应能力,而无需在仓库里追着 import 到处跑。换句话说,kitchensink 的代码本身就是写给平台用户的教程。
这个定位在入口文件的注释里同样明确——main.go 开头写道:Command kitchensink runs a stdlib-only HTTP server that exposes every probe subpackage as a real HTTP endpoint.(kitchensink 命令运行一个纯标准库 HTTP 服务器,把每个探针子包暴露为真实 HTTP 端点)。
三条硬性约束:标准库、无状态、小而精
README 为 kitchensink 定义了三条不可逾越的约束,这也决定了它的代码风格与架构边界:
- 仅用 Go 标准库(Go standard library only)。不允许任何第三方依赖。唯一被允许的本地 import 是
internal/httpx,用于平凡的响应拼装(例如httpx.JSON),它被放在internal/目录下,从而保持在“工作示例”的展示面之外。同时探针之间不允许互相 import(No cross-probe imports)。 - 无状态(Stateless)。不使用数据库、不使用缓存、不存活过单个请求的 goroutine。每个 handler 都是“请求的纯函数”。
- 小(Small)。如果一个探针膨胀到约 50 行以上,它大概率应该被拆成独立服务,而不是继续塞在 kitchensink 的某个角落。
这三条约束在代码中体现得相当彻底。以 internal/httpx 为例,httpx.go 的包注释明确解释了它存在的意义:让每个探针的 handler 专注于自己演示的能力——一次辅助调用胜过四行响应头拼装;同时放在 internal/ 下,让读者看到的探针代码是“标准库调用 + 一个很小的本地 import”,而不是一层庞大的工具库。
httpx 目前只提供唯一一个函数:
// JSON writes v as indented JSON with the given status code and the
// application/json Content-Type.
func JSON(w http.ResponseWriter, status int, v any) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
enc := json.NewEncoder(w)
enc.SetIndent("", " ")
_ = enc.Encode(v)
}
它负责“以指定状态码写出带缩进的 JSON,并设置 application/json 的 Content-Type”——这是绝大多数探针的公共响应方式。
配置:只有环境变量,没有 CLI 标志
kitchensink 只通过环境变量配置,不提供任何 CLI 标志。README 对此的解释是:部署(Deployments)负责注入环境变量,而这正是 kitchensink 存在要验证的契约(contract)——如果环境变量注入链路出了问题,这个服务第一时间就能暴露出来。
目前唯一的配置项是:
| 环境变量 | 作用 | 默认值 |
|---|---|---|
PORT |
监听端口 | 8080 |
这一点在 main.go 中体现为很直接的三行逻辑:
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
addr := ":" + port
目录布局与完整路由清单
README 给出的目录布局与探针清单如下:
svc/kitchensink/
├── main.go — wires method+path → handler
├── hello/ — GET /hello, smoke test
├── env/ — GET /env, process environment
├── buildinfo/ — GET /buildinfo, value injected via -ldflags -X
├── principal/ — GET /principal, decodes X-Unkey-Principal
├── headers/ — GET /headers, echoes request headers
├── echo/ — POST /echo, echoes body verbatim
├── logs/ — POST /log, logs body at INFO
├── status/ — GET /status/{code}, returns arbitrary status
└── sleep/ — GET /sleep?d=<duration>, blocks before responding
结合源码,实际目录中还存在两个 README 布局里未展开的成员:index/(GET / 路由清单页)和 internal/httpx/(公共响应辅助)。真实目录结构以 svc/kitchensink 下的文件为准。
所有路由在 main.go 的 routes 切片中集中注册,注册表本身就是一份“端点 → 用途”的对照表:
| 方法与路径 | 作用 | 对应子包 |
|---|---|---|
GET / |
列出全部已注册路由 | index |
GET /hello |
冒烟测试,返回 hello, world |
hello |
GET /env |
以 JSON 返回进程环境,可用 ?prefix= 过滤 |
env |
GET /buildinfo |
返回经 -ldflags -X 注入的构建期版本号 |
buildinfo |
GET /principal |
解码 X-Unkey-Principal 头并返回 |
principal |
GET /headers |
以 JSON 回显收到的请求头 | headers |
POST /echo |
原样返回请求体 | echo |
POST /log |
以 INFO 级别记录请求体并回显 | logs |
GET /status/{code} |
返回任意指定 HTTP 状态码 | status |
GET /sleep |
按 ?d=<duration> 阻塞后响应,支持取消 |
sleep |
启动装配与优雅退出
main.go 展示了完整的启动流程,其中值得注意的工程细节包括:
- JSON 结构化日志:
slog.New(slog.NewJSONHandler(os.Stdout, nil))并slog.SetDefault,所有探针(如logs)通过全局slog记录日志,统一输出为 JSON 到 stdout,便于平台日志采集器(log aggregator)拾取。 - 路由注册即索引:
mux.HandleFunc(rt.Pattern, rt.Fn)的同时调用index.Register(rt.Pattern, rt.Description),把每个路由登记到GET /的自述页上。 - 超时保护:
http.Server设置了ReadHeaderTimeout: 10 * time.Second,防止慢速请求头攻击或僵尸连接拖垮服务。 - 优雅退出:监听
os.Interrupt与syscall.SIGTERM,收到信号后以 5 秒超时的srv.Shutdown(ctx)完成优雅下线,配合容器的停止流程。
自述页的实现:index 探针
index 是唯一需要知道“有哪些路由”的探针,因此它与其他探针不同:main.go 在启动时为每个路由调用一次 Register,再把 Handler 挂载到根路径。其实现见 index/handler.go:Register 用 strings.Cut(pattern, " ") 把形如 "GET /hello" 的 ServeMux 模式拆成方法与路径,Handler 则按路径排序后以纯文本渲染出带分隔线的清单页。
逐个探针深入:每个端点验证什么
下面结合每个子包的源码,说明各探针的具体行为,以及它在平台中对应的验证场景。
GET /hello —— 最小可用形态与冒烟测试
hello/handler.go 是整个仓库最简单的探针,也是“新增探针的参考形状”:一个常量 200 OK 响应,Content-Type 为 text/plain; charset=utf-8,正文是 hello, world\n。
// Handler writes "hello, world" as text/plain. Registered by main.go.
func Handler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/plain; charset=utf-8")
_, _ = w.Write([]byte("hello, world\n"))
}
它的定位是管道本身的冒烟测试(smoke test for the pipeline itself):如果请求能打到这个端点并拿到预期响应,说明从客户端、网关、路由到容器的整条链路是通的。
GET /env —— 验证部署环境变量注入
env/handler.go 把进程环境变量以 JSON 返回,并支持 ?prefix= 按键前缀过滤:
func Handler(w http.ResponseWriter, r *http.Request) {
prefix := r.URL.Query().Get("prefix")
out := map[string]string{}
for _, kv := range os.Environ() {
k, v, _ := strings.Cut(kv, "=")
if prefix != "" && !strings.HasPrefix(k, prefix) {
continue
}
out[k] = v
}
httpx.JSON(w, http.StatusOK, out)
}
它的用途是端到端验证部署环境变量注入(verifying deployment env injection works end-to-end):把服务部署上去后,curl localhost:8080/env?prefix=MYAPP_,就能确认平台注入的变量是否真的进入了进程环境。
GET /buildinfo —— 验证 -ldflags -X 构建期注入
buildinfo/handler.go 演示的是链接期变量注入这条管线契约:build-time variable → ldflags -X → package var,与 env 探针的“运行时环境 → os.Getenv”形成鲜明对照。其核心是一个包级变量:
var Version = "unset"
"unset" 是兜底哨兵值:本地 go run 没有注入时,探针依然能正常响应。覆盖它的命令是:
go build -ldflags "-X 'github.com/unkeyed/unkey/svc/kitchensink/buildinfo.Version=<value>'"
handler 则把该值以 JSON 返回:{"version": ...}。
在 Dockerfile 中可以看到这条管线在真实构建中的落地:构建阶段通过 Docker BuildKit 的 secret mount 把平台变量挂载到 /run/secrets/.env,if [ -f /run/secrets/.env ]; then set -a && . /run/secrets/.env && set +a; fi 加载后,以 -ldflags "-X 'github.com/unkeyed/unkey/svc/kitchensink/buildinfo.Version=${VERSION:-unset}'" 注入版本号——-f 守卫保证本地无 secret 挂载时构建依然可用,${VERSION:-unset} 与源码中的哨兵值保持一致。
GET /principal —— 解码网关注入的鉴权主体
principal/handler.go 验证的是 frontline 网关在鉴权策略通过后设置的 X-Unkey-Principal 头。该头的常量与 svc/frontline/internal/policies.PrincipalHeader 保持一致(注释说明为保持 kitchensink 纯标准库、避免跨服务 import 而在此复制一份)。
行为分三种情况:
- 头不存在(即绕过 frontline 直连本端点):返回
401 Unauthorized,提示“需要带鉴权策略经由 frontline 访问本端点”; - 头存在但 JSON 解析失败(frontline 传来了垃圾数据):返回
502 Bad Gateway——这是“网关的错,不是调用方的错”; - 头合法:解析为 JSON 后原样返回。
raw := r.Header.Get(header)
if raw == "" {
http.Error(w, header+" header not set; reach this endpoint through frontline with an auth policy", http.StatusUnauthorized)
return
}
var p map[string]any
if err := json.Unmarshal([]byte(raw), &p); err != nil {
http.Error(w, "invalid principal JSON from frontline: "+err.Error(), http.StatusBadGateway)
return
}
httpx.JSON(w, http.StatusOK, p)
GET /headers —— 回显请求头,验证头透传
headers/handler.go 把收到的请求头整体以 JSON 返回:
func Handler(w http.ResponseWriter, r *http.Request) {
httpx.JSON(w, http.StatusOK, r.Header)
}
它的价值在于调试请求头经过 frontline、负载均衡器或任何中间代理后的透传情况(debugging header propagation):端到端请求后检查响应里的头集合,即可确认自定义头、认证头是否被正确保留或改写。
POST /echo —— 验证请求体不被改写
echo/handler.go 原样返回请求体,并尽量保留 Content-Type:
func Handler(w http.ResponseWriter, r *http.Request) {
if ct := r.Header.Get("Content-Type"); ct != "" {
w.Header().Set("Content-Type", ct)
}
_, _ = io.Copy(w, r.Body)
}
实现直接用 io.Copy 把 r.Body 流式拷贝到 w,不需要在内存里读完整请求体。它用于验证请求体透传与代理未静默改写 payload(proxies aren't silently rewriting payloads)。
POST /log —— 验证平台日志采集
logs/handler.go 读取请求体、以 INFO 级别记录到 stdout,并回显已记录的内容:
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "failed to read body: "+err.Error(), http.StatusBadRequest)
return
}
msg := string(body)
slog.Info("kitchensink/log", "body", msg)
httpx.JSON(w, http.StatusOK, map[string]string{"logged": msg})
其用途是验证平台日志采集器(log aggregator)能拾取应用日志:发送一条请求后,到平台日志侧确认 kitchensink/log 这条 INFO 日志是否如期出现。值得注意的是包名取 logs 而非 log,正是为了避免遮蔽调用方可能用到的标准库 log 包(见该文件包注释)。
GET /status/{code} —— 任意状态码,演练上游错误处理
status/handler.go 从路径参数解析状态码并原样返回:
code, err := strconv.Atoi(r.PathValue("code"))
if err != nil || code < 100 || code > 599 {
http.Error(w, "code must be a valid HTTP status (100-599)", http.StatusBadRequest)
return
}
http.Error(w, http.StatusText(code), code)
实现依赖 Go 1.22+ 的 http.ServeMux 路径通配符 {code} 与 r.PathValue。它的用途是演练 frontline 对上游错误(502、429 等)的处理,而不需要一个真的会失败的 upstream——比如 curl localhost:8080/status/503 即可随时制造一个 503 上游。
GET /sleep —— 阻塞响应,演练超时与慢上游
sleep/handler.go 按 ?d=<duration> 阻塞指定时长后返回 200:
dStr := r.URL.Query().Get("d")
if dStr == "" {
http.Error(w, "d query param required, e.g. /sleep?d=500ms", http.StatusBadRequest)
return
}
d, err := time.ParseDuration(dStr)
if err != nil || d < 0 {
http.Error(w, "d must be a valid duration (e.g. 500ms, 2s, 1m): "+dStr, http.StatusBadRequest)
return
}
select {
case <-time.After(d):
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte("slept " + d.String() + "\n"))
case <-r.Context().Done():
}
时长用 time.ParseDuration 解析("500ms"、"2s"、"1m30s" 等)。实现通过 select 同时监听定时器与 r.Context().Done(),尊重客户端取消,避免测试场景下泄漏 goroutine。它用于测试 frontline 的超时与慢上游行为(Frontline timeouts and slow-upstream behavior)。
新增一个探针:三步走
README 给出了新增探针的标准流程,结合源码可以展开为:
第 1 步:创建子包与 handler。 在 svc/kitchensink/<name>/handler.go 中实现行为。
第 2 步:导出标准签名。 写出 func Handler(w http.ResponseWriter, r *http.Request)。hello/handler.go 是最小可用形态的模板——只依赖 net/http,不引入任何框架。
第 3 步:注册路由。 在 main.go 的 routes 切片中追加一行:
"GET /<name>": <name>.Handler,
注册键使用 Go 1.22+ 的 http.ServeMux 模式语法:GET /foo、POST /bar/{id} 等,且方法 + 路径与 handler 一一对应。注册时 main.go 会自动完成三件事:挂载 handler、写入 index 自述页、打印一条 registered INFO 日志。
值得注意的是,README 中的注册示例("GET /<name>": <name>.Handler)是简化写法,实际代码中 routes 是包含 Pattern、Description、Fn 三个字段的结构体切片,因此真实新增时需要同时提供路径模式、人类可读描述与 handler 三者,例如:
{"GET /hello", "Smoke test — returns 'hello, world'.", hello.Handler},
运行方式:本机、自定义端口与 Docker
README 给出了三种运行方式,均可直接套用。
方式一:直接以 Go 运行(默认端口 8080):
go run ./svc/kitchensink
方式二:自定义端口(通过 PORT 环境变量覆盖):
PORT=9090 go run ./svc/kitchensink
方式三:Docker 构建运行。注意构建上下文是仓库根目录,而不是 kitchensink 所在目录——因为二进制属于主 Go module(需要根目录的 go.mod 参与构建):
docker build -f svc/kitchensink/Dockerfile -t kitchensink .
docker run --rm -p 8080:8080 kitchensink
Dockerfile 的实现细节也值得注意:多阶段构建,builder 阶段基于 golang:1.25-alpine,先单独拷贝 go.mod/go.sum 并 go mod download 以利用层缓存;运行阶段基于 gcr.io/distroless/static-debian13:nonroot 以非 root 用户运行;镜像内 ENV PORT=8080 并 EXPOSE 8080,ENTRYPOINT 直接执行二进制。构建时还通过 BuildKit secret 挂载 .env 来注入 VERSION(见上文 buildinfo 探针)。
方式四:本地构建二进制(如需注入版本号):
go build -ldflags "-X 'github.com/unkeyed/unkey/svc/kitchensink/buildinfo.Version=v1.0.0'" -o kitchensink ./svc/kitchensink
启动后,可以直接用 README 给出的三连探测验证服务健康:
curl localhost:8080/hello
curl localhost:8080/env
curl localhost:8080/status/503
另外还可以:
curl localhost:8080/查看全部已注册路由的自述清单;curl -X POST localhost:8080/echo -d '{"foo":"bar"}' -H 'Content-Type: application/json'验证请求体回显;curl 'localhost:8080/sleep?d=2s'制造一次 2 秒的慢响应;curl -X POST localhost:8080/log -d 'hello logs'触发一条 INFO 日志;curl -H 'X-Unkey-Principal: {"sub":"user_123"}' localhost:8080/principal模拟网关注入的鉴权主体(无该头则返回 401)。
小结:kitchensink 在 unkey 中的角色
从仓库结构看,unkey 的 svc/ 下并列着 api、ctrl、frontline、heimdall、krane、logdrain、vault 等生产服务,而 kitchensink 刻意保持了极简:它是验证平台特性的“测试插头”,同时也是面向集成者的“活文档”。每一个探针都用标准库写成一个最小可用的端到端示例,让工程师不必在大量业务代码中摸索,就能确认网关策略、部署路由、环境变量注入、请求头透传、日志采集、超时处理等能力是否按预期工作。
如果你想深入某个能力背后的实现,可以从这些路径继续阅读:网关侧的 X-Unkey-Principal 注入逻辑见 svc/frontline 下的 policies 相关代码,平台日志采集链路见 svc/logdrain,而 kitchensink 自身的全部探针源码则集中在 svc/kitchensink 目录下,可作为新增探针或集成对接的第一手参考。