Lens：桌面安装、多集群接入与应用排查
Lens K8S IDE 是 Kubernetes 桌面客户端。集群以独立入口呈现，工作负载、网络、存储和权限资源可以在侧栏中查找；对象详情、YAML、日志和终端集中在同一窗口。需要反复切换几个集群、同时观察多个 Pod 时，桌面视图便于连续浏览。
桌面客户端连接哪些对象
Lens 桌面应用
├── Lens ID：产品激活、订阅和可选云功能
├── kubeconfig：Kubernetes API 地址、CA、集群登录身份
│ └── context → namespace → Deployment / Pod / Service
├── 本地设置：集群入口、窗口、日志标签页、扩展
└── 可选集成：云账号、团队空间及其他产品功能Lens ID 与 Kubernetes 登录身份分别负责产品使用和集群访问。完成 Lens 激活后，仍需要有效 kubeconfig；从 Lens 注销，也不会自动删除 Kubernetes RoleBinding。
本地 kubeconfig 可以连接本机 kind，也可以连接远程集群。“本地”描述文件来源，不代表服务端就在当前电脑。连接前核对文件中的 server 与 context，尤其不要用两个相同的显示名称区分测试和生产。
Lens 适合资源浏览、日志和短时调试。频繁发布的清单继续保存在 Git、Helm 或 Kustomize 中；界面编辑提交的是实际 API 变更，GitOps 控制器可能随后把它覆盖。批量处理与可重复排障可使用 kubectl，纯终端操作可使用 K9s。
安装并接入一个测试集群
选择桌面安装包
Linux 需要图形桌面环境；普通无桌面的服务器不必为了运行 Lens 安装整套 GUI。以下 APT 路径适用于 Ubuntu 22.04 或更新的受支持 amd64 桌面系统，安装步骤使用 sudo，启动应用使用普通用户。系统要求、RPM、AppImage、Windows 与 macOS 安装入口见官方安装说明。
首次添加软件源前，确认机器没有已受管的同名文件；存在时停止，交由软件管理员核对。
set -euo pipefail
command -v curl
command -v gpg
test ! -e /usr/share/keyrings/lens-archive-keyring.gpg
test ! -e /etc/apt/sources.list.d/lens.list
install_dir=$(mktemp -d /tmp/lens-install.XXXXXX)
curl -q --fail --show-error --location --max-time 60 \
https://downloads.k8slens.dev/keys/gpg -o "$install_dir/lens-key.asc"
gpg --dearmor --output "$install_dir/lens-key.gpg" "$install_dir/lens-key.asc"
sudo install -m 0644 "$install_dir/lens-key.gpg" \
/usr/share/keyrings/lens-archive-keyring.gpg
printf '%s\n' \
'deb [arch=amd64 signed-by=/usr/share/keyrings/lens-archive-keyring.gpg] https://downloads.k8slens.dev/apt/debian stable main' \
| sudo tee /etc/apt/sources.list.d/lens.list >/dev/null
sudo apt-get update
apt-cache policy lens
sudo apt-get install lens
dpkg-query -W lens
rm -- "$install_dir/lens-key.asc" "$install_dir/lens-key.gpg"
rmdir -- "$install_dir"
unset install_dir
lens-desktopAPT 校验仓库签名，软件源公钥通过官方 HTTPS 地址取得。企业分发还应把信任的公钥和安装版本纳入软件仓库配置。apt-cache policy 显示候选版本，dpkg-query 显示最终安装版本；需要固定版本时，从已批准仓库选择实际存在的版本，再用 apt-get install lens=版本号 安装。stable 软件源会更新，不能作为版本锁定。
Windows 使用官方 exe 安装包，默认可安装到当前用户；macOS 将 dmg 中的 Lens.app 放入 Applications。首次启动按欢迎页登录已有 Lens ID 或建立符合组织要求的账号并激活。离线激活取决于订阅与管理员配置，具体入口见激活说明。产品激活不需要授予 Kubernetes 管理员权限。
只导入实验 context
下面的 Bash 命令在已安装 kubectl、可访问测试集群的工作站执行。可以按 kind 主文建立 kind-tooling-dev。运行 Lens 的工作站必须能访问 kubeconfig 的 API 地址；Linux 虚拟机或 WSL 内的回环地址，未必能直接从另一台电脑访问。
set -euo pipefail
umask 077
CTX=kind-tooling-dev
NS=lens-lab
lens_lab_dir=$(mktemp -d /tmp/lens-lab.XXXXXX)
k() { kubectl --context "$CTX" "$@"; }
k cluster-info
k config view --minify --flatten --raw > "$lens_lab_dir/kubeconfig"
chmod 600 "$lens_lab_dir/kubeconfig"
kubectl --kubeconfig "$lens_lab_dir/kubeconfig" config view --minify --raw=false导出的文件包含当前 context 所需凭证，不上传、不提交、不放进同步盘。最后一条命令隐藏凭证值，用于核对目标；它不会自动把管理员身份降权。管理员身份只用于这个隔离实验，生产接入使用单独的只读凭证。
导入路径按本地集群接入说明操作：
- 打开 Preferences → Kubernetes → Manage Kubeconfigs。
- 选择 Add from filesystem，选择刚生成的 kubeconfig 文件。
- 在 Navigator → Kubernetes Clusters → Local Kubeconfigs 找到目标 context。
- 打开集群，核对 API 地址与名称，再进入资源视图。
也可以通过 Add Kubeconfigs → Add kubeconfig by pasting 粘贴内容；该方式会在 ~/.lens/kubeconfigs 中生成额外文件。文件导入更容易追踪实验凭证的位置。删除原文件前先取消其导入或监视，避免旧入口持续报连接错误。
创建可浏览、可访问的应用
继续在原管理员 Bash 会话执行。namespace 已存在时停止，不复用归属不明的对象。
k create namespace "$NS"
k -n "$NS" create deployment lens-web --image=nginx:1.30.4-alpine --port=80
k -n "$NS" expose deployment lens-web --port=80 --target-port=80
k -n "$NS" rollout status deployment/lens-web --timeout=180s
k -n "$NS" get deployment,pod,service -l app=lens-web节点需要能拉取镜像；离线 kind 环境先导入对应镜像。正常结果包含一个可用 Deployment、一个 Running Pod 和一个 ClusterIP Service。
在 Lens 中进入 Workloads → Deployments，将 namespace 选为 lens-lab，打开 lens-web，比较副本数与镜像。随后进入 Workloads → Pods，选中关联 Pod，检查容器 nginx、Ready、Restart 次数和事件。Network → Services 中应能找到 lens-web；服务选择器 app=lens-web 把流量关联到实验 Pod。
使用资源、日志和端口转发排查应用
从 Pod 详情打开日志
在 Workloads → Pods 选中目标 Pod，使用 More Actions → Log 打开日志。日志标签页的 Pod、Container 下拉框用于切换对象，具体位置见官方日志操作。
Nginx 初次启动主要显示入口脚本和启动信息；访问页面后才会出现访问日志。多容器 Pod 必须选择正确容器，滚动更新时还要留意 Pod 名称是否已经改变。旧标签页没有新请求日志，可能只是仍停在旧 Pod。
从容器端口建立本机访问
实验 Deployment 指定了 containerPort: 80，所以 Pod 详情可以识别容器端口。进入 Pod Details → Container，选择 nginx 的 80/TCP，点击 Forward 配置本地端口为 18081。检查当前对话框支持的监听地址选项，只允许本机访问；如果无法确认监听范围，使用下面显式回环绑定的 kubectl 对照命令。
在独立终端执行，它会保持前台运行：
kubectl --context kind-tooling-dev -n lens-lab \
port-forward --address=127.0.0.1 deployment/lens-web 18081:80Lens 转发和这条命令二选一，不能同时占用 18081。监听成功后，在另一个本机终端验证：
curl -q --noproxy '*' --fail-with-body --max-time 10 \
http://127.0.0.1:18081/响应应包含 Welcome to nginx!，Lens 日志窗口应出现这次 GET 的访问记录。这个结果验证了本机转发到 Pod 的路径；Service 的 ClusterIP、Ingress 和外部负载均衡仍是另外的网络路径。
Lens 的 Port Forwarding 视图可以查看、停止和删除转发会话，见官方端口转发说明。停止 Lens 会话或对照终端的 Ctrl-C 后，再次 curl 应连接失败。若仍收到页面，检查是不是另一个进程仍占用端口，不要直接结束未知进程。
在界面中识别失败发布
关闭转发后，在原管理员 Bash 会话设置不存在的镜像标签：
k -n "$NS" set image deployment/lens-web \
nginx=nginx:lens-lab-image-does-not-exist
if k -n "$NS" rollout status deployment/lens-web --timeout=30s; then
printf '异常：不存在的镜像标签却发布成功\n' >&2
exit 1
fi
k -n "$NS" get pods -l app=lens-web在 Lens 中比较新旧 Pod。新 Pod 的镜像拉取失败，而旧 Pod 可能继续 Running。打开新 Pod 的 Events，检查错误是否确实来自预期的镜像名称；没有启动的容器通常没有应用日志，Pod Shell 也无法连接。
修复时回到管理员终端：
k -n "$NS" set image deployment/lens-web nginx=nginx:1.30.4-alpine
k -n "$NS" rollout status deployment/lens-web --timeout=180s
k -n "$NS" get pods -l app=lens-webLens 应随资源更新显示恢复后的副本。再次建立转发并执行 HTTP 检查，确认恢复的 Pod 能处理请求。实际项目应在原始配置仓库修复，而不是仅修改当前集群。
按动作拆分授权
日常观察身份可以读取资源与日志，容器终端、端口转发、编辑和删除分别授权。以下检查使用导入 Lens 的同一 kubeconfig：
lens_k() {
kubectl --kubeconfig "$lens_lab_dir/kubeconfig" -n "$NS" "$@"
}
lens_k auth can-i get pods
lens_k auth can-i get pods --subresource=log
lens_k auth can-i create pods --subresource=exec
lens_k auth can-i create pods --subresource=portforward
lens_k auth can-i patch deployments隔离实验的管理员身份通常全部返回 yes。生产观察账号只授予任务所需权限；没有授权的检查返回 no 和非零退出码，脚本中应使用 if 分支处理。需要可直接验证的 namespace 级只读身份，可使用 K9s 的短期账号实验，把 observer.kubeconfig 导入 Lens，选择 k9s-lab 查看资源和日志。该身份无法执行端口转发、exec 或删除。
Pod Shell 需要服务端授权，也需要容器中存在可用 shell；distroless 镜像没有 sh 时，即使权限正确也无法打开。不要为了让按钮可用扩大整个项目的权限，或临时改造生产镜像加入调试工具。
多集群、指标和扩展
多集群入口应包含用途和区域，生产与开发使用不同凭证。切换后先检查 namespace 与目标对象，再操作资源。Lens 显示名便于辨认，但 kubeconfig 中的 server 才决定请求发往哪里。
CPU、内存和历史图表取决于指标来源与权限。图表为空时先判断是没有指标服务、数据源连接失败还是查询被拒绝；不能据此认为应用没有负载，也不要为填满图表直接安装未经评估的集群组件。
扩展会在桌面管理会话中执行代码。接入前确认来源、版本、维护状态和所需能力，升级异常时先禁用新增扩展作对照。云集成、AI 功能及遥测还会增加出站数据流；启用前核对组织允许发送的数据和当前产品设置，不把本地资源浏览与供应商云服务混成一个授权决定。
连接故障、升级和退出
用同一身份区分桌面故障与集群故障
| 现象 | 首个检查 | 下一步 |
|---|---|---|
| 集群一直 Connecting / Offline | 同一 kubeconfig 执行 get pods | 检查 server、CA、代理及凭证有效期 |
| kubectl 成功，Lens 失败 | Lens 使用的文件路径、认证插件和应用日志 | 核对 GUI 进程的 PATH、代理与证书环境 |
| 资源可看，日志 Forbidden | pods/log 的 get 权限 | 修正指定 namespace 的 RoleBinding |
| Pod Shell 失败 | exec 权限、容器运行状态、shell 是否存在 | 按具体错误修复 |
| 转发端口被占用 | Port Forwarding 列表与本机监听 | 停止本次旧会话或选择空闲端口 |
| 升级后布局或偏好损坏 | 备份本地数据，记录版本和启动日志 | 尝试只重置界面状态 |
kubeconfig 使用 exec 登录插件时，Lens 所在操作系统必须能找到对应可执行文件。Linux Shell 中已安装 aws 或 gcloud，不代表 Windows 桌面进程也具备该命令。插件 apiVersion 与客户端能力需要匹配；遇到旧配置，优先按云厂商当前工具重新生成，不能只替换字段名称假定协议兼容。
升级保留本地数据与安装包
Lens 的安装渠道决定更新方式：exe、dmg、AppImage 支持应用内更新，APT/RPM 通过包管理器更新。受管电脑先保留旧安装包，关闭 Lens，再备份用户数据与实际导入的 kubeconfig。
常见数据位置如下，迁移与重置行为见安装文档的更新章节：
| 系统 | 默认用户数据目录 |
|---|---|
| Linux | ~/.config/Lens/，或 XDG_CONFIG_HOME 下的 Lens |
| Windows | %APPDATA%\Lens\ |
| macOS | ~/Library/Application Support/Lens/ |
备份包含集群地址、偏好和可能的凭证信息，应按敏感文件保存。升级后检查原集群连接、日志读取、权限拒绝和扩展。需要回退时使用旧安装包与兼容的旧数据副本，不让旧版本直接覆盖已迁移的新格式目录。
--clear-state 只清除部分界面持久状态，保留 kubeconfig、集群凭证和订阅信息。它适合偏好损坏的定位，不能当作凭证擦除命令。使用前先备份，再按官方平台命令启动。
撤销实验访问并清理
先在 Lens 停止本次端口转发、关闭日志和 Pod Shell，移除对实验 kubeconfig 的导入或监视。原管理员终端删除专用 namespace：
test "$CTX" = kind-tooling-dev
test "$NS" = lens-lab
k delete namespace "$NS" --wait=true --timeout=120s
test -f "$lens_lab_dir/kubeconfig"
rm -- "$lens_lab_dir/kubeconfig"
rmdir -- "$lens_lab_dir"
unset -f k lens_k
unset CTX NS lens_lab_dir如果使用过粘贴导入，还需要在 Manage Kubeconfigs 核对并移除对应副本，不删除整个 ~/.kube。退出 Lens ID 在用户菜单选择 Unregister，具体行为见账号注销说明。
移除本地文件只清理当前电脑上的副本。人员退出项目时，还要在实际身份系统撤销登录与集群授权；保存在其他电脑或备份中的有效凭证不会因为卸载桌面软件自动失效。