Agent 集群可以在 Cube 隔离运行环境内运行 Linux 桌面和图形界面（GUI）应用，通过浏览器查看画面并操作键盘、鼠标。您可以用它为 Agent 提供可观察、可交互的操作环境，或在调试时查看应用窗口、截图和工作文件。
本文以 Ubuntu GNOME 桌面为例，说明部署准备、连接方式、截图和文件保存。当前验证使用 CPU 软件渲染，无需 GPU；当前暂不支持 GPU / qGPU 图形加速和 Windows 桌面。
适用场景
为需要图形界面的 Agent 工具提供 Linux 运行环境。
在浏览器中观察应用窗口，手动执行操作、检查结果和排查问题。
获取桌面截图，用于结果确认或作为 Agent 的视觉输入。
将用户创建的文件和截图保存到持久化工作区，重建环境后继续读取。
普通桌面操作可采用 CPU 软件渲染。当前暂不支持 GPU / qGPU 图形加速，依赖此类加速的 3D 图形、视频处理等应用不在支持范围内。其他应用是否兼容，应使用实际应用镜像验证。
工作方式
桌面应用在 Cube 的 Linux Guest 环境中运行。虚拟显示服务生成画面，VNC 服务传输画面和键鼠输入，noVNC 将连接呈现在浏览器中。
浏览器 ↔ 已确认的访问入口 ↔ noVNC / VNC ↔ 虚拟显示服务 ↔ Linux 桌面应用
当前示例使用 GNOME、Xorg dummy 和 noVNC；Xorg 无法启动时，原示例脚本还提供 Xvfb 回退。已测试的显示后端是 Xorg dummy。Mesa llvmpipe 使用 CPU 渲染，因此运行桌面不要求物理显示器或 GPU。
当前验证范围
能力 | 验证结果 | 使用边界 |
Ubuntu GNOME 桌面 | 已验证 | 在 Cube Pod 内安装并启动示例桌面栈。 |
浏览器访问 | 已验证 | 经普通 Pod 转接访问 noVNC；正式访问入口待确认。 |
鼠标和键盘 | 已验证 | 鼠标打开终端，键盘输入、执行命令并创建文件。 |
桌面截图 | 已验证 | 使用 gnome-screenshot 的 X11 回退生成并导出实际画面。 |
工作文件持久化 | 已验证 | 同节点删除原 Pod 后，新 Cube Pod 挂载同一 AWV 卷，文件内容及校验值一致。 |
GPU / qGPU 图形加速、Windows 桌面 | 暂不支持 | 当前支持范围为使用 CPU 软件渲染的 Linux 桌面。 |
使用前准备
部署前，请确认以下条件：
1. 已获得 Agent 集群 Kubernetes 访问权限，目标节点的 Cube 运行时就绪，并取得可使用的 RuntimeClass 名称。
2. 已准备适配目标 CPU 架构的桌面镜像，包含桌面环境、虚拟显示服务、VNC / noVNC 和启动脚本。
3. 已确认浏览器到桌面服务的访问方式。noVNC 默认使用 TCP 6080；入口还需要支持 WebSocket。
4. 需要保留用户文件时，已开通并验证持久卷，明确挂载路径、用户 UID/GID、单写入要求和卷回收策略。
测试配置为 4 核 CPU、8 GiB 内存、1280×720 分辨率，用户目录使用 10 GiB 持久卷。这是单次测试配置，不是最低配置、推荐规格或性能承诺。提高分辨率、增加窗口或运行更重的应用会改变资源消耗，应先进行容量测试。
部署与连接
1. 准备桌面工作负载
通过 Kubernetes 提交桌面 Pod，并显式设置已确认的 RuntimeClass。配置桌面启动命令、资源 requests / limits 和用户目录挂载，确保应用实际进入 Cube 运行环境。接入方法请参见 通过 Kubernetes 接入工作负载。
建议将桌面依赖预先构建到镜像中。临时在 Pod 启动时下载和安装桌面软件可用于联调，但安装耗时、软件源访问和依赖变化会影响启动结果，不能作为预构建镜像的启动性能。
将持久卷挂载到用户目录时，空卷会覆盖镜像中原有的目录内容。首次启动需要初始化所需目录，如 Desktop、Documents，并设置正确的所有权；已有用户文件不应被初始化步骤覆盖。
2. 确认桌面就绪
检查日志中虚拟显示、桌面会话、VNC 和 noVNC 的启动结果，再通过实际访问确认画面。
kubectl -n <命名空间> get pod <桌面Pod> -o widekubectl -n <命名空间> logs <桌面Pod> -c <桌面容器>
将尖括号内容替换为实际资源名称。Pod 显示 Running 或 Ready、端口返回 HTTP 200，都不能单独证明桌面会话正常；还需要确认浏览器看到实际桌面，并能完成操作。
3. 通过浏览器连接
打开环境交付的 noVNC 地址，连接后检查桌面画面，使用鼠标打开终端，再输入一条简单命令并观察回显。
当前测试环境直接对 Cube Pod 执行
kubectl port-forward 访问 6080 失败；桌面 Guest 内服务正常，但端口转发未到达 Guest 服务。因此，本文不将直接转发作为可用操作步骤。联调时已验证的替代路径是：在集群内使用普通 Pod 转接桌面 Pod 的地址，再将转接 Pod 的端口仅绑定到本机
127.0.0.1。这是临时测试方式；转接地址随桌面 Pod 重建而变化，需要重新确认。正式 Service、Ingress、访问鉴权及网络策略仍需目标环境验证。CubeSandbox 示例的 VNC 配置未设置密码。用于业务访问前，应配置明确的身份校验、加密连接和授权范围，避免将原始 VNC 或无鉴权桌面入口直接开放到公网。
截图与保存文件
获取桌面截图
在桌面容器中，以桌面用户运行截图工具。以下命令适用于本文示例中的
user 用户和 DISPLAY=:0：kubectl -n <命名空间> exec <桌面Pod> -c <桌面容器> -- \\runuser -u user -- env DISPLAY=:0 \\gnome-screenshot -f /home/user/Documents/desktop.pngkubectl -n <命名空间> cp -c <桌面容器> \\<桌面Pod>:/home/user/Documents/desktop.png ./desktop.png
截图目录应已创建并允许桌面用户写入。
kubectl cp 需要容器中存在 tar 工具；导出后应打开图片，确认内容与当前画面一致。本次测试中，GNOME Shell 内建截图接口不可用，gnome-screenshot 自动回退到 X11 后成功生成图片。出现回退提示时应检查最终文件和画面，不应只根据提示判断截图失败。
保存和恢复工作文件
将需要保留的文件写入已挂载的持久化目录，例如
/home/user/Documents。路径应以实际卷挂载配置为准，不能仅根据目录名称判断其是否持久化。验证文件保存时，先记录文件内容和校验值：
kubectl -n <命名空间> exec <桌面Pod> -c <桌面容器> -- \\sha256sum /home/user/Documents/desktop.png
停止并卸载原工作负载后，再让新 Pod 挂载同一卷，核对文件内容和校验值。本次已验证同节点新 Cube Pod 读取原文本和截图均一致。卷准备、单写入控制及恢复检查请参见 工作区与持久化数据 和 重建运行环境后恢复文件。
重新挂载用户目录后，启动桌面应用并检查工作文件。
常见问题
现象 | 检查与处理 |
浏览器一直连接或黑屏 | 分别检查 noVNC / WebSocket 入口、VNC、虚拟显示和桌面进程。不要只检查 HTTP 首页。 |
Cube Pod 端口转发连接被拒绝 | 区分 Guest 内服务是否监听，以及转发是否到达 Guest；当前直接转发路径已发现不兼容。 |
用户目录或桌面文件夹缺失 | 检查空持久卷是否覆盖了镜像目录，按桌面用户身份初始化必要目录并检查权限。 |
截图报错或空白 | 检查 DISPLAY、桌面会话、执行用户和目标目录权限；打开导出图片确认内容。 |
锁屏或部分系统服务不可用 | 当前示例不是完整系统登录会话。已观察到屏幕锁定、systemd 和部分桌面服务告警，这些功能未完成验收。 |
浏览器或大型 GUI 应用异常退出 | 检查内存、共享内存和应用日志。本次 Guest 的 /dev/shm 实测为 64 MiB，配置更大 emptyDir 的效果尚未确认。 |
重建后文件丢失 | 检查是否使用同一 PVC、写入路径是否位于挂载目录，以及卷回收策略；容器根文件系统和临时目录不能代替持久卷。 |
清理资源
结束使用后，关闭桌面连接和临时转发，停止测试工作负载。删除持久卷前确认是否仍需保存工作文件；删除 Pod 与删除 PVC 是两种操作，后者可能触发后端数据回收。
