Pod 终端与日志:为什么浏览器建连要先换一张 60 秒的票
Alioth 技术笔记 · 第 15 篇 · Kubernetes 控制台 / 实时通道 仓库:github.com/aide-family... | 在线演示:web.alioth.asia/
导语
做 Web 终端的人都会撞上同一堵墙:浏览器的 WebSocket 不能自定义 Authorization 头。要么把 JWT 塞进查询参数,要么先换一张短命票据。前者会出现在访问日志、浏览器历史和网关日志里,而且一旦泄露就能长期重放;后者只多一次 HTTP 往返。Alioth 选了票据,有效期 60 秒、只能用一次、绑定到具体的 Pod 和容器。这篇讲票据模型、协议细节,以及为什么"日志"和"终端"必须是两个权限。
一、票据在签发时把该校验的都校验完
go
// IssueTicket 签发 60 秒内有效的一次性票据。权限和租户归属都在这里校验,
// 消费票据时不再重复校验:浏览器 WebSocket 无法带 Authorization 头,票据就是建连凭证。
func (terminal *Terminal) IssueTicket(ctx context.Context, clusterUID, namespace, name, container string, cols, rows int32) (string, error) {
ns, err := terminal.access.Allow(ctx, perm.K8sPodExec)
if err != nil { return "", err }
clusterUID, namespace, name, container, err = normalizePodExecTarget(clusterUID, namespace, name, container)
if err != nil { return "", err }
// 跨租户按不存在处理:集群不属于当前租户时签不出任何票据。
if _, err := terminal.clusters.GetCluster(ctx, ns, clusterUID); err != nil {
return "", terminal.access.Wrap(err)
}
return terminal.issueTicket(clusterUID, namespace, name, container, cols, rows), nil
}
票据里存的不只是 UID,而是完整目标 :集群、命名空间、Pod、容器和窗口大小(cols/rows)。窗口大小也绑进来,是因为浏览器建连后只发 resize 帧,不再传尺寸------把初始尺寸放在票据里,握手阶段就不需要额外状态。
票据是内存 map,签的时候顺手清过期项,CloseAll 之外不需要任何后台任务:
go
// 顺手清掉过期票据,避免长期运行的进程里票据表只增不减。
for key, item := range terminal.tickets {
if now.After(item.expires) { delete(terminal.tickets, key) }
}
二、消费:取走即删,目标必须一致
go
terminal.mu.Lock()
item, ok := terminal.tickets[ticket]
if ok { delete(terminal.tickets, ticket) } // 取走即删除,重复使用走到 not found
terminal.mu.Unlock()
if !ok || time.Now().After(item.expires) {
return podExecTicket{}, merr.Unauthenticated("invalid ticket")
}
if item.clusterUID != clusterUID || item.namespace != namespace || item.name != name {
return podExecTicket{}, merr.Unauthenticated("invalid ticket")
}
三个细节:
- 读和删在同一个锁内,所以两张并发的 WebSocket 不可能用同一张票;
- 集群、命名空间、Pod 必须与票据完全一致,改一个参数都拿不到会话------票据不能成为"任意 Pod 的通行证";
- 错误统一是
invalid ticket,不区分"不存在 / 过期 / 目标不符"。区分它们等于告诉攻击者"这张票是真的,只是你用错了地方"。
容器名允许留空,此时用票据里绑定值;显式传了就必须一致。这是为了兼容浏览器只传 ticket 的最简形式,同时不放弃校验。
三、代价:60 秒内回收的权限仍然有效
权限只在签发时校验一次,意味着:用户在 10:00 被移出租户,10:00:30 之前签发的票据仍然能建连。Alioth 用 60 秒 TTL 把这个窗口压到可接受范围------票据不能续期,过时必须重新走一次带鉴权的 HTTP 请求。
这是一个明确的取舍:"实时通道的长连接"和"每次操作都重新鉴权"在 WebSocket 上不可兼得。要么在连接期间周期性鉴权(复杂且容易漏),要么把凭证的有效期压到足够短。选后者,是因为终端的会话生命周期本来就是分钟级,用户不会在意偶尔重连。
四、协议:二进制是内容,文本是控制
服务端和浏览器之间的约定只有三条:
- 二进制帧 = 终端的原始字节;
- 文本帧
{"type":"resize","cols":..,"rows":..}= 调整窗口; - 关闭前发
{"type":"exit","reason":".."}= 告诉前端为什么结束。
go
const podExecWriteTimeout = 10 * time.Second
func writePodExecFrame(conn *websocket.Conn, kind int, payload []byte) error {
_ = conn.SetWriteDeadline(time.Now().Add(podExecWriteTimeout))
return conn.WriteMessage(kind, payload)
}
每帧都设写超时 是这里最实用的细节:浏览器断网(拔网线、合盖休眠)时 TCP 不会立刻报错,如果写没有 deadline,处理器会一直阻塞在这个协程里,远端会话也跟着挂住。10 秒后写失败、连接关闭、shell.Stop() 执行,资源才真正释放。
另一个容易忽略的点是上下文的处理:
go
// 终端生命周期不受 HTTP 请求上下文约束:升级后的连接不再有请求 deadline,
// 关闭时机由 WebSocket 断开或 Terminal.CloseAll 决定。
context.WithoutCancel(r.Context())
如果直接传 r.Context(),那这个 context 里的值(租户、用户)会跟着连接活到结束,但它的取消信号也会在 HTTP 处理返回时触发------终端刚连上就被取消。WithoutCancel 保留值、去掉取消,正好是这里需要的语义。
五、前端为什么必须拼绝对地址
一个很隐蔽的坑:相对地址的 WebSocket 会被浏览器按当前页面解析。如果网关没有正确转发升级请求,请求会落到前端的 SPA fallback(返回 HTML),连接就永远 pending,既不成功也不失败。
ts
// 地址必须是绝对 ws/wss;相对地址会被浏览器按当前页面解析,
// 落到前端的 SPA fallback 上就会一直 pending(例如网关没有转发升级请求)。
if (!/^wss?:\/\//i.test(url)) {
settled = true
emitState({ state: "failed", message: "" })
return
}
所以构造地址的辅助函数是:
ts
const proto = window.location.protocol === "https:" ? "wss" : "ws"
return `${proto}://${window.location.host}${suffix}`
配合 10 秒连接超时(socketConnectTimeoutMs),失败会变成一个明确的"连接失败",而不是一个转圈到天荒地老的终端。
六、日志、终端、删除是三个权限
这是整个 Kubernetes 控制台里最重要的拆分:
| 操作 | 权限码 | 能力 |
|---|---|---|
| 看 Pod、容器、状态 | k8s:pod:read |
k8s_pod_read |
| 读容器日志尾部 | k8s:pod:logs |
k8s_pod_logs |
| 进容器开终端 | k8s:pod:exec |
k8s_pod_exec |
| 删 Pod | k8s:pod:delete |
k8s_pod_delete |
go
func (explorer *Explorer) PodLogs(...) {
if _, err := explorer.scope(ctx, clusterUID, perm.K8sPodLogs); err != nil { return nil, err }
...
}
为什么不能合成一个 k8s:pod?因为它们的风险等级完全不同:看日志是只读排障,进容器等于拿到该容器的 shell(可以读环境变量、访问 ServiceAccount Token、横向移动)。"只买只读集群"的租户如果因为要看日志而顺带获得了 exec 能力,这个授权模型就失效了。能力层(第 03 篇)也按操作拆开,所以商务上可以只卖"Pod 日志"。
七、几个真实的坑
- 终端要能被统一回收。
track把每个 shell 记进 map,并包装Stop先摘除再关闭,避免CloseAll与 HTTP 处理的defer重复关闭同一会话。 - 目标名有长度上限。 命名空间、Pod、容器名都限制 253 字符,窗口大小上限 1000,和 proto 校验保持一致------HTTP 之外还有 gRPC 和内部调用,不能只靠前端。
- 集群错误不回显细节。 建连失败时按 kratos 错误码返回状态,但响应体只有
pod exec unavailable,不把集群地址或凭据问题带出去。 - 票据失败不补发。 建连失败后必须重新申请票据,不会在服务端偷偷续一张------否则"一次性"就名不副实了。
八、怎么验证
app/alioth/internal/biz/cluster/shell_test.go 覆盖了票据签发、重复使用、目标不匹配、窗口大小归一化。手工验证:
bash
git clone https://github.com/aide-family/moon.git && cd moon
make dev-up
open http://127.0.0.1:8080
接入一个集群后打开某个 Pod 的终端,然后在浏览器开发者工具里复制那张 ticket,用 websocat 再连一次------应该得到 401。再把 URL 里的 Pod 名改掉重连,同样 401。最后只给账号 k8s:pod:logs 权限,尝试打开终端,应该停在"功能未开通",而日志抽屉仍能正常打开。
结语
Web 终端的正确性不取决于终端模拟器多好用,而取决于四个边界:凭证怎么来、票据能给谁用、连接什么时候必须死、以及它对应哪一个权限。Alioth 的答案是:60 秒一次性票据、目标全绑定、写超时 10 秒、日志与 exec 拆成两个权限。每一条都让体验稍微麻烦一点,但每一条都对应一个真实会被利用的缺口。
下一篇:边缘 Agent------为什么是 Agent 出站连接,而不是控制面回拨。