Linux 服务器没桌面？Docker 跑个 Webtop，浏览器里就是图形桌面 - 文章 - 开发者社区

本文基于 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。

picture.image

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

一、Webtop 是什么？

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

能力	说明
浏览器访问	打开 `https://服务器IP:端口` 即可操作完整桌面，无需 VNC 客户端
多种桌面	支持 XFCE、KDE、MATE、i3 等；基于 Alpine / Ubuntu / Debian / Arch / Fedora
宿主机无桌面	桌面跑在容器内，宿主机保持纯 CLI，不污染系统
文件与剪贴板	侧边栏支持上传/下载文件、剪贴板同步、分辨率调节
持久化	`/config` 卷保存用户配置、桌面文件、proot-apps 安装的软件

典型使用场景：

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

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

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

方式	优点	缺点
宿主机装 GNOME/KDE	原生性能最好	占内存（常 1～2 GB+）、和 Web 服务抢资源、升级可能搞崩生产环境
SSH + 命令行	轻量、稳定	无法操作 GUI 工具
Docker Webtop	宿主机仍 headless；按需启停；与 Redmine/MySQL 等容器隔离	画面经编码推流，老 CPU 可能略卡；需 HTTPS 才完整

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

三、环境要求

项目	建议
操作系统	Linux（本文 Ubuntu 24.04）
Docker	已安装 Docker 与 Docker Compose V2
内存	≥ 2 GB（推荐 4 GB；桌面容器较吃内存）
CPU	双核即可；无 AVX2 的老 CPU 请用 `ubuntu-xfce`（见第十节 FAQ）
磁盘	≥ 5 GB（镜像 + `/config` 持久化）
端口	13000（HTTP）、13001（HTTPS，推荐）

验证 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

配置项	说明
`PUID` / `PGID`	与宿主机用户一致，运行 `id` 查看；避免 `/config` 权限错乱
`CUSTOM_USER` / `PASSWORD`	HTTP 基本认证，务必设置；默认无认证极不安全
`LC_ALL=zh_CN.UTF-8`	中文界面
`shm_size: 1gb`	必设，否则容器内浏览器易崩溃
`13000:3000` / `13001:3001`	避开宿主机 3000 被 Redmine 等占用（见 FAQ）
`PIXELFLUX_WAYLAND=false`	老 CPU 强制 X11，与 `ubuntu-xfce` 搭配更稳

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 访问地址

方式	地址	说明
HTTP	`http://服务器IP:13000`	能打开，部分音视频功能受限
HTTPS（推荐）	`https://服务器IP:13001`	自签名证书，需手动信任

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

6.2 HTTP 基本认证

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

picture.image

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

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

七、桌面使用指南

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

7.1 文件管理

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

picture.image

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

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

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

7.2 终端

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

picture.image

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

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

7.3 应用程序菜单

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

picture.image

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

7.4 内置浏览器

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

picture.image

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

7.5 应用程序查找器

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

picture.image

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

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

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

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

八、环境变量与卷速查

变量	说明
`PUID` / `PGID`	文件所有者 UID/GID
`TZ`	时区，如 `Asia/Shanghai`
`LC_ALL`	语言，如 `zh_CN.UTF-8`
`CUSTOM_USER` / `PASSWORD`	HTTP 基本认证（强烈建议设置）
`PIXELFLUX_WAYLAND`	`false` 强制 X11；老 CPU 必备
`SUBFOLDER`	反代子路径，如 `/webtop/`
`SELKIES_ENCODER`	老 CPU 可设 `x264enc,x264enc-striped,jpeg` 改善编码

容器路径	说明
`/config`	持久化配置、用户主目录、桌面文件

九、安全提醒

官方文档强调：

默认无认证——未设 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，浏览器访问可能出现：

picture.image

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

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

解决方案（推荐）：

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

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

镜像标签	桌面	无 AVX2 老 CPU
`ubuntu-kde`	KDE	通常不可用
`ubuntu-xfce`	XFCE	推荐
`ubuntu-mate`	MATE	可用
`debian-kde`	KDE	可尝试

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

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 为轩辕镜像加速的同步版，便于国内拉取。

十一、命令速查

操作	命令
拉取镜像	`docker pull docker.xuanyuan.run/linuxserver/webtop:ubuntu-xfce`
启动	`cd /www/wwwroot/webtop && docker compose up -d`
查看日志	`docker compose logs -f webtop`
HTTPS 访问	`https://服务器IP:13001`
检查 AVX2	`grep -q avx2 /proc/cpuinfo && echo OK
查端口占用	`ss -tlnp \| grep :3000`
停止服务	`cd /www/wwwroot/webtop && docker compose down`

十二、延伸阅读

主题	链接
LinuxServer 官方文档	https://docs.linuxserver.io/images/docker-webtop/
GitHub 源码	https://github.com/linuxserver/docker-webtop
Docker Hub	https://hub.docker.com/r/linuxserver/webtop
轩辕镜像页	https://xuanyuan.cloud/zh/r/linuxserver/webtop
轩辕镜像	https://xuanyuan.cloud

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