Docker 一键部署 Kasm Desktop：快速搭建容器化 Ubuntu 桌面

本文基于 kasmweb/desktop:1.18.0，实测标签 1.18.0，测试平台 Ubuntu 24.04 Linux。

云服务器、VPS、家用 NAS 多半是 纯命令行 Linux：没有显示器、没有桌面环境。装带界面的安装向导、数据库客户端或办公软件，只能靠 SSH；给宿主机装一整套 GNOME / KDE，又占内存、又难和维护中的 Web / 数据库服务共存；传统 VNC / RDP 还要额外装客户端，证书与权限也更碎。

内网和小团队更实际的做法是：宿主机继续保持无图形界面，按需起一个容器，用本机浏览器进完整 Linux 桌面，用完可停，不污染系统。商业云桌面贵、数据出域不可控；自建整套虚拟化或编排平台对「只想临时开个桌面」又偏重。

Kasm Desktop（镜像 kasmweb/desktop，见 镜像页）是 Kasm Workspaces 提供的 容器化 Ubuntu 桌面：画面经开源 KasmVNC 推到浏览器，实测为 XFCE，预装 Chrome 与 Firefox。镜像面向 Workspaces 编排，也支持 独立部署——本文只跟做独立部署，一条 Compose 即可跑通。

部署跑通之后，你实际能做这些事：

场景部署后怎么用云服务器图形化操作浏览器打开 https://IP:6901，登录后操作 XFCE 桌面临时办公 / 开发用内置 Chrome / Firefox、终端、文件管理器，宿主机不必装桌面隔离试用 Linux GUI容器内试软件，停掉即走评估 Kasm 生态先独立跑通，再决定是否安装完整 Kasm Workspaces

本文用 轩辕镜像 加速拉取 kasmweb/desktop:1.18.0，以 Docker Compose 完成启动与浏览器登录；文末附 docker run 备选。文内附 8 张实测截图。

上手要点

• 部署：默认 Compose（第五节）；临时试玩见 第八节 docker run

• 标签：1.18.0（钉死发布版；上游通常无 latest）

• 端口：宿主机 6901 → 容器 6901（必须 HTTPS）

• 账号：kasm_user / 环境变量 VNC_PW（务必改成强密码）

• 共享内存：shm_size: 512m（过小易导致容器内浏览器崩溃）

• 桌面：实测 XFCE；预装 Chrome / Firefox

• 暴露：公网限制来源 IP + 强密码；自签名证书需浏览器点「高级 → 继续前往」

• 边界：独立部署部分能力不完整（见第六节）；多用户 / 完整能力用 Workspaces

镜像说明：kasmweb/desktop · tags。相关：KasmVNC · workspaces-images · 自定义镜像 · 问题反馈。

一、Kasm Desktop 是什么？

一句话：Docker 里跑 Ubuntu + XFCE，浏览器打开就能用桌面——不必给服务器装图形界面，也不必另装 VNC 客户端。

能力说明浏览器访问https://IP:6901，画面由 KasmVNC 推流桌面环境Ubuntu Jammy + XFCE；预装 Chrome、Firefox部署方式独立部署（本文）或挂到 Kasm Workspaces 做多用户编排自定义可基于官方 Core / 默认镜像扩展，见 Building Custom Images

和常见方案比：

Kasm Desktop（本文）宿主机装 GNOME/KDEWebtop宿主机可保持无桌面直接装桌面，占资源可保持无桌面访问方式浏览器 + KasmVNC本机或另配远程浏览器 + Selkies适合试用 Kasm、临时 GUI长期本机图形环境LinuxServer 生态

易混对象（只需跟做一个镜像）：

对象说明kasmweb/desktop本文跟做镜像KasmVNC推流组件，已打进镜像，不用单独 pullworkspaces-images官方构建源码库（含 dockerfile-kasm-desktop 等），不是第二个 Desktop 镜像Kasm Workspaces完整平台（用户、会话、策略）；本文不安装轩辕 /r/ 与 /zh/r/同一镜像的概览页 / 中文简介页，不是两个仓库

浏览器 ──HTTPS:6901──▶ KasmVNC ──▶ XFCE + Chrome / Firefox 认证：kasm_user + VNC_PW 共享内存：shm_size ≥ 512m

官方限时演示（非自建）：Kasm Live Demo。

二、环境要求

项目建议系统Linux，建议 Ubuntu 24.04DockerEngine + Compose V2内存≥ 2～4 GB 可用（桌面 + 浏览器较吃内存）磁盘CONTENT SIZE 约 1.58 GB（DISK USAGE 约 5.31 GB）+ 工作目录架构实测 amd64；其它架构先查 tags端口宿主机 6901（HTTPS）

docker --version docker compose version

Linux 未装 Docker 可使用轩辕镜像一键安装脚本：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

备用地址：

bash <(wget -qO- https://get.xuanyuan.me/docker.sh)

更多见 轩辕镜像使用手册。

6901 已被占用时，Compose 改为 "16901:6901"，访问 https://IP:16901。

三、标签怎么选

Kasm 镜像标签与 Workspaces 发版对齐，通常不提供 latest。本文钉死 1.18.0。

标签含义推荐1.18.0固定发布版本文跟做1.19.0 等更新的固定发布版升级前核对说明与架构*-rolling*滚动重建尝鲜；生产勿当默认develop开发测试仅测试

完整列表：tags。

四、拉取镜像

用 轩辕镜像 加速拉取：

docker pull docker.xuanyuan.run/kasmweb/desktop:1.18.0

Ubuntu 24.04 实测：

1.18.0: Pulling from kasmweb/desktop 09710af56a6b: Pull complete d3e7c97af490: Pull complete 4f4fb700ef54: Pull complete 7a22b210ffa5: Pull complete 0f18855c5fad: Pull complete 0ca4d1fe6073: Pull complete 1fcfa6cf3103: Pull complete 668a930d1f3a: Pull complete 008a1600738f: Pull complete 6e13916b2f2b: Pull complete 71985e4f0615: Pull complete 8f23b650c150: Pull complete 67c9d22e1b6e: Pull complete 4a05668217a1: Pull complete 17d47f6c67d6: Pull complete Digest: sha256:9a94316372b8858d0238134ba507812e867fcb903d0db599c8cfd9ff8bcd0bfb Status: Downloaded newer image for docker.xuanyuan.run/kasmweb/desktop:1.18.0 docker.xuanyuan.run/kasmweb/desktop:1.18.0

docker images docker.xuanyuan.run/kasmweb/desktop:1.18.0

IMAGE ID DISK USAGE CONTENT SIZE EXTRA docker.xuanyuan.run/kasmweb/desktop:1.18.0 9a94316372b8 5.31GB 1.58GB U

首次拉取体积较大，请预留磁盘与时间。

五、Docker Compose 部署（推荐）

平台工作目录Linux（正文默认）/www/wwwroot/kasm-desktopmacOS 实测~/docker/kasm-desktop

5.1 创建目录

mkdir -p /www/wwwroot/kasm-desktop chown -R "$USER:$USER" /www/wwwroot/kasm-desktop cd /www/wwwroot/kasm-desktop

非 root 时给 mkdir / chown 加 sudo。

5.2 编写 docker-compose.yml

把 ChangeMe_StrongPass 换成你自己的强密码（浏览器登录密码 = VNC_PW）：

cat > docker-compose.yml <<'EOF' services: kasm-desktop: image: docker.xuanyuan.run/kasmweb/desktop:1.18.0 container_name: kasm-desktop restart: unless-stopped ports: - "6901:6901" environment: - VNC_PW=ChangeMe_StrongPass shm_size: "512m" EOF

配置项说明image轩辕镜像加速坐标 + 标签 1.18.06901:6901HTTPS 桌面入口VNC_PW登录密码；务必修改，勿把示例密码长期暴露在公网shm_size: 512m必设；共享内存不足时容器内浏览器易崩溃

未挂数据卷时，桌面内文件随容器生命周期变化；要长期保留请自行备份，或改用 Workspaces 的 Persistent Profiles。

5.3 启动服务

docker compose pull docker compose up -d docker compose ps docker compose logs -f --tail 100

Ubuntu 实测：

[+] Running 2/2 ✔ Network kasm-desktop_default Created ✔ Container kasm-desktop Started NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS kasm-desktop docker.xuanyuan.run/kasmweb/desktop:1.18.0 "/dockerstartup/kasm…" kasm-desktop 5 seconds ago Up 4 seconds 4901/tcp, 5901/tcp, 0.0.0.0:6901->6901/tcp, [::]:6901->6901/tcp

日志关键行（节选）：

Starting KasmVNC Paste this url in your browser: https://192.168.96.2:6901 ------------------ Xfce4 window manager startup------------------ Starting XFCE ------------------ KasmVNC environment started ------------------ vncext: Listening for websocket connections on 0.0.0.0 interface(s), port 6901 Kasm User () started container id b5e456028ee1 with local IP address 192.168.96.2

日志中的 https://192.168.96.2:6901 是容器网桥地址，局域网请用 https://宿主机IP:6901（本文实测 https://192.168.1.10:6901）。
KasmGamepadServer、polkit、colord、UDisks2 等告警在独立容器里常见，一般不影响桌面使用。

看到 Up，且出现 Starting XFCE、Listening … port 6901 后，按 Ctrl+C 退出日志跟踪。

六、浏览器访问与使用

6.1 打开地址（必须 HTTPS）

方式地址说明HTTPShttps://服务器IP:6901自签名证书；不要用 HTTP（日志会出现 non-SSL connection disallowed）

本文实测：https://192.168.1.10:6901。本机可试 https://127.0.0.1:6901。

首次会提示「您的连接不是私密连接」（NET::ERR_CERT_AUTHORITY_INVALID）：点 高级 → 继续前往 …（不安全）。

picture.image

6.2 登录

项值用户名kasm_user密码Compose 里的 VNC_PW

picture.image

登录后进入 XFCE：左侧为 Downloads、Uploads、Google Chrome、Firefox；屏幕左缘小箭头为 Kasm 控制条（剪贴板、画质等）。

picture.image

6.3 桌面里能做什么

双击 Google Chrome，可正常上网（本文打开轩辕镜像首页）：

picture.image

打开桌面 Downloads，文件管理器路径一般为 /home/kasm-user/Desktop/Downloads/：

picture.image

顶栏 Applications 可进 Terminal、File Manager、Settings 等：

picture.image

打开 Terminal Emulator，执行 uname -a：主机名与容器 ID 一致（实测 b5e456028ee1）：

picture.image

再执行 top，可看到 Xvnc、ffmpeg 及 kasm_* 相关进程：

picture.image

独立部署限制：官方说明音频、上传/下载、麦克风直通等在 stand-alone 下可能不完整，完整能力通常需要 Kasm Workspaces。桌面上的 Uploads / Downloads 是否可用，以你实测为准。

七、日常运维与安全

cd /www/wwwroot/kasm-desktop docker compose ps docker compose logs -f --tail 100 docker compose restart docker compose stop

修改 VNC_PW 后执行 docker compose up -d。

公网暴露时建议：

• 防火墙仅放行可信来源访问 6901

• 使用强密码，并定期更换

• 有域名时前置反向代理 + 可信证书（注意 WebSocket / HTTPS 透传）

问题反馈：workspaces-issues。

八、备选：docker run

仅临时试玩或没有 Compose 时使用；日常跟做仍用第五节。

docker run -d --name kasm-desktop --restart unless-stopped --shm-size=512m -p 6901:6901 -e VNC_PW=ChangeMe_StrongPass docker.xuanyuan.run/kasmweb/desktop:1.18.0

一次性前台试玩（退出即删容器）：

docker run --rm -it --shm-size=512m -p 6901:6901 -e VNC_PW=ChangeMe_StrongPass docker.xuanyuan.run/kasmweb/desktop:1.18.0

与 Compose 容器重名时先 docker compose down 或换 --name。

九、迁移 / 升级

1. docker compose stop，备份仍需保留的桌面文件（若有）

2. 将 Compose 中标签改为目标版本（如 1.19.0），先查 tags

3. docker compose pull && docker compose up -d

4. 浏览器重新登录，抽查 Chrome / 终端

5. 异常则改回旧标签再 up -d

滚动标签（*-rolling*）会定期重建，升级前记下可回退的固定版号或 Digest。

十、常见问题 FAQ

Q1：KasmVNC 还要再拉一个镜像吗？
不用。跟做 kasmweb/desktop 即可。要改预装软件再看 workspaces-images 与 自定义镜像。

Q2：打不开 https://IP:6901？
查 docker compose ps / logs；放行 6901；确认映射 6901:6901。自签名证书点「高级 → 继续前往」。必须用 HTTPS；HTTP 会触发 non-SSL connection disallowed。不要用日志里的容器网桥 IP（如 192.168.96.2）当访问地址。

Q3：用户名密码是什么？
用户名 kasm_user；密码为 VNC_PW。改密码后执行 docker compose up -d。

Q4：容器里浏览器崩溃？
确认 shm_size: "512m"（或更大）；内存不足时关掉多余标签页或加大宿主机可用内存。

Q5：日志里 Gamepad / polkit / colord 报错？
独立部署常见告警，多数不影响使用。成功看 Starting XFCE 与 Listening … port 6901。

Q6：为什么没有 latest？
Kasm 一般不提供 latest。请显式写 1.18.0 等固定标签。

Q7：独立部署还是装完整 Workspaces？
个人试用、单桌面 → 本文。多用户、会话策略、完整音频/传文件 → 按 Installation 安装平台。

Q8：和 Webtop 怎么选？
都是浏览器远程桌面。要 Kasm 生态选本文；要 LinuxServer / Selkies 看 Webtop 教程。不必两个都装。

Q9：拉取失败 401 / 402？
401：按 登录认证 检查镜像账户。402：流量用尽，需 充值。其它问题见 常见问题。

十一、命令速查

docker pull docker.xuanyuan.run/kasmweb/desktop:1.18.0 cd /www/wwwroot/kasm-desktop docker compose up -d docker compose ps docker compose logs -f --tail 100 # 浏览器 https://服务器IP:6901 # 用户 kasm_user / 密码 = VNC_PW docker compose down

十二、延伸阅读

• kasmweb/desktop 镜像页 · 标签列表

• GitHub · KasmVNC

• GitHub · workspaces-images

• Kasm Workspaces 安装

• Building Custom Images

• workspaces-issues

• 官方演示 Cast

• Webtop 对照教程

• 轩辕镜像使用手册

总结

• 跟做 kasmweb/desktop:1.18.0：Compose 映射 6901，设置 VNC_PW 与 shm_size: 512m。

• 浏览器用 HTTPS 登录 kasm_user，进入 XFCE（Chrome / Firefox 已预装）。

• KasmVNC 是推流技术、workspaces-images 是构建源码，都不必再单独拉 Desktop 镜像。

• 独立部署适合试用；多用户与完整能力请上 Kasm Workspaces。

阅读原文

• 轩辕镜像官方博客：https://xuanyuan.cloud/blog/kasm-desktop-docker-deploy