x11docker 版本演进全览:从 3.0 到 7.8 的核心功能变迁、弃用清单与升级指南
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/pulsesocket,并支持=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.0default预设文件——放在~/.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 为基准)的实践建议:
- 先看 diff 再升级:
x11docker --update-master=diff预览代码差异,--update升级到最新 release;7.6.0 迁移期间需要两次--update加一次--remove-oldprefix。 - 同步调整命令行习惯:检查脚本/别名中是否还在用
--backend=nerdctl、--runtime=kata-runtime、--build、--gpu=virgl、--kwin、--iglx、--showenv等已弃用选项;--clipboard=oneway改c2h/h2c,superv/altv改cmv。 - 善用默认预设:把
--backend=podman等长期选项写入~/.config/x11docker/preset/default,相当于 x11docker 的全局配置文件。 - 注意安全语义变化:默认
--network=none、默认--cap-drop=ALL与no-new-privileges意味着"最小可用";确实需要能力时按 Troubleshooting 的"逐步加权限再逐步回收"流程收敛到最少选项。 - 新特性优先组合: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 稳定性的长期承诺书。