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 即可跑通。

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

本文用 轩辕镜像 加速拉取 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 客户端。

和常见方案比：

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

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

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

---

二、环境要求

bash
docker --version
docker compose version

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

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

备用地址：

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

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

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

---

三、标签怎么选

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

完整列表：tags。

---

四、拉取镜像

用 轩辕镜像 加速拉取：

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

Ubuntu 24.04 实测：

text
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

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

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

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

---

五、Docker Compose 部署（推荐）

5.1 创建目录

bash
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）：

bash
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

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

5.3 启动服务

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

Ubuntu 实测：

text
[+] 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

日志关键行（节选）：

text
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）

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

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

6.2 登录

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

6.3 桌面里能做什么

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

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

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

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

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

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

---

七、日常运维与安全

bash
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 时使用；日常跟做仍用第五节。

bash
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

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

bash
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：流量用尽，需 充值。其它问题见 常见问题。

---

十一、命令速查

bash
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