四级渐进学习法 · 网关与 headless · 第 3/9 篇

入口的学问：三岔口怎么选。

日志过了 mTLS 那一关，下一个问题是指给谁：同一个 audit-gateway，K8s 里有三种 Service——headless、ClusterIP、还有那个叫 multi 的陷阱。四级台阶讲清一件事：TLS 在边缘终止，负载均衡要到每个 Pod。

envoy ×2 · 30015 gRPC+mTLS audit-gateway ×3 · headless :8285 30016 调试 · 30017 HTTP 9901 Admin 看上游健康
THE FRAMEWORK

先看地图，再出发THE FRAMEWORK — 链路的第二、三跳

全链路七跳，本页覆盖接入两跳：终端 Agent → envoy mTLS（本页）→ audit-gateway（本页）→ Kafka → Flink ETL → std topic → StarRocks。envoy 是大门，gateway 是收发室，两个都不许有单点。

L1

受控语言

二十八句确定性短句，分四组：入口与端口、TLS 终止与转发、三种 Service、副本与高可用。

例：「envoy 的 gRPC 上游必须是 headless。」
L2

结构图

三张图：envoy→headless→3 Pod 链路（可点击）、三种 Service 对比表、per-Pod 健康检查时序。

例：对比表里 multi 那一行标红。
L3

交互网页

上游选择台：分别选 headless / ClusterIP / multi，看 DNS 返回、envoy 视角、健康检查能力、结论四栏联动。加六题自测与排障三连。

例：选 multi，看 DNS 返回什么。
L4

定制视频

六镜头：入口三扇门 → 边缘终止 → DNS 魔法 → 逐 Pod 把脉 → multi 陷阱 → 无单点收尾。成片已交付 · 01:33。

例：一支片子讲完「指给谁」这个决定。

本页名片（一分钟版）

主角：envoy-gateway（Deployment ×2）与 audit-gateway（Deployment ×3）
一句话：TLS 在边缘终止，负载均衡到每个 Pod。
三个数字：30015 正式入口 · 3 个 Pod IP · 1 个失效 endpoint（multi）。
解决两件事：不可信网络的身份验证（mTLS）· 上游无单点（headless + 健康检查）。

Clasp-Audit-CA证书三年 · CA 十年Admin :9901

一句话主线（背下来，全页都在展开它）

Agent(gRPC+mTLS) → envoy :30015 ×2（TLS 终止）→ 查 headless DNS → 3 × PodIP:8285 → 逐 Pod LB + 健康检查 → audit-gateway ×3（校验 token/租户）→ Kafka

L1 CONTROLLED LANGUAGE

受控语言：二十八句讲清入口简短、确定、一词一义——不靠形容词，只靠事实

以下每句话都来自交接材料（部署手册、envoy 配置、设计方案 v5）。读不懂的句子，去 L2 找对应的结构图。

入口与端口

§ 1 · 7 句

TLS 终止与转发

§ 2 · 6 句

三种 Service

§ 3 · 9 句

副本与高可用

§ 4 · 6 句
L2 DIAGRAMS

结构图：入口的真实骨架图 1 可点击组件 · 图 2 是本页最重要的对比表

三张图：先看 envoy 到 3 个 Pod 的完整链路，再把三种 Service 摆上同一张表对比，最后看健康检查怎么剔除坏 Pod。

终端 Agent ×N gRPC + mTLS :30015 envoy-gateway ×2 TLS 终点 · 双向认证 30015 / 30016 / 30017 Admin :9901 Clasp-Audit-CA 签发 audit-gateway-headless ClusterIP=None · :8285 Pod-1 · 10.42.1.17:8285 token/租户校验 → Kafka Pod-2 · 10.42.2.31:8285 同构副本 · 互不依赖 Pod-3 · 10.42.3.8:8285 加副本即扩容 audit-gateway :80 ClusterIP · HTTP 上游专用 audit-gateway-multi 无 selector · 1 失效 endpoint 禁止用作上游 mTLS DNS 查询 返回 3 个 Pod IP TLS 在 envoy 终止 → 明文 gRPC → headless DNS → 逐 Pod LB + 健康检查 → Kafka
图 1 · envoy → headless → 3 Pod 完整链路（点击组件查看职责与陷阱）
点击图中的组件（envoy / headless / Pod / ClusterIP / multi…），这里显示它的职责。
对比项 headlessaudit-gateway-headless :8285 ClusterIPaudit-gateway :80 multi（陷阱）audit-gateway-multi selector 有 · 自动挂 3 个 Pod副本变化自动跟随 有 · 自动挂 3 个 Pod经 kube-proxy 代理 无 selector不会自动挂任何 Pod endpoints 3 × PodIP:8285get endpoints 可验证 1 × VIP（代理入口）Pod 藏在代理后面 1 个 · 已失效指向空地址 DNS 返回 3 条 A 记录（Pod IP）envoy 直连每个 Pod 1 个 VIP连接先到代理层 解析正常但无可用后端流量进了死胡同 用作 gRPC 上游 ✅ 正解（per-Pod LB + 健康检查） ⚠️ 仅 HTTP 上游可用 ❌ 禁止
图 2 · 三种 Service 对比：selector、endpoints、DNS、用途
envoy 主动健康检查 Pod-1健康 ✓ 在轮转列表 Pod-2检查失败 ✗ 被剔除 Pod-3健康 ✓ 在轮转列表 Admin :9901/clusters 看到 audit-gateway-headless::8285 ├─ 10.42.1.17:8285 healthy ├─ 10.42.2.31:8285 ✗ removed └─ 10.42.3.8:8285 healthy Pod-2 恢复后自动加回轮转列表
图 3 · per-Pod 健康检查：坏 Pod 剔除、恢复加回，全在 envoy 内完成
L3 INTERACTIVE

交互探索：上游选择台选一种 Service，看 envoy 眼里的世界

同一个 audit-gateway，三种 Service 形态给 envoy 的世界完全不同。分别点选，看 DNS 返回什么、envoy 能做什么健康检查、最终结论是什么。玩完做六题自测。

3a · 上游选择台

三选一 · 四栏联动
✅ 正解：gRPC 上游唯一选择——逐 Pod 负载均衡 + 主动健康检查。

3b · 概念自测

6 题 · 单选

已答 0 / 6 · 正确 0 · 正确率 0%

1. Agent 的正式上报入口是？

30015 是双向认证正式入口；30016 是无需证书的调试口；30017 才是 HTTP over mTLS；30018 是 audit-agent 的 HTTP 对外端口，不经 envoy。

2. envoy 的 gRPC 上游应该指向哪个 Service？

headless 的 DNS 直接返回 3 个 Pod IP，envoy 才能逐 Pod 负载均衡并做健康检查。

3. audit-gateway-multi 为什么禁止用作上游？

无 selector 意味着不会自动挂 Pod，仅有的 endpoint 已失效——配成上游等于把流量引进死胡同。

4. ClusterIP Service 用作 gRPC 上游的局限是？

kube-proxy 代理后 envoy 只见 VIP，Pod 挂了它不知道；headless 让 envoy 直连每个 Pod，坏 Pod 自己剔。

5. 上游健康状态在哪里观察？

健康检查是 envoy 做的，结果当然在 envoy 的 Admin 页看：3 个上游全部 healthy 才算接入就绪。

6. 30016 调试口的正确用法是？

30016（容器 8286）是排障用的明文链路：grpcurl -plaintext 直连即可验证 gateway 本身是否正常，绕开证书因素。

3c · 排障三连（实战参考）

来自部署手册

① endpoints 对不对

get endpoints audit-gateway-headless 必须返回 3 个 Pod IP:8285。返回 0 个 = Service/标签配错。

② 上游健不健康

envoy Admin :9901/clusters 看 3 个上游是否全 healthy；有 removed 说明健康检查在剔除坏 Pod。

③ 握手通不通

openssl s_client 带 client 证书连 30015，看到 Verify return code: 0 (ok) 即 mTLS 链路通。

L4 VIDEO

定制视频：指给谁六镜头 · 成片已交付 · 01:33· 分镜与解说骨架已备

六镜头讲完「指给谁」这个决定：三扇门、边缘终止、DNS 魔法、逐 Pod 把脉、multi 陷阱、无单点收尾。画面里的端口、副本数、endpoint 状态与 L1–L3 同源。

成片 · topic-03-gateway.mp4　✓ 已交付

00:00 开场 · 三扇门 00:15 边缘终止 · TLS 换吞吐 00:31 headless · DNS 直返 Pod 00:47 headless Service 01:03 multi（陷阱） 01:18 健康检查 · 逐 Pod 把脉

规格：1920×1080 · 30fps · 01:33 · H.264 + AAC · 中文配音（zh-CN-Yunxi 逐句合成，每句实测时长均落在自己的字幕窗口内）+ 画面内嵌字幕。底部常驻进度轨随镜头推进点亮。

分镜脚本

6 镜头 · 旁白即片中字幕

镜头 1 · 入口三扇门

画面：envoy 城堡三扇门亮起——30015 重锁（mTLS）、30016 敞门（调试）、30017 中锁（HTTP）。
旁白：所有终端要进的，是 30015 这扇门。门上两把锁：你的证书，和我的证书。

镜头 2 · TLS 在边缘终止

画面：加密隧道抵达城堡即拆开，城内道路全部明文，证书卡片留在门房。
旁白：密文只走不可信的路。过了门，内网明文换吞吐；要换证书，只动这一处门房。

镜头 3 · headless 的 DNS 魔法

画面：envoy 问 DNS，返回的不是 VIP 而是三张 Pod 名片，虚线直连三个房间。
旁白：headless 不设总机。DNS 报出三个真名，envoy 一个个直连——这才叫认识每个 Pod。

镜头 4 · 逐 Pod 把脉

画面：envoy 给三个 Pod 依次号脉，Pod-2 变灰被移出圆桌，恢复后又被请回。
旁白：认识，就要负责。健康检查逐个把脉，病了移出，好了请回——九千一百端口上看得一清二楚。

镜头 5 · multi 陷阱

画面：multi 门牌金光闪闪，推门是一条断头路，路牌写「无 selector · 1 失效 endpoint」。
旁白：名字最像的那个，恰恰是陷阱。指给 multi，流量就进了死胡同——部署手册把它标成禁地。

镜头 6 · 收尾：无单点

画面：两座城门、三个房间全景图，任意一个熄灭，路线自动改道，日志流不断。
旁白：两扇门、三个房间，谁坏了都有人顶上。这就是入口的设计：验证身份，然后，永不单点。

解说骨架：六个设计决定

镜头 2–5 的旁白依据

① 边缘终止 TLS

证书集中管理，内网明文换吞吐，轮换只动边缘。

② headless 上游

per-Pod 负载均衡 + 主动健康检查，ClusterIP 做不到。

③ per-Pod 健康检查

坏 Pod 剔除、恢复加回，全部 envoy 内完成。

④ ×2 与 ×3

接入层与解析层独立扩缩，各自无单点。

⑤ multi 前车之鉴

无 selector + 失效 endpoint = 指向空地址。

⑥ 端口各司其职

上报 30015、调试 30016、HTTP 30017，永不混用。