本文基于  linuxserver/webtop:ubuntu-xfce  镜像，Ubuntu 24.04 服务器实测

云服务器、VPS、家用 NAS 大多是  纯命令行 Linux——没有显示器、没有桌面环境，装软件、管文件、跑带 GUI 的工具只能靠 SSH。给宿主机装一套 GNOME / KDE？又占内存又难维护，还可能和现有服务抢资源。

Webtop  是 LinuxServer.io 出品的  浏览器远程桌面 ：Docker 起一个容器，里面跑完整 Linux 桌面（XFCE / KDE 等），你在   本机浏览器   里打开就是图形界面—— 宿主机无需安装任何桌面，服务器照样 headless 跑 Nginx、MySQL、Redmine。

本文带你完成一次  Webtop Docker Compose 部署：镜像加速拉取、编写  docker-compose.yml、HTTPS 登录、文件管理、终端与内置浏览器——全程零基础可跟做，文末  FAQ 含端口冲突与 AVX2 排错，附  8 张实测截图。

国内用户从 Docker Hub 拉取  linuxserver/webtop  可能较慢，本文使用  轩辕镜像  加速。官方文档见  LinuxServer Webtop，源码仓库  linuxserver/docker-webtop。

图 1：部署成功后，浏览器里就是完整 Linux 桌面——宿主机无需安装图形界面

一、Webtop 是什么？

Webtop  是  LinuxServer.io  维护的  容器化 Linux 桌面，基于 Selkies 技术把桌面画面编码后通过 Web 推流到浏览器。核心特点：

典型使用场景：

• 云服务器 / VPS 临时跑带 GUI 的安装向导、数据库客户端、IDE
• 内网运维 图形化浏览日志目录、用文件管理器整理备份
• 开发测试 在隔离容器里试 Linux 桌面软件，不影响宿主机
• 老机器 / 低配置 不想给宿主机装完整桌面，按需 docker compose up 即用即关

与 VNC / RDP 的区别 ：Webtop  零客户端，有浏览器就行；镜像体积较大（数 GB），适合按需启动，不建议 7×24 常驻占资源。与  File Browser  互补——前者管文件列表，后者给完整桌面体验。

二、为什么不在宿主机装桌面？

本文实测环境：Ubuntu 24.04 服务器上已跑  Redmine（占用 3000 端口），Webtop 用  13000 / 13001  映射，互不干扰。

三、环境要求

验证 Docker：

docker --version
docker compose version

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

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

更多安装说明见  轩辕镜像使用手册。

检查 CPU 是否支持 AVX2（可选，老机器建议先查）：

grep -q avx2 /proc/cpuinfo && echo "支持 AVX2" || echo "不支持 AVX2，请用 ubuntu-xfce"

四、拉取镜像

本文最终使用  ubuntu-xfce  标签（兼容无 AVX2 CPU）。若你确认 CPU 支持 AVX2 且想要 KDE，可换  ubuntu-kde。

docker pull docker.xuanyuan.run/linuxserver/webtop:ubuntu-xfce

首次拉取体积较大（数 GB），国内建议全程使用  docker.xuanyuan.run  加速域。

五、Docker Compose 部署

5.1 创建目录

mkdir -p /www/wwwroot/webtop/config
cd /www/wwwroot/webtop

5.2 编写 docker-compose.yml

services:
  webtop:
    image: docker.xuanyuan.run/linuxserver/webtop:ubuntu-xfce
    container_name: webtop-ubuntu-kde
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - LC_ALL=zh_CN.UTF-8
      - CUSTOM_USER=admin
      - PASSWORD= 你的强密码
      - PIXELFLUX_WAYLAND=false
    volumes:
      - ./config:/config
    ports:
      - "13000:3000"
      - "13001:3001"
    shm_size: "1gb"
    restart: unless-stopped

5.3 启动服务

docker compose pull
docker compose up -d
docker compose logs -f webtop

成功时日志关键行示例：

[ls.io-init] CPU does not support AVX2. Falling back to X11
INFO:selkies.__main__:Starting Selkies in 'websockets' mode.
INFO:data_websocket:Data WebSocket Server listening on port 8082
INFO:main:SelkiesStreamingApp initialized: encoder=x264enc, display=1024x768

看到  Falling back to X11  表示已自动回退到 X11 模式，可正常使用 。日志里偶现  PolicyKit1 failed: Permission denied  在容器环境中常见， 不影响桌面功能。

按  Ctrl+C  退出日志跟踪，容器继续在后台运行。

六、浏览器访问与登录

6.1 访问地址

本文实测地址：https://192.168.1.18:13001/

6.2 HTTP 基本认证

浏览器会弹出登录框，输入  docker-compose.yml  中的  CUSTOM_USER  与  PASSWORD：

图 3：设置 CUSTOM_USER / PASSWORD 后的浏览器登录界面

证书警告：镜像使用  自签名证书，内网可点「高级 → 继续访问」；公网建议 Nginx 反代并配置正式证书。

七、桌面使用指南

进入后是  XFCE 中文桌面，顶部菜单栏 + 底部程序坞，和普通 Linux 桌面一致。

7.1 文件管理

打开  文件管理器（Thunar），可图形化浏览容器内目录、查看磁盘占用：

图 4：图形化浏览文件系统，查看磁盘使用情况

默认管理的是  容器内  文件系统。若需访问宿主机目录，可在  docker-compose.yml  增加卷挂载，例如  - /www/wwwroot:/data。

侧边栏  Files  面板支持浏览器与容器之间  上传 / 下载  文件。

7.2 终端

底部坞站或菜单打开  终端模拟器，可跑  apt、docker（若挂载 socket）、脚本等：

图 5：容器内终端——uname -a  显示 Ubuntu x86_64

容器内终端默认用户为  abc，且  可无密码 sudo——这是 Webtop 的设计，方便装软件；也意味着有 GUI 访问权的人等同容器内 root，务必做好认证与网络隔离。

7.3 应用程序菜单

左上角  所有应用程序  可打开设置、终端、文件管理器等：

图 6：完整应用程序菜单，含显示、键盘、外观等设置

7.4 内置浏览器

桌面自带  Firefox / Chromium，可直接在远程桌面里上网、查文档：

图 7：容器内浏览器访问 xuanyuan.cloud——拉镜像、查文档不用切回本机

7.5 应用程序查找器

应用程序查找器  列出预装软件：Chromium、Foot 终端、Mousepad 文本编辑器等：

图 8：预装 Chromium、终端、文本编辑器等常用工具

安装更多软件（容器内终端）：

# 临时安装（容器重建后丢失）sudo apt update && sudo apt install -y git

# 持久化安装（推荐）proot-apps install filezilla

八、环境变量与卷速查

九、安全提醒

官方文档强调：

• 默认无认证——未设 PASSWORD 时任何人可访问桌面。
• 桌面内 终端可无密码 sudo，能装软件、探测内网。
• 不要裸奔公网；内网也建议强密码 + 防火墙限制 IP。
• 完整音视频等功能依赖 HTTPS。
• 公网暴露请用 Nginx / SWAG 反代 + 正式证书 + 更强认证。

十、常见问题与踩坑 FAQ

Q1：3000  端口被占用，启动报错  address already in use？

首次启动若映射  3000:3000，可能报错：

failed to bind host port 0.0.0.0:3000/tcp: address already in use

原因：宿主机 3000 已被其他服务占用（本文实测为 Redmine）。

处理 ：只改   左侧宿主机端口，容器内仍用 3000 / 3001：

ports:
  - "13000:3000"
  - "13001:3001"

排查占用：

ss -tlnp | grep :3000

Q2：页面提示  ensure you have a cpu with AVX2 support，黑屏无法进入桌面？

若使用  ubuntu-kde  且 CPU 无 AVX2，浏览器访问可能出现：

图 2：ubuntu-kde  在无 AVX2 CPU 上可能直接报错（Wayland Only）

原因：ubuntu-kde  标注为  Wayland Only，Wayland 栈在 x86_64 上需要  AVX2（约 Intel 四代 Haswell 及以后）。

解决方案（推荐）：

1. 镜像改为 ubuntu-xfce（支持 X11 自动回退）
2. 环境变量加 PIXELFLUX_WAYLAND=false
3. 重建容器：

cd /www/wwwroot/webtop
docker compose pull
docker compose down
docker compose up -d

换镜像后若界面异常，可清空配置重来（会丢失桌面内自定义）：

docker compose down
rm -rf /www/wwwroot/webtop/config/*
docker compose up -d

Q3：画面卡顿怎么办？

老 CPU 走 X11 + CPU 编码属正常。可尝试：侧边栏降低帧率；加  SELKIES_ENCODER=x264enc,x264enc-striped,jpeg；缩小浏览器窗口降低分辨率。

Q4：日志里  PolicyKit1 failed  有影响吗？

容器内常见，一般不影响 桌面、文件管理器和终端使用。

Q5：如何访问宿主机文件？

在  volumes  增加挂载，例如  - /www/wwwroot:/data，重启后在文件管理器打开  /data。

Q6：如何升级 Webtop？

cd /www/wwwroot/webtop
docker compose pull
docker compose down
docker compose up -d

/config  卷数据保留。

Q7：如何停止与卸载？

cd /www/wwwroot/webtop
docker compose down

# 删除全部数据（慎用）docker compose down
rm -rf /www/wwwroot/webtop

Q8：与 Docker Hub 官方镜像的关系？

功能相同。docker.xuanyuan.run/linuxserver/webtop:ubuntu-xfce  为轩辕镜像加速的同步版，便于国内拉取。

十一、命令速查

十二、延伸阅读

总结 ：Webtop =  不给宿主机装桌面，浏览器里就是 Linux 图形环境 。docker compose up -d → https:// 服务器 IP:13001  登录 → 文件管理、终端、内置浏览器一应俱全。踩坑记住两点：3000 改映射、 老 CPU 用 ubuntu-xfce + PIXELFLUX_WAYLAND=false。按需启停，用完  docker compose down  释放内存，生产服务器照样保持纯命令行。