x11docker 版本演进全览:从 3.0 到 7.8 的核心功能变迁、弃用清单与升级指南

原创2026-10-14 16:35:491,666 阅读
文章标签:开发工具

x11docker 版本演进全览:从 3.0 到 7.8 的核心功能变迁、弃用清单与升级指南

导读

本文以 x11docker 项目的 CHANGELOG.md(2017 年 v3.0 至 2026 年 v7.8.0 的全部版本记录)为骨架,系统梳理这个"在 Docker/podman 容器中运行 GUI 应用与桌面、聚焦安全"的 bash 脚本项目二十多个版本的功能演进主线:X/Wayland 显示服务器的选择、安全加固策略、容器后端与运行时支持、剪贴板/GPU/声音等外设集成的演进,以及大量选项的改名、弃用与移除。读完本文,你将掌握 x11docker 各版本之间的迁移路径、当前 7.8.0 的新特性(--xw、--pipewire、--clipboard 新参数、--satellite 转正等),并能从源码层面理解 CHANGELOG 在 --update 升级流程中的工程角色。

一、变更日志规范:Keep a Changelog 与语义化版本

CHANGELOG.md 的开头明确了两条项目约定:

  • 变更记录格式遵循 Keep a Changelog 规范("All notable changes to this project will be documented in this file");
  • 自 v4.0.0(2018-04-07) 起,项目严格遵循 Semantic Versioning(语义化版本控制) 规则。

v4.0.0 本身就是一次元层面的变更:[#38] 将变更日志从 x11docker 源码中独立出来,形成独立的 CHANGELOG.md,此前版本链接指向历史源码树,此后版本链接指向对应的 release。这意味着从 4.0 开始,CHANGELOG 既是升级指南,也是用户判断"哪些选项被改名、哪些行为被破坏"的权威依据——这一点对后文所有 API 变更的追溯都至关重要。

二、近况速览:Unreleased 与 7.8.0(2026-01-17)

2.1 v7.8.0:Wayland 与 X 并行、PipeWire 声音、剪贴板重做

7.8.0 是当前最新稳定版本,值得逐项细读。

新增选项(Added):

选项 作用
--xw 让 X 与 Wayland 应用并排运行(side by side)。主脚本解析处 Xwogether="yes"(x11docker)即为此选项的开关变量
--pipewire 在容器内提供 PipeWire 声音。关联 issue #545/#527/#507/#418/#380,是此前 --pulseaudio/--alsa 之外的第三条声音通道(见 x11docker 的 Sharepipewire="yes")
--xeyes 在新 X server 上运行 xeyes,可作为 --clipboard=cmv 在 Wayland+X11 容器(--xw)中的辅助工具(Xeyes="${2:-"+shape"}",见 x11docker)
Docker Desktop 部分支持 VM 版 Docker Desktop 获得实验性支持

行为变更(Changed):

  • --weston-xwayland:支持 rootless Xwayland,并新增对 --wayland 选项的配合;
  • --weston=<a href="https://link.gitcode.com/i/0f54f534583e33aa9b43aada8394f447" target="_blank">ARG]:新增可选参数,--weston=x 等价于 --weston-xwayland --wayland,--weston=X 等价于 --weston-xwayland --wayland --desktop(issue #501)。man page 中同样记录了这两个快捷记法(见 [x11docker.man);
  • --hostwayland:现在可以与其他 X server 选项叠加使用,实现 X 与 Wayland 应用并排;
  • --hostdisplay:即使不带 --xc 也使用 x11docker/xserver 镜像中的 XlibNoSHM.so,从而避免对 --ipc=host 的依赖;
  • --clipboard:全面重做——支持 Wayland;移除 primary 参数;弃用 oneway,改为 c2h(容器→宿主单向)、h2c(宿主→容器单向);弃用 superv|altv,改为 cmv(按下 <a href="https://link.gitcode.com/i/2bb3096e254660549be7b5292b343614" target="_blank">CTRL]+[SUPER]+[v] 时才把宿主剪贴板内容提供给容器,其余行为同 yes)。man page 对 c2h/h2c/cmv 均有明确释义(见 [x11docker.man)。

弃用(Deprecated):

  • --backend=nerdctl:推断使用稀少;
  • --runtime=kata-runtime:推断使用稀少(issue #543);
  • --build:需要 ADD 支持才能正常工作;
  • --gpu=virgl 参数:被弃用。

修复(Fixed) 中值得注意的工程细节:

  • /etc/profile.d/10-x11docker-env.sh 不再设置 DISPLAY,而是在 ssh 会话中设置 XAUTHORITY=~/.Xauthority(issue #554);
  • --xc --backend=host 修复了 rootful/rootless 后端判定;
  • WSL2g 在已设置 DISPLAY 时不再默认 --runx,并改用 socat 从虚拟 socket 创建 unix socket(issue #557)。

2.2 Unreleased:下一版本的预告

尚未发布的变更已经写入日志:

  • Fixed:--westonini 为自定义 weston 配置补充 Xwayland wrapper;用 ip -4 检查取代 hostname -I(issue #560);--xoverip *xwayland 改用 -listen tcp 而非 socat;--xc 在挂载前检查文件/设备是否已存在(issue #564);
  • Changed:--satellite 因 xwayland-satellite v0.8.1 已支持若干 X 选项而脱离实验状态;
  • Added:--xlogo,与 --xeyes 一样作为 --clipboard=cmv 的辅助工具(Xlogo="yes",见 x11docker)。

三、7.6/7.7:安装前缀迁移与日常维护

3.1 v7.6.0:/usr → /usr/local 前缀迁移

v7.6.0(2023-01-18)之前,x11docker 通过 --install|--update|--update-master 将自身安装到 /usr 前缀下;7.6.0 起改随 Linux Foundation FHS 规范安装到 /usr/local。由于旧安装与新安装并存,升级必须执行两次:

# 第一次运行:安装新版本
x11docker --update
# 第二次运行:安装生效(两次更新才能完成迁移)
x11docker --update
# 之后清理旧前缀安装
x11docker --remove-oldprefix

--remove-oldprefix(关联 issue #479)专门用于删除 /usr 下的旧安装文件。升级提示明确给出了这一三步走流程。

3.2 v7.5.0 与 v7.4.x:日常维护能力补全

  • v7.5.0:新增 man page(issue #469),--update 从 7.4.2 运行两次即可安装;修复 --tty 与 --xc 组合失败问题(--tty 时禁用 --xc,issue #464);引入 jq 支持以降低对 python 的依赖(issue #478);--xonly 以非特权方式运行 socat 使 unix socket 可访问(issue #466);--share 修复 HOME 内文件夹的软链接(issue #475)。
  • v7.4.1:--update、--update-master 新增可选参数 diff,可在不安装的情况下预览当前版本与新版本的代码差异(issue #460):
    x11docker --update-master=diff
    
  • v7.4.0:新增 --xauth [=yes|trusted|untrusted|no] 配置 X cookie,新增 --printcheck 显示 X server 依赖检查信息;--xoverip 新增 yes|no|socat|listentcp 参数,其中 socat 允许在 --hostdisplay 与 Xwayland 相关选项下走 TCP;同时弃用 --no-auth(改用 --xauth=no)。
  • v7.7.x(2025-11):集中修复 --xc(X 容器)场景——--xc --xorg 补充挂载 /dev/tty0 /dev/fb0(Debian trixie 控制台)、--xc --weston* 改用 --ipc=host、--xc=docker --backend=podman 修复 capabilities/DAC_OVERRIDE、NVIDIA 驱动重复安装检查;--password 修复 ~/.config/x11docker 目录不存在时的 mkdir 问题(issue #535/#537),并在提示中显示宿主用户名;--pulseaudio 改为共享 cookie 文件(issue #507);--xopt=ARG 新增自定义 X server 命令行参数;ssh 场景新增 /x11docker/sshenv 环境设置辅助脚本(issue #554)。同时弃用 --kwin,建议改用 --weston。

四、核心功能演进主线:从 3.0 到 7.8

4.1 X server 与 Wayland:从零到容器化 X server

  • v3.0.0(2017-04-15):首次加入 Wayland 支持,新增 --wayland(自动搭建纯 Wayland 环境)、--weston、--kwin、--xwayland、--weston-xwayland、--kwin-xwayland、--xpra-xwayland、--nothing(不提供任何显示服务器,后演化为 --tty)等一批选项。
  • v3.1.x:加入 --nxagent(嵌套 X server,支持 seamless 模式);后续补充 --size、--fullscreen、--clipboard 配合,并支持 untrusted cookies 与键盘布局。
  • v6.0.0(2019-07-08):--wm 改用镜像 x11docker/openbox 提供窗口管理器,支持 --wm=host、--wm=COMMAND、--wm=IMAGE 三种形态;--vcxsrv 被移除(MS Windows 改用 runx 提供 X)。
  • v7.0.0(2022-01-20):引入 --xc——在 x11docker/xserver 镜像的容器中运行 X server,除控制台场景(尤其 --xorg)外的大多数 X server 与 Wayland 选项均受支持;同时引入 --xpra2(xpra server 在容器内、客户端在宿主)与 --xpra2-xwayland。这是"宿主无需安装 X 依赖"的关键一步,与 README 中"推荐拉取 x11docker/xserver 镜像"的依赖策略一致。
  • v7.2.0:--xc 支持容器内 Weston(含控制台)与容器内 Xorg(issue #7/#40/#221/#258/#444)。
  • v7.8.0:--xw 让 X 与 Wayland 应用并排运行;--satellite(rootless Xwayland,运行 xwayland-satellite,需已有 Wayland compositor,见 x11docker.man)成熟。

4.2 安全加固:能力裁剪与防 X 泄漏的持续演进

安全是 x11docker 的项目焦点(README 副标题即 "Focus on security"),这一点在 CHANGELOG 中有清晰的时间线:

  • v3.5.0(2017-05-17):docker run --cap-drop=ALL 成为默认,容器能力压到最小;容器用户默认与宿主用户相同,避免容器内 root;新增 --user(支持 UID:GID)、--cap-default(放开默认能力)。
  • v3.5.3:为 docker run 增加 --security-opt=no-new-privileges。
  • v3.9.8.1:no-new-privileges 成为除 --sudouser 外的全局默认;用户切换使用 exec su 避免 root shell 残留父进程树。
  • v4.3.0:对 init 系统与 --dbus-system 也默认 no-new-privileges;删除/最小化 /etc/pam.d/su 与 /etc/pam.d/sudo,封堵容器内提权路径。
  • v7.0.0:--network=none 成为默认(此前 v6.7.0 引入 -I, --network 并预告"未来必须显式开启才有网络");--user=root 需要 --sudouser 或 --cap-default 才能获得常规 root 权限。
  • v7.4.0:--xauth 统一了 X cookie 策略;v7.8.0 修复 SECURITY 扩展缺失时的 cookie 问题(issue #557)。

与安全相关的另一条线是 --hostdisplay 的警告体系:CHANGELOG 多次强化对共享宿主 :0 显示器的风险提示(v5.3.x 修复 ssh -X 下的 XAUTHORITY、v6.x 要求 --clipboard 时启用 trusted cookie 并警告等),并始终把"跑第二个 X server"作为默认方案。

4.3 容器后端与运行时:docker → podman → host

  • v6.9.0(2021-06-02):引入 --backend=BACKEND(实验性),支持 docker、podman、nerdctl;同时支持 rootless docker(issue #327)。
  • v7.1.0:--backend=proot(用 proot 在宿主跑 rootfs,issue #224)、--backend=host(直接以宿主应用运行,取代 -e, --exe)。
  • v7.2.0:新增 --rootless [=yes|no] 显式控制 rootless 后端。
  • v7.6.0 之后的现状(与 README 一致):受支持参数收敛为 docker、podman、host;rootful 推荐 docker/podman,rootless 推荐 podman(只有 podman 支持 rootless 下的 --home 与合理的 --share 文件属主);--backend=proot、--backend=nerdctl 先后被弃用。

运行时(runtime):v5.6.0 引入 --runtime=RUNTIME(已知 runc、crun、nvidia、kata-runtime);v7.0.0 实验性支持 sysbox-runc(需 sysbox≥0.5.0、内核≥5.12);v7.4.2 起 kata-runtime 因 kata v2.x 不再提供该命令而弃用,v7.8.0 最终移除。

4.4 剪贴板:从双向到可控单向、再到 Wayland

  • v5.x 起 --clipboard 与 --trusted 语义纠缠(--trusted 被弃用,改用 --clipboard);
  • v7.3.0 引入 oneway、altv、superv 参数(issue #440/#379/#152),限制容器对宿主剪贴板的访问方向;
  • v7.8.0 重做为 c2h、h2c、cmv,并支持 Wayland 剪贴板(宿主 X → 容器 Wayland 的单向支持则早在 v7.3.2 就已加入);cmv 配合 --xeyes/--xlogo 与 --xc 的按键绑定工具使用。

4.5 GPU 加速:virgl、iglx、NVIDIA 驱动自动安装

  • v4.2.0 起 --gpu 支持容器内 NVIDIA 驱动自动安装(glibc 镜像);
  • v5.4.x 持续打磨 NVIDIA 驱动安装参数(--install-libglvnd、--no-nvidia-modprobe 等);
  • v6.8.0 加入 --iglx(间接渲染,后改名 --gpu=iglx,仅 --xorg);
  • v7.1.1 加入 --gpu=virgl(经 virgl_test_server,实验性,仅配合 --xc,可为 Xephyr/nxagent/Xvfb 等提供加速);
  • v7.0.0 设置 prime-run 环境变量(issue #394),并确认 NVIDIA Wayland/Xwayland 支持需驱动≥470.x、Xwayland≥21.1.2;
  • v7.2.0 支持 VA-API、VDPAU 视频加速与 DRI_PRIME(issue #443);
  • v7.4.0 起 --gpu 调整了 X 依赖检查;v7.8.0 弃用 --gpu=virgl 参数。

4.6 声音:ALSA → PulseAudio → PipeWire

  • v3.7.0:--alsa(支持 --alsa=CARDNAME 指定声卡);
  • v3.9.7.3/v5.0.0:--pulseaudio 由 TCP 改为共享 XDG_RUNTIME_DIR/pulse socket,并支持 =tcp/=socket/=host 参数(Linux 上 socket 与 tcp 均可,MS Windows 仅 tcp);
  • v6.6.x:--pulseaudio 在系统级 pulseaudio 时自动切到 TCP;
  • v7.8.0:新增 --pipewire,要求宿主与镜像都装 pipewire(另需 pipewire-pulse 与/或 pipewire-alsa;若宿主有 pipewire+pipewire-pulse 而镜像只有 pulseaudio 客户端库,--pulseaudio=tcp 也可用)。

4.7 Init 系统与 DBus

  • v3.8.0:--init(tini/docker-init,成为默认)、--no-init、--systemd、--runit;
  • v3.9.x:--openrc、--sysvinit、--dbusdaemon(后改名 --dbus-system)、--sharecgroup;
  • v5.5.0:统一为 --init=tini|systemd|sysvinit|openrc|runit|none|s6-overlay,替代一系列单数选项;
  • v6.8.0:--password 设置容器用户密码;--sudouser 支持 nopasswd 参数;
  • v7.x:持续修复 cgroupv2、elogind、arch 容器等(v7.1.0 issue #349、v6.5.0 issue #417);
  • DBus 三通道齐全:--dbus(用户会话)、--dbus=system(系统守护进程,实验性,不推荐)、--hostdbus(连宿主会话);README 还提供 --share /run/dbus/system_bus_socket 直接共享宿主系统 socket 的路线。

4.8 其他高频实用功能的时间线

  • 语言/键盘:v3.9.5 --keymap、v3.9.6 --lang(缺 locale 时用 localedef 生成,支持 --lang=zh_CN 等);v5.5.1 起 --lang 参数变为可选;
  • 文件共享:v3.5.2 --volume → v3.5.3 改名 --sharedir → v5.6.0 改名 --share(支持 :ro、卷、/dev 设备文件);--home 自 v5.x 起支持 --home=DIR、--home=VOLUME;
  • 资源限制:v5.4.0 --limit[=FACTOR](默认限制 50% CPU 与 50% 当前空闲内存);
  • 预配置:v6.6.0 --preset、v7.0.0 default 预设文件——放在 ~/.config/x11docker/preset 或 /etc/x11docker/preset 下,可让 x11docker --preset=multimedia 这类组合命令成为日常习惯;
  • 窗口生命周期:v7.3.0 --checkwindow [=ARG](X 窗口全部关闭即退出容器,或按 xwininfo 关键词停止);
  • 远程与 Windows:v5.0.0 支持 MSYS2/Cygwin/WSL,v6.6.0 实验性支持 WSL2 与 --mobyvm,v7.8.0 实验性支持 Docker Desktop。

五、API 变更与迁移清单

5.1 v5.0.0 的命令行语法变更

v5.0.0(2018-08-20)做了破坏性 API 变更,自定义 DOCKER_RUN_OPTIONS 的写法从引号包裹改为双 -- 分隔:

# 新语法(推荐):
x11docker [OPTIONS] --  DOCKER_RUN_OPTIONS -- IMAGE [COMMAND [ARG1 ARG2 ...]]
# 旧语法(已弃用,仍有效):
x11docker [OPTIONS] -- "DOCKER_RUN_OPTIONS"   IMAGE [COMMAND [ARG1 ARG2 ...]]
# 会被误解析而失效的写法:
x11docker [OPTIONS] -- "DOCKER_RUN_OPTIONS"   IMAGE COMMAND ARG1 -- ARG2

5.2 选项改名总表

弃用/移除的选项 替代方案 引入/移除版本
--volume --sharedir → --share 3.5.2 → 3.5.3 → 5.6.0
--homedir=DIR --home=DIR 6.1.0
--cachedir --cachebasedir 5.0.0
--showenv / --showid / --showinfofile / --showpid1 --printenv / --printid / --printinfofile / --printpid1 7.0.0
--hostipc --ipc [=ARG] 7.1.0
--exe --backend=host 7.1.0
--podman --backend=podman 6.9.0
--no-internet / --hostnet --network=none / --network=host 6.7.0
--tini / --systemd / --openrc / --runit / --sysvinit / --no-init `--init=tini systemd
--starter --launcher 5.3.0
--silent / --nothing --quiet / --tty 5.3.3
--trusted / --untrusted --clipboard / 无 5.3.0
--no-auth --xauth=no 7.4.0
--iglx --gpu=iglx 7.1.1
--kwin --weston 7.7.0
--backend=proot 无(推断无人使用) 7.5.0
--backend=nerdctl 无(推断使用稀少) 7.8.0
--runtime=kata-runtime 无(kata v2.x 移除命令) 7.4.2 → 7.8.0
--build 本地 Dockerfile 构建 7.8.0
x11docker-gui、--vcxsrv、--pull、--pw、--xdummy 等 见各自替代项 6.0.0/7.0.0

v6.0.0 的大规模清理值得单独提示:--ps、--trusted、--untrusted、--no-xtest、--no-xhost、--silent、--stderr、--stdout、--nothing、--cachedir、--starter、--tini、--systemd、--openrc、--runit、--sysvinit、--no-init、--sys-admin 等一批选项被移除,需在 changelog 各 'Deprecated' 章节中查找替代项。

5.3 行为语义变化速记

  • --network=none 自 7.0.0 起成为默认,需要联网请显式加 -I, --network;
  • 短选项自 6.2.0 起不再接受可选参数(影响 -l -m -p -P -w -v);-m、-w、-v、-g、--lang、--wm 等带可选参数的长选项,= 是强制的(如 --lang=ru、--wm=openbox、--gpu=virgl);
  • --user=root 自 7.0.0 起不再拥有常规 root 能力,需配合 --sudouser 或 --cap-default;
  • --hostdisplay 配合 --gpu/--clipboard 时会自动启用 --ipc=host 与 trusted cookie(README 明确:此组合无任何 X 泄漏防护,是"不关心隔离但极快"的不安全方案);
  • 升级安装前缀:7.6.0 前为 /usr,之后为 /usr/local,升级需连跑两次 --update 再加 --remove-oldprefix。

六、版本节奏与关键里程碑时间线

版本 日期 里程碑意义
v3.0.0 2017-04-15 引入 Wayland 支持(weston/kwin/xwayland/xpra-xwayland 等)
v3.5.0 2017-05-17 --cap-drop=ALL 默认、--user、--cap-default
v3.8.0 2017-12-04 --init/--systemd/--runit,tini 成为默认 PID 1
v4.0.0 2018-04-07 CHANGELOG 独立、遵循 Keep a Changelog 与 SemVer
v5.0.0 2018-08-20 MS Windows(MSYS2/Cygwin/WSL)支持、-- API 变更
v5.5.0 2019-03-06 --init= 统一选项
v6.0.0 2019-07-08 --wm 镜像化、大规模移除旧选项
v6.3.0 2019-10-04 返回容器命令退出码(x11docker 自身错误码 64)
v6.6.0 2020-03-19 实验性 WSL2、--preset、--mobyvm
v6.9.0 2021-06-02 `--backend=docker
v7.0.0 2022-01-20 --xc 容器化 X server、--network=none 默认
v7.2.0 2022-06-21 --rootless、容器内 Weston/Xorg
v7.4.0 2022-07-28 --xauth、--xoverip 新参数
v7.6.0 2023-01-18 安装前缀迁移 /usr/local
v7.7.x 2025-11 --xopt、ssh 环境脚本、--kwin 弃用
v7.8.0 2026-01-17 --xw、--pipewire、--clipboard 重做、--satellite 成熟

七、从源码看 CHANGELOG 的工程角色

CHANGELOG.md 不只是文档,它在 x11docker 主脚本的升级与安装流程中承担着实际功能:

  • 升级下载与版本提取:--update 会先下载最新的 CHANGELOG.md,再从其中解析最新版本号作为本次升级目标(grep "## \<a href="https://link.gitcode.com/i/633efbcab159388d1a68b2360c266d7f" target="_blank">" ... head -n1 | cut -d[ -f2 | cut -d] -f1,见 [x11docker);
  • 变更摘要展示:--update/--update-master(以及 v7.4.1 的 diff 参数)通过 sed 截取两个版本标题之间的段落,向用户展示本次升级的变更摘要(x11docker);
  • 随包分发:安装时 CHANGELOG.md 与 README.md、LICENSE.txt 一并复制到 /usr/local/share/doc/x11docker/(x11docker);
  • 排错指引:--help 的排错提示会让用户"在 /usr/share/doc/x11docker/CHANGELOG.md 中搜索"对应选项或关键词(x11docker)。

也就是说,用户在升级前后查到的"这个选项为什么没了/改成什么了",正是从这份 CHANGELOG 中实时读取的——这也是本文建议读者把 CHANGELOG.md 当作迁移手册来用的原因。

八、升级与迁移建议

结合以上演进梳理,给出现阶段(以 7.8.0 为基准)的实践建议:

  1. 先看 diff 再升级:x11docker --update-master=diff 预览代码差异,--update 升级到最新 release;7.6.0 迁移期间需要两次 --update 加一次 --remove-oldprefix。
  2. 同步调整命令行习惯:检查脚本/别名中是否还在用 --backend=nerdctl、--runtime=kata-runtime、--build、--gpu=virgl、--kwin、--iglx、--showenv 等已弃用选项;--clipboard=oneway 改 c2h/h2c,superv/altv 改 cmv。
  3. 善用默认预设:把 --backend=podman 等长期选项写入 ~/.config/x11docker/preset/default,相当于 x11docker 的全局配置文件。
  4. 注意安全语义变化:默认 --network=none、默认 --cap-drop=ALL 与 no-new-privileges 意味着"最小可用";确实需要能力时按 Troubleshooting 的"逐步加权限再逐步回收"流程收敛到最少选项。
  5. 新特性优先组合:X 与 Wayland 并排用 --xw 或 --weston=x/--weston=X;声音优先 --pipewire;剪贴板单向控制用 --clipboard=c2h|h2c|cmv,并可用 --xeyes/--xlogo 辅助定位 Wayland 焦点问题。

从 2017 年的纯 X 容器工具到 2026 年支持 Wayland、PipeWire、容器化 X server 与 rootless podman 的 7.8.0,x11docker 的每一步演进都完整沉淀在 CHANGELOG.md 中——它既是变更记录,也是安全策略与 API 稳定性的长期承诺书。

登录后查看全文
x11docker