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

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

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

---

## 一、Webtop 是什么？

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

| 能力 | 说明 |
|------|------|
| 浏览器访问 | 打开 `https://服务器IP:端口` 即可操作完整桌面，无需 VNC 客户端 |
| 多种桌面 | 支持 XFCE、KDE、MATE、i3 等 |
| 宿主机无桌面 | 桌面跑在 **容器内**，宿主机保持纯 CLI |
| 文件与剪贴板 | 侧边栏支持上传/下载、剪贴板同步、分辨率调节 |
| 持久化 | `/config` 卷保存用户配置与桌面文件 |

典型场景：云服务器临时跑带 GUI 的安装向导；内网运维图形化浏览日志；开发测试隔离桌面软件；老机器按需 `docker compose up` 即用即关。

> **与 VNC 的区别**：Webtop **零客户端**，有浏览器就行；适合按需启动，不建议 7×24 常驻。

![浏览器中的 XFCE 桌面：部署成功后，宿主机无需安装图形界面](https://developer.qcloudimg.com/http-save/yehe-2813964/4d11b32751b7cb424c7e119c63490336.png)


*图 1：浏览器里就是完整 Linux 桌面*

---

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

| 方式 | 优点 | 缺点 |
|------|------|------|
| 宿主机装 GNOME/KDE | 原生性能最好 | 占内存 1～2 GB+、和 Web 服务抢资源 |
| SSH + 命令行 | 轻量、稳定 | 无法操作 GUI 工具 |
| **Docker Webtop** | 宿主机仍 headless；按需启停；与业务容器隔离 | 画面经编码推流，老 CPU 可能略卡 |

本文实测：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 |
| 端口 | **13000**（HTTP）、**13001**（HTTPS，推荐） |

验证 Docker：

```bash
docker --version
docker compose version
```

若尚未安装 Docker，可使用一键脚本：

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

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

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

---

## 四、拉取镜像并 Compose 部署

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

### 4.1 创建目录

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

### 4.2 拉取镜像

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

| 官方镜像 | 轩辕镜像加速拉取 |
|----------|------------------|
| `linuxserver/webtop:ubuntu-xfce` | `docker pull docker.xuanyuan.run/linuxserver/webtop:ubuntu-xfce` |

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

### 4.3 编写 docker-compose.yml

```yaml
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` 查看 |
| `CUSTOM_USER` / `PASSWORD` | **HTTP 基本认证**，务必设置 |
| `LC_ALL=zh_CN.UTF-8` | 中文界面 |
| `shm_size: 1gb` | **必设**，否则容器内浏览器易崩溃 |
| `13000:3000` / `13001:3001` | 避开宿主机 3000 被占用（见 FAQ） |
| `PIXELFLUX_WAYLAND=false` | 老 CPU 强制 X11，与 `ubuntu-xfce` 搭配更稳 |

### 4.4 启动服务

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

成功时日志关键行（**Ubuntu 24.04 实测**）：

```text
[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` 在容器内常见，**不影响桌面功能**。

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

---

## 五、浏览器访问与登录

### 5.1 访问地址

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

本文实测地址（将 IP 换成你的服务器）：

```
https://192.168.1.18:13001/
```

### 5.2 HTTP 基本认证

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

![HTTPS 登录框：设置 CUSTOM_USER 与 PASSWORD 后的浏览器登录界面](https://developer.qcloudimg.com/http-save/yehe-2813964/0db3ff02525ba3d17ff846251892e692.png)


*图 2：HTTPS 登录界面*

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

> **安全提示**：未设 `PASSWORD` 时默认 **无认证**，任何人可访问桌面。桌面内终端 **可无密码 sudo**，务必设置强密码并限制访问 IP，**不要裸奔公网**。

---

## 六、桌面使用指南

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

### 6.1 文件管理

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

![文件管理器与磁盘属性：图形化浏览文件系统](https://developer.qcloudimg.com/http-save/yehe-2813964/eecfad3d5c5bcce453c3340acbcca9b0.png)


*图 3：文件管理器与磁盘使用情况*

> 默认管理 **容器内** 文件系统。访问宿主机目录可在 compose 增加 `- /www/wwwroot:/data`。侧边栏 **Files** 面板支持浏览器与容器间 **上传 / 下载**。

### 6.2 终端

底部坞站或菜单打开 **终端模拟器**：

![终端执行 uname -a：容器内 Ubuntu x86_64](https://developer.qcloudimg.com/http-save/yehe-2813964/0d58fde1fb1b0628e34f30b298c69a06.png)


*图 4：容器内终端——`uname -a` 显示 Ubuntu x86_64*

容器内默认用户 **abc**，可无密码 `sudo` 装软件——有 GUI 访问权的人等同容器内 root，**务必做好认证与网络隔离**。

### 6.3 应用程序菜单

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

![应用程序菜单与设置子菜单](https://developer.qcloudimg.com/http-save/yehe-2813964/902f4051b38cf42f4160ca9d2741f296.png)


*图 5：完整应用程序菜单*

### 6.4 内置浏览器

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

![桌面内浏览器访问轩辕镜像 xuanyuan.cloud](https://developer.qcloudimg.com/http-save/yehe-2813964/75fc5d57c56f57558e58e66bfb4a37a2.png)


*图 6：容器内浏览器访问 xuanyuan.cloud*

### 6.5 应用程序查找器

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

![应用程序查找器：Chromium、终端、文本编辑器](https://developer.qcloudimg.com/http-save/yehe-2813964/ac2339cca7019860cb8976c702b5ca45.png)


*图 7：预装常用工具*

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

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

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

---

## 七、常见问题与踩坑 FAQ

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

首次映射 `3000:3000` 可能报错：

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

**原因**：宿主机 3000 已被 Redmine 等服务占用。

**处理**：只改左侧宿主机端口：

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

排查：`ss -tlnp | grep :3000`

**Q2：页面提示 `ensure you have a cpu with AVX2 support`，黑屏？**

若使用 `ubuntu-kde` 且 CPU 无 AVX2，可能出现：

![AVX2 不支持报错：ubuntu-kde 在无 AVX2 CPU 上黑屏](https://developer.qcloudimg.com/http-save/yehe-2813964/e6377d8fe5e4b6196701f8acf4d4eb1b.png)


*图 8：`ubuntu-kde` 在无 AVX2 CPU 上报错（Wayland Only）*

**原因**：`ubuntu-kde` 为 **Wayland Only**，需要 **AVX2**（约 Intel 四代 Haswell 及以后）。

**解决**：

1. 镜像改为 **`ubuntu-xfce`**
2. 加 **`PIXELFLUX_WAYLAND=false`**
3. 重建：

```bash
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 | 可用 |

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

```bash
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：如何升级 / 停止？**

```bash
# 升级
cd /www/wwwroot/webtop
docker compose pull && docker compose down && docker compose up -d

# 停止（保留 config）
docker compose down

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

**Q7：与 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 \|\| echo 请用 ubuntu-xfce` |
| 查端口占用 | `ss -tlnp \| grep :3000` |
| 停止服务 | `cd /www/wwwroot/webtop && docker compose down` |

---

## 总结

Webtop = **不给宿主机装桌面，浏览器里就是 Linux 图形环境**：

- 使用轩辕镜像加速拉取 `linuxserver/webtop:ubuntu-xfce`
- `docker compose up -d` → `https://服务器IP:13001` 登录
- 文件管理、终端、内置浏览器一应俱全
- 踩坑记住：**3000 改映射**、**老 CPU 用 ubuntu-xfce + PIXELFLUX_WAYLAND=false**
- 按需启停，用完 `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
```

linuxserver/webtop 轩辕镜像页：

```
https://xuanyuan.cloud/zh/r/linuxserver/webtop
```

轩辕镜像首页：

```
https://xuanyuan.cloud
```

如果你在拉取 Docker 镜像时遇到速度慢、超时等问题，可以试试轩辕镜像的加速服务。欢迎收藏 linuxserver/webtop 镜像页，获取最新标签与更新说明：

```
https://xuanyuan.cloud/zh/r/linuxserver/webtop
```

---

**环境变量速查、安全提醒、GPU 加速与更多 FAQ，详细步骤请查看：**

```
https://xuanyuan.cloud/blog/linux-docker-webtop
```
---

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

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

Linux 服务器没桌面？Docker 跑个 Webtop，浏览器里就是图形桌面

云服务器、VPS、家用 NAS 大多是 纯命令行 Linux——没有显示器、没有桌面环境，装软件、管文件、跑带 GUI 的工具只能靠 SSH。给宿主机装一套 GNOME / KDE？又占内存又难维护，还可能和现有服务抢资源。Webtop 是 LinuxServer.io 出品的 浏览器远程桌面：Docker 起一个容器，里面跑完整 Linux 桌面（XFCE / KDE 等）。

运维

编程语言

Webtop是一款基于Docker的浏览器远程桌面工具，无需在宿主机安装桌面环境即可通过浏览器访问完整Linux图形界面。支持XFCE、KDE等多种桌面，适合云服务器临时GUI操作、内网运维等场景。本文提供详细部署教程，包括镜像加速拉取、docker-compose配置、HTTPS登录及常见问题解决，帮助用户快速搭建轻量级远程桌面环境。

代码解释

云服务器

文件系统

服务器

GitHub

容器

Docker

GNOME

Linux

MySQL

Nginx

XFCE

2026上云采购 | AI焕新·智启新局

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Webtop是一款基于Docker的浏览器远程桌面工具，无需在宿主机安装桌面环境即可通过浏览器访问完整Linux图形界面。支持XFCE、KDE等多种桌面，适合云服务器临时GUI操作、内网运维等场景。本文提供详细部署教程，包括镜像加速拉取、docker-compose配置、HTTPS登录及常见问题解决，帮助用户快速搭建轻...

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

Linux 服务器没桌面？Docker 跑个 Webtop，浏览器里就是图形桌面

Linux 服务器没桌面？Docker 跑个 Webtop，浏览器里就是图形桌面

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐