Pod 终端与日志:为什么浏览器建连要先换一张 60 秒的票

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")
}

三个细节:

  1. 读和删在同一个锁内,所以两张并发的 WebSocket 不可能用同一张票;
  2. 集群、命名空间、Pod 必须与票据完全一致,改一个参数都拿不到会话------票据不能成为"任意 Pod 的通行证";
  3. 错误统一是 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 日志"。

七、几个真实的坑

  1. 终端要能被统一回收。 track 把每个 shell 记进 map,并包装 Stop 先摘除再关闭,避免 CloseAll 与 HTTP 处理的 defer 重复关闭同一会话。
  2. 目标名有长度上限。 命名空间、Pod、容器名都限制 253 字符,窗口大小上限 1000,和 proto 校验保持一致------HTTP 之外还有 gRPC 和内部调用,不能只靠前端。
  3. 集群错误不回显细节。 建连失败时按 kratos 错误码返回状态,但响应体只有 pod exec unavailable,不把集群地址或凭据问题带出去。
  4. 票据失败不补发。 建连失败后必须重新申请票据,不会在服务端偷偷续一张------否则"一次性"就名不副实了。

八、怎么验证

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 出站连接,而不是控制面回拨。

相关推荐
一条Go14 分钟前
开源新生代雷达 · 第 14 期
github
考虑考虑1 小时前
zookeeper认证
后端·zookeeper
真上帝的左手2 小时前
26. AI-大语言模型-基础
人工智能·ai·架构·llm·大语言模型
掘金者阿豪2 小时前
数据库选型到底应该看什么?从业务需求到技术架构的实践分析
前端·后端
挖掘狂人2 小时前
ThreadLocal 会内存泄露吗?
java·安全·架构
苍何2 小时前
豆包终于想通了...
后端
AAA修煤气灶刘哥3 小时前
Agent 都能干活了,软件还需要那么多按钮吗?
人工智能·后端·架构
未秃头的程序猿3 小时前
给新模块加了个 @MapperScan,启动崩了,最后发现跟 MapperScan 没关系
java·后端·mybatis
苍何3 小时前
不用 Opus5.5 ,即梦也能出爆款 vibe 视频了
后端