Kubeshark Kubernetes 部署指南

目标：在 Ubuntu 22.04 服务器上从零搭建 k3s 最小 Kubernetes 集群，并以两条路径（官方 CLI kubeshark tap 一键部署、Helm Chart 手工部署）完成 Kubeshark v53.6.0 的安装、Web UI 访问验证与完整卸载清理，含 kubeconfig 配置、特权容器排障与 L4 流量捕获验证的完整实测回显。已在 Ubuntu 22.04（内核 6.8.0-138-generic，12 核 / 32GiB 内存）+ k3s v1.34.1+k3s1 单节点集群实测通过（2026-10-23）。

一、环境信息

本文全部命令与回显来自以下实测环境：

操作系统：Ubuntu 22.04 LTS（内核 6.8.0-138-generic，x86_64）
硬件：12 核 CPU / 32GiB 内存（Kubeshark 默认资源 requests 极低，hub/worker/front 各 50Mi，但捕获运行期建议预留 2GiB 以上余量）
Kubernetes：k3s v1.34.1+k3s1（单节点，control-plane+etcd 合一，已裁剪 traefik/servicelb/metrics-server/local-storage）
Helm：v3.17.3
Kubeshark：v53.6.0（官方 CLI 二进制 + Helm Chart 53.6.0，镜像仓库 docker.io/kubeshark，镜像 tag v53.6）
demo 工作负载：nginx:1.27-alpine（服务端）+ curlimages/curl:8.11.1（客户端，每 3 秒请求一次，用于产生集群内 HTTP 流量）
实测日期：2026-10-23

二、前置条件

2.1 集群与内核要求

Kubeshark 的 Worker 以特权 DaemonSet 部署到集群每个节点，安装前需确认：

Kubernetes 版本 ≥ 1.16（Chart 元数据 kube-version: >= 1.16.0-0，helm 安装日志实测回显）；
节点内核需支持 AF_PACKET 抓包（任意 ≥2.6 内核均可）并挂载 /sys；若要启用 eBPF 追踪（TLS 解密、syscall 级归因），内核需挂载 debugfs/tracefs 并支持 kprobes（Ubuntu 22.04 默认内核满足）；
节点可访问外网拉取镜像（docker.io/kubeshark/hub、kubeshark/worker、kubeshark/front，tag 与版本对应，如 v53.6）；离线集群需自建镜像仓库并用 --set tap.docker.registry=<仓库> 指向；
社区版（Community，免费）限 3 节点 / 60 Pods，且要求集群能出公网完成 telemetry（详见 7.1 节）；
一个能访问集群 API 的 kubeconfig（k3s 默认在 /etc/rancher/k3s/k3s.yaml）。

2.2 k3s 最小集群准备（实测）

如果没有现成集群，用官方脚本安装 k3s 并裁剪掉本实验用不到的组件（每条命令单独执行）：

# 安装 k3s server，禁用 traefik/servicelb/metrics-server/local-storage 与网络策略（最小化）
curl -sfL https://get.k3s.io | sh -s - server \
  --disable=traefik --disable=servicelb --disable=metrics-server \
  --disable=local-storage --disable-network-policy \
  --write-kubeconfig-mode 644

等待约 30 秒后验证节点就绪（实测回显，节点名取自主机名）：

kubectl get nodes

NAME         STATUS   ROLES                AGE   VERSION
k3s-master   Ready    control-plane,etcd   48s   v1.34.1+k3s1

kubectl version 2>&1 | head -3

Client Version: v1.34.1+k3s1
Kustomize Version: v5.7.1
Server Version: v1.34.1+k3s1

k3s 安装器会自动把 kubeconfig 写入 /etc/rancher/k3s/k3s.yaml 并为 kubectl 建好符号链接，kubectl get nodes 返回 Ready 即集群可用。

三、版本选型说明

组件	实测版本	获取方式	说明
kubeshark CLI	v53.6.0	GitHub Releases 官方二进制	单文件静态链接，约 60MB（实测 62,206,136 字节），无运行时依赖
Helm Chart	53.6.0	helm.kubeshark.com 官方仓库	Chart 与二进制同号发布；`kubeshark tap` 内部也是拉取该 Chart
hub/worker/front 镜像	v53.6	docker.io/kubeshark	Chart 默认拉取，tag 由 `tap.docker.tag` 控制（默认留空=跟随 Chart）
k3s	v1.34.1+k3s1	get.k3s.io	任意 ≥1.16 的 K8s 发行版均可

版本查询命令：kubeshark version（二进制版本）；helm search repo kubeshark（Chart 最新版本）。Kubeshark 发版节奏快（2026-10-21 发布 v53.6.0），生产部署建议锁定具体版本号下载，不做 latest 漂移。

四、安装方案 A：kubeshark CLI 一键部署（官方推荐）

4.1 安装 kubeshark 二进制

官方 Releases 提供 linux/darwin/windows 的 amd64/arm64 四平台二进制，Linux x86-64 下载安装（实测约 10 秒完成）：

curl -Lo kubeshark https://github.com/kubeshark/kubeshark/releases/download/v53.6.0/kubeshark_linux_amd64 && chmod 755 kubeshark
sudo mv kubeshark /usr/local/bin/

校验完整性（实测 sha256）：

sha256sum /usr/local/bin/kubeshark

c805fe70335ea9f4d1da6e2fe061541dfd727baeede1075981da178d6c80b537  /usr/local/bin/kubeshark

验证可执行（实测回显）：

kubeshark version

v53.6.0

4.2 配置 kubeconfig（排障实录一）

kubeshark tap 需要读取 kubeconfig 才能连接集群。若当前用户找不到 kubeconfig，会直接报错退出（实测报错原文）：

2026-10-23T07:10:08Z ERR common.go:99 > error="error while using kube config (/.kube/config)\nyou can set alternative kube config file path by adding the kube-config-path field to the kubeshark config file, err:  stat /.kube/config: no such file or directory"

定位：kubeshark 按 $HOME/.kube/config（本例 HOME 为空时退到 /.kube/config）或 kube.configPath 配置查找凭据，而 k3s 的 kubeconfig 在 /etc/rancher/k3s/k3s.yaml，两者不一致。解决（任选其一，实测方案一）：

# 方案一：把 k3s kubeconfig 放到当前用户标准位置（root 用户为 /root/.kube/config）
mkdir -p ~/.kube && cp /etc/rancher/k3s/k3s.yaml ~/.kube/config

# 方案二：环境变量显式指定（对 CI/临时会话更干净）
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

修复后重跑 kubeshark tap，日志确认凭据加载成功（实测回显）：

2026-10-23T07:11:14Z INF common.go:70 > Using kubeconfig: path=/root/.kube/config

4.3 部署 demo 工作负载（产生被捕获的集群内流量）

Kubeshark 部署后需要集群内确有流量才能看到数据。部署一对 nginx 服务端 + curl 客户端产生每 3 秒一次的内部 HTTP 请求（实测命令与回显）：

kubectl create deployment demo-nginx --image=nginx:1.27-alpine --replicas=1

deployment.apps/demo-nginx created

kubectl expose deployment demo-nginx --port=80

service/demo-nginx exposed

kubectl create deployment demo-client --image=curlimages/curl:8.11.1 --replicas=1 -- /bin/sh -c "while true; do curl -s http://demo-nginx/ >/dev/null; sleep 3; done"

deployment.apps/demo-client created

等待镜像拉取完成后确认两个 Pod 均 Running（实测回显）：

kubectl get pods -o wide

NAME                           READY   STATUS    RESTARTS   AGE   IP          NODE         NOMINATED NODE   READINESS GATES
demo-client-6cb6666488-cbj6f   1/1     Running   0          2m1s   10.42.0.4   k3s-master   <none>           <none>
demo-nginx-57669875d8-chmsf    1/1     Running   0          2m1s   10.42.0.3   k3s-master   <none>           <none>

4.4 执行 kubeshark tap

tap 是官方 CLI 的核心部署命令，一条命令完成 Helm 安装、资源就绪等待与端口转发（实测回显逐行照抄）：

kubeshark tap

2026-10-23T07:11:14Z INF tapRunner.go:50 > Using Docker: registry=docker.io/kubeshark tag=
2026-10-23T07:11:14Z INF tapRunner.go:54 > Kubeshark will store the traffic up to a limit (per node). Oldest TCP/UDP streams will be removed once the limit is reached. limit=10Gi
2026-10-23T07:11:14Z INF versionCheck.go:24 > Checking for a newer version...
2026-10-23T07:11:14Z INF common.go:70 > Using kubeconfig: path=/root/.kube/config
2026-10-23T07:11:14Z INF tapRunner.go:70 > Telemetry enabled=true notice="Telemetry can be disabled by setting the flag: --telemetry-enabled=false"
2026-10-23T07:11:14Z INF tapRunner.go:72 > Targeting pods in: namespaces=["default","kube-node-lease","kube-public","kube-system"]
2026-10-23T07:11:14Z INF tapRunner.go:139 > Targeted pod: demo-client-6cb6666488-cbj6f
2026-10-23T07:11:14Z INF tapRunner.go:139 > Targeted pod: demo-nginx-57669875d8-chmsf
2026-10-23T07:11:14Z INF tapRunner.go:139 > Targeted pod: coredns-7896679cc-fz6vk
2026-10-23T07:11:14Z INF tapRunner.go:82 > Waiting for the creation of Kubeshark resources...
2026-10-23T07:11:16Z INF helm.go:132 > Downloading Helm chart: repo-path=/root/.cache/helm/repository url=https://github.com/kubeshark/kubeshark.github.io/releases/download/kubeshark-53.6.0/kubeshark-53.6.0.tgz
2026-10-23T07:11:16Z INF helm.go:151 > Installing using Helm: kube-version=">= 1.16.0-0" release=kubeshark source=["https://github.com/kubeshark/kubeshark/tree/master/helm-chart"] version=53.6.0
2026-10-23T07:11:16Z INF helm.go:62 > creating 21 resource(s)
2026-10-23T07:11:16Z INF tapRunner.go:99 > Installed the Helm release: kubeshark
2026-10-23T07:11:16Z INF tapRunner.go:180 > Added: pod=kubeshark-hub
2026-10-23T07:11:16Z INF tapRunner.go:276 > Added: pod=kubeshark-front
2026-10-23T07:11:28Z INF tapRunner.go:208 > Waiting for readiness... pod=kubeshark-hub
2026-10-23T07:11:34Z INF tapRunner.go:205 > Ready. pod=kubeshark-hub
2026-10-23T07:11:40Z INF tapRunner.go:303 > Waiting for readiness... pod=kubeshark-front
2026-10-23T07:11:42Z INF tapRunner.go:300 > Ready. pod=kubeshark-front
2026-10-23T07:11:42Z INF proxy.go:32 > Starting proxy... namespace=default proxy-host=127.0.0.1 service=kubeshark-front src-port=8899
2026-10-23T07:11:47Z INF tapRunner.go:439 > Kubeshark is available at: url=http://127.0.0.1:8899
2026-10-23T07:11:47Z ERR browser.go:26 > While trying to open a browser error="exec: \"xdg-open\": executable file not found in $PATH"

要点解读：

tap 自动下载 Chart（kubeshark-53.6.0.tgz）并安装名为 kubeshark 的 Helm release，创建 21 个资源；
自动把 default/kube-system 等命名空间内的 Pod 纳入捕获目标（Targeted pod 行）；
完成后自动启动本地端口转发，Web UI 固定在 http://127.0.0.1:8899；
最后一行 xdg-open 报错是无头服务器上「自动打开浏览器」失败，属预期现象，Web UI 不受影响（远程服务器可用 SSH 隧道访问，见 4.6 节）；
tap 进程需保持前台运行（Ctrl+C 会中断端口转发，但集群内 Kubeshark 组件继续运行，可随时用 kubeshark proxy 重新拉起转发，见 5.4 节）。

4.5 验证部署

另开一个终端验证资源与 Web UI（实测回显）：

kubectl get pods -A

NAMESPACE     NAME                                READY   STATUS    RESTARTS   AGE
default       demo-client-6cb6666488-cbj6f        1/1     Running   0          5m29s
default       demo-nginx-57669875d8-chmsf         1/1     Running   0          5m29s
default       kubeshark-front-568b59dd44-c9fzq    1/1     Running   0          71s
default       kubeshark-hub-c88754494-tbpdb       1/1     Running   0          71s
default       kubeshark-worker-daemon-set-cgbgt   2/2     Running   0          71s
kube-system   coredns-7896679cc-fz6vk             1/1     Running   0          7m33s

三件套齐全：kubeshark-front（Web UI）、kubeshark-hub（聚合与 API）、kubeshark-worker-daemon-set（节点捕获，含 sniffer+tracer 两个容器）。Worker 是 DaemonSet（实测 kubectl get ds 输出 DESIRED/CURRENT/READY = 1/1/1，单节点即一个）。

Web UI 可达性验证（实测回显，响应头节选）：

curl -sI http://127.0.0.1:8899 | head -5

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With, x-session-token
Access-Control-Allow-Methods: POST, OPTIONS, GET, PUT, DELETE

返回 HTTP/1.1 200 OK 即 Web UI 就绪。远程服务器可通过 SSH 隧道在本地浏览器打开：ssh -L 8899:127.0.0.1:8899 <user>@<服务器IP>，然后访问 http://127.0.0.1:8899。

L4 流量捕获验证（实测）：等待数分钟后 Worker 的 eBPF 流表即有数据。用官方 MCP 查询工具验证（kubeshark mcp 的 URL 直连模式，逐条 JSON-RPC 输入，经 Web UI 端口转发查询 Hub）：

kubeshark mcp --url http://127.0.0.1:8899
# 向其 stdio 依次发送 initialize / notifications/initialized 后调用 list_l4_flows（limit=1）

实测返回（JSON 节选，total=120 表示捕获到 120 条 TCP/UDP 流）：

{"flows":[{"proto":"tcp","client":{"ip":"10.42.0.13"},"server":{"ip":"10.42.0.2","port":9153,"ns":"kube-system","svc":"kube-dns"},...
"totals":{"pkts":24,"bytes":45912}},...],"total":120,"truncated":true}

流记录包含协议、客户端/服务端 IP 与端口、K8s Service 归属（svc: kube-dns）、收发包数与字节数、TCP 握手时延分位数（tcp_handshake_p50_us/p90_us/p99_us，实测 3~128µs）。L7 API 事务在嵌套实验环境（K8s 本身跑在容器内）未能产生条目，见 8.6 节的说明与排查建议；真实服务器上 Web UI 的 L7 视图以界面实际展示为准。

4.6 排障实录

以下问题均在本次实测中真实遇到，按「现象 → 定位 → 解决」沉淀。

排障一：找不到 kubeconfig（见 4.2 节）——现象为 tap 启动即报 stat /.kube/config: no such file or directory 并退出；定位是 kubeshark 默认读 $HOME/.kube/config 而 k3s kubeconfig 在 /etc/rancher/k3s/k3s.yaml；解决为复制 kubeconfig 或设置 KUBECONFIG 环境变量。

排障二：端口 8899 被占用。重复执行 kubeshark tap/kubeshark proxy 时，若旧的端口转发进程仍在，报错（实测原文）：

2026-10-23T07:22:02Z ERR common.go:26 > Error occurred while running K8s proxy. Try setting different port using --proxy-front-port error="listen tcp 127.0.0.1:8899: bind: address already in use"

定位：kubectl port-forward 子进程残留。解决：找到并结束旧进程后重跑，或换端口（如 --proxy-front-port 8900）：

ps -ef | grep "port-forward" | grep -v grep
kill <旧进程 PID>

排障三：无头服务器 xdg-open 报错（见 4.4 节要点解读）——browser.go:26 > While trying to open a browser error="exec: \"xdg-open\": executable file not found in $PATH"，仅影响自动开浏览器，可忽略；Web UI 用 SSH 隧道访问。

排障四（特定场景）：Kubernetes 本身运行在容器内（k3s-in-docker / kind / k3d）时 Worker 起不来。若你的 k3s/K8s 集群节点本身是外层容器里的进程，Worker 初始化会连续报两类错误（实测原文）：

其一，/sys 挂载传播失败：

Warning  Failed     ...  kubelet  Error: failed to generate container spec: failed to generate spec: path "/sys" is mounted on "/sys" but it is not a shared mount

其二，eBPF 追踪器初始化失败：

2026-10-23T07:13:04Z ERR tracer/main.go:307 > Initialize tracer failed. error="install sycall hooks failed: install syscall hooks failed: neither debugfs nor tracefs are mounted"

2026-10-23T07:13:06Z ERR cmd/worker/main.go:546 > Failed to create flows manager error="attach inet_sock_set_state: neither debugfs nor tracefs are mounted"

定位：外层容器默认以私有传播（rprivate）挂载 /sys，Kubelet 无法在 Pod 内传播挂载宿主内核调试文件系统。解决（在承载 k3s 的外层特权容器内执行，然后重建 Worker Pod）：

mount --make-rshared /
mount -t debugfs debugfs /sys/kernel/debug
mount -t tracefs tracefs /sys/kernel/tracing
kubectl delete pod -l app.kubeshark.com/app=worker

⚠️ 注意：以上三条命令只适用于「K8s 集群节点本身是容器」的嵌套场景（k3s-in-docker、kind、k3d 等）。真实服务器直装 k3s 时 /sys 由宿主内核原生挂载，不需要也不应该执行这些操作；修复后 Worker 日志中不再出现上述报错即恢复（本实测环境修复后 Worker 2/2 Running，L4 流表正常累积至 120 条）。

五、安装方案 B：Helm Chart 手工部署

5.1 卸载方案 A 的既有安装（实测 kubeshark clean）

同一集群二选一：若已按方案 A 装过，先完整卸载（kubeshark clean 是官方卸载命令，实测回显节选，共清理 Role/ClusterRoleBinding/ConfigMap/Secret/ServiceAccount/NetworkPolicy 等全部 21 个资源）：

kubeshark clean

2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-self-config-role" Role
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-cluster-role-binding-default" ClusterRoleBinding
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-cluster-role-default" ClusterRole
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-nginx-config-map" ConfigMap
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-config-map" ConfigMap
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-saml-x509-key-secret" Secret
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-secret" Secret
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-saml-x509-crt-secret" Secret
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-service-account" ServiceAccount
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-worker-network-policy" NetworkPolicy
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-front-network-policy" NetworkPolicy
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-dex-network-policy" NetworkPolicy
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-hub-network-policy" NetworkPolicy
2026-10-23T07:28:03Z INF helm.go:177 > purge requested for kubeshark
2026-10-23T07:28:03Z INF clean.go:28 > Uninstalled the Helm release: kubeshark

卸载完成后验证（实测回显，release 列表为空、Pod 只剩 demo 与系统组件）：

helm list -n default

NAME    NAMESPACE       REVISION        UPDATED STATUS  CHART   APP VERSION

5.2 安装 Helm 并添加官方 Chart 仓库

若尚未安装 Helm（实测安装 v3.17.3）：

curl -Lo /tmp/helm.tar.gz https://get.helm.sh/helm-v3.17.3-linux-amd64.tar.gz
tar xzf /tmp/helm.tar.gz -C /tmp
sudo mv /tmp/linux-amd64/helm /usr/local/bin/helm && chmod 755 /usr/local/bin/helm
helm version

version.BuildInfo{Version:"v3.17.3", GitCommit:"e4da49785aa6e6ee2b86efd5dd9e43400318262b", GitTreeState:"clean", GoVersion:"go1.23.7"}

添加官方 Chart 仓库并更新索引（实测回显）：

helm repo add kubeshark https://helm.kubeshark.com

"kubeshark" has been added to your repositories

helm repo update

...Successfully got an update from the "kubeshark" chart repository
Update Complete. ⎈Happy Helming!⎈

确认 Chart 版本（实测回显）：

helm search repo kubeshark

NAME                    CHART VERSION   APP VERSION     DESCRIPTION
kubeshark/kubeshark     53.6.0                          The API Traffic Analyzer for Kubernetes

5.3 helm install 部署

标准安装（Helm 需能找到集群凭据：export KUBECONFIG=/etc/rancher/k3s/k3s.yaml；可按需追加 --set 覆盖，参数全集见本专栏《Kubeshark 配置参数详解》）。实测（追加了一项把 L7 解析的自动停止窗口延长到 24 小时，默认 5m）：

helm install kubeshark kubeshark/kubeshark --namespace default --set tap.capture.dissection.stopAfter=24h

实测输出（官方提示信息逐行照抄）：

Thank you for installing Kubeshark.

Registry: docker.io/kubeshark
Tag: v53.6.0

Your deployment has been successful. The release is named `kubeshark` and it has been deployed in the `default` namespace.

Notices:
- API AUTHENTICATION IS DISABLED (tap.auth.enabled=false, the default).
- Callers are not identified, and every one of them gets the role
  `kubeshark-admin`.
- Anyone able to reach the Hub can read captured traffic and change settings.
- For a read-only deployment with no login, set `tap.auth.defaultRole=kubeshark-viewer`.
- To identify callers, set `tap.auth.enabled=true` with a `tap.auth.type` of `saml` or `oidc`.
- See https://docs.kubeshark.com/en/roles
- No license key was detected.
- Authenticate through the dashboard to activate a complementary COMMUNITY license.
- If you have an Enterprise license, download the license key from https://console.kubeshark.com/
- An Enterprise license-key can be added as 'license: <license>' in helm values or as `--set license=<license>` or as `LICENSE` via mounted secret (`tap.secrets`).
- Contact us to get an Enterprise license: https://kubeshark.com/contact-us.

To access the application, follow these steps:

1. Perform port forwarding with the following commands:

    kubectl port-forward -n default service/kubeshark-front 8899:80
    you could also run: `kubeshark proxy` (which simply manages the port-forward connection)

2. Once port forwarding is done, you can access the application by visiting the following URL in your web browser:
    http://127.0.0.1:8899/

💡 说明：官方 Notices 有两条值得重视——① 默认未启用 API 鉴权（tap.auth.enabled=false），任何能连到 Hub 的人都拥有 kubeshark-admin 角色，能读取全部捕获流量，公网可达的集群务必按提示开启认证或改为 kubeshark-viewer 只读角色；② 未检测到 license 时可经 Dashboard 登录流程激活互补的 COMMUNITY 许可，Enterprise 许可经 --set license=<license> 注入。

与方案 A 不同，helm install 不会自动建立端口转发，Web UI 访问需手动执行（见 5.4 节）。

5.4 验证部署并打开 Web UI

等待组件就绪（实测回显，全新安装约 90 秒）：

kubectl get pods

NAME                                READY   STATUS    RESTARTS   AGE
demo-client-6cb6666488-cbj6f        1/1     Running   0          22m
demo-nginx-57669875d8-chmsf         1/1     Running   0          22m
kubeshark-front-568b59dd44-5h2g8    1/1     Running   0          91s
kubeshark-hub-bfb4c88fb-cb27k       1/1     Running   0          91s
kubeshark-worker-daemon-set-nsbz2   2/2     Running   0          91s

用官方 CLI 的 proxy 子命令建立端口转发（等价于 helm 输出里提示的 kubectl port-forward，且会自动管理转发进程；实测回显）：

kubeshark proxy

2026-10-23T07:25:08Z INF proxy.go:32 > Starting proxy... namespace=default proxy-host=127.0.0.1 service=kubeshark-front src-port=8899
2026-10-23T07:25:08Z INF proxyRunner.go:103 > Kubeshark is available at: url=http://127.0.0.1:8899
2026-10-23T07:25:08Z ERR browser.go:26 > While trying to open a browser error="exec: \"xdg-open\": executable file not found in $PATH"

（xdg-open 报错同 4.4 节，无头服务器忽略即可。）Web UI 验证同 4.5 节：curl -sI http://127.0.0.1:8899 返回 HTTP/1.1 200 OK。

--set 是否生效可用 Hub 进程参数复核（实测回显，-capture-stop-after 24h 证明 stopAfter=24h 已下发）：

ps -ef | grep "[h]ub -port"

... ./hub -port 8080 -loglevel warning -capture-stop-after 24h -snapshot-size-limit 20Gi ...

六、方案对比与选择建议

维度	方案 A：kubeshark tap	方案 B：helm install
操作量	一条命令（含端口转发）	repo add + install + 手动 port-forward 三步
适用场景	开发调试、快速试用	GitOps/ArgoCD 管理、生产标准化交付、需精细定制 values
端口转发	自动拉起	手动（kubectl port-forward 或 kubeshark proxy）
参数覆盖	`--set` 逐项追加	values.yaml / `-f` / `--set` 全量能力
升级管理	重跑 tap（检测到既有安装则跳过 Helm install，仅更新配置）	helm upgrade 标准流程，可回滚
CI/CD 集成	适合临时会话	适合流水线

选择建议：先 tap 快速验证，转 Helm 做长期托管。两者底层是同一个 Chart（tap 日志实测其下载的就是 kubeshark-53.6.0.tgz），运行形态完全一致，随时可以 clean 后切换。

七、部署后配置说明

7.1 许可（License）三件事

Community（免费）限额 3 节点 / 60 Pods，到 License Portal 注册领取后以 --set license=<license> 注入或升级时加入 values；
未注入 license 时部署可运行，安装输出会提示经 Dashboard 登录激活互补 COMMUNITY 许可（见 5.3 节 Notices 实测原文）；
Community/Pro 许可要求集群能出公网（telemetry 必须可达，否则许可失效），离线集群需评估 Enterprise 离线许可。

7.2 认证（Auth）

默认 tap.auth.enabled=false，所有调用者都是 kubeshark-admin（可读全部流量、可改设置）。最小加固：--set tap.auth.defaultRole=kubeshark-viewer（只读免登录）；正式多用户场景启用 SAML/OIDC（tap.auth.enabled=true + tap.auth.type=saml|oidc）。

7.3 捕获行为相关的两个默认值

tap.capture.dissection.stopAfter 默认 5m：L7 协议解析在启动 5 分钟后自动停止（省资源），无人值守采集需延长（本实测改为 24h 并在 Hub 进程参数中复核生效）；
tap.telemetry.enabled 默认 true：关闭用 --telemetry-enabled=false（tap 日志实测提示原文：Telemetry can be disabled by setting the flag: --telemetry-enabled=false），但注意与 7.1 节许可的联动。

更多参数逐项说明见本专栏《Kubeshark 配置参数详解》。

八、常见问题（FAQ）

Q1：tap 报 stat /.kube/config: no such file or directory？ 见 4.2 节排障实录一：复制 k3s kubeconfig 到 ~/.kube/config 或 export KUBECONFIG。

Q2：Web UI 打不开 / 8899 拒绝连接？ 先确认 kubeshark-front Pod 是否 Running（kubectl get pods）；再确认端口转发是否存活——tap 的 Ctrl+C 或进程退出都会断掉转发，重跑 kubeshark proxy 即可（实测验证 200 OK）；远程服务器用 SSH -L 隧道。

Q3：8899 端口被占用？ 见 4.6 节排障实录二：结束残留的 port-forward 进程，或 --proxy-front-port 换端口。

Q4：kubeshark-worker-daemon-set 一直不 Ready？ 先看事件：kubectl describe pod -l app.kubeshark.com/app=worker。真实服务器常见原因是内核过旧不支持 eBPF/特权挂载（可 --set tap.tls=false 关闭 eBPF 追踪降级为纯 AF_PACKET 抓包）；K8s-in-容器嵌套场景见 4.6 节排障实录四。

Q5：L7 视图/接口列表一段时间后没数据了？ 默认 tap.capture.dissection.stopAfter=5m 到期自动停止解析（实测复现：5 分钟后 MCP 查询报 L7 protocol dissection is disabled），延长该值或重新 enable 后恢复。本次嵌套实验环境中 L7 条目持续为空，与外层容器对解析作业的存储/挂载限制有关；真实服务器若同样为空，优先检查 Worker 的 raw capture 是否正常（kubeshark mcp 的 get_raw_capture_status 工具实测返回 enabled=true/session_id）与 Hub/Worker 日志。

Q6：镜像拉取失败（离线/慢）？ 节点需能拉取 docker.io/kubeshark/{hub,worker,front}:v53.6。离线集群自建仓库后 --set tap.docker.registry=<仓库地址>，必要时配 tap.docker.imagePullSecrets。

Q7：如何采集诊断日志给官方提 issue？ kubeshark logs -f /tmp/kubeshark_logs.zip（实测生成 14KB 的 ZIP，含 hub/worker/front 全部容器日志）。若本地无配置文件会多一行警告 Failed write file! ... /.kubeshark/config.yaml: no such file or directory，不影响 ZIP 生成。

九、卸载与清理

方案 A/B 卸载命令相同（实测见 5.1 节完整回显）：

kubeshark clean

该命令卸载 Helm release 并删除 Kubeshark 的全部集群资源（含 RBAC、ConfigMap、Secret、NetworkPolicy），不会触碰业务工作负载（实测 demo-nginx/demo-client 在 clean 后仍 Running）。彻底清理残余（可选）：

helm list -n default          # 确认 release 已删（实测输出为空表）
kubectl get pods              # 确认无 kubeshark-* Pod

卸载本机 CLI 二进制：删除 /usr/local/bin/kubeshark 即可（静态单文件，无其他残留）；缓存目录 ~/.cache/helm/repository（Chart 包）与 ~/.kubeshark（配置）可按需删除。

十、参考链接

官方安装文档：https://docs.kubeshark.com/en/install
Helm Configuration Reference：https://docs.kubeshark.com/en/helm_reference
GitHub Releases（v53.6.0 二进制下载与校验）：https://github.com/kubeshark/kubeshark/releases
官方 Chart 仓库：https://helm.kubeshark.com
License Portal 文档：https://docs.kubeshark.com/en/license_portal
角色与认证文档：https://docs.kubeshark.com/en/roles
站内系列：《Kubeshark 介绍与选型指南》、本专栏《Kubeshark 配置参数详解》、《Kubeshark 常用 CLI 命令详解》。